Claude Engram

Persistent memory for AI coding assistants. Auto-tracks mistakes, decisions, and context. Retrieves the right memory at the right time using hybrid search (keyword + vector + reranking). Works with any MCP-compatible tool.

Benchmarks

Retrieval benchmarks

Retrieval-only (recall@k). These measure whether the right memory is found in the top results — not end-to-end QA with answer generation and judge scoring, which is what the published LongMemEval leaderboard measures. MemPalace comparison uses the same retrieval-only methodology (their raw mode, no LLM reranking, top_k=10).

Reproduce: python tests/bench_longmemeval.py, bench_locomo.py, bench_convomem.py

Integration benchmarks

These test what the product actually does — not just search retrieval.

Reproduce: python tests/bench_integration.py (runs from tests/ directory)

Comparison with MemPalace

Different approaches. MemPalace is a conversation archive with a spatial palace structure, knowledge graph, AAAK compression, and specialist agents. Claude Engram is live-capture: hooks into the coding lifecycle to auto-track mistakes, decisions, and context as you work. Comparable retrieval, different strengths.

Compatibility

With Claude Code, hooks auto-capture mistakes, decisions, edits, test results, and session state. With other tools, you use the MCP tools manually — the memory system, hybrid search, archiving, and scoring all work the same.

Features

• Hybrid search — keyword + AllMiniLM vector + reranking. No ChromaDB dependency.
• Auto-tracks mistakes from any failed tool. Warns before editing the same file.
• Auto-captures decisions from prompts ("let's use X") via semantic + regex scoring.
• Detects edit loops when the same file is edited 3+ times.
• Survives compaction — auto-checkpoint before, re-inject rules/mistakes after.
• Tiered storage — hot (fast) + archive (cold, searchable, restorable). Rules and mistakes never archive.
• Scored injection — top 3 memories by file match, tags, recency, importance before every edit.
• Multi-project — memories scoped per sub-project. Workspace rules cascade down.

Install

git clone https://github.com/20alexl/claude-engram.git
cd claude-engram
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
 
pip install -e .                # Core
pip install -e ".[semantic]"    # + AllMiniLM for vector search and decision capture
 
python install.py               # Configure hooks + MCP server

Per-Project Setup

python install.py --setup /path/to/your/project

Or copy .mcp.json and CLAUDE.md to your project root.

Mid-Project Adoption

Already deep in a project? Install normally, then tell your AI to dump what it knows:

Save everything you know about this project:
- memory(add_rule) for each project convention
- memory(remember) for key facts about the architecture
- work(log_decision) for decisions we've made and why

Ollama (Optional)

Only needed for scout_search, scout_analyze, and LLM-based convention checking. Everything else works without it.

ollama pull gemma3:4b                    # or gemma3:12b for better semantic search
export CLAUDE_ENGRAM_MODEL="gemma3:4b"   # Linux/Mac

Configuration

Documentation

Library Book — design, internals, full usage guide, API reference, gotchas.

License

MIT