subcog
starsforks
How to install subcog?
zircote/subcog
$git clone https://github.com/zircote/subcogPersistent memory system for AI coding assistants. Captures decisions, learnings, and context from coding sessions. Features hybrid search (semantic + BM25), MCP server integration, SQLite persistence with knowledge graph, and proactive memory surfacing. Written in Rust.
README.md
| 1 | # Subcog |
| 2 | |
| 3 | [](https://github.com/zircote/subcog/actions/workflows/ci.yml) |
| 4 | [](https://github.com/zircote/subcog/releases) |
| 5 | [](https://crates.io/crates/subcog) |
| 6 | [](https://www.rust-lang.org/) |
| 7 | [](LICENSE) |
| 8 | [](https://github.com/rust-lang/rust-clippy) |
| 9 | [](https://github.com/EmbarkStudios/cargo-deny) |
| 10 | |
| 11 | A persistent memory system for AI coding assistants. Subcog captures decisions, learnings, and context from coding sessions and surfaces them when relevant. |
| 12 | |
| 13 |  |
| 14 | |
| 15 | ## Overview |
| 16 | |
| 17 | Subcog delivers: |
| 18 | |
| 19 | - **Single-binary distribution** (<100MB, <10ms cold start) |
| 20 | - **Three-layer storage architecture**: SQLite persistence, FTS5 indexing, usearch HNSW vectors |
| 21 | - **MCP server integration** for AI agent interoperability |
| 22 | - **Claude Code plugin** with hooks for seamless IDE integration |
| 23 | - **Semantic search** with hybrid vector + BM25 ranking (RRF fusion) |
| 24 | - **Knowledge graph** with entity extraction and relationship inference |
| 25 | - **Faceted storage** with project, branch, and file path filtering |
| 26 | |
| 27 | ## ADR Compliance |
| 28 | |
| 29 | ADR compliance is tracked in [`docs/adrs/README.md`](docs/adrs/README.md). Current compliance is **95% (55/58 active ADRs)** with documented partials in ADR-0003 and ADR-0039. |
| 30 | |
| 31 | ## Benchmark Results |
| 32 | |
| 33 | Subcog achieves **97% accuracy on factual recall** (LongMemEval) and **57% on personal context** (LoCoMo), compared to 0% baseline without memory. See [full benchmark results](docs/BENCHMARKS.md). |
| 34 | |
| 35 | | Benchmark | With Subcog | Baseline | Improvement | |
| 36 | |-----------|-------------|----------|-------------| |
| 37 | | LongMemEval | 97% | 0% | +97% | |
| 38 | | LoCoMo | 57% | 0% | +57% | |
| 39 | | ContextBench | 24% | 0% | +24% | |
| 40 | | MemoryAgentBench | 28% | 21% | +7% | |
| 41 | |
| 42 | ## Features |
| 43 | |
| 44 | ### Core (Always Available) |
| 45 | - Memory capture with **automatic embedding generation** (384-dimensional vectors) |
| 46 | - **Real semantic search** using all-MiniLM-L6-v2 via fastembed-rs |
| 47 | - **Hybrid search** combining BM25 text search + vector similarity (RRF fusion) |
| 48 | - **Normalized scores** (0.0-1.0 range) for intuitive relevance understanding |
| 49 | - **SQLite persistence** as single source of truth (ACID-compliant) |
| 50 | - **Faceted storage** with project_id, branch, and file_path fields |
| 51 | - Multi-domain memories (project, user, organization) |
| 52 | - 10 memory namespaces (decisions, learnings, patterns, blockers, etc.) |
| 53 | - **Branch garbage collection** for tombstoning stale branch memories |
| 54 | - **Migration tools** for upgrading existing memories to use embeddings |
| 55 | |
| 56 | ### Enhanced (Opt-in) |
| 57 | - Entity and temporal extraction |
| 58 | - Secrets filtering (API keys, PII detection) |
| 59 | - OpenTelemetry observability |
| 60 | - Full Claude Code hook integration |
| 61 | |
| 62 | ### LLM-Powered (Requires Provider) |
| 63 | - Implicit capture from conversations |
| 64 | - Memory consolidation and summarization |
| 65 | - Supersession detection |
| 66 | - Temporal reasoning queries |
| 67 | |
| 68 | ## Installation |
| 69 | |
| 70 | Multiple installation methods are available. See [INSTALLATION.md](docs/INSTALLATION.md) for detailed instructions. |
| 71 | |
| 72 | ```bash |
| 73 | # Cargo (recommended - Rust developers) |
| 74 | cargo install subcog |
| 75 | |
| 76 | # Homebrew (macOS/Linux) |
| 77 | brew install zircote/tap/subcog |
| 78 | |
| 79 | # Docker |
| 80 | docker run --rm ghcr.io/zircote/subcog --help |
| 81 | |
| 82 | # Binary download |
| 83 | curl -LO https://github.com/zircote/subcog/releases/latest/download/subcog-VERSION-TARGET.tar.gz |
| 84 | |
| 85 | # npm/npx (fallback if binary install unavailable) |
| 86 | npx @zircote/subcog --help |
| 87 | ``` |
| 88 | |
| 89 | | Method | Platforms | Auto-update | |
| 90 | |--------|-----------|-------------| |
| 91 | | Cargo | All | `cargo install` | |
| 92 | | Homebrew | macOS, Linux | `brew upgrade` | |
| 93 | | Docker | linux/amd64, linux/arm64 | Pull latest tag | |
| 94 | | Binary | All | Manual | |
| 95 | | npm/npx | macOS, Linux, Windows | Via npm | |
| 96 | |
| 97 | ## Quick Start |
| 98 | |
| 99 | ```bash |
| 100 | # Capture a memory |
| 101 | subcog capture --namespace decisions "Use PostgreSQL for primary storage due to ACID requirements" |
| 102 | |
| 103 | # Search memories (semantic search with normalized scores 0.0-1.0) |
| 104 | subcog recall "database storage decision" |
| 105 | |
| 106 | # Search with raw RRF scores (for debugging) |
| 107 | subcog recall "database storage decision" --raw |
| 108 | |
| 109 | # Check status |
| 110 | subcog status |
| 111 | |
| 112 | # Migrate existing memories to use real embeddings |
| 113 | subcog migrate embeddings |
| 114 | ``` |
| 115 | |
| 116 | ### Score Normalization |
| 117 | |
| 118 | Search results return normalized scores in the 0.0-1.0 range: |
| 119 | - **1.0**: Best match in the result set |
| 120 | - **>=0.7**: Strong semantic match |
| 121 | - **>=0.5**: Moderate relevance |
| 122 | - **<0.5**: Weak match |
| 123 | |
| 124 | Use `--raw` flag to see the underlying RRF (Reciprocal Rank Fusion) scores. |
| 125 | |
| 126 | ## MCP Server |
| 127 | |
| 128 | Run as an MCP server for AI agent integration: |
| 129 | |
| 130 | `` |
People who liked this also viewed
6 picksType
- excel-mcpA Model Context Protocol (MCP) server for working with Excel (.xlsx) files without requiring Microsoft Excel. Enables AI assistants to create, read, modify, and format spreadsheets using openpyxl, fully in Python and cross-platform.MCP ServersOct 2025
- memories-with-lessons-mcp-serverI enhance the existing memory mcp server from the official mcp github, so big thanks and credits for creating thisMCP ServersFeb 2025
- anytype-mcpAn MCP server enabling AI assistants to interact with Anytype - your encrypted, local and collaborative wiki - to organize objects, lists, and more through natural language.MCP ServersJul 2026
- mcp-server-kubernetesMCP Server for kubernetes management commandsMCP ServersJul 2026
- thoughtboxThoughtbox is an intention ledger for agents. Evaluate AI's decisions against its decision-making.MCP ServersJul 2026
- google-drive-mcpA Model Context Protocol (MCP) server that provides secure integration with Google Drive, Docs, Sheets, Slides and Calendar. It allows Claude Desktop and other MCP clients to manage files in Google Drive through a standardized interface.MCP ServersJul 2026
