v4.5.0 "Reach"

[4.5.0] — 2026-06-21 — "Reach"

Why: two ways to put the right context in front of an agent with less
waste — displace redundant context across providers instead of concatenating it,
and point a spawned sub-agent at the files most likely related to the one it is
working on. Both are structural and never-worse by construction; neither is a
cost/bill claim.

Added

• Sub-agent focal reach (#139) — when a sub-agent starts, the context broker
  now appends the files most likely related to the parent's most-recently-read
  file: graph-adjacent files first (real call/import edges), then path-based
  reach (same-directory siblings, test↔implementation counterparts). Tiered so a
  real graph hit is never displaced by a weaker path guess; de-duplicated;
  capped. Lets a sub-agent skip the grep-around discovery step. Degrades silently
  to the existing top-entities map when no focal file can be inferred.
• Reach benchmarks — bench/recall-coverage gains a path-reach mode
  (ENGRAM_BENCH_PATHREACH=1); new bench/cochange-holdout is a non-circular
  temporal-holdout test (learn co-change from past commits, predict held-out
  future co-change) against a popularity baseline. Honest result in the output:
  co-change alone is weak, but combined with path-reach it beats the baseline.

Changed

• Cross-provider displacement — the resolver now de-duplicates and
  blend-ranks context across providers and discards the redundancy, instead of
  concatenating each provider's section. The Stop summary reports ~N redundant tokens displaced across providers (structural — not a bill saving).
• Never-worse gate on the enriched Read packet — an intercepted Read only
  serves the enriched (structure + provider) packet when it is strictly smaller
  than the raw file; otherwise engram falls back to the graph-only summary
  (already proven smaller). Guarantees an intercepted Read never injects more
  tokens than the file it replaces.

v4.4.0 "Curve"

Highlights: engram measure --session (Token-loop C, whole-session break-even-P curve); cluster-bootstrap CIs on the recall bench (ranker lift +5.0pp [+1.7, +8.5], excludes 0 → real); query/gen fail loudly on a bad --project (#92); hermetic skills test (#137); honest README front door. Full notes: CHANGELOG.md [4.4.0].

v4.3.0 "Proof"

v4.3.0 'Proof'

v4.2.0 "Loop"

v4.2.0 "Loop" — engram closes the agent's research loop

The original Context Spine goal was to collapse the whole grep → read → read investigation loop, not just the single file read. v4.1 shipped ranking; v4.2 ships the rest of the loop — and every piece is gated so it only fires when it genuinely saves tokens, with an escalation path so it can never blind the agent.

Added

• Grep interception → call sites (ADR-0001, ADR-0004). A content-mode grep for a well-referenced symbol is answered from the reference graph with the actual file:line: code call sites — smaller than the raw grep (init is 573 vs 9,317 tokens on engram's own repo) while showing the real usage. Default files_with_matches / count greps and low-usage symbols (< 4 caller files) pass straight through. Always carries an rg -n escalation. ENGRAM_GREP_INTERCEPT=0 opts out.
• Same-session read dedup (ADR-0003). Re-read an unchanged file you already read this session and engram returns a pointer instead of re-serving it. Recall-safe by construction: byte-unchanged (mtime+size) guard, full reads only, a 400-byte floor, and a PreCompact + SessionStart reset so it never points at content that compaction or /clear evicted. A 30-min TTL + 256-entry cap bound any unsignalled eviction. ENGRAM_READ_DEDUP=0 opts out.
• Deterministic session-level bench (bench/session-level.ts). Replays machine-generated investigation traces through the real handlers and models the session saving as a curve over how often the agent re-fetches raw content — the break-even point is the honest headline, not a single number.

Honesty

Everything here is a structural context-token reduction, not a bill saving (engram's net agent-loop cost over prompt caching is ~0). Numbers are measured and gated so an interception never costs more than the call it replaces.

1100 tests passing. Apache 2.0, local SQLite, zero cloud. See CHANGELOG.md for the full diff.

v4.1.0 "Compass"

v4.1.0 "Compass" — 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.

Added

• Ranked context (PageRank) over a real cross-file reference graph.
• Graph traversal commands: engram callers, engram callees, engram impact.
• Per-session value summary (Stop hook): one line showing reads answered, mistake warnings, and tokens kept out of context.
• Day-1 mistakes: a bug-fix-commit miner (fix: / fixes #N, not just rare reverts) seeds mistake-memory on a fresh engram init.

Changed

• Honesty pass. Every surface frames the per-file win as a structural context-packet reduction, not a cost/bill saving (engram's net agent-loop cost over prompt caching is ~0). No headline cost claims.
• Reduction is honest by construction: the Read hook only replaces a file read when its packet is genuinely smaller (statSync size-guard), so a reported reduction is never negative. The benchmark reports both raw and effective (size-guarded) numbers.
• Incremental re-index now maintains the reference graph atomically (single transaction, rollback on failure), so PageRank ranking stays fresh between full inits.
• Proactive mistake warnings are high-precision — only git reverts + explicit engram learn warn before an edit; inferred mistakes stay browsable but never nag.

Structural per-file reduction on engramx's own repo: up to ~89% (structural, not a bill saving — your repo varies; run npx tsx bench/real-world.ts on yours). 1074 tests passing. Apache 2.0, local SQLite, zero cloud.

See CHANGELOG.md for the full diff.

engramx v4.0.0 — Skill Pack

Engram's memory becomes active. v3.x captured mistakes 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 in one command.

The bi-temporal moment

Fresh engram init on any git-active repo produces a non-empty mistakes table within seconds. When Claude is about to edit a file with a recurring pattern, this is what gets injected into its context window:

⛔ engramx pre-mortem — you've made this mistake before:

  ⚠ git revert touching src
     ┌─ then you believed: feat: add buggy helper that returns null causing form crashes
     ├─ found false:       2026-05-18
     └─ truth now:         Reverted in 99f158e (2026-05-18)
        file: src.ts

The agent reads what you used to believe vs what's now true — and adapts the proposed edit.

What's in v4.0

• Schema v9 — four new bi-temporal fields on every mistake: then_believed, found_false_at, truth_now, applies_to. Additive, idempotent migration. v3.x mistakes back-fill as NULL and continue to render legacy single-line.
• git-revert auto-capture miner — walks the last 200 commits, detects revert pairs via subject prefix + This reverts commit <sha> body marker, fetches reverted commit metadata, emits one bi-temporal mistake per pair. Idempotent stable IDs.
• Auto-install hook on engram init — 6 Sentinel hook events written to .claude/settings.local.json by default. Per-project scope. Opt out with engram init --no-hook.
• Mistake-guard default-on (permissive mode) — pre-mortem fires automatically. Opt out with ENGRAM_MISTAKE_GUARD=0. Strict deny mode still opt-in via ENGRAM_MISTAKE_GUARD=2.
• engram upgrade command — friendly v3.x → v4.0 migration path with v4.0 highlights output.
• Mistake-guard hardening — structured stderr telemetry (no more silent fail-open), Bash min-pattern lifted >2/>3 → >4/>5, 8 new invocation-layer integration tests verifying the full dispatch wiring.
• isInsideProject symlink fallback — production reliability fix for macOS Write-to-new-file in symlinked tempdirs.
• Mesh feature-flagged behind ENGRAM_MESH_EXPERIMENTAL=1. GA moves to v4.5 per the May 18 strategic re-cut.

Distribution

Sibling repo engram-skill-pack ships engram as Anthropic Claude Code Marketplace Skills. v0.2.0 active today with three skills (engram-mistakes, engram-query, engram-gods); full five-skill surface in v0.3.0.

npx @anthropic-ai/claude-code add nickcirv/engram-skill-pack

Tests

1025/1025 passing (+18 over v3.4.0). Zero regressions across all 5 v4.0 commits.

Process

This release walked the 8-phase release ritual at ~/.claude/skills/engram-release/SKILL.md. Every phase backtested, triple-audited, stress-tested for edge cases. Phase 0 audit caught 4 falsified assumptions before any code shipped and re-cut scope from "Mesh + Spine GA" to "Skill Pack." Full details in CHANGELOG.md.

Upgrade

npm i -g engramx@4.0.0
engram upgrade   # idempotent schema migration + v4.0 highlights

Or for a fresh install:

npm i -g engramx@4.0.0
cd ~/your-project && engram init   # auto-installs the Sentinel hook

v3.4.0 — Universal Spine

The release that turns engram from a Claude Code tool into a universal context spine across every major AI coding tool.

What's new

Universal init detector (5 → 8 IDEs)

engram setup now auto-detects Cline, Zed, and OpenAI Codex CLI alongside Claude Code, Cursor, Continue.dev, Aider, and Windsurf. Per-IDE setup hints include the exact MCP config snippet for Cline.

Anthropic Claude Code plugin

/plugin install engram from the official directory once the listing lands. Plugin manifest at plugins/anthropic-marketplace/ with three skills (/engram:cost, /engram:query, /engram:mistakes) plus the MCP server config.

VS Code / Cursor extension

A thin wrapper around the engramx CLI shipped to OpenVSX. Six commands, status-bar entry, two settings. Compiles to a single out/extension.js. Works in VS Code, Cursor, and any VS Code fork.

Cline integration

docs/integrations/cline.md — Cline supports MCP natively, so the integration is one config-snippet away.

engramx-continue

Sister npm package at adapters/continue/. Continue.dev @engram context provider with HTTP and CLI fallback transports. Tarball clean (2.2 KB, 4 files).

Public surface refresh

• README.md callout leads with May 2026 market context (Cursor pricing crisis + Claude Code rate-limit pain)
• IDE matrix expanded from 8 to 11
• "How It Compares" rewritten as the May 2026 8-row competitive matrix
• docs/install.html title, OG, hero pill, IDE matrix all v3.4
• GitHub repo description and topics refreshed

Tests

• 910 passing across Ubuntu + Windows × Node 20 + 22 (was 907 baseline → +3 detector tests)

Why now

Three things broke at the same time in 2026. Cursor went usage-based and people started getting $1,400 surprise bills. Anthropic tightened Claude Code limits, then quietly tested removing the product from the $20 Pro plan. AI coding fragmented into 8 IDEs with no common context layer. v3.4 puts engram into all of them.

Full strategic audit: ~/Desktop/Projects/Engram/00-strategy/2026-05-02-strategic-audit-v34-pivot.md
7-day execution plan: ~/Desktop/Projects/Engram/01-prds/04-universal-spine-7-day-plan.md

Process

This is the first release that walked the new 8-phase release ritual at ~/.claude/skills/engram-release/SKILL.md. Future releases follow the same checklist by default.

Install

npm install -g engramx@latest
cd ~/your-project
engram setup            # auto-detects every supported IDE

For Continue.dev users:

npm install engramx-continue

For Cursor / VS Code users:

code --install-extension engram-vscode    # OpenVSX

v3.3.0 — Cost Lens

v3.3.0 Cost Lens

v3.0.2 — MCP Registry

v3.0.2 — MCP Registry integration (chore)

Patch release. No runtime changes. Adds the mcpName field to package.json required by the Official MCP Registry (registry.modelcontextprotocol.io) for namespace-ownership proof, and tightens the server.json descriptions to the registry's 100-char limit.

What changed

• package.json → top-level "mcpName": "io.github.NickCirv/engram"
• server.json → descriptions shortened (top-level 343 → 91 chars; 5 env-var descriptions 102-158 → 53-83 chars each)
• Both bumped to 3.0.2 to match the required npm publish

Why not in 3.0.1

3.0.1 needed to ship the preuninstall hook-cleanup as fast as possible after @freenow82's report. The MCP Registry integration surfaced only during the submission flow after 3.0.1 was already live — separate concern, separate patch.

For users

Nothing to do. 3.0.1 works correctly; 3.0.2 is an infra-side nicety that makes engramx discoverable at registry.modelcontextprotocol.io. npm install -g engramx picks up 3.0.2 on the next install.

Verification

• 878/878 tests passing
• CI green Ubuntu + Windows × Node 20 + 22
• TypeScript strict, lint clean

v3.0.1 — "Clean Uninstall" (hotfix)

v3.0.1 — Clean Uninstall

Patch release. No feature changes. Fixes the orphaned-hooks bug @freenow82 reported within hours of 3.0.0 going live. Apologies to anyone who hit it.

What 3.0.0 shipped with

npm uninstall -g engramx removed the binary from PATH but left the hook entries in ~/.claude/settings.json pointing at a engram intercept command that no longer existed. Claude Code fires those hooks on every tool call — the commands failed with ENOENT — user-visible behaviour was "Claude Code stopped executing anything." Recovery required reinstalling engramx just to run engram uninstall-hook before uninstalling again. That is a bad experience.

What 3.0.1 does

• scripts/preuninstall.mjs runs automatically on npm uninstall -g engramx. Strips every engram-tagged hook from ~/.claude/settings.json, drops the HUD statusLine, backs up the original to a timestamped .bak, writes atomically via rename. Hard contract: this script NEVER fails the uninstall. Every error path logs a one-line hint and exits 0. The user's npm uninstall always succeeds, with or without hook cleanup.
• scripts/postinstall.mjs prints a one-time info banner on npm install -g engramx showing the next step (engram setup) and the clean-uninstall flow. Respects $CI and $ENGRAM_NO_POSTINSTALL=1.
• New engram repair-hooks CLI alias — literally the same command as engram uninstall-hook, named so stranded users can find it by the word they'd actually search for.
• README has a new "Want out?" section with the clean-uninstall command and a link to the recovery path for anyone stranded on 3.0.0.

If you installed 3.0.0 and your Claude Code is still broken

Two paths:

Fast, no reinstall (requires jq — brew install jq on mac, apt install jq on Linux):

jq 'walk(if type == "object" and .hooks? then
  .hooks |= map(select(.command // "" | test("engram"; "i") | not))
else . end)' ~/.claude/settings.json > /tmp/claude-settings.json && \
cp ~/.claude/settings.json ~/.claude/settings.json.bak && \
mv /tmp/claude-settings.json ~/.claude/settings.json

Works from 3.0.1:

npm install -g engramx@3.0.1
engram repair-hooks --scope user    # or: engram uninstall-hook --scope user
# Claude Code is clean. You can keep engramx, or:
npm uninstall -g engramx             # preuninstall will run this time

Verification

The preuninstall script was fixture-tested before shipping: a synthesized settings.json with a mix of engram hooks, unrelated custom hooks in the same event arrays, an engram statusLine, and unrelated top-level keys. Post-run:

• ✅ 3 engram hook entries removed
• ✅ custom echo 'my custom hook' preserved in PreToolUse
• ✅ custom SessionStart hook preserved
• ✅ unrelated Stop hook (no engram reference) completely untouched
• ✅ engram statusLine removed
• ✅ unrelated top-level otherUserPrefs preserved byte-for-byte
• ✅ timestamped .bak file created
• ✅ no engram substring anywhere in the result

CI also green — Ubuntu + Windows × Node 20 + 22, all 878 tests passing.

Thanks

@freenow82 — this is the report that turns a launch into a better tool. Genuinely grateful.