@kage-core/kage-graph-mcp 3.0.0 → 3.2.0

package/dist/cli.js

@@ -489,7 +489,17 @@ async function main() {
                 console.log(`  … and ${packets.length - 20} more`);
             return;
         }
+        if (sub === "view") {
+            (0, okf_js_1.migratePacketsToOkf)(project, { includePending: args.includes("--pending") });
+            const concepts = (0, okf_js_1.loadOkfConcepts)((0, okf_js_1.okfBundleDir)(project), { projectDir: project });
+            const out = (0, node_path_1.join)((0, okf_js_1.okfBundleDir)(project), "viewer.html");
+            (0, node_fs_1.writeFileSync)(out, (0, okf_js_1.okfViewerHtml)(concepts, { title: (0, node_path_1.basename)(project) }), "utf8");
+            console.log(`OKF viewer: ${concepts.length} concept(s) — a self-contained page, no server, no giant URL.`);
+            console.log(`Open it:  open ${out}`);
+            return;
+        }
         console.log("kage okf — Open Knowledge Format is Kage's standard memory format.");
+        console.log("  kage okf view [--project <dir>]                   view your memory as a clean OKF bundle (self-contained page)");
         console.log("  kage okf migrate [--project <dir>] [--pending]   packets → OKF bundle (.agent_memory/okf)");
         console.log("  kage okf lint [<dir|file>] [--project <dir>]      check OKF conformance");
         console.log("  kage okf import [<dir>] [--project <dir>] [--json]  read an OKF bundle back into packets");

package/dist/daemon.js

@@ -823,7 +823,7 @@ async function startViewer(projectDir, options = {}) {
         res.end((0, node_fs_1.readFileSync)(filePath));
     });
     await new Promise((resolveListen) => server.listen(port, host, resolveListen));
