subcog

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: