pi-mega-compact 0.4.0 → 0.4.1

package/README.md

@@ -115,48 +115,64 @@ OpenAI-style contract and the `MEGACOMPACT_EMBEDDING_KEY` / `MEGACOMPACT_EMBEDDI
   compile). No network call and no API key are needed at runtime.
 - A pi coding agent install that loads extensions from `~/.pi/agent/extensions/`.
 
-### From a git checkout
+### Install from npm (recommended)
 
 ```bash
-git clone https://github.com/TheArchitectit/pi-mega-compact.git \
-  ~/.pi/agent/extensions/pi-mega-compact
-cd ~/.pi/agent/extensions/pi-mega-compact
-npm install
-npm run build
+npm install pi-mega-compact
 ```
 
+This places the package in `node_modules` and exposes the extension entry at
+`node_modules/pi-mega-compact/extensions/mega-compact.ts`. Then point pi at it
+(see "Register with pi" below).
+
 ### Register with pi
 
-Either copy/link the extension into pi's extensions dir (the clone above already
-does), **or** add it to your pi config's `pi.extensions` list:
+Add the extension to your pi config's `pi.extensions` list, pointing at the
+installed entry (npm path or a symlink into pi's extensions dir — either works):
 
 ```jsonc
 {
   "pi": {
-    "extensions": ["~/.pi/agent/extensions/pi-mega-compact/extensions/mega-compact.ts"]
+    "extensions": ["pi-mega-compact/extensions/mega-compact.ts"]
   }
 }
 ```
 
-Or use the bundled helper (needs `jq`):
+Or symlink the installed package into pi's extensions dir (the simplest path if
+you run pi from the same machine):
 
 ```bash
-./install.sh          # copy into ~/.pi/agent/extensions/pi-mega-compact
-./install.sh -s       # symlink instead of copy (dev mode)
+ln -s "$(npm root)/pi-mega-compact" ~/.pi/agent/extensions/pi-mega-compact
 ```
 
+> **From a git checkout (development).** To hack on the extension, clone instead
+> and build locally:
+> ```bash
+> git clone https://github.com/TheArchitectit/pi-mega-compact.git \
+>   ~/.pi/agent/extensions/pi-mega-compact
+> cd ~/.pi/agent/extensions/pi-mega-compact
+> npm install && npm run build
+> ```
+> The bundled `./install.sh` helper (`copy`) / `./install.sh -s` (`symlink`) does
+> the same and also registers the path in pi's config (needs `jq`).
+
 ### Verify
 
 ```bash
-cd ~/.pi/agent/extensions/pi-mega-compact
-npm test          # all unit/integration tests pass (192 as of v0.2.0)
+npm test          # all unit/integration tests pass (278 as of v0.4.0)
 npm run lint      # tsc --noEmit + guardrails scan clean
 ```
 
 ### Uninstall
 
 ```bash
