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:

subcog serve

Configure in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "subcog": {
      "command": "subcog",
      "args": ["serve"]
    }
  }
}

Note: This configuration requires the subcog binary to be installed and in your PATH. Install via cargo install subcog, Homebrew, or download from GitHub Releases. If you cannot install the binary, use npx as a fallback:

{ "command": "npx", "args": ["-y", "@zircote/subcog", "serve"] }

Available MCP Tools

Subcog exposes ~22 consolidated MCP tools (see ADR-0061 for the consolidation design):

| Category | Tools | Description | |----------|-------|-------------| | Core | subcog_capture, subcog_recall, subcog_status | Memory CRUD and search | | Lifecycle | subcog_consolidate, subcog_reindex | Maintenance operations | | CRUD | subcog_get, subcog_update, subcog_delete, subcog_list | Individual memory operations | | Bulk | subcog_delete_all, subcog_restore, subcog_history | Bulk and recovery operations | | Graph | subcog_graph, subcog_entities, subcog_relationships | Knowledge graph queries | | Prompts | subcog_prompts, prompt_understanding | Prompt template management | | Templates | subcog_templates | Context template management | | Session | subcog_init, subcog_get_summary, subcog_namespaces | Session and namespace info | | Compliance | subcog_gdpr_export | Data export for compliance |

When working with an agent, treat inputs that match MCP tool names as tool invocations (not shell commands) unless you explicitly say "shell" or "run in terminal".

Transport Security

Subcog supports two transport modes with different security models:

Stdio Transport (Default)

The stdio transport is the default and recommended mode for local development:

| Property | Description | |----------|-------------| | Trust Model | Process isolation via OS - parent spawns subcog as child process | | Network Exposure | None - communication only via stdin/stdout pipes | | Authentication | Implicit - same-user execution, no credentials required | | Confidentiality | Data stays on local machine (SQLite is authoritative) | | Integrity | OS guarantees pipe integrity, no MITM attacks possible |

When to use: Local development with Claude Desktop or other MCP clients that spawn subcog directly.

HTTP Transport (Optional)

Enable the HTTP transport for network-accessible deployments:

# Enable HTTP transport
subcog serve --http --port 8080

# With JWT authentication (recommended for production)
subcog serve --http --port 8080 --jwt-secret "your-secret-key"

| Property | Description | |----------|-------------| | Trust Model | JWT token authentication required | | Network Exposure | Binds to specified port (localhost by default) | | Authentication | JWT tokens with configurable expiry | | CORS | Configurable allowed origins | | TLS | Use a reverse proxy (nginx, Caddy) for HTTPS |

When to use: Team environments, remote access, or integration with web-based clients.

Data Protection

Both transports include built-in security features:

• Secrets Detection: API keys, tokens, and passwords are detected and optionally redacted
• PII Filtering: Personal information can be masked before storage
• Encryption at Rest: Enable with encryption_enabled = true (default: true)
• Audit Logging: All operations are logged for compliance (SOC2, GDPR)

See environment-variables.md for security configuration options.

Claude Code Hooks

Subcog integrates with all 5 Claude Code hooks:

| Hook | Purpose | |------|---------| | SessionStart | Inject relevant context at session start | | UserPromptSubmit | Detect capture signals in prompts | | PostToolUse | Surface related memories after file operations | | PreCompact | Analyze conversation for auto-capture | | Stop | Finalize session, capture pending memories |

Configure in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "command": "subcog hook session-start" }],
    "UserPromptSubmit": [{ "command": "subcog hook user-prompt-submit" }],
    "PostToolUse": [{ "command": "subcog hook post-tool-use" }],
    "PreCompact": [{ "command": "subcog hook pre-compact" }],
    "Stop": [{ "command": "subcog hook stop" }]
  }
}

Migration

Upgrade existing memories to use real embeddings:

# Dry-run (see what would be migrated)
subcog migrate embeddings --dry-run

# Migrate all memories without embeddings
subcog migrate embeddings

# Force re-generation of all embeddings
subcog migrate embeddings --force

# Migrate from a specific repository
subcog migrate embeddings --repo /path/to/repo

The migration command:

• Scans all memories in the index
• Generates embeddings using