@cairnkeep/cli 2.0.0 → 2.2.0

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

@@ -29,6 +29,8 @@ const anythingllmSyncScript = process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT
     ? resolve(expandHome(process.env.CAIRN_ANYTHINGLLM_SYNC_SCRIPT))
     : join(infraRoot, "examples", "anythingllm", "sync_to_anythingllm.py");
 const HISTORY_NAMESPACE = "__history__";
+const REVIEWED_NAMESPACE = "__reviewed__";
+const REVIEW_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 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) {
@@ -180,17 +182,52 @@ async function openScope(scope, create, options = {}) {
 function isHistoryKey(key) {
     return key === HISTORY_NAMESPACE || key.startsWith(`${HISTORY_NAMESPACE}/`);
 }
+function isReviewedKey(key) {
+    return key === REVIEWED_NAMESPACE || key.startsWith(`${REVIEWED_NAMESPACE}/`);
+}
+function assertWritableMemoryKey(key) {
+    if (isHistoryKey(key) || isReviewedKey(key)) {
+        throw new Error(`Keys under ${HISTORY_NAMESPACE}/ and ${REVIEWED_NAMESPACE}/ are reserved.`);
+    }
+}
 function historyPrefix(baseKey) {
     return `${HISTORY_NAMESPACE}/${baseKey}/`;
 }
 function historySnapshotKey(baseKey, timestamp) {
-    return `${historyPrefix(baseKey)}${timestamp}`;
+    return `${historyPrefix(baseKey)}${timestamp}-${randomUUID()}`;
+}
+const reviewedRecordSchema = z.object({
+    schema_version: z.literal(1),
+    review_id: z.string(),
+    key: z.string(),
+    value_hash: z.string(),
+    state: z.enum(["active", "superseded", "invalidated"]),
+    applied_at: z.string(),
+    superseded_at: z.string().optional(),
+    superseded_by: z.string().optional(),
+    invalidated_at: z.string().optional(),
+    invalidation_reason: z.string().optional(),
+});
+function reviewedRecordKey(reviewId) {
+    return `${REVIEWED_NAMESPACE}/${reviewId}`;
+}
+function parseReviewedRecord(value) {
+    const parsed = reviewedRecordSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error("Stored reviewed-memory provenance is invalid; refusing to continue.");
+    }
+    return parsed.data;
+}
+async function inImmediateScopeTransaction(agent, operation) {
+    const transaction = agent.getDatabase().transaction(operation);
+    const immediate = transaction.immediate;
+    return immediate();
 }
 function visibleEntries(entries, includeHistory) {
     if (includeHistory) {
         return entries;
     }
-    return entries.filter((entry) => !isHistoryKey(entry.key));
+    return entries.filter((entry) => !isHistoryKey(entry.key) && !isReviewedKey(entry.key));
 }
 async function listEntries(scope, prefix = "", options = {}) {
     const agent = await openScope(scope, false, options);
@@ -759,9 +796,7 @@ function createMemoryServer(context = {}) {
             promote_to: z.string().optional(),
         }),
     }, async ({ scope, key, value, promote_to }) => {
-        if (isHistoryKey(key)) {
-            throw new Error(`Keys under ${HISTORY_NAMESPACE}/ are reserved for memory history.`);
-        }
+        assertWritableMemoryKey(key);
         const targets = promote_to && promote_to !== scope ? [scope, promote_to] : [scope];
         // Collision-safe: in the unified store, writes from different repos/machines
         // can share a key. If a different value already exists, preserve the old one
@@ -824,6 +859,9 @@ function createMemoryServer(context = {}) {
             key: z.string().min(1),
         }),
     }, async ({ scope, key }) => {
+        if (isReviewedKey(key)) {
+            throw new Error(`Keys under ${REVIEWED_NAMESPACE}/ are reserved for reviewed-memory provenance.`);
+        }
         const agent = await openScope(scope, false, scopeOptions);
         if (agent) {
             try {
@@ -887,9 +925,7 @@ function createMemoryServer(context = {}) {
             reason: z.string().optional(),
         }),
     }, async ({ scope, key, value, reason }) => {
-        if (isHistoryKey(key)) {
-            throw new Error(`Keys under ${HISTORY_NAMESPACE}/ are reserved for memory history.`);
-        }
+        assertWritableMemoryKey(key);
         const agent = await openScope(scope, true, scopeOptions);
         if (!agent) {
             throw new Error(`Unable to open scope ${scope}.`);
@@ -929,6 +965,207 @@ function createMemoryServer(context = {}) {
             await agent.close();
         }
     });
+    server.registerTool("memory_apply_reviewed", {
+        description: "Idempotently apply a human-reviewed memory revision with durable provenance.",
+        inputSchema: z.object({
+            scope: z.string(),
+            review_id: z.string().regex(REVIEW_ID_PATTERN),
+            key: z.string().min(1),
+            value: z.string(),
+        }),
+    }, async ({ scope, review_id, key, value }) => {
+        assertWritableMemoryKey(key);
+        const agent = await openScope(scope, true, scopeOptions);
+        if (!agent) {
+            throw new Error(`Unable to open scope ${scope}.`);
+        }
+        try {
+            const payload = await inImmediateScopeTransaction(agent, async () => {
+                const recordKey = reviewedRecordKey(review_id);
+                const valueHash = hashText(value);
+                const stored = await agent.kv.get(recordKey);
+                if (stored !== undefined) {
+                    const existing = parseReviewedRecord(stored);
+                    if (existing.key !== key || existing.value_hash !== valueHash) {
+                        throw new Error(`Review id ${review_id} was already used with different content.`);
+                    }
+                    if (existing.state !== "active") {
+                        throw new Error(`Review id ${review_id} is ${existing.state} and cannot be reapplied.`);
+                    }
+                    return {
+                        ok: true,
+                        scope,
+                        review_id,
+                        key,
+                        applied: false,
+                        idempotent: true,
+                        snapshot_key: null,
+                    };
+                }
+                const appliedAt = new Date().toISOString();
+                const provenance = await agent.kv.list(`${REVIEWED_NAMESPACE}/`);
+                for (const entry of provenance) {
+                    const previousRecord = parseReviewedRecord(entry.value);
+                    if (previousRecord.state === "active" && previousRecord.key === key) {
+                        await agent.kv.set(entry.key, {
+                            ...previousRecord,
+                            state: "superseded",
+                            superseded_at: appliedAt,
+                            superseded_by: review_id,
+                        });
+                    }
+                }
+                const previous = await agent.kv.get(key);
+                const previousValue = previous === undefined ? undefined : normalizeValue(previous);
+                let snapshotKey = null;
+                if (previousValue !== undefined && previousValue !== value) {
+                    snapshotKey = historySnapshotKey(key, appliedAt);
+                    await agent.kv.set(snapshotKey, {
+                        value: previousValue,
+                        superseded_at: appliedAt,
+                        superseded_reason: `reviewed memory ${review_id}`,
+                    });
+                }
+                await agent.kv.set(key, value);
+                await agent.kv.set(recordKey, {
+                    schema_version: 1,
+                    review_id,
+                    key,
+                    value_hash: valueHash,
+                    state: "active",
+                    applied_at: appliedAt,
+                });
+                return {
+                    ok: true,
+                    scope,
+                    review_id,
+                    key,
+                    applied: true,
+                    idempotent: false,
+                    snapshot_key: snapshotKey,
+                };
+            });
+            return {
+                content: [{ type: "text", text: asToolText(payload) }],
+                structuredContent: payload,
+            };
+        }
+        finally {
+            await agent.close();
+        }
+    });
+    server.registerTool("memory_invalidate_reviewed", {
+        description: "Invalidate a reviewed revision, removing it only when the live value still matches.",
+        inputSchema: z.object({
+            scope: z.string(),
+            review_id: z.string().regex(REVIEW_ID_PATTERN),
+            key: z.string().min(1),
+            reason: z.string().max(512).optional(),
+        }),
+    }, async ({ scope, review_id, key, reason }) => {
+        assertWritableMemoryKey(key);
+        const agent = await openScope(scope, true, scopeOptions);
+        if (!agent) {
+            throw new Error(`Unable to open scope ${scope}.`);
+        }
+        try {
+            const payload = await inImmediateScopeTransaction(agent, async () => {
+                const recordKey = reviewedRecordKey(review_id);
+                const stored = await agent.kv.get(recordKey);
+                if (stored === undefined) {
+                    const invalidatedAt = new Date().toISOString();
+                    await agent.kv.set(recordKey, {
+                        schema_version: 1,
+                        review_id,
+                        key,
+                        value_hash: "",
+                        state: "invalidated",
+                        applied_at: invalidatedAt,
+                        invalidated_at: invalidatedAt,
+                        ...(reason ? { invalidation_reason: reason } : {}),
+                    });
+                    return {
+                        ok: true,
+                        scope,
+                        review_id,
+                        key,
+                        invalidated: true,
+                        idempotent: false,
+                        missing: true,
+                        removed: false,
+                        current_changed: false,
+                        snapshot_key: null,
+                    };
+                }
+                const record = parseReviewedRecord(stored);
+                if (record.key !== key) {
+                    throw new Error(`Review id ${review_id} belongs to a different memory key.`);
+                }
+                if (record.state === "invalidated") {
+                    return {
+                        ok: true,
+                        scope,
+                        review_id,
+                        key: record.key,
+                        invalidated: false,
+                        idempotent: true,
+                        missing: record.value_hash === "",
+                        removed: false,
+                        current_changed: false,
+                        snapshot_key: null,
+                    };
+                }
+                const invalidatedAt = new Date().toISOString();
+                let currentChanged = false;
+                let removed = false;
+                let snapshotKey = null;
+                if (record.state === "active") {
+                    const current = await agent.kv.get(record.key);
+                    if (current !== undefined) {
+                        const currentValue = normalizeValue(current);
+                        if (hashText(currentValue) === record.value_hash) {
+                            snapshotKey = historySnapshotKey(record.key, invalidatedAt);
+                            await agent.kv.set(snapshotKey, {
+                                value: currentValue,
+                                superseded_at: invalidatedAt,
+                                superseded_reason: reason ?? `reviewed memory ${review_id} invalidated`,
+                            });
+                            await agent.kv.delete(record.key);
+                            removed = true;
+                        }
+                        else {
+                            currentChanged = true;
+                        }
+                    }
+                }
+                await agent.kv.set(recordKey, {
+                    ...record,
+                    state: "invalidated",
+                    invalidated_at: invalidatedAt,
+                    ...(reason ? { invalidation_reason: reason } : {}),
+                });
+                return {
+                    ok: true,
+                    scope,
+                    review_id,
+                    key: record.key,
+                    invalidated: true,
+                    idempotent: false,
+                    missing: false,
+                    removed,
+                    current_changed: currentChanged,
+                    snapshot_key: snapshotKey,
+                };
+            });
+            return {
+                content: [{ type: "text", text: asToolText(payload) }],
+                structuredContent: payload,
+            };
+        }
+        finally {
+            await agent.close();
+        }
+    });
     server.registerTool("memory_history", {
         description: "Read prior versions of a memory entry from the hidden history namespace.",
         inputSchema: z.object({

package/mcp-memory-server/package.json

@@ -22,8 +22,9 @@
         "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",
+        "check:reviewed-memory": "node scripts/smoke-reviewed-memory.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:remote-context && 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 && npm run check:reviewed-memory",
         "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": "2.0.0",
+  "version": "2.2.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -8,7 +8,8 @@
     "access": "public"
   },
   "bin": {
-    "cairn": "bin/cairn"
+    "cairn": "bin/cairn",
+    "cairn-container": "scripts/cairn-container"
   },
   "files": [
     "bin/",
@@ -18,6 +19,7 @@
     "opencode/",
     "examples/anythingllm/",
     "examples/overlay-distribution/",
+    "containers/",
     "schemas/",
     "docs/",
     "CHANGELOG.md",

package/scripts/cairn-container

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+VERSION=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$ROOT/package.json" | head -1)
+ENGINE=${CONTAINER_ENGINE:-podman}
+SERVER_IMAGE=${CAIRNKEEP_CONTAINER_IMAGE:-ghcr.io/cairnkeep/cairnkeep:${VERSION:-latest}}
+WORKSPACE_IMAGE=${CAIRNKEEP_WORKSPACE_IMAGE:-ghcr.io/cairnkeep/cairnkeep-workspace:${VERSION:-latest}}
+
+usage() {
+  cat <<'EOF'
+Usage:
+  cairn-container stdio [--image IMAGE] [--volume VOLUME]
+  cairn-container http --token-file FILE [--port PORT] [--name NAME]
+                       [--allowed-hosts HOSTS] [--image IMAGE]
+                       [--volume VOLUME] [--env-file FILE]
+  cairn-container workspace --repo PATH [--mode sandbox|shared]
+                            [--image IMAGE] [--data-volume VOLUME]
+                            [--workspace-volume VOLUME] [--home-volume VOLUME]
+                            [--env-file FILE] [--secret NAME=FILE]... [--] [COMMAND...]
+
+`sandbox` copies the selected repository into a named volume and leaves the
+host checkout untouched. `shared` bind-mounts the selected repository read/write.
+Secret files are mounted read-only and exposed through NAME_FILE variables.
+EOF
+}
+
+fail() {
+  echo "cairn-container: $*" >&2
+  exit 2
+}
+
+require_engine() {
+  command -v "$ENGINE" >/dev/null 2>&1 || fail "$ENGINE is not installed"
+}
+
+absolute_dir() {
+  [ -d "$1" ] || fail "not a directory: $1"
+  (cd "$1" && pwd -P)
+}
+
+absolute_file() {
+  [ -f "$1" ] || fail "not a regular file: $1"
+  [ ! -L "$1" ] || fail "refusing symlink: $1"
+  dir=$(dirname "$1")
+  base=$(basename "$1")
+  printf '%s/%s\n' "$(cd "$dir" && pwd -P)" "$base"
+}
+
+check_secret_mode() {
+  file=$1
+  if stat -c '%a' "$file" >/dev/null 2>&1; then
+    mode=$(stat -c '%a' "$file")
+  else
+    mode=$(stat -f '%Lp' "$file")
+  fi
+  case "$mode" in
+    400 | 600) ;;
+    *) fail "secret file must have mode 400 or 600: $file" ;;
+  esac
+}
+
+safe_name() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9_.-' '-'
+}
+
+podman_base_args() {
+  PODMAN_ARGS=(
+    run --rm
+    --userns=keep-id:uid=10001,gid=10001
+    --cap-drop=all
+    --security-opt=no-new-privileges
+    --read-only
+    --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777
+  )
+}
+
+run_stdio() {
+  image=$SERVER_IMAGE
+  volume=cairnkeep-data
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --volume) [ "$#" -ge 2 ] || fail "--volume requires a value"; volume=$2; shift 2 ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown stdio option: $1" ;;
+    esac
+  done
+
+  require_engine
+  podman_base_args
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" -i \
+    --volume "$volume:/data:Z,U" \
+    "$image" stdio
+}
+
+run_http() {
+  image=$SERVER_IMAGE
+  volume=cairnkeep-data
+  name=cairnkeep
+  port=7801
+  token_file=
+  env_file=
+  allowed_hosts=
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --volume) [ "$#" -ge 2 ] || fail "--volume requires a value"; volume=$2; shift 2 ;;
+      --name) [ "$#" -ge 2 ] || fail "--name requires a value"; name=$2; shift 2 ;;
+      --port) [ "$#" -ge 2 ] || fail "--port requires a value"; port=$2; shift 2 ;;
+      --token-file) [ "$#" -ge 2 ] || fail "--token-file requires a value"; token_file=$2; shift 2 ;;
+      --env-file) [ "$#" -ge 2 ] || fail "--env-file requires a value"; env_file=$2; shift 2 ;;
+      --allowed-hosts) [ "$#" -ge 2 ] || fail "--allowed-hosts requires a value"; allowed_hosts=$2; shift 2 ;;
+      -h | --help) usage; exit 0 ;;
+      *) fail "unknown http option: $1" ;;
+    esac
+  done
+
+  [ -n "$token_file" ] || fail "http mode requires --token-file"
+  token_file=$(absolute_file "$token_file")
+  check_secret_mode "$token_file"
+  case "$port" in *[!0-9]* | "") fail "invalid port: $port" ;; esac
+
+  require_engine
+  podman_base_args
+  PODMAN_ARGS+=(--detach --replace --name "$name")
+  [ -z "$env_file" ] || PODMAN_ARGS+=(--env-file "$(absolute_file "$env_file")")
+  if [ -z "$allowed_hosts" ]; then
+    allowed_hosts="localhost:${port},127.0.0.1:${port},localhost:7801,127.0.0.1:7801"
+  fi
+
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" \
+    --publish "127.0.0.1:${port}:7801" \
+    --volume "$volume:/data:Z,U" \
+    --volume "$token_file:/run/secrets/http-token:ro,Z" \
+    --env MCP_HTTP_HOST=0.0.0.0 \
+    --env MCP_HTTP_PORT=7801 \
+    --env "CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=$allowed_hosts" \
+    --env CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token \
+    "$image" http
+}
+
+run_workspace() {
+  image=$WORKSPACE_IMAGE
+  mode=sandbox
+  repo=
+  data_volume=cairnkeep-data
+  home_volume=cairnkeep-home
+  workspace_volume=
+  env_file=
+  secret_specs=()
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --repo) [ "$#" -ge 2 ] || fail "--repo requires a value"; repo=$2; shift 2 ;;
+      --mode) [ "$#" -ge 2 ] || fail "--mode requires a value"; mode=$2; shift 2 ;;
+      --image) [ "$#" -ge 2 ] || fail "--image requires a value"; image=$2; shift 2 ;;
+      --data-volume) [ "$#" -ge 2 ] || fail "--data-volume requires a value"; data_volume=$2; shift 2 ;;
+      --home-volume) [ "$#" -ge 2 ] || fail "--home-volume requires a value"; home_volume=$2; shift 2 ;;
+      --workspace-volume) [ "$#" -ge 2 ] || fail "--workspace-volume requires a value"; workspace_volume=$2; shift 2 ;;
+      --env-file) [ "$#" -ge 2 ] || fail "--env-file requires a value"; env_file=$2; shift 2 ;;
+      --secret) [ "$#" -ge 2 ] || fail "--secret requires NAME=FILE"; secret_specs+=("$2"); shift 2 ;;
+      --) shift; break ;;
+      -h | --help) usage; exit 0 ;;
+      *) break ;;
+    esac
+  done
+
+  [ -n "$repo" ] || fail "workspace mode requires --repo"
+  repo=$(absolute_dir "$repo")
+  case "$mode" in sandbox | shared) ;; *) fail "--mode must be sandbox or shared" ;; esac
+  if [ -z "$workspace_volume" ]; then
+    workspace_volume="cairnkeep-workspace-$(safe_name "$(basename "$repo")")"
+  fi
+
+  require_engine
+  podman_base_args
+  PODMAN_ARGS+=(-i)
+  [ ! -t 0 ] || PODMAN_ARGS+=(-t)
+  PODMAN_ARGS+=(
+    --volume "$data_volume:/data:Z,U"
+    --volume "$home_volume:/home/cairn:Z,U"
+    --env "CAIRN_WORKSPACE_MODE=$mode"
+  )
+  if [ "$mode" = shared ]; then
+    PODMAN_ARGS+=(--volume "$repo:/workspace:rw,Z")
+  else
+    PODMAN_ARGS+=(
+      --volume "$repo:/source:ro,Z"
+      --volume "$workspace_volume:/workspace:Z,U"
+    )
+  fi
+  [ -z "$env_file" ] || PODMAN_ARGS+=(--env-file "$(absolute_file "$env_file")")
+
+  for spec in "${secret_specs[@]}"; do
+    name=${spec%%=*}
+    file=${spec#*=}
+    [ "$name" != "$spec" ] || fail "--secret requires NAME=FILE"
+    case "$name" in *[!A-Z0-9_]* | "") fail "invalid secret variable name: $name" ;; esac
+    file=$(absolute_file "$file")
+    check_secret_mode "$file"
+    target=$(safe_name "$name")
+    PODMAN_ARGS+=(
+      --volume "$file:/run/secrets/$target:ro,Z"
+      --env "${name}_FILE=/run/secrets/$target"
+    )
+  done
+
+  if [ "$#" -eq 0 ]; then
+    set -- bash
+  fi
+  exec "$ENGINE" "${PODMAN_ARGS[@]}" "$image" "$@"
+}
+
+cmd=${1:-help}
+[ "$#" -eq 0 ] || shift
+case "$cmd" in
+  stdio) run_stdio "$@" ;;
+  http) run_http "$@" ;;
+  workspace) run_workspace "$@" ;;
+  help | -h | --help) usage ;;
+  *) fail "unknown command: $cmd" ;;
+esac

