release: v4.1.0 "Compass" — ranking headline + honesty pass across all public surfaces

Version bump 4.0.0 → 4.1.0 across package.json, package-lock, server.json (×2).
CHANGELOG [Unreleased] → [4.1.0] "Compass"; corrected the stale 'incremental
doesn't maintain calls edges' limitation (76b2890 fixed it — now rebuilt
atomically) and documented the size-guarded effective-reduction metric.

README + install.html: new v4.1 "Compass" callout/showcase led by the ranking
moat (PageRank reference graph, callers/callees/impact traversal, day-1
mistakes, per-session value line). Install commitment bumped to engramx@4.1.0.

Honesty pass (finishes the long-running softening):
- server.json description: '89.1% measured token reduction' → 'up to ~89%
  structural context reduction (varies by repo)'.
- Killed every user-facing 'savings' / 'X% is what you get' framing in
  install.html + banner.html + marketplace README; softened bare precise
  '89.1%' marketing headlines to 'up to ~89% structural (not a bill saving,
  varies)'. README detailed Proof tables keep the committed reproducible 87-file
  numbers (scoped + caveated) — those are honest by nature.
- .gitignore: guard against committing dated bench reports (they embed the
  absolute project path — caught one as a Category-E leak this session).

Audit evidence: tsc clean; full suite 1074/1074 (honesty-claims regression
green); build OK; npm pack → engramx-4.1.0.tgz, 53 files, no junk. Leak-audit:
0 sensitive-term hits over the diff + clean-room subagent verdict CLEAN.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: NickCirv

.gitignore

@@ -11,8 +11,10 @@ dist/
 .aider-context.md
 .context/
 .cursor/
