engramx 3.0.2 → 3.4.0

package/CHANGELOG.md

@@ -6,6 +6,47 @@ All notable changes to engram are documented here. Format based on
 
 ## [Unreleased]
 
+## [3.4.0] — 2026-05-02 — "Universal Spine"
+
+The release that turns engram from a Claude Code tool into a universal context spine across every major AI coding tool. Same engram, same graph, same 89.1% reduction — now plugged into 8 IDEs out of the box.
+
+### Added
+
+- **Universal init detector.** `src/setup/detect.ts` adds three new detectors: `detectCline` (probes for VS Code's Cline globalStorage), `detectZed` (probes for Zed's config and `.zed/settings.json`), `detectCodex` (probes for `~/.codex` and `AGENTS.md`). `detectAllIdes()` now returns 8 entries (was 5). Per-IDE setup hints in `wizard.ts` now include the exact MCP config snippet for Cline.
+- **Anthropic Claude Code plugin manifest.** `plugins/anthropic-marketplace/` — submission-ready `marketplace.json`, `plugin.json`, three skills (`/engram:cost`, `/engram:query`, `/engram:mistakes`), and the MCP server config that registers `engram-serve` automatically. Verified against `code.claude.com/docs/en/plugins`.
+- **VS Code / Cursor extension.** `extensions/vscode/` — thin wrapper around the engramx CLI. Six commands (init, gen-mdc, gen, cost, dashboard, doctor), status-bar entry, two configuration settings. Compiles to a single `out/extension.js` and packs via `vsce` for OpenVSX. Works in VS Code, Cursor, and any VS Code fork.
+- **Cline integration documented.** `docs/integrations/cline.md` — Cline supports MCP natively, so the integration is one config-snippet away. Cross-linked from `docs/integrations/README.md`.
+- **engramx-continue.** Sister npm package at `adapters/continue/` — Continue.dev `@engram` context provider with HTTP and CLI fallback transports. Tarball verified clean (2.2 KB, 4 files).
+
+### Changed
+
+- **README.md.** Top-of-file callout now leads with the May 2026 market context (Cursor pricing crisis + Claude Code rate-limit pain) so the positioning matches what users are actually searching for. IDE matrix expanded from 8 to 11. "How It Compares" rewritten as the May 2026 8-row competitive matrix (engramx vs Cursor index / Aider repo map / Cline / Continue / Mem0 / claude-mem / CartoGopher); legacy table moved to a collapsed details block.
+- **docs/install.html.** Title, meta description, OG title + description, hero pill, nav link, and IDE matrix all refreshed for v3.4 framing.
+- **GitHub repo description and topics.** Description shortened and re-led with "context spine that 10x's every AI coding session." Topics maxed at 20 with `cline` and `universal-spine` added.
+
+### Tests
+- Net-new: 3 detector tests in `tests/setup/detect.test.ts` (detectCline / detectZed / detectCodex).
+- Total: **910 passing** (was 907 baseline).
+
+### Process
+
+This is the first release that walks the new 8-phase release ritual codified at `~/.claude/skills/engram-release/SKILL.md`. Phase 3 (public surface refresh) caught README + install.html + topics drift in one pass. Future releases follow the same checklist by default.
+
+### Why
+
+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 — one install, one graph, every tool benefits. Audit at `~/Desktop/Projects/Engram/00-strategy/2026-05-02-strategic-audit-v34-pivot.md`.
+
+## [3.3.0] — 2026-05-02 — "Cost Lens"
+
+### Added
+- New `engram cost` subcommand: aggregates token-savings telemetry from existing `.engram/hook-log.jsonl` files across one or many project roots. Outputs a terminal table, JSON, or a weekly Markdown digest at `~/.engram/cost-report-YYYY-Www.md`.
+- New `src/cost/` module: `types.ts`, `aggregator.ts`, `formatter.ts`, `digest.ts`, `instrument.ts`. Pure functions, hermetic tests, NaN-safe math.
+- Dispatch instrumentation in `src/intercept/dispatch.ts` — every PreToolUse log entry now carries `wouldHaveRead`, `injected`, and `tokensSaved` fields when applicable.
+- 31 new tests across `tests/cost.test.ts` and `tests/cost-instrument.test.ts`, hermetic.
+
+### Why
+Cost Lens is the baseline for the v3.3 → v4.0 roadmap. Future features (Bridge, Mesh, Vector) get evaluated against the real-world impact, not a single static benchmark. PRD: `01-prds/03-engram-mesh-ruflo-integration-PRD.md`.
+
 ## [3.0.2] — 2026-04-24 — "MCP Registry"
 
 Chore release. No runtime changes. Adds the `mcpName` field to `package.json`

