@cairnkeep/cli 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [2.2.0] - 2026-07-20
+
+### Added
+
+- Add unprivileged memory-server and workspace OCI images with rootless Podman
+  launchers, authenticated HTTP deployment examples, and persistent storage.
+- Add isolated-copy and explicit shared-checkout workspace modes for private
+  derived distributions.
+- Verify stdio startup, HTTP authentication, memory persistence across
+  replacement, and both workspace modes in container CI.
+
+## [2.1.0] - 2026-07-16
+
+### Added
+
+- Add `memory_apply_reviewed` for idempotent application of externally reviewed
+  memory revisions with durable provenance and collision-safe history.
+- Add `memory_invalidate_reviewed` for revision-matched retraction and durable
+  tombstones that prevent delayed writes from resurrecting invalid memory.
+- Add end-to-end checks for replay, supersession, manual changes, retraction,
+  tombstones, and reserved provenance records.
+
+### Changed
+
+- Make history snapshot keys unique when multiple revisions occur in the same
+  millisecond.
+
+The existing memory tools, database locations, and remote HTTP routing contract
+are unchanged. Existing clients remain compatible and reviewed-memory records
+are created only when an integration explicitly invokes the new tools.
+
 ## [2.0.0] - 2026-07-15
 
 ### Breaking
@@ -69,6 +100,8 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
+[2.2.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.3...v2.0.0
 [1.1.3]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.2...v1.1.3
 [1.1.2]: https://github.com/cairnkeep/cairnkeep/compare/v1.1.1...v1.1.2

package/README.md

@@ -41,6 +41,24 @@ and 20 are end-of-life upstream.
 Linux, macOS, Bash 3.2 portability, and clean Node 22/24/26 runtime checks
 are exercised in CI.
 
+## Try with Podman
+
+The minimal OCI image runs the memory server as an unprivileged user and keeps
+all databases in a named volume:
+
+```bash
+podman run --rm -i \
+  --userns=keep-id:uid=10001,gid=10001 \
+  --read-only --cap-drop=all --security-opt=no-new-privileges \
+  --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+  --volume cairnkeep-data:/data:Z,U \
+  ghcr.io/cairnkeep/cairnkeep:latest stdio
+```
+
+For persistent authenticated HTTP, rootless Quadlet, isolated workspace mode,
+storage paths, secrets, and private derived images, see
+**[Containers](docs/containers.md)**.
+
 ## Components
 
 - **`mcp-memory-server/`** — an MCP server exposing durable, scoped memory
@@ -166,6 +184,7 @@ search):
 | `CAIRN_LLM_EXTRACTION_MODEL` | Chat model used for memory 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_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
 | `CAIRN_GIT_PROVIDER` | Git host for collaboration commands: `github`\|`gitlab`\|`codeberg`\|`forgejo`\|`none` ([docs/git-providers.md](docs/git-providers.md)) |
 | `CAIRN_ROUTE_ENDPOINT` | Base URL of an already-running token-miser routing/tiering proxy (unset → `route_check` is inert) |
@@ -189,6 +208,7 @@ enabling them.
 - **Managed overlay distributions** (wrapper CLI, policy lock, private registry, rollback) — [docs/overlay-distributions.md](docs/overlay-distributions.md)
 - **Full operating guide** — [docs/operating.md](docs/operating.md)
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
+- **Podman and OCI containers** — [docs/containers.md](docs/containers.md)
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Support** — [SUPPORT.md](SUPPORT.md)

package/containers/compose.yaml

@@ -0,0 +1,29 @@
+services:
+  cairnkeep:
+    image: ghcr.io/cairnkeep/cairnkeep:${CAIRNKEEP_VERSION:-latest}
+    command: ["http"]
+    restart: unless-stopped
+    read_only: true
+    cap_drop: ["ALL"]
+    security_opt:
+      - no-new-privileges:true
+    environment:
+      MCP_HTTP_HOST: 0.0.0.0
+      MCP_HTTP_PORT: "7801"
+      CAIRN_MEMORY_HTTP_ALLOWED_HOSTS: ${CAIRN_MEMORY_HTTP_ALLOWED_HOSTS:-localhost:7801,127.0.0.1:7801}
+      CAIRN_MEMORY_HTTP_TOKEN_FILE: /run/secrets/http-token
+    ports:
+      - "127.0.0.1:${CAIRNKEEP_PORT:-7801}:7801"
+    volumes:
+      - cairnkeep-data:/data
+    secrets:
+      - http-token
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+
+volumes:
+  cairnkeep-data:
+
+secrets:
+  http-token:
+    file: ${CAIRNKEEP_HTTP_TOKEN_FILE:-./secrets/http-token}

