Codemem

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.

Quick Start

Install

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

Initialize

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.

That's it

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

Map your codebase (optional)

Run the full analysis pipeline -- indexes your codebase with tree-sitter, runs 14 enrichment analyses (git history, complexity, security, architecture, etc.), 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.

Key Features

• 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)
• 32 MCP tools -- Memory CRUD, self-editing (refine/split/merge), graph traversal, code search, enrichment pipeline (14 enrichment types), 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

Benchmarks

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.

How It Works

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

Hybrid scoring

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

Configuration

Embedding providers

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

Observation compression

Optionally compress raw tool observations via LLM before storage:

export CODEMEM_COMPRESS_PROVIDER=ollama   # or openai, anthropic

Persistent config

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

MCP Tools

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

CLI

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.

Performance

Documentation

• 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 32 tools with parameters and examples
• CLI Reference -- All 19 commands
• Comparison -- vs Mem0, Zep/Graphiti, Letta, claude-mem, and more

Building from Source

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.

Research and Inspirations

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

• 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.
• Contextual Embeddings Cookbook (Anthropic) -- Implementation guide for contextual embeddings with prompt caching.

• AutoMem -- Graph-vector hybrid memory achieving 90.53% on LoCoMo. Direct inspiration for Codemem's hybrid scoring and consolidation cycles.
• claude-mem -- Persistent memory compression via Claude Agent SDK. Inspired lifecycle hooks and observation compression.
• Mem0 -- Production memory layer for AI (47K+ stars). Informed memory type design.
• Zep/Graphiti -- Temporal knowledge graph engine. Inspired graph persistence model.
• Letta (MemGPT) -- Stateful AI agents with self-editing memory.
• Cognee -- Knowledge graph memory via triplet extraction.
• claude-context -- AST-aware code search via MCP (by Zilliz).

See docs/comparison.md for detailed feature comparisons.

License

Apache 2.0