package/README.md

@@ -47,16 +47,28 @@
   <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-876%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-910%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/token%20savings-89.1%25%20measured-orange" alt="89.1% 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>
 
 ---
 
-> **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.
+## Why this exists, May 2026
+
+Three things broke at the same time. Cursor went usage-based and people started getting $1,400 surprise bills. Anthropic tightened Claude Code limits, then quietly tested removing it from the $20 Pro plan. Half the AI coding crowd migrated from one tool to the other, hit the new ceiling within a week, and started looking for any way to make a session last longer.
+
+Engramx is what makes the session last longer. It indexes your codebase into a local SQLite knowledge graph once. Then it intercepts file reads at the agent boundary and replaces them with a structural summary the agent already has the working memory for. Same edit, same diff, same code shipped — fewer tokens consumed in the round trip.
+
+On a real 87-file repo, the measured reduction is **89.1%**. That's not a marketing number. The benchmark is committed to this repo as `bench/real-world.ts` and runs against any project you point it at. 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 as the strongest measured number 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.
+
+> **v3.4 "Universal Spine" shipped 2026-05-02** — multi-IDE detector covers 8 tools, Anthropic Claude Code plugin (`/plugin install engram`), VS Code / Cursor extension on OpenVSX, `engramx-continue` on npm, Cline integration documented. Cost Lens telemetry from v3.3.0 now feeds a weekly Markdown digest at `~/.engram/cost-report-YYYY-Www.md`. 910 tests, CI green on Ubuntu + Windows × Node 20 + 22. See [CHANGELOG.md](CHANGELOG.md) for the v3.3 + v3.4 diff.
+
+> **EngramX v3.0 "Spine" shipped 2026-04-24** — the biggest release before v3.4. The spine is **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.
 
 ---
 
@@ -368,14 +380,19 @@ engram hooks install             # auto-rebuild graph on every git commit
 
 ## IDE Integrations
 
+`engram setup` auto-detects every supported IDE on your machine and prints the right next-step for each. You don't have to remember which command to run — the detector knows.
+
 | IDE | Integration | Setup |
 |-----|------------|-------|