package/containers/entrypoint.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+set -eu
+
+load_secret() {
+  name=$1
+  eval "file=\${${name}_FILE:-}"
+  eval "value=\${${name}:-}"
+
+  if [ -n "$file" ] && [ -n "$value" ]; then
+    echo "cairnkeep: set either $name or ${name}_FILE, not both" >&2
+    exit 64
+  fi
+  if [ -n "$file" ]; then
+    if [ ! -f "$file" ] || [ ! -r "$file" ]; then
+      echo "cairnkeep: secret file for $name is not readable" >&2
+      exit 66
+    fi
+    value=$(cat "$file")
+    export "$name=$value"
+  fi
+}
+
+load_secret CAIRN_MEMORY_HTTP_TOKEN
+load_secret CAIRN_LLM_API_KEY
+load_secret ANYTHINGLLM_API_KEY
+
+mode=${1:-stdio}
+shift || true
+
+case "$mode" in
+  stdio)
+    unset MCP_HTTP_HOST MCP_HTTP_PORT
+    cd "${CAIRN_SERVER_WORKDIR:-/data/project}"
+    exec cairn memory-server "$@"
+    ;;
+  http)
+    if [ -z "${CAIRN_MEMORY_HTTP_TOKEN:-}" ]; then
+      echo "cairnkeep: HTTP mode requires CAIRN_MEMORY_HTTP_TOKEN or CAIRN_MEMORY_HTTP_TOKEN_FILE" >&2
+      exit 64
+    fi
+    export MCP_HTTP_HOST=${MCP_HTTP_HOST:-0.0.0.0}
+    export MCP_HTTP_PORT=${MCP_HTTP_PORT:-7801}
+    allowed_hosts=${CAIRN_MEMORY_HTTP_ALLOWED_HOSTS:-}
+    export CAIRN_MEMORY_HTTP_ALLOWED_HOSTS="${allowed_hosts:+$allowed_hosts,}localhost:${MCP_HTTP_PORT},127.0.0.1:${MCP_HTTP_PORT}"
+    cd "${CAIRN_SERVER_WORKDIR:-/data/project}"
+    exec cairn memory-server "$@"
+    ;;
+  cairn)
+    exec cairn "$@"
+    ;;
+  *)
+    exec "$mode" "$@"
+    ;;
+esac

package/containers/healthcheck.mjs

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+
+const port = process.env.MCP_HTTP_PORT?.trim();
+if (!port) {
+    process.exit(0);
+}
+
+let token = process.env.CAIRN_MEMORY_HTTP_TOKEN?.trim();
+const tokenFile = process.env.CAIRN_MEMORY_HTTP_TOKEN_FILE?.trim();
+if (!token && tokenFile) {
+    try {
+        token = readFileSync(tokenFile, "utf8").trim();
+    } catch {
+        process.exit(1);
+    }
+}
+if (!token) {
+    process.exit(1);
+}
+
+const body = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+        protocolVersion: "2025-06-18",
+        capabilities: {},
+        clientInfo: { name: "cairnkeep-container-health", version: "1" },
+    },
+};
+
+try {
+    const response = await fetch(`http://127.0.0.1:${port}/mcp`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(4000),
+    });
+    process.exit(response.ok ? 0 : 1);
+} catch {
+    process.exit(1);
+}

package/containers/quadlet/cairnkeep-data.volume

@@ -0,0 +1,2 @@
+[Volume]
+VolumeName=cairnkeep-data

package/containers/quadlet/cairnkeep.container

