Engram Cc

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 .

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 instead. The npx --package ... form above is for assistants that install EngramCC directly from npm without running project-local setup first.

---

Supported Assistants

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

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

---

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:

Models are stored in a shared directory chosen during engramcc setup and saved in /.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/ │ └── .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

/Engram Context Continuum/models/ └── .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:

---

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

What Those Results Mean

Handoff Quality

npm run test:quality exercises the full path from session events to next-session context injection.

|