A standalone Rust memory engine for AI coding assistants. Single binary, zero runtime deps.

Codemem 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 indexers.

# Shell (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/cogniplex/codemem/main/install.sh | sh

# Homebrew
brew install cogniplex/tap/codemem

# Cargo
cargo install codemem

Or download a prebuilt binary from Releases.

cd your-project
codemem init

Downloads 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.

Codemem now automatically captures context, injects prior knowledge at session start, and provides 26 MCP tools to your assistant.

Run 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:

codemem analyze

Then 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:

claude --agent code-mapper

See Index & Enrich Pipeline for what happens under the hood.

SCIP (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.

Install the indexer for your language:

Codemem 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.

Configure via ~/.codemem/config.toml:

[scip]
enabled = true                    # Master switch (default: true)
auto_detect_indexers = true       # Check PATH for available indexers
cache_index = true                # Cache .scip files between runs
cache_ttl_hours = 24              # Re-index if cache older than this
create_external_nodes = true      # Create ext: nodes for dependency symbols
store_docs_as_memories = true     # Attach hover docs as memories
hierarchical_containment = true   # Build nested containment tree
collapse_intra_class_edges = true # Fold intra-class calls into parent metadata

[scip.fan_out_limits]
module = 200     # Modules can be widely imported
class = 50       # Classes referenced moderately
function = 30    # Functions and methods less so
method = 30

# Override auto-detected indexer commands per language:
# [scip.indexers]
# rust = "rust-analyzer scip ."
# typescript = "scip-typescript index --infer-tsconfig"

No 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.

• 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)
• SCIP integration -- Compiler-grade cross-references via SCIP 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
• 26 MCP tools -- Memory CRUD, self-editing (refine/split/merge), graph traversal, code search, consolidation, impact analysis, session context, pattern detection over JSON-RPC
• 4 lifecycle hooks -- Automatic context injection (SessionStart), prompt capture (UserPromptSubmit), observation capture (PostToolUse), and session summaries (Stop)
• 8-component hybrid scoring -- Vector similarity, graph strength, BM25 token overlap, temporal alignment, tag matching, importance, confidence, and recency
• 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)
• Contextual embeddings -- Metadata and graph context enriched before embedding for higher recall precision
• Pluggable embeddings -- Candle (local BERT, default), Ollama, or any OpenAI-compatible API
• Cross-session intelligence -- Pattern detection, file hotspot tracking, decision chains, and session continuity
• Memory consolidation -- 5 neuroscience-inspired cycles: Decay (power-law), Creative/REM (semantic KNN), Cluster (cosine + union-find), Summarize (LLM-powered), Forget
• Self-editing memory -- Refine, split, and merge memories with full provenance tracking via temporal graph edges
• Operational metrics -- Per-tool latency percentiles (p50/p95/p99), call counters, and gauges via codemem_status tool
• Real-time file watching -- notify-based watcher with <50ms debounce and .gitignore support
• Persistent config -- TOML-based configuration at ~/.codemem/config.toml
• Production hardened -- Zero .unwrap() in production code, safe concurrency, versioned schema migrations

Although codemem is designed for code exploration memory (not generic conversational recall), it scores competitively on standard memory benchmarks:

Both 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.

See bench/locomo/ and bench/longmemeval/ for methodology, reproduction steps, and detailed breakdowns.

graph LR
    A[AI Assistant] -->|SessionStart hook| B[codemem context]
    A -->|PostToolUse hooks| C[codemem ingest]
    A -->|Stop hook| E[codemem summarize]
    A -->|MCP tools| D[codemem serve]
    B -->|Inject context| A
    C --> F[Storage + Vector + Graph]
    D --> F
    F -->|Recall| A

1. Passively captures what your AI reads, searches, and edits via lifecycle hooks
2. Actively recalls relevant context via MCP tools with 8-component hybrid scoring
3. Injects context at session start so your assistant picks up where it left off

Weights are configurable via codemem config set scoring.<key> <value> and persist in ~/.codemem/config.toml.

By default, Codemem runs a local BERT model (no API key needed). To use a remote provider:

# Ollama (local server)
export CODEMEM_EMBED_PROVIDER=ollama

# OpenAI-compatible (works with Voyage AI, Together, Azure, etc.)
export CODEMEM_EMBED_PROVIDER=openai
export CODEMEM_EMBED_URL=https://api.voyageai.com/v1
export CODEMEM_EMBED_MODEL=voyage-3
export CODEMEM_EMBED_API_KEY=pa-...

Optionally compress raw tool observations via LLM before storage:

export CODEMEM_COMPRESS_PROVIDER=ollama   # or openai, anthropic

Scoring weights, vector/graph tuning, and storage settings persist in ~/.codemem/config.toml. Partial configs merge with defaults.

26 tools organized by category. See MCP Tools Reference for full API documentation.

codemem init          # Initialize project (model + hooks + MCP)
codemem search        # Search memories
codemem stats         # Database statistics
codemem serve         # Start MCP server (JSON-RPC stdio)
codemem index         # Index codebase with tree-sitter
codemem consolidate   # Run consolidation cycles
codemem analyze       # Full pipeline: index + enrich + PageRank + clusters
codemem watch         # Real-time file watcher
codemem export/import # Backup and restore (JSONL, JSON, CSV, Markdown)
codemem sessions      # Session management (list, start, end)
codemem doctor        # Health checks on installation
codemem config        # Get/set configuration values
codemem migrate       # Run pending schema migrations

See CLI Reference for full usage.

• Architecture -- System design, data flow diagrams, storage schema
• Index & Enrich Pipeline -- Step-by-step data flow from source files to annotated graph
• MCP Tools Reference -- All 26 tools with parameters and examples
• CLI Reference -- All 19 commands
• Comparison -- vs Mem0, Zep/Graphiti, Letta, claude-mem, and more

git clone https://github.com/cogniplex/codemem.git
cd codemem
cargo build --release          # Optimized binary at target/release/codemem
cargo test --workspace         # Run all tests
cargo bench                    # Criterion benchmarks

6-crate Cargo workspace. See CONTRIBUTING.md for development guidelines.

Codemem builds on ideas from several research papers, blog posts, and open-source projects.

See docs/comparison.md for detailed feature comparisons.

Apache 2.0