@cairnkeep/cli 1.0.5 → 1.1.1

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

@@ -13,15 +13,18 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod";
 import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashText, } from "./embeddings.js";
 import { computeRepoState, exploreCacheKey, normalizeExploreQuery, readExploreCache, writeExploreCache, } from "./explore-cache.js";
+class ClientContextError extends Error {
+}
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 const infraRoot = resolve(moduleDir, "..", "..");
-// Path to the domain-knowledge sync script. Defaults to a script bundled next to
-// this repo, but a wrapper can point CAIRN_ANYTHINGLLM_SYNC_SCRIPT at its own copy
-// (the integration scripts often live in the wrapper, not the core).
+// Path to the bundled deployment-neutral sync script. An overlay can replace it
+// with a deployment-specific implementation.
 const anythingllmSyncScript = process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT
     ? resolve(expandHome(process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT))
-    : join(infraRoot, "anythingllm", "sync_to_anythingllm.py");
+    : join(infraRoot, "examples", "anythingllm", "sync_to_anythingllm.py");
 const HISTORY_NAMESPACE = "__history__";
+const PROJECT_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const WORKSPACE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 function expandHome(value) {
     if (value === "~") {
         return homedir();
@@ -86,9 +89,44 @@ function assertSafeScope(scope) {
         throw new Error(`Invalid scope "${scope}": must be kebab-case (^[a-z0-9][a-z0-9-]*$), "project", or "all".`);
     }
 }
-function resolveScopePath(scope, cwd = process.cwd()) {
+function parseHeaderList(headers, name, validate) {
+    const raw = headers.get(name)?.trim();
+    if (!raw) {
+        return undefined;
+    }
+    if (raw.length > 4096) {
+        throw new ClientContextError(`${name} is too long.`);
+    }
+    const values = Array.from(new Set(raw.split(",").map((value) => value.trim()).filter(Boolean)));
+    if (values.length > 32 || values.some((value) => !validate(value))) {
+        throw new ClientContextError(`${name} contains an invalid value.`);
+    }
+    return values;
+}
+function parseServerContext(headers) {
+    const rawProjectId = headers.get("x-cairn-project")?.trim();
+    if (rawProjectId && !PROJECT_ID_PATTERN.test(rawProjectId)) {
+        throw new ClientContextError("X-Cairn-Project must be a kebab-case identifier of at most 64 characters.");
+    }
+    const scopes = parseHeaderList(headers, "X-Cairn-Scopes", (value) => value !== "all" && (value === "project" || SCOPE_PATTERN.test(value)));
+    const anythingllmWorkspaces = parseHeaderList(headers, "X-Cairn-AnythingLLM-Workspaces", (value) => WORKSPACE_PATTERN.test(value));
+    const memoryConfig = scopes || anythingllmWorkspaces
+        ? {
+            scopes: scopes ?? ["identity"],
+            anythingllm_workspaces: anythingllmWorkspaces ?? [],
+        }
+        : undefined;
+    return {
+        projectId: rawProjectId || undefined,
+        memoryConfig,
+    };
+}
+function resolveScopePath(scope, options = {}) {
     if (scope === "project") {
-        return resolve(cwd, ".agentfs", "project.db");
+        if (options.projectId) {
+            return resolve(getBaseDir(), "projects", `${options.projectId}.db`);
+        }
+        return resolve(options.cwd ?? process.cwd(), ".agentfs", "project.db");
     }
     // "all" is a read-only virtual scope: memory_read/memory_search fan it out
     // over the configured scopes (via getSearchScopes) before resolving. It has
@@ -123,8 +161,8 @@ function normalizeValue(value) {
     }
     return JSON.stringify(value);
 }
-async function openScope(scope, create, cwd) {
-    const dbPath = resolveScopePath(scope, cwd);
+async function openScope(scope, create, options = {}) {
+    const dbPath = resolveScopePath(scope, options);
     if (!create && !existsSync(dbPath)) {
         return null;
     }
@@ -149,7 +187,7 @@ function visibleEntries(entries, includeHistory) {
     return entries.filter((entry) => !isHistoryKey(entry.key));
 }
 async function listEntries(scope, prefix = "", options = {}) {
-    const agent = await openScope(scope, false, options.cwd);
+    const agent = await openScope(scope, false, options);
     if (!agent) {
         return [];
     }
@@ -165,8 +203,8 @@ async function listEntries(scope, prefix = "", options = {}) {
         await agent.close();
     }
 }
-async function readKey(scope, key) {
-    const agent = await openScope(scope, false);
+async function readKey(scope, key, options = {}) {
+    const agent = await openScope(scope, false, options);
     if (!agent) {
         return [];
     }
@@ -385,14 +423,16 @@ async function callAnythingLLM(workspace, query) {
 function entryText(entry) {
     return entry.value ? `${entry.key}\n${entry.value}` : entry.key;
 }
-function embeddingCachePath(scope) {
-    return join(getBaseDir(), ".embeddings", `${hashText(resolveScopePath(scope))}.json`);
+function embeddingCachePath(scope, projectId) {
+    return join(getBaseDir(), ".embeddings", `${hashText(resolveScopePath(scope, { projectId }))}.json`);
 }
-async function semanticSearch(scope, query, topK, minScore) {
-    const config = getMemoryConfig();
+async function semanticSearch(scope, query, topK, minScore, config = getMemoryConfig(), projectId) {
     const scopes = getSearchScopes(scope, config);
     const embeddingConfig = getEmbeddingConfig();
-    const perScopeEntries = await Promise.all(scopes.map(async (candidate) => ({ scope: candidate, entries: await listEntries(candidate) })));
+    const perScopeEntries = await Promise.all(scopes.map(async (candidate) => ({
+        scope: candidate,
+        entries: await listEntries(candidate, "", { projectId }),
+    })));
     const allEntries = perScopeEntries.flatMap((group) => group.entries);
     if (allEntries.length === 0) {
         return { results: [], mode: embeddingConfig ? "semantic" : "substring" };
@@ -410,7 +450,7 @@ async function semanticSearch(scope, query, topK, minScore) {
         const caches = [];
         const vectors = new Map();
         for (const group of perScopeEntries) {
-            const cache = new EmbeddingCache(embeddingCachePath(group.scope), embeddingConfig.model);
+            const cache = new EmbeddingCache(embeddingCachePath(group.scope, projectId), embeddingConfig.model);
             caches.push(cache);
             const misses = [];
             for (const entry of group.entries) {
@@ -670,8 +710,10 @@ function gitToplevel(cwd) {
 // only allows one connected transport per server). All instances share the
 // module-level helpers + AgentFS below. Enables a single long-lived process to
 // serve many concurrent clients within one trusted server-side storage domain.
-function createMemoryServer() {
+function createMemoryServer(context = {}) {
     const server = new McpServer({ name: "cairn-memory", version: "0.1.0" });
+    const memoryConfig = () => context.memoryConfig ?? getMemoryConfig();
+    const scopeOptions = { projectId: context.projectId };
     server.registerTool("memory_read", {
         description: "Read an exact key or search memory entries across AgentFS scopes.",
         // Plain object schema — a .refine() wrapper (ZodEffects) makes the SDK
@@ -689,11 +731,11 @@ function createMemoryServer() {
         if (Boolean(key) === Boolean(query)) {
             throw new Error("Provide exactly one of key or query.");
         }
-        const config = getMemoryConfig();
+        const config = memoryConfig();
         const scopes = getSearchScopes(scope, config);
         const results = key
-            ? (await Promise.all(scopes.map((candidate) => readKey(candidate, key)))).flat()
-            : searchEntries((await Promise.all(scopes.map((candidate) => listEntries(candidate)))).flat(), query ?? "");
+            ? (await Promise.all(scopes.map((candidate) => readKey(candidate, key, scopeOptions)))).flat()
+            : searchEntries((await Promise.all(scopes.map((candidate) => listEntries(candidate, "", scopeOptions)))).flat(), query ?? "");
         const sorted = results.sort((left, right) => {
             return `${left.scope}:${left.key}`.localeCompare(`${right.scope}:${right.key}`);
         });
@@ -722,7 +764,7 @@ function createMemoryServer() {
         // disambiguated (rename keys, memory_history to recover).
         const collisions = [];
         for (const target of targets) {
-            const agent = await openScope(target, true);
+            const agent = await openScope(target, true, scopeOptions);
             if (!agent) {
                 throw new Error(`Unable to open scope ${target}.`);
             }
@@ -762,7 +804,7 @@ function createMemoryServer() {
             idempotentHint: true,
         },
     }, async ({ scope, prefix }) => {
-        const entries = await listEntries(scope, prefix ?? "");
+        const entries = await listEntries(scope, prefix ?? "", scopeOptions);
         const keys = entries.map((entry) => entry.key).sort();
         return {
             content: [{ type: "text", text: asToolText(keys) }],
@@ -776,7 +818,7 @@ function createMemoryServer() {
             key: z.string().min(1),
         }),
     }, async ({ scope, key }) => {
-        const agent = await openScope(scope, false);
+        const agent = await openScope(scope, false, scopeOptions);
         if (agent) {
             try {
                 await agent.kv.delete(key);
@@ -802,7 +844,7 @@ function createMemoryServer() {
             readOnlyHint: true,
         },
     }, async ({ scope, query, top_k, min_score }) => {
-        const { results, mode, model } = await semanticSearch(scope, query, top_k ?? 8, min_score ?? 0);
+        const { results, mode, model } = await semanticSearch(scope, query, top_k ?? 8, min_score ?? 0, memoryConfig(), context.projectId);
         const payload = { mode, model, count: results.length, results };
         return {
             content: [{ type: "text", text: asToolText(payload) }],
@@ -842,7 +884,7 @@ function createMemoryServer() {
         if (isHistoryKey(key)) {
             throw new Error(`Keys under ${HISTORY_NAMESPACE}/ are reserved for memory history.`);
         }
-        const agent = await openScope(scope, true);
+        const agent = await openScope(scope, true, scopeOptions);
         if (!agent) {
             throw new Error(`Unable to open scope ${scope}.`);
         }
@@ -892,8 +934,11 @@ function createMemoryServer() {
             idempotentHint: true,
         },
     }, async ({ scope, key }) => {
-        const current = await readKey(scope, key);
-        const history = (await listEntries(scope, historyPrefix(key), { includeHistory: true }))
+        const current = await readKey(scope, key, scopeOptions);
+        const history = (await listEntries(scope, historyPrefix(key), {
+            includeHistory: true,
+            ...scopeOptions,
+        }))
             .sort((left, right) => left.key.localeCompare(right.key));
         const payload = {
             scope,
@@ -909,17 +954,21 @@ function createMemoryServer() {
     server.registerTool("domain_knowledge_query", {
         description: "Query an AnythingLLM workspace in query mode for domain knowledge.",
         inputSchema: z.object({
-            workspace: z.string().min(1),
+            workspace: z.string().min(1).optional(),
             query: z.string().min(1),
         }),
         annotations: {
             readOnlyHint: true,
         },
     }, async ({ workspace, query }) => {
-        const answer = await callAnythingLLM(workspace, query);
+        const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(memoryConfig());
+        if (!workspaceSlug) {
+            throw new Error("No AnythingLLM workspace provided and no project workspace found in memory config.");
+        }
+        const answer = await callAnythingLLM(workspaceSlug, query);
         return {
             content: [{ type: "text", text: answer }],
-            structuredContent: { workspace, answer },
+            structuredContent: { workspace: workspaceSlug, answer },
         };
     });
     server.registerTool("domain_knowledge_sync", {
@@ -932,7 +981,7 @@ function createMemoryServer() {
         }),
     }, async ({ workspace, mode, confirm_replace, timeout_seconds }) => {
         const syncMode = mode ?? "incremental";
-        const config = getMemoryConfig();
+        const config = memoryConfig();
         const workspaceSlug = workspace ?? defaultAnythingLLMWorkspace(config);
         if (!workspaceSlug) {
             throw new Error("No AnythingLLM workspace provided and no project workspace found in memory config.");
@@ -1183,12 +1232,13 @@ if (httpPort > 0) {
         }
         // New session (first request = initialize). The transport mints a session
         // id and the SDK returns it via the response header; client echoes it back.
+        const context = parseServerContext(request.headers);
         const transport = new WebStandardStreamableHTTPServerTransport({
             sessionIdGenerator: () => randomUUID(),
             onsessioninitialized: (id) => { sessions.set(id, transport); },
             onsessionclosed: (id) => { sessions.delete(id); },
         });
-        const session = createMemoryServer();
+        const session = createMemoryServer(context);
         await session.connect(transport);
         return transport.handleRequest(request);
     };
@@ -1198,7 +1248,7 @@ if (httpPort > 0) {
             res.setHeader("Access-Control-Allow-Origin", allowOrigin);
             res.setHeader("Vary", "Origin");
             res.setHeader("Access-Control-Allow-Methods", "POST, GET, DELETE, OPTIONS");
-            res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id, Accept, Authorization");
+            res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id, Accept, Authorization, X-Cairn-Project, X-Cairn-Scopes, X-Cairn-AnythingLLM-Workspaces");
         }
         if (req.method === "OPTIONS") {
             res.writeHead(allowOrigin ? 204 : 403).end();
@@ -1235,7 +1285,8 @@ if (httpPort > 0) {
             res.end(Buffer.from(await response.arrayBuffer()));
         }
         catch (err) {
-            res.writeHead(500).end(err instanceof Error ? err.message : String(err));
+            const status = err instanceof ClientContextError ? 400 : 500;
+            res.writeHead(status).end(err instanceof Error ? err.message : String(err));
         }
     });
     httpServer.listen(httpPort, httpHost, () => {

package/mcp-memory-server/package.json

@@ -14,12 +14,13 @@
         "check:search": "node scripts/smoke-search-e2e.mjs",
         "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: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",
         "check:route-guard": "node scripts/smoke-route-guard.mjs",
         "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:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard",
+        "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",
         "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": "1.0.5",
+  "version": "1.1.1",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,7 +16,9 @@
     "templates/",
     "claude/",
     "opencode/",
+    "examples/anythingllm/",
     "docs/",
+    "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md",
     "mcp-memory-server/dist/",
@@ -36,8 +38,8 @@
     "fix:perms": "git ls-files -s | awk '$1==\"100755\"{print $4}' | xargs chmod 755",
     "prepack": "npm run build:server && npm run fix:perms",
     "test": "for test in scripts/test-*.sh; do \"$test\" || exit 1; done",
-    "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm test",
-    "prepublishOnly": "npm run check:public && npm run build:server && npm --prefix mcp-memory-server test --global=false --dry-run=false"
+    "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm run build:server && npm test",
+    "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server test --global=false --dry-run=false"
   },
   "repository": {
     "type": "git",

package/scripts/probe-memory-server.mjs

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 
-const serverPath = process.argv[2];
-if (!serverPath) {
-  console.error("usage: probe-memory-server.mjs PATH_TO_SERVER");
+const probeArgs = process.argv.slice(2);
+if (probeArgs.length === 0) {
+  console.error("usage: probe-memory-server.mjs PATH_TO_SERVER | --command COMMAND [ARGS...]");
   process.exit(2);
 }
 
-const child = spawn(process.execPath, [serverPath], {
+const commandMode = probeArgs[0] === "--command";
+const command = commandMode ? probeArgs[1] : process.execPath;
+const commandArgs = commandMode ? probeArgs.slice(2) : [probeArgs[0]];
+if (!command) {
+  console.error("probe-memory-server.mjs: --command requires a command");
+  process.exit(2);
+}
+
+const child = spawn(command, commandArgs, {
   env: process.env,
   stdio: ["pipe", "pipe", "pipe"],
 });
@@ -29,7 +37,11 @@ const response = new Promise((resolve, reject) => {
       if (!line.trim()) continue;
       try {
         const message = JSON.parse(line);
-        if (message.id === 1 && message.result?.serverInfo?.name === "cairn-memory") {
+        if (
+          message.id === 1 &&
+          message.result?.serverInfo?.name === "cairn-memory" &&
+          message.result?.capabilities?.tools
+        ) {
           resolve();
           return;
         }

package/scripts/smoke-mcp-boot.sh

@@ -5,35 +5,28 @@
 # transport works. This is the core product path, and nothing else tests it
 # after packaging/installation.
 #
-# Prefers `cairn memory-server` (a global install), else falls back to node on
-# the repo's dist build — so it works both post-install and from a clone.
+# Prefers `cairn memory-server` (a global install), else falls back to the
+# repository build. The Node probe owns the timeout so this works on macOS,
+# which does not ship GNU `timeout`.
 set -uo pipefail
 
 ROOT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 
 if command -v cairn >/dev/null 2>&1; then
-  server=(cairn memory-server)
+  probe=(node "$ROOT_DIR/scripts/probe-memory-server.mjs" --command cairn memory-server)
 elif [[ -f "$ROOT_DIR/mcp-memory-server/dist/index.js" ]]; then
-  server=(node "$ROOT_DIR/mcp-memory-server/dist/index.js")
+  probe=(node "$ROOT_DIR/scripts/probe-memory-server.mjs" "$ROOT_DIR/mcp-memory-server/dist/index.js")
 else
   echo "smoke-mcp-boot: FAIL (no cairn on PATH and no dist build to run)"
   exit 1
 fi
 
-req='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"ci","version":"0"}}}'
-
 tmp=$(mktemp -d)
 trap 'rm -rf "$tmp"' EXIT
 
-# HOME points at a throwaway dir so the server's default store (~/.cairnkeep)
-# lands there; `head -1` closes stdin after the first reply, so the server sees
-# EOF and exits cleanly.
-out=$(printf '%s\n' "$req" | HOME="$tmp" timeout 15 "${server[@]}" 2>/dev/null | head -1)
-
-if grep -q '"result"' <<<"$out" && grep -q '"tools"' <<<"$out"; then
+if HOME="$tmp" "${probe[@]}"; then
   echo "smoke-mcp-boot: OK (server booted, initialize returned tools capability)"
   exit 0
 fi
 echo "smoke-mcp-boot: FAIL (no valid initialize response)"
-echo "  got: ${out:0:200}"
 exit 1

package/scripts/test-package-install.sh

@@ -29,4 +29,8 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 
 (cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"
 
+installed_root="$tmp/prefix/lib/node_modules/@cairnkeep/cli"
+[[ -f "$installed_root/examples/anythingllm/sync_to_anythingllm.py" ]] || \
+  fail "npm tarball omitted the default AnythingLLM sync script"
+
 echo "PASS: npm tarball installs a self-contained CLI and MCP server"

package/templates/env.example.template

@@ -27,3 +27,9 @@
 # Optional: comma-separated allowed Host headers for DNS-rebinding protection
 # (default: the bind host + localhost on the chosen port).
 # CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=
+#
+# Optional document-RAG sync. API credentials and endpoint may be local or remote.
+# ANYTHINGLLM_BASE_URL=http://localhost:3001
+# ANYTHINGLLM_API_KEY=
+# CAIRN_ANYTHINGLLM_PROJECTS_FILE=~/.config/cairnkeep/anythingllm-projects.json
+# CAIRN_ANYTHINGLLM_STATE_FILE=~/.local/state/cairnkeep/anythingllm-sync.json