@cairnkeep/cli 2.16.0 → 2.17.0

package/mcp-memory-server/dist/retrieval-benchmark.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { z } from "zod";
+const benchmarkFileSchema = z.object({
+    path: z.string().min(1).regex(/^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$)).+$/),
+    kind: z.enum(["document", "skill"]),
+    title: z.string().min(1),
+    description: z.string(),
+    keywords: z.array(z.string()),
+    content: z.string(),
+}).strict();
+const benchmarkPackSchema = z.object({
+    id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    version: z.string().regex(/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/),
+    title: z.string().min(1),
+    enabled: z.boolean(),
+    files: z.array(benchmarkFileSchema).min(1).max(1_024),
+}).strict();
+const benchmarkCaseSchema = z.object({
+    id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    query: z.string().min(1),
+    relevant: z.array(z.string().min(1)),
+    forbidden: z.array(z.string().min(1)),
+    limit: z.number().int().min(1).max(100),
+}).strict();
+const retrievalBenchmarkSuiteSchema = z.object({
+    schema_version: z.literal(1),
+    id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    description: z.string().min(1),
+    packs: z.array(benchmarkPackSchema).min(1).max(32),
+    cases: z.array(benchmarkCaseSchema).min(1).max(1_024),
+}).strict();
+function assertUnique(values, label) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`Duplicate ${label}`);
+}
+function resultKey(row) {
+    return `${row.pack_id}@${row.version}:${row.path}`;
+}
+function resultIdentity(pack, path) {
+    return `${pack.id}@${pack.version}:${path}`;
+}
+function suiteVisibilityPolicy(suite) {
+    const declared = new Set();
+    const forbidden = new Set();
+    for (const pack of suite.packs) {
+        for (const file of pack.files) {
+            const identity = resultIdentity(pack, file.path);
+            declared.add(identity);
+            if (!pack.enabled || file.kind === "skill")
+                forbidden.add(identity);
+        }
+    }
+    return { declared, forbidden };
+}
+function round(value) {
+    return Number(value.toFixed(6));
+}
+function quantile(values, percentile) {
+    if (values.length === 0)
+        return 0;
+    const ordered = [...values].sort((a, b) => a - b);
+    return ordered[Math.ceil(percentile * ordered.length) - 1] ?? ordered[ordered.length - 1];
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right, "en"))
+            .map(([key, item]) => [key, stable(item)]));
+    }
+    return value;
+}
+function digest(value) {
+    return createHash("sha256").update(JSON.stringify(stable(value))).digest("hex");
+}
+export function parseRetrievalBenchmarkSuite(value) {
+    const suite = retrievalBenchmarkSuiteSchema.parse(value);
+    assertUnique(suite.packs.map(({ id, version }) => `${id}@${version}`), "benchmark pack id and version");
+    assertUnique(suite.cases.map(({ id }) => id), "benchmark case id");
+    for (const pack of suite.packs) {
+        assertUnique(pack.files.map(({ path }) => path), `file path in ${pack.id}@${pack.version}`);
+    }
+    const { declared, forbidden: suiteForbidden } = suiteVisibilityPolicy(suite);
+    for (const benchmarkCase of suite.cases) {
+        assertUnique(benchmarkCase.relevant, `relevant result in ${benchmarkCase.id}`);
+        assertUnique(benchmarkCase.forbidden, `forbidden result in ${benchmarkCase.id}`);
+        if (benchmarkCase.relevant.some((key) => benchmarkCase.forbidden.includes(key))) {
+            throw new Error(`Benchmark case ${benchmarkCase.id} marks a result both relevant and forbidden`);
+        }
+        const forbiddenRelevant = benchmarkCase.relevant.find((key) => suiteForbidden.has(key));
+        if (forbiddenRelevant) {
+            throw new Error(`Benchmark case ${benchmarkCase.id} marks suite-forbidden result ${forbiddenRelevant} as relevant`);
+        }
+        for (const key of [...benchmarkCase.relevant, ...benchmarkCase.forbidden]) {
+            if (!declared.has(key))
+                throw new Error(`Benchmark case ${benchmarkCase.id} references undeclared result ${key}`);
+        }
+    }
+    return suite;
+}
+export function canonicalBenchmarkReport(report) {
+    const { generated_at: _generatedAt, report_digest: _reportDigest, ...rest } = report;
+    return stable({
+        ...rest,
+        cases: rest.cases.map(({ latency_ms: _latency, ...benchmarkCase }) => benchmarkCase),
+        metrics: {
+            ...rest.metrics,
+            median_latency_ms: 0,
+            p95_latency_ms: 0,
+        },
+    });
+}
+export async function evaluateRetrievalBenchmark(suiteValue, adapter) {
+    const suite = parseRetrievalBenchmarkSuite(suiteValue);
+    const clock = adapter.now ?? (() => performance.now());
+    const networkBefore = adapter.networkRequests?.() ?? 0;
+    const mutationsBefore = adapter.filesystemMutations?.() ?? 0;
+    const cases = [];
+    const { declared, forbidden: suiteForbidden } = suiteVisibilityPolicy(suite);
+    for (const benchmarkCase of suite.cases) {
+        const started = clock();
+        const rows = (await adapter.retrieve(benchmarkCase)).slice(0, benchmarkCase.limit);
+        const latency = Math.max(0, clock() - started);
+        const relevant = new Set(benchmarkCase.relevant);
+        const forbidden = new Set([...suiteForbidden, ...benchmarkCase.forbidden]);
+        const returned = rows.map(resultKey);
+        const leakedResults = returned.filter((key) => forbidden.has(key) || !declared.has(key));
+        const undeclaredResults = returned.filter((key) => !declared.has(key)).length;
+        const uniqueTopFive = new Set(returned.slice(0, 5).filter((key) => relevant.has(key)));
+        const firstRelevant = returned.findIndex((key) => relevant.has(key));
+        let relevantBytes = 0;
+        let irrelevantBytes = 0;
+        for (const [index, row] of rows.entries()) {
+            const bytes = Buffer.byteLength(row.text, "utf8");
+            if (relevant.has(returned[index]))
+                relevantBytes += bytes;
+            else
+                irrelevantBytes += bytes;
+        }
+        cases.push({
+            id: benchmarkCase.id,
+            query: benchmarkCase.query,
+            relevant: [...benchmarkCase.relevant],
+            forbidden: [...forbidden].sort((left, right) => left.localeCompare(right, "en")),
+            returned,
+            leaked_results: leakedResults,
+            isolation_case: relevant.size === 0,
+            isolation_pass: leakedResults.length === 0,
+            hit_at_1: returned[0] && relevant.has(returned[0]) ? 1 : 0,
+            recall_at_5: relevant.size ? round(uniqueTopFive.size / relevant.size) : 0,
+            reciprocal_rank: firstRelevant < 0 ? 0 : round(1 / (firstRelevant + 1)),
+            relevant_bytes: relevantBytes,
+            irrelevant_bytes: irrelevantBytes,
+            estimated_context_tokens: Math.ceil((relevantBytes + irrelevantBytes) / 4),
+            forbidden_results: leakedResults.length,
+            undeclared_results: undeclaredResults,
+            latency_ms: round(latency),
+        });
+    }
+    const count = cases.length;
+    const sum = (field) => cases.reduce((total, item) => total + Number(item[field]), 0);
+    const positiveCases = cases.filter(({ isolation_case }) => !isolation_case);
+    const negativeCases = cases.filter(({ isolation_case }) => isolation_case);
+    const sumPositive = (field) => positiveCases.reduce((total, item) => total + item[field], 0);
+    const negativeCasesPassed = negativeCases.filter(({ isolation_pass }) => isolation_pass).length;
+    const negativeCaseLeaks = negativeCases.reduce((total, item) => total + item.forbidden_results, 0);
+    const report = {
+        schema_version: 1,
+        benchmark_id: suite.id,
+        mode: adapter.mode,
+        generated_at: new Date().toISOString(),
+        cases,
+        metrics: {
+            cases: count,
+            positive_cases: positiveCases.length,
+            negative_cases: negativeCases.length,
+            negative_cases_passed: negativeCasesPassed,
+            negative_case_pass_rate: negativeCases.length ? round(negativeCasesPassed / negativeCases.length) : 1,
+            negative_case_leaks: negativeCaseLeaks,
+            hit_at_1: positiveCases.length ? round(sumPositive("hit_at_1") / positiveCases.length) : 0,
+            recall_at_5: positiveCases.length ? round(sumPositive("recall_at_5") / positiveCases.length) : 0,
+            mean_reciprocal_rank: positiveCases.length ? round(sumPositive("reciprocal_rank") / positiveCases.length) : 0,
+            relevant_bytes: sum("relevant_bytes"),
+            irrelevant_bytes: sum("irrelevant_bytes"),
+            estimated_context_tokens: sum("estimated_context_tokens"),
+            median_latency_ms: round(quantile(cases.map(({ latency_ms }) => latency_ms), 0.5)),
+            p95_latency_ms: round(quantile(cases.map(({ latency_ms }) => latency_ms), 0.95)),
+            network_requests: Math.max(0, (adapter.networkRequests?.() ?? networkBefore) - networkBefore),
+            filesystem_mutations: Math.max(0, (adapter.filesystemMutations?.() ?? mutationsBefore) - mutationsBefore),
+            forbidden_results: sum("forbidden_results"),
+            undeclared_results: sum("undeclared_results"),
+        },
+        report_digest: "",
+    };
+    report.report_digest = digest(canonicalBenchmarkReport(report));
+    return report;
+}

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

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { AgentFS } from "agentfs-sdk";
+import { z } from "zod";
+import { hashText } from "./embeddings.js";
+import { applyReviewedTypedNode, invalidateReviewedTypedNode } from "./node-store.js";
+import { assertMemoryProposalCandidateConsistency, digestText, expectedMemoryProposalOperation, } from "./memory-proposal-schema.js";
+export const HISTORY_NAMESPACE = "__history__";
+export const REVIEWED_NAMESPACE = "__reviewed__";
+export const REVIEW_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const SCOPE_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const reviewedRecordSchema = z.object({
+    schema_version: z.literal(1),
+    review_id: z.string(),
+    key: z.string(),
+    value_hash: z.string(),
+    state: z.enum(["active", "superseded", "invalidated"]),
+    applied_at: z.string(),
+    superseded_at: z.string().optional(),
+    superseded_by: z.string().optional(),
+    invalidated_at: z.string().optional(),
+    invalidation_reason: z.string().optional(),
+}).strict();
+function expandHome(value) {
+    if (value === "~")
+        return homedir();
+    return value.startsWith("~/") ? join(homedir(), value.slice(2)) : value;
+}
+function baseDir() {
+    return resolve(expandHome(process.env.CAIRN_AGENTFS_BASE_DIR ?? "~/.cairnkeep"));
+}
+export function resolveMemoryScopePath(scope, options = {}) {
+    if (scope === "project") {
+        return options.projectId
+            ? resolve(baseDir(), "projects", `${options.projectId}.db`)
+            : resolve(options.cwd ?? process.cwd(), ".agentfs", "project.db");
+    }
+    if (scope === "all")
+        throw new Error('Scope "all" is read-only; choose one concrete scope.');
+    if (!SCOPE_PATTERN.test(scope))
+        throw new Error(`Invalid scope "${scope}": must be a concrete kebab-case scope or "project".`);
+    const root = baseDir();
+    const dbPath = resolve(root, `${scope}.db`);
+    const rel = relative(root, dbPath);
+    if (!rel || rel.startsWith("..") || isAbsolute(rel))
+        throw new Error(`Invalid scope "${scope}": resolves outside the base directory.`);
+    return dbPath;
+}
+async function openMemoryScope(scope, create, options = {}) {
+    const path = resolveMemoryScopePath(scope, options);
+    if (!create && !existsSync(path))
+        return null;
+    if (create)
+        mkdirSync(dirname(path), { recursive: true });
+    return AgentFS.open({ id: scope, path });
+}
+function normalizeValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined || value === null)
+        return "";
+    return JSON.stringify(value);
+}
+export function assertWritableMemoryKey(key) {
+    if (key === HISTORY_NAMESPACE || key.startsWith(`${HISTORY_NAMESPACE}/`)
+        || key === REVIEWED_NAMESPACE || key.startsWith(`${REVIEWED_NAMESPACE}/`)) {
+        throw new Error(`Keys under ${HISTORY_NAMESPACE}/ and ${REVIEWED_NAMESPACE}/ are reserved.`);
+    }
+}
+function historySnapshotKey(key, timestamp) {
+    return `${HISTORY_NAMESPACE}/${key}/${timestamp}-${randomUUID()}`;
+}
+function recordKey(reviewId) {
+    return `${REVIEWED_NAMESPACE}/${reviewId}`;
+}
+function parseRecord(value) {
+    const parsed = reviewedRecordSchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error("Stored reviewed-memory provenance is invalid; refusing to continue.");
+    return parsed.data;
+}
+async function immediate(agent, operation) {
+    const transaction = agent.getDatabase().transaction(operation);
+    const run = transaction.immediate;
+    return run();
+}
+async function supersedeActiveRecord(agent, key, reviewId, at) {
+    for (const entry of await agent.kv.list(`${REVIEWED_NAMESPACE}/`)) {
+        const prior = parseRecord(entry.value);
+        if (prior.state === "active" && prior.key === key && prior.review_id !== reviewId) {
+            await agent.kv.set(entry.key, { ...prior, state: "superseded", superseded_at: at, superseded_by: reviewId });
+        }
+    }
+}
+async function writeReviewed(agent, scope, reviewId, key, value, typed, appliedAt) {
+    await supersedeActiveRecord(agent, key, reviewId, appliedAt);
+    let snapshotKey = null;
+    if (typed) {
+        const changed = await applyReviewedTypedNode({
+            agent, scope, review_id: reviewId, key, value, node_type: "memory", tags: [], in_transaction: true,
+        });
+        snapshotKey = changed.snapshot_key;
+    }
+    else {
+        const previous = await agent.kv.get(key);
+        const previousValue = previous === undefined ? undefined : normalizeValue(previous);
+        if (previousValue !== undefined && previousValue !== value) {
+            snapshotKey = historySnapshotKey(key, appliedAt);
+            await agent.kv.set(snapshotKey, {
+                value: previousValue,
+                superseded_at: appliedAt,
+                superseded_reason: `reviewed memory ${reviewId}`,
+            });
+        }
+        await agent.kv.set(key, value);
+    }
+    await agent.kv.set(recordKey(reviewId), {
+        schema_version: 1,
+        review_id: reviewId,
+        key,
+        value_hash: hashText(value),
+        state: "active",
+        applied_at: appliedAt,
+    });
+    return snapshotKey;
+}
+export async function applyReviewedMemory(scope, reviewId, key, value, options = {}) {
+    assertWritableMemoryKey(key);
+    if (!REVIEW_ID_PATTERN.test(reviewId))
+        throw new Error("Invalid review id.");
+    const agent = await openMemoryScope(scope, true, options);
+    if (!agent)
+        throw new Error(`Unable to open scope ${scope}.`);
+    try {
+        return await immediate(agent, async () => {
+            const stored = await agent.kv.get(recordKey(reviewId));
+            const valueHash = hashText(value);
+            if (stored !== undefined) {
+                const existing = parseRecord(stored);
+                if (existing.key !== key || existing.value_hash !== valueHash)
+                    throw new Error(`Review id ${reviewId} was already used with different content.`);
+                if (existing.state !== "active")
+                    throw new Error(`Review id ${reviewId} is ${existing.state} and cannot be reapplied.`);
+                return { ok: true, scope, review_id: reviewId, key, applied: false, idempotent: true, snapshot_key: null };
+            }
+            const snapshotKey = await writeReviewed(agent, scope, reviewId, key, value, options.typed ?? false, new Date().toISOString());
+            return { ok: true, scope, review_id: reviewId, key, applied: true, idempotent: false, snapshot_key: snapshotKey };
+        });
+    }
+    finally {
+        await agent.close();
+    }
+}
+export async function invalidateReviewedMemory(scope, reviewId, key, reason, options = {}) {
+    assertWritableMemoryKey(key);
+    const agent = await openMemoryScope(scope, true, options);
+    if (!agent)
+        throw new Error(`Unable to open scope ${scope}.`);
+    try {
+        return await immediate(agent, async () => {
+            const keyForRecord = recordKey(reviewId);
+            const stored = await agent.kv.get(keyForRecord);
+            if (stored === undefined) {
+                const at = new Date().toISOString();
+                await agent.kv.set(keyForRecord, { schema_version: 1, review_id: reviewId, key, value_hash: "", state: "invalidated", applied_at: at, invalidated_at: at, ...(reason ? { invalidation_reason: reason } : {}) });
+                return { ok: true, scope, review_id: reviewId, key, invalidated: true, idempotent: false, missing: true, removed: false, current_changed: false, snapshot_key: null };
+            }
+            const record = parseRecord(stored);
+            if (record.key !== key)
+                throw new Error(`Review id ${reviewId} belongs to a different memory key.`);
+            if (record.state === "invalidated")
+                return { ok: true, scope, review_id: reviewId, key: record.key, invalidated: false, idempotent: true, missing: record.value_hash === "", removed: false, current_changed: false, snapshot_key: null };
+            const at = new Date().toISOString();
+            let currentChanged = false;
+            let removed = false;
+            let snapshotKey = null;
+            if (record.state === "active") {
+                const current = await agent.kv.get(record.key);
+                if (current !== undefined) {
+                    const currentValue = normalizeValue(current);
+                    if (hashText(currentValue) === record.value_hash) {
+                        if (options.typed) {
+                            const changed = await invalidateReviewedTypedNode({ agent, scope, review_id: reviewId, key: record.key, reason, in_transaction: true });
+                            snapshotKey = changed.snapshot_key;
+                        }
+                        else {
+                            snapshotKey = historySnapshotKey(record.key, at);
+                            await agent.kv.set(snapshotKey, { value: currentValue, superseded_at: at, superseded_reason: reason ?? `reviewed memory ${reviewId} invalidated` });
+                            await agent.kv.delete(record.key);
+                        }
+                        removed = true;
+                    }
+                    else
+                        currentChanged = true;
+                }
+            }
+            await agent.kv.set(keyForRecord, { ...record, state: "invalidated", invalidated_at: at, ...(reason ? { invalidation_reason: reason } : {}) });
+            return { ok: true, scope, review_id: reviewId, key: record.key, invalidated: true, idempotent: false, missing: false, removed, current_changed: currentChanged, snapshot_key: snapshotKey };
+        });
+    }
+    finally {
+        await agent.close();
+    }
+}
+export async function readMemoryBaseHashes(scope, keys, options = {}) {
+    const agent = await openMemoryScope(scope, false, options);
+    const result = new Map();
+    try {
+        for (const key of keys) {
+            assertWritableMemoryKey(key);
+            const raw = agent ? await agent.kv.get(key) : undefined;
+            const value = raw === undefined ? null : normalizeValue(raw);
+            result.set(key, { value, hash: value === null ? null : digestText(value) });
+        }
+        return result;
+    }
+    finally {
+        if (agent)
+            await agent.close();
+    }
+}
+function proposalReviewId(digest, index) {
+    return `mp:${digest}:${index}`;
+}
+export async function applyProposalCandidates(scope, proposalDigest, candidates, options = {}) {
+    for (const candidate of candidates)
+        assertMemoryProposalCandidateConsistency(candidate);
+    const agent = await openMemoryScope(scope, true, options);
+    if (!agent)
+        throw new Error(`Unable to open scope ${scope}.`);
+    try {
+        return await immediate(agent, async () => {
+            const existing = [];
+            for (let index = 0; index < candidates.length; index += 1) {
+                const candidate = candidates[index];
+                assertWritableMemoryKey(candidate.key);
+                const stored = await agent.kv.get(recordKey(proposalReviewId(proposalDigest, index)));
+                existing.push(stored === undefined ? null : parseRecord(stored));
+            }
+            if (existing.every((record) => record !== null)) {
+                for (let index = 0; index < candidates.length; index += 1) {
+                    const record = existing[index];
+                    const candidate = candidates[index];
+                    const current = await agent.kv.get(candidate.key);
+                    if (record.state !== "active" || record.key !== candidate.key || record.value_hash !== hashText(candidate.value)
+                        || current === undefined || digestText(normalizeValue(current)) !== candidate.value_hash) {
+                        throw new Error("Proposal replay does not match current reviewed memory state.");
+                    }
+                }
+                return { ok: true, scope, proposal_digest: proposalDigest, applied: false, idempotent: true, count: candidates.length, results: [] };
+            }
+            if (existing.some((record) => record !== null))
+                throw new Error("Proposal has partial reviewed provenance; refusing a non-atomic replay.");
+            for (const candidate of candidates) {
+                const current = await agent.kv.get(candidate.key);
+                const currentValue = current === undefined ? null : normalizeValue(current);
+                const currentHash = currentValue === null ? null : digestText(currentValue);
+                if (currentHash !== candidate.base_hash)
+                    throw new Error(`Memory proposal is stale at key "${candidate.key}".`);
+                const expectedOperation = expectedMemoryProposalOperation(currentHash, candidate.value_hash);
+                if (candidate.operation !== expectedOperation) {
+                    throw new Error(`Memory proposal operation is inconsistent at key "${candidate.key}".`);
+                }
+            }
+            const at = new Date().toISOString();
+            const results = [];
+            for (let index = 0; index < candidates.length; index += 1) {
+                const candidate = candidates[index];
+                const reviewId = proposalReviewId(proposalDigest, index);
+                const snapshotKey = await writeReviewed(agent, scope, reviewId, candidate.key, candidate.value, options.typed ?? false, at);
+                results.push({ key: candidate.key, operation: candidate.operation, review_id: reviewId, snapshot_key: snapshotKey });
+            }
+            return { ok: true, scope, proposal_digest: proposalDigest, applied: true, idempotent: false, count: candidates.length, results };
+        });
+    }
+    finally {
+        await agent.close();
+    }
+}

