engramx 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -6,6 +6,76 @@ All notable changes to engram are documented here. Format based on
 
 ## [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

package/README.md

@@ -1,5 +1,5 @@
 <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>
 
 <!-- ============================================================
@@ -47,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.
 
-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.
+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.
 
-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.
+**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. 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.
+
+**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 full setup. The next Claude Code session starts with a project brief already loaded, file reads intercepted, and a live HUD showing cumulative savings.
+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
+```
+
+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.
 
 ---
 
@@ -128,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 |
@@ -144,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:**
 
@@ -262,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 |

package/dist/{aider-context-J557IHIP.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-TSXA5XZH.js");
+  const { getStore } = await import("./core-77F2BVYV.js");
   const store = await getStore(projectRoot);
   try {
     const allNodes = store.getAllNodes();

package/dist/{chunk-PEH54LYC.js → chunk-645NBY6L.js}

@@ -1,7 +1,12 @@
 // src/db/migrate.ts
 import { existsSync, copyFileSync } from "fs";
-var CURRENT_SCHEMA_VERSION = 7;
+var CURRENT_SCHEMA_VERSION = 8;
 var DOWN_MIGRATIONS = {
+  // v3.0: bi-temporal mistake validity. SQLite only added DROP COLUMN in
+  // 3.35 (2021); older sql.js builds may not support it. We don't depend
+  // on the columns being absent — leaving them in place is safe. The index
+  // CAN be dropped cleanly.
+  8: `DROP INDEX IF EXISTS idx_nodes_validity;`,
   7: `DROP TABLE IF EXISTS query_cache; DROP TABLE IF EXISTS pattern_cache;`,
   6: `DROP TABLE IF EXISTS engram_config;`,
   5: `DROP TABLE IF EXISTS provider_cache;`,
@@ -14,6 +19,13 @@ var DOWN_MIGRATIONS = {
   // 1 → 0 drops the entire schema. We require `engram init` for that.
   1: `DROP TABLE IF EXISTS stats; DROP TABLE IF EXISTS edges; DROP TABLE IF EXISTS nodes;`
 };
+function addColumnIfMissing(db, table, column, ddl) {
+  const result = db.exec(`PRAGMA table_info(${table})`);
+  const existing = (result[0]?.values ?? []).map((row) => row[1]);
+  if (!existing.includes(column)) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${ddl}`);
+  }
+}
 var MIGRATIONS = {
   // v0.1.0: Initial schema
   1: `
@@ -85,7 +97,28 @@ CREATE TABLE IF NOT EXISTS pattern_cache (
   graph_version INTEGER NOT NULL,
   hit_count INTEGER NOT NULL DEFAULT 0
 );
-CREATE INDEX IF NOT EXISTS idx_query_cache_file ON query_cache(file_path);`
+CREATE INDEX IF NOT EXISTS idx_query_cache_file ON query_cache(file_path);`,
+  // v3.0.0: Bi-temporal validity for mistake nodes (and any other node kind
+  // that wants it). `valid_until` is the unix-ms timestamp after which the
+  // mistake should NO LONGER surface in context (e.g. the referenced code
+  // was refactored away). NULL = still valid (back-compat default for all
+  // existing rows). `invalidated_by_commit` records the git SHA that caused
+  // the invalidation, for audit + future "explain why this mistake stopped
+  // firing" UX. Index is partial — only mistakes with an explicit validity
+  // window pay storage cost.
+  //
+  // Function-based because ALTER TABLE ADD COLUMN isn't idempotent in
+  // SQLite — re-running on a db that already has the columns throws
+  // 'duplicate column name'. We pre-check via PRAGMA table_info.
+  8: (db) => {
+    addColumnIfMissing(db, "nodes", "valid_until", "valid_until INTEGER");
+    addColumnIfMissing(db, "nodes", "invalidated_by_commit", "invalidated_by_commit TEXT");
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_nodes_validity
+        ON nodes(kind, valid_until)
+        WHERE kind = 'mistake' AND valid_until IS NOT NULL;
+    `);
+  }
 };
 function getSchemaVersion(db) {
   try {
@@ -116,9 +149,13 @@ function runMigrations(db, dbPath) {
   );
   let migrationsRun = 0;
   for (let v = fromVersion + 1; v <= CURRENT_SCHEMA_VERSION; v++) {
-    const sql = MIGRATIONS[v];
-    if (sql) {
-      db.exec(sql);
+    const step = MIGRATIONS[v];
+    if (step) {
+      if (typeof step === "string") {
+        db.exec(step);
+      } else {
+        step(db);
+      }
       migrationsRun++;
     }
   }

package/dist/chunk-73IBCRFI.js

@@ -0,0 +1,215 @@
+import {
+  applyArgTemplate
+} from "./chunk-ZUC6OXSL.js";
+
+// src/providers/mcp-client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+var McpClientWrapper = class {
+  constructor(config) {
+    this.config = config;
+  }
+  config;
+  client = null;
+  transport = null;
+  connectingPromise = null;
+  shutdownRegistered = false;
+  lastErrorAt = 0;
+  errorBackoffMs = 3e4;
+  /**
+   * Connect once (idempotent). Concurrent callers share one promise so
+   * we never spawn the server twice. On failure we set a backoff window
+   * so the next Read doesn't re-try spawn immediately.
+   */
+  async connect() {
+    if (this.client) return;
+    if (this.connectingPromise) return this.connectingPromise;
+    if (Date.now() - this.lastErrorAt < this.errorBackoffMs) {
+      throw new Error(
+        `[mcp] ${this.config.name}: in error backoff (last failure ${Math.round(
+          (Date.now() - this.lastErrorAt) / 1e3
+        )}s ago)`
+      );
+    }
+    this.connectingPromise = this.doConnect().catch((err) => {
+      this.lastErrorAt = Date.now();
+      this.client = null;
+      this.transport = null;
+      throw err;
+    }).finally(() => {
+      this.connectingPromise = null;
+    });
+    return this.connectingPromise;
+  }
+  async doConnect() {
+    if (this.config.transport !== "stdio") {
+      throw new Error(
+        `[mcp] ${this.config.name}: http transport not yet implemented`
+      );
+    }
+    const transport = new StdioClientTransport({
+      command: this.config.command,
+      args: this.config.args ? [...this.config.args] : void 0,
+      env: this.config.env ? { ...this.config.env } : void 0,
+      cwd: this.config.cwd,
+      // Pipe stderr so a chatty server doesn't spam the parent's stderr
+      // during normal operation. Re-enable "inherit" for debugging.
+      stderr: "pipe"
+    });
+    const client = new Client(
+      { name: "engramx", version: "3.0.0" },
+      { capabilities: {} }
+    );
+    await client.connect(transport);
+    this.transport = transport;
+    this.client = client;
+    if (!this.shutdownRegistered) {
+      this.registerShutdown();
+      this.shutdownRegistered = true;
+    }
+  }
+  /**
+   * Call a single tool with a timeout. Returns null on error (never
+   * throws). Caller is responsible for aggregating multiple tool results.
+   */
+  async callTool(toolName, args, timeoutMs) {
+    try {
+      await this.connect();
+    } catch {
+      return null;
+    }
+    if (!this.client) return null;
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(), timeoutMs);
+    try {
+      const result = await this.client.callTool(
+        { name: toolName, arguments: args },
+        void 0,
+        { signal: abort.signal, timeout: timeoutMs }
+      );
+      clearTimeout(timer);
+      const blocks = Array.isArray(result?.content) ? result.content : [];
+      const text = blocks.map((b) => {
+        const block = b;
+        if (block.type === "text" && typeof block.text === "string") {
+          return block.text;
+        }
+        return `[${block.type ?? "unknown"} block]`;
+      }).join("\n").trim();
+      if (text.length === 0) return null;
+      return { content: text };
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /** Close the connection. Safe to call on an unconnected client. */
+  async disconnect() {
+    const client = this.client;
+    const transport = this.transport;
+    this.client = null;
+    this.transport = null;
+    try {
+      await client?.close();
+    } catch {
+    }
+    try {
+      await transport?.close();
+    } catch {
+    }
+  }
+  registerShutdown() {
+    const shutdown = () => {
+      void this.disconnect();
+    };
+    process.once("SIGTERM", shutdown);
+    process.once("SIGINT", shutdown);
+    process.once("beforeExit", shutdown);
+  }
+};
+function createMcpProvider(config) {
+  const wrapper = new McpClientWrapper(config);
+  const tokenBudget = config.tokenBudget ?? 200;
+  const timeoutMs = config.timeoutMs ?? 2e3;
+  const enabled = config.enabled ?? true;
+  return {
+    name: config.name,
+    label: config.label,
+    // Tier 2 — external process/HTTP with cache support. Matches
+    // context7/obsidian tier semantics in the existing resolver.
+    tier: 2,
+    tokenBudget,
+    timeoutMs,
+    async isAvailable() {
+      if (!enabled) return false;
+      if (config.tools.length === 0) return false;
+      return true;
+    },
+    async resolve(filePath, context) {
+      try {
+        const results = await Promise.allSettled(
+          config.tools.map((tool) => callSingleTool(wrapper, tool, filePath, context, timeoutMs))
+        );
+        const sections = [];
+        let highestConfidence = 0;
+        for (const outcome of results) {
+          if (outcome.status === "fulfilled" && outcome.value) {
+            sections.push(outcome.value.content);
+            highestConfidence = Math.max(
+              highestConfidence,
+              outcome.value.confidence
+            );
+          }
+        }
+        if (sections.length === 0) return null;
+        let combined = sections.join("\n\n");
+        const budget = tokenBudget;
+        if (estimateTokens(combined) > budget) {
+          const lines = combined.split("\n");
+          const kept = [];
+          let used = 0;
+          for (const line of lines) {
+            const lineTokens = estimateTokens(line) + 1;
+            if (used + lineTokens > budget) break;
+            kept.push(line);
+            used += lineTokens;
+          }
+          combined = kept.join("\n") + "\n\u2026 [truncated to fit budget]";
+        }
+        return {
+          provider: config.name,
+          content: combined,
+          confidence: highestConfidence,
+          cached: false
+        };
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+async function callSingleTool(wrapper, tool, filePath, context, timeoutMs) {
+  const args = applyArgTemplate(tool.args, {
+    filePath,
+    projectRoot: context.projectRoot,
+    imports: context.imports
+  });
+  const result = await wrapper.callTool(tool.name, args, timeoutMs);
+  if (!result) return null;
+  return {
+    content: result.content,
+    confidence: tool.confidence ?? 0.75
+  };
+}
+var __internalsForTesting = {
+  McpClientWrapper
+};
+
+export {
+  createMcpProvider,
+  __internalsForTesting
+};