Install · Quickstart · Dashboard · Benchmark · IDE Integrations · HTTP API · ECP Spec · Contributing
v2.0 "Ecosystem" shipped 2026-04-17 — web dashboard at
engram ui, 3-layer memory cache (23μs/op at 99% hit rate), provider plugin system (~/.engram/plugins/*.mjs),engram cacheCLI, schema rollback with automatic backup, incremental re-indexing (78% faster on large repos), auto-bundled tree-sitter grammars, Windsurf + Neovim + Emacs integrations. See CHANGELOG.md for the full diff.
engram intercepts every file read your AI agent makes and replaces it with a pre-assembled context packet — structure, decisions, git history, library docs, and known issues — from 8 providers, delivered in a single ~500-token response. The agent gets what it needs without reading the file. You stop paying for context you've already paid for.
This is not a tool the agent calls. It hooks at the Claude Code tool boundary. Every Read, Edit, Write, and cat is intercepted automatically.
npm install -g engramx
cd ~/my-project
engram init
engram install-hookThat's the full setup. The next Claude Code session starts with a project brief already loaded, file reads intercepted, and a live HUD showing cumulative savings.
A zero-dependency web dashboard ships built-in. One command, opens in your browser:
engram ui
The Overview tab: real metrics from your sessions — tokens saved, cost saved at $3/M rate, session-level hit rate, cache performance, graph health.
Activity — live hook events streamed via Server-Sent Events. See every Read / Edit / Write decision (deny = intercepted, passthrough = engram couldn't help). Per-tool breakdown on the right shows where the savings come from.
Files — the heatmap ranks your hot files by interception count. Cursor knows this view.
Graph — Canvas 2D force-directed visualization of the knowledge graph. God nodes are larger and labeled. Drag to pan, scroll to zoom, click for details. 300+ nodes at 60fps.
Providers — component health (HTTP / LSP / AST / IDE count) and per-layer cache stats (entries + cross-session hit counts).
- 35KB total — one HTTP response, zero external CDN calls, works offline and on air-gapped machines.
- Zero runtime dependencies — all CSS and JS inlined as TypeScript template literals; SVG charts and Canvas 2D graph hand-rolled (~400 LOC total).
- CSP-hardened —
default-src 'self'; connect-src 'self'meta tag plusesc()at every data-to-HTML boundary. Defends against attacker-controlled file paths and labels mined from untrusted repos. - Live-updating — SSE stream pushes new hook events to the Activity tab within 1 second.
See also the Sessions tab (cumulative breakdown + sparkline) in assets/screenshots/02-sessions.png.
Measured across 10 structured coding tasks against a baseline of reading the relevant files directly. No synthetic data. No cherry-picked queries.
| Task | Baseline (tokens) | engram (tokens) | Savings |
|---|---|---|---|
| task-01-find-caller | 4,500 | 650 | 85.6% |
| task-02-parent-class | 2,800 | 400 | 85.7% |
| task-03-file-for-class | 3,200 | 300 | 90.6% |
| task-04-import-graph | 6,800 | 900 | 86.8% |
| task-05-exported-api | 5,500 | 700 | 87.3% |
| task-06-landmine-check | 8,200 | 850 | 89.6% |
| task-07-architecture-sketch | 14,500 | 1,600 | 89.0% |
| task-08-refactor-scope | 9,200 | 1,100 | 88.0% |
| task-09-hot-files | 3,800 | 550 | 85.5% |
| task-10-cross-file-flow | 12,800 | 1,400 | 89.1% |
| Aggregate | 7,130 | 845 | 88.1% |
Run the benchmark yourself: engram bench or engram stress-test for the full suite.
engram sits between your AI agent and the filesystem. When the agent reads a file, engram checks its knowledge graph. If the file is covered with sufficient confidence, it blocks the read and injects a compact context packet instead. The packet is assembled from up to 8 providers in parallel, all pre-cached at session start.
The 8 providers:
| Provider | Source | Confidence | Latency |
|---|---|---|---|
engram:ast |
Tree-sitter parse (10 languages) | 1.0 | <50ms |
engram:structure |
Regex heuristics (fallback) | 0.85 | <50ms |
engram:mistakes |
Past failure nodes from graph | — | <10ms |
engram:git |
Co-change patterns, churn, authorship | — | <100ms |
mempalace |
Decisions, learnings, project context | — | <5ms cached |
context7 |
Library API docs for detected imports | — | <5ms cached |
obsidian |
Project notes, architecture docs | — | <5ms cached |
engram:lsp |
Live diagnostics captured as mistake nodes | — | on-event |
External providers cache into SQLite at SessionStart. Per-read resolution is a cache lookup, not a live call. If a provider is unavailable it is skipped silently — you always get at least the structural summary.
The 9 hook handlers:
| Hook | What it does |
|---|---|
PreToolUse:Read |
Blocks the read if file is covered. Delivers structural summary as the block reason. |
PreToolUse:Edit |
Passes through. Injects known mistakes as landmine warnings alongside the edit. |
PreToolUse:Write |
Same as Edit — advisory injection only, never blocks writes. |
PreToolUse:Bash |
Catches cat | head | tail | less | more <single-file> and delegates to the Read handler. |
SessionStart |
Injects a compact project brief (god nodes, graph stats, top landmines, git branch). Bundles MemPalace context in parallel. |
UserPromptSubmit |
Extracts keywords from the prompt, runs a budget-capped pre-query, injects results before the agent responds. |
PostToolUse |
Observer only. Writes to .engram/hook-log.jsonl for hook-stats. |
PreCompact |
Re-injects god nodes and active landmines right before Claude compresses the conversation. Survives compaction. |
CwdChanged |
Auto-switches project context when you navigate to a different repo mid-session. |
Ten safety invariants enforced at runtime:
- Any handler error → passthrough (Claude Code is never blocked)
- 2-second per-handler timeout
- Kill switch (
.engram/hook-disabled) respected by every handler - Atomic settings.json writes with timestamped backups
- Never intercept outside the project root
- Never intercept binary files or secrets (
.env,.pem,.key,id_rsa, etc.) - Never log user prompt content (privacy invariant, asserted in tests)
- Never inject more than 8,000 chars per hook response
- Stale graph detection — file mtime newer than graph mtime → passthrough
- Partial-read bypass — explicit
offsetorlimiton Read → passthrough
npm install -g engramxRequires Node.js 20+. Zero native dependencies. No build tools. Local SQLite via sql.js WASM — no Rust, no Python, no system libs.
cd ~/my-project
engram init # scan codebase → .engram/graph.db (~40ms, 0 tokens)
engram install-hook # wire the Sentinel into Claude Code
engram ui # open the web dashboard in your browserOpen a Claude Code session. When the agent reads a well-covered file you will see a system-reminder with the structural summary instead of file contents. After the session:
engram hook-stats # what was intercepted, tokens saved (CLI)
engram ui # same data, richer view, real-time updates
engram hook-preview src/auth.ts # dry-run: see what the hook would inject for one fileFull recommended setup (one-time per project):
npm install -g engramx
cd ~/my-project
engram init --with-skills # also index ~/.claude/skills/ into the graph
engram install-hook # wire Sentinel into Claude Code
engram hooks install # auto-rebuild graph on every git commitExperience tiers — each works standalone:
| Tier | What you run | What you get |
|---|---|---|
| Graph only | engram init |
CLI queries, MCP server, engram gen for CLAUDE.md |
| + Sentinel | engram install-hook |
Automatic Read interception, Edit warnings, session briefs, HUD |
| + Context Spine | Configure providers.json | Rich packets from all 8 providers per read |
| + Skills index | engram init --with-skills |
Graph includes your ~/.claude/skills/ |
| + Git hooks | engram hooks install |
Graph rebuilds on every commit, stays current |
| + HTTP server | engram server --http |
REST API on port 7337 for external tooling |
| IDE | Integration | Setup |
|---|---|---|
| Claude Code | Hook-based interception (native, automatic) | engram install-hook |
| Cursor | MDC snapshot + native MCP | engram gen-mdc · docs/integrations/cursor-mcp.md |
| Continue.dev | @engram context provider |
docs/integrations/continue.md |
| Zed | Context server (/engram) |
engram context-server |
| Aider | Context file generation | engram gen-aider |
| Windsurf (Codeium) | .windsurfrules snapshot + MCP |
engram gen-windsurfrules |
| Neovim | MCP via codecompanion / avante | docs/integrations/neovim.md |
| Emacs | MCP via gptel-mcp | docs/integrations/emacs.md |
Per-IDE setup guides are in docs/integrations/.
| engram | Continue @RepoMap | Cursor .cursorrules | Aider repo-map | @199-bio/engram | |
|---|---|---|---|---|---|
| Interception model | Hook-based, automatic on every Read | Fetched at @-mention time | Static file, manual | Per-session map | MCP server, called explicitly |
| Cache strategy | SQLite at SessionStart, <5ms per read | No cache — live fetch | No cache | Per-session only | No cache |
| Persistent memory | Decisions, mistakes, patterns across sessions | No | Manual text file | No | No |
| Multiple providers | 8 (AST, git, mistakes, MemPalace, Context7, Obsidian, LSP) | Repo structure only | No | Repo structure only | Graph query only |
| Mistake tracking | LSP diagnostics → mistake nodes, |
No | No | No | No |
| Survives compaction | Yes (PreCompact hook) | No | Yes (static file) | No | No |
| LLM cost | $0 | $0 | $0 | $0 | $0 |
| Native deps | Zero | No | No | No | No |
npm install -g engramxproviders.json (optional — auto-detection works for most setups):
{
"providers": {
"mempalace": { "enabled": true },
"context7": { "enabled": true },
"obsidian": { "enabled": true, "vault": "~/vault" },
"lsp": { "enabled": true }
}
}Hook scope options:
engram install-hook # default: .claude/settings.local.json (gitignored)
engram install-hook --scope project # .claude/settings.json (committed)
engram install-hook --scope user # ~/.claude/settings.json (global)
engram install-hook --dry-run # preview changes without writingKill switch (if anything goes wrong):
engram hook-disable # touches .engram/hook-disabled — all handlers pass through
engram hook-enable # removes the kill switch
engram uninstall-hook # surgical removal, preserves other hooks in settings.jsonCore:
engram init [path] # scan codebase, build knowledge graph
engram init --with-skills # also index ~/.claude/skills/
engram query "how does auth" # query the graph (BFS, token-budgeted)
engram query "auth" --dfs # DFS traversal
engram gods # most connected entities
engram stats # node/edge counts, confidence breakdown
engram bench # token reduction benchmark (10 tasks)
engram stress-test # full stress test suite
engram path "auth" "database" # shortest path between concepts
engram learn "chose JWT..." # add a decision or pattern to the graph
engram mistakes # list known landminesCode generation:
engram gen # auto-detect target (CLAUDE.md / .cursorrules / AGENTS.md)
engram gen --target claude # write to CLAUDE.md
engram gen --target cursor # write to .cursorrules
engram gen --target agents # write to AGENTS.md
engram gen --task bug-fix # task-aware view (general | bug-fix | feature | refactor)
engram gen --memory-md # write structural facts to Claude's native MEMORY.md
engram gen-mdc # generate Cursor MDC rules
engram gen-aider # generate Aider context file
engram gen-ccs # generate CCS-compatible outputSentinel:
engram intercept # hook entry point (called by Claude Code, reads stdin)
engram install-hook # install hooks into Claude Code settings
engram uninstall-hook # remove engram entries
engram hook-stats # summarize .engram/hook-log.jsonl
engram hook-stats --json # machine-readable output
engram hook-preview <file> # dry-run Read handler for a specific file
engram hook-disable # kill switch
engram hook-enable # remove kill switchInfrastructure:
engram watch [path] # live file watcher — incremental re-index on save
engram dashboard [path] # live terminal dashboard
engram hud-label [path] # JSON label for Claude HUD --extra-cmd integration
engram hooks install # install post-commit + post-checkout git hooks
engram hooks status # check git hook installation
engram hooks uninstall # remove git hooks
engram server --http # start HTTP REST server on port 7337
engram context-server # start Zed context server
engram tune --dry-run # auto-tune provider weights (preview mode)
engram db status # schema version, migration state
engram init --from-ccs # import from CCS-format context fileClaude HUD integration:
Add --extra-cmd="engram hud-label" to your statusLine command to see live savings:
engram 48.5K saved 75%
Start the server with engram server --http (default port 7337).
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Server health + graph stats |
POST |
/query |
Query the knowledge graph |
GET |
/gods |
Most connected entities |
GET |
/stats |
Node/edge counts, confidence breakdown |
POST |
/path |
Shortest path between two concepts |
GET |
/mistakes |
Known failure nodes |
POST |
/learn |
Add a decision or pattern |
POST |
/init |
Trigger a graph rebuild |
GET |
/hook-stats |
Hook interception log summary |
All responses are JSON. The server is local-only by default — bind address is 127.0.0.1.
{
"mcpServers": {
"engram": {
"command": "npx",
"args": ["-y", "engramx", "serve", "/path/to/your/project"]
}
}
}MCP Tools (6):
query_graph— search the knowledge graph with natural languagegod_nodes— core abstractions (most connected entities)graph_stats— node/edge counts, confidence breakdownshortest_path— trace connections between two conceptsbenchmark— token reduction measurementlist_mistakes— known failure modes from past sessions
Shell wrapper (for Bash-based agents):
cp scripts/mcp-engram ~/bin/mcp-engram && chmod +x ~/bin/mcp-engram
mcp-engram query "how does auth work" -p ~/myrepoengram v1.0 ships the first draft of the Engram Context Protocol (ECP v0.1) — an open specification for how AI coding tools should package and exchange structured context packets.
The spec defines the wire format, provider negotiation, budget constraints, and confidence scoring used by engram internally. Any tool can implement the spec to produce or consume engram-compatible context packets.
License: CC-BY 4.0
Spec: docs/specs/ecp-v0.1.md
import { init, query, godNodes, stats } from "engramx";
const result = await init("./my-project");
console.log(`${result.nodes} nodes, ${result.edges} edges`);
const answer = await query("./my-project", "how does auth work");
console.log(answer.text);
const gods = await godNodes("./my-project");
for (const g of gods) {
console.log(`${g.label} — ${g.degree} connections`);
}src/
├── cli.ts CLI entry point
├── core.ts API surface (init, query, stats, learn)
├── serve.ts MCP server (6 tools, JSON-RPC stdio)
├── server.ts HTTP REST server (port 7337)
├── hooks.ts Git hook install/uninstall
├── autogen.ts CLAUDE.md / .cursorrules / MDC generation
├── graph/
│ ├── schema.ts Types: nodes, edges, confidence, schema versioning
│ ├── store.ts SQLite persistence (sql.js WASM, zero native deps)
│ └── query.ts BFS/DFS traversal, shortest path
├── miners/
│ ├── ast-miner.ts Tree-sitter AST extraction (10 languages, confidence 1.0)
│ ├── git-miner.ts Change patterns from git history
│ ├── session-miner.ts Decisions/patterns from AI session docs
│ └── skills-miner.ts ~/.claude/skills/ indexer (opt-in)
├── providers/
│ ├── context-spine.ts Provider assembly + budget management
│ ├── mempalace.ts MemPalace integration
│ ├── context7.ts Context7 library docs
│ ├── obsidian.ts Obsidian vault
│ └── lsp.ts LSP diagnostic capture
└── intelligence/
└── token-tracker.ts Cumulative token savings measurement
Supported languages (AST): TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, Ruby, PHP.
Everything runs locally. No data leaves your machine. No telemetry. No cloud dependency. The only network call is npm install. Prompt content is never logged (asserted in 579 tests).
Issues and PRs welcome at github.com/NickCirv/engram.
Run engram init on a real codebase and share what it got right and wrong. The benchmark suite (engram bench) is the fastest way to see the difference on your own code.