@inetafrica/open-claudia 2.6.58 → 2.7.0

package/core/recall/discoverer.js

@@ -17,6 +17,7 @@
 
 const graph = require("./graph");
 const metrics = require("./metrics");
+const tuning = require("./tuning");
 const { spawnSubagent } = require("../subagent");
 const warmWalker = require("./warm-walker");
 const toolsLib = require("../tools");
@@ -33,16 +34,17 @@ try { transcriptIndex = require("../transcript-index"); } catch (e) { /* old nod
 const WALKER_MODEL = process.env.RECALL_DISCOVERER_MODEL || "haiku";
 const WALKER_TIMEOUT_MS = Number(process.env.RECALL_DISCOVERER_TIMEOUT_MS || 25000);
 const WALKER_ENABLED = String(process.env.RECALL_DISCOVERER_WALKER || "on").toLowerCase() !== "off";
-// Cap on pack/entity candidates handed to the walker. Uncapped, a wordy turn
-// seeds 15-40 nodes × 600-char excerpts — the walker then reads a 10-25KB
-// prompt, which measured as THE dominant recall latency (p50 ~13.5s even with
-// the warm process). Capped, the prompt stays small; priority order below keeps
-// the strongest evidence.
-const MAX_WALKER_CANDIDATES = Number(process.env.RECALL_WALKER_MAX_CANDIDATES || 14);
+// Sizing/tier knobs (walker candidate cap, episode limit, seeds-tier width,
+// cascade on/off) live in recall/tuning.js — dream-adjustable within hard
+// bounds, env pins still win. The walker candidate cap exists because uncapped,
+// a wordy turn seeds 15-40 nodes × 600-char excerpts and the walker prompt
+// measured as THE dominant recall latency (p50 ~13.5s even warm).
 const EPISODES_ENABLED = String(process.env.RECALL_EPISODES || "on").toLowerCase() !== "off";
-const EPISODE_LIMIT = Number(process.env.RECALL_EPISODE_LIMIT || 3);
 const EXCERPT_CHARS = 600;
 const CONTEXT_CLIP = 3000;
+// Fraction of cascade auto-verdicts also sent to the judge as an accuracy
+// audit — divergence is logged and the dream disables the cascade if it drifts.
+const SHADOW_RATE = Number(process.env.RECALL_CASCADE_SHADOW_RATE || 0.1);
 
 let _lastSync = 0;
 const SYNC_INTERVAL_MS = 60000;
@@ -73,10 +75,22 @@ function recallTier(userText, seedCount) {
   if (!/[a-z0-9]/.test(t)) return "skip"; // emoji/punctuation only
   if (words.length <= 4 && PLEASANTRY_RE.test(t)) return "skip";
   if (words.length <= 2 && seedCount === 0) return "skip";
-  if (words.length <= 4) return "seeds";
+  if (words.length <= tuning.get("seedsTierMaxWords")) return "seeds";
   return "full";
 }
 
+// Evidence-backed pre-verdict for one candidate, from its rolling usage stats.
+// Conservative by design: auto-drop needs a long never-kept/never-used streak;
+// auto-keep needs a high keep-rate AND at least one real use (open/reviewer).
+// Anything without strong history returns null and goes to the judge.
+function cascadeVerdict(st) {
+  if (!st) return null;
+  const seen = st.seen || 0, kept = st.kept || 0, used = (st.open || 0) + (st.rev || 0);
+  if (seen >= 6 && kept === 0 && used === 0) return "drop";
+  if (seen >= 5 && kept / seen >= 0.8 && used >= 1) return "keep";
+  return null;
+}
+
 // Back-compat boolean view of the tier (exported/tested API).
 function needsRecall(userText, seedCount) {
   return recallTier(userText, seedCount) !== "skip";
@@ -221,8 +235,8 @@ async function run(ctx) {
   // 1: tiered pre-gate.
   const tier = recallTier(userText, seedCount);
   if (tier === "skip") {
-    metrics.logTurn({ engine: "discoverer", query: userText, gated: true, tier, latencyMs: Date.now() - started });
-    return { packBlock: "", entityBlock: "", toolBlock: "", episodeBlock: "", packMatches: [], entityMatches: [], toolMatches: [], episodeMatches: [], why: {}, gated: true };
+    metrics.logTurn({ engine: "discoverer", model: WALKER_MODEL, query: userText, gated: true, tier, latencyMs: Date.now() - started });
+    return { packBlock: "", entityBlock: "", toolBlock: "", episodeBlock: "", packMatches: [], entityMatches: [], toolMatches: [], episodeMatches: [], why: {}, gated: true, tier };
   }
 
   // 3: spreading activation from seeds across the graph (full tier only — the
@@ -257,7 +271,7 @@ async function run(ctx) {
   }
   const candidates = [];
   if (tier === "full") {
-    for (const id of orderedIds.slice(0, MAX_WALKER_CANDIDATES)) {
+    for (const id of orderedIds.slice(0, tuning.get("walkerMaxCandidates"))) {
       const base = excerptFor(id, packsLib, entitiesLib);
       if (!base) continue;
       const act = activated.get(id);
@@ -316,7 +330,7 @@ async function run(ctx) {
   let episodeCands = [];
   if (tier === "full" && EPISODES_ENABLED && transcriptIndex && transcriptIndex.available()) {
     try {
-      const { hits } = transcriptIndex.search(userText, { limit: EPISODE_LIMIT });
+      const { hits } = transcriptIndex.search(userText, { limit: tuning.get("episodeLimit") });
       episodeCands = (hits || []).map((h) => {
         const terms = [...String(h.snip || "").matchAll(/>>(.+?)<</g)].map((m) => m[1]).slice(0, 4);
         return {
@@ -333,14 +347,63 @@ async function run(ctx) {
     } catch (e) { /* episodic recall is best-effort */ }
   }
 