-| **Claude Code** | Hook-based interception (native, automatic) | `engram install-hook` |
-| **Cursor** | MDC snapshot + native MCP | `engram gen-mdc` &middot; [docs/integrations/cursor-mcp.md](docs/integrations/cursor-mcp.md) |
-| **Continue.dev** | `@engram` context provider | [docs/integrations/continue.md](docs/integrations/continue.md) |
-| **Zed** | Context server (`/engram`) | `engram context-server` |
-| **Aider** | Context file generation | `engram gen-aider` |
+| **Claude Code** | Hook-based interception (native, automatic) — **plus** `/plugin install engram` for slash-commands | `engram install-hook` &middot; [docs/integrations/claude-code.md](docs/integrations/claude-code.md) |
+| **Cursor** | MDC snapshot + native MCP + VS Code extension on OpenVSX | `engram gen-mdc` &middot; [docs/integrations/cursor-mcp.md](docs/integrations/cursor-mcp.md) |
+| **Cline** | MCP server (5M+ VS Code installs, no native answer to token burn) | [docs/integrations/cline.md](docs/integrations/cline.md) |
+| **Continue.dev** | `@engram` context provider via [`engramx-continue`](https://www.npmjs.com/package/engramx-continue) | [docs/integrations/continue.md](docs/integrations/continue.md) |
+| **Aider** | Context file generation | `engram gen-aider` &middot; [docs/integrations/aider.md](docs/integrations/aider.md) |
 | **Windsurf** (Codeium) | `.windsurfrules` snapshot + MCP | `engram gen-windsurfrules` |
+| **Zed** | Context server (`/engram`) | `engram context-server` &middot; [docs/integrations/zed.md](docs/integrations/zed.md) |
+| **OpenAI Codex CLI** | `AGENTS.md` auto-emit (universal Linux Foundation standard) | `engram gen` (default emits both `AGENTS.md` + `CLAUDE.md`) |
+| **VS Code (any agent)** | Status-bar entry + 6 commands wrapping the CLI | `code --install-extension engram-vscode` (OpenVSX) |
 | **Neovim** | MCP via codecompanion / avante | [docs/integrations/neovim.md](docs/integrations/neovim.md) |
 | **Emacs** | MCP via gptel-mcp | [docs/integrations/emacs.md](docs/integrations/emacs.md) |
 
@@ -385,17 +402,40 @@ Per-IDE setup guides are in [`docs/integrations/`](docs/integrations/).
 
 ## How It Compares
 
+The "context spine" slot — local-first, code-aware, works in any MCP runtime, with a reproducible benchmark — is currently unowned. Here's the field as of May 2026:
+
+|  | **engramx** | Cursor index | Aider repo map | Cline | Continue.dev | Mem0 | claude-mem | CartoGopher |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| Works in any MCP runtime | ✅ | IDE-locked | Aider only | VS Code only | VS Code only | ✅ | Claude Code only | ✅ |
+| Local-first (nothing leaves machine) | ✅ | cloud-synced | ✅ | ✅ | ✅ | optional | ✅ | ✅ |
+| Code-aware AST graph | ✅ | proprietary | ✅ | — | — | — | — | ✅ |
+| Reproducible benchmark | ✅ **89.1%** | — | — | — | — | — | — | claims 88% |
+| Bi-temporal mistake memory | ✅ | — | — | — | — | — | partial | — |
+| `AGENTS.md` + `CLAUDE.md` dual-emit | ✅ | — | — | — | — | — | — | — |
+| Single npm install | ✅ | full IDE | pip | VS Code ext | VS Code ext | pip / npm | claude plugin | Go binary |
+| License | Apache 2.0 | proprietary | Apache 2.0 | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT | unknown |
+| GitHub stars (May 2026) | 108 | proprietary | 39K | 61.2K | 32.4K | 47.8K | new | unknown |
+
+The matrix isn't a slight at any of them — most do something engram doesn't. Cursor's index is great inside Cursor. Aider's repo map is great in Aider. Cline's full-file rewrite model is honest about what it is. The point is that nobody else covers all eight rows. Engram is the only tool that does.
+
+For the legacy comparison vs `Continue @RepoMap` / `Cursor .cursorrules` / `@199-bio/engram` (small repo-map approaches), see the matrix below.
+
+<details>
+<summary><strong>Legacy detailed comparison</strong></summary>
+
 | | engram | Continue @RepoMap | Cursor .cursorrules | Aider repo-map | @199-bio/engram |
 |---|---|---|---|---|---|
 | **Interception model** | Hook-based, automatic on every Read | Fetched at @-mention time | Static file, manual | Per-session map | MCP server, called explicitly |
 | **Cache strategy** | SQLite at SessionStart, <5ms per read | No cache — live fetch | No cache | Per-session only | No cache |
 | **Persistent memory** | Decisions, mistakes, patterns across sessions | No | Manual text file | No | No |
-| **Multiple providers** | 8 (AST, git, mistakes, MemPalace, Context7, Obsidian, LSP) | Repo structure only | No | Repo structure only | Graph query only |
+| **Multiple providers** | 9 (AST, git, mistakes, MemPalace, Context7, Obsidian, LSP, Anthropic Memory, MCP plugins) | Repo structure only | No | Repo structure only | Graph query only |
 | **Mistake tracking** | LSP diagnostics → mistake nodes, ⚠️ on Edit | No | No | No | No |
 | **Survives compaction** | Yes (PreCompact hook) | No | Yes (static file) | No | No |
 | **LLM cost** | $0 | $0 | $0 | $0 | $0 |
 | **Native deps** | Zero | No | No | No | No |
 
+</details>
+
 ---
 
 ## Install + Configuration

package/dist/cli.js

@@ -1393,6 +1393,51 @@ async function handleCwdChanged(payload) {
   }
 }
 