-# Dated benchmark result files (TEMPLATE.csv is tracked for reference)
+# Dated benchmark result files (TEMPLATE.csv is tracked for reference).
+# Generated reports embed the absolute project path — keep them out of git.
 bench/results/*.json
+bench/results/real-world-2*.md
 
 # Local planning docs (not published)
 .planning/

CHANGELOG.md

@@ -6,12 +6,15 @@ All notable changes to engram are documented here. Format based on
 
 ## [Unreleased]
 
+## [4.1.0] — 2026-06-03 — "Compass"
+
 ### Added
 - **Ranked context (PageRank).** A real cross-file reference graph is now
   built at `engram init` (tree-sitter call/reference extraction → `calls`
   edges), and query results are ranked by personalized PageRank over it —
   importance flows from who-references-you, recursively, biased toward your
-  query. Replaces the previous raw edge-degree ordering.
+  query. Replaces the previous raw edge-degree ordering. engram is the only
+  tool in its category that *ranks* the graph rather than dumping it.
 - **Graph traversal commands:** `engram callers <symbol>`,
   `engram callees <symbol>`, `engram impact <symbol>` over the reference graph.
 - **Per-session value summary.** A Stop hook prints one line per session:
@@ -26,16 +29,20 @@ All notable changes to engram are documented here. Format based on
   *structural context-packet reduction*, not a cost/bill saving (engram's net
   agent-loop cost over prompt caching is ~0; the benchmark self-discloses its
   baseline). No headline cost claims.
+- **Reduction is now honest by construction.** The Read hook only replaces a
+  file read when its structural packet is actually *smaller* than the file
+  (`statSync` size-guard) — tiny files pass through untouched, so a reported
+  saving is never negative. The benchmark reports both raw per-file reduction
+  and an **effective (size-guarded)** number — what engram actually delivers.
+- **Incremental re-index now maintains the reference graph.** The full
+  `calls`-edge set is rebuilt atomically (single transaction, rollback on
+  failure) on every init including incremental, so PageRank ranking stays
+  fresh between full inits — no manual refresh needed.
 - **Proactive mistake warnings are high-precision** — only high-confidence
   mistakes (git reverts, explicit `engram learn`) warn before an edit;
   inferred bug-fix/session mistakes stay browsable via `engram mistakes` but
   never nag.
 
-### Known limitations
-- The reference graph (and thus PageRank ranking) is rebuilt on **full**
-  `engram init`. Incremental re-index does not yet maintain `calls` edges, so
-  ranking can drift between full inits — run `engram init` to refresh.
-
 ## [4.0.0] — 2026-05-18 — "Skill Pack"
 
 Engram's memory becomes **active**. v3.x captured mistakes and answered queries when asked; v4.0 surfaces past corrections **before** the agent makes the edit, captures new ones automatically from git history, and ships a sibling marketplace pack so Claude Code users install engram in one command.

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/banner-v3.png" alt="engramx — the universal context spine for AI coding tools (v4.0 'Skill Pack')" width="100%">
+  <img src="assets/banner-v3.png" alt="engramx — the universal context spine for AI coding tools (v4.1 'Compass')" width="100%">
 </p>
 
 <p align="center">
@@ -86,8 +86,8 @@ mkdir -p /tmp/engram-demo && cd /tmp/engram-demo && \
   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.0.0 init . && \
-  npx --yes engramx@4.0.0 mistakes
+  npx --yes engramx@4.1.0 init . && \
+  npx --yes engramx@4.1.0 mistakes
 ```
 
 You should see, within 30 seconds, the **bi-temporal pre-mortem** engram auto-captured from your revert:
@@ -115,13 +115,13 @@ Three things broke at the same time. Cursor went usage-based and people started
 
 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 87-file repo, the **per-file structural context reduction is 89.1%** (codebase-dependent — `bench/real-world.ts` reproduces it on any project you point it at). This is a *structural* token-reduction measured on this codebase, not an agent-loop cost-savings figure, 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.
+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.0 "Skill Pack" shipped 2026-05-18 — in 30 seconds:** Bi-temporal mistakes auto-fire before your agent repeats them. Fresh installs auto-capture mistakes from git revert history. Hook auto-installs on `engram init`. Skill-pack sibling repo ships engram to the Claude Code Marketplace in one command.
+> **v4.1 "Compass" shipped 2026-06-03 — engram now ranks the graph.** A real cross-file reference graph (tree-sitter `calls` edges) is built at `engram init`, and query results are ranked by **personalized PageRank** over it — importance flows from who-references-you, recursively, biased toward your query, instead of raw edge-degree. engram is the only tool in its category that *ranks* the graph rather than dumping it. New traversal commands `engram callers <symbol>`, `engram callees <symbol>`, and `engram impact <symbol>` walk the same edges.
 >
-> v3.x captured mistakes when asked; v4.0 surfaces past corrections *before* the agent makes the edit. Schema v9 adds four bi-temporal fields per mistake (`then_believed`, `found_false_at`, `truth_now`, `applies_to`). A new **git-revert miner** auto-populates them from your repo's revert history — fresh `engram init` produces a non-empty mistakes table within seconds, no manual seeding needed. `engram init` now **auto-installs** the Sentinel hook by default (opt out with `--no-hook`) and the mistake-guard runs in `permissive` mode by default (opt out with `ENGRAM_MISTAKE_GUARD=0`). Sibling repo **[engram-skill-pack](https://github.com/NickCirv/engram-skill-pack)** ships engram as Claude Code Skills via the Anthropic Marketplace — three active skills (`engram-mistakes`, `engram-query`, `engram-gods`), full five-skill surface in v0.3.0. **Mesh moves to v4.5** behind `ENGRAM_MESH_EXPERIMENTAL=1`; the May 18 strategic re-cut prioritised distribution-via-skills over federation. 1025 tests passing. See [CHANGELOG.md](CHANGELOG.md) for the full v4.0 diff.
+> Also new: **day-1 mistakes** — a bug-fix-commit miner (`fix:` / `fixes #N`, not just rare reverts) means a fresh `engram init` surfaces real landmines immediately, and a **per-session value line** (Stop hook) shows what engram kept out of context each session. And the **honesty pass**: every surface now frames the per-file win as a *structural context-packet reduction, not a cost saving* (engram's net agent-loop cost over prompt caching is ~0); the Read hook is size-guarded so a reported reduction is never negative, and `bench/real-world.ts` self-discloses its baseline. Incremental re-index now maintains the reference graph atomically, so ranking stays fresh between full inits. 1074 tests passing. See [CHANGELOG.md](CHANGELOG.md) for the full v4.1 diff (and v4.0 "Skill Pack" — bi-temporal mistakes from git-revert history).
 
 <details>
 <summary><strong>Earlier release notes (v3.4 "Universal Spine", May 2)</strong></summary>
@@ -181,9 +181,9 @@ Your AI coding agent keeps re-reading the same files. Every `Read`, every `Edit`
 
 The agent gets what it needs, structured. And **every plugin you add extends what engram can surface** — Serena for LSP symbols, GitHub MCP for issue context, Sentry MCP for production errors, Supabase / Neon for schema. Each one closes a context gap the agent would otherwise spend turns researching. (More providers = more capability; whether they net fewer tokens on a given task depends on the task — measure it on yours.)
 
-**Per-file structural reduction on a reproducible benchmark: 89.1%** (engramx's own codebase; structural token reduction, not agent-loop cost). 85 of 87 real source files saw reduced per-file token cost. Best case 98.4% (18,820 tokens → 306). Your per-repo numbers vary.
+**Per-file structural reduction on a reproducible benchmark: up to ~89%** (engramx's own codebase; structural token reduction, not agent-loop cost). On the committed 87-file run, 85 of 87 real source files saw reduced per-file token cost, best case 98.4% (18,820 tokens → 306); a fresh sample of 50 files reduces ~89.5% aggregate. Your per-repo numbers vary — run it on yours.
 
-> **What this number is (and isn't):** 89.1% is a *per-file structural context reduction* measured on engramx's own repo with all 9 providers active — it measures how much smaller engram's context packet is than reading the full files raw. It is **not** an agent-loop cost-savings figure and will differ on your codebase. Your actual dollar saving depends on your prompt-caching setup and workload — run the benchmark on your own repo (see [Benchmark](#benchmark)) to get your structural number.
+> **What this number is (and isn't):** ~89% is a *per-file structural context reduction* measured on engramx's own repo with all 9 providers active — it measures how much smaller engram's context packet is than reading the full files raw. It is **not** an agent-loop cost-savings figure and will differ on your codebase. Your actual dollar saving depends on your prompt-caching setup and workload — run the benchmark on your own repo (see [Benchmark](#benchmark)) to get your structural number.
 
 ### One command to everything
 

assets/banner.html

@@ -301,14 +301,14 @@ <h1>engr<span>a</span>m<span>X</span></h1>
     <span class="prompt">$</span> <span class="cmd">npm install -g engramx</span><br>
     <span class="prompt">$</span> <span class="cmd">engram setup</span><br>
     <span class="output">↳ indexed, hooked, dual-emit AGENTS.md + CLAUDE.md</span><br>
-    <span class="output">📉 89.1% measured token savings on 87 files</span><br>
+    <span class="output">📉 up to ~89% structural context reduction (own repo, varies)</span><br>
     <span class="highlight">✅ next session reads from the spine.</span>
   </div>
 </div>
 
 <!-- Bottom bar -->
 <div class="bottom-bar">
-  <div class="stat"><span class="stat-value">89.1%</span> measured savings</div>
+  <div class="stat"><span class="stat-value">~89%</span> structural reduction</div>
   <div class="stat"><span class="stat-value">9 + plugins</span> providers</div>
   <div class="stat"><span class="stat-value">0</span> LLM cost · <span class="stat-value">0</span> cloud</div>
   <div class="stat">works with <span class="stat-value">Claude Code</span> · <span class="stat-value">Cursor</span> · <span class="stat-value">Codex</span> · any AGENTS.md agent</div>