engram

<p align="center">
  <img src="assets/banner-v3.png" alt="engramx — the universal context spine for AI coding tools (v4.4.0 'Curve')" width="100%">
</p>

<p align="center">
  <strong>Engram makes your AI coding agent stop re-reading the same files — and stop repeating mistakes your repo already fixed.</strong><br>
  <sub>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 <strong>bi-temporal mistakes are auto-captured from your git revert history</strong>, so it stops repeating fixes that already failed. Context packets run ~50–90% smaller per file (structural size, not a bill saving — run <code>engram bench</code> on yours). Local SQLite, zero cloud, Apache 2.0.</sub>
</p>

<p align="center">
  <a href="#try-in-30-seconds-no-install"><strong>Try in 30 seconds (no install) ▶</strong></a>
</p>

<!-- ============================================================
     24-second product showcase (Hyperframes-rendered MP4 + WebM).
     Source: docs/demos/showcase.html · scenes drive both the
     live HTML player and this MP4. Edit scene-table.md to change.
     If the MP4 isn't rendered yet, GitHub gracefully shows the
     poster image and links to the live HTML player.
     ============================================================ -->
<p align="center">
  <video src="https://raw.githubusercontent.com/NickCirv/engram/main/docs/demos/showcase.mp4"
         controls
         muted
         playsinline
         poster="docs/demos/poster.svg"
         width="100%">
    <a href="docs/demos/showcase.html">
      <img src="docs/demos/poster.svg" alt="engram — 24-second showcase (click to open the live HTML player)" width="100%">
    </a>
  </video>
</p>

<p align="center">
  <sub>
    <a href="docs/install.html"><strong>Install Page</strong></a> ·
    <a href="docs/demos/showcase.html"><strong>Live Demo</strong></a> ·
    <a href="docs/demos/scene-table.md"><strong>Scene Table</strong></a> ·
    rendered with <a href="https://github.com/heygen-com/hyperframes">Hyperframes</a>
  </sub>
</p>

<p align="center">
  <a href="#install"><strong>Install</strong></a> ·
  <a href="#quickstart"><strong>Quickstart</strong></a> ·
  <a href="#dashboard"><strong>Dashboard</strong></a> ·
  <a href="#benchmark"><strong>Benchmark</strong></a> ·
  <a href="#ide-integrations"><strong>IDE Integrations</strong></a> ·
  <a href="#http-api"><strong>HTTP API</strong></a> ·
  <a href="#ecp-spec"><strong>ECP Spec</strong></a> ·
  <a href="#contributing"><strong>Contributing</strong></a>
</p>

<p align="center">
  <a href="https://github.com/NickCirv/engram/actions"><img src="https://github.com/NickCirv/engram/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/engramx"><img src="https://img.shields.io/npm/v/engramx?color=blue&label=engramx" alt="npm engramx"></a>
  <a href="https://www.npmjs.com/package/engramx-continue"><img src="https://img.shields.io/npm/v/engramx-continue?color=blue&label=engramx-continue" alt="npm engramx-continue"></a>
  <a href="https://open-vsx.org/extension/nickcirv/engram-vscode"><img src="https://img.shields.io/open-vsx/v/nickcirv/engram-vscode?color=blue&label=OpenVSX" alt="OpenVSX engram-vscode"></a>
  <img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License">
  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node">
  <img src="https://img.shields.io/badge/tests-1167%20passing-brightgreen" alt="Tests">
  <img src="https://img.shields.io/badge/per--file%20reduction-53--89%25-orange" alt="53-89% per-file structural reduction">
  <img src="https://img.shields.io/badge/native%20deps-zero-green" alt="Zero native deps">
  <img src="https://img.shields.io/badge/LLM%20calls-0-green" alt="engram makes zero LLM calls">
</p>

---

## Try in 30 seconds (no install)

<p align="center">
  <a href="https://asciinema.org/a/GjjvPXVyArnivAog">
    <img src="https://asciinema.org/a/GjjvPXVyArnivAog.svg" alt="engram v4.0 demo — bi-temporal mistakes auto-captured from git revert (30 seconds)" width="100%">
  </a>
</p>

<p align="center">
  <sub>▶ <a href="https://asciinema.org/a/GjjvPXVyArnivAog"><strong>Play the live recording</strong></a> · or get the raw cast at <a href="docs/demos/v4-skill-pack.cast"><code>docs/demos/v4-skill-pack.cast</code></a> (<code>asciinema play</code>) · or generate it yourself with <a href="docs/demos/v4-skill-pack-demo.sh"><code>v4-skill-pack-demo.sh</code></a></sub>
</p>

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.4.0 init . && \
  npx --yes engramx@4.4.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 <sha> (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.4.0 "Curve" — 2026-06-14.** New: **`engram measure --session`** proves the *combined* whole-session structural reduction by replaying your hook-log as an honest per-session break-even-P curve (Token-loop C). The recall bench now ships **confidence intervals** and counts import edges (it was under-measuring). Honest, repo-dependent numbers: **recall@10 ≈ 43% / 17% / 25%** (own repo / a mature external library / an app), with the ranker beating random ordering by **+5.6pp / +4.4pp / ~0** respectively. Run `engram bench` on yours — and note the durable wins are the **mistakes memory + capacity**, not a recall number. Plus: `query`/`gen` fail loudly on a bad `--project`, a hermetic skills test, and a front door that leads with the differentiator, not the number. Still no cost claims — a structural reduction, not a bill saving.
>
> **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 t