Engram Context Continuum

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.

The Problem

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.

Quick Install

npx engram-cc

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

Canonical MCP Install Command

For assistants that self-install MCP servers from npm, the canonical EngramCC command is:

npx --yes --package=@morous-dev/engram-cc -- engramcc-mcp

Equivalent npm exec form:

npm exec --yes --package=@morous-dev/engram-cc -- engramcc-mcp

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

Supported Assistants

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

How It Works

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

Session Lifecycle

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

Tiered Context Injection

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 recall tool — zero token waste on stale context

Memory Architecture

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

Local SLM Pipeline

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.

Stable Project Identity

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

Data Locations

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

MCP Tools

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 |

Configuration

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"

Benchmarks

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.

Verified Benchmark Runs

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

What Those Results Mean

Handoff Quality

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

Real-Data Retrieval / Retention

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.

SLM Adversarial Robustness

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.

SLM Scale Stability

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.

Cross-Tier Compaction Retention

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%

Multi-Compaction Marathon

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

Important Caveats

• tier3 still 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 A11 failure is no longer the current state and should not be cited as a live weakness.
• benchmark/test-160k-real.mjs was not rerun after the carry-forward patch, so its older numbers are intentionally omitted from the headline claims here.

Bottom-Line Read

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.

Development

npm run build       # Compile TypeScript → build/
npm run typecheck   # Type check without emit
npm run clean       # Remove build/
npm run setup       # Build + run setup CLI

Runtime requirements:

• Node.js >= 18 (all hooks, MCP server, setup CLI)

Contributor note:

• See ADAPTER-AUTHORING.md before adding or changing assistant adapters. It defines the allowed touch points, capability rules, storage rules, and current portability boundaries.

Platform Support

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 |

Troubleshooting: better-sqlite3 build failure

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

Linux (Debian/Ubuntu):

sudo apt install build-essential python3

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

Troubleshooting: Local SLM tier not available

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:

• tier3 Llama 3.2 3B: ~4 GB RAM
• tier3b Qwen3.5 4B: ~3.5 GB RAM
• tier3c Gemma 3 4B: ~3 GB RAM

Troubleshooting: Vector store not active

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"

Project Structure

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

License

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.