package/scripts/doctor.sh

@@ -28,6 +28,17 @@ fail() { printf '  [FAIL] %s\n' "$1"; fails=$((fails + 1)); }
 # reachable); a connect/timeout failure returns non-zero.
 reachable() { curl -sS -m 5 -o /dev/null "$1" >/dev/null 2>&1; }
 
+embedding_works() {
+  local payload
+  payload=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], input: ["cairnkeep health check"] }))' \
+    "$CAIRN_MEMORY_EMBEDDING_MODEL") || return 1
+  curl -fsS -m 10 -o /dev/null \
+    -H "Authorization: Bearer $CAIRN_LLM_API_KEY" \
+    -H "Content-Type: application/json" \
+    --data "$payload" \
+    "${CAIRN_MEMORY_EMBEDDING_URL%/}/embeddings" >/dev/null 2>&1
+}
+
 echo "cairn doctor"
 
 # 1. Required memory server: prove that the shipped build and dependencies can
@@ -66,10 +77,12 @@ fi
 if [[ -n "${CAIRN_MEMORY_EMBEDDING_URL:-}" ]]; then
   if ! command -v curl >/dev/null 2>&1; then
     skip "embedding endpoint: curl not installed, cannot probe ${CAIRN_MEMORY_EMBEDDING_URL}"
