# Engram > The context spine that 10x's every AI coding session. Live in 8 IDEs (Claude Code, Cursor, Cline, Continue, Aider, Codex, Windsurf, Zed) via npm + OpenVSX + Anthropic plugin directory. 89% measured token reduction. Local SQLite, zero cloud, Apache 2.0. - **Type:** MCP server - **Install:** `agentstack add mcp-nickcirv-engram` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [NickCirv](https://agentstack.voostack.com/s/nickcirv) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 3.0.2 - **License:** Apache-2.0 - **Upstream author:** [NickCirv](https://github.com/NickCirv) - **Source:** https://github.com/NickCirv/engram - **Website:** https://github.com/NickCirv/engram ## Install ```sh agentstack add mcp-nickcirv-engram ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Engram makes your AI coding agent stop re-reading the same files — and stop repeating mistakes your repo already fixed. One install. 8 IDEs. Your agent works from a structural map of your repo instead of re-reading whole files — so sessions run longer before the context wall — and bi-temporal mistakes are auto-captured from your git revert history, so it stops repeating fixes that already failed. Context packets run ~50–90% smaller per file (structural size, not a bill saving — run engram bench on yours). Local SQLite, zero cloud, Apache 2.0. Try in 30 seconds (no install) ▶ Install Page · Live Demo · Scene Table · rendered with Hyperframes Install · Quickstart · Dashboard · Benchmark · IDE Integrations · HTTP API · ECP Spec · Contributing --- ## Try in 30 seconds (no install) ▶ Play the live recording · or get the raw cast at docs/demos/v4-skill-pack.cast (asciinema play) · or generate it yourself with v4-skill-pack-demo.sh Or paste this into your terminal — same flow, no global install, no commitment. Creates a throwaway repo with a reverted bug, then runs engram against the public npm registry: ```bash mkdir -p /tmp/engram-demo && cd /tmp/engram-demo && \ git init -q && git commit --allow-empty -q -m "init" && \ echo "export const buggy = () => null;" > src.ts && \ git add -A && git commit -q -m "feat: add buggy helper returning null causing form crashes" && \ git revert --no-edit HEAD > /dev/null && \ npx --yes engramx@4.5.0 init . && \ npx --yes engramx@4.5.0 mistakes ``` You should see, within 30 seconds, the **bi-temporal pre-mortem** engram auto-captured from your revert: ``` ⚠️ 1 mistake(s) recorded: ⚠ Mistake #1 — 2026-05-19 ┌─ then you believed: feat: add buggy helper returning null causing form crashes ├─ found false: 2026-05-19 └─ truth now: Reverted in (2026-05-19) ref: src.ts applies to: git revert touching src ``` That's the rave moment — engram remembering what your AI agent forgot, surfaced *before* the next edit. Multiply this across your actual repo's revert history, and it works on every Claude Code session automatically. When you're ready: scroll to [Install](#install-in-30-seconds) for the global install path. --- ## Why this exists, May 2026 Three things broke at the same time. Cursor went usage-based and people started getting $1,400 surprise bills. Anthropic tightened Claude Code limits, then quietly tested removing it from the $20 Pro plan. Half the AI coding crowd migrated from one tool to the other, hit the new ceiling within a week, and started looking for any way to make a session last longer. Engramx is what makes the session last longer. It indexes your codebase into a local SQLite knowledge graph once. Then it intercepts file reads at the agent boundary and replaces them with a structural summary the agent already has the working memory for. Same edit, same diff, same code shipped — fewer tokens consumed in the round trip. On engramx's own repo the **per-file structural context reduction is ~89%** (89.5% in the latest `bench/real-world.ts` run, size-guarded so it never counts a file engram wouldn't shrink). Across eight real OSS repos it ranges roughly **50–90% — highest on large-file Python/Go codebases, lower on many-small-file projects** (`bench/real-world.ts` reproduces it on any project you point it at). This is a *structural* context-packet reduction measured per file, **not** an agent-loop cost saving, and it varies by repo. Independent migration guides ([dev.to/56kode](https://dev.to/56_kode/why-were-moving-from-cursor-to-claude-code-and-why-you-should-too-9kh), [SpectrumAI Lab](https://spectrumailab.com/blog/claude-code-vs-cursor)) cite engram for the strongest measured structural reduction in the category. Works in 8 IDEs and counting — Claude Code, Cursor, Cline, Continue.dev, Aider, Windsurf, Zed, OpenAI Codex CLI. One install, one graph, every tool benefits. Apache 2.0. Local SQLite. Nothing leaves your machine. > **v4.5.0 "Reach" — 2026-06-21.** New: the **sub-agent broker** now points a spawned agent at the files most likely related to the one it is working on — graph-adjacent files first (real call/import edges), then same-directory siblings and test↔implementation counterparts — so it can skip the grep-around discovery step (tiered so a real graph hit is never displaced by a weaker path guess; de-duplicated; never-worse). And the resolver now **displaces redundant context across providers** (de-dupe + blend-rank + discard) instead of concatenating it, with the Stop line reporting `~N redundant tokens displaced`. An intercepted Read's enriched packet is served only when it is strictly smaller than the raw file, else it falls back to the graph-only summary. Both are structural — never a bill/cost claim. Still: local SQLite, nothing leaves your machine. > > **v4.3 "Proof" shipped 2026-06-05 — engram's saving is now real *and provable*.** Run **`engram measure`** in your own repo to see the honest structural context-token reduction on **your** code — every disclosure computed live: it's a ceiling, here's the recall, here's the intercept rate, "structural tokens, not your bill." Run **`npm run bench:recall`** for the reproducible proof that engram surfaces the files a change actually touches (recall@10 33% on engram's own repo, decomposed honestly: candidate generation reaches 43%, the PageRank ranker adds +3.2pp over random-within-candidate; 10.4% blind chance). > > New this release: a **never-worse gate** on Grep (engram passes through whenever its packet isn't actually smaller — sized to your grep's exact `cwd`/`path`/`glob` scope), **Bash-grep interception** (the shell-only IDEs — Aider, Codex CLI, Cline — now get the call-site packet too), a **sub-agent context broker** (a tight ~100-token ranked slice into each spawned Claude Code sub-agent — the one regime prompt caching can't help), and a **compaction ledger** (a "previously read" list injected at `/compact` so the agent doesn't re-explore). Every number is a measured fact or a labelled bet — **no cost claims**; a *structural* context reduction, not a bill saving (engram's net over prompt caching ≈ 0). 1149 tests. See [CHANGELOG.md](CHANGELOG.md), `docs/COMPARISON.md` (vs the other local code-graph tools — ranking isn't unique, the *combination* is), and `docs/FRONTIER.md`. > > **v4.3.1 (patch) — 2026-06-06:** a two-swarm execution audit hardened the release. Fixes: the `engram cost` digest no longer prints an unqualified dollar/"% saved" figure (it now carries the structural-not-a-bill-saving caveat); `bench`/`stats` state "Nx LARGER — passes through" instead of a backwards "0.2x smaller" on tiny repos; the incremental reindex now rebuilds cross-file `calls` edges (no graph drift between full re-indexes) **and** does so in ~1ms via an mtime-keyed refs cache instead of re-parsing every file on each edit; the MCP server reports its real version; `doctor` flags a disabled kill-switch; `gen --task ` errors cleanly. No new features, no behaviour change to the honest claim. > > **v4.3.2 (patch) — 2026-06-06:** **fixes a broken MCP-setup command in this README** — the config block now uses `npx -y -p engramx engram-serve ` (the previous `engramx serve` had no such subcommand, so MCP clients failed with "unknown command 'serve'"). Also: `gen-ccs` now exports a structural fallback on fresh repos instead of an empty file; TS `interface`/`type`/`enum` declarations are extracted as first-class graph nodes; the git co-change miner no longer emits a self-edge for distinct files sharing a basename; provider warmup probes no longer keep the process alive a few seconds after a session starts. Adds `llms-install.md` for agent-driven setup. No behaviour change to the honest claim. Earlier release notes (v4.2 "Loop", June 3) **v4.2 "Loop" shipped 2026-06-03 — engram closed the agent's investigation loop.** The original Context Spine goal was to collapse the whole `grep → read → read` loop, not just the single file read. v4.2 shipped a **Grep interception** that answers a content-mode symbol search from the reference graph with the actual `file:line: code` call sites — smaller than the raw grep (`init` is 573 vs 9,317 tokens on engram's own repo) while showing the real usage — and **same-session read dedup** that returns a pointer instead of re-serving an unchanged file the agent already read. Both are recall-safe (an `rg -n` escalation; byte-unchanged + PreCompact/SessionStart reset guards) and gated so they only fire when they genuinely save tokens. (v4.1 "Compass" — PageRank-ranked graph + `callers`/`callees`/`impact` traversal.) Earlier release notes (v3.4 "Universal Spine", May 2) **v3.4 "Universal Spine" shipped 2026-05-02** — multi-IDE detector covers 8 tools, Anthropic Claude Code plugin submitted to the official directory ([in review](https://claude.ai/settings/plugins)), VS Code / Cursor extension live as [`nickcirv.engram-vscode`](https://open-vsx.org/extension/nickcirv/engram-vscode) on OpenVSX, [`engramx-continue`](https://www.npmjs.com/package/engramx-continue) on npm, Cline integration documented. Cost Lens telemetry from v3.3.0 feeds a weekly Markdown digest at `~/.engram/cost-report-YYYY-Www.md`. 1007 tests, CI green on Ubuntu + Windows × Node 20 + 22. Earlier release notes (v3.0 "Spine", April 24) EngramX v3.0 "Spine" shipped 2026-04-24 — the biggest release before v3.4. The spine is **extensible**: any MCP server becomes an EngramX provider via a 10-line plugin file. **Pre-mortem mistake-guard** warns before you repeat a bug. **Bi-temporal mistake memory** — refactored-away mistakes stop firing. **Anthropic Auto-Memory bridge** reads Claude Code's own consolidated memory. **SSE-streaming** packets render progressively. `engram gen` dual-emits `AGENTS.md` + `CLAUDE.md` by default. --- ## Install in 30 seconds Three paths depending on where you want engram to live. All three install the **same engram**; you can stack them. ### 1. CLI (recommended starting point — works in every supported IDE) ```bash npm install -g engramx cd ~/your-project engram setup ``` `engram setup` auto-detects every supported IDE on your machine (Claude Code, Cursor, Cline, Continue, Aider, Windsurf, Zed, Codex CLI) and prints the next step for each. You don't have to remember which command to run for which tool. ### 2. Cursor / VS Code extension (live on OpenVSX) ```bash code --install-extension nickcirv.engram-vscode ``` Adds six commands to the Cursor / VS Code command palette plus a status-bar entry that opens the cost dashboard with one click. [Listing on OpenVSX](https://open-vsx.org/extension/nickcirv/engram-vscode). ### 3. Continue.dev users ```bash npm install engramx-continue ``` Adds engram as an `@engram` context provider. [Package on npm](https://www.npmjs.com/package/engramx-continue) · [Integration docs](docs/integrations/continue.md). > The Anthropic Claude Code plugin (`/plugin install engram` from the official directory) is pending in the official directory. When it lands, that's a fourth install path with zero CLI steps. Until then, path 1 covers Claude Code via hooks. --- # EngramX — the cached context spine for AI coding agents. Your AI coding agent keeps re-reading the same files. Every `Read`, every `Edit`, every `cat` re-loads context that's already in your window. **EngramX is the spine.** It intercepts every file read at the tool boundary, answers from a pre-assembled context packet held in **three layers of cache** — a knowledge graph the agent has already "paid" to build, a per-provider SQLite cache of external lookups, and an in-memory LRU of recent queries — and hands the agent a single ~500-token response instead of a raw file. The agent gets what it needs, structured. And **every plugin you add extends what engram can surface** — Serena for LSP symbols, GitHub MCP for issue context, Sentry MCP for production errors, Supabase / Neon for schema. Each one closes a context gap the agent would otherwise spend turns researching. (More providers = more capability; whether they net fewer tokens on a given task depends on the task — measure it on yours.) **Per-file structural reduction on a reproducible benchmark: up to ~89%** (engramx's own codebase; structural token reduction, not agent-loop cost). On the committed 87-file run, 85 of 87 real source files saw reduced per-file token cost, best case 98.4% (18,820 tokens → 306); a fresh sample of 50 files reduces ~89.5% aggregate. Your per-repo numbers vary — run it on yours. > **What this number is (and isn't):** ~89% is a *per-file structural context reduction* measured on engramx's own repo with all 9 providers active — it measures how much smaller engram's context packet is than reading the full files raw. It is **not** an agent-loop cost-savings figure and will differ on your codebase. Your actual dollar saving depends on your prompt-caching setup and workload — run the benchmark on your own repo (see [Benchmark](#benchmark)) to get your structural number. ### One command to everything ```bash npm install -g engramx cd ~/my-project engram setup ``` That's the install. `engram setup` runs `engram init` (builds the graph), `engram install-hook` (wires the Sentinel into your AI tool), detects your IDE, dual-emits `AGENTS.md` + `CLAUDE.md`, then runs `engram doctor` to verify everything green. Under 30 seconds on most projects. Works in Claude Code, Cursor, Codex CLI, Windsurf, GitHub Copilot Chat, JetBrains Junie, Aider, Zed, Continue — any agent that reads `AGENTS.md` or uses MCP. The **next session** you open starts with the spine pre-loaded: project brief already in context, file reads intercepted, a live HUD showing cumulative savings, bi-temporal mistakes waiting to warn you, and any plugins you've added already answering their domains. --- ## I'm not a developer — what does this actually do? Short answer: **your AI coding assistant stops re-loading the same information into context twice.** Long answer: 1. You ask your AI assistant (Claude Code, Cursor, Codex, whatever) to help with a file. 2. The assistant tries to read that file. Normally it reads the whole thing, loads every byte into context, and throws most of it away. 3. EngramX catches the read, answers with a cached summary (the 50–200 lines the agent actually needs, plus context from your git history, past mistakes, library docs, and anything else useful), and lets the agent work from that. 4. The agent works from a compact structural view instead of re-reading whole files. Multi-hour sessions stop hitting context limits, and the agent stops re-introducing bugs you already fixed — because EngramX remembers what broke. (Token-cost impact depends on your workload — engram-counter measures your real number.) It runs on your laptop. It doesn't send your code anywhere. It's Apache 2.0. There's no account, no login, no cloud. You install it once and forget it's there. **Want engram to understand more?** Install a plugin. Each one adds a context source — see [Plugins extend what engram understands](#plugins-extend-what-engram-understands) below. Drop a 10-line `.mjs` file in `~/.engram/plugins/` and the next session uses it. **Want out?** Clean uninstall is one command: ```bash npm uninstall -g engramx # 3.0.1+ auto-runs preuninstall hook-cleanup ``` If you installed 3.0.0 and ran `npm uninstall` before the 3.0.1 patch shipped, your Claude Code hooks may be orphaned. Run `engram repair-hooks --scope user` (install 3.0.1 first if needed) or see the [`CHANGELOG.md`](CHANGELOG.md#301--2026-04-24--clean-uninstall) for the manual `jq`-based recovery one-liner. --- ## Proof, not promises Everything above is a measured *per-file structural* reduction on engramx's own files — not estimated, but also not an agent-loop cost figure (your per-repo numbers vary). `bench/real-world.ts` r … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [NickCirv](https://github.com/NickCirv) - **Source:** [NickCirv/engram](https://github.com/NickCirv/engram) - **License:** Apache-2.0 - **Homepage:** https://github.com/NickCirv/engram Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v3.0.2 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **3.0.2** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-nickcirv-engram - Seller: https://agentstack.voostack.com/s/nickcirv - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.