engramx 2.0.2 → 3.0.0

package/CHANGELOG.md

@@ -4,6 +4,277 @@ All notable changes to engram are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [3.0.0] — 2026-04-24 — "Spine"
+
+The biggest engramx release since v1.0. One meticulous release, not a
+staircase — per the decision log at `~/Desktop/Projects/Engram/00-strategy/decisions/`
+(single-release-vs-staircase + engramx-canonical-brand).
+
+Headline: engramx becomes the **extensible context spine**. Any MCP
+server plugs in via a 10-line plugin file; every provider's output is
+budget-weighted, mistake-boosted, and streamed progressively via SSE;
+the mistakes moat grows two new capabilities (bi-temporal validity +
+pre-mortem warnings); `engram gen` emits both `CLAUDE.md` AND `AGENTS.md`
+by default. **Real-world benchmark: 89.1% measured savings** on engramx's
+own 87-file sample (committed report in `bench/results/`).
+
+Contributor credit: [@mechtar-ru](https://github.com/mechtar-ru) for PR #6
+(OOM fixes on large codebases — cherry-picked with preserved authorship).
+
+### Added — v3.0 "Spine" track
+
+**Pillar 1 — Capabilities to add to it (extensibility foundation)**
+- **Generic MCP-client aggregator** (`src/providers/mcp-client.ts`). Spawn or HTTP-connect to any MCP server, cache tool lists, call tools with timeout + retry, normalize into `ProviderContext`. Config at `~/.engram/mcp-providers.json`. Per-provider budgets, graceful degradation, process shutdown hooks. Uses `@modelcontextprotocol/sdk` v1.29 behind an internal abstraction so future SDK v2 migration is a single-file swap. Stdio transport ships; HTTP path stubbed pending post-3.0 Host/Origin hardening integration.
+- **Provider plugin contract v2** (`src/providers/plugin-loader.ts`). Plugins declaring an `mcpConfig` instead of a custom `resolve()` are auto-wrapped via `createMcpProvider()`. Classic plugins with hand-rolled `resolve()` still work unchanged. Custom `resolve()` wins if both are present. 10-line plugins are now possible.
+- **Budget-weighted resolver + mistakes-boost reranking** (`src/providers/resolver.ts`). Per-provider token budgets enforced as a backstop even if a provider ignores its contract. Results whose content mentions a known-mistake label get confidence × 1.5 (capped at 1.0) — boost breaks ties within a priority tier without overriding priority across tiers. Case-insensitive label matching.
+
+**Pillar 2 — Save proper context**
+- **Anthropic Auto-Memory bridge** (`src/providers/anthropic-memory.ts`). Reads Claude Code's auto-managed `~/.claude/projects/<encoded>/memory/MEMORY.md` index, surfaces entries scored against the current file's basename / imports / path segments. Tier 1, runs under 10 ms, max 1 MB hard-cap on index size. Override via `ENGRAM_ANTHROPIC_MEMORY_PATH` for tests + advanced users. Inserted at `PROVIDER_PRIORITY[3]` between mistakes and mempalace.
+- **Streaming partial context packets via SSE** (`/context/stream?file=<path>` endpoint + `resolveRichPacketStreaming()` generator). Emit one SSE frame per provider as it resolves. Matches MCP SEP-1699: every frame carries an `id:` for `Last-Event-ID` resumption on reconnect. Client disconnect mid-stream aborts the generator cleanly. Inherits existing auth + Host + Origin guards.
+- **Serena plugin reference** at `docs/plugins/examples/serena-plugin.mjs` (10-line mcpConfig plugin — install instructions in `docs/plugins/README.md`).
+
+**Pillar 3 — Really help users (mistakes moat)**
+- **Bi-temporal validity on mistake nodes**: schema migration 8 adds `valid_until` and `invalidated_by_commit` columns plus a partial index `idx_nodes_validity`. Mistakes whose `validUntil` is in the past are filtered out by the `engram:mistakes` provider. Backward-compatible: legacy rows without the columns keep firing (NULL = still valid).
+- **Pre-mortem mistake-guard** (`src/intercept/handlers/mistake-guard.ts`). Opt-in via `ENGRAM_MISTAKE_GUARD=1` (permissive: warns via `additionalContext`) or `=2` (strict: denies the tool call). Matches Edit/Write against the file's mistake nodes via indexed `getNodesByFile`; matches Bash against `metadata.commandPattern` substrings and `sourceFile` mentions in the command. Respects the bi-temporal filter. Zero overhead when unset.
+
+**Hygiene / ecosystem**
+- `engram gen` emits BOTH `CLAUDE.md` AND `AGENTS.md` by default (Linux Foundation universal agent-instructions standard; adopted by Codex CLI, Cursor, Windsurf, Copilot, Junie, Antigravity). Explicit `--target=claude|cursor|agents` preserves single-file behavior.
+- README opens with **"What engramx is not"** section — disarms collision with Go-Engram (Gentleman-Programming/engram), DeepSeek's "Engram" paper (Jan 2026), and MemPalace in the first 30 seconds of any new visitor read.
+- PR #6 (`@mechtar-ru`) cherry-picked ourselves with preserved authorship: `MAX_DEPTH=100` in ast-miner's directory walk, `MAX_FILES_PER_COMMIT=50` in git-miner's co-change analysis, expanded default skip dirs. Dead-code cleanup of duplicate `DEFAULT_EXCLUDED_DIRS` / `loadEngramIgnore` that had shipped alongside v2.1's newer `DEFAULT_SKIP_DIRS` / `loadIgnorePatterns`. Closes issue #5.
+
+### Proof — real-world benchmark (new, committed)
+
+`bench/real-world.ts` runs the full resolver pipeline against the repo's own source tree and compares rich-packet tokens to raw-file-read tokens. Latest run (2026-04-24, 100-file scale-out, 87 files actually sampled after skip rules):
+
+| Metric | Value |
+|---|---|
+| Baseline tokens (raw Read of every file) | 163,122 |
+| engramx tokens (rich packets) | 17,722 |
+| Aggregate savings | **89.1%** |
+| Median per-file savings | 84.2% |
+| Files where engramx saved tokens | 85 of 87 |
+| Best case (`src/cli.ts`) | 98.4% (18,820 → 306) |
+
+Reproducible by anyone, on any project: `npx tsx bench/real-world.ts --project . --files 50`.
+
+### Changed
+
+- `autogen()` return type: `{ file: string }` → `{ files: string[] }` (single caller in `cli.ts` updated). Consumers of the programmatic API who called `result.file` must read `result.files[0]` instead (or use `--target` to keep single-file semantics).
+- `PROVIDER_PRIORITY` gains `anthropic:memory` at index 3 — downstream test that hard-coded the array order was updated.
+- `MIGRATIONS` (src/db/migrate.ts): extended from `Record<number, string>` to `Record<number, string | ((db) => void)>` so migrations that need non-idempotent DDL (like `ALTER TABLE ADD COLUMN`) can guard with `PRAGMA table_info` checks.
+- README badge updates: tests 640 → 876, providers 8 → 9, savings 88.1% → 90.8%.
+
+### Migration
+
+**v2.1 → v3.0 is schema-migration-required and automatic**: first open of your existing `.engram/graph.db` triggers migration 8. A `.bak-v7` backup is written alongside. Legacy mistake rows survive unchanged (NULL `validUntil` = still valid). Verified on a simulated v2.1 DB during release audit.
+
+**API consumers of `autogen()`** must update call sites: `result.file` (single string) → `result.files` (array). CLI callers are unaffected.
+
+### Tests
+
+771 → 876 passing (+105 new). CI green Ubuntu+Windows × Node 20+22. TypeScript `--noEmit` clean, lint clean.
+
+## [2.1.0] — 2026-04-21 — "Reliability + Zero-Friction Install"
+
+First release in the v2.1 / v2.2 / v3.0 elevation trilogy. Design spec
+at `docs/superpowers/specs/2026-04-20-engram-elevation-trilogy-design.md`.
+
+Headline: `engram setup` is the new one-command first-run flow. Users
+go from `npm install -g engramx` to a working Sentinel hook + indexed
+graph in under 30 seconds. `engram doctor` reports component health
+with remediation hints. `engram update` ships future hotfixes to every
+install without surprise — passive notify, zero telemetry, one-command
+upgrade. Plus fixes for issue #11 (AST/LSP path bug in flattened
+bundles) and issue #14's Bash-ops half (auto-reindex on `rm`/`mv`/
+`git rm` via an opt-in PostToolUse gate).
+
+Contributor credit this release: [@gabiudrescu](https://github.com/gabiudrescu)
+for PR #13 (reindex CLI + `install-hook --auto-reindex`), PR #12
+(watcher prune on delete/rename), and the original v2.0.2 security
+disclosure. [@ttessarolo](https://github.com/ttessarolo) for precise
+forensics + suggested fix on issue #11.
+
+### Added — v2.1 "Reliability + Zero-Friction Install" track
+
+- **`engram update`** — one-command self-upgrade.
+  Passive notify on every `engram *` invocation when a newer version is
+  available (cached, at most one line on stderr, throttled to a 7-day
+  registry check). Manual trigger detects the package manager that owns
+  the engram install (npm / pnpm / yarn / bun via install-path markers)
+  and shells out to its global-upgrade command. `--check` for dry-probe,
+  `--force` to bypass the 7-day throttle, `--dry-run` to print the
+  upgrade command without executing it, `--manager <mgr>` override.
+  Zero telemetry: the only network call is an anonymous GET to
+  `registry.npmjs.org/engramx/latest`. `ENGRAM_NO_UPDATE_CHECK=1` and
+  `$CI` disable the entire subsystem. Addresses the "1,300 weekly
+  downloads, 10/day organic, near-zero hotfix reach" problem.
+
+- **`engram doctor`** — component health report with remediation hints.
+  Wraps existing probes (HTTP, LSP, AST, IDE adapters) plus four new
+  checks: engram version freshness, `.engram/graph.db` presence,
+  Sentinel hook installation, IDE adapter count. Each check emits
+  severity (ok / warn / fail) + detail + optional remediation. Exit
+  code reflects overall severity (0 ok, 1 warn, 2 fail) so `doctor`
+  is CI-friendly. `--verbose` shows remediation hints; `--json` /
+  `--export` emits redacted JSON for bug-report attachment
+  (`projectRoot` intentionally omitted — can contain usernames).
+
+- **`engram setup`** — zero-friction first-run wizard. One command for
+  "go from cloned repo to working engram in under 30 seconds."
+  Runs `init` (if `.engram/graph.db` missing) → `install-hook` (with
+  prompted scope, `local` default) → detects IDE adapters (Cursor,
+  Windsurf, Continue.dev, Aider) and suggests the matching `gen-*`
+  command for each → finishes with a `doctor` summary. Each step is
+  idempotent. `--yes` runs with defaults; `--dry-run` prints intent
+  without acting; `--scope` controls the install-hook scope. Drops
+  install-to-first-value from 4 commands to 1.
+
+- **`engram init --with-hook`** — shorthand for `init` followed by
+  `install-hook` (local scope, idempotent). The #1 thing every user
+  does after `init` was `install-hook`; now it's one step.
+
+- **First-run hint.** On any `engram` subcommand invoked in a repo
+  lacking `.engram/graph.db`, print one line on stderr:
+  `💡 First time in this repo? Run 'engram setup' for a zero-friction install.`
+  Throttled via `~/.engram/first-run-shown` (fires once per machine,
+  not per repo). Silenced in `$CI`, under `ENGRAM_NO_UPDATE_CHECK=1`,
+  and under the JSON-stdout commands (`intercept`, `cursor-intercept`,
+  `hud-label`, `setup`, `init`, `update`, `doctor`) so neither
+  pollutes the hook protocol.
+
+- **Bash PostToolUse parser for auto-reindex** — closes half of
+  [#14](https://github.com/NickCirv/engram/issues/14).
+  `src/intercept/handlers/bash-postool.ts` parses file-mutating Bash
+  commands (`rm`, `mv`, `cp`, `git rm`, `git mv`, single-redirect
+  `<cmd> > <dst>`) into `FileOp { action, path }` records. Strict
+  parser: globs, pipes, subshells, command-substitution, directory
+  ops, and `touch` all pass through untouched. Wired into the
+  PostToolUse observer path in `handlers/post-tool.ts` — on Bash
+  PostToolUse events, each op is handed to `syncFile()` fire-and-forget.
+  Gated by `ENGRAM_AUTO_REINDEX=1` opt-in until
+  [#13](https://github.com/NickCirv/engram/pull/13)'s install-hook
+  `--auto-reindex` flag lands; that flag will toggle the env gate
+  implicitly.
+
+### Fixed — v2.1 reliability
+
+- **AST grammar detection in flattened bundles**
+  ([#11](https://github.com/NickCirv/engram/issues/11) partial).
+  When `tsup`/`esbuild` flattens chunks to `engramx/dist/chunk-*.js`,
+  `import.meta.url` resolves to `engramx/dist` and the previous
+  candidates (`../grammars` and `../../dist/grammars`) both missed the
+  actual grammar dir. Added `join(here, "grammars")` as the first
+  candidate; dev-time layout (`src/intercept/`) still works via the
+  third candidate. Thanks [@ttessarolo](https://github.com/ttessarolo).
+
+- **LSP socket candidate coverage**
+  ([#11](https://github.com/NickCirv/engram/issues/11) partial).
+  `checkLsp` was looking for two socket names while
+  `lsp-connection.ts::candidateSockets()` probes six. Synced the list
+  so HUD availability matches actual provider availability. Kept
+  `.engram/lsp-available` as an explicit user opt-in marker for
+  back-compat.
+
+### Fixed
+
+- **Locale-independent number formatting across the codebase.** All 10
+  `Number.prototype.toLocaleString()` callsites in `src/cli.ts`,
+  `src/serve.ts`, `src/dashboard.ts`, and `src/intercept/stats.ts` have
+  been migrated to a shared `formatThousands()` helper in
+  `src/graph/render-utils.ts`. Two wins:
+
+  1. **Deterministic performance.** First-call ICU init on Windows Node
+     has been observed to take multiple seconds in GitHub Actions VMs,
+     flaking tests at the 5000ms default timeout (seen on
+     `tests/intercept/stats.test.ts > formatStatsSummary` post-merge on
+     `9f99f5b`). The regex-based helper runs in microseconds with no
+     ICU dependency.
+  2. **Locale independence.** `toLocaleString()` emits `"1,234"` on
+     en-US but `"1.234"` on de-DE and `"1 234"` on fr-FR, giving users
+     running engram in non-US shells inconsistent output. All CLI +
+     MCP server + dashboard numbers now render with commas regardless
+     of system locale.
+
+  Added `tests/render-utils.test.ts > formatThousands` — 6 tests
+  covering single-digit, multi-group, negative, and locale-stable cases.
+  Also added `vitest.config.ts` with CI-only `retry: 1` +
+  `testTimeout: 15000ms` as defense-in-depth against other cold-worker
+  flakes.
+
+- **`engram watch` now prunes graph nodes when watched files are deleted
+  or renamed** ([#9](https://github.com/NickCirv/engram/issues/9),
+  [#12](https://github.com/NickCirv/engram/pull/12)). Previously the
+  watcher only subscribed to `change` events, silently ignoring the
+  `rename` events that `fs.watch` fires for create/unlink across all
+  platforms. Deletions left stale nodes in the graph until the next
+  `engram init`; renames produced duplicate nodes under the old and new
+  `sourceFile` paths. Thanks [@gabiudrescu](https://github.com/gabiudrescu).
+
+### Added
+
+- **`syncFile(absPath, root)`** exported from `src/watcher.ts` — the shared
+  "exists → reindex; gone (and was indexed) → prune" primitive reused by
+  the upcoming `engram reindex` CLI subcommand ([#8](https://github.com/NickCirv/engram/issues/8)).
+  Returns a discriminated `SyncResult` (`indexed` | `pruned` | `skipped`).
+- **`GraphStore.countBySourceFile(relPath)`** — noise-reduction gate so
+  `onDelete` only fires for files the graph actually indexed.
+- **`onDelete` callback on `WatchOptions`** — fires with `(filePath, prunedCount)`
+  when the watcher prunes a deleted file's nodes.
+- **`× <path> pruned (N nodes)`** log line in `engram watch`, distinct from
+  the existing green `↻` reindex line.
+- **`gen-cursor --watch`, `gen-aider --watch`, `gen-windsurfrules --watch`**
+  now regenerate their output files on source-file delete (not just on
+  reindex), so generated artifacts no longer keep stale references to
+  deleted sources.
+- **`engram reindex <file>` CLI subcommand**
+  ([#8](https://github.com/NickCirv/engram/issues/8)) — re-indexes a
+  single file into the knowledge graph. The missing primitive for per-
+  edit freshness: Claude Code PostToolUse hooks, editor plugins, and CI
+  can now keep the graph in sync without running a long-lived watcher.
+  Reuses `syncFile()` so semantics match `engram watch`: exists →
+  reindex; missing-but-previously-indexed → prune; unsupported ext or
+  ignored directory → silent exit 0 (safe to fire on every edit). On
+  success prints a single line `engram: reindexed <file> (<N> nodes)`
+  (or `pruned`) using locale-stable `formatThousands`. `--verbose`
+  surfaces stack traces; default error output is a single stderr line.
+  Missing graph exits 1 with `engram: no graph found at <root>. Run
+  'engram init' first.`, matching `engram watch`.
+- **`formatReindexLine(result, displayPath)`** exported from
+  `src/watcher.ts` — pure formatter shared by the new subcommand. Returns
+  `null` for skipped results so callers stay silent.
+- **`engram reindex-hook` subcommand + `engram install-hook --auto-reindex`**
+  ([#8](https://github.com/NickCirv/engram/issues/8), opt-in auto-wire).
+  `reindex-hook` reads Claude Code's PostToolUse payload from stdin and
+  re-indexes `tool_input.file_path` via the shared `syncFile()` primitive.
+  Contract: ALWAYS exits 0 — malformed JSON, missing fields, non-project
+  `cwd`, and all internal errors resolve to a silent no-op so the hook
+  can never fail Claude Code's tool cycle. `install-hook --auto-reindex`
+  appends a second PostToolUse entry with matcher `Edit|Write|MultiEdit`
+  calling `engram reindex-hook`; off by default so existing users aren't
+  surprised. The new entry is recognized by `isEngramHookEntry()` so
+  `engram uninstall-hook` strips it alongside the primary intercept
+  entries. Idempotent — reinstalling with `--auto-reindex` is a no-op
+  when the entry already exists.
+- **`runReindexHook(payload)`** exported from `src/watcher.ts` — the
+  pure async handler behind the `reindex-hook` subcommand. Validates
+  payload shape, resolves project root from `cwd`, delegates to
+  `syncFile`. Swallows every error.
+- **`buildReindexHookEntry()` + `ENGRAM_REINDEX_HOOK_MATCHER`
+  (`"Edit|Write|MultiEdit"`) + `DEFAULT_ENGRAM_REINDEX_HOOK_COMMAND`
+  (`"engram reindex-hook"`)** exported from `src/intercept/installer.ts`
+  — the data primitives for the optional entry. Added
+  `InstallOptions.autoReindex` and `InstallResult.autoReindexAdded` to
+  thread the opt-in through the existing installer surface.
+
+### Notes
+
+- Directory deletion (`rm -rf src/foo`) is intentionally not handled by the
+  watcher — `fs.watch` fires a single rename event on the directory path
+  with no per-file information. A full `engram init` handles that case
+  today; per-file directory-prefix pruning is tracked for v2.2.
+
 ## [2.0.2] — 2026-04-18 — Security hotfix: HTTP server auth & CORS
 
 **This is a security release. Upgrade immediately if you run `engram server`

package/README.md

@@ -1,5 +1,34 @@
 <p align="center">
-  <img src="assets/banner.png" alt="engram — AI coding memory" width="100%">
+  <img src="assets/banner-v3.png" alt="EngramX — the cached context spine for AI coding agents (v3.0 'Spine')" width="100%">
+</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">
@@ -18,33 +47,96 @@
   <a href="https://www.npmjs.com/package/engramx"><img src="https://img.shields.io/npm/v/engramx?color=blue" alt="npm version"></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-640%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/providers-8%20%2B%20plugins-blue" alt="8 Providers + plugins">
-  <img src="https://img.shields.io/badge/token%20savings-88.1%25%20measured-orange" alt="88% Proven Savings">
+  <img src="https://img.shields.io/badge/tests-876%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/providers-9%20%2B%20plugins-blue" alt="9 Providers + plugins">
+  <img src="https://img.shields.io/badge/token%20savings-90.8%25%20measured-orange" alt="90.8% measured savings">
   <img src="https://img.shields.io/badge/native%20deps-zero-green" alt="Zero native deps">
   <img src="https://img.shields.io/badge/LLM%20cost-$0-green" alt="Zero LLM cost">
 </p>
 
 ---
 
-> **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 cache` CLI, 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](CHANGELOG.md) for the full diff.
+> **EngramX v3.0 "Spine" shipped 2026-04-24** — the biggest release since v1.0. The spine is now **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. **89.1% measured real-world token savings** on 87 source files — reproducible in one command. 878 tests, CI green on Ubuntu + Windows × Node 20 + 22. Zero cloud, zero telemetry. See [CHANGELOG.md](CHANGELOG.md) for the full diff.
 
 ---
 
-# The context spine for AI coding agents.
+# 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-pays for context you've already paid for.
+
+**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.
 
-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.
+The agent gets what it needs. You stop paying for context you've already paid for. And **every plugin you add elevates the savings further** — Serena for LSP symbols, GitHub MCP for issue context, Sentry MCP for production errors, Supabase / Neon for schema. Each one closes another context leak the agent would otherwise burn tokens researching.
 
-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.
+**Measured savings on a reproducible benchmark: 89.1%.** Not estimated. 85 of 87 real source files saved tokens. Best case 98.4% (18,820 tokens → 306).
+
+### One command to everything
 
 ```bash
 npm install -g engramx
 cd ~/my-project
-engram init
-engram install-hook
+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 charging you for the same information 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, pays for every byte in tokens, 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. Your monthly AI bill drops. Multi-hour sessions stop hitting rate limits. The agent stops re-introducing bugs you already fixed — because EngramX remembers what broke.
+
+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 even bigger savings?** Install a plugin. Each one closes a different context leak — see [Plugins multiply the savings](#plugins-multiply-the-savings) below. Drop a 10-line `.mjs` file in `~/.engram/plugins/` and the next session uses it.
+
+---
+
+## Proof, not promises
+
+Everything above is measured, not estimated. `bench/real-world.ts` runs the full resolver against real files in this repo and compares the rich-packet token cost to the raw-file-read cost. Reproducible in one command on any project.
+
+Latest run (2026-04-24, 87 source files — full report at [`bench/results/real-world-2026-04-24.md`](bench/results/real-world-2026-04-24.md)):
+
+| Metric | Value |
+|---|---|
+| Baseline tokens (87 files read raw) | **163,122** |
+| engramx tokens (rich packets) | **17,722** |
+| Aggregate savings | **89.1%** |
+| Median per-file savings | 84.2% |
+| Files where engramx saved tokens | 85 of 87 |
+| Best case (`src/cli.ts`) | 98.4% (18,820 → 306) |
+
+Reproduce on your own code:
+
+```bash
+cd your-project
+engram init                          # first-time setup for this project
+npx tsx /path/to/engram/bench/real-world.ts --project . --files 50
 ```
 
-That'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.
+The bench writes a JSON + Markdown report per run into `bench/results/`. Small projects score lower; dense structural projects score higher. It's real arithmetic on your files — you can audit every number.
+
+---
+
+## What engramx is not
+
+The "engram" name is contested. To save you a search:
+
+- **Not Go-Engram** ([Gentleman-Programming/engram](https://github.com/Gentleman-Programming/engram)) — different project, Go binary, salience-gated chat memory. Ships under `engram` (without the `x`).
+- **Not DeepSeek's "Engram" paper** — January 2026 academic work on conditional memory. Research artifact, not a product.
+- **Not MemPalace** — adjacent positioning ("knowledge-graph memory," "method-of-loci"), but conversational memory, not code-structural.
+
+`engramx` is specifically: **a local-first context spine for AI coding agents that hooks into your IDE's tool boundary, indexes your code via tree-sitter + LSP, remembers past mistakes, and assembles ~500-token context packets in place of raw file reads.** Open source, Apache 2.0, single npm install.
 
 ---
 
@@ -99,6 +191,14 @@ See also the **Sessions** tab (cumulative breakdown + sparkline) in [`assets/scr
 
 ## Benchmark
 
+engramx ships with two benchmarks — use whichever fits your workflow.
+
+### Real-world bench (new in v3.0, preferred)
+
+`npx tsx bench/real-world.ts --project . --files 50` runs the full resolver against real files in any project and outputs exact token numbers. See the [Proof](#proof-not-promises) section above for the reproducible 89.1% result on engramx itself.
+
+### Structured task bench (CI regression)
+
 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 |
@@ -115,28 +215,46 @@ Measured across 10 structured coding tasks against a baseline of reading the rel
 | 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.
+Run it yourself: `npx tsx bench/runner.ts` (structured fixtures) or `npx tsx bench/real-world.ts` (live resolver on real files).
+
+---
+
+## Plugins multiply the savings
+
+The 89.1% number is engramx with its 9 built-in providers. Every MCP server you plug in closes another context gap the agent would otherwise burn tokens researching. And because every provider is budget-capped and the resolver is budget-weighted + mistakes-boost reranked, more plugins = more *relevant* context without packet bloat.
+
+| Plugin | Closes this gap | Install |
+|---|---|---|
+| **Serena** (LSP symbols, 20+ languages) | Cross-file references engramx's AST can't resolve precisely — kills the grep-then-read loop | `cp docs/plugins/examples/serena-plugin.mjs ~/.engram/plugins/` |
+| **GitHub MCP** (issues, PRs, commits) | Recent PR discussion & issue history for the file being edited | `engram plugin install github` |
+| **Sentry MCP** (production errors) | "What broke in prod for this file" — cuts the open-dashboard → paste-trace loop | `engram plugin install sentry` |
+| **Supabase / Neon** (schema, RLS) | Database schema context when editing queries / migrations / ORM models | `engram plugin install supabase` |
+| **Context7** (library docs) | Always-current API surface for your actual imports | shipped as a built-in |
+| **Anthropic Auto-Memory** | Claude Code's own consolidated project memory | shipped — auto-detected when `~/.claude/projects/…/memory/MEMORY.md` exists |
+
+Writing a plugin is **~10 lines** — see [`docs/plugins/README.md`](docs/plugins/README.md) for the full spec + examples.
 
 ---
 
 ## What It Does
 
-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.
+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 9 built-in providers plus any plugins you've added, all pre-cached at session start.
 
-**The 8 providers:**
+**The 9 built-in providers (v3.0):**
 
 | 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:mistakes` | Past failure nodes (bi-temporal — stale mistakes filtered out) | — | <10ms |
+| `anthropic:memory` | Claude Code's auto-managed `MEMORY.md` index (v3.0) | 0.85 | <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.
+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. **Plus: any MCP server becomes a provider via a 10-line plugin file** — see [Plugins multiply the savings](#plugins-multiply-the-savings) above.
 
 **The 9 hook handlers:**
 
@@ -175,10 +293,23 @@ npm install -g engramx
 
 Requires Node.js 20+. Zero native dependencies. No build tools. Local SQLite via sql.js WASM — no Rust, no Python, no system libs.
 
+> **Prefer a designed walkthrough?** Open [**docs/install.html**](docs/install.html) — three-step install, benefits matrix, IDE coverage, FAQ. Local file, opens in any browser. Brand-matched terminal-mono aesthetic.
+
 ---
 
 ## Quickstart
 
+**One command, zero friction:**
+
+```bash
+cd ~/my-project
+engram setup                     # init + install-hook + adapter detect + doctor
+```
+
+`engram setup` runs the whole first-run flow interactively (or pass `-y` for defaults, `--dry-run` to preview). It is idempotent — safe to re-run, and skips any step already done.
+
+<sub>Prefer the individual commands?</sub>
+
 ```bash
 cd ~/my-project
 engram init                      # scan codebase → .engram/graph.db (~40ms, 0 tokens)
@@ -186,6 +317,16 @@ engram install-hook              # wire the Sentinel into Claude Code
 engram ui                        # open the web dashboard in your browser
 ```
 
+**Diagnostics + self-update:**
+
+```bash
+engram doctor                    # component health + remediation hints (0=ok, 1=warn, 2=fail)
+engram update                    # check + upgrade via detected pkg manager (no telemetry)
+engram update --check            # check only, dry-probe the registry
+```
+
+Set `ENGRAM_NO_UPDATE_CHECK=1` to disable the passive "newer version available" hint on every CLI invocation. `$CI` does the same automatically.
+
 Open 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:
 
 ```bash
@@ -210,7 +351,7 @@ engram hooks install             # auto-rebuild graph on every git commit
 |------|-------------|-------------|
 | 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 |
+| + Context Spine | Configure providers.json | Rich packets from 9 built-ins + any MCP plugin 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 |
@@ -275,6 +416,7 @@ engram install-hook                  # default: .claude/settings.local.json (git
 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 writing
+engram install-hook --auto-reindex   # also keep the graph fresh after every Edit/Write/MultiEdit (#8)
 ```
 
 **Kill switch (if anything goes wrong):**
@@ -336,6 +478,8 @@ engram hook-enable               # remove kill switch
 
 ```bash
 engram watch [path]              # live file watcher — incremental re-index on save
+engram reindex <file>            # re-index one file (editor/hook/CI primitive, issue #8)
+engram reindex-hook              # PostToolUse hook entry point (reads JSON from stdin, always exits 0)
 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

package/dist/{aider-context-BC5R2ZTA.js → aider-context-6IDE3R7U.js}

@@ -7,7 +7,7 @@ function buildSection(heading, lines) {
   return [`## ${heading}`, "", ...lines, ""].join("\n");
 }
 async function generateAiderContext(projectRoot) {
-  const { getStore } = await import("./core-6IY5L6II.js");
+  const { getStore } = await import("./core-77F2BVYV.js");
   const store = await getStore(projectRoot);
   try {
     const allNodes = store.getAllNodes();

package/dist/check-2Z3MPZEJ.js

@@ -0,0 +1,12 @@
+import {
+  cachePath,
+  checkForUpdate,
+  isNewer,
+  optedOut
+} from "./chunk-RM2TBOVW.js";
+export {
+  cachePath,
+  checkForUpdate,
+  isNewer,
+  optedOut
+};