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

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

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"