engramx 3.0.2 → 3.3.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to engram are documented here. Format based on
 
 ## [Unreleased]
 
+### Added — v3.3 "Cost Lens" (in progress, target: 2026-05-08)
+- 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` (CostEvent / CostSummary / CostConfig), `aggregator.ts` (read + summarize), `formatter.ts` (one-liner / table / Markdown digest), `digest.ts` (ISO-week digest writer with idempotent file output).
+- 13 new tests in `tests/cost.test.ts`, hermetic — use tmp dirs with synthetic logs, no real engram state required.
+- USD estimate uses configurable `inputUsdPerMillion` rate. Default $3.00/M matches Claude Sonnet 4.6 input pricing as of 2026-04-27.
+
+### Why
+Cost Lens is the baseline for everything in the v3.3 → v4.0 roadmap. We need a measured number that survives between releases so future features (Mesh, Vector, Bridge) can be evaluated against the real-world impact, not against a single benchmark file. The PRD lives at `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

@@ -1,119 +1,181 @@
 <p align="center">
-  <img src="assets/banner-v3.png" alt="EngramX — the cached context spine for AI coding agents (v3.0 'Spine')" width="100%">
+  <img src="assets/banner-v3.png" alt="EngramX — the memory layer for AI coding agents" width="100%">
 </p>
 
-<!-- ============================================================
-     24-second product showcase (Hyperframes-rendered MP4 + WebM).
-     Source: docs/demos/showcase.html · scenes drive both the
-     live HTML player and this MP4. Edit scene-table.md to change.
-     If the MP4 isn't rendered yet, GitHub gracefully shows the
-     poster image and links to the live HTML player.
-     ============================================================ -->
 <p align="center">
-  <video src="https://raw.githubusercontent.com/NickCirv/engram/main/docs/demos/showcase.mp4"
-         controls
-         muted
-         playsinline
-         poster="docs/demos/poster.svg"
-         width="100%">
-    <a href="docs/demos/showcase.html">
-      <img src="docs/demos/poster.svg" alt="engram — 24-second showcase (click to open the live HTML player)" width="100%">
-    </a>
-  </video>
-</p>
-
-<p align="center">
-  <sub>
-    <a href="docs/install.html"><strong>Install Page</strong></a> ·
-    <a href="docs/demos/showcase.html"><strong>Live Demo</strong></a> ·
-    <a href="docs/demos/scene-table.md"><strong>Scene Table</strong></a> ·
-    rendered with <a href="https://github.com/heygen-com/hyperframes">Hyperframes</a>
-  </sub>
-</p>
-
-<p align="center">
-  <a href="#install"><strong>Install</strong></a> ·
-  <a href="#quickstart"><strong>Quickstart</strong></a> ·
-  <a href="#dashboard"><strong>Dashboard</strong></a> ·
-  <a href="#benchmark"><strong>Benchmark</strong></a> ·
-  <a href="#ide-integrations"><strong>IDE Integrations</strong></a> ·
-  <a href="#http-api"><strong>HTTP API</strong></a> ·
-  <a href="#ecp-spec"><strong>ECP Spec</strong></a> ·
-  <a href="#contributing"><strong>Contributing</strong></a>
+  <strong>The memory layer that stretches every Claude session.</strong>
 </p>
 
 <p align="center">
   <a href="https://github.com/NickCirv/engram/actions"><img src="https://github.com/NickCirv/engram/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/engramx"><img src="https://img.shields.io/npm/v/engramx?color=blue" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/engramx"><img src="https://img.shields.io/npm/dm/engramx?color=blue" alt="npm downloads"></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-878%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">
+  <a href="https://discord.gg/engramx"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/NickCirv/engram/stargazers"><img src="https://img.shields.io/github/stars/NickCirv/engram?style=social" alt="Stars"></a>
+</p>
+
+<p align="center">
+  <a href="#anthropic-capped-your-week-engram-extends-it">Why</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#per-agent-setup">Per-agent setup</a> ·
+  <a href="#see-what-your-agent-has-remembered">engram remembers</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="ARCHITECTURE.md">Architecture</a> ·
+  <a href="https://discord.gg/engramx">Discord</a>
 </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.
+## Anthropic capped your week. engram extends it.
+
+In November 2025, Anthropic tightened weekly limits on Claude Pro and Max. Heavy Claude Code users now hit caps mid-week. Some by Wednesday. The honest reality nobody is naming out loud:
+
+> **Most of your weekly tokens are spent re-introducing yourself to an agent that forgets.**
+
+Every Monday starts from zero. The agent re-reads the codebase. Re-asks setup questions. Repeats last week's wrong fix. Re-decides architecture you already locked in. By Friday you're rate-limited. Not because you built a lot. Because the agent never got smarter.
+
+engram is the memory layer that fixes that. A persistent knowledge graph, plus a mistake replay buffer, plus a provider mesh that wires in mempalace, obsidian, context7, MCP servers, and Anthropic's own auto-memory. The agent stops being single-shot. It learns from its own history.
 
 ---
 
