@cairnkeep/cli 2.23.0 → 2.24.0

package/mcp-memory-server/dist/anythingllm-workspace.js

@@ -0,0 +1,109 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { readStableJson } from "./stable-file.js";
+/** Shared workspace that is never a project default; it holds cross-project patterns. */
+const SHARED_WORKSPACE = "engineering-patterns";
+const WORKSPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MAX_MAPPING_BYTES = 1024 * 1024;
+const MAX_PROJECTS = 4096;
+function expandHome(value) {
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/"))
+        return join(homedir(), value.slice(2));
+    return value;
+}
+/**
+ * Locate `anythingllm-projects.json`.
+ *
+ * Mirrors the precedence in `examples/anythingllm/sync_to_anythingllm.py` so the
+ * resolver and the sync script can never disagree about which mapping is live.
+ */
+export function anythingllmProjectsFile(env = process.env, legacyDir) {
+    const override = env.CAIRN_ANYTHINGLLM_PROJECTS_FILE;
+    if (override) {
+        const explicit = resolve(expandHome(override));
+        return existsSync(explicit) ? explicit : undefined;
+    }
+    if (legacyDir) {
+        const legacy = join(legacyDir, "anythingllm-projects.json");
+        if (existsSync(legacy))
+            return legacy;
+    }
+    const configHome = env.XDG_CONFIG_HOME
+        ? resolve(expandHome(env.XDG_CONFIG_HOME))
+        : join(homedir(), ".config");
+    const standard = join(configHome, "cairnkeep", "anythingllm-projects.json");
+    if (existsSync(standard))
+        return standard;
+    return undefined;
+}
+/**
+ * Workspace slug declared for the project containing `cwd`, if any.
+ *
+ * The deepest matching `path` wins so a checkout nested inside another project
+ * resolves to its own workspace rather than its parent's.
+ */
+export function workspaceForDirectory(cwd, env = process.env, legacyDir) {
+    const file = anythingllmProjectsFile(env, legacyDir);
+    if (!file)
+        return undefined;
+    let entries;
+    try {
+        const parsed = readStableJson(file, { label: "Workspace mapping", maxBytes: MAX_MAPPING_BYTES });
+        if (!Array.isArray(parsed?.projects) || parsed.projects.length > MAX_PROJECTS)
+            return undefined;
+        entries = parsed.projects;
+    }
+    catch {
+        // A malformed or unreadable mapping must not break workspace resolution;
+        // fall back to the configured list rather than failing the tool call.
+        return undefined;
+    }
+    let here;
+    try {
+        here = realpathSync.native(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    let bestSlug;
+    let bestDepth = -1;
+    let ambiguous = false;
+    for (const entry of entries) {
+        const slug = typeof entry?.slug === "string" ? entry.slug : "";
+        const path = typeof entry?.path === "string" ? entry.path : "";
+        if (!WORKSPACE_PATTERN.test(slug) || slug === SHARED_WORKSPACE || !isAbsolute(path))
+            continue;
+        let root;
+        try {
+            root = realpathSync.native(path);
+        }
+        catch {
+            continue;
+        }
+        const rel = relative(root, here);
+        const contains = rel === "" || (rel !== ".." && !rel.startsWith("../") && !rel.startsWith("..\\") && !isAbsolute(rel));
+        if (contains && root.length > bestDepth) {
+            bestSlug = slug;
+            bestDepth = root.length;
+            ambiguous = false;
+        }
+        else if (contains && root.length === bestDepth && slug !== bestSlug) {
+            ambiguous = true;
+        }
+    }
+    if (ambiguous)
+        throw new Error("Ambiguous project workspace mapping; specify workspace explicitly.");
+    return bestSlug;
+}
+/**
+ * Default workspace for a tool call: the project containing `cwd` when it is
+ * declared, otherwise the previous behaviour so existing single-project setups
+ * keep working unchanged.
+ */
+export function defaultAnythingLLMWorkspace(config, cwd = process.cwd(), env = process.env, legacyDir) {
+    return (workspaceForDirectory(cwd, env, legacyDir) ??
+        config.anythingllm_workspaces?.find((workspace) => workspace !== SHARED_WORKSPACE));
+}

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

@@ -11,10 +11,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
+import { defaultAnythingLLMWorkspace as resolveDefaultAnythingLLMWorkspace } from "./anythingllm-workspace.js";
 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 { getMemoryRerankerConfig, memoryRerankCandidateCount, rerankMemoryResults } from "./memory-reranker.js";
 import { formatHostAuthority, normalizeHostAuthority, normalizeHttpHost, parseHttpPort, resolveHttpToken } from "./http-security.js";
 import { computeRepoState, exploreCacheKey, normalizeExploreQuery, readExploreCache, writeExploreCache, } from "./explore-cache.js";
 import { canonicalTagsSchema, isTypedMemoryNodesEnabled, memoryImportEnvelopeSchema, noteNodeSchema, nodeTypeSchema, } from "./node-schema.js";
@@ -360,8 +362,14 @@ async function readStdin() {
     }
     return Buffer.concat(chunks).toString("utf8");
 }
-function defaultAnythingLLMWorkspace(config) {
-    return config.anythingllm_workspaces?.find((workspace) => workspace !== "engineering-patterns");
+function defaultAnythingLLMWorkspace(config, remote = false) {
+    // HTTP callers route by session metadata, never by the server's checkout.
+    if (remote || resolveDomainRetrievalProvider() !== "anythingllm") {
+        return config.anythingllm_workspaces?.find((workspace) => workspace !== "engineering-patterns");
+    }
+    // `anythingllm-projects.json` may also sit beside the bundled sync script,
+    // which is the legacy location the script still honours.
+    return resolveDefaultAnythingLLMWorkspace(config, process.cwd(), process.env, dirname(anythingllmSyncScript));
 }
 function entryText(entry) {
     const metadata = [entry.node_type, ...(entry.tags ?? [])].filter(Boolean).join("\n");
@@ -370,7 +378,7 @@ function entryText(entry) {
 function embeddingCachePath(scope, projectId) {
     return join(getBaseDir(), ".embeddings", `${hashText(resolveScopePath(scope, { projectId }))}.json`);
 }
-async function semanticSearch(scope, query, topK, minScore, config = getMemoryConfig(), projectId, options = {}) {
+async function semanticSearchCandidates(scope, query, topK, minScore, config = getMemoryConfig(), projectId, options = {}) {
     const scopes = getSearchScopes(scope, config);
     const embeddingConfig = getEmbeddingConfig();
     const perScopeEntries = await Promise.all(scopes.map(async (candidate) => ({
@@ -473,6 +481,32 @@ async function semanticSearch(scope, query, topK, minScore, config = getMemoryCo
         return substringFallback();
     }
 }
+async function semanticSearch(...args) {
+    const reranker = getMemoryRerankerConfig();
+    if (!reranker)
+        return semanticSearchCandidates(...args);
+    const [, query, topK] = args;
+    const options = args[6] ?? {};
+    const candidateArgs = [...args];
+    candidateArgs[2] = memoryRerankCandidateCount(topK, reranker);
+    // The existing path still owns scope, current-value, typed and relevance
+    // admission. The external ranker never sees records rejected by that path.
+    const candidate = await semanticSearchCandidates(...candidateArgs);
+    const exactKeys = new Set([query, ...(options.aliases ?? [])].map(value => value.normalize('NFKC').toLowerCase().trim()));
+    const pinned = (entry) => options.strategy === 'hybrid'
+        ? exactKeys.has(entry.key.normalize('NFKC').toLowerCase())
+        : Boolean(options.typed && isExactTextHit(entry, query));
+    const { results } = await rerankMemoryResults(candidate.results, query, topK, reranker, pinned);
+    const retrieval = candidate.retrieval;
+    if (retrieval?.possible_conflicts) {
+        const keys = new Set(results.map(entry => entry.key));
+        // Explain only selected keys, including when the larger candidate pool
+        // falls back. Do not leak explanations for unreturned candidates.
+        return { ...candidate, results, retrieval: { ...retrieval,
+                possible_conflicts: retrieval.possible_conflicts.filter(row => keys.has(row.key)) } };
+    }
+    return { ...candidate, results };
+}
 // Confines a candidate wiki source file to inside `<repoRoot>/.planning/wiki/sources`
 // via relative()-based containment (Phase 2 SEC-0001 idiom, reused from
 // opencode/plugins/memory-recall.ts) — `resolve() === join()` misses `../`
@@ -701,8 +735,9 @@ function gitToplevel(cwd) {
 // serve many concurrent clients within one trusted server-side storage domain.
 function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProfile = resolveMcpToolProfile({ projectRoot: process.cwd() })) {
     const server = new McpServer({ name: "cairn-memory", version: "0.1.0" });
+    const memoryReranking = getMemoryRerankerConfig() !== null;
     const registerTool = (name, config, callback) => {
-        const metadata = metadataForTool(name);
+        const metadata = metadataForTool(name, { memoryReranking });
         if (!profileAllowsTool(toolProfile, name))
             return;
         server.registerTool(name, {
@@ -1452,7 +1487,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
             readOnlyHint: true,
         },
     }, async ({ workspace, query }) => {
-        const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(memoryConfig());
+        const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(memoryConfig(), context.remote);
         if (!workspaceSlug) {
             throw new Error("No AnythingLLM workspace provided and no project workspace found in memory config.");
         }
@@ -1480,7 +1515,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProf
         }
         const syncMode = mode ?? "incremental";
         const config = memoryConfig();
-        const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(config);
+        const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(config, context.remote);
         if (!workspaceSlug) {
             throw new Error("No AnythingLLM workspace provided and no project workspace found in memory config.");
         }

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

@@ -45,8 +45,11 @@ export const MCP_TOOL_NAMES = Object.freeze(Object.keys(MCP_TOOL_CATALOG));
 export function isCairnToolName(value) {
     return Object.hasOwn(MCP_TOOL_CATALOG, value);
 }
-export function metadataForTool(name) {
+export function metadataForTool(name, options = {}) {
     if (!isCairnToolName(name))
         throw new Error(`MCP tool ${name} has no annotation contract.`);
+    if (name === 'memory_search' && options.memoryReranking) {
+        return { ...MCP_TOOL_CATALOG[name], annotations: { ...MCP_TOOL_CATALOG[name].annotations, openWorldHint: true } };
+    }
     return MCP_TOOL_CATALOG[name];
 }

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

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+const MAX_CANDIDATES = 50;
+const MAX_TEXT_BYTES = 4096;
+const MAX_REQUEST_BYTES = 256 * 1024;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const responseSchema = z.object({ results: z.array(z.object({
+        index: z.number().int().min(0).max(MAX_CANDIDATES - 1),
+        relevance_score: z.number().finite(),
+    })).max(MAX_CANDIDATES) });
+/** Configuration alone never grants permission: explicit opt-in is required. */
+export function getMemoryRerankerConfig(env = process.env) {
+    if (env.CAIRN_MEMORY_RERANK !== '1')
+        return null;
+    try {
+        const url = new URL(env.CAIRN_MEMORY_RERANK_URL ?? '');
+        const model = env.CAIRN_MEMORY_RERANK_MODEL?.trim();
+        const rawTimeout = env.CAIRN_MEMORY_RERANK_TIMEOUT_MS ?? '2000';
+        const timeoutMs = Number(rawTimeout);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash
+            || !model || Buffer.byteLength(model) > 256 || !/^\d+$/.test(rawTimeout)
+            || !Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000)
+            return null;
+        const apiKey = env.CAIRN_MEMORY_RERANK_API_KEY?.trim();
+        if (apiKey && (apiKey.length > 8192 || /[\r\n]/.test(apiKey)))
+            return null;
+        return { apiUrl: url.href.replace(/\/+$/, ''), model, ...(apiKey ? { apiKey } : {}), timeoutMs };
+    }
+    catch {
+        return null;
+    }
+}
+export function memoryRerankCandidateCount(topK, config) {
+    if (!Number.isInteger(topK) || topK < 1 || topK > MAX_CANDIDATES)
+        throw new Error('Reranking requires a bounded result count.');
+    return config ? Math.min(MAX_CANDIDATES, Math.max(32, topK * 4)) : topK;
+}
+function textPrefix(value, maxUnits) {
+    let end = Math.min(value.length, maxUnits);
+    const last = value.charCodeAt(end - 1);
+    if (end < value.length && last >= 0xD800 && last <= 0xDBFF)
+        end--;
+    return value.slice(0, end);
+}
+function rankingText(entry) {
+    // Bound allocation before UTF-8 encoding, then discard an incomplete final
+    // code point rather than introducing replacement characters at the cutoff.
+    const text = `${textPrefix(entry.key, 1024)}\n${textPrefix(entry.value, MAX_TEXT_BYTES)}`;
+    const bytes = Buffer.from(text);
+    return new TextDecoder().decode(bytes.subarray(0, MAX_TEXT_BYTES), { stream: true });
+}
+async function readRankingResponse(response) {
+    if (!response.ok || !response.body || Number(response.headers.get('content-length')) > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel();
+        throw new Error('Reranker response unavailable.');
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_RESPONSE_BYTES)
+                throw new Error('Reranker response exceeds limit.');
+            chunks.push(value);
+        }
+        const bytes = Buffer.concat(chunks, size);
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** Reorder admitted records only. No input object, score, scope or value is changed. */
+export async function rerankMemoryResults(entries, query, topK, config, pinned = () => false) {
+    const baseline = entries.slice(0, topK);
+    if (!config)
+        return { results: baseline, status: 'disabled' };
+    if (entries.length < 2 || entries.length > MAX_CANDIDATES || !query.trim() || Buffer.byteLength(query) > MAX_TEXT_BYTES) {
+        return { results: baseline, status: 'skipped' };
+    }
+    try {
+        const body = JSON.stringify({ model: config.model, query, documents: entries.map(rankingText), top_n: entries.length });
+        if (Buffer.byteLength(body) > MAX_REQUEST_BYTES)
+            return { results: baseline, status: 'skipped' };
+        const response = await fetch(`${config.apiUrl}/rerank`, {
+            method: 'POST', redirect: 'manual', signal: AbortSignal.timeout(config.timeoutMs),
+            headers: { 'Content-Type': 'application/json', ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}) },
+            body,
+        });
+        const parsed = responseSchema.parse(await readRankingResponse(response));
+        if (parsed.results.length !== entries.length
+            || new Set(parsed.results.map(row => row.index)).size !== entries.length
+            || parsed.results.some(row => row.index >= entries.length))
+            throw new Error('Invalid ranking indices.');
+        const scores = new Map(parsed.results.map(row => [row.index, row.relevance_score]));
+        const ordered = entries.map((entry, index) => ({ entry, index, pinned: pinned(entry) }));
+        ordered.sort((a, b) => Number(b.pinned) - Number(a.pinned)
+            || scores.get(b.index) - scores.get(a.index) || a.index - b.index);
+        return { results: ordered.slice(0, topK).map(row => row.entry), status: 'reranked' };
+    }
+    catch {
+        // Never return endpoint errors, response bodies or credentials to clients.
+        return { results: baseline, status: 'failed' };
+    }
+}

package/mcp-memory-server/package.json

@@ -16,10 +16,11 @@
         "check:extract": "node scripts/smoke-extract-cli.mjs",
         "check:search": "node scripts/smoke-search-e2e.mjs",
         "check:memory-retrieval": "node scripts/smoke-memory-retrieval.mjs && node scripts/smoke-memory-retrieval-mcp.mjs && node scripts/run-memory-retrieval-study.mjs --check --summary",
+        "check:memory-reranker": "node scripts/smoke-memory-reranker.mjs && node scripts/smoke-memory-reranker-mcp.mjs && node scripts/run-memory-reranker-study.mjs --check --summary",
         "study:memory-retrieval": "npm run build && node scripts/run-memory-retrieval-study.mjs --summary",
         "check:scope-guard": "node scripts/smoke-scope-guard.mjs",
         "check:http-guard": "node scripts/smoke-http-guard.mjs",
-        "check:remote-context": "node scripts/smoke-remote-context.mjs",
+        "check:remote-context": "node scripts/smoke-remote-context.mjs && node scripts/smoke-remote-context-ports.mjs",
         "check:explore-guard": "node scripts/smoke-explore-guard.mjs",
         "check:explore-cache": "node scripts/smoke-explore-cache.mjs",
         "check:explore-crossref": "node scripts/smoke-explore-crossref.mjs",
@@ -58,6 +59,7 @@
         "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:anythingllm-workspace": "node scripts/smoke-anythingllm-workspace.mjs && node scripts/smoke-anythingllm-workspace-mcp.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",
@@ -77,7 +79,7 @@
         "@modelcontextprotocol/sdk": "^1.32.1",
         "agentfs-sdk": "^0.6.4",
         "yaml": "2.9.1",
-        "zod": "^4.6.5"
+        "zod": "^4.6.7"
     },
     "devDependencies": {
         "@types/node": "^22.20.5",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cairnkeep/cli",
-    "version": "2.23.0",
+    "version": "2.24.0",
     "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
     "license": "Apache-2.0",
     "type": "module",
@@ -41,7 +41,7 @@
         "@modelcontextprotocol/sdk": "^1.32.1",
         "agentfs-sdk": "^0.6.4",
         "yaml": "2.9.1",
-        "zod": "^4.6.5"
+        "zod": "^4.6.7"
     },
     "scripts": {
         "build:server": "npm --prefix mcp-memory-server ci --include=dev --global=false --dry-run=false && npm --prefix mcp-memory-server run build --global=false --dry-run=false",

package/scripts/doctor.sh

@@ -112,6 +112,23 @@ else
   skip "embedding endpoint (CAIRN_MEMORY_EMBEDDING_URL unset)"
 fi
 
+# Optional learned reranking: use the runtime validator and a synthetic request.
+# Never print provider bodies, credentials, URLs or user memory in diagnostics.
+if [[ "${CAIRN_MEMORY_RERANK:-}" == 1 ]]; then
+  if node "$CAIRN_ROOT/scripts/probe-memory-reranker.mjs" >/dev/null 2>&1; then
+    pass "memory reranker accepted a synthetic ranking request"
+  else
+    rerank_status=$?
+    if [[ "$rerank_status" == 2 ]]; then
+      fail "memory reranker configuration invalid — set CAIRN_MEMORY_RERANK_URL and CAIRN_MEMORY_RERANK_MODEL; timeout must be 100–10000 ms"
+    else
+      fail "memory reranker unavailable or returned invalid ranking data — search falls back to its existing order"
+    fi
+  fi
+else
+  skip "memory reranker (CAIRN_MEMORY_RERANK unset/not 1)"
+fi
+
 # 4. Git provider (collaboration commands). Report configuration only — auth is
 #    provider- and host-specific and lives in the wrapper, not the core.
 case "${CAIRN_GIT_PROVIDER:-}" in

package/scripts/probe-memory-reranker.mjs

@@ -0,0 +1,22 @@
+// Exit codes are a value-free doctor protocol: 0 disabled/healthy,
+// 2 invalid opt-in configuration, 3 unavailable or invalid ranking response.
+import { getMemoryRerankerConfig, rerankMemoryResults } from '../mcp-memory-server/dist/memory-reranker.js';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export async function probeMemoryReranker() {
+  if (process.env.CAIRN_MEMORY_RERANK !== '1') return 0;
+  const config = getMemoryRerankerConfig();
+  if (!config) return 2;
+  const result = await rerankMemoryResults([
+    { key: 'health/policy', value: 'Corrections append a new release ledger entry.' },
+    { key: 'health/theme', value: 'The release ledger interface uses a dark theme.' },
+  ], 'How are release ledger corrections recorded?', 2, config);
+  return result.status === 'reranked' ? 0 : 3;
+}
+
+let invokedDirectly = false;
+try { invokedDirectly = Boolean(process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)); } catch {}
+if (invokedDirectly) {
+  process.exitCode = await probeMemoryReranker();
+}

package/scripts/test-container-health.mjs

@@ -11,6 +11,8 @@ assert.match(quadlet, /^Secret=cairnkeep-http-token,type=mount,target=http-token
   "the managed container secret must satisfy the probe's private-file contract");
 assert.match(containerfile, /COPY --chmod=644 containers\/healthcheck\.mjs \/opt\/cairnkeep\/containers\/healthcheck\.mjs/, "probe imports must resolve within the packaged server");
 assert.match(containerfile, /ln -s \/opt\/cairnkeep\/containers\/healthcheck\.mjs \/usr\/local\/lib\/cairnkeep\/container-healthcheck\.mjs/, "keep the established container probe path");
+assert.match(containerfile, /COPY --chmod=644 containers\/healthcheck\.mjs[^\n]*\nRUN chmod 755 \/opt\/cairnkeep\/containers\b/,
+  "normalize the probe directory's traversal mode after COPY for unprivileged runtime users");
 assert.match(source, /parseHttpPort/, "health destination must use the server's numeric port parser");
 assert.match(source, /resolveHttpToken/, "health tokens must use the server's bounded resolver");
 const { containerHealthcheck } = await import("../containers/healthcheck.mjs");

package/scripts/test-container.sh

@@ -43,6 +43,21 @@ image_user=$("$ENGINE" image inspect --format '{{.Config.User}}' "$server_image"
   exit 1
 }
 
+# Check the real legacy entrypoint before a failing credential probe can mask
+# a module-load or directory-traversal error as an expected authentication denial.
+"$ENGINE" run --rm --entrypoint node "$server_image" --input-type=module -e '
+  import assert from "node:assert/strict";
+  import { accessSync, constants, realpathSync } from "node:fs";
+  import { pathToFileURL } from "node:url";
+  assert.equal(process.getuid(), 10001);
+  accessSync("/opt/cairnkeep/containers", constants.R_OK | constants.X_OK);
+  const target = realpathSync("/usr/local/lib/cairnkeep/container-healthcheck.mjs");
+  assert.equal(target, "/opt/cairnkeep/containers/healthcheck.mjs");
+  accessSync(target, constants.R_OK);
+  await import(pathToFileURL(target).href);
+  console.log("container health entrypoint: readable, searchable and importable as runtime UID");
+'
+
 "$ENGINE" volume create "$volume" >/dev/null
 node scripts/probe-memory-server.mjs --command \
   "$ENGINE" run --rm -i --volume "$volume:/data" "$server_image" stdio
@@ -112,10 +127,15 @@ done
 cat "$tmp/write.out"
 # Exec probes see the original container environment, not the entrypoint's
 # loaded secret. The deliberately public bind fixture must be rejected.
-if "$ENGINE" exec "$name" node /usr/local/lib/cairnkeep/container-healthcheck.mjs; then
+if "$ENGINE" exec "$name" node /usr/local/lib/cairnkeep/container-healthcheck.mjs >"$tmp/health.out" 2>"$tmp/health.err"; then
   echo "FAIL: healthcheck accepted a non-private token file" >&2
   exit 1
 fi
+[[ ! -s "$tmp/health.out" && ! -s "$tmp/health.err" ]] || {
+  cat "$tmp/health.out" "$tmp/health.err" >&2
+  echo "FAIL: healthcheck must reject unsafe credentials without a runtime error" >&2
+  exit 1
+}
 # Exercise the same legacy entrypoint against a private, container-owned file.
 "$ENGINE" exec "$name" sh -c 'umask 077; cat /run/secrets/http-token > /tmp/health-token; CAIRN_MEMORY_HTTP_TOKEN_FILE=/tmp/health-token node /usr/local/lib/cairnkeep/container-healthcheck.mjs; status=$?; rm -f /tmp/health-token; exit "$status"'
 "$ENGINE" rm -f "$name" >/dev/null

package/scripts/test-dependency-security.mjs

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const root = fileURLToPath(new URL("../", import.meta.url));
+const policy = join(root, "scripts/verify-dependency-security.mjs");
+const paths = ["package.json", "package-lock.json", "mcp-memory-server/package.json", "mcp-memory-server/package-lock.json"];
+const baseline = Object.fromEntries(paths.map(path => [path, JSON.parse(readFileSync(join(root, path), "utf8"))]));
+const scratch = mkdtempSync(join(tmpdir(), "cairn-dependency-policy-"));
+function check(label, mutate, expected) {
+  const values = structuredClone(baseline);
+  mutate(values);
+  for (const path of paths) {
+    const target = join(scratch, path);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, JSON.stringify(values[path]));
+  }
+  const result = spawnSync(process.execPath, [policy], { cwd: scratch, encoding: "utf8", timeout: 10000 });
+  assert.ifError(result.error);
+  assert.equal(result.status, expected ? 1 : 0, `${label}: ${result.stderr}`);
+  if (expected) assert.match(result.stderr, expected, label);
+}
+try {
+  check("valid dependency graph", () => {}, null);
+  for (const lockPath of ['package-lock.json', 'mcp-memory-server/package-lock.json']) {
+    for (const [name, vulnerable] of [['body-parser', '2.3.0'], ['fast-uri', '3.1.8'], ['ip-address', '10.7.3']]) {
+      check(`${lockPath} rejects vulnerable ${name}`, x => {
+        x[lockPath].packages[`node_modules/${name}`].version = vulnerable;
+      }, new RegExp(`resolved ${name}: requires`));
+      check(`${lockPath} rejects nested vulnerable ${name}`, x => {
+        x[lockPath].packages[`node_modules/fixture/node_modules/${name}`] = { version: vulnerable };
+      }, new RegExp(`resolved ${name}: requires`));
+    }
+  }
+  check("root manifest/lock mismatch", x => { x["package.json"].dependencies.zod = "^4.0.0"; }, /manifest and lock root Zod ranges differ/);
+  check("server manifest/lock mismatch", x => { x["mcp-memory-server/package-lock.json"].packages[""].dependencies.zod = "^4.0.0"; }, /manifest and lock root Zod ranges differ/);
+  check("matched server range differs from packaged CLI", x => {
+    x["mcp-memory-server/package.json"].dependencies.zod = "^4.0.0";
+    x["mcp-memory-server/package-lock.json"].packages[""].dependencies.zod = "^4.0.0";
+  }, /root and server Zod ranges differ/);
+  check("different resolved schema version", x => { x["mcp-memory-server/package-lock.json"].packages["node_modules/zod"].version = "4.0.0"; }, /root and server resolved Zod versions differ/);
+  check("missing direct schema", x => { delete x["package-lock.json"].packages["node_modules/zod"]; }, /direct Zod: version must be a string/);
+  check("existing SDK advisory check retained", x => { x["package-lock.json"].packages["node_modules/@modelcontextprotocol/sdk"].version = "1.0.0"; }, /resolved @modelcontextprotocol\/sdk: requires/);
+  console.log("PASS: dependency policy positive control, both-lock/nested advisory rejection and schema parity mutations");
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}

package/scripts/test-dependency-security.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+node "$ROOT/scripts/test-dependency-security.mjs"

package/scripts/test-doctor.sh

@@ -18,12 +18,14 @@ export HOME="$tmp/home"
 mkdir -p "$HOME"
 # Clean the inherited env so the test controls what is "configured".
 unset CAIRN_LLM_API_URL CAIRN_MEMORY_EMBEDDING_URL CAIRN_GIT_PROVIDER CAIRN_AGENTFS_BASE_DIR
+unset CAIRN_MEMORY_RERANK CAIRN_MEMORY_RERANK_URL CAIRN_MEMORY_RERANK_MODEL CAIRN_MEMORY_RERANK_API_KEY CAIRN_MEMORY_RERANK_TIMEOUT_MS
 
 # 1. Nothing configured → only SKIP/PASS/WARN, exit 0.
 proj="$tmp/clean"; mkdir -p "$proj"
 ( cd "$proj" && "$doctor" ) >"$tmp/out1" 2>&1 || fail "doctor exited non-zero with nothing configured:\n$(cat "$tmp/out1")"
 grep -q "\[SKIP\]" "$tmp/out1" || fail "expected SKIP lines when nothing is configured"
 grep -q "typed metadata and note transaction state" "$tmp/out1" || fail "expected typed/note diagnostics in the public doctor output"
+grep -qF "[SKIP] memory reranker" "$tmp/out1" || fail "expected default-off reranker diagnostic"
 grep -q "artifact store (not present" "$tmp/out1" || fail "expected absent opt-in artifact diagnostics"
 grep -q "capability configuration (not present — managed overrides are unused)" "$tmp/out1" ||
   fail "expected absent capability configuration diagnostics"
@@ -92,6 +94,12 @@ const server = createServer((request, response) => {
   request.on("end", () => {
     let body = {};
     try { body = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch {}
+    if (request.url === "/v1/rerank") {
+      response.writeHead(200, { "Content-Type": "application/json" });
+      response.end(JSON.stringify({ results: body.model === "invalid-ranker" ? [] :
+        body.documents.map((_, index) => ({ index, relevance_score: -index })) }));
+      return;
+    }
     const routeValid = request.url === "/v1/embeddings";
     const keyValid = request.headers.authorization === "Bearer test-key";
     const modelValid = body.model === "test-embedding";
@@ -153,6 +161,26 @@ EOF
     fail "missing-model diagnostic leaked an upstream body or request id"
 fi
 
+# Reranker diagnostics validate configuration and actual data, not HTTP status alone.
+if [[ -n "${port:-}" ]]; then
+  ( cd "$proj" && CAIRN_MEMORY_RERANK=1 CAIRN_MEMORY_RERANK_URL="http://127.0.0.1:$port/v1" \
+      CAIRN_MEMORY_RERANK_MODEL=test-ranker "$doctor" ) >"$tmp/reranker-ok" 2>&1 ||
+    fail "doctor rejected a valid reranking response"
+  grep -qF "[PASS] memory reranker accepted a synthetic ranking request" "$tmp/reranker-ok" ||
+    fail "doctor did not probe reranking"
+  if ( cd "$proj" && CAIRN_MEMORY_RERANK=1 "$doctor" ) >"$tmp/reranker-config" 2>&1; then
+    fail "doctor accepted an incomplete opted-in reranker"
+  fi
+  grep -qF "[FAIL] memory reranker configuration invalid" "$tmp/reranker-config" ||
+    fail "doctor omitted the reranker configuration diagnostic"
+  if ( cd "$proj" && CAIRN_MEMORY_RERANK=1 CAIRN_MEMORY_RERANK_URL="http://127.0.0.1:$port/v1" \
+      CAIRN_MEMORY_RERANK_MODEL=invalid-ranker "$doctor" ) >"$tmp/reranker-invalid" 2>&1; then
+    fail "doctor mistook fallback for a healthy reranker"
+  fi
+  grep -qF "[FAIL] memory reranker unavailable or returned invalid ranking data" "$tmp/reranker-invalid" ||
+    fail "doctor omitted the invalid ranking response diagnostic"
+fi
+
 # 5. Artifact doctor passes a valid store, repairs only derived state, and
 # refuses authoritative full-record corruption without leaking stored values.
 artifact_cli="$ROOT/mcp-memory-server/dist/artifact-cli.js"

package/scripts/test-windows-native.mjs

@@ -88,10 +88,12 @@ try {
   writeFileSync(join(invalidDerivedPack, `${"e".repeat(64)}.json`), "{\"corrupt\":true}\n");
   process.env.CAIRN_PACK_BASE_DIR = packBase;
   const inheritedLlmUrl = process.env.CAIRN_LLM_API_URL;
+  const inheritedRerank = process.env.CAIRN_MEMORY_RERANK;
   const exitCodeBeforeDoctor = process.exitCode;
   const doctorWrite = process.stdout.write.bind(process.stdout);
   let doctorOutput = "";
   delete process.env.CAIRN_LLM_API_URL;
+  delete process.env.CAIRN_MEMORY_RERANK;
   process.stdout.write = ((chunk) => { doctorOutput += String(chunk); return true; });
   try {
     await runWindowsCommand({ command: "doctor", args: ["--repair"], root });
@@ -100,9 +102,12 @@ try {
     process.exitCode = exitCodeBeforeDoctor;
     if (inheritedLlmUrl === undefined) delete process.env.CAIRN_LLM_API_URL;
     else process.env.CAIRN_LLM_API_URL = inheritedLlmUrl;
+    if (inheritedRerank === undefined) delete process.env.CAIRN_MEMORY_RERANK;
+    else process.env.CAIRN_MEMORY_RERANK = inheritedRerank;
   }
   assert.equal(existsSync(invalidDerivedPack), false, "native Windows doctor forwards safe context-pack cache repair");
   assert.match(doctorOutput, /\[PASS\] context pack diagnostics passed/);
+  assert.match(doctorOutput, /\[SKIP\] memory reranker unset\/not 1/);
 
   let containerArgs = [];
   runNativeContainer(["stdio", "--image", "example/windows:1", "--volume", "windows-data"], root, (_engine, args) => { containerArgs = args; });