-    console.log(`Kage viewer listening on ${url}`);
+    console.log(`Kage viewer → http://${host}:${port}/`);
     process.on("SIGTERM", () => {
         liveFeed.close();
         server.close(() => process.exit(0));

package/dist/kernel.js

@@ -154,6 +154,7 @@ exports.setupAgent = setupAgent;
 exports.generatePluginHooks = generatePluginHooks;
 exports.setupDoctor = setupDoctor;
 exports.verifyAgentActivation = verifyAgentActivation;
+exports.pruneObservations = pruneObservations;
 exports.observe = observe;
 exports.observationSignalScore = observationSignalScore;
 exports.kageSessionCaptureReport = kageSessionCaptureReport;
@@ -209,6 +210,7 @@ const node_worker_threads_1 = require("node:worker_threads");
 const ts = __importStar(require("typescript"));
 const index_js_1 = require("./registry/index.js");
 const okf_js_1 = require("./okf.js");
+const metrics_math_js_1 = require("./metrics-math.js");
 exports.PACKET_SCHEMA_VERSION = 2;
 exports.MEMORY_TYPES = [
     "repo_map",
@@ -375,25 +377,32 @@ For normal coding tasks:
 For quick factual questions, \`kage_context\` alone is enough. For status or demo requests, call \`kage_metrics\`.
 ${AGENTS_POLICY_END}
 `;
+// Hooks pass raw user prompts as recall queries ("what is X? can we replace it"),
+// so interrogatives, pronouns, and auxiliaries must be stopwords too — otherwise
+// filler words collect BM25/vector/graph credit and drown the query's rare,
+// high-IDF terms (a packet literally titled with the queried term lost to
+// packets matching only "what"/"can"/"we").
 const STOPWORDS = new Set([
-    "a",
-    "an",
-    "and",
-    "are",
-    "do",
-    "does",
-    "for",
-    "how",
-    "i",
-    "in",
-    "is",
-    "it",
-    "of",
-    "on",
-    "or",
-    "the",
-    "to",
-    "with",
+    "a", "about", "again", "also", "an", "and", "are", "as", "at",
+    "be", "been", "being", "but", "by",
+    "can", "could",
+    "did", "do", "does",
+    "else",
+    "for", "from",
+    "had", "has", "have", "having", "he", "her", "hers", "here", "him", "his", "how",
+    "i", "if", "in", "into", "is", "it", "its",
+    "just",
+    "let", "lets",
+    "may", "me", "might", "mine", "my",
+    "no", "not",
+    "of", "on", "once", "or", "our", "ours", "over",
+    "please",
+    "shall", "she", "should", "so",
+    "than", "that", "the", "their", "theirs", "them", "then", "there", "these", "they", "this", "those", "to", "too",
+    "under", "us",
+    "very",
+    "was", "we", "were", "what", "when", "where", "which", "who", "whom", "whose", "why", "will", "would", "with",
+    "you", "your", "yours",
 ]);
 function memoryRoot(projectDir) {
     return (0, node_path_1.join)(projectDir, ".agent_memory");
@@ -7010,6 +7019,7 @@ function refreshProject(projectDir, options = {}) {
     }
     const validation = validateProject(projectDir);
     const metrics = kageMetricsShallow(projectDir, { codeGraph, knowledgeGraph, validation });
+    pruneObservations(projectDir);
     ensureDir(reportsDir(projectDir));
     writeJson((0, node_path_1.join)(reportsDir(projectDir), "context-slots.json"), kageContextSlots(projectDir));
     writeJson((0, node_path_1.join)(reportsDir(projectDir), "handoff.json"), kageMemoryHandoff(projectDir));
@@ -7943,12 +7953,17 @@ function recallBreakdown(projectDir, terms, packet, textScore, temporalScore = 0
     const vector = Number(vectorScore.toFixed(2));
     const usage = Number(usageScore.toFixed(2));
     const pathTypeTagWeight = packet.type === "reference" ? 0.2 : 0.8;
-    // Popularity (usage) must only AMPLIFY genuine relevance, never float a packet that has no
-    // lexical/semantic/graph/intent match to the top — that is what produced confident
-    // off-domain junk (a hot packet ranked #1 for a query it shared no terms with).
+    // Priors (usage, quality, freshness) must only AMPLIFY genuine relevance, never float a
+    // packet that has no lexical/semantic/graph/tag/intent match to the top — that is what
+    // produced confident off-domain junk: a hot, high-quality packet ranked above the one
+    // packet whose title literally contained the queried term, because its unconditional
+    // quality+freshness (~12 pts) beat a weak-but-real lexical match.
     const coreRelevance = textScore + graphScore + intent + vector;
+    const matchSignal = coreRelevance + pathTypeTag;
     const effectiveUsage = coreRelevance > 0 ? usage : 0;
-    const final = Number((textScore + graphScore + pathTypeTag * pathTypeTagWeight + intent + vector + effectiveUsage + freshness + quality + feedback).toFixed(2));
+    const effectiveQuality = matchSignal > 0 ? quality : 0;
+    const effectiveFreshness = matchSignal > 0 ? freshness : Math.min(freshness, 0);
+    const final = Number((textScore + graphScore + pathTypeTag * pathTypeTagWeight + intent + vector + effectiveUsage + effectiveFreshness + effectiveQuality + feedback).toFixed(2));
     return {
         bm25: textScore,
         text: textScore,
@@ -12987,16 +13002,16 @@ function benchmarkCodingMemoryQuality(options = {}) {
             retrieved,
             latency_ms: latencyMs,
             context_tokens: estimateTokens(recalled.context_block),
-            recall: Object.fromEntries(metricsK.map((k) => [`at_${k}`, roundDecimal(codingRecallAt(retrieved, relevant, k) * 100, 2)])),
-            precision_at_5_percent: roundDecimal(codingPrecisionAt(retrieved, relevant, 5) * 100, 2),
-            ndcg_at_10: roundDecimal(codingNdcgAt(retrieved, relevant, 10), 4),
-            mrr: roundDecimal(codingMrr(retrieved, relevant), 4),
+            recall: Object.fromEntries(metricsK.map((k) => [`at_${k}`, (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingRecallAt)(retrieved, relevant, k) * 100, 2)])),
+            precision_at_5_percent: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingPrecisionAt)(retrieved, relevant, 5) * 100, 2),
+            ndcg_at_10: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingNdcgAt)(retrieved, relevant, 10), 4),
+            mrr: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.codingMrr)(retrieved, relevant), 4),
         };
     });
     const sourceDiversity = codingMemorySourceDiversityProbe((0, node_path_1.join)(runDir, "source-diversity"));
     const allMemoryTokens = estimateTokens(loadApprovedPackets(projectDir).map(packetText).join("\n\n"));
-    const averageContextTokens = Math.round(averageNumber(perQuery.map((item) => item.context_tokens)));
-    const recallByK = Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, roundDecimal(averageNumber(perQuery.map((item) => item.recall[`at_${k}`] ?? 0)), 2)]));
+    const averageContextTokens = Math.round((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.context_tokens)));
+    const recallByK = Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.recall[`at_${k}`] ?? 0)), 2)]));
     const summary = {
         benchmark: "Kage coding memory quality",
         retrieval_mode: "kage-recall-default",
@@ -13006,14 +13021,14 @@ function benchmarkCodingMemoryQuality(options = {}) {
         refresh_ms: refreshMs,
         ...recallByK,
         recall_at_k_percent: Number(recallByK[`recall_at_${topK}_percent`] ?? 0),
-        precision_at_5_percent: roundDecimal(averageNumber(perQuery.map((item) => item.precision_at_5_percent)), 2),
-        ndcg_at_10: roundDecimal(averageNumber(perQuery.map((item) => item.ndcg_at_10)), 4),
-        mrr: roundDecimal(averageNumber(perQuery.map((item) => item.mrr)), 4),
-        median_latency_ms: percentileNumber(perQuery.map((item) => item.latency_ms), 0.5),
-        p95_latency_ms: percentileNumber(perQuery.map((item) => item.latency_ms), 0.95),
+        precision_at_5_percent: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.precision_at_5_percent)), 2),
+        ndcg_at_10: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.ndcg_at_10)), 4),
+        mrr: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(perQuery.map((item) => item.mrr)), 4),
+        median_latency_ms: (0, metrics_math_js_1.percentileNumber)(perQuery.map((item) => item.latency_ms), 0.5),
+        p95_latency_ms: (0, metrics_math_js_1.percentileNumber)(perQuery.map((item) => item.latency_ms), 0.95),
         all_memory_tokens: allMemoryTokens,
         average_context_tokens: averageContextTokens,