+// src/cost/instrument.ts
+import { statSync as statSync3 } from "fs";
+var CHARS_PER_TOKEN = 4;
+function tokensFromChars(chars) {
+  if (!Number.isFinite(chars) || chars <= 0) return 0;
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+function extractInjectedTokens(result) {
+  if (!result || typeof result !== "object") return 0;
+  try {
+    const hook = result.hookSpecificOutput;
+    if (!hook || typeof hook !== "object") return 0;
+    const reason = hook.permissionDecisionReason;
+    if (typeof reason === "string" && reason.length > 0) {
+      return tokensFromChars(reason.length);
+    }
+    const ctx = hook.additionalContext;
+    if (typeof ctx === "string" && ctx.length > 0) {
+      return tokensFromChars(ctx.length);
+    }
+  } catch {
+  }
+  return 0;
+}
+function estimateWouldHaveReadTokens(tool, filePath) {
+  if (tool !== "Read") return 0;
+  if (!filePath || typeof filePath !== "string") return 0;
+  try {
+    const size = statSync3(filePath).size;
+    return tokensFromChars(size);
+  } catch {
+    return 0;
+  }
+}
+function composeCostFields(tool, filePath, result) {
+  const injected = extractInjectedTokens(result);
+  const wouldHaveRead = estimateWouldHaveReadTokens(tool, filePath);
+  const tokensSaved = Math.max(0, wouldHaveRead - injected);
+  const out = {};
+  if (wouldHaveRead > 0) out.wouldHaveRead = wouldHaveRead;
+  if (injected > 0) out.injected = injected;
+  if (tokensSaved > 0) out.tokensSaved = tokensSaved;
+  return out;
+}
+
 // src/intercept/dispatch.ts
 function validatePayload(raw) {
   if (raw === null || typeof raw !== "object") return null;
@@ -1468,11 +1513,13 @@ async function dispatchPreToolUse(payload) {
       if (projectRoot) {
         const decision = extractPreToolDecision(result);
         const filePath = typeof handlerPayload.tool_input?.file_path === "string" ? handlerPayload.tool_input.file_path : void 0;
+        const cost = composeCostFields(tool, filePath, result);
         logHookEvent(projectRoot, {
           event: "PreToolUse",
           tool,
           path: filePath,
-          decision
+          decision,
+          ...cost
         });
       }
     }
@@ -1494,7 +1541,7 @@ function extractPreToolDecision(result) {
 
 // src/dashboard.ts
 import chalk from "chalk";
-import { existsSync as existsSync5, statSync as statSync3 } from "fs";
+import { existsSync as existsSync5, statSync as statSync4 } from "fs";
 import { join as join5, resolve as resolve6, basename as basename4 } from "path";
 var AMBER = chalk.hex("#d97706");
 var DIM = chalk.dim;
@@ -1617,7 +1664,7 @@ function startDashboard(projectRoot, options = {}) {
     try {
       const logPath = join5(root, ".engram", "hook-log.jsonl");
       if (existsSync5(logPath)) {
-        const currentSize = statSync3(logPath).size;
+        const currentSize = statSync4(logPath).size;
         if (currentSize !== lastSize) {
           cachedEntries = readHookLog(root);
           lastSize = currentSize;
@@ -1680,7 +1727,7 @@ import {
   readFileSync as readFileSync3,
   writeFileSync,
   renameSync,
-  statSync as statSync4
+  statSync as statSync5
 } from "fs";
 import { join as join6 } from "path";
 var ENGRAM_MARKER_START = "<!-- engram:structural-facts:start -->";
@@ -1757,7 +1804,7 @@ function writeEngramSectionToMemoryMd(projectRoot, engramSection) {
   try {
     let existing = "";
     if (existsSync6(memoryPath)) {
-      const st = statSync4(memoryPath);
+      const st = statSync5(memoryPath);
       if (st.size > MAX_MEMORY_FILE_BYTES) {
         return false;
       }
@@ -2166,6 +2213,47 @@ program.command("bench").description("Run token reduction benchmark").option("-p
   }
   console.log();
 });
+program.command("cost").description("Show token-savings telemetry from engram hook logs").option(
+  "-p, --project <path...>",
+  "One or more project roots. Defaults to current dir if omitted."
+).option("--digest", "Write weekly Markdown digest to ~/.engram/").option("--json", "Emit machine-readable JSON instead of a terminal table").action(
+  async (opts) => {
+    const cost = await import("./cost-CSILPTZT.js");
+    const roots = opts.project && opts.project.length > 0 ? opts.project.map((p) => pathResolve2(p)) : [pathResolve2(".")];
+    if (opts.digest) {
+      const result = cost.writeWeeklyDigest(roots);
+      console.log(
+        chalk2.green(
+          `wrote ${result.isoWeek} digest \u2192 ${result.path} (${result.rows.length} project${result.rows.length === 1 ? "" : "s"})`
+        )
+      );
+      return;
+    }
+    const rows = cost.summarizeProjects(roots);
+    if (opts.json) {
+      console.log(JSON.stringify(rows, null, 2));
+      return;
+    }
+    console.log(chalk2.bold("\nengram cost lens\n"));
+    console.log(cost.formatTable(rows));
+    const totalSaved = rows.reduce(
+      (a, r) => a + r.summary.tokensSaved,
+      0
+    );
+    const totalEvents = rows.reduce((a, r) => a + r.summary.events, 0);
+    const totalUsd = rows.reduce(
+      (a, r) => a + r.summary.approxUsdSaved,
+      0
+    );
+    console.log(
+      chalk2.dim(
+        `
+total: ${cost.formatNumber(totalSaved)} tokens saved \xB7 ${cost.formatUsd(totalUsd)} \xB7 ${totalEvents} events
+`
+      )
+    );
+  }
+);
 var hooks = program.command("hooks").description("Manage git hooks");
 hooks.command("install").description("Install post-commit and post-checkout hooks").argument("[path]", "Project directory", ".").action((p) => console.log(install(p)));
 hooks.command("uninstall").description("Remove engram git hooks").argument("[path]", "Project directory", ".").action((p) => console.log(uninstall(p)));
@@ -2761,7 +2849,7 @@ program.command("stress-test").description("Run stress tests: memory, concurrenc
   }
 });
 program.command("server").description("Start engram HTTP REST server (binds to 127.0.0.1 only)").option("--http", "Enable HTTP server (default)").option("--port <port>", "HTTP port", "7337").option("-p, --project <path>", "Project directory", ".").action(async (opts) => {
-  const { startHttpServer } = await import("./server-2ZQKXJ5M.js");
+  const { startHttpServer } = await import("./server-LEYILLJ2.js");
   await startHttpServer(pathResolve2(opts.project), parseInt(opts.port, 10));
 });
 program.command("ui").description("Open the web dashboard (auto-starts HTTP server if needed)").option("--port <port>", "HTTP port", "7337").option("-p, --project <path>", "Project directory", ".").option("--no-open", "Don't launch browser, just print the URL").action(async (opts) => {
@@ -2989,7 +3077,7 @@ pluginCmd.command("list").description("List installed provider plugins").action(
   }
 });
 pluginCmd.command("install").description("Install a plugin by copying its .mjs file into ~/.engram/plugins/").argument("<file>", "Path to plugin .mjs file").action(async (file) => {
-  const { copyFileSync: copyFileSync2, statSync: statSync5 } = await import("fs");
+  const { copyFileSync: copyFileSync2, statSync: statSync6 } = await import("fs");
   const { basename: basename6 } = await import("path");
   const { getPluginsDir, ensurePluginsDir, validatePlugin } = await import("./plugin-loader-SQQB6V74.js");
   const { pathToFileURL } = await import("url");
@@ -2998,7 +3086,7 @@ pluginCmd.command("install").description("Install a plugin by copying its .mjs f
     console.error(chalk2.red(`File not found: ${absPath}`));
     process.exit(1);
   }
-  if (!statSync5(absPath).isFile()) {
+  if (!statSync6(absPath).isFile()) {
     console.error(chalk2.red(`Not a file: ${absPath}`));
     process.exit(1);
   }
@@ -3193,7 +3281,7 @@ program.command("setup").description("Zero-friction first-run wizard (init + ins
   "local"
 ).action(
   async (opts) => {
-    const { runSetup } = await import("./wizard-UH27IO4I.js");
+    const { runSetup } = await import("./wizard-WGBAIZLF.js");
     const scope = opts.scope === "local" || opts.scope === "project" || opts.scope === "user" ? opts.scope : "local";
     const result = await runSetup({
       projectPath: opts.project,

package/dist/cost-CSILPTZT.js

@@ -0,0 +1,227 @@
+// src/cost/types.ts
+var DEFAULT_COST_CONFIG = {
+  inputUsdPerMillion: 3,
+  currency: "USD"
+};
+
+// src/cost/aggregator.ts
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+var LOG_FILES = ["hook-log.jsonl", "hook-log.jsonl.1"];
+function readEvents(projectRoot) {
+  const out = [];
+  for (const name of LOG_FILES) {
+    const p = join(projectRoot, ".engram", name);
+    if (!existsSync(p)) continue;
+    let raw = "";
+    try {
+      raw = readFileSync(p, "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const parsed = JSON.parse(line);
+        out.push(toCostEvent(parsed));
+      } catch {
+      }
+    }
+  }
+  return out;
+}
+function toCostEvent(raw) {
+  const tokensSaved = numOrUndef(raw.tokensSaved);
+  const injected = numOrUndef(raw.injected);
+  const wouldHaveRead = numOrUndef(
+    raw.wouldHaveRead
+  );
+  return {
+    ts: typeof raw.ts === "string" ? raw.ts : (/* @__PURE__ */ new Date(0)).toISOString(),
+    event: typeof raw.event === "string" ? raw.event : "unknown",
+    tool: strOrUndef(raw.tool),
+    path: strOrUndef(raw.path),
+    wouldHaveRead,
+    injected,
+    tokensSaved
+  };
+}
+function numOrUndef(v) {
+  return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : void 0;
+}
+function strOrUndef(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function summarize(events, config = DEFAULT_COST_CONFIG) {
+  let saved = 0;
+  let injected = 0;
+  let wouldHave = 0;
+  let firstTs = "";
+  let lastTs = "";
+  for (const e of events) {
+    if (e.tokensSaved) saved += e.tokensSaved;
+    if (e.injected) injected += e.injected;
+    if (e.wouldHaveRead) wouldHave += e.wouldHaveRead;
+    if (!firstTs || e.ts < firstTs) firstTs = e.ts;
+    if (!lastTs || e.ts > lastTs) lastTs = e.ts;
+  }
+  const denom = wouldHave > 0 ? wouldHave : saved + injected;
+  const reductionRatio = denom > 0 ? saved / denom : 0;
+  const approxUsdSaved = saved / 1e6 * config.inputUsdPerMillion;
+  return {
+    fromTs: firstTs,
+    toTs: lastTs,
+    events: events.length,
+    tokensSaved: saved,
+    tokensInjected: injected,
+    tokensWouldHave: wouldHave,
+    reductionRatio,
+    approxUsdSaved
+  };
+}
+function summarizeProjects(projectRoots, config = DEFAULT_COST_CONFIG) {
+  return projectRoots.map((projectRoot) => ({
+    projectRoot,
+    summary: summarize(readEvents(projectRoot), config)
+  }));
+}
+
+// src/cost/formatter.ts
+function formatNumber(n) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(2)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return String(Math.round(n));
+}
+function formatUsd(n) {
+  if (n >= 1) return `$${n.toFixed(2)}`;
+  if (n >= 0.01) return `$${n.toFixed(3)}`;
+  return `$${n.toFixed(4)}`;
+}
+function formatPct(ratio) {
+  return `${(ratio * 100).toFixed(1)}%`;
+}
+function formatOneLine(s) {
+  return [
+    `${formatNumber(s.tokensSaved)} tokens saved`,
+    `${formatPct(s.reductionRatio)} reduction`,
+    `~${formatUsd(s.approxUsdSaved)}`,
+    `${s.events} events`
+  ].join(" \xB7 ");
+}
+function formatTable(rows) {
+  if (rows.length === 0) return "(no projects with hook-log.jsonl)";
+  const lines = [];
+  lines.push("Project                            Tokens saved   Reduction   Approx USD   Events");
+  lines.push("\u2500".repeat(86));
+  for (const r of rows) {
+    const name = truncate(basenameOf(r.projectRoot), 32).padEnd(34);
+    const saved = formatNumber(r.summary.tokensSaved).padStart(13);
+    const pct = formatPct(r.summary.reductionRatio).padStart(11);
+    const usd = formatUsd(r.summary.approxUsdSaved).padStart(12);
+    const ev = String(r.summary.events).padStart(7);
+    lines.push(`${name}${saved}   ${pct}   ${usd}   ${ev}`);
+  }
+  return lines.join("\n");
+}
+function formatMarkdownDigest(rows, totals, isoWeek) {
+  const lines = [];
+  lines.push(`# Engram Cost Digest \u2014 ${isoWeek}`);
+  lines.push("");
+  lines.push(`**Total tokens saved:** ${formatNumber(totals.tokensSaved)} (${formatPct(totals.reductionRatio)} reduction, ~${formatUsd(totals.approxUsdSaved)})`);
+  lines.push("");
+  lines.push("## Per-project");
+  lines.push("");
+  lines.push("| Project | Tokens saved | Reduction | Approx USD | Events |");
+  lines.push("|---|---:|---:|---:|---:|");
+  for (const r of rows) {
+    lines.push([
+      "",
+      basenameOf(r.projectRoot),
+      formatNumber(r.summary.tokensSaved),
+      formatPct(r.summary.reductionRatio),
+      formatUsd(r.summary.approxUsdSaved),
+      String(r.summary.events),
+      ""
+    ].join("|"));
+  }
+  lines.push("");
+  lines.push("_Generated by `engram cost --digest` (v3.3 Cost Lens)_");
+  return lines.join("\n");
+}
+function basenameOf(p) {
+  const idx = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+  return idx >= 0 ? p.slice(idx + 1) : p;
+}
+function truncate(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 1)}\u2026`;
+}
+
+// src/cost/digest.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join as join2 } from "path";
+function isoWeekLabel(d = /* @__PURE__ */ new Date()) {
+  const target = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+  const dayNum = (target.getUTCDay() + 6) % 7;
+  target.setUTCDate(target.getUTCDate() - dayNum + 3);
+  const firstThursday = new Date(Date.UTC(target.getUTCFullYear(), 0, 4));
+  const weekNum = 1 + Math.round(
+    ((target.getTime() - firstThursday.getTime()) / 864e5 - 3 + (firstThursday.getUTCDay() + 6) % 7) / 7
+  );
+  return `${target.getUTCFullYear()}-W${String(weekNum).padStart(2, "0")}`;
+}
+function writeWeeklyDigest(projectRoots, config = DEFAULT_COST_CONFIG, outDir = join2(homedir(), ".engram"), now = /* @__PURE__ */ new Date()) {
+  mkdirSync(outDir, { recursive: true });
+  const rows = summarizeProjects(projectRoots, config);
+  const totals = sumRows(rows, config);
+  const isoWeek = isoWeekLabel(now);
+  const md = formatMarkdownDigest(rows, totals, isoWeek);
+  const path = join2(outDir, `cost-report-${isoWeek}.md`);
+  writeFileSync(path, md, "utf8");
+  return { path, isoWeek, rows };
+}
+function sumRows(rows, config) {
+  let saved = 0;
+  let injected = 0;
+  let wouldHave = 0;
+  let events = 0;
+  let firstTs = "";
+  let lastTs = "";
+  for (const r of rows) {
+    saved += r.summary.tokensSaved;
+    injected += r.summary.tokensInjected;
+    wouldHave += r.summary.tokensWouldHave;
+    events += r.summary.events;
+    if (r.summary.fromTs && (!firstTs || r.summary.fromTs < firstTs)) {
+      firstTs = r.summary.fromTs;
+    }
+    if (r.summary.toTs && (!lastTs || r.summary.toTs > lastTs)) {
+      lastTs = r.summary.toTs;
+    }
+  }
+  const denom = wouldHave > 0 ? wouldHave : saved + injected;
+  return {
+    fromTs: firstTs,
+    toTs: lastTs,
+    events,
+    tokensSaved: saved,
+    tokensInjected: injected,
+    tokensWouldHave: wouldHave,
+    reductionRatio: denom > 0 ? saved / denom : 0,
+    approxUsdSaved: saved / 1e6 * config.inputUsdPerMillion
+  };
+}
+export {
+  DEFAULT_COST_CONFIG,
+  formatMarkdownDigest,
+  formatNumber,
+  formatOneLine,
+  formatPct,
+  formatTable,
+  formatUsd,
+  isoWeekLabel,
+  readEvents,
+  summarize,
+  summarizeProjects,
+  writeWeeklyDigest
+};

package/dist/{wizard-UH27IO4I.js → wizard-WGBAIZLF.js}

@@ -99,13 +99,66 @@ function detectAider(projectRoot) {
     status: !installed ? "not detected" : configured ? ".aider-context.md present" : "detected \u2014 run `engram gen-aider`"
   };
 }
+function detectCline() {
+  const candidates = [
+    join(homedir(), "Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev"),
+    join(homedir(), ".config/Code/User/globalStorage/saoudrizwan.claude-dev"),
+    join(homedir(), "AppData/Roaming/Code/User/globalStorage/saoudrizwan.claude-dev")
+  ];
+  const installed = candidates.some(existsSync);
+  let configured = false;
+  if (installed) {
+    try {
+      configured = candidates.filter(existsSync).some((p) => {
+        const settings = join(p, "settings", "cline_mcp_settings.json");
+        return existsSync(settings) && readFileSync(settings, "utf-8").includes("engram");
+      });
+    } catch {
+      configured = false;
+    }
+  }
+  return {
+    name: "Cline",
+    installed,
+    configured,
+    status: !installed ? "not detected" : configured ? "engram MCP server registered" : "detected \u2014 add engram-serve to cline_mcp_settings.json"
+  };
+}
+function detectZed(projectRoot) {
+  const candidates = [
+    join(homedir(), ".config/zed"),
+    join(homedir(), "Library/Application Support/Zed"),
+    join(homedir(), "AppData/Roaming/Zed")
+  ];
+  const installed = candidates.some(existsSync);
+  const configured = existsSync(join(projectRoot, ".zed", "settings.json"));
+  return {
+    name: "Zed",
+    installed,
+    configured,
+    status: !installed ? "not detected" : configured ? "Zed project settings present" : "detected \u2014 add engram context server"
+  };
+}
+function detectCodex(projectRoot) {
+  const installed = existsSync(join(homedir(), ".codex"));
+  const configured = existsSync(join(projectRoot, "AGENTS.md"));
+  return {
+    name: "Codex CLI",
+    installed,
+    configured,
+    status: !installed ? "not detected" : configured ? "AGENTS.md present" : "detected \u2014 run `engram gen` to create AGENTS.md"
+  };
+}
 function detectAllIdes(projectRoot) {
   return [
     detectClaudeCode(projectRoot),
     detectCursor(projectRoot),
-    detectWindsurf(projectRoot),
+    detectCline(),
     detectContinue(),
-    detectAider(projectRoot)
+    detectWindsurf(projectRoot),
+    detectAider(projectRoot),
+    detectZed(projectRoot),
+    detectCodex(projectRoot)
   ];
 }
 
@@ -214,7 +267,11 @@ async function offerIdeAdapters(opts, rl) {
   const suggest = {
     Cursor: "engram gen-mdc",
     Windsurf: "engram gen-windsurfrules",
-    Aider: "engram gen-aider"
+    Aider: "engram gen-aider",
+    "Codex CLI": "engram gen --target agents",
+    Cline: "Add to cline_mcp_settings.json: { engram: { command: 'engram-serve', args: ['" + root + "'] } }",
+    "Continue.dev": "Add to ~/.continue/config.json: { contextProviders: [{ name: 'engramx-continue' }] }",
+    Zed: "Register engram-serve as a Zed context server (see Docs/integrations/zed.md)"
   };
   const suggested = [];
   for (const ide of unconfigured) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "3.0.2",
+  "version": "3.4.0",
   "mcpName": "io.github.NickCirv/engram",
   "description": "The context spine for AI coding agents. 9 built-in providers + mcpConfig plugin contract (wrap any MCP server in 10 lines), generic MCP-client aggregator (stdio), pre-mortem mistake-guard, bi-temporal mistake memory, Anthropic Auto-Memory bridge, SSE streaming context packets, dual-emit AGENTS.md+CLAUDE.md. 90.8% measured real-world token savings (reproducible bench included). Local SQLite, zero cloud.",
   "repository": {

package/dist/{server-2ZQKXJ5M.js → server-LEYILLJ2.js}

@@ -1,7 +1,3 @@
-import {
-  ContextCache,
-  getContextCache
-} from "./chunk-CIQQ5Y3S.js";
 import {
   getOrCreateToken,
   isHostValid,
@@ -9,6 +5,10 @@ import {
   parseCookies,
   safeEqual
 } from "./chunk-N6PPKOPK.js";
+import {
+  ContextCache,
+  getContextCache
+} from "./chunk-CIQQ5Y3S.js";
 import {
   summarizeHookLog
 } from "./chunk-FKY6HIT2.js";