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

package/dist/cli.js

@@ -10,12 +10,12 @@ const node_process_1 = require("node:process");
 const daemon_js_1 = require("./daemon.js");
 const kernel_js_1 = require("./kernel.js");
 const graph_registry_js_1 = require("./graph-registry.js");
+const okf_js_1 = require("./okf.js");
 const CORE_USAGE = `Kage — code-grounded memory for coding agents
 
 Core commands:
   kage install [--project <dir>]             one-shot: init + index + auto-wire detected agents
   kage scan --project <dir>                  60-second truth report on any repo (zero setup)
-  kage demo                                  watch the reject/withhold loop run in a sandbox
   kage init --project <dir>                  create repo memory (.agent_memory only)
   kage index --project <dir> [--full]        build/refresh code graph + indexes
   kage recall "<query>" --project <dir>      grounded recall from repo memory
@@ -52,7 +52,7 @@ Usage:
   kage hook status --project <dir> [--json]
   kage hook uninstall --project <dir> [--json]
   kage refresh --project <dir> [--full] [--force] [--json]
-  kage merge-packet <ours> <base> <theirs>      git merge driver for .agent_memory/packets/*.json
+  kage merge-packet <ours> <base> <theirs>      git merge driver for .agent_memory/packets/*.md
   kage gc --project <dir> [--dry-run] [--force] [--json]
   kage compact --project <dir> [--dry-run] [--json]
   kage verify --project <dir> [--id <packet-id>] [--json]
@@ -449,6 +449,52 @@ async function main() {
         console.log("  npx -y @kage-core/kage-graph-mcp install");
         return;
     }
+    if (command === "okf") {
+        // OKF (Open Knowledge Format) is Kage's standard on-disk memory format.
+        const sub = args[1] && !args[1].startsWith("--") ? args[1] : "";
+        const project = (0, node_path_1.resolve)(projectArg(args));
+        if (sub === "migrate" || sub === "export") {
+            const result = (0, okf_js_1.migratePacketsToOkf)(project, { includePending: args.includes("--pending") });
+            console.log(`Kage memory → OKF: wrote ${result.written} concept(s) to ${result.root}`);
+            for (const [type, count] of Object.entries(result.byType).sort((a, b) => b[1] - a[1])) {
+                console.log(`  ${type}: ${count}`);
+            }
+            console.log("\nConformant OKF bundle: index.md (progressive disclosure), log.md (history), concept docs.");
+            console.log("Trust metadata rides in x-kage-* frontmatter, so any OKF consumer (incl. Google's visualizer) reads it unchanged.");
+            return;
+        }
+        if (sub === "lint") {
+            const target = args[2] && !args[2].startsWith("--") ? (0, node_path_1.resolve)(args[2]) : (0, okf_js_1.okfBundleDir)(project);
+            const { files, failures } = (0, okf_js_1.lintOkfBundle)(target);
+            if (failures.length === 0) {
+                console.log(`OKF lint: ${files} concept(s) in ${target} — all conformant.`);
+                return;
+            }
+            console.log(`OKF lint: ${failures.length}/${files} concept(s) non-conformant in ${target}:`);
+            for (const failure of failures)
+                console.log(`  ${failure.path}: ${failure.errors.join("; ")}`);
+            process.exit(1);
+        }
+        if (sub === "import") {
+            const dir = args[2] && !args[2].startsWith("--") ? (0, node_path_1.resolve)(args[2]) : (0, okf_js_1.okfBundleDir)(project);
+            const packets = (0, okf_js_1.loadOkfConcepts)(dir, { projectDir: project });
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(packets, null, 2));
+                return;
+            }
+            console.log(`Read ${packets.length} concept(s) from OKF bundle ${dir}`);
+            for (const packet of packets.slice(0, 20))
+                console.log(`  [${packet.type}] ${packet.title}`);
+            if (packets.length > 20)
+                console.log(`  … and ${packets.length - 20} more`);
+            return;
+        }
+        console.log("kage okf — Open Knowledge Format is Kage's standard memory format.");
+        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");
+        return;
+    }
     if (command === "init") {
         const withPolicy = args.includes("--with-policy");
         const result = (0, kernel_js_1.initProject)(projectArg(args), { policy: withPolicy });
@@ -1406,6 +1452,10 @@ async function main() {
                 `~${(0, kernel_js_1.formatTokenCount)(summary.all_time.replay_tokens)} all time ` +
                 `(discovery cost of served memories vs their compressed read cost)`);
         }
+        const usdOverridden = Number.isFinite(Number(process.env.KAGE_USD_PER_MTOK)) && Number(process.env.KAGE_USD_PER_MTOK) > 0;
+        console.log(`\nDollars estimated at $${kernel_js_1.VALUE_DOLLARS_PER_MILLION_TOKENS}/1M input tokens ` +
+            `(${usdOverridden ? "via KAGE_USD_PER_MTOK" : "Sonnet-class default — set KAGE_USD_PER_MTOK for your model"}). ` +
+            `Ledger: .agent_memory/reports/value.json`);
         return;
     }
     if (command === "file-context") {

package/dist/daemon.js

@@ -202,7 +202,7 @@ function startLiveFeed(projectRoot, options = {}) {
     try {
         watchers.push((0, node_fs_1.watch)(packetsDir, (_event, filename) => {
             const name = String(filename ?? "");
-            if (!name.endsWith(".json"))
+            if (!name.endsWith(".json") && !name.endsWith(".md"))
                 return;
             debounced(`packet:${name}`, () => onPacketChange(name));
         }));

package/dist/kernel.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PACKET_MERGE_DRIVER_CONFIG = exports.PACKET_MERGE_ATTRIBUTE_LINE = exports.AUTO_DISTILL_SIGNAL_THRESHOLD = exports.AUTO_DISTILL_TAG = exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
+exports.PACKET_MERGE_DRIVER_CONFIG = exports.PACKET_MERGE_ATTRIBUTE_LINE = exports.AUTO_DISTILL_SIGNAL_THRESHOLD = exports.AUTO_DISTILL_TAG = exports.VALUE_DOLLARS_PER_MILLION_TOKENS = exports.SETUP_AGENTS = exports.MEMORY_TYPES = exports.PACKET_SCHEMA_VERSION = void 0;
 exports.memoryRoot = memoryRoot;
 exports.packetsDir = packetsDir;
 exports.pendingDir = pendingDir;
@@ -208,6 +208,7 @@ const node_path_1 = require("node:path");
 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");
 exports.PACKET_SCHEMA_VERSION = 2;
 exports.MEMORY_TYPES = [
     "repo_map",
@@ -271,7 +272,11 @@ const AGENTS_POLICY_END = "<!-- END_KAGE_MEMORY_POLICY_V1 -->";
 const AGENTS_POLICY = `${AGENTS_POLICY_MARKER}
 # Kage Memory Harness
 
