Universal AI session memory substrate. One install. Every AI coding assistant. Persistent context across sessions, folder renames, and tool switches.
In neuroscience, an engram is the physical trace a memory leaves in the brain. EngramCC does the same for AI — a local memory substrate that persists what your AI assistant learned, decided, and did, so the next session picks up exactly where the last one left off.
Every AI coding session starts from zero. The assistant re-reads files it read yesterday, re-learns conventions it already knows, re-asks questions you already answered. Context compaction silently erases the session mid-work. Switch tools and all memory is gone.
EngramCC solves this at the infrastructure level — not by prompting harder, but by building a persistent memory layer that runs underneath any AI assistant.
npx engram-ccRun it from the project root you want ECC to manage, or pass --project-dir <path>.
The setup CLI detects your hardware, prepares a project-local .engram-cc/ workspace, asks for a shared models directory, and generates assistant hook/MCP snippets under .engram-cc/assistant-configs/. No user-home config is modified.
For assistants that self-install MCP servers from npm, the canonical EngramCC command is:
npx --yes --package=@morous-dev/engram-cc -- engramcc-mcpEquivalent npm exec form:
npm exec --yes --package=@morous-dev/engram-cc -- engramcc-mcpAssistants should not guess npx @morous-dev/engram-cc mcp. Use the explicit package/bin form above.
For project-local ECC setup, the generated snippets under .engram-cc/assistant-configs/
intentionally use node <project-local build/mcp/server.js> instead. The npx --package ...
form above is for assistants that install EngramCC directly from npm without running project-local setup first.
| Assistant | Hook support | MCP support |
|---|---|---|
| Claude Code | Full lifecycle hooks | recall / search / recent / graph_query |
| Gemini CLI | Full lifecycle hooks | recall / search / recent / graph_query |
| VS Code Copilot | — | recall / search / recent / graph_query |
| Codex CLI | Native hooks (session_start, pre_tool_use, stop) + transcript-exact user_prompt_submit / post_tool_use + synthesized pre_compact |
recall / search / recent / graph_query |
| Kilo CLI | Wrapper-assisted only; native hooks not verified | recall / search / recent / graph_query |
| OpenCode | Full lifecycle hooks | recall / search / recent / graph_query |
| Cursor | — | recall / search / recent / graph_query |
On Windows, generated hook snippets call src/hooks/hook-runner.mjs so assistant and
project env vars are injected without brittle cmd /C quoting.
Codex-specific note: the exact prompt/tool bridge reads Codex's own session JSONL under
CODEX_HOME / ~/.codex/sessions/, but ECC still writes its state only into the project-local
.engram-cc/ directory. Because Codex does not expose a true prompt-submit injection hook,
startup context also includes a Codex turn policy that steers the assistant toward EngramCC
MCP memory on user turns when earlier context may have compacted out.
Kilo-specific note: current verified support is MCP plus the ekilo wrapper flow for
session-start / session-stop continuity. Kilo has an open request for native lifecycle hooks,
so ECC does not claim native Kilo hook parity yet.
EngramCC runs as session middleware — lifecycle hooks capture what happens during a session, a local SLM synthesizes memory offline at session end, and an MCP server serves pre-digested context to any connected assistant.
┌─────────────────────────────────────────────────────────────────┐
│ Your AI Coding Session │
│ │
│ UserPromptSubmit → PostToolUse → PreCompact → Stop │
│ │ │ │ │ │
│ └───────────────┴──────────────┴──────────┘ │
│ │ │
│ SQLite event DB │
│ │ │
│ ┌───────────┴───────────┐ │
│ │ Local SLM Archivist │ │
│ │ (no API calls, 100% │ │
│ │ offline synthesis) │ │
│ └───────────┬───────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ │ │ │ │
│ YAML handoff Knowledge graph Vector store │
│ (hot resume) (BFS traversal) (semantic search) │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ MCP server │
│ (recall / search / recent │
│ / graph_query) │
└─────────────────────────────────────────────────────────────────┘
↑ ↓
SessionStart hook Next session
injects context picks up here
| Hook | When | What it does |
|---|---|---|
UserPromptSubmit |
User sends a message | Captures intent and decision signals |
PostToolUse |
Any tool completes | Captures file ops, errors, tool results |
PreCompact |
Context nears limit | Snapshots session state before erasure |
SessionStart |
Session opens | Injects hot handoff or cold summary + MCP pointer |
Stop |
Session closes | SLM synthesis → handoff YAML + graph + vector store |
EngramCC injects context surgically, not blindly:
- Hot resume (< 30 min since last session): full handoff XML injected — complete working context, decisions, modified files, errors
- Cold start: one-sentence headline + pointer to MCP
recalltool — zero token waste on stale context
| Layer | Storage | Contents | Lifespan |
|---|---|---|---|
| Working | YAML | Preferences, conventions, persistent decisions | Cross-session |
| Episodic | SQLite + FTS5 | All session events, full-text searchable | Per-project |
| Semantic | SQLite graph | File/decision knowledge graph, BFS traversal | Per-project |
| Procedural | sqlite-vec | Embedding-indexed high-value events | Per-project |
EngramCC synthesizes session memory using local models first — zero external API calls for its own compaction, handoff, and retrieval support.
The setup CLI detects your hardware and selects the best available tier:
| Tier | Model | RAM needed | What it does |
|---|---|---|---|
| 1 | Rule-based | 0 | Always-on heuristic extraction |
| 2 | MiniLM-L6-v2 ONNX | ~400 MB | Embeddings via @huggingface/transformers |
| 3 | Llama 3.2 3B Q5_K_M | ~4 GB | Primary local synthesis tier |
| 3b | Qwen3.5 4B Q4_K_M | ~3.5 GB | Alternate synthesis tier, strong multilingual/coding performance |
| 3c | Gemma 3 4B QAT Q4_0 | ~3 GB | Alternate synthesis tier, strong structured reasoning |
| 4 | Ollama / LM Studio / Groq | user-provided | External HTTP provider |
Models are stored in a shared directory chosen during engramcc setup and saved in <projectDir>/.engram-cc/config.json. Tiers auto-cascade: if no Tier 3 model is available, Tier 2 runs; if Tier 2 is unavailable, Tier 1 runs. Core memory capture is never blocked.
EngramCC tracks projects by a stable UUID stored in .ecc-id — not by folder path. This means:
- Rename the project folder → same history
- Move it to a different drive → same history
- Re-clone from git → same history (falls back to git root commit hash)
Resolution order: .ecc-id file → git root commit hash → fresh UUIDv4 (written once, never regenerated).
<projectDir>/.engram-cc/
├── sessions/
│ └── <uuid>.db ← SQLite DB per project (all memory tiers)
├── assistant-configs/ ← Local hook/MCP snippets per assistant
├── config.json ← Project config, including shared models path
├── handoff.yaml ← Session handoff (hot resume data)
└── working.yaml ← Cross-session working memory
<chosenModelsRoot>/Engram Context Continuum/models/
└── <model>.gguf ← Shared GGUF models reused across projects
All data is local. No network calls for core operation. No credentials, tokens, or API keys required.
When connected via MCP, any assistant can query EngramCC directly:
| Tool | Purpose |
|---|---|
recall |
Full session context: handoff + working memory |
search |
FTS5 full-text search over all session events |
recent |
Most recent N events, filterable by category |
graph_query |
BFS traversal of the knowledge graph |
Override compression tier or external provider in plugin-config.yaml:
# Force a specific compression tier (default: auto)
compression:
tier: "tier3b"
# Tier 4 only
external:
provider: "ollama"
model: "phi4-mini"
base_url: "http://localhost:11434"The numbers below were verified against the current repo state on March 14, 2026 after the carry-forward compaction fix. They reflect what was actually run, not historical bests.
| Command | What it measures | Current result |
|---|---|---|
npm run build |
TypeScript compile integrity | ✅ PASS |
node benchmark/test-session-db.mjs |
Session DB, archive, resume-chain, carry-forward regressions | ✅ 53/53 |
npm run test:quality |
End-to-end handoff quality across S1/S2/S3 | ✅ 20/20 |
node benchmark/test-hook-portability.mjs |
Cross-assistant hook env and startup portability | ✅ 14/14 |
node benchmark/test-codex-adapter.mjs |
Codex transcript sync + trigger + stop regressions | ✅ 29/29 |
npm run test:brutal:quick |
Real-data extraction calibration (WildChat + SWE-bench) | ✅ PASS |
npm run test:lifecycle:quick |
100-cycle real-data lifecycle / archive retention observation | ✅ PASS |
node benchmark/test-adversarial.mjs --model llama3.2-3b |
Hostile SLM inputs A1–A11 | ✅ 11/11 |
node benchmark/test-adversarial.mjs --model qwen |
Hostile SLM inputs A1–A11 | ✅ 11/11 |
node benchmark/test-adversarial.mjs --model gemma3-4b |
Hostile SLM inputs A1–A11 | ✅ 11/11 |
node benchmark/test-tier-comparison.mjs |
Cross-tier compaction retention (4→20 cycles) | ✅ 38/38 on tier3, tier3b, tier3c |
node benchmark/test-scale.mjs |
Prompt-length stability | ✅ Llama 16/16 · Qwen 15/16 |
node benchmark/test-compaction-marathon.mjs |
Multi-compaction memory retention | ✅ 53/53 |
node benchmark/test-diffmode.mjs |
Grammar-constrained JSON output | ✅ PASS for Llama 3.2 3B + Qwen3.5 4B |
npm run test:quality exercises the full path from session events to next-session context injection.
| Scenario | Assertions | Result |
|---|---|---|
| S1 — Initial session | 6/6 | ✅ |
| S2 — Hot resume | 5/5 | ✅ |
| S3 — Marathon / cold start | 9/9 | ✅ |
Total: 20/20
npm run test:brutal:quick and npm run test:lifecycle:quick use public external datasets:
- WildChat-1M coding conversations
- SWE-bench GitHub issue statements
Current verified observations:
- extraction brutal calibration: PASS
- adversarial extractor traps: 15/15
- chain phase
extract → store → search → snapshot: PASS - lifecycle checkpoints: 100% / 80% / 80% / 100% FTS5 recall at cycles 25 / 50 / 75 / 100
- cycle 100 recall by source: WildChat 5/7 (71%), SWE-bench 13/13 (100%)
The two misses in the lifecycle run were low-signal terms (nothing, creator), not archive corruption.
The adversarial suite is the hardest accuracy benchmark in the repo: code walls, stack traces, multilingual sessions, flip-flop errors, domain jargon, buried current tasks, and multi-compaction chains.
Current verified scores:
| Model | Score |
|---|---|
| Llama 3.2 3B Q5_K_M | 11/11 |
| Qwen3.5 4B Q4_K_M | 11/11 |
| Gemma 3 4B QAT Q4_0 | 11/11 |
This matters because A11 used to be the real gap. It now passes after the deterministic carry-forward state was added to the compaction chain.
node benchmark/test-scale.mjs probes prompt growth from 128 to 985 words.
| Model | Result |
|---|---|
| Llama 3.2 3B | 16/16 |
| Qwen3.5 4B | 15/16 |
Current caveat:
- Qwen 4B had one miss at S4 (985 words) on the no-hallucination check.
node benchmark/test-tier-comparison.mjs runs the same 4→20 cycle compaction stress test across all three production GGUF tiers.
| Tier | Result |
|---|---|
tier3 — Llama 3.2 3B |
38/38 |
tier3b — Qwen3.5 4B |
38/38 |
tier3c — Gemma 3 4B |
38/38 |
At the time of this README update, the verified token savings vs raw snapshot were:
tier3: 24–26%tier3b: 16–23%tier3c: 20–28%
node benchmark/test-compaction-marathon.mjs simulates long-running sessions across 4, 8, 12, 16, and 20 compaction cycles.
Current verified result:
- 53/53 assertions passed
- all anchor facts survived through 20 compaction cycles
tier3still occasionally falls back from grammar-constrained diff-mode to prose in some runs. Correctness stayed green in the verified suites above, but the fallback still exists.- Qwen 4B is strong overall, but its current scale run is 15/16, not perfect.
- The old
A11failure is no longer the current state and should not be cited as a live weakness. benchmark/test-160k-real.mjswas not rerun after the carry-forward patch, so its older numbers are intentionally omitted from the headline claims here.
ECC is now strong in the places that matter most for a CLI memory substrate:
- real-data extraction and retention
- end-to-end handoff quality
- chained compaction continuity
- cross-tier SLM robustness
The retrieval layer remains the long-term safety net. The SLM layer is now good enough to carry forward session state across compactions without the old A11 collapse.
npm run build # Compile TypeScript → build/
npm run typecheck # Type check without emit
npm run clean # Remove build/
npm run setup # Build + run setup CLIRuntime requirements:
- Node.js >= 18 (all hooks, MCP server, setup CLI)
Contributor note:
- See
ADAPTER-AUTHORING.mdbefore adding or changing assistant adapters. It defines the allowed touch points, capability rules, storage rules, and current portability boundaries.
EngramCC runs on Windows, macOS, and Linux (x64 and ARM64).
| Dependency | Type | Platform coverage |
|---|---|---|
| better-sqlite3 | Native C++ addon | Prebuilt binaries for all major platforms + Node versions |
| node-llama-cpp (Tier 3) | Native addon | 13 prebuilt variants: Windows/macOS/Linux × x64/ARM64 × CPU/CUDA/Vulkan/Metal |
| sqlite-vec (Vector store) | Native addon | Prebuilt for Windows x64, macOS x64/ARM64, Linux x64/ARM64 |
| @huggingface/transformers (Tier 2) | Pure JS + WASM | Universal — no native code |
| All other deps | Pure JS | Universal |
better-sqlite3 is the only hard dependency that requires native compilation. It ships with prebuilt binaries for common platform + Node version combinations. If the prebuilt doesn't match your setup, npm falls back to compiling from source, which requires:
Windows:
npm install --global windows-build-tools
# or install Visual Studio Build Tools with "Desktop development with C++"macOS:
xcode-select --installLinux (Debian/Ubuntu):
sudo apt install build-essential python3Linux (Fedora/RHEL):
sudo dnf groupinstall "Development Tools"If npm install fails with gyp ERR! or node-pre-gyp errors, installing the build tools above and re-running npm install will fix it.
The local synthesis tiers require GGUF models in the shared models directory configured for the project. If no supported Tier 3 model is present, EngramCC falls back to Tier 2 (embeddings) or Tier 1 (rule-based).
Examples:
engramcc --tier=tier3 --project-dir <project> --models-dir <shared-models-dir>
engramcc --tier=tier3b --project-dir <project> --models-dir <shared-models-dir>
engramcc --tier=tier3c --project-dir <project> --models-dir <shared-models-dir>Approximate runtime requirements:
tier3Llama 3.2 3B: ~4 GB RAMtier3bQwen3.5 4B: ~3.5 GB RAMtier3cGemma 3 4B: ~3 GB RAM
The vector store uses sqlite-vec, which is an optional dependency. If it fails to load, EngramCC operates normally without vector search — all other memory tiers (episodic, semantic, working) are unaffected. To verify:
node -e "require('sqlite-vec')" 2>&1 || echo "sqlite-vec not available — vector search disabled"src/
├── hooks/ ← Lifecycle hook entry points (.mjs + .ts)
├── adapters/ ← Per-assistant registration (Claude Code, Gemini CLI, etc.)
├── session/ ← SQLite event capture, schema, FTS5
├── memory/ ← Working YAML, knowledge graph, vector store
├── handoff/ ← Session handoff writer, reader, dedup
├── compression/ ← SLM pipeline: tier selection, ONNX, node-llama-cpp
├── mcp/ ← MCP stdio server
├── tokenization/ ← Token budget auditor
├── project-id.ts ← Stable project UUID resolution
└── cli/
├── setup.ts ← Install CLI: hardware detection, adapter registration
└── download-model.ts ← GGUF model downloader
Open source: AGPL-3.0 — free to use, modify, and distribute as long as derivative works are also open source under AGPL-3.0.
Commercial: A proprietary license is available for teams that need to use EngramCC in closed-source products or hosted services without AGPL obligations. See COMMERCIAL-LICENSE.md for details.