package/mcp-memory-server/dist/work-evidence-schema.js

@@ -63,6 +63,12 @@ export const completeWorkEvidenceSchema = z.object({
     change_digest: digestSchema,
     patch: workEvidencePatchSchema,
 }).strict();
+export const CONTEXT_USAGE_OUTCOMES = ["used", "unused", "unknown"];
+export const contextUsageReceiptInputSchema = z.object({
+    task_digest: digestSchema,
+    result_digest: digestSchema,
+    outcome: z.enum(CONTEXT_USAGE_OUTCOMES),
+}).strict();
 export const workEvidenceLinkSchema = z.discriminatedUnion("kind", [
     z.object({
         schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
@@ -90,6 +96,17 @@ export const workEvidenceLinkSchema = z.discriminatedUnion("kind", [
         review_id: safeRefSchema,
         key: safeRefSchema,
     }).strict(),
+    z.object({
+        schema_version: z.literal(WORK_EVIDENCE_SCHEMA_VERSION),
+        link_id: digestSchema,
+        evidence_id: workEvidenceIdSchema,
+        kind: z.literal("context_usage"),
+        created_at: z.iso.datetime(),
+        receipt_id: digestSchema,
+        task_digest: digestSchema,
+        result_digest: digestSchema,
+        outcome: z.enum(CONTEXT_USAGE_OUTCOMES),
+    }).strict(),
 ]);
 export const storedWorkEvidenceSchema = z.discriminatedUnion("status", [pendingWorkEvidenceSchema, completeWorkEvidenceSchema]);
 function truthy(value) {

package/mcp-memory-server/dist/work-evidence-store.js

@@ -5,7 +5,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { getArtifactLimits, isArtifactStoreEnabled } from "./artifact-schema.js";
 import { putArtifact } from "./artifact-store.js";
 import { hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
-import { WORK_EVIDENCE_SCHEMA_VERSION, completeWorkEvidenceSchema, getWorkEvidenceLimits, isWorkEvidenceEnabled, isWorkEvidencePatchEnabled, pendingWorkEvidenceSchema, storedWorkEvidenceSchema, workEvidenceIdSchema, workEvidenceLinkSchema, } from "./work-evidence-schema.js";
+import { WORK_EVIDENCE_SCHEMA_VERSION, completeWorkEvidenceSchema, contextUsageReceiptInputSchema, getWorkEvidenceLimits, isWorkEvidenceEnabled, isWorkEvidencePatchEnabled, pendingWorkEvidenceSchema, storedWorkEvidenceSchema, workEvidenceIdSchema, workEvidenceLinkSchema, } from "./work-evidence-schema.js";
 const MAX_RECORD_BYTES = 1024 * 1024;
 const STALE_PENDING_MS = 24 * 60 * 60 * 1000;
 const EMPTY_DIGEST = createHash("sha256").update("").digest("hex");
@@ -22,6 +22,13 @@ function canonical(value) {
     }
     return JSON.stringify(value);
 }
+function contextUsageReceiptId(evidenceId, value) {
+    return sha256(canonical({
+        evidence_id: evidenceId,
+        task_digest: value.task_digest,
+        result_digest: value.result_digest,
+    }));
+}
 function storeRoot(projectRoot) {
     return resolve(projectRoot, ".agentfs", "work-evidence", "v1");
 }
@@ -350,6 +357,48 @@ export async function linkActiveWorkEvidence(projectRoot, value) {
         return null;
     }
 }
+export async function appendContextUsageReceipt(projectRoot, evidenceId, value, now = new Date()) {
+    if (!isWorkEvidenceEnabled())
+        return null;
+    const id = workEvidenceIdSchema.parse(evidenceId);
+    const input = contextUsageReceiptInputSchema.parse(value);
+    const root = resolve(projectRoot);
+    if (!ensureStoreHierarchy(root, false) || !existsSync(recordPath(root, id))) {
+        throw new Error(`Work evidence "${id}" not found.`);
+    }
+    readStored(id, root);
+    const receiptId = contextUsageReceiptId(id, input);
+    const link = workEvidenceLinkSchema.parse({
+        schema_version: WORK_EVIDENCE_SCHEMA_VERSION,
+        link_id: receiptId,
+        evidence_id: id,
+        kind: "context_usage",
+        created_at: now.toISOString(),
+        receipt_id: receiptId,
+        ...input,
+    });
+    const path = join(linksRoot(root, id), `${receiptId}.json`);
+    if (existsSync(path)) {
+        const stored = workEvidenceLinkSchema.parse(readJson(path));
+        if (stored.kind !== "context_usage"
+            || stored.receipt_id !== receiptId
+            || stored.task_digest !== input.task_digest
+            || stored.result_digest !== input.result_digest
+            || stored.outcome !== input.outcome) {
+            throw new Error(`Conflicting context usage outcome for receipt "${receiptId}".`);
+        }
+        return stored;
+    }
+    atomicJson(path, link);
+    return link;
+}
+export async function linkActiveContextUsageReceipt(projectRoot, value) {
+    const evidenceId = process.env.CAIRN_WORK_EVIDENCE_ID?.trim();
+    if (!evidenceId || !isWorkEvidenceEnabled())
+        return null;
+    const root = process.env.CAIRN_WORK_EVIDENCE_ROOT?.trim() || projectRoot;
+    return appendContextUsageReceipt(resolve(root), evidenceId, value);
+}
 function storedWorkEvidenceRows(projectRoot, status) {
     if (!ensureStoreHierarchy(projectRoot, false))
         return [];
@@ -483,6 +532,13 @@ export function doctorWorkEvidence(projectRoot = process.cwd(), repair = false)
                         const link = workEvidenceLinkSchema.parse(readJson(path));
                         if (link.evidence_id !== evidenceId || `${link.link_id}.json` !== name)
                             throw new Error("mismatch");
+                        if (link.kind === "context_usage") {
+                            const expected = contextUsageReceiptId(evidenceId, link);
+                            if (!existsSync(recordPath(projectRoot, evidenceId))
+                                || link.receipt_id !== expected
+                                || link.link_id !== expected)
+                                throw new Error("invalid context usage receipt identity");
+                        }
                         links += 1;
                     }
                     catch {

package/mcp-memory-server/package.json

@@ -23,6 +23,7 @@
         "check:explore-crossref": "node scripts/smoke-explore-crossref.mjs",
         "check:route-guard": "node scripts/smoke-route-guard.mjs",
         "check:reviewed-memory": "node scripts/smoke-reviewed-memory.mjs",
+        "check:memory-proposals": "node scripts/smoke-memory-proposals.mjs",
         "check:trajectory-roundtrip": "node scripts/smoke-trajectory-roundtrip.mjs",
         "check:trajectory-redaction": "node scripts/smoke-trajectory-redaction.mjs",
         "check:trajectory-retention": "node scripts/smoke-trajectory-retention.mjs",
@@ -49,12 +50,18 @@
         "check:mcp-trust": "node scripts/smoke-mcp-trust.mjs",
         "check:pi-mcp-bridge": "node scripts/smoke-pi-mcp-bridge.mjs",
         "check:context-pack": "node scripts/smoke-context-pack.mjs",
+        "check:context-pack-retrieval": "node scripts/smoke-context-pack-retrieval.mjs",
+        "check:context-pack-v216-compat": "node scripts/smoke-context-pack-v216-compat.mjs",
+        "check:context-usage": "node scripts/smoke-context-usage.mjs",
+        "check:domain-retrieval": "node scripts/smoke-domain-retrieval.mjs",
+        "check:retrieval-benchmark": "node scripts/smoke-retrieval-benchmark.mjs && node scripts/run-retrieval-benchmark.mjs --check",
+        "benchmark:retrieval": "npm run build && node scripts/run-retrieval-benchmark.mjs",
         "check:work-evidence": "node scripts/smoke-work-evidence.mjs",
         "check:okf": "node scripts/smoke-okf.mjs",
         "check:playbook": "node scripts/smoke-playbook.mjs",
         "check:notes": "npm run build && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment",
         "test": "npm run test:smoke",
-        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:context-pack && npm run check:work-evidence && npm run check:okf && npm run check:playbook",
+        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:memory-proposals && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:context-pack && npm run check:context-pack-retrieval && npm run check:context-pack-v216-compat && npm run check:context-usage && npm run check:domain-retrieval && npm run check:retrieval-benchmark && npm run check:work-evidence && npm run check:okf && npm run check:playbook",
         "test:search": "npm run build && npm run check:search",
         "test:memory": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:search",
         "test:all": "npm run test:memory"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",