-This repo uses Kage as an automatic memory harness for coding agents.
+This repo uses Kage as an automatic memory harness for coding agents. Memory is
+stored and exchanged in Open Knowledge Format (OKF) — markdown concept files under
+\`.agent_memory/packets/\`, with Kage's verification metadata in OKF-legal \`x-kage-*\`
+frontmatter, readable by any OKF consumer. Use \`kage okf migrate|lint|import\` to
+work with OKF bundles.
 
 ## Automatic Recall
 
@@ -466,10 +471,23 @@ function ensureDir(path) {
     (0, node_fs_1.mkdirSync)(path, { recursive: true });
 }
 function readJson(path) {
+    // Packet files are OKF concept docs (.md); every other store artifact is JSON.
+    // Routing the dispatch here makes all packet readers (supersede, stale, repair,
+    // sync, …) format-aware without touching each call site.
+    if (path.endsWith(".md")) {
+        const packet = (0, okf_js_1.okfConceptToPacket)((0, node_fs_1.readFileSync)(path, "utf8"));
+        if (!packet)
+            throw new Error(`not a parseable OKF concept: ${path}`);
+        return packet;
+    }
     return JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
 }
 function writeJson(path, value) {
     ensureDir((0, node_path_1.dirname)(path));
+    if (path.endsWith(".md")) {
+        (0, node_fs_1.writeFileSync)(path, (0, okf_js_1.packetToOkfConcept)(value), "utf8");
+        return;
+    }
     (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
 function slugify(input) {
@@ -483,7 +501,7 @@ function slugify(input) {
 }
 function packetFileName(packet) {
     const idHash = (0, node_crypto_1.createHash)("sha256").update(packet.id).digest("hex").slice(0, 8);
-    return `${packet.type}-${slugify(packet.title)}-${idHash}.json`;
+    return `${packet.type}-${slugify(packet.title)}-${idHash}.md`;
 }
 function repoKey(projectDir) {
     const configPath = (0, node_path_1.join)(projectDir, ".git", "config");
@@ -1017,8 +1035,14 @@ function recordRecallAccess(projectDir, results) {
 // ---------------------------------------------------------------------------
 const VALUE_LEDGER_SCHEMA_VERSION = 1;
 const VALUE_LEDGER_EVENT_CAP = 5000;
-// Rough Sonnet-class input price used for the dollar estimate: $15 per 1M tokens.
-const VALUE_DOLLARS_PER_MILLION_TOKENS = 15;
+// Input price used for the dollar estimate. Default: Sonnet-class ~$3 per 1M input tokens (the
+// typical coding-agent tier) — deliberately conservative so the savings figure never overstates.
+// Override with KAGE_USD_PER_MTOK to match your model (e.g. 15 for Opus, 2.5 for GPT-4o, 0.8 for
+// Haiku). The old default ($15, Opus pricing) overstated savings ~5x for most users.
+exports.VALUE_DOLLARS_PER_MILLION_TOKENS = (() => {
+    const raw = Number(process.env.KAGE_USD_PER_MTOK);
+    return Number.isFinite(raw) && raw > 0 ? raw : 3;
+})();
 function valueLedgerPath(projectDir) {
     return (0, node_path_1.join)(reportsDir(projectDir), "value.json");
 }
@@ -1112,7 +1136,7 @@ function recordValueEvent(projectDir, event) {
     recordValueEvents(projectDir, [event]);
 }
 function estimatedTokenDollars(tokensSaved) {
-    return Number(((tokensSaved / 1_000_000) * VALUE_DOLLARS_PER_MILLION_TOKENS).toFixed(2));
+    return Number(((tokensSaved / 1_000_000) * exports.VALUE_DOLLARS_PER_MILLION_TOKENS).toFixed(2));
 }
 function summarizeValueWindow(events, cutoff) {
     const window = { tokens_saved: 0, replay_tokens: 0, stale_withheld: 0, stale_caught: 0, recalls: 0, caller_answers: 0 };
@@ -2369,9 +2393,33 @@ function walkFiles(root, predicate) {
 // Tolerant packet read: a single corrupt or merge-conflicted packet (e.g. an
 // unresolved `<<<<<<<` from a teammate's git merge) must not take down all of
 // recall/verify/compact. Skip the bad file with a warning and keep going.
+// Packets are stored as OKF concept documents (.md). Legacy .json packets stay
+// readable so existing stores and test fixtures keep loading during/after the swap.
+function isPacketFile(name) {
+    return name.endsWith(".md") || name.endsWith(".json");
+}
+// Read a packet file from disk, dispatching on format. Throws on an unparseable
+// file (same contract as the JSON reader it replaces); callers that tolerate bad
+// files go through tryReadPacket.
+function readPacketFromDisk(path) {
+    if (path.endsWith(".md")) {
+        const packet = (0, okf_js_1.okfConceptToPacket)((0, node_fs_1.readFileSync)(path, "utf8"));
+        if (!packet)
+            throw new Error(`not a parseable OKF concept: ${path}`);
+        return packet;
+    }
+    return readJson(path);
+}
+// Write a packet file, preserving its on-disk format (.md = OKF, legacy .json).
+function writePacketToDisk(path, packet) {
+    if (path.endsWith(".md"))
+        (0, node_fs_1.writeFileSync)(path, (0, okf_js_1.packetToOkfConcept)(packet), "utf8");
+    else
+        writeJson(path, packet);
+}
 function tryReadPacket(path) {
     try {
-        return readJson(path);
+        return readPacketFromDisk(path);
     }
     catch (error) {
         process.stderr.write(`kage: skipping unreadable memory packet ${path}: ${error.message}\n`);
@@ -2382,7 +2430,7 @@ function loadPacketsFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return [];
     return (0, node_fs_1.readdirSync)(dir)
-        .filter((name) => name.endsWith(".json"))
+        .filter(isPacketFile)
         .sort()
         .flatMap((name) => {
         const packet = tryReadPacket((0, node_path_1.join)(dir, name));
@@ -2393,7 +2441,7 @@ function loadPacketEntriesFromDir(dir) {
     if (!(0, node_fs_1.existsSync)(dir))
         return [];
     return (0, node_fs_1.readdirSync)(dir)
-        .filter((name) => name.endsWith(".json"))
+        .filter(isPacketFile)
         .sort()
         .flatMap((name) => {
         const path = (0, node_path_1.join)(dir, name);
@@ -2416,7 +2464,7 @@ function recallablePendingPackets(projectDir) {
 function writePacket(projectDir, packet, statusDir) {
     const dir = statusDir === "packets" ? packetsDir(projectDir) : pendingDir(projectDir);
     const path = (0, node_path_1.join)(dir, packetFileName(packet));
-    writeJson(path, packet);
+    writePacketToDisk(path, packet);
     return path;
 }
 function memoryAuditPath(projectDir) {
@@ -2815,7 +2863,7 @@ const NOISE_PATH_PREFIXES = [
     "elm-stuff/",
 ];
 function isReviewableMemoryPath(filePath) {
-    return /^\.agent_memory\/(?:packets|pending)\/[^/]+\.json$/.test(filePath);
+    return /^\.agent_memory\/(?:packets|pending)\/[^/]+\.(?:json|md)$/.test(filePath);
 }
 function isNoisePath(filePath) {
     if (isReviewableMemoryPath(filePath))
@@ -6731,7 +6779,7 @@ function readCurrentKnowledgeGraph(projectDir, codeGraph, expectedInputHash) {
 function graphFastFingerprint(projectDir) {
     const packetPaths = (0, node_fs_1.existsSync)(packetsDir(projectDir))
         ? (0, node_fs_1.readdirSync)(packetsDir(projectDir))
-            .filter((name) => name.endsWith(".json"))
+            .filter(isPacketFile)
             .map((name) => (0, node_path_1.join)(packetsDir(projectDir), name))
         : [];
     const paths = [
@@ -7147,7 +7195,7 @@ function compactProject(projectDir, options = {}) {
         if (hardReason) {
             deprecated.push({ id: packet.id, title: packet.title, reason: hardReason });
             if (!dryRun)
-                writeJson(path, { ...packet, status: "deprecated", updated_at: nowIso() });
+                writePacketToDisk(path, { ...packet, status: "deprecated", updated_at: nowIso() });
             continue;
         }
         const meaningful = packet.paths.filter((p) => meaningfulMemoryPath(p) && !shouldSkipRepoMemoryPath(p));
@@ -13939,7 +13987,7 @@ function createPublicCandidate(projectDir, id) {
     if (!validation.ok)
         return { ok: false, errors: validation.errors };
     const path = (0, node_path_1.join)(publicCandidatesDir(projectDir), packetFileName(packet));
-    writeJson(path, packet);
+    writePacketToDisk(path, packet);
     return { ok: true, packet, path, errors: [] };
 }
 function registryRecommendations(projectDir) {
@@ -15474,7 +15522,7 @@ function distillSession(projectDir, sessionId, options = {}) {
             result.path = promotedPath;
         }
         else {
-            writeJson(result.path, result.packet);
+            writePacketToDisk(result.path, result.packet);
         }
         return result;
     };
@@ -15686,7 +15734,7 @@ function createDiffChangeMemory(projectDir, summary) {
         const existing = (0, node_fs_1.readdirSync)(packetsDir(projectDir)).filter((name) => name.startsWith(stalePrefix) && name !== stableFileName);
         for (const name of existing) {
             const stale = (0, node_path_1.join)(packetsDir(projectDir), name);
-            const stalePacket = readJson(stale);
+            const stalePacket = readPacketFromDisk(stale);
             if (stalePacket?.type === "workflow" && stalePacket?.title === title) {
                 (0, node_fs_1.unlinkSync)(stale);
             }
@@ -16044,7 +16092,7 @@ function prCheck(projectDir) {
         .split(/\r?\n/)
         .map(parsePorcelainPath)
         .map((path) => path.replace(/^.* -> /, ""))
-        .filter((path) => path.startsWith(".agent_memory/packets/") && path.endsWith(".json"))).sort();
+        .filter((path) => path.startsWith(".agent_memory/packets/") && isPacketFile(path))).sort();
     const codeGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/code_graph/graph.json", { head: overlay.head, tree, inputHash: codeInputHash });
     const memoryGraphCurrent = graphIsCurrent(projectDir, ".agent_memory/graph/graph.json", { head: overlay.head, tree, inputHash: memoryInputHash });
     const sessions = kageSessionCaptureReport(projectDir);
@@ -16412,8 +16460,8 @@ function recordFeedback(projectDir, id, feedback) {
     if (!["helpful", "wrong", "stale"].includes(feedback)) {
         return { ok: false, errors: [`Invalid feedback: ${feedback}`] };
     }
-    for (const path of walkFiles(packetsDir(projectDir), (candidate) => candidate.endsWith(".json"))) {
-        const packet = readJson(path);
+    for (const path of walkFiles(packetsDir(projectDir), isPacketFile)) {
+        const packet = readPacketFromDisk(path);
         if (packet.id !== id)
             continue;
         const quality = (packet.quality ?? {});
@@ -16434,7 +16482,7 @@ function recordFeedback(projectDir, id, feedback) {
                 stale_reported_at: packet.updated_at,
             };
         }
-        writeJson(path, packet);
+        writePacketToDisk(path, packet);
         recordMemoryAudit(projectDir, "feedback", [packet], {
             feedback,
             path: (0, node_path_1.relative)(projectDir, path),
@@ -16454,9 +16502,9 @@ function validateProject(projectDir) {
         [pendingDir(projectDir), "pending"],
         [publicCandidatesDir(projectDir), "public candidate"],
     ]) {
-        for (const packetPath of walkFiles(dir, (path) => path.endsWith(".json"))) {
+        for (const packetPath of walkFiles(dir, isPacketFile)) {
             try {
-                const packet = readJson(packetPath);
+                const packet = readPacketFromDisk(packetPath);
                 const validation = validatePacket(packet, (0, node_path_1.relative)(projectDir, packetPath));
                 errors.push(...validation.errors);
                 warnings.push(...validation.warnings);
@@ -16654,12 +16702,17 @@ function resolveConflictedPacket(content) {
     for (const side of [sides.ours, sides.theirs]) {
         try {
             const parsed = JSON.parse(side);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
                 candidates.push(parsed);
+                continue;
+            }
         }
         catch {
-            // This side does not parse; the other side may still win.
+            // Not JSON — fall through and try the OKF concept format below.
         }
+        const okf = (0, okf_js_1.okfConceptToPacket)(side);
+        if (okf)
+            candidates.push(okf);
     }
     if (!candidates.length)
         return null;
@@ -16672,7 +16725,7 @@ function resolveConflictedPacket(content) {
 // exit 0 on success, non-zero to leave the conflict). v1 policy is whole-file
 // newest-wins by updated_at — packets are single facts, so field-level merges
 // buy little over taking the most recently verified side.
-exports.PACKET_MERGE_ATTRIBUTE_LINE = ".agent_memory/packets/*.json merge=kage-packet";
+exports.PACKET_MERGE_ATTRIBUTE_LINE = ".agent_memory/packets/*.md merge=kage-packet";
 exports.PACKET_MERGE_DRIVER_CONFIG = 'git config merge.kage-packet.driver "npx -y @kage-core/kage-graph-mcp merge-packet %A %O %B"';
 function mergePacketFiles(oursPath, basePath, theirsPath) {
     void basePath; // Reserved for a future field-level three-way merge.
@@ -16680,6 +16733,10 @@ function mergePacketFiles(oursPath, basePath, theirsPath) {
         const raw = safeReadText(path);
         if (raw === null)
             return null;
+        if (path.endsWith(".md")) {
+            const packet = (0, okf_js_1.okfConceptToPacket)(raw);
+            return packet ? { raw, packet } : null;
+        }
         try {
             const parsed = JSON.parse(raw);
             if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
@@ -16729,7 +16786,7 @@ function ensurePacketMergeAttributes(projectDir) {
     const path = (0, node_path_1.join)(projectDir, ".gitattributes");
     const existing = safeReadText(path) ?? "";
     const lines = existing.split(/\r?\n/);
-    const pattern = /^\.agent_memory\/packets\/\*\.json\s+merge=/;
+    const pattern = /^\.agent_memory\/packets\/\*\.(?:json|md)\s+merge=/;
     const index = lines.findIndex((line) => pattern.test(line.trim()));
     if (index !== -1) {
         if (lines[index].trim() === exports.PACKET_MERGE_ATTRIBUTE_LINE)
@@ -16756,7 +16813,7 @@ function repairProject(projectDir, options = {}) {
         [publicCandidatesDir(projectDir), "public-candidates"],
     ];
     for (const [dir, label] of packetDirs) {
-        for (const path of walkFiles(dir, (candidate) => candidate.endsWith(".json"))) {
+        for (const path of walkFiles(dir, isPacketFile)) {
             const target = `${label}/${(0, node_path_1.basename)(path)}`;
             let raw;
             try {
@@ -16953,14 +17010,14 @@ function remediationFor(error) {
     return "npx -y kage-graph-mcp doctor --project .";
 }
 function approvePending(projectDir, id) {
-    const pendingFiles = walkFiles(pendingDir(projectDir), (path) => path.endsWith(".json"));
+    const pendingFiles = walkFiles(pendingDir(projectDir), isPacketFile);
     for (const path of pendingFiles) {
-        const packet = readJson(path);
+        const packet = readPacketFromDisk(path);
         if (packet.id === id) {
             packet.status = "approved";
             packet.updated_at = nowIso();
             const target = (0, node_path_1.join)(packetsDir(projectDir), packetFileName(packet));
-            writeJson(target, packet);
+            writePacketToDisk(target, packet);
             (0, node_fs_1.renameSync)(path, `${path}.approved`);
             recordMemoryAudit(projectDir, "approve", [packet], {
                 from: (0, node_path_1.relative)(projectDir, path),
@@ -16973,9 +17030,9 @@ function approvePending(projectDir, id) {
     throw new Error(`Pending packet not found: ${id}`);
 }
 function rejectPending(projectDir, id) {
-    const pendingFiles = walkFiles(pendingDir(projectDir), (path) => path.endsWith(".json"));
+    const pendingFiles = walkFiles(pendingDir(projectDir), isPacketFile);
     for (const path of pendingFiles) {
-        const packet = readJson(path);
+        const packet = readPacketFromDisk(path);
         if (packet.id === id) {
             const target = `${path}.rejected`;
             (0, node_fs_1.renameSync)(path, target);
@@ -17733,7 +17790,7 @@ function syncIdentityArgs(memoryDir) {
 }
 const SYNC_SETUP_HINT = "Run: kage sync setup --remote <git-url>";
 function syncPacketFile(file) {
-    return file.startsWith("packets/") && file.endsWith(".json");
+    return file.startsWith("packets/") && isPacketFile(file);
 }
 function countSyncPacketFiles(namesOutput) {
     return namesOutput
@@ -17816,7 +17873,7 @@ function rebaseOntoUpstream(memoryDir, upstream) {
         for (const file of conflicted) {
             if (!syncPacketFile(file)) {
                 runSyncGit(memoryDir, ["rebase", "--abort"]);
-                return { ok: false, resolved, conflictBackups, error: `kage sync only auto-resolves packets/*.json conflicts; ${file} needs manual resolution in ${memoryDir}.` };
+                return { ok: false, resolved, conflictBackups, error: `kage sync only auto-resolves packets/*.md conflicts; ${file} needs manual resolution in ${memoryDir}.` };
             }
             const resolution = resolvePacketSyncConflict(memoryDir, file);
             if (!resolution.ok) {

package/dist/okf.js

@@ -0,0 +1,384 @@
+"use strict";
+// Kage <-> Google Open Knowledge Format (OKF) adapter.
+//
+// OKF (github.com/GoogleCloudPlatform/knowledge-catalog/okf) is Kage's standard
+// on-disk interchange format for memory. A Kage memory packet is rendered as an
+// OKF concept document: a Markdown file with YAML frontmatter whose only required
+// field is `type`, plus the recommended `title` / `description` / `resource` /
+// `tags` / `timestamp`. Kage's trust metadata (status, scope, confidence, the
+// content-hash anchors, the lineage) rides along as OKF-legal custom `x-kage-*`
+// frontmatter keys — OKF mandates that consumers preserve unknown producer fields,
+// so a Kage bundle stays fully OKF-conformant and renders in any OKF consumer.
+//
+// Round-trip is lossless: every Kage-authored concept embeds the exact packet as a
+// fenced ```json kage-state block in the body, so packet -> concept -> packet is an
+// identity. Concepts WITHOUT that block (hand-authored or produced by another tool)
+// are imported best-effort from their frontmatter + body, which is what lets Kage
+// consume any third-party OKF bundle.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.okfType = okfType;
+exports.kageType = kageType;
+exports.packetToOkfConcept = packetToOkfConcept;
+exports.okfConceptToPacket = okfConceptToPacket;
+exports.lintOkfConcept = lintOkfConcept;
+exports.okfConceptFileName = okfConceptFileName;
+exports.okfBundleDir = okfBundleDir;
+exports.migratePacketsToOkf = migratePacketsToOkf;
+exports.loadOkfConcepts = loadOkfConcepts;
+exports.lintOkfBundle = lintOkfBundle;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const kernel_js_1 = require("./kernel.js");
+// ---- type vocabulary mapping (Kage snake_case <-> OKF display string) ----
+const TYPE_DISPLAY = {
+    repo_map: "Repo Map",
+    runbook: "Runbook",
+    bug_fix: "Bug Fix",
+    decision: "Decision",
+    rationale: "Rationale",
+    convention: "Convention",
+    workflow: "Workflow",
+    gotcha: "Gotcha",
+    reference: "Reference",
+    policy: "Policy",
+    issue_context: "Issue Context",
+    code_explanation: "Code Explanation",
+    negative_result: "Negative Result",
+    constraint: "Constraint",
+};
+const DISPLAY_TO_TYPE = Object.fromEntries(Object.entries(TYPE_DISPLAY).map(([k, v]) => [v.toLowerCase(), k]));
+function okfType(type) {
+    return TYPE_DISPLAY[type] ?? "Reference";
+}
+function kageType(display) {
+    const key = String(display ?? "").trim().toLowerCase();
+    if (DISPLAY_TO_TYPE[key])
+        return DISPLAY_TO_TYPE[key];
+    if (kernel_js_1.MEMORY_TYPES.includes(key))
+        return key;
+    return "reference";
+}
+// ---- the lossless machine-state block ----
+const STATE_FENCE_OPEN = "```json kage-state";
+const STATE_FENCE_CLOSE = "```";
+function extractKageState(content) {
+    const open = content.indexOf(STATE_FENCE_OPEN);
+    if (open === -1)
+        return null;
+    const start = open + STATE_FENCE_OPEN.length;
+    const close = content.indexOf("\n```", start);
+    if (close === -1)
+        return null;
+    try {
+        const obj = JSON.parse(content.slice(start, close).trim());
+        if (obj && obj.schema_version === kernel_js_1.PACKET_SCHEMA_VERSION && obj.id && obj.title)
+            return obj;
+    }
+    catch {
+        // fall through to best-effort import
+    }
+    return null;
+}
+// ---- small local helpers (kept self-contained; no reliance on kernel internals) ----
+function yamlScalar(value) {
+    // JSON-encoded strings are valid YAML flow scalars and dodge every quoting/colon
+    // edge case, so we never hand-roll YAML escaping.
+    return JSON.stringify(value ?? "");
+}
+function yamlList(items) {
+    return `[${items.map((item) => JSON.stringify(item)).join(", ")}]`;
+}
+function firstHeading(body) {
+    const match = body.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+function stripFirstHeading(body) {
+    return body.replace(/^#\s+.+\n?/, "").trim();
+}
+function summarize(body) {
+    const text = body.replace(/\s+/g, " ").trim();
+    return text.length > 280 ? `${text.slice(0, 277).trimEnd()}…` : text;
+}
+function oneLine(value) {
+    const text = (value ?? "").replace(/\s+/g, " ").trim();
+    return text.length > 120 ? `${text.slice(0, 117)}…` : text;
+}
+function asStringArray(value) {
+    if (Array.isArray(value))
+        return value.map(String);
+    if (typeof value === "string" && value.trim()) {
+        return value.replace(/^\[|\]$/g, "").split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+    }
+    return [];
+}
+function asNumber(value, fallback) {
+    const n = typeof value === "number" ? value : Number.parseFloat(String(value));
+    return Number.isFinite(n) ? n : fallback;
+}
+function ensureDir(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        (0, node_fs_1.mkdirSync)(path, { recursive: true });
+}
+function citationText(ref) {
+    const kind = ref.kind ? String(ref.kind) : "source";
+    const where = ref.path ? ` ${String(ref.path)}` : ref.resource ? ` ${String(ref.resource)}` : "";
+    const at = ref.captured_at ? ` (${String(ref.captured_at)})` : "";
+    return `${kind}${where}${at}`.trim();
+}
+function okfVerifiedStatus(packet) {
+    if (packet.status === "superseded")
+        return "superseded";
+    if (packet.status === "deprecated")
+        return "deprecated";
+    const freshness = packet.freshness;
+    return freshness && freshness.last_verified_at ? "verified" : "unverified";
+}
+// ---- packet -> OKF concept document ----
+function packetToOkfConcept(packet) {
+    const fm = [];
+    fm.push(`type: ${yamlScalar(okfType(packet.type))}`);
+    fm.push(`title: ${yamlScalar(packet.title)}`);
+    fm.push(`description: ${yamlScalar(packet.summary ?? "")}`);
+    const resource = packet.paths?.[0];
+    if (resource)
+        fm.push(`resource: ${yamlScalar(resource)}`);
+    if (packet.tags?.length)
+        fm.push(`tags: ${yamlList(packet.tags)}`);
+    const freshness = packet.freshness;
+    const timestamp = (freshness && freshness.last_verified_at) || packet.updated_at;
+    if (timestamp)
+        fm.push(`timestamp: ${yamlScalar(String(timestamp))}`);
+    // Kage trust extension (OKF-legal arbitrary producer fields).
+    fm.push(`x-kage-id: ${yamlScalar(packet.id)}`);
+    fm.push(`x-kage-type: ${yamlScalar(packet.type)}`);
+    fm.push(`x-kage-status: ${yamlScalar(packet.status)}`);
+    fm.push(`x-kage-scope: ${yamlScalar(packet.scope)}`);
+    fm.push(`x-kage-visibility: ${yamlScalar(packet.visibility)}`);
+    fm.push(`x-kage-confidence: ${packet.confidence}`);
+    fm.push(`x-kage-verified: ${yamlScalar(okfVerifiedStatus(packet))}`);
+    if (packet.paths?.length)
+        fm.push(`x-kage-paths: ${yamlList(packet.paths)}`);
+    if (packet.stack?.length)
+        fm.push(`x-kage-stack: ${yamlList(packet.stack)}`);
+    const body = [];
+    body.push(`# ${packet.title}`, "");
+    if (packet.summary?.trim() && packet.summary.trim() !== packet.body?.trim())
+        body.push(`> ${oneLine(packet.summary)}`, "");
+    if (packet.body?.trim())
+        body.push(packet.body.trim(), "");
+    const ctx = packet.context;
+    if (ctx) {
+        if (ctx.why?.trim())
+            body.push("## Why", "", ctx.why.trim(), "");
+        if (ctx.trigger?.trim())
+            body.push("## Trigger", "", ctx.trigger.trim(), "");
+        if (ctx.action?.trim())
+            body.push("## Action", "", ctx.action.trim(), "");
+        if (ctx.verification?.trim())
+            body.push("## Verification", "", ctx.verification.trim(), "");
+        if (ctx.risk_if_forgotten?.trim())
+            body.push("## Risk if forgotten", "", ctx.risk_if_forgotten.trim(), "");
+        if (ctx.stale_when?.trim())
+            body.push("## Stale when", "", ctx.stale_when.trim(), "");
+        if (ctx.rejected_alternatives?.length) {
+            body.push("## Rejected alternatives", "", ...ctx.rejected_alternatives.map((alt) => `- ${alt}`), "");
+        }
+    }
+    if (packet.source_refs?.length) {
+        body.push("# Citations", "");
+        packet.source_refs.forEach((ref, i) => body.push(`[${i + 1}] ${citationText(ref)}`));
+        body.push("");
+    }
+    body.push("## Kage state", "", "Machine state for lossless round-trip; OKF consumers can ignore it.", "", STATE_FENCE_OPEN, JSON.stringify(packet), STATE_FENCE_CLOSE, "");
+    return `---\n${fm.join("\n")}\n---\n\n${body.join("\n")}\n`;
+}
+// ---- OKF concept document -> packet ----
+function okfConceptToPacket(content, opts = {}) {
+    // A file carrying git conflict markers is not a valid concept — surface it as
+    // unparseable so validation flags it and the repair / merge-driver path (which
+    // parses each side separately) resolves it, rather than silently picking a side.
+    if (/^(?:<{7} |={7}\s*$|>{7} )/m.test(content))
+        return null;
+    // Lossless path: a Kage-authored concept carries its exact packet.
+    const state = extractKageState(content);
+    if (state)
+        return state;
+    // Best-effort import of a foreign / hand-authored OKF concept.
+    const { frontmatter, body } = (0, kernel_js_1.parseFrontmatter)(content);
+    const fm = frontmatter;
+    if (!String(fm.type ?? "").trim() && !firstHeading(body))
+        return null;
+    const projectDir = opts.projectDir ?? ".";
+    const base = opts.sourcePath ? (0, node_path_1.basename)(opts.sourcePath, ".md") : "concept";
+    const type = kageType(fm.type);
+    const title = String(fm.title ?? firstHeading(body) ?? base);
+    const cleanBody = stripFirstHeading(body) || body.trim();
+    const paths = fm["x-kage-paths"]
+        ? asStringArray(fm["x-kage-paths"])
+        : fm.resource
+            ? [String(fm.resource)]
+            : [];
+    const timestamp = fm.timestamp ? String(fm.timestamp) : new Date().toISOString();
+    return {
+        schema_version: kernel_js_1.PACKET_SCHEMA_VERSION,
+        id: fm["x-kage-id"] ? String(fm["x-kage-id"]) : (0, kernel_js_1.makePacketId)(projectDir, type, title, base),
+        title,
+        summary: String(fm.description ?? summarize(cleanBody)),
+        body: cleanBody,
+        type,
+        scope: (String(fm["x-kage-scope"] ?? "repo")),
+        visibility: (String(fm["x-kage-visibility"] ?? "team")),
+        sensitivity: "internal",
+        status: (String(fm["x-kage-status"] ?? "approved")),
+        confidence: asNumber(fm["x-kage-confidence"], 0.7),
+        tags: asStringArray(fm.tags),
+        paths,
+        stack: asStringArray(fm["x-kage-stack"]),
+        source_refs: [
+            { kind: "okf_import", path: opts.sourcePath ? (0, node_path_1.relative)(projectDir, opts.sourcePath) : undefined, resource: fm.resource },
+        ],
+        freshness: { ttl_days: 365, last_verified_at: fm.timestamp ?? null, verification: "okf_import" },
+        edges: [],
+        quality: { reviewer: null, votes_up: 0, votes_down: 0, uses_30d: 0, reports_stale: 0 },
+        created_at: timestamp,
+        updated_at: timestamp,
+    };
+}
+// ---- conformance lint ----
+function lintOkfConcept(content) {
+    const errors = [];
+    if (!content.startsWith("---"))
+        errors.push("missing YAML frontmatter");
+    const { frontmatter } = (0, kernel_js_1.parseFrontmatter)(content);
+    if (!String(frontmatter.type ?? "").trim()) {
+        errors.push("frontmatter missing required non-empty `type`");
+    }
+    return { ok: errors.length === 0, errors };
+}
+// ---- filenames / bundle layout ----
+function okfConceptFileName(packet) {
+    const idHash = (0, node_crypto_1.createHash)("sha256").update(packet.id).digest("hex").slice(0, 8);
+    return `${(0, kernel_js_1.slugify)(packet.title) || "concept"}-${idHash}.md`;
+}
+function okfBundleDir(projectDir) {
+    return (0, node_path_1.join)((0, kernel_js_1.memoryRoot)(projectDir), "okf");
+}
+function titleCaseDir(dir) {
+    return dir.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function buildLog(entries) {
+    const byDate = new Map();
+    for (const entry of entries) {
+        const date = entry.date || "unknown";
+        if (!byDate.has(date))
+            byDate.set(date, []);
+        byDate.get(date).push(entry.line);
+    }
+    const out = ["# Log", ""];
+    for (const date of [...byDate.keys()].sort().reverse()) {
+        out.push(`## ${date}`, "", ...byDate.get(date).map((line) => `- ${line}`), "");
+    }
+    return `${out.join("\n")}\n`;
+}
+function migratePacketsToOkf(projectDir, opts = {}) {
+    const packets = [
+        ...(0, kernel_js_1.loadApprovedPackets)(projectDir),
+        ...(opts.includePending ? (0, kernel_js_1.loadPendingPackets)(projectDir) : []),
+    ];
+    const root = okfBundleDir(projectDir);
+    ensureDir(root);
+    const byType = {};
+    const indexByType = {};
+    const logEntries = [];
+    for (const packet of packets) {
+        const typeDir = (0, kernel_js_1.slugify)(okfType(packet.type));
+        const dir = (0, node_path_1.join)(root, typeDir);
+        ensureDir(dir);
+        const file = okfConceptFileName(packet);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, file), packetToOkfConcept(packet), "utf8");
+        byType[packet.type] = (byType[packet.type] ?? 0) + 1;
+        (indexByType[typeDir] ??= []).push(`- [${packet.title}](/${typeDir}/${file}) — ${oneLine(packet.summary)}`);
+        logEntries.push({
+            date: (packet.updated_at || packet.created_at || "").slice(0, 10),
+            line: `**Update** ${packet.title} (${okfType(packet.type)})`,
+        });
+    }
+    for (const [typeDir, lines] of Object.entries(indexByType)) {
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, typeDir, "index.md"), `# ${titleCaseDir(typeDir)}\n\n${lines.sort().join("\n")}\n`, "utf8");
+    }
+    const rootIndex = [
+        "# Kage knowledge bundle",
+        "",
+        `${packets.length} concepts in Open Knowledge Format (OKF) v0.1, with the Kage trust extension (\`x-kage-*\`).`,
+        "",
+    ];
+    for (const typeDir of Object.keys(indexByType).sort()) {
+        rootIndex.push(`- [${titleCaseDir(typeDir)}](/${typeDir}/index.md) (${indexByType[typeDir].length})`);
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, "index.md"), `${rootIndex.join("\n")}\n`, "utf8");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, "log.md"), buildLog(logEntries), "utf8");
+    return { root, written: packets.length, byType };
+}
+// ---- bundle reader (consume any OKF bundle, ours or a third party's) ----
+function walkMarkdown(root) {
+    const out = [];
+    let entries = [];
+    try {
+        entries = (0, node_fs_1.readdirSync)(root);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        const path = (0, node_path_1.join)(root, name);
+        let stats;
+        try {
+            stats = (0, node_fs_1.statSync)(path);
+        }
+        catch {
+            continue;
+        }
+        if (stats.isDirectory())
+            out.push(...walkMarkdown(path));
+        else if (name.endsWith(".md"))
+            out.push(path);
+    }
+    return out.sort();
+}
+function loadOkfConcepts(dir, opts = {}) {
+    if (!(0, node_fs_1.existsSync)(dir))
+        return [];
+    const out = [];
+    for (const path of walkMarkdown(dir)) {
+        const name = (0, node_path_1.basename)(path);
+        if (name === "index.md" || name === "log.md")
+            continue;
+        try {
+            const packet = okfConceptToPacket((0, node_fs_1.readFileSync)(path, "utf8"), {
+                projectDir: opts.projectDir ?? dir,
+                sourcePath: path,
+            });
+            if (packet)
+                out.push(packet);
+        }
+        catch {
+            // a single malformed concept must not break the whole bundle read
+        }
+    }
+    return out;
+}
+function lintOkfBundle(dir) {
+    const failures = [];
+    let files = 0;
+    for (const path of walkMarkdown(dir)) {
+        const name = (0, node_path_1.basename)(path);
+        if (name === "index.md" || name === "log.md")
+            continue;
+        files += 1;
+        const result = lintOkfConcept((0, node_fs_1.readFileSync)(path, "utf8"));
+        if (!result.ok)
+            failures.push({ path, errors: result.errors });
+    }
+    return { files, failures };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.5.6",
-  "description": "Team memory for coding agents: captures the decisions, runbooks, and bug fixes that get lost, verified against your code and shared via git. MCP server, zero deps, no account.",
+  "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.",
   "main": "dist/index.js",
   "files": [
     "dist/**/*.js",