-  const walkRes = await walk(userText, contextText || fullContext, candidates);
+  // Walker cascade: candidates with strong usage history get an evidence-backed
+  // auto-verdict and skip the judge — the model reads only the ambiguous middle
+  // (fewer tokens, less noise in the prompt). A random SHADOW_RATE slice of
+  // auto-decided candidates is judged anyway and compared, so the shortcut is
+  // continuously audited against the model it replaces; on shadowed candidates
+  // the judge's verdict wins. Top-3 ranked candidates and episodes (no stable
+  // history) always go to the judge.
+  const cascadeOn = tier === "full" && tuning.get("cascade") !== "off";
+  const autoKept = new Map(); // id -> canned why (honest provenance)
+  const autoDropped = [];
+  const shadowVerdicts = new Map(); // id -> auto verdict, also sent to judge
+  let judgeCands = candidates;
+  if (cascadeOn && candidates.length) {
+    let nodeHist = {};
+    try { nodeHist = metrics.nodeStats().nodes || {}; } catch (e) {}
+    const protectedIds = new Set(orderedIds.slice(0, 3));
+    judgeCands = [];
+    for (const c of candidates) {
+      const st = c.id.startsWith("episode:") || protectedIds.has(c.id) ? null : nodeHist[c.id];
+      const v = cascadeVerdict(st);
+      if (!v) { judgeCands.push(c); continue; }
+      if (Math.random() < SHADOW_RATE) { shadowVerdicts.set(c.id, v); judgeCands.push(c); continue; }
+      if (v === "keep") autoKept.set(c.id, `kept ${st.kept}/${st.seen} recent similar turns`);
+      else autoDropped.push(c.id);
+    }
+  }
+
+  const walkRes = await walk(userText, contextText || fullContext, judgeCands);
   const whyById = walkRes.kept;
 
-  // Decide the kept set. Walker result wins; on fail-open keep the user-origin
-  // seeds only (classic baseline) and drop graph-expanded/context guesses.
+  let shadowChecks = 0, shadowAgree = 0;
+  if (whyById && shadowVerdicts.size) {
+    for (const [id, v] of shadowVerdicts) {
+      const agree = (v === "keep") === whyById.has(id);
+      shadowChecks++;
+      if (agree) shadowAgree++;
+      metrics.logShadow(agree);
+    }
+  }
+
+  // Decide the kept set. Walker result + evidence auto-keeps win; on walker
+  // fail-open (full tier) keep the strongest 3 user-origin seeds only — an
+  // unjudged tool or episode is a guess, not a memory (measured: a failed walk
+  // once kept 15 unjudged seeds including WiFi tools for a dream question). The
+  // seeds tier keeps its classic contract: all user-origin keyword seeds.
+  let whyMap = whyById ? new Map(whyById) : null;
+  if (whyMap) for (const [id, why] of autoKept) whyMap.set(id, why);
   let keptIds;
