@cairnkeep/cli 1.0.4 → 1.1.0

package/README.md

@@ -27,7 +27,8 @@ cairnkeep-org sibling project.
   embedding-ranked search against any OpenAI-compatible endpoint.
 - **`bin/cairn`** — the CLI. `cairn bootstrap [path]` scaffolds a project's
   `.ai/` launchers + env; `cairn doctor` health-checks the configured pieces;
-  `cairn memory export|import` relocates the durable store between machines;
+  `cairn memory export|import` relocates the durable store between machines
+  (`export` requires the optional `sqlite3` CLI);
   `cairn audit-timer` installs the scheduled memory+wiki audit; `cairn uninstall`
   reverses the install (backup-first, revertible).
 - **`templates/`** — project scaffolding (generic launchers, env) plus the
@@ -60,6 +61,11 @@ operating layer (commands, agents, hooks) installed into your harness, and a
 bootstrapped project. `cairn bootstrap` does only the last of these — the full
 ordered walkthrough is in **[docs/operating.md](docs/operating.md)**.
 
+This setup is local by default: the registered stdio server stores memory on
+the user's computer. Cairnkeep never discovers or selects a remote host.
+Remote HTTP storage requires an explicit server deployment and client URL; see
+**[Memory storage and deployment](docs/storage.md)** before enabling it.
+
 The short version for Claude Code:
 
 ```bash
@@ -106,7 +112,7 @@ unless a wrapper opts in:
 
 **Contributor mode.** Working on a repo you don't own? `cairn bootstrap
 --untracked /path/to/project` additionally writes the scaffolded paths
-(`.ai/`, `.planning/`) into the repo's `.git/info/exclude`, so the workflow
+(`.ai/`, `.planning/`, `.agentfs/`) into the repo's `.git/info/exclude`, so the workflow
 files stay purely local: nothing to commit or push, invisible to every other
 contributor, and no edit to the shared `.gitignore`. The trade-off is that
 untracked planning state lives only on that clone — deleting the clone
@@ -141,6 +147,7 @@ Without an API key, search degrades gracefully to substring matching.
 - **Optional document RAG** (`domain_knowledge_*` via AnythingLLM) — [docs/domain-knowledge.md](docs/domain-knowledge.md)
 - **Building a private overlay** (wrap cairnkeep for your org/provider) — [docs/building-an-overlay.md](docs/building-an-overlay.md)
 - **Full operating guide** — [docs/operating.md](docs/operating.md)
+- **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md)
 - **Security policy** — [SECURITY.md](SECURITY.md)

package/bin/cairn

@@ -15,6 +15,43 @@ CAIRN_ROOT=$(cd -P "$(dirname "$SOURCE")/.." && pwd)
 cmd="${1:-help}"
 [[ $# -gt 0 ]] && shift
 
+usage() {
+  cat <<'USAGE'
+cairn — Cairnkeep CLI
+
+Usage:
+  cairn bootstrap [--untracked] [path]
+                           Scaffold launchers, planning files, and the private
+                           project-memory ignore guard (default path: .).
+                           --untracked keeps the scaffold out of git via the repo's
+                           .git/info/exclude (contributor mode: nothing to commit,
+                           invisible to other contributors, local-only).
+  cairn memory-server      Run the memory MCP server (stdio). Register it with your
+                           harness, e.g. claude mcp add cairn-memory -s user -- cairn memory-server.
+  cairn sync [--apply] [--live-root DIR]
+                           Install/update the Claude Code operating layer (commands,
+                           agents, hooks) into ~/.claude, or into DIR for a single
+                           project (--live-root <project>/.claude).
+  cairn doctor             Health-check the memory server and configured LLM /
+                           embedding endpoints, git provider, and store.
+  cairn memory <path|export|import>
+                           Relocate global-scope memory. `path` prints its location;
+                           `export <file.tgz>` takes a WAL-safe snapshot (requires
+                           sqlite3); `import <file.tgz>` restores it.
+  cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
+                           Install (opt-in) a systemd user timer that runs the
+                           memory+wiki audit on a schedule; prints a cron alternative.
+  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--live-root DIR] [PROJECT ...]
+                           Reverse what cairnkeep installed/modified (operating
+                           layer, hook registrations, MCP registration, audit
+                           timer, and any given projects' bootstrap scaffold).
+                           Backs everything up first with a revert.sh; keeps the
+                           durable memory store unless --purge-memory is given.
+  cairn version            Print version
+  cairn help               Show this help
+USAGE
+}
+
 case "$cmd" in
   bootstrap)
     exec "$CAIRN_ROOT/scripts/bootstrap.sh" "$@"
@@ -43,40 +80,12 @@ case "$cmd" in
     v=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$CAIRN_ROOT/package.json" 2>/dev/null | head -1)
     echo "cairnkeep ${v:-unknown}"
     ;;
-  help | --help | -h | *)
-    cat <<'USAGE'
-cairn — Cairnkeep CLI
-
-Usage:
-  cairn bootstrap [--untracked] [path]
-                           Scaffold .ai/ launchers + env into a project (default: .).
-                           --untracked keeps the scaffold out of git via the repo's
-                           .git/info/exclude (contributor mode: nothing to commit,
-                           invisible to other contributors, local-only).
-  cairn memory-server      Run the memory MCP server (stdio). Register it with your
-                           harness, e.g. claude mcp add cairn-memory -s user -- cairn memory-server.
-  cairn sync [--apply] [--live-root DIR]
-                           Install/update the Claude Code operating layer (commands,
-                           agents, hooks) into ~/.claude, or into DIR for a single
-                           project (--live-root <project>/.claude).
-  cairn doctor             Health-check the configured pieces (memory server, LLM /
-                           embedding endpoints, git provider, store); skips what is
-                           unconfigured, fails only on a configured-but-unreachable dep.
-  cairn memory <path|export|import>
-                           Relocate the durable memory store. `path` prints its
-                           location; `export <file.tgz>` takes a WAL-safe snapshot;
-                           `import <file.tgz>` restores it on another machine.
-  cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
-                           Install (opt-in) a systemd user timer that runs the
-                           memory+wiki audit on a schedule; prints a cron alternative.
-  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--live-root DIR] [PROJECT ...]
-                           Reverse what cairnkeep installed/modified (operating
-                           layer, hook registrations, MCP registration, audit
-                           timer, and any given projects' bootstrap scaffold).
-                           Backs everything up first with a revert.sh; keeps the
-                           durable memory store unless --purge-memory is given.
-  cairn version            Print version
-  cairn help               Show this help
-USAGE
+  help | --help | -h)
+    usage
+    ;;
+  *)
+    echo "Unknown command: $cmd" >&2
+    usage >&2
+    exit 2
     ;;
 esac

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

@@ -18,12 +18,19 @@ installs. This guide covers all three in order.
 
 - Node.js (for the memory server) and a supported harness: Claude Code or
   OpenCode.
+- Optional: the `sqlite3` CLI for `cairn memory export`. Runtime memory and
+  `cairn memory import` do not require it.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
   embedding-ranked search. Without it, memory search degrades to substring
   matching — everything else still works.
 
 ## Setup order (Claude Code)
 
+The commands below install the default local topology: `cairn-memory` runs as a
+stdio child process and writes SQLite databases on this computer. Nothing in
+the installer discovers or selects a remote host. Read
+[Memory storage and deployment](storage.md) before choosing remote HTTP mode.
+
 **Via npm** (simplest — everything is on `PATH` as `cairn`):
 
 ```bash
