Persistent 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.
How to install subcog?
zircote/subcog
$git clone https://github.com/zircote/subcogInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install subcog by running `git clone https://github.com/zircote/subcog`, then use it for the current task and follow its documentation at https://github.com/zircote/subcog.
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 | `` |
Related
6 picksType
- ha-mcpComprehensive Model Context Protocol server for managing Home Assistant through AI assistants.Jul 2026
- google_workspace_mcpGoogle Workspace MCP server for Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Chat.Jul 2026
- basic-memoryLocal-first knowledge management with bi-directional LLM sync via Markdown files.Jul 2026
- voicemodeNatural voice conversations for AI assistants - STT/TTS via MCPJul 2026
- mcp-server-calculatorA Model Context Protocol server for calculatingMay 2025
- email-mcpIMAP/SMTP email MCP server — 47 tools, IMAP IDLE push, multi-account, AI triage.May 2026
