{
  "markdown": "# Engram Context Continuum\n\n[![Support EngramCC](https://img.shields.io/badge/Support_EngramCC-Pay_What_You_Want-yellow?style=for-the-badge)](https://morous-dev.lemonsqueezy.com/checkout/buy/d10e8ab1-7616-433b-9c69-4ccb13edbdc0)\n\n**Universal AI session memory substrate.** One install. Every AI coding assistant. Persistent context across sessions, folder renames, and tool switches.\n\n> *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.*\n\n---\n\n## The Problem\n\nEvery 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.\n\nEngramCC solves this at the infrastructure level — not by prompting harder, but by building a persistent memory layer that runs underneath any AI assistant.\n\n---\n\n## Quick Install\n\n```bash\nnpx engram-cc\n```\n\nRun it from the project root you want ECC to manage, or pass `--project-dir <path>`.\n\nThe 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.\n\n### Canonical MCP Install Command\n\nFor assistants that self-install MCP servers from npm, the canonical EngramCC command is:\n\n```bash\nnpx --yes --package=@morous-dev/engram-cc -- engramcc-mcp\n```\n\nEquivalent `npm exec` form:\n\n```bash\nnpm exec --yes --package=@morous-dev/engram-cc -- engramcc-mcp\n```\n\nAssistants should not guess `npx @morous-dev/engram-cc mcp`. Use the explicit package/bin form above.\n\nFor project-local ECC setup, the generated snippets under `.engram-cc/assistant-configs/`\nintentionally use `node <project-local build/mcp/server.js>` instead. The `npx --package ...`\nform above is for assistants that install EngramCC directly from npm without running project-local setup first.\n\n---\n\n## Supported Assistants\n\n| Assistant | Hook support | MCP support |\n|---|---|---|\n| Claude Code | Full lifecycle hooks | recall / search / recent / graph_query |\n| Gemini CLI | Full lifecycle hooks | recall / search / recent / graph_query |\n| VS Code Copilot | — | recall / search / recent / graph_query |\n| 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 |\n| Kilo CLI | Wrapper-assisted only; native hooks not verified | recall / search / recent / graph_query |\n| OpenCode | Full lifecycle hooks | recall / search / recent / graph_query |\n| Cursor | — | recall / search / recent / graph_query |\n\nOn Windows, generated hook snippets call `src/hooks/hook-runner.mjs` so assistant and\nproject env vars are injected without brittle `cmd /C` quoting.\n\nCodex-specific note: the exact prompt/tool bridge reads Codex's own session JSONL under\n`CODEX_HOME` / `~/.codex/sessions/`, but ECC still writes its state only into the project-local\n`.engram-cc/` directory. Because Codex does not expose a true prompt-submit injection hook,\nstartup context also includes a Codex turn policy that steers the assistant toward EngramCC\nMCP memory on user turns when earlier context may have compacted out.\n\nKilo-specific note: current verified support is MCP plus the `ekilo` wrapper flow for\nsession-start / session-stop continuity. Kilo has an open request for native lifecycle hooks,\nso ECC does not claim native Kilo hook parity yet.\n\n---\n\n## How It Works\n\nEngramCC 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.\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                    Your AI Coding Session                        │\n│                                                                   │\n│  UserPromptSubmit → PostToolUse → PreCompact → Stop              │\n│         │               │              │          │               │\n│         └───────────────┴──────────────┴──────────┘              │\n│                                 │                                 │\n│                         SQLite event DB                           │\n│                                 │                                 │\n│                     ┌───────────┴───────────┐                    │\n│                     │   Local SLM Archivist  │                    │\n│                     │  (no API calls, 100%   │                    │\n│                     │   offline synthesis)   │                    │\n│                     └───────────┬───────────┘                    │\n│                                 │                                 │\n│              ┌──────────────────┼──────────────────┐             │\n│              │                  │                  │             │\n│         YAML handoff     Knowledge graph     Vector store        │\n│         (hot resume)      (BFS traversal)   (semantic search)    │\n│              │                  │                  │             │\n│              └──────────────────┴──────────────────┘             │\n│                                 │                                 │\n│                         MCP server                                │\n│                    (recall / search / recent                      │\n│                       / graph_query)                              │\n└─────────────────────────────────────────────────────────────────┘\n         ↑                                         ↓\n   SessionStart hook                       Next session\n   injects context                         picks up here\n```\n\n### Session Lifecycle\n\n| Hook | When | What it does |\n|---|---|---|\n| `UserPromptSubmit` | User sends a message | Captures intent and decision signals |\n| `PostToolUse` | Any tool completes | Captures file ops, errors, tool results |\n| `PreCompact` | Context nears limit | Snapshots session state before erasure |\n| `SessionStart` | Session opens | Injects hot handoff or cold summary + MCP pointer |\n| `Stop` | Session closes | SLM synthesis → handoff YAML + graph + vector store |\n\n### Tiered Context Injection\n\nEngramCC injects context surgically, not blindly:\n\n- **Hot resume** (< 30 min since last session): full handoff XML injected — complete working context, decisions, modified files, errors\n- **Cold start**: one-sentence headline + pointer to MCP `recall` tool — zero token waste on stale context\n\n### Memory Architecture\n\n| Layer | Storage | Contents | Lifespan |\n|---|---|---|---|\n| Working | YAML | Preferences, conventions, persistent decisions | Cross-session |\n| Episodic | SQLite + FTS5 | All session events, full-text searchable | Per-project |\n| Semantic | SQLite graph | File/decision knowledge graph, BFS traversal | Per-project |\n| Procedural | sqlite-vec | Embedding-indexed high-value events | Per-project |\n\n---\n\n## Local SLM Pipeline\n\nEngramCC synthesizes session memory using local models first — zero external API calls for its own compaction, handoff, and retrieval support.\n\nThe setup CLI detects your hardware and selects the best available tier:\n\n| Tier | Model | RAM needed | What it does |\n|---|---|---|---|\n| 1 | Rule-based | 0 | Always-on heuristic extraction |\n| 2 | MiniLM-L6-v2 ONNX | ~400 MB | Embeddings via `@huggingface/transformers` |\n| 3 | Llama 3.2 3B Q5_K_M | ~4 GB | Primary local synthesis tier |\n| 3b | Qwen3.5 4B Q4_K_M | ~3.5 GB | Alternate synthesis tier, strong multilingual/coding performance |\n| 3c | Gemma 3 4B QAT Q4_0 | ~3 GB | Alternate synthesis tier, strong structured reasoning |\n| 4 | Ollama / LM Studio / Groq | user-provided | External HTTP provider |\n\nModels 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.\n\n---\n\n## Stable Project Identity\n\nEngramCC tracks projects by a **stable UUID** stored in `.ecc-id` — not by folder path. This means:\n\n- Rename the project folder → same history\n- Move it to a different drive → same history\n- Re-clone from git → same history (falls back to git root commit hash)\n\nResolution order: `.ecc-id` file → git root commit hash → fresh UUIDv4 (written once, never regenerated).\n\n---\n\n## Data Locations\n\n```\n<projectDir>/.engram-cc/\n├── sessions/\n│   └── <uuid>.db               ← SQLite DB per project (all memory tiers)\n├── assistant-configs/          ← Local hook/MCP snippets per assistant\n├── config.json                 ← Project config, including shared models path\n├── handoff.yaml                ← Session handoff (hot resume data)\n└── working.yaml                ← Cross-session working memory\n\n<chosenModelsRoot>/Engram Context Continuum/models/\n└── <model>.gguf                ← Shared GGUF models reused across projects\n```\n\nAll data is local. No network calls for core operation. No credentials, tokens, or API keys required.\n\n---\n\n## MCP Tools\n\nWhen connected via MCP, any assistant can query EngramCC directly:\n\n| Tool | Purpose |\n|---|---|\n| `recall` | Full session context: handoff + working memory |\n| `search` | FTS5 full-text search over all session events |\n| `recent` | Most recent N events, filterable by category |\n| `graph_query` | BFS traversal of the knowledge graph |\n\n---\n\n## Configuration\n\nOverride compression tier or external provider in `plugin-config.yaml`:\n\n```yaml\n# Force a specific compression tier (default: auto)\ncompression:\n  tier: \"tier3b\"\n\n  # Tier 4 only\n  external:\n    provider: \"ollama\"\n    model: \"phi4-mini\"\n    base_url: \"http://localhost:11434\"\n```\n\n---\n\n## Benchmarks\n\nThe 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.\n\n### Verified Benchmark Runs\n\n| Command | What it measures | Current result |\n|---|---|---|\n| `npm run build` | TypeScript compile integrity | ✅ PASS |\n| `node benchmark/test-session-db.mjs` | Session DB, archive, resume-chain, carry-forward regressions | ✅ **53/53** |\n| `npm run test:quality` | End-to-end handoff quality across S1/S2/S3 | ✅ **20/20** |\n| `node benchmark/test-hook-portability.mjs` | Cross-assistant hook env and startup portability | ✅ **14/14** |\n| `node benchmark/test-codex-adapter.mjs` | Codex transcript sync + trigger + stop regressions | ✅ **29/29** |\n| `npm run test:brutal:quick` | Real-data extraction calibration (WildChat + SWE-bench) | ✅ PASS |\n| `npm run test:lifecycle:quick` | 100-cycle real-data lifecycle / archive retention observation | ✅ PASS |\n| `node benchmark/test-adversarial.mjs --model llama3.2-3b` | Hostile SLM inputs A1–A11 | ✅ **11/11** |\n| `node benchmark/test-adversarial.mjs --model qwen` | Hostile SLM inputs A1–A11 | ✅ **11/11** |\n| `node benchmark/test-adversarial.mjs --model gemma3-4b` | Hostile SLM inputs A1–A11 | ✅ **11/11** |\n| `node benchmark/test-tier-comparison.mjs` | Cross-tier compaction retention (4→20 cycles) | ✅ **38/38** on `tier3`, `tier3b`, `tier3c` |\n| `node benchmark/test-scale.mjs` | Prompt-length stability | ✅ Llama **16/16** · Qwen **15/16** |\n| `node benchmark/test-compaction-marathon.mjs` | Multi-compaction memory retention | ✅ **53/53** |\n| `node benchmark/test-diffmode.mjs` | Grammar-constrained JSON output | ✅ PASS for Llama 3.2 3B + Qwen3.5 4B |\n\n### What Those Results Mean\n\n#### Handoff Quality\n\n`npm run test:quality` exercises the full path from session events to next-session context injection.\n\n| Scenario | Assertions | Result |\n|---|---|---|\n| S1 — Initial session | 6/6 | ✅ |\n| S2 — Hot resume | 5/5 | ✅ |\n| S3 — Marathon / cold start | 9/9 | ✅ |\n\n**Total: 20/20**\n\n#### Real-Data Retrieval / Retention\n\n`npm run test:brutal:quick` and `npm run test:lifecycle:quick` use public external datasets:\n- WildChat-1M coding conversations\n- SWE-bench GitHub issue statements\n\nCurrent verified observations:\n- extraction brutal calibration: **PASS**\n- adversarial extractor traps: **15/15**\n- chain phase `extract → store → search → snapshot`: **PASS**\n- lifecycle checkpoints: **100% / 80% / 80% / 100%** FTS5 recall at cycles 25 / 50 / 75 / 100\n- cycle 100 recall by source: **WildChat 5/7 (71%)**, **SWE-bench 13/13 (100%)**\n\nThe two misses in the lifecycle run were low-signal terms (`nothing`, `creator`), not archive corruption.\n\n#### SLM Adversarial Robustness\n\nThe 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.\n\nCurrent verified scores:\n\n| Model | Score |\n|---|---|\n| Llama 3.2 3B Q5_K_M | **11/11** |\n| Qwen3.5 4B Q4_K_M | **11/11** |\n| Gemma 3 4B QAT Q4_0 | **11/11** |\n\nThis matters because **A11 used to be the real gap**. It now passes after the deterministic carry-forward state was added to the compaction chain.\n\n#### SLM Scale Stability\n\n`node benchmark/test-scale.mjs` probes prompt growth from 128 to 985 words.\n\n| Model | Result |\n|---|---|\n| Llama 3.2 3B | **16/16** |\n| Qwen3.5 4B | **15/16** |\n\nCurrent caveat:\n- Qwen 4B had **one** miss at S4 (985 words) on the no-hallucination check.\n\n#### Cross-Tier Compaction Retention\n\n`node benchmark/test-tier-comparison.mjs` runs the same 4→20 cycle compaction stress test across all three production GGUF tiers.\n\n| Tier | Result |\n|---|---|\n| `tier3` — Llama 3.2 3B | **38/38** |\n| `tier3b` — Qwen3.5 4B | **38/38** |\n| `tier3c` — Gemma 3 4B | **38/38** |\n\nAt the time of this README update, the verified token savings vs raw snapshot were:\n- `tier3`: **24–26%**\n- `tier3b`: **16–23%**\n- `tier3c`: **20–28%**\n\n#### Multi-Compaction Marathon\n\n`node benchmark/test-compaction-marathon.mjs` simulates long-running sessions across 4, 8, 12, 16, and 20 compaction cycles.\n\nCurrent verified result:\n- **53/53 assertions passed**\n- all anchor facts survived through **20 compaction cycles**\n\n### Important Caveats\n\n- `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.\n- Qwen 4B is strong overall, but its current scale run is **15/16**, not perfect.\n- The old `A11` failure is no longer the current state and should not be cited as a live weakness.\n- `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.\n\n### Bottom-Line Read\n\nECC is now strong in the places that matter most for a CLI memory substrate:\n- real-data extraction and retention\n- end-to-end handoff quality\n- chained compaction continuity\n- cross-tier SLM robustness\n\nThe 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.\n\n---\n\n## Development\n\n```bash\nnpm run build       # Compile TypeScript → build/\nnpm run typecheck   # Type check without emit\nnpm run clean       # Remove build/\nnpm run setup       # Build + run setup CLI\n```\n\n**Runtime requirements:**\n- Node.js >= 18 (all hooks, MCP server, setup CLI)\n\n**Contributor note:**\n- See `ADAPTER-AUTHORING.md` before adding or changing assistant adapters. It defines the allowed touch points, capability rules, storage rules, and current portability boundaries.\n\n---\n\n## Platform Support\n\nEngramCC runs on **Windows**, **macOS**, and **Linux** (x64 and ARM64).\n\n| Dependency | Type | Platform coverage |\n|---|---|---|\n| better-sqlite3 | Native C++ addon | Prebuilt binaries for all major platforms + Node versions |\n| node-llama-cpp (Tier 3) | Native addon | 13 prebuilt variants: Windows/macOS/Linux × x64/ARM64 × CPU/CUDA/Vulkan/Metal |\n| sqlite-vec (Vector store) | Native addon | Prebuilt for Windows x64, macOS x64/ARM64, Linux x64/ARM64 |\n| @huggingface/transformers (Tier 2) | Pure JS + WASM | Universal — no native code |\n| All other deps | Pure JS | Universal |\n\n### Troubleshooting: `better-sqlite3` build failure\n\n`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:\n\n**Windows:**\n```powershell\nnpm install --global windows-build-tools\n# or install Visual Studio Build Tools with \"Desktop development with C++\"\n```\n\n**macOS:**\n```bash\nxcode-select --install\n```\n\n**Linux (Debian/Ubuntu):**\n```bash\nsudo apt install build-essential python3\n```\n\n**Linux (Fedora/RHEL):**\n```bash\nsudo dnf groupinstall \"Development Tools\"\n```\n\nIf `npm install` fails with `gyp ERR!` or `node-pre-gyp` errors, installing the build tools above and re-running `npm install` will fix it.\n\n### Troubleshooting: Local SLM tier not available\n\nThe 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).\n\nExamples:\n\n```bash\nengramcc --tier=tier3 --project-dir <project> --models-dir <shared-models-dir>\nengramcc --tier=tier3b --project-dir <project> --models-dir <shared-models-dir>\nengramcc --tier=tier3c --project-dir <project> --models-dir <shared-models-dir>\n```\n\nApproximate runtime requirements:\n- `tier3` Llama 3.2 3B: ~4 GB RAM\n- `tier3b` Qwen3.5 4B: ~3.5 GB RAM\n- `tier3c` Gemma 3 4B: ~3 GB RAM\n\n### Troubleshooting: Vector store not active\n\nThe 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:\n\n```bash\nnode -e \"require('sqlite-vec')\" 2>&1 || echo \"sqlite-vec not available — vector search disabled\"\n```\n\n---\n\n## Project Structure\n\n```\nsrc/\n├── hooks/          ← Lifecycle hook entry points (.mjs + .ts)\n├── adapters/       ← Per-assistant registration (Claude Code, Gemini CLI, etc.)\n├── session/        ← SQLite event capture, schema, FTS5\n├── memory/         ← Working YAML, knowledge graph, vector store\n├── handoff/        ← Session handoff writer, reader, dedup\n├── compression/    ← SLM pipeline: tier selection, ONNX, node-llama-cpp\n├── mcp/            ← MCP stdio server\n├── tokenization/   ← Token budget auditor\n├── project-id.ts   ← Stable project UUID resolution\n└── cli/\n    ├── setup.ts    ← Install CLI: hardware detection, adapter registration\n    └── download-model.ts ← GGUF model downloader\n```\n\n---\n\n## License\n\n**Open source:** [AGPL-3.0](LICENSE) — free to use, modify, and distribute as long as derivative works are also open source under AGPL-3.0.\n\n**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](COMMERCIAL-LICENSE.md) for details.\n\n",
  "bytes": 19278,
  "sha": "27f57020a3ef03ce65a8193ca63ecad75a2adc2293364d591e22c8bb144a0b76",
  "repo_slug": "morous-dev/engram-context-continuum",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_morous_dev_engram_cc_0b6d9d25/readme"
}