@@ -0,0 +1,32 @@
+[Unit]
+Description=Cairnkeep memory server
+After=network-online.target
+Wants=network-online.target
+
+[Container]
+Image=ghcr.io/cairnkeep/cairnkeep:latest
+ContainerName=cairnkeep
+Exec=http
+UserNS=keep-id:uid=10001,gid=10001
+Volume=cairnkeep-data.volume:/data:Z
+Secret=cairnkeep-http-token,type=mount,target=http-token
+Environment=MCP_HTTP_HOST=0.0.0.0
+Environment=MCP_HTTP_PORT=7801
+Environment=CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=localhost:7801,127.0.0.1:7801
+Environment=CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token
+PublishPort=127.0.0.1:7801:7801
+ReadOnly=true
+DropCapability=all
+HealthCmd=node /usr/local/lib/cairnkeep/container-healthcheck.mjs
+HealthInterval=30s
+HealthTimeout=5s
+HealthStartPeriod=10s
+HealthRetries=3
+PodmanArgs=--security-opt=no-new-privileges
+
+[Service]
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target

package/containers/workspace-entrypoint.sh

@@ -0,0 +1,25 @@
+#!/bin/sh
+set -eu
+
+mode=${CAIRN_WORKSPACE_MODE:-shared}
+case "$mode" in
+  shared)
+    ;;
+  sandbox)
+    if [ ! -d /source ]; then
+      echo "cairnkeep: sandbox mode requires a read-only repository mounted at /source" >&2
+      exit 66
+    fi
+    if [ ! -e /workspace/.cairnkeep-sandbox-ready ]; then
+      cp -a /source/. /workspace/
+      : > /workspace/.cairnkeep-sandbox-ready
+    fi
+    ;;
+  *)
+    echo "cairnkeep: CAIRN_WORKSPACE_MODE must be shared or sandbox" >&2
+    exit 64
+    ;;
+esac
+
+cd /workspace
+exec /usr/local/bin/cairn-container-entrypoint "$@"

package/docs/containers.md

@@ -0,0 +1,187 @@
+# Containers
+
+Cairnkeep publishes two OCI images for Podman and other OCI-compatible
+engines:
+
+| Image | Purpose |
+|---|---|
+| `ghcr.io/cairnkeep/cairnkeep:<version>` | Minimal MCP memory server, over stdio or authenticated HTTP |
+| `ghcr.io/cairnkeep/cairnkeep-workspace:<version>` | Derivation base with Cairnkeep, Git, SSH, and ripgrep |
+
+Both images run as the unprivileged user `10001:10001`. The workspace image is
+not a preconfigured coding harness: a private distribution can derive from it
+and install only its approved harnesses and policies.
+
+## Local stdio
+
+After installing `@cairnkeep/cli`, register the container launcher rather than
+the host memory server:
+
+```bash
+claude mcp add cairn-memory -s user -- cairn-container stdio
+```
+
+Each harness session starts an ephemeral server container. Memory survives in
+the `cairnkeep-data` named volume. The container does not discover or contact a
+remote Cairnkeep server.
+
+The equivalent direct Podman command is:
+
+```bash
+podman run --rm -i \
+  --userns=keep-id:uid=10001,gid=10001 \
+  --read-only --cap-drop=all --security-opt=no-new-privileges \
+  --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
+  --volume cairnkeep-data:/data:Z,U \
+  ghcr.io/cairnkeep/cairnkeep:latest stdio
+```
+
+Pin a version instead of `latest` for managed installations.
+
+## Authenticated HTTP
+
+Generate the bearer token into a private file and start a loopback-only
+listener:
+
+```bash
+install -m 700 -d ~/.config/cairnkeep/secrets
+openssl rand -hex 32 > ~/.config/cairnkeep/secrets/http-token
+chmod 600 ~/.config/cairnkeep/secrets/http-token
+
+cairn-container http \
+  --token-file ~/.config/cairnkeep/secrets/http-token \
+  --port 7801
+```
+
+The launcher refuses token files that are symlinks or have a mode other than
+`0400` or `0600`. It mounts the token read-only instead of putting it in the
+container environment or image.
+
+The listener is deliberately published only on `127.0.0.1`. For access from
+other machines, keep it on loopback behind a TLS reverse proxy or encrypted
+private network. Add the externally visible `Host` header to the DNS-rebinding
+allowlist:
+
+```bash
+cairn-container http \
+  --token-file ~/.config/cairnkeep/secrets/http-token \
+  --allowed-hosts memory.example.com
+```
+
+The container always adds its own loopback address for health checks.
+
+One HTTP server and bearer token form one trust domain. They are not a
+multi-tenant authorization boundary; see [Memory storage and
+deployment](storage.md).
+
+## Persistent service
+
+[`containers/compose.yaml`](../containers/compose.yaml) is a portable starting
+point:
+
+```bash
+mkdir -p containers/secrets
+openssl rand -hex 32 > containers/secrets/http-token
+chmod 600 containers/secrets/http-token
+podman compose -f containers/compose.yaml up -d
+```
+
+Set `CAIRNKEEP_VERSION` to pin the image and
+`CAIRN_MEMORY_HTTP_ALLOWED_HOSTS` when a reverse proxy sends a different host
+name. The named volume contains all memory state.
+
+For rootless Podman managed by systemd, copy the files from
+[`containers/quadlet`](../containers/quadlet) to
+`~/.config/containers/systemd/`, create the referenced secret, and reload:
+
+```bash
+printf '%s' "$(openssl rand -hex 32)" |
+  podman secret create cairnkeep-http-token -
+systemctl --user daemon-reload
+systemctl --user enable --now cairnkeep.service
+```
+
+Review the image tag, published port, allowed hosts, and backup location before
+using the sample as a long-running service.
+
+## Storage and backups
+
+Inside the server image:
+
+| Data | Container path |
+|---|---|
+| Local/legacy project database | `/data/project/.agentfs/project.db` |
+| Named/global scopes | `/data/scopes/<scope>.db` |
+| Header-routed HTTP projects | `/data/scopes/projects/<project-id>.db` |
+
+All three paths are below `/data`, so replacing the container while retaining
+the volume does not move or delete memory. Removing the volume does delete the
+store. Back up the volume with the service stopped, or use SQLite online
+backups for each database as described in [storage.md](storage.md).
+
+## Model and RAG endpoints
+
+Embedding, extraction, and document-RAG services remain optional external
+services. Supply non-secret settings with an env file:
+
+```dotenv
+CAIRN_LLM_API_URL=https://models.example.com/v1
+CAIRN_LLM_EXTRACTION_MODEL=example-chat-model
+CAIRN_MEMORY_EMBEDDING_URL=https://models.example.com/v1
+CAIRN_MEMORY_EMBEDDING_MODEL=example-embedding-model
+```
+
+For workspace containers, pass keys as files:
+
+```bash
+cairn-container workspace --repo . \
+  --env-file ~/.config/cairnkeep/container.env \
+  --secret CAIRN_LLM_API_KEY=~/.config/cairnkeep/secrets/llm-key
+```
+
+The entrypoint reads `CAIRN_LLM_API_KEY_FILE`,
+`CAIRN_MEMORY_HTTP_TOKEN_FILE`, and `ANYTHINGLLM_API_KEY_FILE`. Do not bake
+credentials, cookies, SSH private keys, or a populated `.env` into an image.
+
+## Isolated workspaces
+
+The default `sandbox` mode copies the selected repository into a persistent
+named volume. Commands can change that copy but cannot write to the host
+checkout:
+
+```bash
+cairn-container workspace --repo /path/to/repository
+```
+
+Rerunning the command with the same workspace volume resumes the copy. Use
+`--workspace-volume` when repositories have the same basename or when an
+explicit lifecycle is preferable.
+
+`shared` mode is opt-in and bind-mounts the checkout read/write:
+
+```bash
+cairn-container workspace --repo /path/to/repository --mode shared
+```
+
+The container has normal outbound network access but receives no host home
+directory, container-engine socket, or host credentials unless the operator
+mounts them. For stricter execution, add network policy and resource limits in
+the private distribution.
+
+## Private derived images
+
+A managed overlay should derive from a pinned workspace image:
+
+```dockerfile
+ARG CAIRNKEEP_VERSION
+FROM ghcr.io/cairnkeep/cairnkeep-workspace:${CAIRNKEEP_VERSION}
+
+USER root
+# Install the approved harness package from the approved registry.
+USER 10001:10001
+```
+
+The derived image may contain non-secret organization policy and launchers.
+Machine credentials and repository access remain runtime secrets. Build and
+publish that image from the private overlay repository to its approved private
+registry; do not add private configuration to the public Cairnkeep image.