-        context_reduction_percent: roundDecimal(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
+        context_reduction_percent: (0, metrics_math_js_1.roundDecimal)(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
         source_diversity_pass: sourceDiversity.pass,
         source_diversity_unique_sources: sourceDiversity.unique_sources,
         source_diversity_max_results_from_one_source: sourceDiversity.max_results_from_one_source,
@@ -13027,7 +13042,7 @@ function benchmarkCodingMemoryQuality(options = {}) {
             queries: queries.length,
             packets_per_topic: packetsPerTopic,
             distractors_per_topic: distractorsPerTopic,
-            categories: countByKey(queries, (item) => item.category),
+            categories: (0, metrics_math_js_1.countByKey)(queries, (item) => item.category),
         },
         top_k: topK,
         metrics_k: metricsK,
@@ -13120,7 +13135,7 @@ function codingMemorySourceDiversityProbe(projectDir) {
             source,
         };
     });
-    const sourceCounts = countByKey(retrieved, (item) => item.source);
+    const sourceCounts = (0, metrics_math_js_1.countByKey)(retrieved, (item) => item.source);
     const maxResultsFromOneSource = Math.max(0, ...Object.values(sourceCounts));
     const independentRank = retrieved.find((item) => item.source === "session:independent-session")?.rank ?? null;
     return {
@@ -13178,16 +13193,16 @@ function benchmarkMemoryScale(options = {}) {
             };
         });
         const allMemoryTokens = estimateTokens(loadApprovedPackets(projectDir).map(packetText).join("\n\n"));
-        const averageContextTokens = Math.round(averageNumber(queries.map((item) => item.context_tokens)));
+        const averageContextTokens = Math.round((0, metrics_math_js_1.averageNumber)(queries.map((item) => item.context_tokens)));
         results.push({
             packets: size,
             refresh_ms: refreshMs,
-            recall_hit_rate_percent: roundDecimal((queries.filter((item) => item.hit).length / queries.length) * 100, 2),
-            median_recall_latency_ms: percentileNumber(queries.map((item) => item.latency_ms), 0.5),
-            p95_recall_latency_ms: percentileNumber(queries.map((item) => item.latency_ms), 0.95),
+            recall_hit_rate_percent: (0, metrics_math_js_1.roundDecimal)((queries.filter((item) => item.hit).length / queries.length) * 100, 2),
+            median_recall_latency_ms: (0, metrics_math_js_1.percentileNumber)(queries.map((item) => item.latency_ms), 0.5),
+            p95_recall_latency_ms: (0, metrics_math_js_1.percentileNumber)(queries.map((item) => item.latency_ms), 0.95),
             all_memory_tokens: allMemoryTokens,
             average_context_tokens: averageContextTokens,
-            context_reduction_percent: roundDecimal(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
+            context_reduction_percent: (0, metrics_math_js_1.roundDecimal)(((allMemoryTokens - averageContextTokens) / Math.max(1, allMemoryTokens)) * 100, 2),
             queries,
         });
     }
@@ -13319,7 +13334,7 @@ function codingObservation(index, item, target, variant) {
         topic: item.id,
         target,
         category: item.category,
-        title: `${titleCase(item.query)} repo memory ${variant + 1}`,
+        title: `${(0, metrics_math_js_1.titleCase)(item.query)} repo memory ${variant + 1}`,
         summary: `Reusable learning about ${item.query}: ${item.lesson}`,
         body: [
             `During a real agent session, this durable repo learning was captured for ${item.query}.`,
@@ -13404,32 +13419,11 @@ function codingQualityByCategory(perQuery, metricsK) {
     return Array.from(groups.entries()).map(([category, rows]) => ({
         category,
         queries: rows.length,
-        ...Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, roundDecimal(averageNumber(rows.map((item) => item.recall[`at_${k}`] ?? 0)), 2)])),
-        ndcg_at_10: roundDecimal(averageNumber(rows.map((item) => item.ndcg_at_10)), 4),
-        mrr: roundDecimal(averageNumber(rows.map((item) => item.mrr)), 4),
+        ...Object.fromEntries(metricsK.map((k) => [`recall_at_${k}_percent`, (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(rows.map((item) => item.recall[`at_${k}`] ?? 0)), 2)])),
+        ndcg_at_10: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(rows.map((item) => item.ndcg_at_10)), 4),
+        mrr: (0, metrics_math_js_1.roundDecimal)((0, metrics_math_js_1.averageNumber)(rows.map((item) => item.mrr)), 4),
     }));
 }
