@cairnkeep/cli 2.13.0 → 2.14.0

package/docs/releasing.md

@@ -12,8 +12,12 @@ from a workstation.
 4. Publish a GitHub Release whose tag is exactly `v<package.json version>`.
 5. The `Publish release` workflow checks out that immutable tag, repeats the
    tests, and publishes `@cairnkeep/cli` with npm provenance.
-6. The workflow attaches the npm tarball, a CycloneDX SBOM, and SHA-256 checksums
-   to the GitHub Release.
+6. The workflow uses the exact locked `@cyclonedx/cyclonedx-npm` development
+   dependency to generate a reproducible CycloneDX 1.6 SBOM from
+   `package-lock.json`. Generation includes schema validation and runs before
+   npm publication, so an invalid document blocks both publication and
+   attachment. The workflow attaches that SBOM, the npm tarball, and SHA-256
+   checksums to the GitHub Release.
 7. The workflow publishes versioned `linux/amd64` and `linux/arm64`
    memory-server and workspace images to GHCR. It also updates `latest` for a
    stable release or `next` for a prerelease.

package/docs/storage.md

@@ -548,3 +548,9 @@ and switch only the named project after exact-digest confirmation.
 It never chooses a pack version or grants a skill approval. `cairn pack remove`
 refuses any referenced digest. Ordinary uninstall retains this directory even
 when memory is removed; `--purge-packs` is the separate backup-first consent.
+
+Imported OKF files live inside the same immutable object. The deterministic
+link index is derived data under `cache/graphs/<pack-digest>.json`; corruption
+or deletion does not affect identity and causes a rebuild from the object. OKF
+exports are not stored automatically: `export-okf --apply` creates a new
+operator-selected directory only after its preview digest is confirmed.

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.13.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.14.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/mcp-memory-server/dist/context-pack-cli.js

