@cairnkeep/cli 1.0.3 → 1.0.5

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/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,10 @@ 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, 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.
 
 ## The workflow
 
@@ -335,9 +346,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 +358,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 +367,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,134 @@
+# 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.
+
+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`.
+- 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.

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

@@ -669,7 +669,7 @@ 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).
+// serve many concurrent clients within one trusted server-side storage domain.
 function createMemoryServer() {
     const server = new McpServer({ name: "cairn-memory", version: "0.1.0" });
     server.registerTool("memory_read", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,9 +32,12 @@
     "zod": "^3.25.76"
   },
   "scripts": {
+    "build:server": "npm --prefix mcp-memory-server ci --include=dev --global=false --dry-run=false && npm --prefix mcp-memory-server run build --global=false --dry-run=false",
+    "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

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# 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
+# `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; }
+
+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 "$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 "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