-  if (whyById) {
-    keptIds = new Set(whyById.keys());
+  if (whyMap) {
+    keptIds = new Set(whyMap.keys());
+  } else if (tier === "full") {
+    const rankedUserSeeds = [
+      ...packSeeds.filter((m) => m.origin === "user").map((m) => ({ id: `pack:${m.dir}`, score: m.score || 2 })),
+      ...entSeeds.filter((m) => m.origin === "user").map((m) => ({ id: `entity:${m.slug}`, score: m.score || 2 })),
+    ].sort((a, b) => b.score - a.score).slice(0, 3).map((s) => s.id);
+    keptIds = new Set([...autoKept.keys(), ...rankedUserSeeds]);
+    if (autoKept.size) whyMap = new Map(autoKept);
   } else {
     keptIds = new Set(
       [...packSeeds.filter((m) => m.origin === "user").map((m) => `pack:${m.dir}`),
@@ -374,9 +437,9 @@ async function run(ctx) {
   // 5: render via shared builders, then weave in the why-bullets.
   let packBlock = buildPackBlock(finalPacks, budget);
   const entityBlock = buildEntityBlock(finalEnts, budget);
-  if (packBlock && whyById) {
+  if (packBlock && whyMap) {
     const bullets = finalPacks
-      .map((m) => ({ m, why: whyById.get(`pack:${m.dir}`) }))
+      .map((m) => ({ m, why: whyMap.get(`pack:${m.dir}`) }))
       .filter((x) => x.why)
       .map((x) => `- ${x.m.name || x.m.dir}: ${x.why}`);
     if (bullets.length) packBlock = `\n\n### Why these surfaced (discoverer)\n${bullets.join("\n")}${packBlock}`;
@@ -388,7 +451,7 @@ async function run(ctx) {
   const toolMatches = [];
   for (const c of toolCand.values()) {
     if (keptIds.has(`tool:${c.name}`)) {
-      toolMatches.push({ name: c.name, description: c.description, why: whyById ? whyById.get(`tool:${c.name}`) || "" : "" });
+      toolMatches.push({ name: c.name, description: c.description, why: whyMap ? whyMap.get(`tool:${c.name}`) || "" : "" });
     }
   }
   let toolBlock = "";
@@ -405,7 +468,7 @@ async function run(ctx) {
   // unjudged transcript snippet is a guess, not a memory).
   const episodeMatches = episodeCands
     .filter((c) => keptIds.has(c.id))
-    .map((c) => ({ id: c.id, name: c.name, excerpt: c.excerpt, terms: c._terms, why: whyById ? whyById.get(c.id) || "" : "" }));
+    .map((c) => ({ id: c.id, name: c.name, excerpt: c.excerpt, terms: c._terms, why: whyMap ? whyMap.get(c.id) || "" : "" }));
   let episodeBlock = "";
   if (episodeMatches.length) {
     const lines = episodeMatches.map((m) => {
@@ -417,11 +480,16 @@ async function run(ctx) {
 
   metrics.logTurn({
     engine: "discoverer",
+    model: WALKER_MODEL,
     query: userText,
     tier,
     seeds: seedNodes,
     activated: [...activated.entries()].map(([id, a]) => ({ id, activation: a.activation, hop: a.hop })),
-    kept: [...keptIds].map((id) => ({ id, why: whyById ? whyById.get(id) : "" })),
+    cand: candidates.map((c) => ({ id: c.id, act: !!c.activated })),
+    kept: [...keptIds].map((id) => ({ id, why: whyMap ? whyMap.get(id) : "" })),
+    auto: (autoKept.size || autoDropped.length || shadowChecks)
+      ? { kept: [...autoKept.keys()], dropped: autoDropped, shadow: { checks: shadowChecks, agree: shadowAgree } }
+      : null,
     gated: false,
     latencyMs: Date.now() - started,
     seedMs,
@@ -433,8 +501,8 @@ async function run(ctx) {
 
   return {
     packBlock, entityBlock, toolBlock, episodeBlock, packMatches: finalPacks, entityMatches: finalEnts,
-    toolMatches, episodeMatches, why: whyById ? Object.fromEntries(whyById) : {}, gated: false,
+    toolMatches, episodeMatches, why: whyMap ? Object.fromEntries(whyMap) : {}, gated: false, tier,
   };
 }
 
-module.exports = { name: "discoverer", run, needsRecall, recallTier, walk };
+module.exports = { name: "discoverer", run, needsRecall, recallTier, walk, cascadeVerdict };

package/core/recall/graph.js

@@ -156,6 +156,33 @@ function reinforceSet(nodeIds, amount = 1) {
   }
 }
 
+// Negative Hebbian: weaken every edge touching a node that keeps surfacing
+// via the graph but never gets kept or used — firing wrongly, so unwire.
+// Same floor contract as decay(); additionally, `related` edges that fall to
+// their structural base are deleted outright: a link-derived edge re-derives
+// at base weight on the next sync (harmless), while a co-use edge that earned
+// its weight from wrong firings is gone for good.
+function weakenNode(nodeId, { factor = 0.6, prune = true } = {}) {
+  const db = openDb();
+  if (!db || !nodeId) return { weakened: 0, pruned: 0 };
+  let weakened = 0, pruned = 0;
+  try {
+    const rows = db.prepare("SELECT src, dst, type, weight FROM edges WHERE src=? OR dst=?").all(nodeId, nodeId);
+    for (const e of rows) {
+      const floor = BASE_WEIGHT[e.type] || 0;
+      const next = Math.max(floor, e.weight * factor);
+      if (prune && e.type === "related" && next <= floor + 0.05) {
+        db.prepare("DELETE FROM edges WHERE src=? AND dst=? AND type=?").run(e.src, e.dst, e.type);
+        pruned++;
+      } else if (Math.abs(next - e.weight) > 1e-6) {
+        db.prepare("UPDATE edges SET weight=? WHERE src=? AND dst=? AND type=?").run(next, e.src, e.dst, e.type);
+        weakened++;
+      }
+    }
+  } catch (e) {}
+  return { weakened, pruned };
+}
+
 // Exponential time decay on reinforced weight. Structural floor is preserved:
 // an edge never decays below its type's base weight.
 function decay({ halfLifeDays = DEFAULTS.halfLifeDays } = {}) {
@@ -377,7 +404,7 @@ module.exports = {
   EDGE_TYPES, DEFAULTS, GRAPH_DB,
   available, openDb,
   addEdge, removeEdge, allEdges, neighbors,
-  reinforce, reinforceSet, decay, expand,
-  syncFromCorpus, parseLinks, pruneOrphans, tend, stats,
+  reinforce, reinforceSet, decay, weakenNode, expand,
+  syncFromCorpus, parseLinks, pruneOrphans, tend, stats, isSharedConcern,
   _resetForTest,
 };

package/core/recall/kpi.js

@@ -0,0 +1,227 @@
+// Per-version KPI aggregation over recall telemetry. Ground truth is the
+// per-turn JSONL (every record version+model stamped); the nightly dream
+// snapshots in recall-kpi.jsonl are the time series. Deterministic and
+// read-only — powers `open-claudia kpi` (text table, JSON, and a
+// self-contained HTML report with inline SVG charts, no CDN).
+
+const fs = require("fs");
+const metrics = require("./metrics");
+
+const LEGACY_VERSION = "pre-2.6.59"; // records logged before version stamping shipped
+
+function emptyBucket(v) {
+  return {
+    v, models: new Set(), firstTs: "", lastTs: "",
+    turns: 0, gated: 0, seedsTier: 0, keptTotal: 0,
+    rescueTurns: 0, rescues: 0, walkerFailed: 0,
+    latencyMsTotal: 0, costUsd: 0, autoKept: 0, autoDropped: 0,
+    opens: 0, reviewerUses: 0, byTier: {},
+  };
+}
+
+// Stream the per-turn log into per-version buckets. Use-records (📖 opens /
+// reviewer adjudications) are attributed to the version that observed the use.
+function scanLog() {
+  let lines = [];
+  try { lines = fs.readFileSync(metrics.LOG_FILE, "utf8").split("\n").filter(Boolean); }
+  catch (e) { return new Map(); }
+  const byV = new Map();
+  const bucket = (v) => { if (!byV.has(v)) byV.set(v, emptyBucket(v)); return byV.get(v); };
+  for (const line of lines) {
+    let rec; try { rec = JSON.parse(line); } catch (e) { continue; }
+    const b = bucket(rec.v || LEGACY_VERSION);
+    if (!b.firstTs) b.firstTs = rec.ts || "";
+    if (rec.ts) b.lastTs = rec.ts;
+    if (Array.isArray(rec.use)) {
+      if (rec.source === "reviewer") b.reviewerUses += rec.use.length;
+      else b.opens += rec.use.length;
+      continue;
+    }
+    b.turns++;
+    if (rec.model) b.models.add(rec.model);
+    b.latencyMsTotal += rec.latencyMs || 0;
+    b.costUsd += rec.costUsd || 0;
+    if (rec.tier) {
+      const t = b.byTier[rec.tier] || { n: 0, ms: 0 };
+      t.n++; t.ms += rec.latencyMs || 0;
+      b.byTier[rec.tier] = t;
+    }
+    if (rec.gated) { b.gated++; continue; }
+    if (rec.tier === "seeds") b.seedsTier++;
+    if (rec.walker === "failed") b.walkerFailed++;
+    const kept = rec.kept || [];
+    b.keptTotal += kept.length;
+    const seedIds = new Set((rec.seeds || []).map((s) => s.id));
+    const rescues = kept.filter((k) => !seedIds.has(k.id)).length;
+    if (rescues > 0) { b.rescueTurns++; b.rescues += rescues; }
+    if (rec.auto) {
+      b.autoKept += (rec.auto.kept || []).length;
+      b.autoDropped += (rec.auto.dropped || []).length;
+    }
+  }
+  return byV;
+}
+
+const r1 = (n) => Math.round(n * 10) / 10;
+const pct = (n, d) => (d ? Math.round((n / d) * 100) : null);
+
+// One comparable row per version, ordered oldest→newest by first sighting.
+function aggregate() {
+  const rows = [];
+  for (const b of scanLog().values()) {
+    const used = b.opens + b.reviewerUses;
+    rows.push({
+      v: b.v,
+      models: [...b.models].sort(),
+      from: (b.firstTs || "").slice(0, 10),
+      to: (b.lastTs || "").slice(0, 10),
+      turns: b.turns,
+      gatedPct: pct(b.gated, b.turns),
+      seedsTierPct: pct(b.seedsTier, b.turns),
+      keptTotal: b.keptTotal,
+      avgKept: b.turns - b.gated ? r1(b.keptTotal / (b.turns - b.gated)) : 0,
+      rescuePct: pct(b.rescueTurns, b.turns - b.gated),
+      noisePct: b.keptTotal ? Math.max(0, 100 - Math.round((used / b.keptTotal) * 100)) : null,
+      opens: b.opens,
+      reviewerUses: b.reviewerUses,
+      avgLatencyMs: b.turns ? Math.round(b.latencyMsTotal / b.turns) : 0,
+      byTier: Object.fromEntries(Object.entries(b.byTier).map(([t, x]) => [t, { turns: x.n, avgMs: x.n ? Math.round(x.ms / x.n) : 0 }])),
+      costUsd: r1(b.costUsd * 10) / 10,
+      costPerTurnUsd: b.turns ? Math.round((b.costUsd / b.turns) * 10000) / 10000 : 0,
+      walkerFailPct: pct(b.walkerFailed, b.turns - b.gated),
+      autoKept: b.autoKept,
+      autoDropped: b.autoDropped,
+    });
+  }
+  rows.sort((a, b) => (a.from || "").localeCompare(b.from || ""));
+  return rows;
+}
+
+function trend() { return metrics.readKpi(); }
+
+// ── text table (CLI) ──────────────────────────────────────────────────
+function renderTable(rows) {
+  if (!rows.length) return "No recall telemetry yet.";
+  const cols = [
+    ["version", (r) => r.v],
+    ["turns", (r) => String(r.turns)],
+    ["rescue", (r) => (r.rescuePct == null ? "—" : r.rescuePct + "%")],
+    ["noise", (r) => (r.noisePct == null ? "—" : r.noisePct + "%")],
+    ["avg", (r) => (r.avgLatencyMs / 1000).toFixed(1) + "s"],
+    ["gated", (r) => (r.gatedPct == null ? "—" : r.gatedPct + "%")],
+    ["$ / turn", (r) => "$" + r.costPerTurnUsd.toFixed(3)],
+    ["cascade", (r) => (r.autoKept || r.autoDropped ? `${r.autoKept}/${r.autoDropped}` : "—")],
+    ["walker-fail", (r) => (r.walkerFailPct == null ? "—" : r.walkerFailPct + "%")],
+    ["window", (r) => `${r.from}→${r.to}`],
+    ["models", (r) => r.models.join(",") || "—"],
+  ];
+  const widths = cols.map(([h, f]) => Math.max(h.length, ...rows.map((r) => f(r).length)));
+  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ");
+  const out = [line(cols.map(([h]) => h)), line(widths.map((w) => "-".repeat(w)))];
+  for (const r of rows) out.push(line(cols.map(([, f]) => f(r))));
+  return out.join("\n");
+}
+
+// ── HTML report (inline SVG, no dependencies) ─────────────────────────
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+const PALETTE = ["#4f8ef7", "#f7734f", "#3dbf7a", "#b06ef7", "#f0b429", "#e8618c", "#38bdc8"];
+
+function barChart(title, items, { fmt = (v) => String(v), max = null } = {}) {
+  const data = items.filter((i) => i.value != null && Number.isFinite(i.value));
+  if (!data.length) return "";
+  const W = 560, ROW = 30, LABEL = 150, PAD = 8;
+  const H = data.length * ROW + 34;
+  const top = max != null ? max : Math.max(...data.map((d) => d.value), 1e-9);
+  const bars = data.map((d, i) => {
+    const w = Math.max(2, Math.round((d.value / top) * (W - LABEL - 90)));
+    const y = 30 + i * ROW;
+    return `<text x="${LABEL - PAD}" y="${y + 15}" text-anchor="end" class="lb">${esc(d.label)}</text>` +
+      `<rect x="${LABEL}" y="${y + 3}" width="${w}" height="${ROW - 10}" rx="4" fill="${PALETTE[i % PALETTE.length]}"/>` +
+      `<text x="${LABEL + w + 6}" y="${y + 15}" class="vl">${esc(fmt(d.value))}</text>`;
+  }).join("");
+  return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg">` +
+    `<text x="0" y="16" class="tt">${esc(title)}</text>${bars}</svg>`;
+}
+
+function lineChart(title, series, { fmt = (v) => String(v) } = {}) {
+  const all = series.flatMap((s) => s.points.map((p) => p.y)).filter((y) => Number.isFinite(y));
+  const n = Math.max(...series.map((s) => s.points.length), 0);
+  if (!all.length || n < 2) return "";
+  const W = 560, H = 190, L = 46, B = 24, T = 26;
+  const top = Math.max(...all, 1e-9);
+  const x = (i) => L + (i / (n - 1)) * (W - L - 12);
+  const y = (v) => T + (1 - v / top) * (H - T - B);
+  const paths = series.map((s, si) => {
+    const pts = s.points.map((p, i) => `${x(i).toFixed(1)},${y(p.y).toFixed(1)}`).join(" ");
+    return `<polyline points="${pts}" fill="none" stroke="${PALETTE[si % PALETTE.length]}" stroke-width="2"/>`;
+  }).join("");
+  const legend = series.map((s, si) =>
+    `<circle cx="${L + si * 130}" cy="${H - 8}" r="4" fill="${PALETTE[si % PALETTE.length]}"/>` +
+    `<text x="${L + si * 130 + 9}" y="${H - 4}" class="lb">${esc(s.label)}</text>`).join("");
+  const grid = [0, 0.5, 1].map((f) =>
+    `<line x1="${L}" y1="${y(top * f)}" x2="${W - 12}" y2="${y(top * f)}" class="gr"/>` +
+    `<text x="${L - 5}" y="${y(top * f) + 4}" text-anchor="end" class="vl">${esc(fmt(top * f))}</text>`).join("");
+  return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg">` +
+    `<text x="0" y="16" class="tt">${esc(title)}</text>${grid}${paths}${legend}</svg>`;
+}
+
+function htmlReport() {
+  const rows = aggregate();
+  const snaps = trend().filter((s) => s.health && s.window && s.window.turns > 0);
+  const label = (r) => `${r.v} (${r.turns}t)`;
+  const charts = [
+    barChart("Graph rescue rate — % of judged turns where memory was saved by the graph, not keywords (higher = better transfer)",
+      rows.map((r) => ({ label: label(r), value: r.rescuePct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+    barChart("Noise — % of injected memories never opened or credited by the reviewer (lower is better)",
+      rows.map((r) => ({ label: label(r), value: r.noisePct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+    barChart("Average recall latency", rows.map((r) => ({ label: label(r), value: r.avgLatencyMs / 1000 })), { fmt: (v) => v.toFixed(1) + "s" }),
+    barChart("Recall cost per turn", rows.map((r) => ({ label: label(r), value: r.costPerTurnUsd })), { fmt: (v) => "$" + v.toFixed(3) }),
+    barChart("Gated turns — pleasantries skipped for free", rows.map((r) => ({ label: label(r), value: r.gatedPct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+    barChart("Walker failure rate", rows.map((r) => ({ label: label(r), value: r.walkerFailPct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+  ].filter(Boolean).map((s) => `<div class="card">${s}</div>`).join("\n");
+
+  const trendChart = snaps.length >= 2 ? lineChart(
+    "Nightly trend (per dream window)",
+    [
+      { label: "rescue %", points: snaps.map((s) => ({ y: (s.health.rescueRate || 0) * 100 })) },
+      { label: "noise %", points: snaps.map((s) => ({ y: (s.health.noiseRate || 0) * 100 })) },
+      { label: "latency s", points: snaps.map((s) => ({ y: (s.health.avgLatencyMs || 0) / 1000 })) },
+    ],
+    { fmt: (v) => Math.round(v) }) : "";
+
+  const tierRows = rows.map((r) => {
+    const t = Object.entries(r.byTier).map(([k, v]) => `${k}: ${v.turns}× @ ${(v.avgMs / 1000).toFixed(1)}s`).join(" · ") || "—";
+    return `<tr><td>${esc(r.v)}</td><td>${esc(r.from)}→${esc(r.to)}</td><td>${r.turns}</td><td>${t}</td>` +
+      `<td>${r.opens} / ${r.reviewerUses}</td><td>${r.autoKept} / ${r.autoDropped}</td><td>${esc(r.models.join(", ") || "—")}</td></tr>`;
+  }).join("\n");
+
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Open Claudia — recall KPIs</title>
+<style>
+body{font-family:-apple-system,Segoe UI,Roboto,sans-serif;background:#101418;color:#e6edf3;margin:0;padding:24px;max-width:660px;margin:auto}
+h1{font-size:20px;margin:0 0 4px} .sub{color:#8b98a5;font-size:13px;margin-bottom:20px}
+.card{background:#161c23;border:1px solid #232c36;border-radius:10px;padding:14px;margin-bottom:14px}
+svg{width:100%;height:auto} .tt{fill:#e6edf3;font-size:12px;font-weight:600} .lb{fill:#aeb8c2;font-size:11px}
+.vl{fill:#8b98a5;font-size:10px} .gr{stroke:#232c36;stroke-width:1}
+table{width:100%;border-collapse:collapse;font-size:12px} td,th{padding:6px 8px;border-bottom:1px solid #232c36;text-align:left}
+th{color:#8b98a5;font-weight:600}
+</style></head><body>
+<h1>🧠 Open Claudia — recall KPIs by version</h1>
+<div class="sub">Generated ${new Date().toISOString().slice(0, 16).replace("T", " ")} · ${rows.reduce((a, r) => a + r.turns, 0)} recall turns · ${snaps.length} dream snapshot${snaps.length === 1 ? "" : "s"}</div>
+${charts}
+${trendChart ? `<div class="card">${trendChart}</div>` : ""}
+<div class="card"><table>
+<tr><th>version</th><th>window</th><th>turns</th><th>latency by tier</th><th>opens / reviewer</th><th>cascade kept / dropped</th><th>walker model</th></tr>
+${tierRows}
+</table></div>
+</body></html>`;
+}
+
+function writeHtmlReport(outPath) {
+  const p = outPath || require("path").join(require("../../config-dir"), "kpi-report.html");
+  fs.writeFileSync(p, htmlReport());
+  return p;
+}
+
+module.exports = { LEGACY_VERSION, aggregate, trend, renderTable, htmlReport, writeHtmlReport };