@@ -52,7 +59,7 @@ claude mcp add cairn-memory -s user -- node "$PWD/mcp-memory-server/dist/index.j
 scripts/sync-claude-assets.sh --apply
 
 # 4. Scaffold a target project
-cairn bootstrap /path/to/project
+bin/cairn bootstrap /path/to/project
 cp /path/to/project/.ai/env.example /path/to/project/.ai/.env
 $EDITOR /path/to/project/.ai/.env    # see "Configuration" below
 # Not the repo's owner? Add --untracked to keep the scaffold out of git
@@ -139,7 +146,7 @@ vendor or host.
 | `CAIRN_LLM_EXTRACTION_MODEL` | Chat model for `memory-capture` extraction |
 | `CAIRN_MEMORY_EMBEDDING_URL` | Embeddings endpoint (falls back to `CAIRN_LLM_API_URL`) |
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
-| `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
+| `CAIRN_AGENTFS_BASE_DIR` | Server-side base dir for named/global memory scopes (default `~/.cairnkeep`); it does not affect `project` scope |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none`. See [git-providers.md](git-providers.md) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → the `route_check` tool is inert) |
 | `CAIRN_EXPLORE_BINARY` | Absolute path to the `token_miser` binary used by `context_explore` (unset → the tool throws at call time) |
@@ -243,10 +250,11 @@ Claude-Code-only path this milestone — there is no OpenCode parity plugin.
 
 ### HTTP transport (opt-in, network-facing)
 
-The server runs over stdio by default. Setting `MCP_HTTP_PORT` switches it to a
-streamable HTTP transport so one long-lived process can serve many clients — but
-because that exposes every memory tool over the network, HTTP mode is guarded and
-**fails closed**:
+The server runs locally over stdio by default. Setting `MCP_HTTP_PORT` switches
+it to a streamable HTTP transport so one long-lived process can serve many
+clients within one trusted storage domain. The databases then live on the HTTP
+server host. Because that exposes every memory tool over the network, HTTP mode
+is guarded and **fails closed**:
 
 | Variable | Purpose |
 |---|---|
