Subcog
A persistent memory system for AI coding assistants. Subcog captures decisions, learnings, and context from coding sessions and surfaces them when relevant.
Overview
Subcog delivers:
- Single-binary distribution (<100MB, <10ms cold start)
- Three-layer storage architecture: SQLite persistence, FTS5 indexing, usearch HNSW vectors
- MCP server integration for AI agent interoperability
- Claude Code plugin with hooks for seamless IDE integration
- Semantic search with hybrid vector + BM25 ranking (RRF fusion)
- Knowledge graph with entity extraction and relationship inference
- Faceted storage with project, branch, and file path filtering
ADR Compliance
ADR compliance is tracked in docs/adrs/README.md. Current compliance is 95% (55/58 active ADRs) with documented partials in ADR-0003 and ADR-0039.
Benchmark Results
Subcog achieves 97% accuracy on factual recall (LongMemEval) and 57% on personal context (LoCoMo), compared to 0% baseline without memory. See full benchmark results.
| Benchmark | With Subcog | Baseline | Improvement |
|---|
| LongMemEval | 97% | 0% | +97% |
| LoCoMo | 57% | 0% | +57% |
| ContextBench | 24% | 0% | +24% |
| MemoryAgentBench | 28% | 21% | +7% |
Features
Core (Always Available)
- Memory capture with automatic embedding generation (384-dimensional vectors)
- Real semantic search using all-MiniLM-L6-v2 via fastembed-rs
- Hybrid search combining BM25 text search + vector similarity (RRF fusion)
- Normalized scores (0.0-1.0 range) for intuitive relevance understanding
- SQLite persistence as single source of truth (ACID-compliant)
- Faceted storage with project_id, branch, and file_path fields
- Multi-domain memories (project, user, organization)
- 10 memory namespaces (decisions, learnings, patterns, blockers, etc.)
- Branch garbage collection for tombstoning stale branch memories
- Migration tools for upgrading existing memories to use embeddings
Enhanced (Opt-in)
- Entity and temporal extraction
- Secrets filtering (API keys, PII detection)
- OpenTelemetry observability
- Full Claude Code hook integration
LLM-Powered (Requires Provider)
- Implicit capture from conversations
- Memory consolidation and summarization
- Supersession detection
- Temporal reasoning queries
Installation
Multiple installation methods are available. See INSTALLATION.md for detailed instructions.
# Cargo (recommended - Rust developers)
cargo install subcog
# Homebrew (macOS/Linux)
brew install zircote/tap/subcog
# Docker
docker run --rm ghcr.io/zircote/subcog --help
# Binary download
curl -LO https://github.com/zircote/subcog/releases/latest/download/subcog-VERSION-TARGET.tar.gz
# npm/npx (fallback if binary install unavailable)
npx @zircote/subcog --help
| Method | Platforms | Auto-update |
|---|
| Cargo | All | cargo install |
| Homebrew | macOS, Linux | brew upgrade |
| Docker | linux/amd64, linux/arm64 | Pull latest tag |
| Binary | All | Manual |
| npm/npx | macOS, Linux, Windows | Via npm |
Quick Start
# Capture a memory
subcog capture --namespace decisions "Use PostgreSQL for primary storage due to ACID requirements"
# Search memories (semantic search with normalized scores 0.0-1.0)
subcog recall "database storage decision"
# Search with raw RRF scores (for debugging)
subcog recall "database storage decision" --raw
# Check status
subcog status
# Migrate existing memories to use real embeddings
subcog migrate embeddings
Score Normalization
Search results return normalized scores in the 0.0-1.0 range:
- 1.0: Best match in the result set
- >=0.7: Strong semantic match
- >=0.5: Moderate relevance
- <0.5: Weak match
Use --raw flag to see the underlying RRF (Reciprocal Rank Fusion) scores.
MCP Server
Run as an MCP server for AI agent integration:
