@cairnkeep/cli 2.16.0 → 2.17.0

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

@@ -14,13 +14,16 @@ import { z } from "zod";
 import { artifactIdSchema, artifactKindSchema, artifactMediaTypeSchema, artifactNodeRefSchema, artifactProvenanceSchema, artifactSessionRefSchema, compactionSummaryInputContentSchema, diffContentSchema, generatedFileInputContentSchema, isArtifactHttpEnabled, isArtifactStoreEnabled, testOutputContentSchema, } from "./artifact-schema.js";
 import { isCapabilityContractEnabled, resolveCapabilityStatus, } from "./capability-config.js";
 import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashText, } from "./embeddings.js";
+import { queryDomainKnowledge, resolveDomainRetrievalProvider } from "./domain-retrieval-provider.js";
 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, relatedVisibleContext, searchVisibleContext } from "./context-pack.js";
+import { attachNodeMetadata, commitMemoryImport, createTypedNode, deleteTypedNode, getTypedNode, listTypedHistory, planMemoryImport, supersedeTypedNode, } from "./node-store.js";
+import { contextPackHttpEnabled, contextPacksEnabled, listVisibleContext, readVisibleContext, relatedVisibleContext, searchVisibleContext, treeVisibleContext } 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";
+import { extractMemoryCandidates as extractMemoryCandidatesFromProvider } from "./memory-extraction.js";
+import { applyReviewedMemory, invalidateReviewedMemory } from "./reviewed-memory-store.js";
 const MINIMUM_NODE_MAJOR = 22;
 const nodeMajor = Number.parseInt(process.versions.node, 10);
 if (!Number.isInteger(nodeMajor) || nodeMajor < MINIMUM_NODE_MAJOR) {
@@ -223,33 +226,6 @@ function historyPrefix(baseKey) {
 function historySnapshotKey(baseKey, timestamp) {
     return `${historyPrefix(baseKey)}${timestamp}-${randomUUID()}`;
 }
-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(),
-});
-function reviewedRecordKey(reviewId) {
-    return `${REVIEWED_NAMESPACE}/${reviewId}`;
-}
-function parseReviewedRecord(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 inImmediateScopeTransaction(agent, operation) {
-    const transaction = agent.getDatabase().transaction(operation);
-    const immediate = transaction.immediate;
-    return immediate();
-}
 function visibleEntries(entries, includeHistory) {
     if (includeHistory) {
         return entries;
@@ -340,113 +316,6 @@ function truncateOutput(value, maxLength = 12000) {
     }
     return `${value.slice(0, maxLength)}\n...[truncated ${value.length - maxLength} chars]`;
 }
-function stripMarkdownFences(value) {
-    return value
-        .trim()
-        .replace(/^```(?:json)?\s*/i, "")
-        .replace(/\s*```$/, "")
-        .trim();
-}
-function parseJsonResponse(value) {
-    const stripped = stripMarkdownFences(value);
-    try {
-        return JSON.parse(stripped);
-    }
-    catch {
-        const firstBrace = stripped.indexOf("{");
-        const lastBrace = stripped.lastIndexOf("}");
-        if (firstBrace !== -1 && lastBrace > firstBrace) {
-            return JSON.parse(stripped.slice(firstBrace, lastBrace + 1));
-        }
-        throw new Error(`Failed to parse JSON response: ${truncateOutput(stripped, 1000)}`);
-    }
-}
-function sanitizeExtractionCandidates(value, fallbackCategory) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value
-        .map((item) => {
-        if (!item || typeof item !== "object") {
-            return null;
-        }
-        const raw = item;
-        const key = typeof raw.key === "string" ? raw.key.trim() : "";
-        const candidateValue = typeof raw.value === "string" ? raw.value.trim() : "";
-        if (!key || !candidateValue) {
-            return null;
-        }
-        const category = typeof raw.category === "string" && raw.category.trim()
-            ? raw.category.trim()
-            : fallbackCategory;
-        const importance = typeof raw.importance === "number"
-            ? Math.max(0, Math.min(1, raw.importance))
-            : undefined;
-        return {
-            key,
-            value: candidateValue,
-            category,
-            importance,
-        };
-    })
-        .filter((candidate) => candidate !== null);
-}
-async function extractMemoryCandidates(content, modelOverride, category) {
-    const apiKey = process.env.CAIRN_LLM_API_KEY;
-    if (!apiKey) {
-        throw new Error("CAIRN_LLM_API_KEY is not set.");
-    }
-    const rawUrl = process.env.CAIRN_LLM_API_URL;
-    if (!rawUrl) {
-        throw new Error("CAIRN_LLM_API_URL is not set.");
-    }
-    const apiUrl = rawUrl.trim().replace(/\/+$/, "");
-    const model = (modelOverride ?? process.env.CAIRN_LLM_EXTRACTION_MODEL)?.trim();
-    if (!model) {
-        throw new Error("CAIRN_LLM_EXTRACTION_MODEL is not set.");
-    }
-    const systemPrompt = [
-        "You extract durable memory candidates from development notes.",
-        "Return ONLY valid JSON, no markdown fences.",
-        "Schema: {\"candidates\":[{\"key\":\"decisions/cache-rule\",\"value\":\"...\",\"category\":\"decision\",\"importance\":0.92}]}",
-        "Only include genuinely reusable knowledge.",
-        "Skip trivial status notes, temporary branch details, and duplicated points.",
-        "Prefer short kebab-case keys with a useful prefix such as decisions/, pitfalls/, patterns/, bugs/, constraints/, preferences/, conventions/.",
-        "Do not invent dates unless they are explicitly present in the source text.",
-        category ? `Bias extraction toward category: ${category}.` : "",
-    ].filter(Boolean).join(" ");
-    const response = await fetch(`${apiUrl}/chat/completions`, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-            model,
-            messages: [
-                { role: "system", content: systemPrompt },
-                { role: "user", content },
-            ],
-            temperature: 0.1,
-            max_tokens: 1200,
-        }),
-        signal: AbortSignal.timeout(120000),
-    });
-    if (!response.ok) {
-        const text = await response.text();
-        throw new Error(`Extraction request failed with ${response.status}: ${text}`);
-    }
-    const payload = (await response.json());
-    const rawContent = payload.choices?.[0]?.message?.content;
-    if (!rawContent) {
-        throw new Error("Extraction model returned no content.");
-    }
-    const parsed = parseJsonResponse(rawContent);
-    return {
-        model,
-        candidates: sanitizeExtractionCandidates(parsed.candidates, category),
-    };
-}
 async function runCommand(command, args, timeoutMs, env = process.env) {
     return new Promise((resolvePromise, reject) => {
         const child = spawn(command, args, {
@@ -492,40 +361,6 @@ async function readStdin() {
 function defaultAnythingLLMWorkspace(config) {
     return config.anythingllm_workspaces?.find((workspace) => workspace !== "engineering-patterns");
 }
-async function callAnythingLLM(workspace, query) {
-    const apiKey = process.env.ANYTHINGLLM_API_KEY;
-    if (!apiKey) {
-        throw new Error("ANYTHINGLLM_API_KEY is not set.");
-    }
-    const baseUrl = process.env.ANYTHINGLLM_BASE_URL ?? "http://localhost:3001";
-    const response = await fetch(`${baseUrl}/api/v1/workspace/${encodeURIComponent(workspace)}/chat`, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-            message: query,
-            mode: "query",
-        }),
-        signal: AbortSignal.timeout(120000),
-    });
-    if (!response.ok) {
-        const text = await response.text();
-        throw new Error(`AnythingLLM request failed with ${response.status}: ${text}`);
-    }
-    const payload = (await response.json());
-    const directText = [
-        payload.textResponse,
-        payload.response,
-        payload.message,
-        payload.text,
-    ].find((value) => typeof value === "string");
-    if (typeof directText === "string") {
-        return directText;
-    }
-    return JSON.stringify(payload, null, 2);
-}
 function entryText(entry) {
     const metadata = [entry.node_type, ...(entry.tags ?? [])].filter(Boolean).join("\n");
     return [entry.key, entry.value, metadata].filter(Boolean).join("\n");
@@ -873,6 +708,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
     const artifactToolsEnabled = isArtifactStoreEnabled() && (!context.remote || isArtifactHttpEnabled());
     const contextPackToolsEnabled = contextPacksEnabled() && (!context.remote || contextPackHttpEnabled());
     const workEvidenceToolsEnabled = isWorkEvidenceEnabled() && !context.remote;
+    const contextUsageToolsEnabled = process.env.CAIRN_CONTEXT_USAGE === "1" && workEvidenceToolsEnabled;
     if (artifactToolsEnabled && context.remote && !context.projectId) {
         throw new ClientContextError("Remote artifact access requires X-Cairn-Project.");
     }
@@ -1317,7 +1153,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             category: z.enum(["decision", "preference", "pattern", "pitfall", "constraint", "bug", "convention"]).optional(),
         }),
     }, async ({ scope, content, model, category }) => {
-        const extracted = await extractMemoryCandidates(content, model, category);
+        const extracted = await extractMemoryCandidatesFromProvider(content, model, category);
         const payload = {
             scope,
             model: extracted.model,
@@ -1424,102 +1260,17 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             value: z.string(),
         }),
     }, async ({ scope, review_id, key, value }) => {
-        assertWritableMemoryKey(key);
-        const agent = await openScope(scope, true, scopeOptions);
-        if (!agent) {
-            throw new Error(`Unable to open scope ${scope}.`);
-        }
-        try {
-            const payload = await inImmediateScopeTransaction(agent, async () => {
-                const recordKey = reviewedRecordKey(review_id);
-                const valueHash = hashText(value);
-                const stored = await agent.kv.get(recordKey);
-                if (stored !== undefined) {
-                    const existing = parseReviewedRecord(stored);
-                    if (existing.key !== key || existing.value_hash !== valueHash) {
-                        throw new Error(`Review id ${review_id} was already used with different content.`);
-                    }
-                    if (existing.state !== "active") {
-                        throw new Error(`Review id ${review_id} is ${existing.state} and cannot be reapplied.`);
-                    }
-                    return {
-                        ok: true,
-                        scope,
-                        review_id,
-                        key,
-                        applied: false,
-                        idempotent: true,
-                        snapshot_key: null,
-                    };
-                }
-                const appliedAt = new Date().toISOString();
-                const provenance = await agent.kv.list(`${REVIEWED_NAMESPACE}/`);
-                for (const entry of provenance) {
-                    const previousRecord = parseReviewedRecord(entry.value);
-                    if (previousRecord.state === "active" && previousRecord.key === key) {
-                        await agent.kv.set(entry.key, {
-                            ...previousRecord,
-                            state: "superseded",
-                            superseded_at: appliedAt,
-                            superseded_by: review_id,
-                        });
-                    }
-                }
-                let snapshotKey = null;
-                if (typedNodesEnabled) {
-                    const changed = await applyReviewedTypedNode({
-                        agent,
-                        scope,
-                        review_id,
-                        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 ${review_id}`,
-                        });
-                    }
-                    await agent.kv.set(key, value);
-                }
-                await agent.kv.set(recordKey, {
-                    schema_version: 1,
-                    review_id,
-                    key,
-                    value_hash: valueHash,
-                    state: "active",
-                    applied_at: appliedAt,
-                });
-                return {
-                    ok: true,
-                    scope,
-                    review_id,
-                    key,
-                    applied: true,
-                    idempotent: false,
-                    snapshot_key: snapshotKey,
-                };
-            });
-            const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
-            await linkActiveWorkEvidence(process.cwd(), { kind: "reviewed_memory", scope, review_id, key });
-            return {
-                content: [{ type: "text", text: asToolText(payload) }],
-                structuredContent: payload,
-            };
-        }
-        finally {
-            await agent.close();
-        }
+        const payload = await applyReviewedMemory(scope, review_id, key, value, {
+            cwd: process.cwd(),
+            projectId: context.projectId,
+            typed: typedNodesEnabled,
+        });
+        const { linkActiveWorkEvidence } = await import("./work-evidence-store.js");
+        await linkActiveWorkEvidence(process.cwd(), { kind: "reviewed_memory", scope, review_id, key });
+        return {
+            content: [{ type: "text", text: asToolText(payload) }],
+            structuredContent: payload,
+        };
     });
     registerTool("memory_invalidate_reviewed", {
         description: "Invalidate a reviewed revision, removing it only when the live value still matches.",
@@ -1530,121 +1281,15 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             reason: z.string().max(512).optional(),
         }),
     }, async ({ scope, review_id, key, reason }) => {
-        assertWritableMemoryKey(key);
-        const agent = await openScope(scope, true, scopeOptions);
-        if (!agent) {
-            throw new Error(`Unable to open scope ${scope}.`);
-        }
-        try {
-            const payload = await inImmediateScopeTransaction(agent, async () => {
-                const recordKey = reviewedRecordKey(review_id);
-                const stored = await agent.kv.get(recordKey);
-                if (stored === undefined) {
-                    const invalidatedAt = new Date().toISOString();
-                    await agent.kv.set(recordKey, {
-                        schema_version: 1,
-                        review_id,
-                        key,
-                        value_hash: "",
-                        state: "invalidated",
-                        applied_at: invalidatedAt,
-                        invalidated_at: invalidatedAt,
-                        ...(reason ? { invalidation_reason: reason } : {}),
-                    });
-                    return {
-                        ok: true,
-                        scope,
-                        review_id,
-                        key,
-                        invalidated: true,
-                        idempotent: false,
-                        missing: true,
-                        removed: false,
-                        current_changed: false,
-                        snapshot_key: null,
-                    };
-                }
-                const record = parseReviewedRecord(stored);
-                if (record.key !== key) {
-                    throw new Error(`Review id ${review_id} belongs to a different memory key.`);
-                }
-                if (record.state === "invalidated") {
-                    return {
-                        ok: true,
-                        scope,
-                        review_id,
-                        key: record.key,
-                        invalidated: false,
-                        idempotent: true,
-                        missing: record.value_hash === "",
-                        removed: false,
-                        current_changed: false,
-                        snapshot_key: null,
-                    };
-                }
-                const invalidatedAt = 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 (typedNodesEnabled) {
-                                const changed = await invalidateReviewedTypedNode({
-                                    agent,
-                                    scope,
-                                    review_id,
-                                    key: record.key,
-                                    reason,
-                                    in_transaction: true,
-                                });
-                                snapshotKey = changed.snapshot_key;
-                            }
-                            else {
-                                snapshotKey = historySnapshotKey(record.key, invalidatedAt);
-                                await agent.kv.set(snapshotKey, {
-                                    value: currentValue,
-                                    superseded_at: invalidatedAt,
-                                    superseded_reason: reason ?? `reviewed memory ${review_id} invalidated`,
-                                });
-                                await agent.kv.delete(record.key);
-                            }
-                            removed = true;
-                        }
-                        else {
-                            currentChanged = true;
-                        }
-                    }
-                }
-                await agent.kv.set(recordKey, {
-                    ...record,
-                    state: "invalidated",
-                    invalidated_at: invalidatedAt,
-                    ...(reason ? { invalidation_reason: reason } : {}),
-                });
-                return {
-                    ok: true,
-                    scope,
-                    review_id,
-                    key: record.key,
-                    invalidated: true,
-                    idempotent: false,
-                    missing: false,
-                    removed,
-                    current_changed: currentChanged,
-                    snapshot_key: snapshotKey,
-                };
-            });
-            return {
-                content: [{ type: "text", text: asToolText(payload) }],
-                structuredContent: payload,
-            };
-        }
-        finally {
-            await agent.close();
-        }
+        const payload = await invalidateReviewedMemory(scope, review_id, key, reason, {
+            cwd: process.cwd(),
+            projectId: context.projectId,
+            typed: typedNodesEnabled,
+        });
+        return {
+            content: [{ type: "text", text: asToolText(payload) }],
+            structuredContent: payload,
+        };
     });
     registerTool("memory_history", {
         description: "Read prior versions of a memory entry from the hidden history namespace.",
@@ -1756,7 +1401,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
         });
     }
     registerTool("domain_knowledge_query", {
-        description: "Query an AnythingLLM workspace in query mode for domain knowledge.",
+        description: "Query the configured read-only domain retrieval provider for domain knowledge.",
         inputSchema: z.object({
             workspace: z.string().min(1).optional(),
             query: z.string().min(1),
@@ -1769,7 +1414,11 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
         if (!workspaceSlug) {
             throw new Error("No AnythingLLM workspace provided and no project workspace found in memory config.");
         }
-        const answer = await callAnythingLLM(workspaceSlug, query);
+        const answer = await queryDomainKnowledge({
+            workspace: workspaceSlug,
+            query,
+            remote: context.remote,
+        });
         return {
             content: [{ type: "text", text: answer }],
             structuredContent: { workspace: workspaceSlug, answer },
@@ -1784,6 +1433,9 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             timeout_seconds: z.number().int().min(30).max(3600).optional(),
         }),
     }, async ({ workspace, mode, confirm_replace, timeout_seconds }) => {
+        if (resolveDomainRetrievalProvider() === "openviking") {
+            throw new Error("domain_knowledge_sync is unavailable for the read-only OpenViking provider.");
+        }
         const syncMode = mode ?? "incremental";
         const config = memoryConfig();
         const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(config);
@@ -1912,14 +1564,28 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             const payload = await listVisibleContext(contextPackProject);
             return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
         });
+        registerTool("context_pack_tree", {
+            description: "Browse a deterministic abstract or overview hierarchy of enabled context-pack files and approved skills.",
+            inputSchema: z.object({
+                pack: z.string().min(1).max(128).optional(),
+                detail: z.enum(["abstract", "overview"]).optional(),
+            }).strict(),
+        }, async ({ pack, detail }) => {
+            const payload = await treeVisibleContext({ ...contextPackProject, pack, detail });
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
         registerTool("context_pack_search", {
             description: "Search documents and explicitly approved skills in context packs enabled for this project.",
             inputSchema: z.object({
                 query: z.string().min(1).max(4096),
                 limit: z.number().int().min(1).max(100).optional(),
+                strategy: z.enum(["flat", "hierarchical"]).optional(),
+                detail: z.enum(["abstract", "overview", "content"]).optional(),
+                explain: z.boolean().optional(),
+                include_refs: z.boolean().optional(),
             }).strict(),
-        }, async ({ query, limit }) => {
-            const payload = await searchVisibleContext(query, { ...contextPackProject, limit });
+        }, async ({ query, limit, strategy, detail, explain, include_refs }) => {
+            const payload = await searchVisibleContext(query, { ...contextPackProject, limit, strategy, detail, explain, includeRefs: include_refs });
             return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
         });
         registerTool("context_pack_read", {
@@ -1947,6 +1613,26 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
         });
     }
+    if (contextUsageToolsEnabled) {
+        registerTool("context_usage_record", {
+            description: "Record a privacy-minimized context result receipt against work evidence.",
+            inputSchema: z.object({
+                evidence_id: z.string().min(4).max(40).regex(/^wev_[0-9a-f-]*$/i).optional(),
+                task_digest: z.string().regex(/^[a-f0-9]{64}$/),
+                result_digest: z.string().regex(/^[a-f0-9]{64}$/),
+                outcome: z.enum(["used", "unused", "unknown"]),
+            }).strict(),
+        }, async ({ evidence_id, task_digest, result_digest, outcome }) => {
+            const { appendContextUsageReceipt, linkActiveContextUsageReceipt } = await import("./work-evidence-store.js");
+            const receipt = evidence_id
+                ? await appendContextUsageReceipt(process.cwd(), evidence_id, { task_digest, result_digest, outcome })
+                : await linkActiveContextUsageReceipt(process.cwd(), { task_digest, result_digest, outcome });
+            const payload = receipt
+                ? { schema_version: 1, recorded: true, receipt }
+                : { schema_version: 1, recorded: false, receipt: null };
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
+    }
     if (workEvidenceToolsEnabled) {
         registerTool("work_evidence_list", {
             description: "List bounded local Git-linked work-evidence records for this project.",
@@ -2031,7 +1717,7 @@ if (cliCommand === "extract") {
         if (!content) {
             throw new Error("No input provided on stdin.");
         }
-        const extracted = await extractMemoryCandidates(content, model, category);
+        const extracted = await extractMemoryCandidatesFromProvider(content, model, category);
         output.write(`${JSON.stringify({
             model: extracted.model,
             count: extracted.candidates.length,

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

@@ -33,9 +33,11 @@ export const MCP_TOOL_CATALOG = {
     context_explore: observation("Explore repository context", true),
     route_check: observation("Check route", true),
     context_pack_list: observation("List context packs"),
+    context_pack_tree: observation("Browse context pack hierarchy"),
     context_pack_search: observation("Search context packs"),
     context_pack_read: observation("Read context pack file"),
     context_pack_related: observation("Traverse context pack links"),
+    context_usage_record: additive("Record context usage"),
     work_evidence_list: observation("List work evidence"),
     work_evidence_read: observation("Read work evidence"),
 };

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

@@ -0,0 +1,87 @@
+function truncateOutput(value, maxLength = 12000) {
+    return value.length <= maxLength
+        ? value
+        : `${value.slice(0, maxLength)}\n...[truncated ${value.length - maxLength} chars]`;
+}
+function stripMarkdownFences(value) {
+    return value.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim();
+}
+function parseJsonResponse(value) {
+    const stripped = stripMarkdownFences(value);
+    try {
+        return JSON.parse(stripped);
+    }
+    catch {
+        const firstBrace = stripped.indexOf("{");
+        const lastBrace = stripped.lastIndexOf("}");
+        if (firstBrace !== -1 && lastBrace > firstBrace) {
+            return JSON.parse(stripped.slice(firstBrace, lastBrace + 1));
+        }
+        throw new Error(`Failed to parse JSON response: ${truncateOutput(stripped, 1000)}`);
+    }
+}
+export function sanitizeExtractionCandidates(value, fallbackCategory) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => {
+        if (!item || typeof item !== "object")
+            return null;
+        const raw = item;
+        const key = typeof raw.key === "string" ? raw.key.trim() : "";
+        const candidateValue = typeof raw.value === "string" ? raw.value.trim() : "";
+        if (!key || !candidateValue)
+            return null;
+        const category = typeof raw.category === "string" && raw.category.trim()
+            ? raw.category.trim()
+            : fallbackCategory;
+        const importance = typeof raw.importance === "number"
+            ? Math.max(0, Math.min(1, raw.importance))
+            : undefined;
+        return { key, value: candidateValue, category, importance };
+    })
+        .filter((candidate) => candidate !== null);
+}
+export async function extractMemoryCandidates(content, modelOverride, category) {
+    const apiKey = process.env.CAIRN_LLM_API_KEY;
+    if (!apiKey)
+        throw new Error("CAIRN_LLM_API_KEY is not set.");
+    const rawUrl = process.env.CAIRN_LLM_API_URL;
+    if (!rawUrl)
+        throw new Error("CAIRN_LLM_API_URL is not set.");
+    const apiUrl = rawUrl.trim().replace(/\/+$/, "");
+    const model = (modelOverride ?? process.env.CAIRN_LLM_EXTRACTION_MODEL)?.trim();
+    if (!model)
+        throw new Error("CAIRN_LLM_EXTRACTION_MODEL is not set.");
+    const systemPrompt = [
+        "You extract durable memory candidates from development notes.",
+        "Return ONLY valid JSON, no markdown fences.",
+        "Schema: {\"candidates\":[{\"key\":\"decisions/cache-rule\",\"value\":\"...\",\"category\":\"decision\",\"importance\":0.92}]}",
+        "Only include genuinely reusable knowledge.",
+        "Skip trivial status notes, temporary branch details, and duplicated points.",
+        "Prefer short kebab-case keys with a useful prefix such as decisions/, pitfalls/, patterns/, bugs/, constraints/, preferences/, conventions/.",
+        "Do not invent dates unless they are explicitly present in the source text.",
+        category ? `Bias extraction toward category: ${category}.` : "",
+    ].filter(Boolean).join(" ");
+    const response = await fetch(`${apiUrl}/chat/completions`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model,
+            messages: [{ role: "system", content: systemPrompt }, { role: "user", content }],
+            temperature: 0.1,
+            max_tokens: 1200,
+        }),
+        signal: AbortSignal.timeout(120000),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Extraction request failed with ${response.status}: ${text}`);
+    }
+    const payload = (await response.json());
+    const rawContent = payload.choices?.[0]?.message?.content;
+    if (!rawContent)
+        throw new Error("Extraction model returned no content.");
+    const parsed = parseJsonResponse(rawContent);
+    return { model, candidates: sanitizeExtractionCandidates(parsed.candidates, category) };
+}