engramx is the context spine for AI coding agents.
It intercepts every Read, Edit, Write, and cat
your agent makes and replaces it with a pre-assembled context packet —
structure, decisions, git history, library docs, known mistakes, and
now any MCP server you plug in —
in a single ~500-token response.
The agent gets what it needs without re-reading the file.
$npm install -g engramx $cd ~/my-project $engram setup ↳ init → indexed 451 nodes, 1005 edges (10 langs) ↳ install-hook → 7 hooks wired ↳ adapters → Claude Code detected · AGENTS.md + CLAUDE.md generated ↳ doctor → everything green ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ next Claude Code session has memory. → optional: engram plugin install serena for +LSP symbols
Works with Claude Code · Cursor · Codex · Aider · Continue · Zed · Windsurf · Neovim · Emacs
The original goal was to collapse the agent's whole grep → read → read
investigation loop, not just the single file read. v4.2 ships the rest — and every piece
is gated so it only fires when it genuinely saves tokens, with an escalation path so it
can never blind the agent. Structural context-token effect, not a bill saving.
A content-mode grep for a well-referenced symbol is answered from the reference graph
with the actual file:line: code call sites — smaller than the raw grep
(init: 573 vs 9,317 tokens on this repo) while showing the real usage.
Default filename greps and low-usage symbols pass straight through.
Re-read an unchanged file you already read this session and engram returns a pointer ("it's still in your context above"), not the file again. Byte-unchanged guard, full reads only, and a PreCompact / SessionStart reset so it never points at evicted content.
A deterministic bench/session-level.ts models the session saving as a curve
over how often the agent re-fetches raw content — instead of quoting one number. The
break-even is the honest headline: engram nets positive unless that fallback rate is high.
Mesh moves to v4.5 behind ENGRAM_MESH_EXPERIMENTAL=1 — the May 18 strategic
re-cut prioritised distribution-via-skills over federation. Read the full diff in
CHANGELOG.md
or watch GitHub Discussions
for the v4.5 mesh GA timeline.
Drop a .mjs into ~/.engram/plugins/ with an mcpConfig
block — the loader spawns the server, calls its tools on every
Read, and merges the result into the rich packet.
Serena for LSP symbols. GitHub for issue context. Sentry for prod errors.
No code changes to engramx.
When you refactor a broken function away, the old mistake stops
firing. Schema-level valid_until +
invalidated_by_commit. No more stale warnings
polluting your context. Your v2.1 database auto-migrates on first open.
Set ENGRAM_MISTAKE_GUARD=1. Before Claude runs a command
that previously caused a bug, engramx intercepts and surfaces the
warning. Set =2 for hard-deny. Zero overhead when unset.
One engram gen writes to both. Works in
Claude Code, Cursor, Codex CLI, Windsurf, Copilot Chat, JetBrains Junie,
Antigravity without per-IDE setup. Linux Foundation's universal
agent-instructions standard, adopted by every major AI coding tool.
GET /context/stream?file=… emits one frame per provider as it resolves.
Fast providers paint first; Serena's cold-start doesn't block the
packet. Resumable across reconnects via Last-Event-ID
(MCP SEP-1699).
Claude Code writes consolidated memory to
~/.claude/projects/<project>/memory/MEMORY.md.
engramx reads the index, surfaces entries relevant to the current file.
When Anthropic flips Auto-Dream on, this bridge gets better —
no update required.
One package, ~6MB, six tree-sitter grammars bundled. Zero cloud calls during install. Apache 2.0.
$npm install -g engramx ↳ added engramx@4.3.1 in 4s
AST-extract every function, class, route, model. 10 languages. Mistake memory + git miner included.
$cd ~/my-project $engram init ↳ 451 nodes · 1005 edges ↳ SQLite at .engram/graph.db
PreToolUse hook intercepts Read /
Edit /
Bash cat and answers from the graph.
Survives PreCompact + CwdChanged.
$engram install-hook ↳ ✓ 7 hooks installed ↳ ✓ hud label active
Your agent attempts Read('src/auth.ts').
engram's PreToolUse hook intercepts. It reads the graph for that file —
structure, recent edits, related decisions, known mistakes — packs
~500 tokens, denies the original Read with the packet as the reason.
The agent sees a richer answer than the file itself, in a fraction
of the tokens. Across engramx's own source the per-file structural
context reduction is up to ~89% (structural, not a
bill saving — your repo varies) — reproducible via
npx tsx bench/real-world.ts.
Hooks at PreToolUse and PreCompact. Your agent doesn't have to learn a new tool — it just sees better context for the same call.
Graph lives at .engram/graph.db.
No API keys, no telemetry by default, runs on a plane.
per-file structural context reduction on engramx's own source — structural, not a bill saving; your repo varies. Committed report at bench/results/. Reproduce with one command.
TS · JS · Python · Go · Rust · Java · Ruby · C# · PHP · Bash. Tree-sitter native.
Mistake memory with bi-temporal validity (v3.0). Past bugs surface; refactored-away mistakes stop firing. 1.5× relevance boost on matching results.
| Dimension | Without engramx | With engramx v3.0 |
|---|---|---|
| Tokens per file Read | ~5,400 raw bytes (median) | ~500 (rich packet) |
| Cumulative token cost | 163,122 tokens (baseline) | 17,722 tokens (89.1% fewer — structural, engramx's own repo) |
| Real $ impact | Fewer context tokens is not a proportional bill cut — Anthropic prompt caching already discounts repeated reads, so engram's net cost effect ≈ 0. The win is smaller, more-relevant context (and fewer repeated mistakes), not a cheaper bill. | |
| Repeat-mistake rate | High — agent re-introduces fixed bugs | Low — mistakes at top of context, pre-mortem guard on Edit / Bash |
| Stale-warning noise | Old bugs keep firing after refactor | Bi-temporal validity — refactored-away mistakes stop surfacing |
| Context survival | Lost on /compact | PreCompact hook re-injects spine |
| Project switch | Manual re-prime | CwdChanged auto-loads new graph |
| Provider ecosystem | Fixed set (cloud RAG, 1 vector DB) | 9 built-ins + any MCP server as a 10-line plugin |
| Network calls | Cloud RAG, embeddings, vendor lock | 0 — local SQLite, $0 LLM cost |
| Setup | Configure RAG, vector DB, embedding model | engram setup · one command |
The up-to-~89% structural reduction is what engramx's 9 built-in providers measure on its own repo (structural, not a bill saving — your repo varies). Every MCP server you plug in covers another context gap — cross-file symbols, production errors, schema, tickets, library docs — that the agent would otherwise burn tokens researching. And because every provider is budget-capped + budget-weighted reranked, more plugins = more relevant context without packet bloat.
| Plugin | Closes this gap | Savings angle | Effort |
|---|---|---|---|
| Serena LSP-backed symbols · MCP · 20+ langs | Cross-file symbol references engramx's AST can't resolve precisely. | Saves ~3-5 file Reads per "find callers" style query. Kills the grep-then-read loop. |
cp serena-plugin.mjs ~/.engram/plugins/
|
| GitHub MCP issues · PRs · commits · official Anthropic+GH | Issue history & PR context when editing a file that was recently discussed. | Replaces "run gh issue list, pipe to grep, read 3 issues" with one context block. |
engram plugin install github
|
| Sentry MCP prod error context · stack traces | "What broke in prod for this file" when the agent is about to change it. | Cuts the debug-request → open-dashboard → paste-stacktrace loop. |
engram plugin install sentry
|
| Supabase / Neon schema · RLS · table info | Database schema context when editing queries, migrations, or ORM models. | Kills the "Read prisma.schema / query pg_catalog / show definition" roundtrip. |
engram plugin install supabase
|
| Context7 always-current library docs · bundled | Library API changes + breaking updates for imports you actually use. | Already a built-in (Tier 2 w/ cache). Stays cheap, stays current. |
shipped · no install
|
| Anthropic Auto-Memory Claude Code's own MEMORY.md | Consolidated memory Claude already wrote about this codebase. | Auto-lights-up when Auto-Dream server flag flips on. Zero code change needed. |
shipped · no install
|
export default { name: "mcp:serena", label: "SEMANTIC SYMBOLS", version: "0.1.0", tokenBudget: 250, mcpConfig: { transport: "stdio", command: "uvx", args: ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server"], tools: [{ name: "find_symbol", args: { name_path: "{fileBasename}" } }] } };
That's the entire Serena integration. No transport code, no connection pooling, no retry logic —
the loader auto-wraps via createMcpProvider().
Full spec at docs/plugins/README.md.
engram gen. Every agent reads it.
v3.0 emits both CLAUDE.md (for Claude Code) and
AGENTS.md (the Linux-Foundation universal agent-instructions
standard adopted by Codex, Cursor, Windsurf, Copilot, Junie, Antigravity) by default.
One project indexing → every agent reads it.
Legacy per-IDE generators still work for explicit control.
$engram ui ↳ listening on http://127.0.0.1:7777 ↳ opening browser…
Real metrics from real sessions. Not vanity numbers — measured at the hook.
Every Read / Edit / Write decision, streamed within 1 second. Deny vs passthrough on the right.
Ranked by interception count. The "where the savings come from" view.
Drag to pan, scroll to zoom, click for details. 300+ nodes at 60fps. God nodes labeled and larger. The view that makes architecture legible to humans.
HTTP / LSP / AST / IDE count and per-layer cache stats. Cross-session hit counts.
.engram/graph.db.
The HTTP server binds to 127.0.0.1 only. Auth is bearer-token (random 64-char, file-mode 0600).
CORS is opt-in via ENGRAM_ALLOWED_ORIGINS. Zero telemetry by default, zero LLM API calls during indexing.
bench/real-world.ts. Results committed under
bench/results/.
Run npx tsx bench/real-world.ts --project . --files 50 on your own code to reproduce.
No estimates. No rounding up. No cherry-picking — 85 of 87 files saved tokens, median 84.2%.
.mjs. Serena for LSP symbols, GitHub for issue context, Sentry for prod errors.ENGRAM_MISTAKE_GUARD=1 and Claude gets a warning before running a command that caused a bug before..bak-v7 saved.engram gen now writes both CLAUDE.md and AGENTS.md. Works in every major AI IDE without per-IDE setup./context/stream?file=… emits one frame per provider as it resolves. Resumable via Last-Event-ID.MEMORY.md index. Lights up automatically when Anthropic's Auto-Dream server flag flips.engram install-hook wires the full PreToolUse / PreCompact / CwdChanged / SessionStart sentinel.
Everything else (Cursor, Codex CLI, Windsurf, Copilot Chat, JetBrains Junie, Antigravity): they all read
AGENTS.md which engram gen now writes by default. One project, indexed once, works everywhere.
Legacy gen-cursorrules / gen-aider / gen-windsurfrules still work for explicit control.
.mjs in ~/.engram/plugins/
with an mcpConfig block pointing at any MCP server — the loader spawns, connects, and merges
tool calls into the rich packet automatically. Works in ~10 lines. Full control path: write your own
async resolve(filePath, context) + isAvailable() in the same .mjs.
The loader validates the shape before loading; broken plugins are silently skipped and reported in
engram plugin list. Full spec + examples in docs/plugins/README.md.
.gitignore + .engramignore.
Filenames matching .env*, *.pem, *.key,
secrets.*, credentials.* are excluded by default.
Content is never sent off-machine, but the conservative move is still:
add anything sensitive to .engramignore before engram init.
One command. The next session has memory. Up to ~89% fewer context tokens (structural, your repo varies) in a reproducible benchmark. Any MCP server becomes a provider in 10 lines. Zero cloud, zero telemetry, Apache 2.0 — uninstall whenever, it's 30 seconds back either way.