{"id":45890331,"url":"https://github.com/cogniplex/codemem","last_synced_at":"2026-03-17T10:03:49.633Z","repository":{"id":341008481,"uuid":"1168597963","full_name":"cogniplex/codemem","owner":"cogniplex","description":"A standalone Rust memory engine for AI coding assistants. Single binary, zero runtime deps. Graph-vector hybrid with MCP tools.","archived":false,"fork":false,"pushed_at":"2026-03-05T13:01:49.000Z","size":3491,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T18:50:16.018Z","etag":null,"topics":["ai-coding","cli","embeddings","knowledge-graph","mcp","mcp-server","memory","rag","rust","sqlite","tree-sitter","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cogniplex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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}},"created_at":"2026-02-27T15:21:20.000Z","updated_at":"2026-03-05T13:01:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cogniplex/codemem","commit_stats":null,"previous_names":["cogniplex/codemem"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/cogniplex/codemem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogniplex%2Fcodemem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogniplex%2Fcodemem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogniplex%2Fcodemem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogniplex%2Fcodemem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cogniplex","download_url":"https://codeload.github.com/cogniplex/codemem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cogniplex%2Fcodemem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30265296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T14:54:00.943Z","status":"ssl_error","status_checked_at":"2026-03-08T14:53:54.486Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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-coding","cli","embeddings","knowledge-graph","mcp","mcp-server","memory","rag","rust","sqlite","tree-sitter","vector-search"],"created_at":"2026-02-27T17:49:00.236Z","updated_at":"2026-03-14T15:51:48.532Z","avatar_url":"https://github.com/cogniplex.png","language":"Rust","readme":"# Codemem\n\n[![CI](https://github.com/cogniplex/codemem/actions/workflows/ci.yml/badge.svg)](https://github.com/cogniplex/codemem/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/cogniplex/codemem/graph/badge.svg)](https://codecov.io/gh/cogniplex/codemem)\n[![Crates.io](https://img.shields.io/crates/v/codemem.svg)](https://crates.io/crates/codemem)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nA standalone Rust memory engine for AI coding assistants. Single binary, zero runtime deps.\n\nCodemem stores what your AI assistant discovers -- files read, symbols searched, edits made -- so repositories don't need re-exploring across sessions. Optionally enriches the graph with compiler-grade cross-references via [SCIP](https://scip.dev) indexers.\n\n![Codemem Graph UI -- Knowledge graph with community detection, edge visualization, and node kind filters](docs/graph-ui.png)\n\n## Quick Start\n\n### Install\n\n```bash\n# Shell (macOS/Linux)\ncurl -fsSL https://raw.githubusercontent.com/cogniplex/codemem/main/install.sh | sh\n\n# Homebrew\nbrew install cogniplex/tap/codemem\n\n# Cargo\ncargo install codemem\n```\n\nOr download a prebuilt binary from [Releases](https://github.com/cogniplex/codemem/releases).\n\n| Platform | Architecture | Binary |\n|----------|-------------|--------|\n| macOS | ARM64 (Apple Silicon) | `codemem-macos-arm64.tar.gz` |\n| Linux | x86_64 | `codemem-linux-amd64.tar.gz` |\n| Linux | ARM64 | `codemem-linux-arm64.tar.gz` |\n\n### Initialize\n\n```bash\ncd your-project\ncodemem init\n```\n\nDownloads the local embedding model (~440MB, one-time), registers lifecycle hooks, and configures the MCP server for your AI assistant. Automatically detects Claude Code, Cursor, and Windsurf.\n\n### That's it\n\nCodemem now automatically captures context, injects prior knowledge at session start, and provides 26 MCP tools to your assistant.\n\n### Map your codebase (optional)\n\nRun the full analysis pipeline -- indexes your codebase with tree-sitter, enriches the graph with SCIP cross-references (if indexers are installed), computes PageRank, and detects architectural clusters:\n\n```bash\ncodemem analyze\n```\n\nThen launch the code-mapper agent to do deep, agent-driven analysis -- it spawns a team of specialized agents that traverse the knowledge graph, discover patterns, and store architectural insights:\n\n```bash\nclaude --agent code-mapper\n```\n\nSee [Index \u0026 Enrich Pipeline](docs/pipeline.md) for what happens under the hood.\n\n### SCIP enrichment (optional, recommended)\n\n[SCIP](https://scip.dev) (Source Code Intelligence Protocol) gives codemem compiler-grade cross-references -- every call, import, type reference, and override in your codebase, with zero false positives. `codemem analyze` auto-detects installed indexers and runs them automatically.\n\n**Install the indexer for your language:**\n\n| Language | Indexer | Install |\n|----------|---------|---------|\n| Rust | rust-analyzer | `rustup component add rust-analyzer` |\n| TypeScript/JavaScript | scip-typescript | `npm install -g @sourcegraph/scip-typescript` |\n| Python | scip-python | `npm install -g @sourcegraph/scip-python` |\n| Go | scip-go | `go install github.com/sourcegraph/scip-go/cmd/scip-go@latest` |\n| Java/Kotlin | scip-java | [scip-java releases](https://sourcegraph.github.io/scip-java/) |\n| C# | scip-dotnet | `dotnet tool install --global scip-dotnet` |\n| Ruby | scip-ruby | `gem install scip-ruby` |\n\nCodemem detects languages from manifest files (`Cargo.toml`, `package.json`, `pyproject.toml`, `go.mod`, etc.) and checks PATH for the corresponding indexer. If found, SCIP edges are fused with ast-grep pattern edges -- when both sources agree on the same edge, their confidence scores sum (0.10 + 0.15 = 0.25), producing higher-fidelity graph connections.\n\n**Configure via `~/.codemem/config.toml`:**\n\n```toml\n[scip]\nenabled = true                    # Master switch (default: true)\nauto_detect_indexers = true       # Check PATH for available indexers\ncache_index = true                # Cache .scip files between runs\ncache_ttl_hours = 24              # Re-index if cache older than this\ncreate_external_nodes = true      # Create ext: nodes for dependency symbols\nstore_docs_as_memories = true     # Attach hover docs as memories\nhierarchical_containment = true   # Build nested containment tree\ncollapse_intra_class_edges = true # Fold intra-class calls into parent metadata\n\n[scip.fan_out_limits]\nmodule = 200     # Modules can be widely imported\nclass = 50       # Classes referenced moderately\nfunction = 30    # Functions and methods less so\nmethod = 30\n\n# Override auto-detected indexer commands per language:\n# [scip.indexers]\n# rust = \"rust-analyzer scip .\"\n# typescript = \"scip-typescript index --infer-tsconfig\"\n```\n\nNo SCIP indexer installed? No problem -- codemem works fine without it. You just get ast-grep pattern edges (confidence 0.10) instead of compiler-grade ones.\n\n## Key Features\n\n- **Graph-vector hybrid architecture** -- HNSW vector search (768-dim) + petgraph knowledge graph (PageRank, Louvain community detection, betweenness centrality, BFS/DFS, SCC, topological sort, and more)\n- **SCIP integration** -- Compiler-grade cross-references via [SCIP](https://scip.dev) indexers (rust-analyzer, scip-typescript, scip-python, scip-go, scip-java, and more). Multi-layer edge fusion with ast-grep: when both sources agree, confidence scores sum. Auto-detects installed indexers, caches results, and cleans up stale nodes on re-index\n- **26 MCP tools** -- Memory CRUD, self-editing (refine/split/merge), graph traversal, code search, consolidation, impact analysis, session context, pattern detection over JSON-RPC\n- **4 lifecycle hooks** -- Automatic context injection (SessionStart), prompt capture (UserPromptSubmit), observation capture (PostToolUse), and session summaries (Stop)\n- **8-component hybrid scoring** -- Vector similarity, graph strength, BM25 token overlap, temporal alignment, tag matching, importance, confidence, and recency\n- **Code-aware indexing** -- tree-sitter structural extraction for 14 languages (Rust, TypeScript/JS/JSX, Python, Go, C/C++, Java, Ruby, C#, Kotlin, Swift, PHP, Scala, HCL/Terraform) with manifest parsing (Cargo.toml, package.json, go.mod, pyproject.toml)\n- **Contextual embeddings** -- Metadata and graph context enriched before embedding for higher recall precision\n- **Pluggable embeddings** -- Candle (local BERT, default), Ollama, or any OpenAI-compatible API\n- **Cross-session intelligence** -- Pattern detection, file hotspot tracking, decision chains, and session continuity\n- **Memory consolidation** -- 5 neuroscience-inspired cycles: Decay (power-law), Creative/REM (semantic KNN), Cluster (cosine + union-find), Summarize (LLM-powered), Forget\n- **Self-editing memory** -- Refine, split, and merge memories with full provenance tracking via temporal graph edges\n- **Operational metrics** -- Per-tool latency percentiles (p50/p95/p99), call counters, and gauges via `codemem_status` tool\n- **Real-time file watching** -- notify-based watcher with \u003c50ms debounce and .gitignore support\n- **Persistent config** -- TOML-based configuration at `~/.codemem/config.toml`\n- **Production hardened** -- Zero `.unwrap()` in production code, safe concurrency, versioned schema migrations\n\n## Benchmarks\n\nAlthough codemem is designed for code exploration memory (not generic conversational recall), it scores competitively on standard memory benchmarks:\n\n| Benchmark | Score | Notes |\n|-----------|-------|-------|\n| [LoCoMo](bench/locomo/) (ACL 2024) | **91.64%** | vs 90.53% published SOTA — stricter conditions: recall limit 10, no evidence oracle, no embedding fallback |\n| [LongMemEval](bench/longmemeval/) (ICLR 2025) | **70%** | vs 71.2% Zep, 82.4% oracle — recall limit 10, GPT-4o judge |\n\nBoth benchmarks use stricter conditions than published baselines: recall limit of 10 (vs 50-100), no evidence oracle, no embedding fallback. Both were run with OpenAI text-embedding-3-small. With the built-in local BERT model (BAAI/bge-base-en-v1.5), LoCoMo scores 89.58% — a ~2% gap that graph expansion closes entirely (91.49% for both models in codemem-graph mode). Higher scores are achievable with better embedding models without any architectural changes.\n\nSee [bench/locomo/](bench/locomo/) and [bench/longmemeval/](bench/longmemeval/) for methodology, reproduction steps, and detailed breakdowns.\n\n## How It Works\n\n```mermaid\ngraph LR\n    A[AI Assistant] --\u003e|SessionStart hook| B[codemem context]\n    A --\u003e|PostToolUse hooks| C[codemem ingest]\n    A --\u003e|Stop hook| E[codemem summarize]\n    A --\u003e|MCP tools| D[codemem serve]\n    B --\u003e|Inject context| A\n    C --\u003e F[Storage + Vector + Graph]\n    D --\u003e F\n    F --\u003e|Recall| A\n```\n\n1. **Passively captures** what your AI reads, searches, and edits via lifecycle hooks\n2. **Actively recalls** relevant context via MCP tools with 8-component hybrid scoring\n3. **Injects context** at session start so your assistant picks up where it left off\n\n### Hybrid scoring\n\n| Component | Weight |\n|-----------|--------|\n| Vector similarity | 25% |\n| Graph strength (PageRank + betweenness + degree + cluster) | 20% |\n| BM25 token overlap | 15% |\n| Temporal | 10% |\n| Importance | 10% |\n| Confidence | 10% |\n| Tag matching | 5% |\n| Recency | 5% |\n\nWeights are configurable via `codemem config set scoring.\u003ckey\u003e \u003cvalue\u003e` and persist in `~/.codemem/config.toml`.\n\n## Configuration\n\n### Embedding providers\n\nBy default, Codemem runs a local BERT model (no API key needed). To use a remote provider:\n\n```bash\n# Ollama (local server)\nexport CODEMEM_EMBED_PROVIDER=ollama\n\n# OpenAI-compatible (works with Voyage AI, Together, Azure, etc.)\nexport CODEMEM_EMBED_PROVIDER=openai\nexport CODEMEM_EMBED_URL=https://api.voyageai.com/v1\nexport CODEMEM_EMBED_MODEL=voyage-3\nexport CODEMEM_EMBED_API_KEY=pa-...\n```\n\n### Observation compression\n\nOptionally compress raw tool observations via LLM before storage:\n\n```bash\nexport CODEMEM_COMPRESS_PROVIDER=ollama   # or openai, anthropic\n```\n\n### Persistent config\n\nScoring weights, vector/graph tuning, and storage settings persist in `~/.codemem/config.toml`. Partial configs merge with defaults.\n\n## MCP Tools\n\n26 tools organized by category. See [MCP Tools Reference](docs/mcp-tools.md) for full API documentation.\n\n| Category | Tools |\n|----------|-------|\n| Memory CRUD (7) | `store_memory`, `recall`, `delete_memory`, `associate_memories`, `refine_memory`, `split_memory`, `merge_memories` |\n| Graph \u0026 Structure (6) | `graph_traverse`, `summary_tree`, `codemem_status`, `search_code`, `get_symbol_info`, `get_symbol_graph` |\n| Graph Analysis (5) | `find_important_nodes`, `find_related_groups`, `get_cross_repo`, `get_node_memories`, `node_coverage` |\n| Consolidation \u0026 Patterns (3) | `consolidate`, `detect_patterns`, `get_decision_chain` |\n| Namespace (3) | `list_namespaces`, `namespace_stats`, `delete_namespace` |\n| Session \u0026 Context (2) | `session_checkpoint`, `session_context` |\n\n## CLI\n\n```\ncodemem init          # Initialize project (model + hooks + MCP)\ncodemem search        # Search memories\ncodemem stats         # Database statistics\ncodemem serve         # Start MCP server (JSON-RPC stdio)\ncodemem index         # Index codebase with tree-sitter\ncodemem consolidate   # Run consolidation cycles\ncodemem analyze       # Full pipeline: index + enrich + PageRank + clusters\ncodemem watch         # Real-time file watcher\ncodemem export/import # Backup and restore (JSONL, JSON, CSV, Markdown)\ncodemem sessions      # Session management (list, start, end)\ncodemem doctor        # Health checks on installation\ncodemem config        # Get/set configuration values\ncodemem migrate       # Run pending schema migrations\n```\n\nSee [CLI Reference](docs/cli-reference.md) for full usage.\n\n## Performance\n\n| Operation | Target |\n|-----------|--------|\n| HNSW search k=10 (100K vectors) | \u003c 2ms |\n| Embedding (single sentence) | \u003c 50ms |\n| Embedding (cache hit) | \u003c 0.01ms |\n| Graph BFS depth=2 | \u003c 1ms |\n| Hook ingest (Read) | \u003c 200ms |\n\n## Documentation\n\n- [Architecture](docs/architecture.md) -- System design, data flow diagrams, storage schema\n- [Index \u0026 Enrich Pipeline](docs/pipeline.md) -- Step-by-step data flow from source files to annotated graph\n- [MCP Tools Reference](docs/mcp-tools.md) -- All 26 tools with parameters and examples\n- [CLI Reference](docs/cli-reference.md) -- All 19 commands\n- [Comparison](docs/comparison.md) -- vs Mem0, Zep/Graphiti, Letta, claude-mem, and more\n\n## Building from Source\n\n```bash\ngit clone https://github.com/cogniplex/codemem.git\ncd codemem\ncargo build --release          # Optimized binary at target/release/codemem\ncargo test --workspace         # Run all tests\ncargo bench                    # Criterion benchmarks\n```\n\n6-crate Cargo workspace. See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.\n\n## Research and Inspirations\n\nCodemem builds on ideas from several research papers, blog posts, and open-source projects.\n\n\u003cdetails\u003e\n\u003csummary\u003ePapers\u003c/summary\u003e\n\n| Paper | Venue | Key Contribution |\n|-------|-------|-----------------|\n| [HippoRAG](https://arxiv.org/abs/2405.14831) | NeurIPS 2024 | Neurobiologically-inspired long-term memory using LLMs + knowledge graphs + Personalized PageRank. Up to 20% improvement on multi-hop QA. |\n| [From RAG to Memory](https://arxiv.org/abs/2502.14802) | ICML 2025 | Non-parametric continual learning for LLMs (HippoRAG 2). 7% improvement in associative memory tasks. |\n| [A-MEM](https://arxiv.org/abs/2502.12110) | 2025 | Zettelkasten-inspired agentic memory with dynamic indexing, linking, and memory evolution. |\n| [MemGPT](https://arxiv.org/abs/2310.08560) | ICLR 2024 | OS-inspired hierarchical memory tiers for LLMs -- self-editing memory via function calls. |\n| [MELODI](https://arxiv.org/abs/2410.03156) | Google DeepMind 2024 | Hierarchical short-term + long-term memory compression. 8x memory footprint reduction. |\n| [ReadAgent](https://arxiv.org/abs/2402.09727) | Google DeepMind 2024 | Human-inspired reading agent with episodic gist memories for 20x context extension. |\n| [LoCoMo](https://arxiv.org/abs/2402.17753) | ACL 2024 | Benchmark for evaluating very long-term conversational memory (300-turn, 9K-token conversations). |\n| [Mem0](https://arxiv.org/abs/2504.19413) | 2025 | Production-ready AI agents with scalable long-term memory. 26% accuracy improvement over OpenAI Memory. |\n| [Zep](https://arxiv.org/abs/2501.13956) | 2025 | Temporal knowledge graph architecture for agent memory with bi-temporal data model. |\n| [Memory in the Age of AI Agents](https://arxiv.org/abs/2512.13564) | Survey 2024 | Comprehensive taxonomy of agent memory: factual, experiential, working memory. |\n| [AriGraph](https://arxiv.org/abs/2407.04363) | 2024 | Episodic + semantic memory in knowledge graphs for LLM agent exploration. |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBlog posts and techniques\u003c/summary\u003e\n\n- [Contextual Retrieval](https://www.anthropic.com/news/contextual-retrieval) (Anthropic, 2024) -- Prepending chunk-specific context before embedding reduces failed retrievals by 49%. Codemem adapts this as template-based contextual enrichment using metadata + graph relationships.\n- [Contextual Embeddings Cookbook](https://platform.claude.com/cookbook/capabilities-contextual-embeddings-guide) (Anthropic) -- Implementation guide for contextual embeddings with prompt caching.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eOpen-source projects\u003c/summary\u003e\n\n- [AutoMem](https://automem.ai/) -- Graph-vector hybrid memory achieving 90.53% on LoCoMo. Direct inspiration for Codemem's hybrid scoring and consolidation cycles.\n- [claude-mem](https://github.com/thedotmack/claude-mem) -- Persistent memory compression via Claude Agent SDK. Inspired lifecycle hooks and observation compression.\n- [Mem0](https://github.com/mem0ai/mem0) -- Production memory layer for AI (47K+ stars). Informed memory type design.\n- [Zep/Graphiti](https://github.com/getzep/graphiti) -- Temporal knowledge graph engine. Inspired graph persistence model.\n- [Letta](https://github.com/letta-ai/letta) (MemGPT) -- Stateful AI agents with self-editing memory.\n- [Cognee](https://github.com/topoteretes/cognee) -- Knowledge graph memory via triplet extraction.\n- [claude-context](https://github.com/zilliztech/claude-context) -- AST-aware code search via MCP (by Zilliz).\n\n\u003c/details\u003e\n\nSee [docs/comparison.md](docs/comparison.md) for detailed feature comparisons.\n\n## License\n\n[Apache 2.0](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogniplex%2Fcodemem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcogniplex%2Fcodemem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcogniplex%2Fcodemem/lists"}