-rm -rf ~/.pi/agent/extensions/pi-mega-compact
+npm uninstall pi-mega-compact
+```
+
+If you symlinked it into pi's extensions dir, also remove that link:
+
+```bash
+rm -f ~/.pi/agent/extensions/pi-mega-compact
 ```
 
 Then remove the path from pi's `pi.extensions` array.

package/extensions/dashboard-server.ts

@@ -53,8 +53,24 @@ interface Snapshot {
   store: {
     checkpointCount: number;
     totalTokenEstimate: number;
+    tokensSaved: number;
     injectedCount: number;
     dedupHitRate: number;
+    storageDedupRate: number;
+    dedupCollapsed: number;
+  };
+  crew: {
+    activeAgents: number;
+    currentTurn: number;
+  };
+  repo: {
+    checkpointCount: number;
+    totalTokenEstimate: number;
+    tokensSaved: number;
+    sessionCount: number;
+    dedupAttempts: number;
+    dedupCollapsed: number;
+    storageDedupRate: number;
   };
 }
 
@@ -75,7 +91,9 @@ function readSnapshot(snapshotPath: string) {
       session: { id: null, state: null, persistedThisSession: false, lastCheckpointId: null, lastCompactedFrom: 0 },
       context: { tokens: null, percent: null, contextWindow: 0 },
       trigger: { armed: false, ready: false, currentTokens: null, thresholdTokens: 100_000, fastGatePct: 80 },
-      store: { checkpointCount: 0, totalTokenEstimate: 0, injectedCount: 0, dedupHitRate: 0 },
+      store: { checkpointCount: 0, totalTokenEstimate: 0, tokensSaved: 0, injectedCount: 0, dedupHitRate: 0, storageDedupRate: 0, dedupCollapsed: 0 },
+      crew: { activeAgents: 0, currentTurn: 0 },
+      repo: { checkpointCount: 0, totalTokenEstimate: 0, tokensSaved: 0, sessionCount: 0, dedupAttempts: 0, dedupCollapsed: 0, storageDedupRate: 0 },
     } as Snapshot;
   }
 }
@@ -166,12 +184,26 @@ function dashboardHtml(tierName: string): string {
     <h2>Vector Store</h2>
     <div class="stat-grid">
       <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Total Tokens</span><span class="value" id="st-tokens">0</span>
+      <span class="label">Tokens Stored</span><span class="value" id="st-tokens">0</span>
+      <span class="label">Tokens Saved</span><span class="value" id="st-saved">0</span>
       <span class="label">Injected</span><span class="value" id="st-injected">0</span>
       <span class="label">Dedup Rate</span><span class="value" id="st-dedup">0%</span>
+      <span class="label">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
+      <span class="label">Collapsed</span><span class="value" id="st-collapsed">0</span>
       <span class="label">Last ID</span><span class="value" id="st-lastid">—</span>
     </div>
   </div>
+  <div class="card">
+    <h2>Repo (all sessions)</h2>
+    <div class="stat-grid">
+      <span class="label">Checkpoints</span><span class="value" id="rp-count">0</span>
+      <span class="label">Tokens Stored</span><span class="value" id="rp-tokens">0</span>
+      <span class="label">Tokens Saved</span><span class="value" id="rp-saved">0</span>
+      <span class="label">Sessions</span><span class="value" id="rp-sessions">0</span>
+      <span class="label">Collapsed</span><span class="value" id="rp-collapsed">0</span>
+      <span class="label">Storage Dedup</span><span class="value" id="rp-sdedup">0%</span>
+    </div>
+  </div>
   <div class="card">
     <h2>Configuration</h2>
     <div class="conf-grid">
@@ -182,6 +214,14 @@ function dashboardHtml(tierName: string): string {
       <span class="label">Anchor</span><span class="value" id="cf-anchor">—</span>
     </div>
   </div>
+  <div class="card">
+    <h2>Crew / Agents</h2>
+    <div class="stat-grid">
+      <span class="label">Active Agents</span><span class="value" id="cr-agents">0</span>
+      <span class="label">Current Turn</span><span class="value" id="cr-turn">0</span>
+      <span class="label">Status</span><span class="value" id="cr-status">idle</span>
+    </div>
+  </div>
 </div>
 
 <div class="events">
@@ -223,10 +263,31 @@ function dashboardHtml(tierName: string): string {
 
     document.getElementById('st-count').textContent = d.store.checkpointCount;
     document.getElementById('st-tokens').textContent = d.store.totalTokenEstimate.toLocaleString();
+    document.getElementById('st-saved').textContent = (d.store.tokensSaved || 0).toLocaleString();
     document.getElementById('st-injected').textContent = d.store.injectedCount;
     document.getElementById('st-dedup').textContent = Math.round(d.store.dedupHitRate * 100) + '%';
+    var sdr = d.store.storageDedupRate || 0;
+    document.getElementById('st-sdedup').textContent = (sdr * 100 >= 10 ? Math.round(sdr * 100) : (sdr * 100).toFixed(1)) + '%';
+    document.getElementById('st-collapsed').textContent = d.store.dedupCollapsed || 0;
     document.getElementById('st-lastid').textContent = d.session.lastCheckpointId || '—';
 
+    // Repo-wide (all sessions in this repo's SQLite store).
+    var repo = d.repo || { checkpointCount: 0, totalTokenEstimate: 0, tokensSaved: 0, sessionCount: 0, dedupCollapsed: 0, storageDedupRate: 0 };
+    document.getElementById('rp-count').textContent = repo.checkpointCount;
+    document.getElementById('rp-tokens').textContent = repo.totalTokenEstimate.toLocaleString();
+    document.getElementById('rp-saved').textContent = (repo.tokensSaved || 0).toLocaleString();
+    document.getElementById('rp-sessions').textContent = repo.sessionCount || 0;
+    document.getElementById('rp-collapsed').textContent = repo.dedupCollapsed || 0;
+    var rsdr = repo.storageDedupRate || 0;
+    document.getElementById('rp-sdedup').textContent = (rsdr * 100 >= 10 ? Math.round(rsdr * 100) : (rsdr * 100).toFixed(1)) + '%';
+
+    // Crew / agents (live sub-agent activity + turn).
+    var crew = d.crew || { activeAgents: 0, currentTurn: 0 };
+    document.getElementById('cr-agents').textContent = crew.activeAgents || 0;
+    document.getElementById('cr-turn').textContent = crew.currentTurn || 0;
+    document.getElementById('cr-status').textContent = (crew.activeAgents > 0)
+      ? ('▶ ' + crew.activeAgents + ' running') : 'idle';
+
     document.getElementById('cf-tier').textContent = d.tier;
     document.getElementById('cf-threshold').textContent = d.config.thresholdTokens.toLocaleString();
     document.getElementById('cf-gate').textContent = d.config.fastGatePct + '%';

package/extensions/mega-compact.test.ts

@@ -322,9 +322,15 @@ test("state snapshot writes dashboard.json after compaction", async () => {
   const ctx = h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
   // Fire auto-trigger compaction (context event above 80% threshold)
   await h.fire("context", { type: "context", messages: h.session }, ctx);
-  const { existsSync: ex } = await import("node:fs");
+  const { existsSync: ex, readFileSync: rf } = await import("node:fs");
   const { join: j } = await import("node:path");
-  assert.ok(ex(j(h.stateDir, "dashboard.json")), "dashboard.json written after compaction");
+  const snapPath = j(h.stateDir, "dashboard.json");
+  assert.ok(ex(snapPath), "dashboard.json written after compaction");
+  const snap = JSON.parse(rf(snapPath, "utf-8"));
+  // Item B: tokensSaved is populated (original − stored) after a real compaction.
+  assert.ok(snap.store.tokensSaved > 0, "snapshot.store.tokensSaved > 0 after compaction");
+  // Item A: crew (live agent) block is present in the dashboard snapshot.
+  assert.ok(snap.crew && typeof snap.crew.activeAgents === "number", "snapshot.crew.activeAgents present");
 });
 
 test("events.log receives compaction events", async () => {

package/extensions/mega-compact.ts

@@ -57,6 +57,7 @@ interface SessionRuntime {
   lastCompactedTokens: number;
   dedupSkips: number;       // compactions skipped because regionHash already stored
   dedupAttempts: number;    // total compaction attempts (for hit-rate denominator)
+  tokensSaved: number;      // this session-instance only: reset on session_start
 }
 
 function envFlag(name: string, fallback: number): number {
@@ -190,12 +191,26 @@ interface DashboardSnapshot {
   store: {
     checkpointCount: number;
     totalTokenEstimate: number;
+    tokensSaved: number;
     injectedCount: number;
     dedupHitRate: number;
     storageDedupRate: number;
     dedupAttempts: number;
     dedupCollapsed: number;
   };
+  crew: {
+    activeAgents: number;
+    currentTurn: number;
+  };
+  repo: {
+    checkpointCount: number;     // across all sessions in this repo's store
+    totalTokenEstimate: number;  // repo-wide stored checkpoint tokens
+    tokensSaved: number;         // repo-wide cumulative stored-summary tokens
+    sessionCount: number;        // distinct sessions with checkpoints
+    dedupAttempts: number;       // cumulative add() calls (store-wide)
+    dedupCollapsed: number;      // cumulative deduped collapses (store-wide)
+    storageDedupRate: number;    // deduped / attempts, 0..1
+  };
 }
 
 class Dashboard {
@@ -261,6 +276,7 @@ export default function (pi: ExtensionAPI) {
   function snapshot(ctx?: ExtensionContext): void {
     if (ctx) bindRepo(ctx.cwd);
     const st = store.stats(rt.sessionId);
+    const repo = store.repoStats();
     const armed = lastCtxPercent != null && lastCtxPercent >= config.fastGatePct;
     const ready = armed && (lastCtxTokens ?? 0) >= config.thresholdTokens;
     dashboard.snapshot({
@@ -287,7 +303,17 @@ export default function (pi: ExtensionAPI) {
       },
       context: { tokens: lastCtxTokens, percent: lastCtxPercent, contextWindow: lastCtxWindow },
       trigger: { armed, ready, currentTokens: lastCtxTokens, thresholdTokens: config.thresholdTokens, fastGatePct: config.fastGatePct },
-      store: { checkpointCount: st.checkpointCount, totalTokenEstimate: st.totalTokenEstimate, injectedCount: st.injectedCount, dedupHitRate: st.dedupHitRate, storageDedupRate: st.storageDedupRate, dedupAttempts: st.dedupAttempts, dedupCollapsed: st.dedupCollapsed },
+      crew: { activeAgents, currentTurn },
+      store: { checkpointCount: st.checkpointCount, totalTokenEstimate: st.totalTokenEstimate, tokensSaved: rt.tokensSaved, injectedCount: st.injectedCount, dedupHitRate: st.dedupHitRate, storageDedupRate: st.storageDedupRate, dedupAttempts: st.dedupAttempts, dedupCollapsed: st.dedupCollapsed },
+      repo: {
+        checkpointCount: repo.checkpointCount,
+        totalTokenEstimate: repo.totalTokenEstimate,
+        tokensSaved: repo.tokensSaved,
+        sessionCount: repo.sessionCount,
+        dedupAttempts: repo.dedupAttempts,
+        dedupCollapsed: repo.dedupCollapsed,
+        storageDedupRate: repo.storageDedupRate,
+      },
     });
 
     // Live stats widget above the editor
@@ -303,7 +329,12 @@ export default function (pi: ExtensionAPI) {
       const dedupStr = storageRate * 100 >= 10
         ? `${Math.round(storageRate * 100)}%`
         : `${(storageRate * 100).toFixed(1)}%`;
-      const savedStr = st.totalTokenEstimate > 0 ? `${Math.round(st.totalTokenEstimate / 1000)}k` : "0";
+      // saved = cumulative original − stored tokens (this session). Show real
+      // token counts; use "k" only at/above 1000 so small-but-real savings are
+      // visible (previously Math.round(x/1000) rounded everything <1000 to 0).
+      const savedStr = rt.tokensSaved >= 1000
+        ? `${(rt.tokensSaved / 1000).toFixed(1)}k`
+        : `${rt.tokensSaved}`;
       const agentStr = activeAgents > 0 ? ` │ 🤖 ${activeAgents} agent${activeAgents === 1 ? "" : "s"}` : "";
       const turnStr = currentTurn > 0 ? ` │ turn ${currentTurn}` : "";
       ctx.ui.setWidget(
@@ -326,6 +357,7 @@ export default function (pi: ExtensionAPI) {
     lastCompactedTokens: 0,
     dedupSkips: 0,
     dedupAttempts: 0,
+    tokensSaved: 0,
   };
   let debounceUntil = 0;
   // Agent tracking for real-time widget updates
@@ -352,6 +384,7 @@ export default function (pi: ExtensionAPI) {
       lastCompactedTokens: 0,
       dedupSkips: 0,
       dedupAttempts: 0,
+      tokensSaved: 0,
     };
     statusKey = undefined;
     activeAgents = 0;
@@ -392,6 +425,11 @@ export default function (pi: ExtensionAPI) {
     rt.lastCompactedFrom = result.compactedFrom;
     rt.lastCompactedTokens = result.tokenEstimate;
     rt.dedupAttempts++;
+    // Per-session "tokens saved" = this session-instance only: the stored-summary
+    // tokens persisted on each NEW (non-deduped) compaction. It resets to 0 on
+    // session_start (rt is rebuilt) — so a fresh session shows 0 while the repo's
+    // cumulative saved (SQLite meta) keeps the historical running total.
+    if (!result.deduped) rt.tokensSaved += result.tokenEstimate;
     if (result.deduped) rt.dedupSkips++;
 
     // Sentinel marker: a non-LLM bookkeeping entry so subsequent triggers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",

package/src/store/sqlite.ts

@@ -145,6 +145,13 @@ function initSchema(db: Database.Database): void {
     );
     CREATE INDEX IF NOT EXISTS idx_raptor_session ON raptor_nodes(session_id);
     CREATE INDEX IF NOT EXISTS idx_raptor_parent ON raptor_nodes(parent_id);
+
+    -- FTS5 trigram virtual table (Sprint 9+ pg_trgm-equivalent verification).
+    CREATE VIRTUAL TABLE IF NOT EXISTS context_chunks_trgm USING fts5(
+      id UNINDEXED,
+      normalized_text,
+      tokenize='trigram'
+    );
   `);
   const v = db.prepare("SELECT value FROM meta WHERE key='schema_version'").get() as
     | { value: string }