@@ -258,7 +266,12 @@ because that exposes every memory tool over the network, HTTP mode is guarded an
 
 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.
+specific reason to expose it, and use a long random token. HTTP mode has no
+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
 
@@ -335,9 +348,11 @@ its settings file and exports `CAIRN_EXTRA_SETTINGS` — no change to the launch
 
 ### `cairn doctor`
 
-Health-checks the configured pieces, reading only `./.ai/.env` (or the current
-env). Unconfigured optional dependencies are skipped; it exits non-zero only when
-a configured dependency (LLM/embedding endpoint, writable store) is unreachable.
+Health-checks the bundled local memory server with a real MCP stdio handshake,
+then checks `./.ai/.env` (or the current environment). It does not inspect a
+harness's remote HTTP registration. Unconfigured optional dependencies are
+skipped; it exits non-zero when the local server probe fails or a configured
+dependency (LLM/embedding endpoint, writable store) is unreachable.
 
 ```bash
 cd /path/to/project && cairn doctor
@@ -345,7 +360,7 @@ cd /path/to/project && cairn doctor
 
 ### `cairn memory export|import|path`
 
-Relocate the durable memory store (one SQLite `.db` per scope under
+Relocate named/global memory (one SQLite `.db` per scope under
 `CAIRN_AGENTFS_BASE_DIR`) between machines or backends:
 
 ```bash