package/docs/operating.md

@@ -23,6 +23,8 @@ installs. This guide covers all three in order.
 - 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.
+- Optional: rootless Podman for the containerized memory server and isolated
+  workspace base described in [Containers](containers.md).
 
 ## Setup order (Claude Code)
 
@@ -87,6 +89,17 @@ Step 3 installs into `~/.claude` (override with `CLAUDE_CONFIG_DIR` or
 Re-running `sync-claude-assets.sh --apply` is idempotent; use `--check` to see
 drift without writing. Run it again whenever you pull changes to `claude/`.
 
+To keep the memory-server runtime in a container, install the npm package for
+the launcher and replace the registration command with:
+
+```bash
+claude mcp add cairn-memory -s user -- cairn-container stdio
+```
+
+This still stores memory locally, in the `cairnkeep-data` Podman volume. It
+does not configure remote HTTP storage or containerize the harness. See
+[Containers](containers.md) for those separate deployment choices.
+
 ## Setup order (OpenCode)
 
 OpenCode is a secondary path. Steps 1, 4, and 5 are identical (use
@@ -146,6 +159,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_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
 | `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) |

package/docs/overlay-distributions.md

@@ -77,6 +77,14 @@ checkout. Avoid `postinstall` enrollment: installing a package must not silently
 replace machine policy. Provide an explicit enrollment command with a retained
 rollback target.
 
+For container delivery, derive from an exact
+`ghcr.io/cairnkeep/cairnkeep-workspace:<version>` tag and publish only to the
+approved private registry. Install approved harnesses and non-secret policy in
+the derived image, but inject credentials at runtime through the platform's
+secret mechanism. The public image deliberately contains no organization
+profile and never selects a remote memory service. See
+[Containers](containers.md) for the base-image and workspace contracts.
+
 ## Release and fleet safety
 
 Every release should verify:

package/docs/privacy-and-data-flow.md

@@ -36,6 +36,12 @@ Project-scoped and named/global database locations are documented in
 the remote server host; changing a storage environment variable on the client
 does not relocate that server's databases.
 
+The official container stores all databases below `/data`. A named volume
+persists them after container replacement and remains sensitive data. Sandbox
+workspace mode also retains a repository copy in its named volume. Neither
+volume is encrypted by Cairnkeep; remove it explicitly when its retention
+period ends. See [Containers](containers.md).
+
 ## Credentials and transport
 
 Keep API keys and bearer tokens out of repositories and command output. Load

package/docs/releasing.md

@@ -14,20 +14,35 @@ from a workstation.
    tests, and publishes `@cairnkeep/cli` with npm provenance.
 6. The workflow attaches the npm tarball, a CycloneDX SBOM, and SHA-256 checksums
    to the GitHub Release.
+7. The workflow publishes versioned `linux/amd64` and `linux/arm64`
+   memory-server and workspace images to GHCR. It also updates `latest` for a
+   stable release or `next` for a prerelease.
+8. Verify both image digests, SBOM attestations, provenance attestations, and an
+   anonymous pull before announcing the release.
 
 Stable versions must use a stable GitHub Release and publish to npm's `latest`
 tag. SemVer prerelease versions must use a GitHub prerelease and publish to
 `next`. A mismatch fails before publication.
 
-The workflow is safe to rerun: it skips `npm publish` when that exact version is
-already present, then regenerates and replaces the release artifacts.
+The workflow is safe to rerun: it skips `npm publish` and each versioned OCI
+image when that exact version is already present. It regenerates release
+artifacts, retries attestations against the resolved image digests, and moves
+only the `latest` or `next` channel tag. A versioned image tag is never rebuilt
+or moved.
 
 ## Repository configuration
 
 The repository must provide an `NPM_TOKEN` Actions secret authorized to publish
 `@cairnkeep/cli`. Keep that credential out of local files and rotate it according
-to the npm account's security policy. The workflow grants only `contents: write`
-and `id-token: write`; the latter is required for npm provenance.
+to the npm account's security policy. The workflow grants `contents: write`,
+`packages: write`, `attestations: write`, and `id-token: write`; the last two
+are required for registry-backed build provenance.
+
+GitHub creates each new GHCR package as private. After the first container
+release, a package administrator must change both `cairnkeep` and
+`cairnkeep-workspace` to Public in their Package settings. This is a one-time,
+irreversible visibility change for each package; subsequent releases remain
+automatic. Confirm an unauthenticated pull after changing visibility.
 
 Treat a published version as immutable. If a release is wrong, fix it in a new
 version rather than moving its tag or replacing the npm package.

package/docs/storage.md

@@ -29,6 +29,12 @@ 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.
 
+When the memory server runs in the official container, the same rule applies:
+the process stores databases below `/data`, normally backed by the
+`cairnkeep-data` named volume. Replacing the container preserves that volume;
+removing the volume removes the databases. See [Containers](containers.md) for
+the exact paths and backup boundary.
+
 ## Remote HTTP mode
 
 Remote storage is explicit. An operator starts Cairnkeep in HTTP mode on a
@@ -112,6 +118,31 @@ sqlite3 /path/to/project/.agentfs/project.db \
 Treat every database and export archive as sensitive. They may contain source
 paths, decisions, incident details, and other project context.
 
+## Reviewed-memory integration
+
+External review systems should not compose `memory_write`, `memory_read`, and
+`memory_delete` into their own promotion protocol. That sequence is not atomic
+and can delete a newer manual revision during lifecycle invalidation.
+
+Cairnkeep exposes two additive MCP tools for reviewed integrations:
+
+- `memory_apply_reviewed` takes `scope`, `review_id`, `key`, and `value`. It is
+  idempotent for the same review and content, preserves a displaced live value
+  in memory history, and rejects reuse of the review ID with different content.
+- `memory_invalidate_reviewed` takes `scope`, `review_id`, `key`, and an optional
+  `reason`. It removes the live value only when it still matches that reviewed
+  revision. If apply has not arrived yet, it records a tombstone so a delayed
+  apply cannot resurrect invalid memory.
+
+Provenance and tombstones use a hidden reserved namespace in the same scoped
+database. Generic memory writes and deletes cannot modify those records. Review
+IDs must be stable, non-secret idempotency identifiers; evidence payloads and
+credentials do not belong in them.
+
+These tools are for an explicit, trusted integration. Cairnkeep itself does not
+approve candidates, discover an evidence service, or promote memory
+automatically. Existing clients and the original memory tools remain unchanged.
+
 ## Automating trusted personal clients
 
 Keep fleet-specific values in a private dotfiles repository or secret manager,

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

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+const DEFAULT_EMBEDDING_TIMEOUT_MS = 15000;
 // Resolve the embeddings endpoint from the environment. Returns null when the
 // API key, URL, or model name is not configured, so callers can fall back to
 // substring search. Point CAIRN_LLM_API_URL (or CAIRN_MEMORY_EMBEDDING_URL) at
@@ -21,7 +22,11 @@ export function getEmbeddingConfig() {
     if (!model) {
         return null;
     }
-    return { apiUrl, apiKey, model };
+    const rawTimeout = Number(process.env.CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS);
+    const timeoutMs = Number.isFinite(rawTimeout) && rawTimeout >= 100 && rawTimeout <= 120000
+        ? Math.floor(rawTimeout)
+        : DEFAULT_EMBEDDING_TIMEOUT_MS;
+    return { apiUrl, apiKey, model, timeoutMs };
 }
 export function hashText(text) {
     return createHash("sha1").update(text).digest("hex");
@@ -59,7 +64,7 @@ export async function embedTexts(config, texts, chunkSize = 64) {
                 "Content-Type": "application/json",
             },
             body: JSON.stringify({ model: config.model, input: chunk }),
-            signal: AbortSignal.timeout(120000),
+            signal: AbortSignal.timeout(config.timeoutMs),
         });
         if (!response.ok) {
             const text = await response.text();