@@ -152,15 +159,80 @@ function initSchema(db: Database.Database): void {
   if (!v) {
     db.prepare("INSERT INTO meta(key, value) VALUES(?, ?)").run("schema_version", String(SCHEMA_VERSION));
   }
+}
 
-  // FTS5 trigram virtual table (Sprint 9+ pg_trgm-equivalent verification).
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS context_chunks_trgm USING fts5(
-      id UNINDEXED,
-      normalized_text,
-      tokenize='trigram'
-    );
-  `);
+/** Read a string-valued meta key (or undefined). Used for cumulative counters. */
+export function getMeta(key: string, stateDir: string = getStateDir()): string | undefined {
+  const db = openStore(stateDir);
+  const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(key) as
+    | { value: string }
+    | undefined;
+  return row?.value;
+}
+
+/**
+ * Cumulative "tokens saved" — the sum of stored checkpoint token estimates across
+ * all compactions in this store (one per repo). Persisted in the SQLite `meta`
+ * table so it survives session restarts and travels with the repo's state dir,
+ * mirroring how `storageDedupRate` is cumulative. Incremented in VectorStore.add()
+ * when a new (non-deduped) checkpoint is persisted.
+ */
+export function getTokensSaved(stateDir: string = getStateDir()): number {
+  const raw = getMeta("tokens_saved", stateDir);
+  const n = raw == null ? 0 : Number(raw);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Add `delta` (>=0) to the cumulative tokens-saved counter. */
+export function addTokensSaved(delta: number, stateDir: string = getStateDir()): void {
+  if (!(delta > 0)) return;
+  const db = openStore(stateDir);
+  db.prepare(
+    `INSERT INTO meta(key, value) VALUES('tokens_saved', ?)
+     ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + ? AS TEXT)`,
+  ).run(String(delta), delta);
+}
+
+/** Cumulative store-wide dedup accounting (Sprint 9+). Persisted in the SQLite
+ *  `meta` table so it survives session restarts and travels with the repo's
+ *  state dir — mirroring `tokens_saved`. Replaces the legacy JSON
+ *  `dedup-stats.json` file (all stats now live in the SQLite store). */
+export interface DedupStats {
+  /** Total add() calls (new checkpoints + deduped collapses). */
+  attempts: number;
+  /** add() calls that collapsed onto an existing checkpoint. */
+  deduped: number;
+}
+
+/** Read a store-wide integer counter from the meta table (0 if absent). */
+export function getMetaNumber(key: string, stateDir: string = getStateDir()): number {
+  const raw = getMeta(key, stateDir);
+  const n = raw == null ? 0 : Number(raw);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** Atomically add `delta` to an integer meta counter. */
+function incMeta(key: string, delta: number, stateDir: string = getStateDir()): void {
+  if (!(delta > 0)) return;
+  const db = openStore(stateDir);
+  db.prepare(
+    `INSERT INTO meta(key, value) VALUES(?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + ? AS TEXT)`,
+  ).run(key, String(delta), delta);
+}
+
+/** Read the cumulative store-wide dedup counters. */
+export function getDedupStats(stateDir: string = getStateDir()): DedupStats {
+  return {
+    attempts: getMetaNumber("dedup_attempts", stateDir),
+    deduped: getMetaNumber("deduped", stateDir),
+  };
+}
+
+/** Increment the store-wide dedup counters for one add() call. */
+export function bumpDedupStats(deduped: boolean, stateDir: string = getStateDir()): void {
+  incMeta("dedup_attempts", 1, stateDir);
+  if (deduped) incMeta("deduped", 1, stateDir);
 }
 
 /** Map a DB row to the public StoredCheckpoint shape. */
@@ -423,6 +495,48 @@ export function storeStats(sessionId: string, stateDir: string = getStateDir()):
   };
 }
 
+/** Repo-wide stats — aggregates every session in this store (one per repo).
+ *  Backed by the SQLite `meta` cumulative counters (`tokens_saved`,
+ *  `dedup_attempts`, `deduped`) plus a SUM over all `context_chunks`. This is the
+ *  cumulative, resumable, cross-device view the dashboard surfaces as "Repo …". */
+export interface RepoStats {
+  /** Total checkpoints across all sessions (excludes SemDeDup-removed rows). */
+  checkpointCount: number;
+  /** Sum of all stored checkpoint token estimates (repo-wide). */
+  totalTokenEstimate: number;
+  /** Total active sessions with at least one checkpoint. */
+  sessionCount: number;
+  /** Cumulative stored-summary tokens saved (Σ stored summaries). */
+  tokensSaved: number;
+  /** Cumulative dedup add() attempts (store-wide). */
+  dedupAttempts: number;
+  /** Cumulative deduped collapses (store-wide). */
+  dedupCollapsed: number;
+  /** Storage dedup rate (deduped / attempts), 0..1. */
+  storageDedupRate: number;
+}
+
+export function repoStats(stateDir: string = getStateDir()): RepoStats {
+  const db = openStore(stateDir);
+  const row = db
+    .prepare(
+      `SELECT COUNT(*) AS c, COALESCE(SUM(token_estimate),0) AS tok,
+              COUNT(DISTINCT session_id) AS sessions
+       FROM context_chunks WHERE dedup_status != 'removed'`,
+    )
+    .get() as { c: number; tok: number; sessions: number };
+  const ds = getDedupStats(stateDir);
+  return {
+    checkpointCount: row.c,
+    totalTokenEstimate: row.tok,
+    sessionCount: row.sessions,
+    tokensSaved: getMetaNumber("tokens_saved", stateDir),
+    dedupAttempts: ds.attempts,
+    dedupCollapsed: ds.deduped,
+    storageDedupRate: ds.attempts === 0 ? 0 : ds.deduped / ds.attempts,
+  };
+}
+
 /** Close and evict a cached connection (test teardown only). */
 export function closeStore(stateDir: string): void {
   const db = cache.get(stateDir);

package/src/store.ts

@@ -168,25 +168,8 @@ export function saveSessionState(sessionId: string, state: SessionState, stateDi
 }
 
 /**
- * Cumulative store-wide dedup accounting. Lives outside the per-session
- * SessionState (which resets on every session instance) so the dedup rate
- * stays stable across session restarts. Persisted as plain JSON in the
- * state dir.
+ * Cumulative store-wide dedup accounting now lives in the SQLite `meta` table
+ * (see store/sqlite.ts: getDedupStats / bumpDedupStats). All store stats are
+ * SQLite-backed so they survive session restarts and travel with the repo's
+ * state dir. The legacy JSON `dedup-stats.json` path was removed.
  */
-export interface DedupStats {
-  /** Total add() calls (new checkpoints + deduped collapses). */
-  attempts: number;
-  /** add() calls that collapsed onto an existing checkpoint. */
-  deduped: number;
-}
-
-const DEDUP_STATS_FILE = "dedup-stats.json";
-
-export function loadDedupStats(stateDir: string = getStateDir()): DedupStats {
-  const file = join(stateDir, DEDUP_STATS_FILE);
-  return readGzJson<DedupStats>(file, { attempts: 0, deduped: 0 });
-}
-
-export function saveDedupStats(stats: DedupStats, stateDir: string = getStateDir()): void {
-  writeGzJson(join(stateDir, DEDUP_STATS_FILE), stats);
-}

package/src/vectorStore.test.ts

@@ -250,6 +250,51 @@ test("stats reports counts, last checkpoint, and dedup rate", () => {
   assert.ok(Math.abs(st2.dedupHitRate - 0.5) < 1e-9);
 });
 
+test("tokensSaved accumulates on new checkpoints; deduped add bumps collapsed not saved", () => {
+  const s = store();
+  // Two genuinely new checkpoints (stored-sum definition of tokensSaved).
+  s.add({ sessionId: "sess_saved", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, timestamp: 1 });
+  s.add({ sessionId: "sess_saved", summary: "beta", regionText: "region beta text", tokenEstimate: 700, timestamp: 2 });
+  const st = s.stats("sess_saved");
+  assert.equal(st.tokensSaved, 1200, "per-session tokensSaved = Σ stored summary tokens");
+  assert.equal(st.dedupCollapsed, 0);
+  assert.equal(st.dedupAttempts, 2);
+
+  // A third add that dedups onto an existing region (same summaryHash path):
+  // collapses onto an existing checkpoint, so it must NOT grow tokensSaved, but
+  // must bump dedupCollapsed + dedupAttempts.
+  const deduped = s.add({ sessionId: "sess_saved", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, timestamp: 3 });
+  assert.ok(deduped.deduped, "identical region should dedup");
+  const st3 = s.stats("sess_saved");
+  assert.equal(st3.tokensSaved, 1200, "deduped add does not add to tokensSaved (stored-sum)");
+  assert.equal(st3.dedupCollapsed, 1, "deduped collapse counted separately");
+  assert.equal(st3.dedupAttempts, 3);
+});
+
+test("repoStats aggregates every session in the SQLite store", () => {
+  const dir = join(baseTmp, `repo-${counter++}`);
+  const a = new VectorStore({ dedupSim: 0.9, stateDir: dir });
+  const b = new VectorStore({ dedupSim: 0.9, stateDir: dir }); // same disk store, diff instance
+  a.add({ sessionId: "sess_a", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, timestamp: 1 });
+  b.add({ sessionId: "sess_b", summary: "beta", regionText: "region beta text", tokenEstimate: 700, timestamp: 2 });
+
+  const repo = a.repoStats();
+  assert.equal(repo.checkpointCount, 2, "checkpoints across both sessions");
+  assert.equal(repo.sessionCount, 2, "two distinct sessions");
+  assert.equal(repo.totalTokenEstimate, 1200);
+  assert.equal(repo.tokensSaved, 1200, "repo-wide cumulative stored-summary tokens");
+  assert.equal(repo.dedupCollapsed, 0);
+
+  // A deduped add into sess_a collapses onto its existing checkpoint: repo
+  // tokensSaved stays put, dedupCollapsed climbs.
+  const deduped = a.add({ sessionId: "sess_a", summary: "alpha", regionText: "region alpha text", tokenEstimate: 500, timestamp: 3 });
+  assert.ok(deduped.deduped);
+  const repo2 = a.repoStats();
+  assert.equal(repo2.tokensSaved, 1200, "deduped collapse does not change repo tokensSaved");
+  assert.equal(repo2.dedupCollapsed, 1);
+  assert.equal(repo2.checkpointCount, 2, "still two stored checkpoints");
+});
+
 test("computeRegionHash normalizes whitespace before hashing", () => {
   const h1 = computeRegionHash("foo  bar");
   const h2 = computeRegionHash("foo bar");

package/src/vectorStore.ts

@@ -14,7 +14,7 @@ import { cosineSimilarity, defaultEmbedder } from "./embedder.js";
 import { loadDedupConfig, type DedupConfigShape, type DedupTier } from "./config/dedup.js";
 import { logDecision } from "./monitoring.js";
 import type { StoredCheckpoint, SessionState } from "./store.js";
-import { getStateDir, normalizeSessionId, compressSmart, loadDedupStats, saveDedupStats } from "./store.js";
+import { getStateDir, normalizeSessionId, compressSmart } from "./store.js";
 import { computeContentDigest } from "./dedup/digest.js";
 import { minhashSignature, SIGNATURE_VERSION, NUM_HASHES } from "./dedup/l1-minhash.js";
 import { lshBands } from "./dedup/l1-lsh.js";
@@ -32,6 +32,10 @@ import {
   insertLshBuckets,
   lshCandidateChunks,
   setDedupStatus,
+  addTokensSaved,
+  getDedupStats,
+  bumpDedupStats,
+  repoStats as repoStatsFromStore,
 } from "./store/sqlite.js";
 import { migrateJsonToSqlite } from "./store/migrate.js";
 
@@ -137,9 +141,6 @@ export class VectorStore {
     const regionHash = computeRegionHash(input.regionText);
     const all = listCheckpoints(sessionId, this.stateDir);
     const cfg = this.cfg;
-    // Cumulative store-wide dedup accounting (survives session resets).
-    const ds = loadDedupStats(this.stateDir);
-    ds.attempts++;
     // Tracks whether a tier matched while in MARK_ONLY (record-but-don't-collapse),
     // and which tier.
     let markOnly: DedupTier | null = null;
@@ -165,8 +166,7 @@ export class VectorStore {
         } else {
           contentMatch.timestamp = input.timestamp;
           upsertCheckpoint(contentMatch, this.stateDir);
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
           const r = { checkpoint: contentMatch, deduped: true, reason: "contentHash" };
           this.record("L0", "deduped", "contentHash", Date.now() - t0);
           return r;
@@ -181,8 +181,7 @@ export class VectorStore {
         if (cfg.MARK_ONLY_L0) {
           markOnly = "L0"; // fall through
         } else {
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
           const r = { checkpoint: regionMatch, deduped: true, reason: "regionHash" };
           this.record("L0", "deduped", "regionHash", Date.now() - t0);
           return r;
@@ -203,8 +202,7 @@ export class VectorStore {
         } else {
           summaryMatch.timestamp = input.timestamp;
           upsertCheckpoint(summaryMatch, this.stateDir);
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
           const r = { checkpoint: summaryMatch, deduped: true, reason: "summaryHash" };
           this.record("L0", "deduped", "summaryHash", Date.now() - t0);
           return r;
@@ -221,8 +219,7 @@ export class VectorStore {
       if (l1 && !cfg.MARK_ONLY_L1) {
         l1.timestamp = input.timestamp;
         upsertCheckpoint(l1, this.stateDir);
-        ds.deduped++;
-        saveDedupStats(ds, this.stateDir);
+        bumpDedupStats(true, this.stateDir);
         const r = { checkpoint: l1, deduped: true, reason: "l1MinHash" };
         this.record("L1", "deduped", "l1MinHash", Date.now() - t0);
         return r;
@@ -257,8 +254,7 @@ export class VectorStore {
           // Near-identical — update timestamp on existing checkpoint
           nearest.checkpoint.timestamp = input.timestamp;
           upsertCheckpoint(nearest.checkpoint, this.stateDir);
-          ds.deduped++;
-          saveDedupStats(ds, this.stateDir);
+          bumpDedupStats(true, this.stateDir);
           const r = { checkpoint: nearest.checkpoint, deduped: true, reason: "contentSimilarity" };
           this.record("L2", "deduped", "contentSimilarity", Date.now() - t0);
           return r;
@@ -291,6 +287,9 @@ export class VectorStore {
     // Persistence is SQLite (store/sqlite.ts). upsertCheckpoint keeps the
     // idempotent-by-id semantics the old JSON append implied.
     upsertCheckpoint(checkpoint, this.stateDir);
+    // Cumulative "tokens saved" counter (per-repo SQLite meta). Bumped for every
+    // new checkpoint persisted, so it survives sessions and travels with the repo.
+    addTokensSaved(input.tokenEstimate ?? 0, this.stateDir);
     // L1: persist this checkpoint's MinHash signature + LSH buckets so future
     // near-duplicate inserts can find it. Deterministic given the seed.
     const sig = minhashSignature(input.regionText);
@@ -320,7 +319,8 @@ export class VectorStore {
     } else {
       this.record("L0", "new", undefined, Date.now() - t0);
     }
-    saveDedupStats(ds, this.stateDir);
+    // Cumulative store-wide dedup accounting (attempt, not collapsed).
+    bumpDedupStats(false, this.stateDir);
     return { checkpoint, deduped: false };
   }
 
@@ -517,6 +517,7 @@ export class VectorStore {
     injectedCount: number;
     dedupHitRate: number; // injected / checkpoints, 0..1
     storageDedupRate: number; // deduped adds / total adds, 0..1 (cumulative)
+    tokensSaved: number; // cumulative stored checkpoint tokens (per-repo SQLite)
     dedupAttempts: number; // cumulative add() calls (store-wide)
     dedupCollapsed: number; // cumulative deduped collapses (store-wide)
   } {
@@ -528,17 +529,31 @@ export class VectorStore {
     );
     const last = ordered[ordered.length - 1];
     const injected = state.injectedCheckpointIds.length;
-    const ds = loadDedupStats(this.stateDir);
+    const ds = getDedupStats(this.stateDir);
+    // Per-session "tokens saved" = this session's Σ stored summary token
+    // estimates (stored-sum definition). Equal to totalTokenEstimate by
+    // construction; repo-wide cumulative saved lives in repoStats().
+    const sessionTok = cps.reduce((s, c) => s + (c.tokenEstimate ?? 0), 0);
     return {
       checkpointCount: cps.length,
-      totalTokenEstimate: cps.reduce((s, c) => s + (c.tokenEstimate ?? 0), 0),
+      totalTokenEstimate: sessionTok,
       lastCheckpointId: last?.checkpointId,
       lastSummary: last?.summary,
       injectedCount: injected,
       dedupHitRate: cps.length === 0 ? 0 : injected / cps.length,
       storageDedupRate: ds.attempts === 0 ? 0 : ds.deduped / ds.attempts,
+      tokensSaved: sessionTok,
       dedupAttempts: ds.attempts,
       dedupCollapsed: ds.deduped,
     };
   }
+
+  /**
+   * Repo-wide stats — aggregates every session in this store (one per repo).
+   * Cumulative, resumable, cross-device. Surfaces the dashboard's "Repo …"
+   * figures; distinct from {@link stats} (per-session).
+   */
+  repoStats(): ReturnType<typeof repoStatsFromStore> {
+    return repoStatsFromStore(this.stateDir);
+  }
 }