-# EngramX — the cached context spine for AI coding agents.
+### What changes when your agent has memory
 
-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.
+| | Without engram | With engram |
+|---|---|---|
+| **Monday** | Agent re-reads codebase from scratch (~40K tokens) | Reads structural graph (~3K tokens) |
+| **Tuesday** | Repeats Monday's wrong fix | ⚠️ Warned: *"You tried this Monday, broke parser.rs:42"* |
+| **Wednesday** | Re-decides architecture you already locked | Surfaces Monday's decision: *"We chose Saga over 2PC because…"* |
+| **Thursday** | Asks the same 5 setup questions | Pulls config from `mempalace`, `obsidian`, `context7` providers |
+| **Friday** | Cap hit by 3pm | Cap hit Sunday, if at all |
+
+Token savings (89.1% measured per Read interception, reproducible benchmark below) are the side-effect. Compounding agent intelligence is the product.
+
+---
 
-**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.
+## Install
 
-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.
+### macOS / Linux (recommended)
 
-**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).
+```bash
+brew install engramx
+```
 
-### One command to everything
+### Cross-platform fallback
 
 ```bash
 npm install -g engramx
-cd ~/my-project
-engram setup
 ```
 
-That's the install. `engram setup` runs `engram init` (builds the graph), `engram install-hook` (wires the Sentinel into your AI tool), detects your IDE, dual-emits `AGENTS.md` + `CLAUDE.md`, then runs `engram doctor` to verify everything green. Under 30 seconds on most projects. Works in Claude Code, Cursor, Codex CLI, Windsurf, GitHub Copilot Chat, JetBrains Junie, Aider, Zed, Continue — any agent that reads `AGENTS.md` or uses MCP.
+### Zero-dep one-liner
 
-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.
+```bash
+curl -fsSL engramx.dev/install | sh
+```
+
+Verify: `engram --version` should show `3.x` or later. Requires Node.js 20+. Zero native deps. No build tools, no Rust, no Python, no system libs.
+
+> **Note:** "engram" the audio plugin and "engram" the neuroscience term are different things. We're `engramx` on npm, `engram` on the CLI. Also not [Go-Engram](https://github.com/Gentleman-Programming/engram) (a salience-gated chat memory in Go) and not DeepSeek's January 2026 "Engram" paper (research artifact, not a product).
 
 ---
 
-## I'm not a developer — what does this actually do?
+## Per-agent setup
 
-Short answer: **your AI coding assistant stops charging you for the same information twice.**
+One command for your stack:
 
-Long answer:
+```bash
+engram init --agent claude          # Claude Code (default)
+engram init --agent cursor          # Cursor
+engram init --agent windsurf        # Windsurf
+engram init --agent codex           # OpenAI Codex
+engram init --agent gemini          # Gemini CLI
+engram init --agent cline           # Cline / Roo Code
+engram init --agent copilot         # GitHub Copilot CLI
+engram init --agent kilocode        # Kilo Code
+engram init --agent antigravity     # Google Antigravity
+```
 
-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.
+One run wires the right hooks, settings, and per-agent config files. Restart your AI tool. engram is live.
 
-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.
+Prefer the all-in-one bootstrap? `engram setup` runs `engram init` + `engram install-hook` + IDE detection + dual-emits `AGENTS.md` and `CLAUDE.md` + `engram doctor`. Under 30 seconds on most projects.
 
-**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.
+---
 
-**Want out?** Clean uninstall is one command:
+## See what your agent has remembered
 
 ```bash
-npm uninstall -g engramx     # 3.0.1+ auto-runs preuninstall hook-cleanup
+$ engram remembers
+
+  43 mistakes avoided     ⚠️  surfaced before the agent could repeat them
+ 127 decisions surfaced   📜  prior architectural choices recalled in context
+  18 cross-session bridges 🔗 sessions that picked up where the last one ended
+  86K tokens saved        🎟️  ~ 4.3 hours of weekly cap, reclaimed
+   7 days indexed         📅  since engram init
+
+Your subscription, stretched.
+```
+
+Cumulative since `engram init`. Run it weekly. Share the screenshot.
+
+---
+
+## How it works
+
+```
+  Without engram:                              With engram:
+
+  Claude → reads file.rs (8,000 tokens)        Claude → reads file.rs
+                                                          ↓
+                                               engram intercepts → graph context (800 tokens)
+                                                          ↓
+                                               Claude sees: structure
+                                                         + last week's mistakes (⚠️ pre-mortem)
+                                                         + relevant decisions
+                                                         + git co-changes
+                                                         + cross-session memory
 ```
 
