@cairnkeep/cli 1.0.5 → 1.1.0

package/docs/building-an-overlay.md

@@ -107,6 +107,13 @@ All optional, all env-gated — a wrapper turns them on by setting the env:
 Point the RAG sync script at your own copy (`CAIRN_ANYTHINGLLM_SYNC_SCRIPT`) so the
 integration scripts live in your overlay, not the core.
 
+For a fleet that shares one trusted HTTP service, have the overlay generate
+project-local Claude Code and OpenCode MCP entries with `X-Cairn-Project`,
+`X-Cairn-Scopes`, and `X-Cairn-AnythingLLM-Workspaces`. This preserves local
+project isolation and workspace defaults while keeping the databases and RAG
+credentials on the server host. Keep bearer tokens in environment-backed
+secret storage, not generated project files.
+
 ## Checklist
 
 - [ ] cairnkeep pinned to a version; no core files copied or patched

package/docs/domain-knowledge.md

@@ -45,6 +45,18 @@ first of `.agent/memory.json`, `.opencode/memory.json`, `.claude/memory.json`, o
 configured workspace that is not `engineering-patterns` (the conventional shared
 workspace). With no workspace given and none configured, it errors.
 
+In local stdio mode, that config is read from the client project's working
+directory. In remote HTTP mode, the server cannot read files from the client
+PC. Configure `ANYTHINGLLM_BASE_URL`, `ANYTHINGLLM_API_KEY`, and any sync script
+on the HTTP server host, then send the project workspaces in the
+`X-Cairn-AnythingLLM-Workspaces` session header. See
+[Memory storage and deployment](storage.md#per-project-remote-sessions).
+
+The HTTP server performs queries and runs the sync script on its own host. A
+remote sync script must therefore obtain project documents from a server-side
+checkout, object store, or git host; it cannot read an arbitrary client PC's
+working tree.
+
 ## Setup (query)
 
 ```bash

package/docs/operating.md

@@ -267,9 +267,11 @@ is guarded and **fails closed**:
 Requests without a valid bearer token get `401`; requests with an unexpected
 `Host` header get `403`. Keep HTTP mode bound to `127.0.0.1` unless you have a
 specific reason to expose it, and use a long random token. HTTP mode has no
-per-user ACL or tenant isolation, and every client shares the server process's
-`project` database. See [Memory storage and deployment](storage.md) for the
-placement rules, client registration, TLS requirements, and backup boundaries.
+per-user ACL or tenant isolation. Clients may bind sessions to separate project
+databases with validated `X-Cairn-Project` routing metadata, but that metadata
+is not an authorization boundary. See [Memory storage and deployment](storage.md)
+for the placement rules, client registration, TLS requirements, project headers,
+and backup boundaries.
 
 ## The workflow
 

package/docs/storage.md

@@ -53,12 +53,34 @@ With this topology, the databases are on the server host, not the client PC.
 Setting `CAIRN_AGENTFS_BASE_DIR` on the client does not redirect a remote
 server; set it in the server service environment.
 
+### Per-project remote sessions
+
+Remote clients can bind an MCP session to a stable project identity and send
+the memory configuration that a local server would read from `memory.json`:
+
+| Header | Purpose |
+|---|---|
+| `X-Cairn-Project` | Kebab-case project identity, up to 64 characters |
+| `X-Cairn-Scopes` | Comma-separated scopes used when a tool reads scope `all` |
+| `X-Cairn-AnythingLLM-Workspaces` | Comma-separated AnythingLLM workspace slugs; the first non-`engineering-patterns` workspace is the default |
+
+When `X-Cairn-Project` is present, `project` scope is stored at
+`${CAIRN_AGENTFS_BASE_DIR}/projects/<project-id>.db`. Sessions with different
+project identities therefore do not share project memory. Without the header,
+HTTP mode retains the legacy behavior and resolves `project` from the server
+working directory.
+
+These headers are session routing metadata, not authorization. The bearer
+token still grants access to the entire server, including the ability to choose
+another valid project identity. Use separate server instances for separate
+trust domains.
+
 HTTP mode is one trusted storage domain:
 
 - One bearer token grants access to every exposed memory tool.
 - There is no per-user ACL, tenant isolation, or client-specific filesystem.
-- `project` scope resolves from the server process's working directory, so all
-  HTTP clients of that process share the same `project.db`.
+- Sessions without `X-Cairn-Project` share the project database resolved from
+  the server process's working directory.
 - Use one server instance per isolation boundary. Do not offer one instance to
   mutually untrusted users.
 - Keep the Cairnkeep listener on loopback behind a TLS reverse proxy, or use an
@@ -132,3 +154,10 @@ Ensure the secret-manager bootstrap exports `CAIRN_MEMORY_HTTP_TOKEN` before
 OpenCode starts. Preserve any other keys already present in `opencode.json`
 rather than replacing the whole file. The URL, token, private host names, and
 device-specific configuration must never be committed to this public project.
+
+For distinct project memory, install a project-local MCP entry with the same
+URL and authorization header plus the three routing headers. Claude Code
+expands `${VAR}` references in project `.mcp.json` URL and header values;
+OpenCode uses `{env:VAR}` references. A private overlay should generate and
+merge these files so secrets remain in the process environment rather than the
+repository.

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

@@ -13,6 +13,8 @@ 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
@@ -22,6 +24,8 @@ const anythingllmSyncScript = process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT
     ? resolve(expandHome(process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT))
     : join(infraRoot, "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 +90,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 +162,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 +188,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 +204,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 +424,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 +451,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 +711,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 +732,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 +765,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 +805,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 +819,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 +845,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 +885,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 +935,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 +955,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 +982,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 +1233,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 +1249,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 +1286,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.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",