{"id":35587221,"url":"https://github.com/zircote/subcog","last_synced_at":"2026-01-23T17:02:47.659Z","repository":{"id":332267205,"uuid":"1124319493","full_name":"zircote/subcog","owner":"zircote","description":"Persistent memory system for AI coding assistants. Captures decisions, learnings, and context from coding sessions. Features hybrid search (semantic + BM25), MCP server for Claude Code, Git Notes persistence, and proactive memory surfacing. Written in Rust.","archived":false,"fork":false,"pushed_at":"2026-01-14T00:10:56.000Z","size":9395,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T00:14:07.884Z","etag":null,"topics":["ai","ai-assistant","claude-code","cli","developer-tools","embeddings","git-notes","hybrid-search","llm","mcp","memory-system","model-context-protocol","rag","rust","semantic-search","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zircote.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"zircote"}},"created_at":"2025-12-28T19:49:52.000Z","updated_at":"2026-01-14T00:11:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zircote/subcog","commit_stats":null,"previous_names":["zircote/subcog"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/zircote/subcog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fsubcog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fsubcog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fsubcog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fsubcog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zircote","download_url":"https://codeload.github.com/zircote/subcog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zircote%2Fsubcog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28482267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-assistant","claude-code","cli","developer-tools","embeddings","git-notes","hybrid-search","llm","mcp","memory-system","model-context-protocol","rag","rust","semantic-search","vector-search"],"created_at":"2026-01-04T22:14:49.745Z","updated_at":"2026-01-23T17:02:47.653Z","avatar_url":"https://github.com/zircote.png","language":"Rust","funding_links":["https://github.com/sponsors/zircote"],"categories":[],"sub_categories":[],"readme":"# Subcog\n\n[![CI](https://github.com/zircote/subcog/actions/workflows/ci.yml/badge.svg)](https://github.com/zircote/subcog/actions/workflows/ci.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/zircote/subcog?logo=github\u0026logoColor=white)](https://github.com/zircote/subcog/releases)\n[![Crates.io](https://img.shields.io/crates/v/subcog?logo=rust\u0026logoColor=white)](https://crates.io/crates/subcog)\n[![Rust Version](https://img.shields.io/badge/rust-1.88%2B-dea584?logo=rust\u0026logoColor=white)](https://www.rust-lang.org/)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![Clippy](https://img.shields.io/badge/linting-clippy-orange?logo=rust\u0026logoColor=white)](https://github.com/rust-lang/rust-clippy)\n[![cargo-deny](https://img.shields.io/badge/security-cargo--deny-blue?logo=rust\u0026logoColor=white)](https://github.com/EmbarkStudios/cargo-deny)\n\nA persistent memory system for AI coding assistants. Subcog captures decisions, learnings, and context from coding sessions and surfaces them when relevant.\n\n![Subcog Prompt Library Workflow](docs/_assets/subcog-inforgraphic.png)\n\n## Overview\n\nSubcog delivers:\n\n- **Single-binary distribution** (\u003c100MB, \u003c10ms cold start)\n- **Three-layer storage architecture**: SQLite persistence, FTS5 indexing, usearch HNSW vectors\n- **MCP server integration** for AI agent interoperability\n- **Claude Code plugin** with hooks for seamless IDE integration\n- **Semantic search** with hybrid vector + BM25 ranking (RRF fusion)\n- **Knowledge graph** with entity extraction and relationship inference\n- **Faceted storage** with project, branch, and file path filtering\n\n## ADR Compliance\n\nADR 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.\n\n## Benchmark Results\n\nSubcog 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).\n\n| Benchmark | With Subcog | Baseline | Improvement |\n|-----------|-------------|----------|-------------|\n| LongMemEval | 97% | 0% | +97% |\n| LoCoMo | 57% | 0% | +57% |\n| ContextBench | 24% | 0% | +24% |\n| MemoryAgentBench | 28% | 21% | +7% |\n\n## Features\n\n### Core (Always Available)\n- Memory capture with **automatic embedding generation** (384-dimensional vectors)\n- **Real semantic search** using all-MiniLM-L6-v2 via fastembed-rs\n- **Hybrid search** combining BM25 text search + vector similarity (RRF fusion)\n- **Normalized scores** (0.0-1.0 range) for intuitive relevance understanding\n- **SQLite persistence** as single source of truth (ACID-compliant)\n- **Faceted storage** with project_id, branch, and file_path fields\n- Multi-domain memories (project, user, organization)\n- 10 memory namespaces (decisions, learnings, patterns, blockers, etc.)\n- **Branch garbage collection** for tombstoning stale branch memories\n- **Migration tools** for upgrading existing memories to use embeddings\n\n### Enhanced (Opt-in)\n- Entity and temporal extraction\n- Secrets filtering (API keys, PII detection)\n- OpenTelemetry observability\n- Full Claude Code hook integration\n\n### LLM-Powered (Requires Provider)\n- Implicit capture from conversations\n- Memory consolidation and summarization\n- Supersession detection\n- Temporal reasoning queries\n\n## Installation\n\nMultiple installation methods are available. See [INSTALLATION.md](docs/INSTALLATION.md) for detailed instructions.\n\n```bash\n# Cargo (recommended - Rust developers)\ncargo install subcog\n\n# Homebrew (macOS/Linux)\nbrew install zircote/tap/subcog\n\n# Docker\ndocker run --rm ghcr.io/zircote/subcog --help\n\n# Binary download\ncurl -LO https://github.com/zircote/subcog/releases/latest/download/subcog-VERSION-TARGET.tar.gz\n\n# npm/npx (fallback if binary install unavailable)\nnpx @zircote/subcog --help\n```\n\n| Method | Platforms | Auto-update |\n|--------|-----------|-------------|\n| Cargo | All | `cargo install` |\n| Homebrew | macOS, Linux | `brew upgrade` |\n| Docker | linux/amd64, linux/arm64 | Pull latest tag |\n| Binary | All | Manual |\n| npm/npx | macOS, Linux, Windows | Via npm |\n\n## Quick Start\n\n```bash\n# Capture a memory\nsubcog capture --namespace decisions \"Use PostgreSQL for primary storage due to ACID requirements\"\n\n# Search memories (semantic search with normalized scores 0.0-1.0)\nsubcog recall \"database storage decision\"\n\n# Search with raw RRF scores (for debugging)\nsubcog recall \"database storage decision\" --raw\n\n# Check status\nsubcog status\n\n# Migrate existing memories to use real embeddings\nsubcog migrate embeddings\n```\n\n### Score Normalization\n\nSearch results return normalized scores in the 0.0-1.0 range:\n- **1.0**: Best match in the result set\n- **\u003e=0.7**: Strong semantic match\n- **\u003e=0.5**: Moderate relevance\n- **\u003c0.5**: Weak match\n\nUse `--raw` flag to see the underlying RRF (Reciprocal Rank Fusion) scores.\n\n## MCP Server\n\nRun as an MCP server for AI agent integration:\n\n```bash\nsubcog serve\n```\n\nConfigure in Claude Desktop's `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"subcog\": {\n      \"command\": \"subcog\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n\u003e **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](https://github.com/zircote/subcog/releases). If you cannot install the binary, use npx as a fallback:\n\u003e ```json\n\u003e { \"command\": \"npx\", \"args\": [\"-y\", \"@zircote/subcog\", \"serve\"] }\n\u003e ```\n\n### Available MCP Tools\n\nSubcog exposes ~22 consolidated MCP tools (see [ADR-0061](docs/adrs/adr_0061.md) for the consolidation design):\n\n| Category | Tools | Description |\n|----------|-------|-------------|\n| **Core** | `subcog_capture`, `subcog_recall`, `subcog_status` | Memory CRUD and search |\n| **Lifecycle** | `subcog_consolidate`, `subcog_reindex` | Maintenance operations |\n| **CRUD** | `subcog_get`, `subcog_update`, `subcog_delete`, `subcog_list` | Individual memory operations |\n| **Bulk** | `subcog_delete_all`, `subcog_restore`, `subcog_history` | Bulk and recovery operations |\n| **Graph** | `subcog_graph`, `subcog_entities`, `subcog_relationships` | Knowledge graph queries |\n| **Prompts** | `subcog_prompts`, `prompt_understanding` | Prompt template management |\n| **Templates** | `subcog_templates` | Context template management |\n| **Session** | `subcog_init`, `subcog_get_summary`, `subcog_namespaces` | Session and namespace info |\n| **Compliance** | `subcog_gdpr_export` | Data export for compliance |\n\nWhen working with an agent, treat inputs that match MCP tool names as tool\ninvocations (not shell commands) unless you explicitly say \"shell\" or \"run in\nterminal\".\n\n### Transport Security\n\nSubcog supports two transport modes with different security models:\n\n#### Stdio Transport (Default)\n\nThe stdio transport is the default and recommended mode for local development:\n\n| Property | Description |\n|----------|-------------|\n| **Trust Model** | Process isolation via OS - parent spawns subcog as child process |\n| **Network Exposure** | None - communication only via stdin/stdout pipes |\n| **Authentication** | Implicit - same-user execution, no credentials required |\n| **Confidentiality** | Data stays on local machine (SQLite is authoritative) |\n| **Integrity** | OS guarantees pipe integrity, no MITM attacks possible |\n\n**When to use**: Local development with Claude Desktop or other MCP clients that spawn subcog directly.\n\n#### HTTP Transport (Optional)\n\nEnable the HTTP transport for network-accessible deployments:\n\n```bash\n# Enable HTTP transport\nsubcog serve --http --port 8080\n\n# With JWT authentication (recommended for production)\nsubcog serve --http --port 8080 --jwt-secret \"your-secret-key\"\n```\n\n| Property | Description |\n|----------|-------------|\n| **Trust Model** | JWT token authentication required |\n| **Network Exposure** | Binds to specified port (localhost by default) |\n| **Authentication** | JWT tokens with configurable expiry |\n| **CORS** | Configurable allowed origins |\n| **TLS** | Use a reverse proxy (nginx, Caddy) for HTTPS |\n\n**When to use**: Team environments, remote access, or integration with web-based clients.\n\n#### Data Protection\n\nBoth transports include built-in security features:\n\n- **Secrets Detection**: API keys, tokens, and passwords are detected and optionally redacted\n- **PII Filtering**: Personal information can be masked before storage\n- **Encryption at Rest**: Enable with `encryption_enabled = true` (default: true)\n- **Audit Logging**: All operations are logged for compliance (SOC2, GDPR)\n\nSee [environment-variables.md](docs/environment-variables.md) for security configuration options.\n\n## Claude Code Hooks\n\nSubcog integrates with all 5 Claude Code hooks:\n\n| Hook | Purpose |\n|------|---------|\n| `SessionStart` | Inject relevant context at session start |\n| `UserPromptSubmit` | Detect capture signals in prompts |\n| `PostToolUse` | Surface related memories after file operations |\n| `PreCompact` | Analyze conversation for auto-capture |\n| `Stop` | Finalize session, capture pending memories |\n\nConfigure in `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{ \"command\": \"subcog hook session-start\" }],\n    \"UserPromptSubmit\": [{ \"command\": \"subcog hook user-prompt-submit\" }],\n    \"PostToolUse\": [{ \"command\": \"subcog hook post-tool-use\" }],\n    \"PreCompact\": [{ \"command\": \"subcog hook pre-compact\" }],\n    \"Stop\": [{ \"command\": \"subcog hook stop\" }]\n  }\n}\n```\n\n## Migration\n\nUpgrade existing memories to use real embeddings:\n\n```bash\n# Dry-run (see what would be migrated)\nsubcog migrate embeddings --dry-run\n\n# Migrate all memories without embeddings\nsubcog migrate embeddings\n\n# Force re-generation of all embeddings\nsubcog migrate embeddings --force\n\n# Migrate from a specific repository\nsubcog migrate embeddings --repo /path/to/repo\n```\n\nThe migration command:\n- Scans all memories in the index\n- Generates embeddings using fastembed (all-MiniLM-L6-v2)\n- Stores embeddings in the vector backend (usearch HNSW)\n- Skips memories that already have embeddings (unless `--force`)\n- Shows progress with migrated/skipped/error counts\n\n## Architecture\n\nSubcog uses a **three-layer storage architecture** to separate concerns:\n\n### System Architecture Diagram\n\n```mermaid\nflowchart TB\n    subgraph Access[\"Access Layer\"]\n        CLI[\"CLI\u003cbr/\u003esubcog capture/recall/status\"]\n        MCP[\"MCP Server\u003cbr/\u003eJSON-RPC over stdio\"]\n        Hooks[\"Claude Code Hooks\u003cbr/\u003eSessionStart, UserPrompt, Stop\"]\n    end\n\n    subgraph Services[\"Service Layer\"]\n        Capture[\"CaptureService\u003cbr/\u003eMemory ingestion\"]\n        Recall[\"RecallService\u003cbr/\u003eHybrid search\"]\n        GC[\"GCService\u003cbr/\u003eBranch cleanup\"]\n        Dedup[\"DeduplicationService\u003cbr/\u003e3-tier duplicate detection\"]\n        Context[\"ContextBuilder\u003cbr/\u003eAdaptive injection\"]\n    end\n\n    subgraph Storage[\"Three-Layer Storage\"]\n        subgraph Persistence[\"Persistence Layer\u003cbr/\u003e(Authoritative)\"]\n            SQLiteP[\"SQLite\u003cbr/\u003e(default)\"]\n            PostgresP[\"PostgreSQL\"]\n            FS[\"Filesystem\"]\n        end\n\n        subgraph Index[\"Index Layer\u003cbr/\u003e(Searchable)\"]\n            SQLiteI[\"SQLite + FTS5\u003cbr/\u003e(default)\"]\n            PostgresI[\"PostgreSQL FTS\"]\n            Redis[\"RediSearch\"]\n        end\n\n        subgraph Vector[\"Vector Layer\u003cbr/\u003e(Embeddings)\"]\n            usearch[\"usearch HNSW\u003cbr/\u003e(default)\"]\n            pgvector[\"pgvector\"]\n            RedisV[\"Redis Vector\"]\n        end\n    end\n\n    subgraph External[\"External Systems\"]\n        FastEmbed[\"FastEmbed\u003cbr/\u003eall-MiniLM-L6-v2\"]\n        LLM[\"LLM Provider\u003cbr/\u003eAnthropic/OpenAI/Ollama\"]\n    end\n\n    CLI --\u003e Capture\n    CLI --\u003e Recall\n    MCP --\u003e Capture\n    MCP --\u003e Recall\n    Hooks --\u003e Context\n    Hooks --\u003e Capture\n\n    Capture --\u003e Persistence\n    Capture --\u003e Index\n    Capture --\u003e Vector\n    Capture --\u003e FastEmbed\n    Capture --\u003e Dedup\n\n    Recall --\u003e Index\n    Recall --\u003e Vector\n    Recall --\u003e FastEmbed\n\n    Context --\u003e Recall\n    Context --\u003e LLM\n\n    Dedup --\u003e Recall\n    Dedup --\u003e FastEmbed\n\n    GC --\u003e Persistence\n    GC --\u003e Index\n\n    style Access fill:#e1f5fe\n    style Services fill:#fff3e0\n    style Storage fill:#e8f5e9\n    style External fill:#fce4ec\n```\n\n### Data Flow Diagram\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant CLI/MCP\n    participant CaptureService\n    participant Dedup\n    participant FastEmbed\n    participant Persistence\n    participant Index\n    participant Vector\n\n    User-\u003e\u003eCLI/MCP: subcog capture \"decision...\"\n    CLI/MCP-\u003e\u003eCaptureService: CaptureRequest\n    CaptureService-\u003e\u003eDedup: Check duplicate\n    Dedup-\u003e\u003eIndex: Hash tag lookup (exact)\n    Dedup-\u003e\u003eFastEmbed: Generate embedding\n    Dedup-\u003e\u003eVector: Similarity search (semantic)\n    Dedup--\u003e\u003eCaptureService: Not duplicate\n\n    CaptureService-\u003e\u003eFastEmbed: Generate embedding\n    FastEmbed--\u003e\u003eCaptureService: [384-dim vector]\n\n    par Store in all layers\n        CaptureService-\u003e\u003ePersistence: Store memory\n        CaptureService-\u003e\u003eIndex: Index for FTS\n        CaptureService-\u003e\u003eVector: Store embedding\n    end\n\n    CaptureService--\u003e\u003eCLI/MCP: CaptureResult{id, urn}\n    CLI/MCP--\u003e\u003eUser: Memory captured\n```\n\n### Hybrid Search Flow\n\n```mermaid\nflowchart LR\n    Query[\"Query: 'database storage decision'\"]\n\n    subgraph Search[\"Parallel Search\"]\n        BM25[\"BM25 Search\u003cbr/\u003e(Index Layer)\"]\n        VectorSearch[\"Vector Search\u003cbr/\u003e(Vector Layer)\"]\n    end\n\n    subgraph Results[\"Raw Results\"]\n        BM25Results[\"id1: 2.3\u003cbr/\u003eid2: 1.8\u003cbr/\u003eid3: 1.2\"]\n        VectorResults[\"id2: 0.92\u003cbr/\u003eid1: 0.85\u003cbr/\u003eid4: 0.78\"]\n    end\n\n    RRF[\"RRF Fusion\u003cbr/\u003escore = sum(1/(k+rank))\"]\n\n    Final[\"Final Results\u003cbr/\u003e(normalized 0.0-1.0)\u003cbr/\u003eid2: 1.00\u003cbr/\u003eid1: 0.87\u003cbr/\u003eid3: 0.45\u003cbr/\u003eid4: 0.38\"]\n\n    Query --\u003e BM25\n    Query --\u003e VectorSearch\n    BM25 --\u003e BM25Results\n    VectorSearch --\u003e VectorResults\n    BM25Results --\u003e RRF\n    VectorResults --\u003e RRF\n    RRF --\u003e Final\n```\n\n### ASCII Architecture Reference\n\n```\n                              +-----------------+\n                              |   Access Layer  |\n                              +-----------------+\n                              |  CLI | MCP | Hooks\n                              +--------+--------+\n                                       |\n                              +--------v--------+\n                              |  Service Layer  |\n                              +-----------------+\n                              | Capture | Recall | GC\n                              +--------+--------+\n                                       |\n        +------------------------------+------------------------------+\n        |                              |                              |\n+-------v-------+             +--------v-------+             +--------v-------+\n|  Persistence  |             |     Index      |             |     Vector     |\n|    Layer      |             |     Layer      |             |     Layer      |\n+---------------+             +----------------+             +----------------+\n|               |             |                |             |                |\n| - Authoritative             | - Full-text    |             | - Embeddings   |\n|   source of truth           |   search (BM25)|             |   (384-dim)    |\n| - ACID storage              | - Faceted      |             | - Similarity   |\n| - Durable                   |   filtering    |             |   search (ANN) |\n|               |             |                |             |                |\n+-------+-------+             +--------+-------+             +--------+-------+\n        |                              |                              |\n+-------v-------+             +--------v-------+             +--------v-------+\n|    SQLite     |             | SQLite + FTS5  |             |    usearch     |\n|  (default)    |             |   (default)    |             |   (HNSW)       |\n+---------------+             +----------------+             +----------------+\n|  PostgreSQL   |             |  PostgreSQL    |             |   pgvector     |\n+---------------+             +----------------+             +----------------+\n|  Filesystem   |             |  RediSearch    |             | Redis Vector   |\n+---------------+             +----------------+             +----------------+\n```\n\n### Layer Responsibilities\n\n| Layer | Purpose | Default Backend | Alternatives |\n|-------|---------|-----------------|--------------|\n| **Persistence** | Authoritative storage, ACID guarantees | SQLite | PostgreSQL, Filesystem |\n| **Index** | Full-text search, BM25 ranking | SQLite + FTS5 | PostgreSQL, RediSearch |\n| **Vector** | Embedding storage, ANN search | usearch (HNSW) | pgvector, Redis Vector |\n\nFor detailed architecture documentation, see [`src/storage/traits/mod.rs`](src/storage/traits/mod.rs).\n\n## Development\n\n### Prerequisites\n\n- Rust 1.88+ (Edition 2024)\n- Git 2.30+\n- [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) for supply chain security\n\n### Setup\n\n```bash\ngit clone https://github.com/zircote/subcog.git\ncd subcog\n\n# Build\ncargo build\n\n# Run tests\ncargo test\n\n# Run all checks\ncargo fmt -- --check \u0026\u0026 \\\ncargo clippy --all-targets --all-features -- -D warnings \u0026\u0026 \\\ncargo test \u0026\u0026 \\\ncargo doc --no-deps \u0026\u0026 \\\ncargo deny check\n```\n\n### Project Structure\n\n```\nsrc/\n├── lib.rs              # Library entry point\n├── main.rs             # CLI entry point\n├── models/             # Data structures (Memory, Domain, Namespace)\n├── storage/            # Storage backends (SQLite, PostgreSQL, usearch)\n│   └── traits/         # Backend trait definitions (see mod.rs for docs)\n├── services/           # Business logic (Capture, Recall, GC)\n├── mcp/                # MCP server implementation\n├── hooks/              # Claude Code hook handlers\n├── embedding/          # Vector embedding generation\n└── observability/      # Tracing, metrics, logging\n\ndocs/\n├── QUICKSTART.md       # Getting started guide\n├── TROUBLESHOOTING.md  # Common issues and solutions\n├── PERFORMANCE.md      # Performance tuning guide\n├── research/           # Research documents\n└── spec/               # Specification documents\n```\n\n## Configuration\n\nConfiguration file at `~/.config/subcog/config.toml`:\n\n```toml\n[storage]\nbackend = \"sqlite\"  # \"sqlite\", \"postgres\", \"filesystem\"\ndata_dir = \"~/.local/share/subcog\"\n\n[embedding]\nmodel = \"all-MiniLM-L6-v2\"\ndimensions = 384\n\n[hooks]\nenabled = true\nsession_start_timeout_ms = 2000\nuser_prompt_timeout_ms = 50\n\n[llm]\nprovider = \"anthropic\"  # Optional: for Tier 3 features\n```\n\n### Faceted Capture\n\nMemories can be tagged with project, branch, and file path:\n\n```bash\n# Capture with facets (auto-detected from git context)\nsubcog capture --namespace decisions \"Use PostgreSQL\"\n\n# Capture with explicit facets\nsubcog capture --namespace decisions --project my-project --branch feature/auth \"Added JWT support\"\n\n# Search within a project\nsubcog recall \"authentication\" --project my-project\n\n# Search within a branch\nsubcog recall \"bug fix\" --branch feature/auth\n\n# Include tombstoned memories\nsubcog recall \"old decision\" --include-tombstoned\n```\n\n### Branch Garbage Collection\n\nClean up memories from deleted branches:\n\n```bash\n# GC current project (dry-run)\nsubcog gc --dry-run\n\n# GC specific branch\nsubcog gc --branch feature/old-branch\n\n# Purge tombstoned memories older than 30 days\nsubcog gc --purge --older-than 30d\n```\n\n## Performance Targets\n\n| Metric | Target | Actual |\n|--------|--------|--------|\n| Cold start | \u003c10ms | ~5ms |\n| Capture latency | \u003c30ms | ~25ms |\n| Search latency (100 memories) | \u003c20ms | ~82us |\n| Search latency (1,000 memories) | \u003c50ms | ~413us |\n| Search latency (10,000 memories) | \u003c100ms | ~3.7ms |\n| Binary size | \u003c100MB | ~50MB |\n| Memory (idle) | \u003c50MB | ~30MB |\n\nAll performance targets are exceeded by 10-100x. Benchmarks run via `cargo bench`.\n\nFor performance tuning, see [docs/PERFORMANCE.md](docs/PERFORMANCE.md).\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [INSTALLATION.md](docs/INSTALLATION.md) | Complete installation guide (npm, Docker, Homebrew, Cargo) |\n| [QUICKSTART.md](docs/QUICKSTART.md) | Getting started guide |\n| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues and solutions |\n| [PERFORMANCE.md](docs/PERFORMANCE.md) | Performance tuning guide |\n| [environment-variables.md](docs/environment-variables.md) | Environment variable reference |\n| [URN-GUIDE.md](docs/URN-GUIDE.md) | Memory URN scheme documentation |\n\n## Specification\n\n### Active Work\n\nSee `docs/spec/active/` for current work in progress.\n\n### Completed Specifications\n\nFull specification documents for the storage architecture are in [`docs/spec/completed/2026-01-03-storage-simplification/`](docs/spec/completed/2026-01-03-storage-simplification/):\n\n- [REQUIREMENTS.md](docs/spec/completed/2026-01-03-storage-simplification/REQUIREMENTS.md) - Product requirements\n- [ARCHITECTURE.md](docs/spec/completed/2026-01-03-storage-simplification/ARCHITECTURE.md) - Technical architecture\n- [IMPLEMENTATION_PLAN.md](docs/spec/completed/2026-01-03-storage-simplification/IMPLEMENTATION_PLAN.md) - Phased implementation\n- [DECISIONS.md](docs/spec/completed/2026-01-03-storage-simplification/DECISIONS.md) - Architecture decision records\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [fastembed](https://github.com/Anush008/fastembed-rs) - Embedding generation\n- [usearch](https://github.com/unum-cloud/usearch) - Vector similarity search\n- [rmcp](https://github.com/anthropics/rmcp) - MCP protocol implementation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzircote%2Fsubcog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzircote%2Fsubcog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzircote%2Fsubcog/lists"}