-If you installed 3.0.0 and ran `npm uninstall` before the 3.0.1 patch shipped, your Claude Code hooks may be orphaned. Run `engram repair-hooks --scope user` (install 3.0.1 first if needed) or see the [`CHANGELOG.md`](CHANGELOG.md#301--2026-04-24--clean-uninstall) for the manual `jq`-based recovery one-liner.
+Nine providers ship by default and every one is pluggable:
+
+| Provider | Surfaces |
+|---|---|
+| `structure` | AST-derived class/function/import graph of the project |
+| `mistakes` | What broke last week. Pre-mortem warnings before the agent re-makes the error. Bi-temporal: refactored-away mistakes stop firing. |
+| `git` | Hot files, co-change pairs, authorship signals |
+| `mempalace` | Your local semantic memory (mempalace MCP / ChromaDB) |
+| `context7` | Up-to-date library docs (Context7 MCP) |
+| `obsidian` | Your knowledge vault, queried at agent-time |
+| `anthropic-memory` | Anthropic's auto-memory bridge |
+| `mcp-client` | Any MCP server. engram talks to all of them. |
+| `lsp` | Live language-server symbols (Serena, etc.) |
+
+Add your own: drop a 10-line `.mjs` into `~/.engram/plugins/`. Validated before install.
+
+---
+
+## Why this exists
+
+Stateless agents are amnesiacs with PhDs. They solve the problem in front of them, then never get smarter at *your* codebase. Multiply that by Anthropic's weekly caps and every session burns tokens re-learning what last session already learned.
+
+engram is the spine that connects sessions. It does what stateless tools physically can't:
+
+1. **Persistence.** `.engram/graph.db` survives every restart, every cap reset, every laptop reboot. Your agent gets a brain that remembers.
+2. **Mistake memory.** Pre-mortem warnings before the agent repeats last week's error. Surfaced at the top of context, automatically.
+3. **Provider mesh.** Runtime composition across knowledge sources you already use. mempalace, obsidian, context7, MCP servers, all wired in.
+
+Token compression is downstream of those.
 
 ---
 
 ## 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.
+Everything above is measured. `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)):
+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 |
 |---|---|
@@ -128,23 +190,36 @@ Reproduce on your own code:
 
 ```bash
 cd your-project
-engram init                          # first-time setup for this project
+engram init
 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.
+Small projects score lower. Dense structural projects score higher. It's real arithmetic on your files. You can audit every number.
+
+---
+
+## Companion tools
+
+engram compresses what the codebase *is* (file contents into graph context). For compressing what the system is *doing* (shell command output) pair it with [rtk](https://github.com/rtk-ai/rtk):
+
+```bash
+brew install rtk           # 60-90% savings on git/npm/cargo/grep/etc. (Bash)
+brew install engramx       # 89% savings + memory + mistake-guard (Read)
+```
+
+Both register PreToolUse hooks. They don't conflict. rtk owns Bash, engram owns Read. Run both for a 3-5x weekly cap stretch end to end.
 
 ---
 
-## What engramx is not
+## Clean uninstall
 
-The "engram" name is contested. To save you a search:
+One command:
 
-- **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.
+```bash
+npm uninstall -g engramx     # 3.0.1+ auto-runs preuninstall hook-cleanup
+```
 
-`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.
+If you installed 3.0.0 and ran `npm uninstall` before the 3.0.1 patch shipped, your Claude Code hooks may be orphaned. Run `engram repair-hooks --scope user` (install 3.0.1 first) or see the [`CHANGELOG.md`](CHANGELOG.md#301--2026-04-24--clean-uninstall) for the manual `jq`-based recovery one-liner.
 
 ---
 
@@ -293,18 +368,6 @@ External providers cache into SQLite at SessionStart. Per-read resolution is a c
 
 ---
 
-## Install
-
-```bash
-npm install -g engramx
-```
-
-Requires Node.js 20+. Zero native dependencies. No build tools. Local SQLite via sql.js WASM — no Rust, no Python, no system libs.
-
-> **Prefer a designed walkthrough?** Open [**docs/install.html**](docs/install.html) — three-step install, benefits matrix, IDE coverage, FAQ. Local file, opens in any browser. Brand-matched terminal-mono aesthetic.
-
----
-
 ## Quickstart
 
 **One command, zero friction:**

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);
   }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engramx",
-  "version": "3.0.2",
+  "version": "3.3.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";