@@ -354,6 +369,11 @@ cairn memory export store.tgz        # WAL-safe snapshot of every scope db
 cairn memory import store.tgz        # restore on another machine (backs up existing)
 ```
 
+`cairn memory export` requires the `sqlite3` CLI so it can use SQLite's online
+backup operation and produce a consistent snapshot while WAL mode is active.
+It does not include project memory at `<project>/.agentfs/project.db`; see
+[Memory storage and deployment](storage.md) for project backup instructions.
+
 ### `cairn audit-timer`
 
 `memory-wiki-audit.sh` is the deterministic invalidation backstop meant to run on

package/docs/storage.md

@@ -0,0 +1,163 @@
+# Memory storage and deployment
+
+## The placement rule
+
+Cairnkeep stores memory on the filesystem of the machine running the
+`cairn-memory` server process. It does not discover a cloud service, VPS, or
+shared host, and installing the npm package does not contact one.
+
+The standard registration is local:
+
+```bash
+claude mcp add cairn-memory -s user -- cairn memory-server
+```
+
+This starts `cairn memory-server` as a local stdio child process. With that
+registration, memory remains on that computer.
+
+| Scope | Database path |
+|---|---|
+| `project` | `<server working directory>/.agentfs/project.db` |
+| Any named/global scope, such as `identity` or `work` | `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/<scope>.db` |
+
+For the local launchers, the server working directory is normally the project
+root. Bootstrap installs `.agentfs/.gitignore` so private project memory is not
+accidentally committed. SQLite may also create `-wal` and `-shm` sidecar files.
+
+`CAIRN_LLM_API_URL` and `CAIRN_MEMORY_EMBEDDING_URL` select optional model
+services used to process/search memory. They do not change where the SQLite
+databases are stored. Git-provider and routing configuration do not change
+storage either.
+
+## Remote HTTP mode
+
+Remote storage is explicit. An operator starts Cairnkeep in HTTP mode on a
+server, configures storage in that server process's environment, and registers
+the resulting URL in each client harness. For example:
+
+```bash
+# On the server host. Put TLS in front of this listener before remote use.
+CAIRN_AGENTFS_BASE_DIR=/var/lib/cairnkeep \
+CAIRN_MEMORY_HTTP_TOKEN="$(openssl rand -hex 32)" \
+CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=memory.example.com \
+MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=7801 \
+cairn memory-server
+
+# On a client. CAIRN_MEMORY_HTTP_TOKEN must contain the server's token.
+claude mcp add --transport http -s user \
+  --header "Authorization: Bearer $CAIRN_MEMORY_HTTP_TOKEN" \
+  cairn-memory https://memory.example.com/mcp
+```
+
+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.
+- 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
+  encrypted private network. Do not expose its raw HTTP listener publicly.
+
+## Inspecting and moving memory
+
+For a local server, these commands report and move named/global scopes only:
+
+```bash
+cairn memory path
+cairn memory export global-memory.tgz
+cairn memory import global-memory.tgz
+```
+
+`cairn memory path` reports the local process's global-scope directory; it
+cannot inspect a harness's remote HTTP registration. Export uses SQLite's
+online backup operation and requires the `sqlite3` CLI.
+
+Project memory is separate at `<project>/.agentfs/project.db` and is not
+included in `cairn memory export`. Back it up while the server is stopped, or
+take an online snapshot with SQLite:
+
+```bash
+sqlite3 /path/to/project/.agentfs/project.db \
+  ".backup '/safe/path/project-memory.db'"
+```
+
+Treat every database and export archive as sensitive. They may contain source
+paths, decisions, incident details, and other project context.
+
+## Automating trusted personal clients
+
+Keep fleet-specific values in a private dotfiles repository or secret manager,
+not in Cairnkeep. A personal bootstrap can install the public package and then
+perform the explicit remote registration:
+
+```bash
+# Populate these from a private secret manager on each trusted PC.
+export CAIRN_MEMORY_REMOTE_URL=https://memory.example.com/mcp
+export CAIRN_MEMORY_HTTP_TOKEN=replace-from-secret-manager
+
+npm install -g @cairnkeep/cli
+
+claude mcp remove cairn-memory -s user 2>/dev/null || true
+claude mcp add --transport http -s user \
+  cairn-memory "$CAIRN_MEMORY_REMOTE_URL" \
+  --header "Authorization: Bearer $CAIRN_MEMORY_HTTP_TOKEN"
+```
+
+OpenCode is configured separately in its per-user `opencode.json`. It supports
+environment references in remote MCP headers, so the token does not need to be
+written literally into the JSON:
+
+```json
+{
+  "mcp": {
+    "cairn-memory": {
+      "type": "remote",
+      "url": "https://memory.example.com/mcp",
+      "oauth": false,
+      "headers": {
+        "Authorization": "Bearer {env:CAIRN_MEMORY_HTTP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+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) {
@@ -669,9 +710,11 @@ function gitToplevel(cwd) {
 // Factory: each MCP client/session needs its own McpServer instance (the SDK
 // 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 (centralized AgentFS on the VPS).
-function createMemoryServer() {
+// serve many concurrent clients within one trusted server-side storage domain.
+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.4",
+  "version": "1.1.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,10 +32,12 @@
     "zod": "^3.25.76"
   },
   "scripts": {
-    "prepack": "git ls-files -s | awk '$1==\"100755\"{print $4}' | xargs chmod 755",
+    "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",
+    "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 --prefix mcp-memory-server ci && npm --prefix mcp-memory-server test"
+    "prepublishOnly": "npm run check:public && npm run build:server && npm --prefix mcp-memory-server test --global=false --dry-run=false"
   },
   "repository": {
     "type": "git",

package/scripts/bootstrap.sh

@@ -57,6 +57,10 @@ install_file "$TPL/start-claude.sh.template"   "$target/.ai/start-claude.sh"   0
 install_file "$TPL/start-opencode.sh.template" "$target/.ai/start-opencode.sh" 0755
 install_file "$TPL/env.example.template"       "$target/.ai/env.example"       0644
 
+# Project-scope memory is private runtime data. Keep it out of version control
+# even before the first .agentfs/project.db is created.
+install_file "$TPL/agentfs-gitignore.template" "$target/.agentfs/.gitignore" 0644
+
 # .planning/ derived-knowledge layer  (template : destination)
 planning_pairs=(
   "planning-config.json.template:.planning/config.json"
@@ -77,7 +81,7 @@ done
 
 if [[ $untracked -eq 1 ]]; then
   mkdir -p "$(dirname "$exclude_file")"
-  for entry in "/${exclude_prefix}.ai/" "/${exclude_prefix}.planning/"; do
+  for entry in "/${exclude_prefix}.ai/" "/${exclude_prefix}.planning/" "/${exclude_prefix}.agentfs/"; do
     if grep -qxF "$entry" "$exclude_file" 2>/dev/null; then
       echo "skip (already excluded): $entry"
     else
@@ -93,7 +97,7 @@ echo
 echo "Cairnkeep bootstrapped into $target"
 echo "Next steps (full guide: docs/operating.md):"
 echo "  1. cp .ai/env.example .ai/.env  and edit"
-echo "  2. Build + register the memory server: cd mcp-memory-server && npm install && npm run build,"
-echo "     then: claude mcp add cairn-memory -s user -- node \"\$PWD/dist/index.js\""
-echo "  3. Install the operating layer (commands/agents/hooks): scripts/sync-claude-assets.sh --apply"
+echo "  2. Register the memory server: claude mcp add cairn-memory -s user -- cairn memory-server"
+echo "  3. Install the operating layer (commands/agents/hooks): cairn sync --apply"
+echo "     From a source clone, use bin/cairn in place of cairn."
 echo "  4. Launch: $target/.ai/start-claude.sh"

package/scripts/doctor.sh

@@ -3,9 +3,9 @@
 #
 # Reports pass/warn/skip/fail for the pieces cairnkeep needs, reading only what
 # is already configured in ./.ai/.env (or the current environment). Unconfigured
-# optional dependencies are SKIPPED, never failed. Exits non-zero only if a
-# CONFIGURED dependency is unreachable, so a green run means "the things you
-# turned on actually work".
+# optional dependencies are SKIPPED, never failed. The required memory server
+# is checked with a real MCP initialize exchange. Exits non-zero if that probe
+# fails or a configured dependency is unreachable.
 set -uo pipefail
 
 CAIRN_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
@@ -30,11 +30,18 @@ reachable() { curl -sS -m 5 -o /dev/null "$1" >/dev/null 2>&1; }
 
 echo "cairn doctor"
 
-# 1. Memory server built (local prerequisite; actionable warning, not a failure).
-if [[ -f "$CAIRN_ROOT/mcp-memory-server/dist/index.js" ]]; then
-  pass "memory server built (mcp-memory-server/dist/index.js)"
+# 1. Required memory server: prove that the shipped build and dependencies can
+#    complete an MCP stdio handshake, rather than only checking for one file.
+server="$CAIRN_ROOT/mcp-memory-server/dist/index.js"
+probe="$CAIRN_ROOT/scripts/probe-memory-server.mjs"
+if ! command -v node >/dev/null 2>&1; then
+  fail "Node.js not found (Node.js 18 or newer is required)"
+elif [[ ! -f "$server" ]]; then
+  fail "memory server not built — run: (cd \"$CAIRN_ROOT/mcp-memory-server\" && npm install && npm run build)"
+elif node "$probe" "$server" >/dev/null 2>&1; then
+  pass "bundled local memory server responds over MCP stdio"
 else
-  warn "memory server not built — run: (cd \"$CAIRN_ROOT/mcp-memory-server\" && npm install && npm run build)"
+  fail "memory server failed its MCP stdio probe — reinstall cairnkeep or rebuild mcp-memory-server"
 fi
 
 # 2. LLM extraction endpoint (optional; unset → substring-only memory search).
@@ -83,6 +90,14 @@ else
   else fail "memory store parent not writable: $parent"; fi
 fi
 
+# 6. Optional backup dependency. Runtime memory and imports do not need it,
+#    but exports use sqlite3's .backup command for a consistent WAL snapshot.
+if command -v sqlite3 >/dev/null 2>&1; then
+  pass "sqlite3 available (memory export enabled)"
+else
+  warn "sqlite3 not found — memory export unavailable (runtime and import unaffected)"
+fi
+
 echo
 if [[ "$fails" -gt 0 ]]; then
   echo "cairn doctor: $fails configured dependency check(s) failed."

package/scripts/memory-store.sh

@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
-# cairn memory <path|export|import> — relocate the durable memory store between
-# machines or backends.
+# cairn memory <path|export|import> — relocate global-scope memory between
+# machines or backends. Project-scope memory lives in <project>/.agentfs/ and
+# is intentionally outside this command's base directory.
 #
-# The store is one SQLite .db per scope under CAIRN_AGENTFS_BASE_DIR
-# (default ~/.cairnkeep). `export` takes a WAL-safe snapshot of every scope db
-# into a portable archive; `import` restores them on another machine; `path`
-# prints the store location so nothing has to guess where it lives.
+# The global store is one SQLite .db per named scope under
+# CAIRN_AGENTFS_BASE_DIR (default ~/.cairnkeep). `export` takes a WAL-safe
+# snapshot of every global-scope db into a portable archive; `import` restores
+# them on another machine; `path` prints the global store location.
 set -euo pipefail
 
 base="${CAIRN_AGENTFS_BASE_DIR:-$HOME/.cairnkeep}"
@@ -14,9 +15,9 @@ base="${base/#\~/$HOME}"
 usage() {
   cat <<'EOF'
 Usage: cairn memory <path|export|import>
-  path                 Print the memory store base directory.
-  export <file.tgz>    WAL-safe snapshot of every scope .db into a portable archive.
-  import <file.tgz>    Restore scope .db files from an archive (backs up existing).
+  path                 Print the global-scope memory base directory.
+  export <file.tgz>    WAL-safe snapshot of every global-scope .db.
+  import <file.tgz>    Restore global-scope .db files (backs up existing).
 EOF
 }
 

package/scripts/probe-memory-server.mjs

@@ -0,0 +1,69 @@
+#!/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");
+  process.exit(2);
+}
+
+const child = spawn(process.execPath, [serverPath], {
+  env: process.env,
+  stdio: ["pipe", "pipe", "pipe"],
+});
+
+let stderr = "";
+child.stderr.setEncoding("utf8");
+child.stderr.on("data", (chunk) => {
+  stderr = (stderr + chunk).slice(-2000);
+});
+
+const response = new Promise((resolve, reject) => {
+  let buffered = "";
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    buffered += chunk;
+    const lines = buffered.split("\n");
+    buffered = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const message = JSON.parse(line);
+        if (message.id === 1 && message.result?.serverInfo?.name === "cairn-memory") {
+          resolve();
+          return;
+        }
+      } catch {
+        // Ignore non-protocol output while waiting for the initialize response.
+      }
+    }
+  });
+  child.once("error", reject);
+  child.once("exit", (code) => reject(new Error(`server exited with status ${code}`)));
+});
+
+const timeout = new Promise((_, reject) => {
+  setTimeout(() => reject(new Error("MCP initialize timed out")), 5000).unref();
+});
+
+const initialize = {
+  jsonrpc: "2.0",
+  id: 1,
+  method: "initialize",
+  params: {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "cairn-doctor", version: "1.0" },
+  },
+};
+
+try {
+  child.stdin.end(`${JSON.stringify(initialize)}\n`);
+  await Promise.race([response, timeout]);
+} catch (error) {
+  const detail = stderr.trim() || error.message;
+  console.error(`memory server probe failed: ${detail}`);
+  process.exitCode = 1;
+} finally {
+  child.kill();
+}

package/scripts/test-bootstrap-untracked.sh

@@ -24,18 +24,22 @@ git -C "$tmp/repo" init -q
 "$ROOT/scripts/bootstrap.sh" --untracked "$tmp/repo" >/dev/null
 [[ -f "$tmp/repo/.ai/start-claude.sh" ]] || fail "scaffold missing"
 [[ -f "$tmp/repo/.planning/config.json" ]] || fail "planning layer missing"
+[[ -f "$tmp/repo/.agentfs/.gitignore" ]] || fail "project-memory ignore guard missing"
 [[ -z "$(git -C "$tmp/repo" status --porcelain)" ]] || fail "scaffold visible to git"
 grep -qxF "/.ai/" "$tmp/repo/.git/info/exclude" || fail "missing /.ai/ exclude entry"
 grep -qxF "/.planning/" "$tmp/repo/.git/info/exclude" || fail "missing /.planning/ exclude entry"
+grep -qxF "/.agentfs/" "$tmp/repo/.git/info/exclude" || fail "missing /.agentfs/ exclude entry"
 
 # Re-run is idempotent: no duplicate exclude entries
 "$ROOT/scripts/bootstrap.sh" --untracked "$tmp/repo" >/dev/null
 [[ $(grep -cxF "/.ai/" "$tmp/repo/.git/info/exclude") -eq 1 ]] || fail "duplicate exclude entries"
+[[ $(grep -cxF "/.agentfs/" "$tmp/repo/.git/info/exclude") -eq 1 ]] || fail "duplicate .agentfs exclude entry"
 
 # Default mode is unchanged: scaffold stays visible to git
 mkdir "$tmp/repo2"
 git -C "$tmp/repo2" init -q
 "$ROOT/scripts/bootstrap.sh" "$tmp/repo2" >/dev/null
 git -C "$tmp/repo2" status --porcelain | grep -q "\.ai/" || fail "default mode should leave the scaffold tracked"
+git -C "$tmp/repo2" status --porcelain | grep -q "\.agentfs/" || fail "default mode should track the memory ignore guard"
 
 echo "PASS: bootstrap --untracked contributor mode"

package/scripts/test-cli-dispatch.sh

@@ -11,6 +11,9 @@ cairn="$ROOT/bin/cairn"
 "$cairn" help | grep -q "cairn sync" || fail "help missing sync"
 "$cairn" help | grep -q "cairn memory-server" || fail "help missing memory-server"
 "$cairn" sync --help >/dev/null 2>&1 || fail "cairn sync dispatch"
+if "$cairn" not-a-command >/dev/null 2>&1; then
+  fail "unknown command should exit non-zero"
+fi
 
 tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT
 CAIRN_AGENTFS_BASE_DIR="$tmp/store" "$cairn" memory path | grep -qx "$tmp/store" || fail "cairn memory path dispatch"

package/scripts/test-package-install.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Prove that the actual npm tarball installs and runs without relying on files
+# or dependencies from the source checkout.
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+cd "$ROOT"
+npm pack --silent --pack-destination "$tmp" --dry-run=false >/dev/null
+tarballs=("$tmp"/*.tgz)
+[[ ${#tarballs[@]} -eq 1 && -f "${tarballs[0]}" ]] || fail "npm pack did not produce exactly one tarball"
+
+npm install -g --silent --prefix "$tmp/prefix" --dry-run=false "${tarballs[0]}"
+export HOME="$tmp/home"
+export PATH="$tmp/prefix/bin:$PATH"
+mkdir -p "$HOME" "$tmp/project"
+
+expected=$(node -p 'require(process.argv[1]).version' "$ROOT/package.json")
+[[ "$(cairn version)" == "cairnkeep $expected" ]] || fail "installed CLI reports the wrong version"
+
+bootstrap_output=$(cairn bootstrap "$tmp/project")
+[[ "$bootstrap_output" == *"cairn memory-server"* ]] || fail "bootstrap printed invalid memory-server setup instructions"
+[[ "$bootstrap_output" == *"cairn sync --apply"* ]] || fail "bootstrap printed invalid operating-layer setup instructions"
+[[ -x "$tmp/project/.ai/start-claude.sh" ]] || fail "bootstrap did not install an executable Claude launcher"
+[[ -f "$tmp/project/.planning/config.json" ]] || fail "bootstrap did not install the planning scaffold"
+
+(cd "$tmp/project" && cairn doctor) >/dev/null || fail "installed package failed cairn doctor"
+
+echo "PASS: npm tarball installs a self-contained CLI and MCP server"

package/scripts/test-shipped-perms.sh

@@ -2,24 +2,20 @@
 # Regression guard for the 744-perms packaging bug. A root-owned `sudo npm i -g`
 # makes root the file owner, so a non-root user can only run cairn if "other"
 # has the execute bit. A publisher umask can strip it at pack time; the
-# `prepack` script re-applies git's tracked executable bit. This verifies
-# prepack heals a umask-mangled entrypoint back to 755 (world-executable).
-#
-# Deliberately does NOT run `npm pack`: this test runs inside `npm test`, which
-# runs inside `npm publish`'s prepublishOnly, and nesting npm that deep is not
-# portable. Running the prepack command directly tests the same guarantee.
+# `fix:perms` script re-applies git's tracked executable bit. This verifies it
+# heals a umask-mangled entrypoint back to 755 (world-executable).
 set -euo pipefail
 ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
 cd "$ROOT"
 fail() { echo "FAIL: $1" >&2; exit 1; }
 
-prepack=$(node -e 'process.stdout.write(require("./package.json").scripts.prepack||"")')
-[[ -n "$prepack" ]] || fail "package.json has no prepack script (perms fix missing)"
+fix_perms=$(node -e 'process.stdout.write(require("./package.json").scripts["fix:perms"]||"")')
+[[ -n "$fix_perms" ]] || fail "package.json has no fix:perms script"
 
 entry=bin/cairn
 trap 'chmod 755 "$entry" 2>/dev/null || true' EXIT
 chmod 744 "$entry"                                              # simulate a stripping umask
-sh -c "$prepack"                                               # run the real prepack command
+sh -c "$fix_perms"                                             # run the real packaging command
 mode=$(stat -c '%a' "$entry" 2>/dev/null || stat -f '%Lp' "$entry")  # GNU || BSD/macOS
-[[ "$mode" == "755" ]] || fail "prepack did not restore $entry to 755 (got $mode) -- 744 packaging bug"
-echo "OK: prepack restores shipped executables to 755"
+[[ "$mode" == "755" ]] || fail "fix:perms did not restore $entry to 755 (got $mode) -- 744 packaging bug"
+echo "OK: fix:perms restores shipped executables to 755"

package/scripts/test-uninstall.sh

@@ -58,11 +58,13 @@ EXCL="$PROJ/.git/info/exclude"
 mkdir -p "$SB/home/.cairnkeep"; echo data >"$SB/home/.cairnkeep/db"
 "$ROOT_DIR/scripts/uninstall.sh" --yes --purge-memory --live-root "$SB/home/.claude" "$PROJ" >/dev/null 2>&1
 check "project .ai removed"      "$([[ -e "$PROJ/.ai" ]] && echo no || echo yes)" "yes"
-check "exclude lines stripped"   "$(grep -cE '\.ai/|\.planning/' "$EXCL" 2>/dev/null || true)" "0"
+check "project .agentfs removed" "$([[ -e "$PROJ/.agentfs" ]] && echo no || echo yes)" "yes"
+check "exclude lines stripped"   "$(grep -cE '\.ai/|\.planning/|\.agentfs/' "$EXCL" 2>/dev/null || true)" "0"
 check "memory store purged"      "$([[ -e "$SB/home/.cairnkeep" ]] && echo no || echo yes)" "yes"
 BK2=$(ls -dt "$SB/home/.cairnkeep-uninstall-"* 2>/dev/null | head -1)
 bash "$BK2/revert.sh" >/dev/null 2>&1
 check "project scaffold restored" "$([[ -d "$PROJ/.ai" ]] && echo yes || echo no)" "yes"
+check "project ignore restored"   "$([[ -f "$PROJ/.agentfs/.gitignore" ]] && echo yes || echo no)" "yes"
 check "memory store restored"     "$(cat "$SB/home/.cairnkeep/db" 2>/dev/null)" "data"
 
 echo

package/scripts/uninstall.sh

@@ -10,7 +10,8 @@
 # Undoes: the operating layer (`cairn sync --apply` — commands, agents,
 # templates, hooks + their settings.json registrations), the MCP registration
 # (`claude mcp add cairn-memory`), the opt-in audit timer, and — for any project
-# paths you pass — the `cairn bootstrap` scaffold. The npm package itself is
+# paths you pass — the `cairn bootstrap` scaffold. Project `.agentfs/` memory is
+# retained unless `--purge-memory` is given. The npm package itself is
 # npm's to remove; the final step is printed, not run (it would delete this
 # script mid-execution).
 set -uo pipefail
@@ -39,9 +40,8 @@ $HOME/.cairnkeep-uninstall-<ts>/ with a revert.sh before any change.
 
   --dry-run        Print what would happen; touch nothing.
   --yes            Do not prompt for confirmation.
-  --purge-memory   Also remove the durable memory store ($HOME/.cairnkeep or
-                   $CAIRN_AGENTFS_BASE_DIR). Backed up first, but this is your
-                   accumulated memory — off by default.
+  --purge-memory   Also remove the global memory store and .agentfs/ memory in
+                   each PROJECT. Backed up first; off by default.
   --live-root PATH Claude root to clean (default: $CLAUDE_CONFIG_DIR or ~/.claude).
   PROJECT ...      Also revert `cairn bootstrap` in these project dirs
                    (.ai/, .planning/, and any .git/info/exclude entries).
@@ -209,16 +209,26 @@ for proj in "${PROJECTS[@]:-}"; do
   echo "Project scaffold: $proj"
   remove_path "$proj/.ai"
   remove_path "$proj/.planning"
+  if [[ $PURGE_MEMORY -eq 1 ]]; then
+    remove_path "$proj/.agentfs"
+  elif [[ -d "$proj/.agentfs" ]]; then
+    echo "  kept project memory: $proj/.agentfs"
+  fi
   # Strip the .git/info/exclude lines contributor-mode bootstrap added.
   if excl=$(cd "$proj" && git rev-parse --git-path info/exclude 2>/dev/null); then
     [[ "$excl" == /* ]] || excl="$proj/$excl"
     prefix=$(cd "$proj" && git rev-parse --show-prefix 2>/dev/null)
     if [[ -f "$excl" ]] && grep -qxF "/${prefix}.ai/" "$excl" 2>/dev/null; then
       if [[ $DRY_RUN -eq 1 ]]; then
-        echo "  would strip .ai/ + .planning/ from ${excl}"
+        echo "  would strip scaffold entries from ${excl}"
       else
         back_up "$excl"
-        grep -vxF -e "/${prefix}.ai/" -e "/${prefix}.planning/" "$excl" >"$excl.tmp" && mv "$excl.tmp" "$excl"
+        if [[ $PURGE_MEMORY -eq 1 ]]; then
+          grep -vxF -e "/${prefix}.ai/" -e "/${prefix}.planning/" -e "/${prefix}.agentfs/" "$excl" >"$excl.tmp" || true
+        else
+          grep -vxF -e "/${prefix}.ai/" -e "/${prefix}.planning/" "$excl" >"$excl.tmp" || true
+        fi
+        mv "$excl.tmp" "$excl"
         echo "  stripped exclude entries from ${excl}"
       fi
     fi

package/templates/agentfs-gitignore.template

@@ -0,0 +1,3 @@
+# Project memory is private runtime data.
+*
+!.gitignore

package/templates/env.example.template

@@ -12,9 +12,13 @@
 # One of: github | gitlab | codeberg | forgejo | none.  See docs/git-providers.md.
 # CAIRN_GIT_PROVIDER=github
 #
-# The memory server runs over stdio by default. HTTP mode is opt-in and network
-# facing, so it is guarded: setting MCP_HTTP_PORT REQUIRES a bearer token, or the
-# server refuses to start. Clients must send `Authorization: Bearer <token>`.
+# Storage belongs to the host running the memory-server process. Named/global
+# scopes default to ~/.cairnkeep; project scope uses <server-cwd>/.agentfs/.
+# CAIRN_AGENTFS_BASE_DIR=~/.cairnkeep
+#
+# The memory server runs locally over stdio by default. These HTTP settings are
+# for the SERVER host of an explicit remote deployment, not a normal local
+# client. Setting MCP_HTTP_PORT REQUIRES a bearer token, or startup fails.
 # CAIRN_MEMORY_HTTP_TOKEN=change-me-to-a-long-random-secret
 # MCP_HTTP_PORT=7801
 # MCP_HTTP_HOST=127.0.0.1