-  elif reachable "$CAIRN_MEMORY_EMBEDDING_URL"; then
-    pass "embedding endpoint reachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+  elif [[ -z "${CAIRN_LLM_API_KEY:-}" || -z "${CAIRN_MEMORY_EMBEDDING_MODEL:-}" ]]; then
+    fail "embedding configuration incomplete (CAIRN_LLM_API_KEY and CAIRN_MEMORY_EMBEDDING_MODEL are required)"
+  elif embedding_works; then
+    pass "embedding endpoint accepted model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   else
-    fail "embedding endpoint unreachable (${CAIRN_MEMORY_EMBEDDING_URL})"
+    fail "embedding request failed for model ${CAIRN_MEMORY_EMBEDDING_MODEL} (${CAIRN_MEMORY_EMBEDDING_URL})"
   fi
 else
   skip "embedding endpoint (CAIRN_MEMORY_EMBEDDING_URL unset)"

package/scripts/probe-container-memory.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const [mode, rawUrl, token] = process.argv.slice(2);
+if (!["write", "read"].includes(mode) || !rawUrl || !token) {
+    console.error("usage: probe-container-memory.mjs <write|read> URL TOKEN");
+    process.exit(2);
+}
+
+const client = new Client({ name: "cairnkeep-container-probe", version: "1" });
+const transport = new StreamableHTTPClientTransport(new URL(rawUrl), {
+    requestInit: {
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "X-Cairn-Project": "container-smoke",
+            "X-Cairn-Scopes": "identity,project",
+        },
+    },
+});
+
+try {
+    await client.connect(transport);
+    if (mode === "write") {
+        const response = await client.callTool({
+            name: "memory_write",
+            arguments: {
+                scope: "identity",
+                key: "patterns/container-persistence",
+                value: "survives container replacement",
+            },
+        });
+        if (response.isError) throw new Error("memory_write returned an error");
+        console.log("container memory write: ok");
+    } else {
+        const response = await client.callTool({
+            name: "memory_read",
+            arguments: {
+                scope: "identity",
+                key: "patterns/container-persistence",
+            },
+        });
+        const value = response.structuredContent?.results?.[0]?.value;
+        if (value !== "survives container replacement") {
+            throw new Error("persisted memory was not recovered");
+        }
+        console.log("container memory persistence: ok");
+    }
+} finally {
+    await client.close();
+}