@@ -1,12 +1,17 @@
 import { existsSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { resolve } from "node:path";
-import { applyContextPackUpdate, approvePackSkill, contextPackBaseDirectory, disableContextPack, doctorContextPacks, enableContextPack, initializeContextPack, inspectContextPackUpdate, installContextPack, listInstalledContextPacks, listPackSkills, lockContextPack, readProjectPointer, removeContextPack, resolveInstalledPack, revokePackSkill, validateContextPack, } from "./context-pack.js";
+import { applyContextPackUpdate, approvePackSkill, contextPackBaseDirectory, disableContextPack, doctorContextPacks, enableContextPack, initializeContextPack, inspectContextPackUpdate, installContextPack, installOkfContextPack, listInstalledContextPacks, listPackSkills, lockContextPack, readProjectPointer, removeContextPack, resolveInstalledPack, revokePackSkill, validateContextPack, } from "./context-pack.js";
+import { applyOkfExport, planOkfExport, validateOkfBundle } from "./okf.js";
 function usage() {
     process.stderr.write(`Usage:
   cairn pack init [DIRECTORY] [--id ID] [--version VERSION] [--title TITLE] [--description TEXT] [--license LICENSE]
   cairn pack lock|validate [DIRECTORY]
   cairn pack install SOURCE [--ref REF]
+  cairn pack import-okf SOURCE --id ID --version VERSION --license LICENSE [--title TITLE] [--description TEXT] [--ref REF]
+  cairn pack validate-okf [DIRECTORY]
+  cairn pack export-okf --project PATH --output DIRECTORY (--file PATH | --note ID)... --check
+  cairn pack export-okf --project PATH --output DIRECTORY (--file PATH | --note ID)... --apply --confirm DIGEST
   cairn pack list [--json]
   cairn pack show SELECTOR [--json]
   cairn pack remove SELECTOR
@@ -36,6 +41,12 @@ function flag(args, name) {
     args.splice(index, 1);
     return true;
 }
+function takeAll(args, name) {
+    const values = [];
+    while (args.includes(name))
+        values.push(take(args, name));
+    return values;
+}
 function projectOptions(args) {
     const projectRoot = take(args, "--project");
     const projectId = take(args, "--project-id");
@@ -80,6 +91,48 @@ async function main() {
         output({ id: result.pack.manifest.id, version: result.pack.manifest.version, digest: result.pack.digest, source: result.source, existing: result.existing }, json, `${result.existing ? "Already installed" : "Installed"} ${result.pack.manifest.id}@${result.pack.manifest.version} ${result.pack.digest}`);
         return;
     }
+    if (command === "import-okf") {
+        const source = args.shift();
+        if (!source)
+            usage();
+        const id = take(args, "--id");
+        const version = take(args, "--version");
+        const license = take(args, "--license");
+        const title = take(args, "--title");
+        const description = take(args, "--description");
+        const ref = take(args, "--ref");
+        if (!id || !version || !license || args.length)
+            usage();
+        const result = await installOkfContextPack(source, { id, version, license, title, description, ref });
+        const payload = { id: result.pack.manifest.id, version: result.pack.manifest.version, digest: result.pack.digest, source: result.source, existing: result.existing, diagnostics: result.diagnostics };
+        output(payload, json, `${result.existing ? "Already installed" : "Imported"} ${result.pack.manifest.id}@${result.pack.manifest.version} ${result.pack.digest} (${result.diagnostics.length} diagnostics)`);
+        return;
+    }
+    if (command === "validate-okf") {
+        const directory = args.shift() ?? process.cwd();
+        if (args.length)
+            usage();
+        const result = await validateOkfBundle(directory);
+        output(result, json, `Valid Open Knowledge Format ${result.version} bundle: ${result.files.length} files, ${result.diagnostics.length} diagnostics.`);
+        return;
+    }
+    if (command === "export-okf") {
+        const projectRoot = take(args, "--project") ?? process.cwd();
+        const outputDirectory = take(args, "--output");
+        const files = takeAll(args, "--file");
+        const noteIds = takeAll(args, "--note");
+        const check = flag(args, "--check");
+        const apply = flag(args, "--apply");
+        const confirm = take(args, "--confirm");
+        if (!outputDirectory || args.length || check === apply || (apply && !confirm) || (check && confirm))
+            usage();
+        const options = { projectRoot, outputDirectory, files, noteIds };
+        const result = check ? await planOkfExport(options) : await applyOkfExport(options, confirm);
+        output(result, json, check
+            ? `Export preview ${result.confirmation_digest}: ${result.output_files.length} files, ${result.redaction_replacements} redactions. Re-run with --apply --confirm ${result.confirmation_digest}.`
+            : `Exported Open Knowledge Format bundle to ${resolve(outputDirectory)}.`);
+        return;
+    }
     if (command === "list") {
         if (args.length)
             usage();

package/mcp-memory-server/dist/context-pack.js

@@ -7,6 +7,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { promisify } from "node:util";
 import { z } from "zod";
 import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashText } from "./embeddings.js";
+import { indexOkfBundle, validateOkfBundle } from "./okf.js";
 import { atomicReplace, hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
 const execFileAsync = promisify(execFile);
 export const CONTEXT_PACK_MANIFEST = "context-pack.json";
@@ -33,6 +34,10 @@ export const contextPackManifestSchema = z.object({
     title: z.string().min(1).max(256),
     description: z.string().min(1).max(2048),
     license: z.string().min(1).max(128),
+    source_format: z.object({
+        name: z.literal("okf"),
+        version: z.string().min(1).max(32),
+    }).strict().optional(),
     files: z.array(contextPackFileSchema).max(CONTEXT_PACK_MAX_ENTRIES),
 }).strict();
 function sha256(...parts) {
@@ -323,56 +328,114 @@ async function materializeSource(source, ref) {
         throw new Error(`Unable to materialize Git context pack: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-export async function installContextPack(sourcePath, options = {}) {
-    const materialized = await materializeSource(sourcePath, options.ref);
+async function publishContextPack(pack, source) {
+    const destination = objectRoot(pack.digest);
+    if (existsSync(destination)) {
+        const existing = await validateContextPack(destination);
+        if (existing.digest !== pack.digest)
+            throw new Error("Stored context pack object failed verification.");
+        await makeImmutable(destination);
+        await atomicJson(join(packBaseDir(), "sources", `${pack.digest}.json`), { schema_version: 1, source });
+        return { pack: existing, source, existing: true };
+    }
+    const objects = dirname(destination);
+    await mkdir(objects, { recursive: true, mode: 0o700 });
+    const temporary = join(objects, `.${pack.digest}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    let published = true;
     try {
-        const pack = await validateContextPack(materialized.root);
-        const destination = objectRoot(pack.digest);
-        if (existsSync(destination)) {
-            const existing = await validateContextPack(destination);
-            if (existing.digest !== pack.digest)
-                throw new Error("Stored context pack object failed verification.");
-            await makeImmutable(destination);
-            await atomicJson(join(packBaseDir(), "sources", `${pack.digest}.json`), { schema_version: 1, source: materialized.source });
-            return { pack: existing, source: materialized.source, existing: true };
-        }
-        const objects = dirname(destination);
-        await mkdir(objects, { recursive: true, mode: 0o700 });
-        const temporary = join(objects, `.${pack.digest}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
-        let published = true;
+        await cp(pack.root, temporary, { recursive: true, errorOnExist: true, force: false });
+        const copied = await validateContextPack(temporary);
+        if (copied.digest !== pack.digest)
+            throw new Error("Context pack changed during installation.");
+        await makeImmutable(temporary);
         try {
-            await cp(pack.root, temporary, { recursive: true, errorOnExist: true, force: false });
-            const copied = await validateContextPack(temporary);
-            if (copied.digest !== pack.digest)
-                throw new Error("Context pack changed during installation.");
-            await makeImmutable(temporary);
-            try {
-                await rename(temporary, destination);
-            }
-            catch (error) {
-                const code = error.code ?? "";
-                const converged = existsSync(destination)
-                    && (["EEXIST", "ENOTEMPTY"].includes(code) || (process.platform === "win32" && code === "EPERM"));
-                if (!converged)
-                    throw error;
-                const concurrent = await validateContextPack(destination);
-                if (concurrent.digest !== pack.digest)
-                    throw new Error("Concurrent context pack installation produced a conflicting object.");
-                published = false;
-            }
+            await rename(temporary, destination);
         }
-        finally {
-            await makeWritable(temporary).catch(() => undefined);
-            await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+        catch (error) {
+            const code = error.code ?? "";
+            const converged = existsSync(destination)
+                && (["EEXIST", "ENOTEMPTY"].includes(code) || (process.platform === "win32" && code === "EPERM"));
+            if (!converged)
+                throw error;
+            const concurrent = await validateContextPack(destination);
+            if (concurrent.digest !== pack.digest)
+                throw new Error("Concurrent context pack installation produced a conflicting object.");
+            published = false;
         }
-        await atomicJson(join(packBaseDir(), "sources", `${pack.digest}.json`), { schema_version: 1, source: materialized.source });
-        return { pack: await validateContextPack(destination), source: materialized.source, existing: !published };
+    }
+    finally {
+        await makeWritable(temporary).catch(() => undefined);
+        await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+    }
+    await atomicJson(join(packBaseDir(), "sources", `${pack.digest}.json`), { schema_version: 1, source });
+    return { pack: await validateContextPack(destination), source, existing: !published };
+}
+export async function installContextPack(sourcePath, options = {}) {
+    const materialized = await materializeSource(sourcePath, options.ref);
+    try {
+        return await publishContextPack(await validateContextPack(materialized.root), materialized.source);
     }
     finally {
         if (materialized.cleanup)
             await rm(materialized.cleanup, { recursive: true, force: true });
     }
 }
+async function prepareOkfContextPack(sourceRoot, options) {
+    const stagingRoot = await mkdtemp(join(tmpdir(), "cairn-okf-pack-"));
+    const staging = join(stagingRoot, "pack");
+    try {
+        const okf = await validateOkfBundle(sourceRoot);
+        await mkdir(staging, { recursive: true, mode: 0o700 });
+        for (const file of okf.files) {
+            const source = resolve(okf.root, ...file.path.split("/"));
+            const target = resolve(staging, ...file.path.split("/"));
+            if (!contained(okf.root, source) || !contained(staging, target))
+                throw new Error(`Unsafe OKF path: ${file.path}`);
+            await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+            await cp(source, target, { errorOnExist: true, force: false });
+        }
+        const title = options.title?.trim() || okf.files.find(({ path }) => path === "index.md")?.title || options.id;
+        const description = options.description?.trim() || `Imported Open Knowledge Format ${okf.version} bundle.`;
+        const manifest = contextPackManifestSchema.parse({
+            schema_version: 1,
+            id: options.id,
+            version: options.version,
+            title,
+            description,
+            license: options.license,
+            source_format: { name: "okf", version: okf.version },
+            files: okf.files.map((file) => ({
+                path: file.path,
+                kind: "document",
+                title: file.title,
+                description: file.description,
+                keywords: file.keywords,
+                sha256: file.sha256,
+            })),
+        });
+        await writeFile(join(staging, CONTEXT_PACK_MANIFEST), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+        return { pack: await validateContextPack(staging), staging_root: stagingRoot, diagnostics: okf.diagnostics };
+    }
+    catch (error) {
+        await rm(stagingRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function installOkfContextPack(sourcePath, options) {
+    const materialized = await materializeSource(sourcePath, options.ref);
+    let prepared;
+    try {
+        prepared = await prepareOkfContextPack(materialized.root, options);
+        const result = await publishContextPack(prepared.pack, materialized.source);
+        return { ...result, diagnostics: prepared.diagnostics };
+    }
+    finally {
+        if (prepared)
+            await rm(prepared.staging_root, { recursive: true, force: true });
+        if (materialized.cleanup)
+            await rm(materialized.cleanup, { recursive: true, force: true });
+    }
+}
 export async function listInstalledContextPacks() {
     const objects = join(packBaseDir(), "objects");
     if (!existsSync(objects))
@@ -561,6 +624,8 @@ export async function removeContextPack(selector) {
     await makeWritable(root);
     await rm(root, { recursive: true, force: true });
     await rm(join(packBaseDir(), "sources", `${pack.digest}.json`), { force: true });
+    await rm(join(packBaseDir(), "cache", "graphs", `${pack.digest}.json`), { force: true });
+    okfIndexPromises.delete(pack.digest);
     return pack.digest;
 }
 export async function listPackSkills(options) {
@@ -618,6 +683,40 @@ export async function visiblePackFiles(options) {
 function provenance(pack, file) {
     return { pack_id: pack.manifest.id, version: pack.manifest.version, pack_digest: pack.digest, path: file.path, kind: file.kind, file_digest: file.sha256 };
 }
+const okfIndexPromises = new Map();
+async function okfIndex(pack) {
+    const sourceFormat = pack.manifest.source_format;
+    if (sourceFormat?.name !== "okf")
+        return null;
+    let pending = okfIndexPromises.get(pack.digest);
+    if (!pending) {
+        pending = (async () => {
+            const cachePath = join(packBaseDir(), "cache", "graphs", `${pack.digest}.json`);
+            const built = await indexOkfBundle(pack.root, pack.manifest.files.map(({ path }) => path), sourceFormat.version);
+            await atomicJson(cachePath, built).catch(() => undefined);
+            return built;
+        })();
+        okfIndexPromises.set(pack.digest, pending);
+    }
+    return pending;
+}
+async function okfProvenance(pack, file) {
+    const index = await okfIndex(pack);
+    if (!index)
+        return {};
+    const indexed = index.files.find(({ path }) => path === file.path);
+    if (!indexed)
+        return {};
+    return {
+        okf: {
+            version: index.version,
+            role: indexed.role,
+            ...(indexed.concept ?? {}),
+            links: { outbound: indexed.outbound, broken: indexed.broken_links },
+            diagnostics: index.diagnostics.filter(({ path }) => path === file.path),
+        },
+    };
+}
 function utf8Slice(bytes, start, maximum) {
     const requestedStart = Math.min(start, bytes.length);
     let safeStart = requestedStart;
@@ -678,7 +777,7 @@ export async function listVisibleContext(options) {
     const grouped = new Map();
     for (const { pack, file } of files) {
         const row = grouped.get(pack.digest) ?? { pack_id: pack.manifest.id, version: pack.manifest.version, pack_digest: pack.digest, title: pack.manifest.title, files: [] };
-        row.files.push({ ...provenance(pack, file), title: file.title, description: file.description, keywords: file.keywords });
+        row.files.push({ ...provenance(pack, file), ...await okfProvenance(pack, file), title: file.title, description: file.description, keywords: file.keywords });
         grouped.set(pack.digest, row);
     }
     return { schema_version: 1, packs: [...grouped.values()] };
@@ -690,8 +789,9 @@ export async function searchVisibleContext(query, options) {
     const candidates = [];
     for (const { pack, file } of await visiblePackFiles(options)) {
         const text = await readFile(join(pack.root, file.path), "utf8");
+        const okf = await okfProvenance(pack, file);
         for (const chunk of chunks(text)) {
-            candidates.push({ pack, file, offset: chunk.offset, text: chunk.text, searchable: `${file.title}\n${file.description}\n${file.keywords.join(" ")}\n${chunk.text}` });
+            candidates.push({ pack, file, offset: chunk.offset, text: chunk.text, searchable: `${file.title}\n${file.description}\n${file.keywords.join(" ")}\n${chunk.text}`, okf });
         }
     }
     const config = getEmbeddingConfig();
@@ -713,7 +813,7 @@ export async function searchVisibleContext(query, options) {
             });
             cache.save();
             const results = candidates.map((candidate, index) => ({
-                ...provenance(candidate.pack, candidate.file), offset: candidate.offset, text: candidate.text,
+                ...provenance(candidate.pack, candidate.file), ...candidate.okf, offset: candidate.offset, text: candidate.text,
                 score: cosineSimilarity(embedded[0], vectors[index] ?? []),
             })).sort((a, b) => b.score - a.score || a.pack_digest.localeCompare(b.pack_digest, "en") || a.path.localeCompare(b.path, "en") || a.offset - b.offset);
             return { schema_version: 1, query, search_mode: "embedding", results: results.slice(0, options.limit ?? 20) };
@@ -724,7 +824,7 @@ export async function searchVisibleContext(query, options) {
     }
     const results = candidates.flatMap((candidate) => {
         const occurrences = candidate.searchable.toLocaleLowerCase("en").split(normalized).length - 1;
-        return occurrences ? [{ ...provenance(candidate.pack, candidate.file), offset: candidate.offset, text: candidate.text, score: occurrences }] : [];
+        return occurrences ? [{ ...provenance(candidate.pack, candidate.file), ...candidate.okf, offset: candidate.offset, text: candidate.text, score: occurrences }] : [];
     });
     results.sort((a, b) => b.score - a.score || a.pack_digest.localeCompare(b.pack_digest, "en") || a.path.localeCompare(b.path, "en") || a.offset - b.offset);
     return { schema_version: 1, query, search_mode: "substring", results: results.slice(0, options.limit ?? 20) };
@@ -742,14 +842,52 @@ export async function readVisibleContext(packSelector, path, options) {
     if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 8192)
         throw new Error("Invalid context pack read range.");
     const slice = utf8Slice(bytes, offset, maxBytes);
-    return { schema_version: 1, ...provenance(pack, file), offset, text: slice.text, next_offset: offset + slice.bytes < bytes.length ? offset + slice.bytes : null };
+    return { schema_version: 1, ...provenance(pack, file), ...await okfProvenance(pack, file), offset, text: slice.text, next_offset: offset + slice.bytes < bytes.length ? offset + slice.bytes : null };
+}
+export async function relatedVisibleContext(packSelector, path, options) {
+    const normalized = normalizePackPath(path);
+    const visible = await visiblePackFiles(options);
+    const matches = visible.filter(({ pack, file }) => (pack.digest === packSelector || pack.digest.startsWith(packSelector) || pack.manifest.id === packSelector) && file.path === normalized);
+    if (matches.length !== 1)
+        throw new Error(matches.length ? "Context pack selector is ambiguous." : "Context pack file is not enabled or approved.");
+    const { pack, file } = matches[0];
+    const index = await okfIndex(pack);
+    if (!index)
+        throw new Error("Related-document traversal is available only for imported Open Knowledge Format packs.");
+    const source = index.files.find(({ path: candidate }) => candidate === file.path);
+    if (!source)
+        throw new Error("Context pack graph does not contain the requested file.");
+    const direction = options.direction ?? "both";
+    const visiblePaths = new Set(visible.filter(({ pack: candidate }) => candidate.digest === pack.digest).map(({ file: candidate }) => candidate.path));
+    const outbound = new Set(direction === "inbound" ? [] : source.outbound);
+    const inbound = new Set(direction === "outbound" ? [] : index.files.filter(({ outbound: links }) => links.includes(file.path)).map(({ path: candidate }) => candidate));
+    const paths = [...new Set([...outbound, ...inbound])].filter((candidate) => visiblePaths.has(candidate)).sort((a, b) => a.localeCompare(b, "en"));
+    const limit = options.limit ?? 20;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error("Invalid related-document limit.");
+    const results = [];
+    for (const candidatePath of paths.slice(0, limit)) {
+        const candidateFile = pack.manifest.files.find(({ path: declared }) => declared === candidatePath);
+        const relation = outbound.has(candidatePath) && inbound.has(candidatePath) ? "both" : outbound.has(candidatePath) ? "outbound" : "inbound";
+        results.push({ ...provenance(pack, candidateFile), ...await okfProvenance(pack, candidateFile), relation, title: candidateFile.title, description: candidateFile.description, keywords: candidateFile.keywords });
+    }
+    return { schema_version: 1, ...provenance(pack, file), ...await okfProvenance(pack, file), direction, results, diagnostics: index.diagnostics.filter(({ path: diagnosticPath }) => diagnosticPath === file.path) };
 }
 export async function doctorContextPacks() {
     const issues = [];
     const remnants = [];
     let objects = 0;
+    const expectedGraphs = new Map();
     try {
-        objects = (await listInstalledContextPacks()).length;
+        const installed = await listInstalledContextPacks();
+        objects = installed.length;
+        for (const item of installed) {
+            const pack = await validateContextPack(objectRoot(item.digest));
+            if (pack.manifest.source_format?.name === "okf") {
+                const graph = await indexOkfBundle(pack.root, pack.manifest.files.map(({ path }) => path), pack.manifest.source_format.version);
+                expectedGraphs.set(pack.digest, JSON.stringify(graph));
+            }
+        }
     }
     catch (error) {
         issues.push(error instanceof Error ? error.message : String(error));
@@ -790,6 +928,36 @@ export async function doctorContextPacks() {
             }
         }
     }
+    const graphDirectory = join(packBaseDir(), "cache", "graphs");
+    if (existsSync(graphDirectory)) {
+        const directoryInfo = lstatSync(graphDirectory);
+        if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink()) {
+            issues.push("Context pack graph cache directory is unsafe.");
+        }
+        else {
+            for (const entry of await readdir(graphDirectory, { withFileTypes: true })) {
+                const match = /^([a-f0-9]{64})\.json$/.exec(entry.name);
+                const path = join(graphDirectory, entry.name);
+                if (!entry.isFile() || entry.isSymbolicLink() || !match || lstatSync(path).size > CONTEXT_PACK_MAX_FILE_BYTES || !privatePathIsSafe(path)) {
+                    issues.push(`Invalid context pack graph cache entry: ${entry.name}`);
+                    continue;
+                }
+                if (!existsSync(objectRoot(match[1])))
+                    issues.push(`Orphaned context pack graph cache: ${entry.name}`);
+                try {
+                    const cached = JSON.parse(await readFile(path, "utf8"));
+                    if (cached.schema_version !== 1 || !Array.isArray(cached.files) || !Array.isArray(cached.diagnostics))
+                        throw new Error("invalid graph cache schema");
+                    const expected = expectedGraphs.get(match[1]);
+                    if (expected && JSON.stringify(cached) !== expected)
+                        throw new Error("graph cache does not match the immutable object");
+                }
+                catch (error) {
+                    issues.push(`Invalid context pack graph cache: ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+        }
+    }
     const pointers = await allPointers().catch((error) => { issues.push(error instanceof Error ? error.message : String(error)); return []; });
     for (const { path, pointer } of pointers) {
         const packs = new Map();
@@ -825,12 +993,26 @@ export async function inspectContextPackUpdate(selector, options) {
         throw new Error("Context pack is not enabled for this project.");
     const sourceRecord = JSON.parse(await readFile(join(packBaseDir(), "sources", `${enabled.digest}.json`), "utf8"));
     const source = sourceRecord.source;
+    const current = await validateContextPack(objectRoot(enabled.digest));
     const materialized = await materializeSource(source.kind === "local" ? source.path : source.url, source.kind === "git" ? source.ref : undefined);
+    let prepared;
     try {
+        if (current.manifest.source_format?.name === "okf") {
+            prepared = await prepareOkfContextPack(materialized.root, {
+                id: current.manifest.id,
+                version: current.manifest.version,
+                license: current.manifest.license,
+                title: current.manifest.title,
+                description: current.manifest.description,
+            });
+            return { current_digest: enabled.digest, candidate_digest: prepared.pack.digest, changed: prepared.pack.digest !== enabled.digest, source: materialized.source, source_format: "okf" };
+        }
         const candidate = await validateContextPack(materialized.root);
         return { current_digest: enabled.digest, candidate_digest: candidate.digest, changed: candidate.digest !== enabled.digest, source: materialized.source };
     }
     finally {
+        if (prepared)
+            await rm(prepared.staging_root, { recursive: true, force: true });
         if (materialized.cleanup)
             await rm(materialized.cleanup, { recursive: true, force: true });
     }
@@ -839,7 +1021,21 @@ export async function applyContextPackUpdate(selector, confirm, options) {
     const check = await inspectContextPackUpdate(selector, options);
     if (confirm !== check.candidate_digest)
         throw new Error("Update confirmation digest does not match the inspected context pack.");
-    const installed = await installContextPack(check.source.kind === "local" ? check.source.path : check.source.url, check.source.kind === "git" ? { ref: check.source.ref } : {});
+    let installed;
+    if (check.source_format === "okf") {
+        const current = await validateContextPack(objectRoot(check.current_digest));
+        installed = await installOkfContextPack(check.source.kind === "local" ? check.source.path : check.source.url, {
+            id: current.manifest.id,
+            version: current.manifest.version,
+            license: current.manifest.license,
+            title: current.manifest.title,
+            description: current.manifest.description,
+            ...(check.source.kind === "git" ? { ref: check.source.ref } : {}),
+        });
+    }
+    else {
+        installed = await installContextPack(check.source.kind === "local" ? check.source.path : check.source.url, check.source.kind === "git" ? { ref: check.source.ref } : {});
+    }
     if (installed.pack.digest !== confirm)
         throw new Error("Context pack changed after update inspection.");
     const pointer = await enableContextPack(installed.pack.digest, options);

package/mcp-memory-server/dist/index.js

@@ -17,7 +17,7 @@ import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashT
 import { computeRepoState, exploreCacheKey, normalizeExploreQuery, readExploreCache, writeExploreCache, } from "./explore-cache.js";
 import { canonicalTagsSchema, isTypedMemoryNodesEnabled, memoryImportEnvelopeSchema, noteNodeSchema, nodeTypeSchema, } from "./node-schema.js";
 import { attachNodeMetadata, applyReviewedTypedNode, commitMemoryImport, createTypedNode, deleteTypedNode, getTypedNode, invalidateReviewedTypedNode, listTypedHistory, planMemoryImport, supersedeTypedNode, } from "./node-store.js";
-import { contextPackHttpEnabled, contextPacksEnabled, listVisibleContext, readVisibleContext, searchVisibleContext } from "./context-pack.js";
+import { contextPackHttpEnabled, contextPacksEnabled, listVisibleContext, readVisibleContext, relatedVisibleContext, searchVisibleContext } from "./context-pack.js";
 import { metadataForTool } from "./mcp-tool-catalog.js";
 import { profileAllowsTool, resolveMcpToolProfile } from "./mcp-tool-profile.js";
 import { isWorkEvidenceEnabled } from "./work-evidence-schema.js";
@@ -1934,6 +1934,18 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             const payload = await readVisibleContext(pack, path, { ...contextPackProject, offset, maxBytes: max_bytes });
             return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
         });
+        registerTool("context_pack_related", {
+            description: "Traverse deterministic links between documents in an enabled imported Open Knowledge Format pack.",
+            inputSchema: z.object({
+                pack: z.string().min(1).max(128),
+                path: z.string().min(1).max(512),
+                direction: z.enum(["outbound", "inbound", "both"]).optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+            }).strict(),
+        }, async ({ pack, path, direction, limit }) => {
+            const payload = await relatedVisibleContext(pack, path, { ...contextPackProject, direction, limit });
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
     }
     if (workEvidenceToolsEnabled) {
         registerTool("work_evidence_list", {

package/mcp-memory-server/dist/mcp-tool-catalog.js

@@ -35,6 +35,7 @@ export const MCP_TOOL_CATALOG = {
     context_pack_list: observation("List context packs"),
     context_pack_search: observation("Search context packs"),
     context_pack_read: observation("Read context pack file"),
+    context_pack_related: observation("Traverse context pack links"),
     work_evidence_list: observation("List work evidence"),
     work_evidence_read: observation("Read work evidence"),
 };

package/mcp-memory-server/dist/note-store.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
-import { chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { chmodSync, closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { buildFailureSignature } from "./failure-signature.js";
 import { NOTE_SCHEMA_VERSION, noteNodeSchema, } from "./note-schema.js";
 import { memoryImportEnvelopeSchema, nodePathSchema, } from "./node-schema.js";
@@ -229,6 +229,48 @@ function resultFor(notesRoot, entry) {
         ...(note.canonical_id ? { canonical_id: note.canonical_id } : {}),
     };
 }
+export function readSharedNoteForExport(noteId) {
+    if (!noteId || noteId.length > 256)
+        throw new Error("Invalid shared note ID.");
+    const notesRoot = join(baseDirectory(), "notes");
+    const entry = loadManifest(notesRoot).notes[noteId];
+    if (!entry)
+        throw new Error(`Shared note "${noteId}" was not found.`);
+    if (entry.record.node_type !== "shared")
+        throw new Error(`Note "${noteId}" is not a promoted shared note.`);
+    const notesInfo = lstatSync(notesRoot);
+    if (!notesInfo.isDirectory() || notesInfo.isSymbolicLink())
+        throw new Error("Shared note store is unsafe.");
+    const realNotesRoot = realpathSync(notesRoot);
+    const path = resolve(notesRoot, entry.path);
+    const realPath = realpathSync(path);
+    const rel = relative(realNotesRoot, realPath);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`Shared note "${noteId}" has an unsafe path.`);
+    }
+    const info = lstatSync(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 1024 * 1024)
+        throw new Error(`Shared note "${noteId}" is unsafe or too large.`);
+    const bytes = readFileSync(realPath);
+    let content;
+    try {
+        content = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new Error(`Shared note "${noteId}" is not UTF-8.`);
+    }
+    if (Buffer.from(content, "utf8").compare(bytes) !== 0)
+        throw new Error(`Shared note "${noteId}" is not canonical UTF-8.`);
+    return {
+        id: entry.record.id,
+        title: entry.record.title,
+        description: entry.record.description,
+        keywords: entry.record.keywords,
+        tags: entry.record.tags,
+        updated_at: entry.record.updated_at,
+        content,
+    };
+}
 function rebuildLookups(manifest) {
     const lookups = {};
     for (const [id, entry] of Object.entries(manifest.notes)) {