-function codingRecallAt(retrieved, relevant, k) {
-    if (!relevant.size)
-        return 0;
-    return retrieved.slice(0, k).filter((item) => relevant.has(item.packet_id)).length / relevant.size;
-}
-function codingPrecisionAt(retrieved, relevant, k) {
-    const rows = retrieved.slice(0, k);
-    return rows.length ? rows.filter((item) => relevant.has(item.packet_id)).length / rows.length : 0;
-}
-function codingNdcgAt(retrieved, relevant, k) {
-    const dcg = retrieved.slice(0, k).reduce((sum, item, index) => sum + (relevant.has(item.packet_id) ? 1 / Math.log2(index + 2) : 0), 0);
-    const idealHits = Math.min(relevant.size, k);
-    let ideal = 0;
-    for (let index = 0; index < idealHits; index += 1)
-        ideal += 1 / Math.log2(index + 2);
-    return ideal ? dcg / ideal : 0;
-}
-function codingMrr(retrieved, relevant) {
-    const index = retrieved.findIndex((item) => relevant.has(item.packet_id));
-    return index >= 0 ? 1 / (index + 1) : 0;
-}
 function codingTypeForCategory(category) {
     if (category === "runbook")
         return "runbook";
@@ -13442,31 +13436,6 @@ function codingTypeForCategory(category) {
 function codingFileForTopic(topic, variant) {
     return `src/${slugify(topic)}-${variant % 3}.ts`;
 }
-function averageNumber(values) {
-    return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
-}
-function percentileNumber(values, p) {
-    if (!values.length)
-        return 0;
-    const sorted = values.slice().sort((a, b) => a - b);
-    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
-    return sorted[index];
-}
-function roundDecimal(value, digits = 2) {
-    const factor = 10 ** digits;
-    return Math.round(value * factor) / factor;
-}
-function countByKey(rows, fn) {
-    const counts = {};
-    for (const row of rows) {
-        const key = fn(row);
-        counts[key] = (counts[key] ?? 0) + 1;
-    }
-    return counts;
-}
-function titleCase(value) {
-    return value.replace(/\b[a-z]/g, (match) => match.toUpperCase());
-}
 function baselineDiscoveryFiles(projectDir, task) {
     const terms = tokenize(task);
     const graph = buildCodeGraph(projectDir);
@@ -14750,6 +14719,36 @@ function verifyAgentActivation(agent, projectDir, options = {}) {
 function observationPath(projectDir, id) {
     return (0, node_path_1.join)(observationsDir(projectDir), `${id}.json`);
 }
+// Observations are session-scoped raw signal: distill consumes them at session end and
+// the resume digest only reads the recent window. Without retention the directory grows
+// forever (measured: 12k files / 48MB in two months of dogfooding), so refresh prunes
+// records older than the retention window. 0 disables pruning.
+const OBSERVATION_RETENTION_DAYS = (() => {
+    const raw = Number(process.env.KAGE_OBSERVATION_RETENTION_DAYS ?? "30");
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30;
+})();
+function pruneObservations(projectDir, maxAgeDays = OBSERVATION_RETENTION_DAYS) {
+    if (maxAgeDays <= 0)
+        return { pruned: 0 };
+    const dir = observationsDir(projectDir);
+    if (!(0, node_fs_1.existsSync)(dir))
+        return { pruned: 0 };
+    const cutoff = Date.now() - maxAgeDays * 86_400_000;
+    let pruned = 0;
+    for (const name of (0, node_fs_1.readdirSync)(dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        const path = (0, node_path_1.join)(dir, name);
+        try {
+            if ((0, node_fs_1.statSync)(path).mtimeMs < cutoff) {
+                (0, node_fs_1.unlinkSync)(path);
+                pruned += 1;
+            }
+        }
+        catch { /* concurrent removal — skip */ }
+    }
+    return { pruned };
+}
 function observationHash(projectDir, event) {
     const bucket = event.timestamp ? new Date(event.timestamp).toISOString().slice(0, 16) : nowIso().slice(0, 16);
     return (0, node_crypto_1.createHash)("sha256")

package/dist/metrics-math.js

@@ -0,0 +1,71 @@
+"use strict";
+// Pure metric and statistics helpers used by the benchmark/metrics code.
+// This is a dependency-free leaf module: it imports nothing from the kernel,
+// so pulling it out carries no circular-dependency risk. Leaf-first is the
+// safe way to decompose the kernel — extract the bottom of the dependency
+// graph first, where nothing depends back inward.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codingRecallAt = codingRecallAt;
+exports.codingPrecisionAt = codingPrecisionAt;
+exports.codingNdcgAt = codingNdcgAt;
+exports.codingMrr = codingMrr;
+exports.averageNumber = averageNumber;
+exports.percentileNumber = percentileNumber;
+exports.roundDecimal = roundDecimal;
+exports.countByKey = countByKey;
+exports.titleCase = titleCase;
+/** Recall@k: fraction of the relevant set retrieved within the top k. */
+function codingRecallAt(retrieved, relevant, k) {
+    if (!relevant.size)
+        return 0;
+    return retrieved.slice(0, k).filter((item) => relevant.has(item.packet_id)).length / relevant.size;
+}
+/** Precision@k: fraction of the top k that is relevant. */
+function codingPrecisionAt(retrieved, relevant, k) {
+    const rows = retrieved.slice(0, k);
+    return rows.length ? rows.filter((item) => relevant.has(item.packet_id)).length / rows.length : 0;
+}
+/** Normalized discounted cumulative gain at k (binary relevance). */
+function codingNdcgAt(retrieved, relevant, k) {
+    const dcg = retrieved.slice(0, k).reduce((sum, item, index) => sum + (relevant.has(item.packet_id) ? 1 / Math.log2(index + 2) : 0), 0);
+    const idealHits = Math.min(relevant.size, k);
+    let ideal = 0;
+    for (let index = 0; index < idealHits; index += 1)
+        ideal += 1 / Math.log2(index + 2);
+    return ideal ? dcg / ideal : 0;
+}
+/** Mean reciprocal rank: 1 / rank of the first relevant hit, else 0. */
+function codingMrr(retrieved, relevant) {
+    const index = retrieved.findIndex((item) => relevant.has(item.packet_id));
+    return index >= 0 ? 1 / (index + 1) : 0;
+}
+/** Arithmetic mean, 0 for an empty list. */
+function averageNumber(values) {
+    return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
+}
+/** p-th percentile (0..1) via nearest-rank, 0 for an empty list. */
+function percentileNumber(values, p) {
+    if (!values.length)
+        return 0;
+    const sorted = values.slice().sort((a, b) => a - b);
+    const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
+    return sorted[index];
+}
+/** Round to a fixed number of decimal places. */
+function roundDecimal(value, digits = 2) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}
+/** Tally rows by a string key. */
+function countByKey(rows, fn) {
+    const counts = {};
+    for (const row of rows) {
+        const key = fn(row);
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+}
+/** Upper-case the first letter of each word. */
+function titleCase(value) {
+    return value.replace(/\b[a-z]/g, (match) => match.toUpperCase());
+}

package/dist/okf.js

@@ -25,6 +25,7 @@ exports.okfConceptFileName = okfConceptFileName;
 exports.okfBundleDir = okfBundleDir;
 exports.migratePacketsToOkf = migratePacketsToOkf;
 exports.loadOkfConcepts = loadOkfConcepts;
+exports.okfViewerHtml = okfViewerHtml;
 exports.lintOkfBundle = lintOkfBundle;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
@@ -368,6 +369,102 @@ function loadOkfConcepts(dir, opts = {}) {
     }
     return out;
 }
+// A clean, self-contained OKF bundle viewer — one HTML file with the concepts
+// inlined, so it opens directly in a browser (no server, no giant URL). Renders
+// concepts as filterable cards with their OKF type, resource, and verification
+// status; click for the body. This is the "view your memory as an OKF bundle"
+// experience, and it works on ANY OKF bundle, not just Kage's.
+function okfViewerHtml(concepts, opts = {}) {
+    const rows = concepts.map((p) => ({
+        t: okfType(p.type),
+        title: p.title,
+        desc: p.summary || "",
+        resource: p.paths?.[0] || "",
+        tags: p.tags || [],
+        v: okfVerifiedStatus(p),
+        body: p.body || "",
+        updated: (p.updated_at || "").slice(0, 10),
+    }));
+    const data = JSON.stringify(rows).replace(/<\/(script)/gi, "<\\/$1");
+    const title = (opts.title || "Kage").replace(/[<>&"]/g, "");
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>OKF bundle — ${title}</title>
+<style>
+:root{--g:#1f9d57;--ink:#16201a;--mut:#5b665e;--line:#e3e6e0;--paper:#fff;--bg:#f7f8f6;--code:#0c110d}
+*{box-sizing:border-box}body{margin:0;font:15px/1.5 -apple-system,Segoe UI,Inter,sans-serif;color:var(--ink);background:var(--bg)}
+header{padding:26px 24px 18px;border-bottom:1px solid var(--line);background:var(--paper)}
+.wrap{max-width:1120px;margin:0 auto}
+.brand{display:flex;align-items:center;gap:9px;font-weight:600;font-size:13px;color:var(--mut)}
+.brand .dot{width:17px;height:17px;border-radius:5px;border:1.5px solid var(--g);position:relative}
+.brand .dot::after{content:"";position:absolute;inset:4px;border-radius:50%;background:var(--g);opacity:.5}
+h1{margin:10px 0 2px;font-size:22px}
+.stats{color:var(--mut);font-size:13.5px}.stats b{color:var(--ink)}
+.controls{max-width:1120px;margin:16px auto 0;padding:0 24px;display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+#q{flex:1;min-width:200px;padding:9px 13px;border:1px solid var(--line);border-radius:9px;font-size:14px;background:var(--paper);color:var(--ink)}
+#chips{display:flex;flex-wrap:wrap;gap:7px}
+.chip{padding:6px 11px;border:1px solid var(--line);border-radius:999px;background:var(--paper);color:var(--mut);font-size:12.5px;cursor:pointer}
+.chip.on{border-color:var(--g);color:var(--g);font-weight:600}
+main#grid{max-width:1120px;margin:18px auto 60px;padding:0 24px;display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:14px}
+.card{padding:15px 16px;border:1px solid var(--line);border-radius:12px;background:var(--paper);cursor:pointer;transition:border-color .12s}
+.card:hover{border-color:var(--g)}
+.meta{display:flex;align-items:center;gap:8px}
+.badge{font:600 10.5px/1 ui-monospace,monospace;text-transform:uppercase;letter-spacing:.05em;color:var(--g);background:rgba(31,157,87,.1);padding:4px 7px;border-radius:5px}
+.pill{margin-left:auto;font:600 11px/1 ui-monospace,monospace;padding:3px 8px;border-radius:999px}
+.pill.ok{color:#0c7a4d;background:rgba(12,122,77,.12)}.pill.warn{color:#9a6b08;background:rgba(154,107,8,.14)}.pill.dim{color:var(--mut);background:rgba(0,0,0,.05)}
+.ti{margin-top:9px;font-weight:600;font-size:15px;line-height:1.3}
+.res{margin-top:6px;font:12px/1.4 ui-monospace,monospace;color:#155e9c;word-break:break-all}
+.ds{margin-top:7px;color:var(--mut);font-size:13px}
+.empty{color:var(--mut);padding:50px;text-align:center;grid-column:1/-1}
+.detail{position:fixed;top:0;right:0;width:min(560px,93vw);height:100vh;overflow:auto;background:var(--paper);border-left:1px solid var(--line);box-shadow:-8px 0 34px rgba(0,0,0,.1);padding:24px 26px 60px;z-index:10}
+.detail.hidden{display:none}
+.detail .x{position:absolute;top:13px;right:16px;border:0;background:none;font-size:25px;color:var(--mut);cursor:pointer;line-height:1}
+.detail h2{margin:12px 0 4px;font-size:19px}
+.tags{margin-top:10px;display:flex;flex-wrap:wrap;gap:6px}.tags span{font:11px/1 ui-monospace,monospace;color:var(--mut);background:rgba(0,0,0,.05);padding:4px 7px;border-radius:5px}
+.detail pre{margin-top:16px;padding:14px 15px;background:var(--code);color:#c7cfc4;border-radius:10px;white-space:pre-wrap;font:12.5px/1.7 ui-monospace,monospace}
+.upd{font:11px/1 ui-monospace,monospace;color:var(--mut)}
+@media (prefers-color-scheme:dark){:root{--ink:#e7ebe4;--mut:#9aa49c;--line:#2a2f2a;--bg:#0e110e}body{background:var(--bg)}header,.card,#q,.chip,.detail{background:#161a16}.badge{background:rgba(31,157,87,.16)}.pill.dim{background:rgba(255,255,255,.07)}.tags span{background:rgba(255,255,255,.07)}}
+</style></head><body>
+<header><div class="wrap">
+  <div class="brand"><span class="dot"></span> Open Knowledge Format · viewed with Kage</div>
+  <h1>${title} — memory bundle</h1>
+  <div class="stats"><b id="n">0</b> concepts · <b id="nv">0</b> verified · <b id="nd">0</b> need attention</div>
+</div></header>
+<div class="controls"><input id="q" placeholder="Search concepts…" autocomplete="off"><div id="chips"></div></div>
+<main id="grid"></main>
+<div id="detail" class="detail hidden"></div>
+<script>
+var C=${data};
+(function(){
+  var grid=document.getElementById('grid'),q=document.getElementById('q'),chips=document.getElementById('chips'),detail=document.getElementById('detail'),active='all';
+  function esc(s){return String(s==null?'':s).replace(/[&<>"]/g,function(m){return {'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[m];});}
+  function vClass(v){return v==='fresh'||v==='verified'?'ok':(v==='drifted'||v==='stale'?'warn':'dim');}
+  var nv=0,nd=0;C.forEach(function(c){if(c.v==='fresh'||c.v==='verified')nv++;if(c.v==='drifted'||c.v==='stale')nd++;});
+  document.getElementById('n').textContent=C.length;document.getElementById('nv').textContent=nv;document.getElementById('nd').textContent=nd;
+  var types={};C.forEach(function(c){types[c.t]=(types[c.t]||0)+1;});
+  function mkChip(label,key){var b=document.createElement('button');b.className='chip'+(key==='all'?' on':'');b.textContent=label;b.onclick=function(){active=key;[].forEach.call(chips.children,function(x){x.classList.remove('on');});b.classList.add('on');render();};chips.appendChild(b);}
+  mkChip('All '+C.length,'all');Object.keys(types).sort().forEach(function(t){mkChip(t+' '+types[t],t);});
+  q.oninput=render;
+  function render(){var term=q.value.toLowerCase();grid.innerHTML='';var shown=0;
+    C.forEach(function(c){
+      if(active!=='all'&&c.t!==active)return;
+      if(term&&(c.title+' '+c.desc+' '+c.resource+' '+c.tags.join(' ')).toLowerCase().indexOf(term)<0)return;
+      shown++;var card=document.createElement('div');card.className='card';
+      card.innerHTML='<div class="meta"><span class="badge">'+esc(c.t)+'</span><span class="pill '+vClass(c.v)+'">'+esc(c.v)+'</span></div><div class="ti">'+esc(c.title)+'</div>'+(c.resource?'<div class="res">'+esc(c.resource)+'</div>':'')+'<div class="ds">'+esc(c.desc.slice(0,150))+'</div>';
+      card.onclick=function(){show(c);};grid.appendChild(card);
+    });
+    if(!shown)grid.innerHTML='<div class="empty">No concepts match.</div>';
+  }
+  function show(c){
+    detail.innerHTML='<button class="x" aria-label="Close" onclick="document.getElementById(\\'detail\\').classList.add(\\'hidden\\')">&times;</button><div class="meta"><span class="badge">'+esc(c.t)+'</span><span class="pill '+vClass(c.v)+'">'+esc(c.v)+'</span>'+(c.updated?'<span class="upd" style="margin-left:8px">'+esc(c.updated)+'</span>':'')+'</div><h2>'+esc(c.title)+'</h2>'+(c.resource?'<div class="res">resource · '+esc(c.resource)+'</div>':'')+(c.tags.length?'<div class="tags">'+c.tags.map(function(t){return '<span>'+esc(t)+'</span>';}).join('')+'</div>':'')+'<pre>'+esc(c.body)+'</pre>';
+    detail.classList.remove('hidden');
+  }
+  document.addEventListener('keydown',function(e){if(e.key==='Escape')detail.classList.add('hidden');});
+  render();
+})();
+</script></body></html>
+`;
+}
 function lintOkfBundle(dir) {
     const failures = [];
     let files = 0;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "3.0.0",
-  "description": "Verified memory for coding agents, stored as a Google Open Knowledge Format (OKF) bundle and checked against your code. The verification layer OKF leaves out. MCP server, no account, no API key.",
+  "version": "3.2.0",
+  "description": "Agent memory on Google's Open Knowledge Format (OKF). Kage maintains your coding agents' OKF memory bundle in git and verifies every concept against your code, deterministically. The verification and freshness layer OKF leaves out. MCP server, no account, no API key.",
   "main": "dist/index.js",
   "files": [
     "dist/**/*.js",

package/viewer/console.js

@@ -67,7 +67,7 @@
   // ---- nav ----
   var META = {
     dashboard: ["kage://dashboard", "Dashboard", "Your team's captured knowledge — decisions, runbooks, and fixes — at a glance."],
-    gains: ["kage://gains", "What Kage saved you", "Tokens, dollars, and bad memories caught — receipts, not vibes."],
+    gains: ["kage://gains", "What Kage saved you", "Tokens saved and bad memories caught — receipts, not vibes."],
     overview: ["kage://trust", "Memory trust", "Whether this repo's agent memory can be trusted — at a glance."],
     graph: ["kage://memory-map", "Memory ↔ code map", "Each packet anchored to the files it's grounded in. Hover a node to inspect."],
     memory: ["kage://memory", "Memory", "Every packet Kage has stored, with health and grounding."],
@@ -137,12 +137,6 @@
   // value.json is the raw ledger written by recall: { totals, events[] }. Windows are
   // recomputed here with the same rules as `kage gains` (today = local midnight,
   // 7d = rolling, all-time = totals so trimmed events never lose history).
-  var DOLLARS_PER_MILLION_TOKENS = 15;
-  function dollars(tokens) { return (tokens / 1e6) * DOLLARS_PER_MILLION_TOKENS; }
-  function fmtDollars(tokens) {
-    var d = dollars(tokens);
-    return "$" + (d >= 100 ? Math.round(d) : d.toFixed(2));
-  }
   function summarizeWindow(events, cutoff) {
     var w = { tokens_saved: 0, stale_withheld: 0, recalls: 0, caller_answers: 0 };
     events.forEach(function (e) {
@@ -175,7 +169,6 @@
     var big = el("div", "big");
     big.appendChild(el("b", null, all.tokens_saved ? "0" : "—"));
     big.appendChild(el("span", "unit", "tokens saved, all time"));
-    if (all.tokens_saved) big.appendChild(el("span", "dollars", "≈ " + fmtDollars(all.tokens_saved)));
     hh.appendChild(big);
     hh.appendChild(el("p", "sub", all.tokens_saved
       ? "Context your agents did not have to re-read from source, because Kage served grounded memory instead."
@@ -186,7 +179,6 @@
       var w = el("div", "r-win");
       w.appendChild(el("div", "k", p[0]));
       w.appendChild(el("div", "v", fmt(p[1].tokens_saved) + " tok"));
-      w.appendChild(el("div", "d", "≈ " + fmtDollars(p[1].tokens_saved)));
       wins.appendChild(w);
     });
     hero.appendChild(wins);
@@ -203,13 +195,13 @@
       lines.appendChild(row);
     });
     hero.appendChild(lines);
-    hero.appendChild(el("div", "r-foot", "estimated at $" + DOLLARS_PER_MILLION_TOKENS + " per 1M input tokens · ledger: .agent_memory/reports/value.json · verify: kage gains"));
+    hero.appendChild(el("div", "r-foot", "ledger: .agent_memory/reports/value.json · verify: kage gains"));
     if (all.tokens_saved) countUp(big.querySelector("b"), all.tokens_saved, 900);
 
     if (tiles) {
       tiles.textContent = "";
       [
-        { k: "Saved (7 days)", v: fmt(week.tokens_saved), s: "≈ " + fmtDollars(week.tokens_saved) + " of context not re-read", cls: "green" },
+        { k: "Saved (7 days)", v: fmt(week.tokens_saved), s: "tokens of context not re-read", cls: "green" },
         { k: "Recalls served (7d)", v: fmt(week.recalls), s: fmt(all.recalls) + " all-time", cls: "green" },
         { k: "Stale caught", v: fmt(all.stale_withheld), s: all.stale_withheld ? "withheld before they misled an agent" : "nothing withheld yet", cls: all.stale_withheld ? "warn" : "" },
         { k: "Graph answers", v: fmt(all.caller_answers), s: "caller questions answered from the code graph", cls: "code" },

package/viewer/index.html

@@ -69,14 +69,12 @@
       .receipt .r-hero .big { display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; }
       .receipt .r-hero .big b { font: 600 64px/0.95 var(--serif); letter-spacing: -0.02em; color: var(--gain); font-variant-numeric: tabular-nums; }
       .receipt .r-hero .big .unit { color: var(--muted); font: 500 16px/1 var(--sans); }
-      .receipt .r-hero .big .dollars { color: var(--ink); font: 600 22px/1 var(--serif); }
       .receipt .r-hero .sub { margin-top: 10px; color: var(--muted); font: 400 13.5px/1.5 var(--sans); max-width: 560px; }
       .receipt .r-windows { display: grid; grid-template-columns: repeat(3, 1fr); border-top: 1px dashed var(--line-strong); }
       .receipt .r-win { padding: 16px 24px; border-left: 1px dashed var(--line-strong); }
       .receipt .r-win:first-child { border-left: 0; }
       .receipt .r-win .k { color: var(--faint); font: 600 10px/1 var(--mono); text-transform: uppercase; letter-spacing: 0.1em; }
       .receipt .r-win .v { margin-top: 8px; font: 600 24px/1 var(--serif); color: var(--ink); font-variant-numeric: tabular-nums; }
-      .receipt .r-win .d { margin-top: 5px; color: var(--gain); font: 600 12px/1 var(--mono); }
       .receipt .r-lines { border-top: 1px dashed var(--line-strong); padding: 14px 24px 16px; }
       .receipt .r-line { display: flex; align-items: baseline; gap: 10px; padding: 5px 0; font: 400 13.5px/1.5 var(--sans); color: var(--ink); }
       .receipt .r-line .dots { flex: 1; border-bottom: 1px dotted var(--line-strong); transform: translateY(-4px); }
@@ -290,7 +288,7 @@
         <header class="head">
           <span class="eyebrow" id="eyebrow">kage://gains</span>
           <h1 id="title">What Kage saved you</h1>
-          <p id="subtitle">Tokens, dollars, and bad memories caught — receipts, not vibes.</p>
+          <p id="subtitle">Tokens saved and bad memories caught — receipts, not vibes.</p>
         </header>
         <div class="wrap">
           <section class="section active" id="section-dashboard">