@cairnkeep/cli 2.3.1 → 2.5.0

package/CHANGELOG.md

@@ -3,6 +3,88 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [2.5.0] - 2026-07-29
+
+### Added
+
+- Add Kimi Code as a supported memory client with a generated project launcher,
+  local stdio guidance, and tested authenticated remote HTTP configuration.
+- Add an explicit harness compatibility matrix and a documented validation
+  process for future MCP clients.
+
+### Fixed
+
+- Document that Kimi requires a literal MCP URL and a token reference through
+  `bearerTokenEnvVar`, preventing invalid `${VAR}` URL configurations without
+  writing bearer-token values to project files.
+
+## [2.4.0] - 2026-07-29
+
+### Added
+
+- Add opt-in, local-only, structured Claude Code and OpenCode session
+  trajectories with pre-write redaction, reasoning omission, bounded retention
+  and no model or network dependency.
+- Add `cairn trajectory list|show|prune`, shell completion, and explicit
+  `cairn doctor --repair` support for trajectory metadata and indexes.
+- Add native Pi trajectory capture through its `session_shutdown` extension,
+  `cairn sync-pi`, a generic Pi launcher, uninstall coverage, and the same
+  opt-in local redaction, size, and retention boundary as other harnesses.
+- Add default-off deterministic hindsight-note distillation, exact repeated
+  error lookup, typed local Markdown hierarchy, lifecycle history, explicit
+  corroborated shared promotion, and `cairn notes` CLI/completion support.
+- Add separately opted-in provider-neutral note prose enrichment and integrate
+  all-project incremental distillation into the existing audit timer without
+  adding online-agent latency.
+- Add default-off typed memory metadata/tags, hard-filtered discovery,
+  history-aware structured `memory_import`, and logical project/shared note
+  address spaces with journaled crash recovery and doctor integration.
+- Add independent default-off compaction continuity for supported Claude Code
+  and OpenCode seams, capturing only harness-produced summaries into local,
+  redacted, bounded immutable revisions with structured fresh-session recovery.
+- Add a separate local artifact store for compaction summaries, diffs, test
+  output, and generated-file metadata/snapshots; four gated MCP tools;
+  `cairn artifact list|show|delete|prune`; doctor, completion, package, and
+  backup-first uninstall coverage; and separately consented HTTP access.
+- Add a default-off managed contract for eight existing capabilities, including
+  project CLI overrides, compatibility-aware status/digests, exact MCP tool
+  omission, guarded installed workflows, and separately consented payload-free
+  local callback records.
+- Add a default-off, adapter-driven two-pass evaluation harness with immutable
+  task sets, paired seeds, confidence intervals, per-capability ablations,
+  deterministic offline fixtures, bounded reports, and exact-source runtime
+  evidence without claiming an unmeasured quality improvement.
+- Add a design-only meta-agent contract describing how future configuration
+  proposals could be evaluated through the existing harness without giving
+  Cairnkeep ownership of an agent or inference loop.
+
+### Fixed
+
+- Load the native OpenCode capability plugin through its supported single-export
+  shape, run its coordinator with Node under OpenCode's Bun host, accept the
+  pinned runtime event envelope, and settle terminal callbacks before the host
+  can exit.
+- Layer `CAIRN_EXTRA_SETTINGS` through OpenCode's supported
+  `OPENCODE_CONFIG` environment seam and keep headless graph commands in the
+  tool-calling path until their real owner operation completes.
+- Pin the Claude Code 2.1.220 `PostCompact` `prompt_id` payload shape alongside
+  the retained 2.1.219 adapter while continuing to refuse unknown versions.
+- Preserve redacted Pi provider failures as trajectory system events and treat
+  a closed trajectory CLI output pipe as a normal consumer exit.
+- Make the audit script executable so its rendered systemd service target can
+  run directly.
+- Bind evaluation note distillation to the admitted task workspace so nested
+  task trajectories cannot be missed or replaced by a source-root fallback.
+- Upgrade the MCP SDK to 1.30.0 so both package graphs use the upstream-owned,
+  patched Hono transport and report zero production vulnerabilities.
+
+Trajectory/compaction capture, artifact access, and note distillation/enrichment remain disabled by default. Existing
+MCP tools, memory database paths, and remote HTTP behavior are unchanged. No
+memory-quality or efficiency improvement is claimed before the evaluation
+harness measures it.
+
 ## [2.3.1] - 2026-07-25
 
 ### Fixed
@@ -129,6 +211,9 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.4.0...v2.5.0
+[2.4.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.3.1...v2.4.0
 [2.3.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.3.0...v2.3.1
 [2.3.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.1...v2.3.0
 [2.2.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.2.0...v2.2.1

package/README.md

@@ -9,15 +9,17 @@
 A *cairn* is a stack of stones left as a trail marker for whoever follows; a
 *keep* is where you store what matters. **Cairnkeep** is where coding agents
 stack durable memory — decisions, pitfalls, patterns — and follow the trail
-across sessions, projects, and harnesses (Claude Code, OpenCode, …).
+across sessions, projects, and harnesses (Claude Code, OpenCode, Kimi Code,
+Pi, and other MCP clients).
 
 ## Status
 
-Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`,
-`doctor`, `memory`, `audit-timer`, `completion`, `uninstall`) installable via
+Shipped: the memory server, the `cairn` CLI (`bootstrap`, `memory-server`, `sync`, `sync-pi`,
+`doctor`, `trajectory`, `artifact`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
 `npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
-agents, hooks) installed on both Claude Code and OpenCode. The generic launchers
+agents, hooks) installed on Claude Code and OpenCode, plus a native Pi
+trajectory extension. The generic launchers
 expose wrapper seams (`.ai/pre-launch.sh`, `CAIRN_EXTRA_SETTINGS`,
 `.ai/post-exit.sh`) so an enterprise wrapper can add provider/credential setup
 without forking them. Also shipped: context exploration (`/context-explore`) and
@@ -35,6 +37,8 @@ and 20 are end-of-life upstream.
 |---|---|
 | Claude Code on Linux/macOS | Memory server plus commands, agents, hooks, and launchers |
 | OpenCode on Linux/macOS | Memory server plus commands, plugins, hooks, and launchers |
+| Kimi Code on Linux/macOS | Memory MCP server plus project launcher; no Cairnkeep operating-layer assets yet |
+| Pi on Linux/macOS | Native opt-in trajectory extension and launcher; no bundled MCP bridge |
 | Codex CLI | Memory MCP server; no Cairnkeep operating-layer assets |
 | Other MCP clients | Memory and optional domain-knowledge MCP tools |
 | Native Windows | Not supported by the Bash-based installer; use WSL (not yet CI-verified) |
@@ -42,6 +46,9 @@ 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.
 
+See [Harness compatibility](docs/harness-compatibility.md) for exact support
+levels, Kimi configuration, and candidates that are not yet runtime-tested.
+
 ## Try with Podman
 
 The minimal OCI image runs the memory server as an unprivileged user and keeps
@@ -67,10 +74,17 @@ storage paths, secrets, and private derived images, see
   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 trajectory list|show|prune` manages opt-in local session trajectories;
+  `cairn artifact list|show|delete|prune` manages opt-in local artifacts;
+  `cairn eval validate|run|ablate|report|prune|delete` coordinates explicit
+  local two-pass and one-capability-at-a-time measurements;
+  `cairn notes distill|search-error|promote|doctor` compiles and searches
+  default-off local hindsight notes outside the online agent path;
   `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 completion bash|zsh|fish` generates shell completion definitions; and
+  `cairn sync-pi` installs the native Pi trajectory extension;
   `cairn uninstall` reverses the install (backup-first, revertible).
 - **`templates/`** — project scaffolding (generic launchers, env) plus the
   derived-knowledge layer (wiki, alignment, graph, security, planning).
@@ -139,6 +153,41 @@ patterns/transactional-migrations: Use transactional migrations for schema chang
 The exact command rendering depends on the client. Any MCP client can call
 `memory_write` and `memory_search` directly.
 
+For Kimi Code, bootstrap supplies a launcher and Kimi reads the repository's
+MCP configuration. A local stdio entry uses `cairn memory-server`. Remote Kimi
+configuration requires a literal URL and supports a token reference through
+`bearerTokenEnvVar`; it does not expand `${VAR}` in the URL. See
+[Harness compatibility](docs/harness-compatibility.md#kimi-code).
+
+For Pi, install the local trajectory adapter and use the scaffolded launcher:
+
+```bash
+cairn sync-pi --apply
+cairn bootstrap /path/to/project
+cd /path/to/project && ./.ai/start-pi.sh
+```
+
+This installs trajectory capture only. Cairnkeep does not bundle or select a Pi
+MCP bridge; configure a user-chosen bridge separately if you also want the MCP
+memory tools inside Pi.
+
+Closed trajectories can be compiled into local hindsight notes without a model
+or embedding service. Capture and distillation are separate opt-ins:
+
+```bash
+export CAIRN_TRAJECTORY_CAPTURE=1     # affects future closed sessions
+export CAIRN_NOTE_DISTILLATION=1
+cairn notes distill --project /path/to/project --json
+printf '%s\n' 'TypeError: example' | cairn notes search-error --project /path/to/project --json
+```
+
+Notes keep deterministic failure, resolution, abandonment, and recurrence
+history under `~/.cairnkeep/notes/`. Shared promotion is never automatic: it
+requires compatible evidence from two distinct projects and an explicit
+`cairn notes promote NOTE-ID --with NOTE-ID --confirm`. See the
+[operating guide](docs/operating.md#hindsight-notes-opt-in) before enabling
+optional model enrichment.
+
 Prefer working from a clone? Build the server with `cd mcp-memory-server && npm
 install && npm run build`, then use `scripts/sync-claude-assets.sh` and
 `bin/cairn` in place of the installed `cairn`.
@@ -159,8 +208,9 @@ unless a wrapper opts in:
   export env (e.g. a provider base URL) or abort the launch by returning
   non-zero. This is where credential refresh / connectivity setup lives.
 - **`CAIRN_EXTRA_SETTINGS`** — path to a settings file layered onto the harness
-  (`--settings` for Claude Code, `--config` for OpenCode). Process env still
-  wins, so an inline value beats the profile.
+  (`--settings` for Claude Code, `OPENCODE_CONFIG` for OpenCode). Pi has no equivalent
+  generic settings-file flag, so its launcher leaves this variable unused.
+  Process env still wins, so an inline value beats the profile.
 - **`.ai/post-exit.sh`** — sourced after the harness exits, with
   `CAIRN_EXIT_STATUS` set to its exit code.
 
@@ -188,6 +238,37 @@ search):
 | `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_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; default off) |
+| `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per captured session (default `5242880`, 5 MiB) |
+| `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Maximum logical bytes across local trajectories (default `268435456`, 256 MiB) |
+| `CAIRN_TRAJECTORY_RETENTION_DAYS` | Retain captured sessions for this many days (default `30`) |
+| `CAIRN_TRAJECTORY_REDACTION_FILE` | Optional project-contained redaction config (default `.ai/trajectory-redaction.json` when present) |
+| `CAIRN_REDACTION_FILE` | Optional project-contained redaction config shared by trajectories and artifacts (falls back to `CAIRN_TRAJECTORY_REDACTION_FILE`) |
+| `CAIRN_COMPACTION_CAPTURE` | Opt in to local harness-produced compaction capture and fresh-session recovery (off by default) |
+| `CAIRN_ARTIFACT_STORE` | Expose four local stdio artifact tools (off by default; independent of compaction capture) |
+| `CAIRN_ARTIFACT_HTTP` | Separately consent to artifact tools over authenticated HTTP (off by default; also requires `CAIRN_ARTIFACT_STORE`) |
+| `CAIRN_ARTIFACT_MAX_BYTES` | Maximum stored bytes per artifact (default `1048576`, 1 MiB) |
+| `CAIRN_ARTIFACT_SESSION_MAX_BYTES` | Maximum logical bytes per artifact session (default `16777216`, 16 MiB) |
+| `CAIRN_ARTIFACT_STORE_MAX_BYTES` | Maximum logical bytes in one artifact store (default `268435456`, 256 MiB) |
+| `CAIRN_ARTIFACT_RETENTION_DAYS` | Artifact age retention (default `30`) |
+| `CAIRN_COMPACTION_MAX_REVISIONS` | Retained compaction revisions per session (default `8`) |
+| `CAIRN_ARTIFACT_GENERATED_FILE_SNAPSHOT_MAX_BYTES` | Generated-file inline snapshot cap (default `262144`, 256 KiB; lower if the artifact cap is lower) |
+| `CAIRN_NOTE_DISTILLATION` | Opt in to one-shot/scheduled local note distillation and lookup (default off) |
+| `CAIRN_NOTE_ENRICHMENT` | Separately opt in to remote/local prose enrichment; never implied by credentials (default off) |
+| `CAIRN_NOTE_ENRICHMENT_MODEL` | Explicit chat model for optional note enrichment (no default) |
+| `CAIRN_NOTE_ENRICHMENT_TIMEOUT_MS` | Optional enrichment timeout (default `15000`) |
+| `CAIRN_TYPED_MEMORY_NODES` | Opt in to typed metadata, filters, logical note address spaces, and `memory_import` (default off; restart the server after changing) |
+| `CAIRN_CAPABILITY_CONTRACT` | Opt in to the managed eight-capability contract (default off) |
+| `CAIRN_CAPABILITY_LOGGING` | Override payload-free local callback logging (`1`/`0`; default off) |
+| `CAIRN_CAPABILITY_MEMORY_WRITE` | Override `memory.write` for this process |
+| `CAIRN_CAPABILITY_MEMORY_SEARCH` | Override `memory.search` for this process |
+| `CAIRN_CAPABILITY_NOTES_DISTILL` | Override `notes.distill` for this process |
+| `CAIRN_CAPABILITY_WIKI` | Override `wiki` for this process |
+| `CAIRN_CAPABILITY_GRAPH` | Override `graph` for this process |
+| `CAIRN_CAPABILITY_SECURITY_AUDIT` | Override `security.audit` for this process |
+| `CAIRN_CAPABILITY_ROUTE_CHECK` | Override `route.check` for this process |
+| `CAIRN_CAPABILITY_CONTEXT_EXPLORE` | Override `context.explore` for this process |
+| `CAIRN_EVAL` | Opt in to the local evaluation coordinator (default off; does not select a harness, model, endpoint, credential, or network) |
 | `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) |
 | `CAIRN_EXPLORE_BINARY` | Absolute path to the `token_miser` binary used by `context_explore` (unset → the tool throws) |
@@ -203,6 +284,151 @@ remote memory, and delegated exploration can send content to endpoints you
 configure. Review [Privacy and data flow](docs/privacy-and-data-flow.md) before
 enabling them.
 
+### Managed capability contract (opt-in)
+
+`CAIRN_CAPABILITY_CONTRACT=1` enables one versioned, typed boundary around the
+existing capability owners. The master flag and callback logging are both off
+by default. With the master flag unset, MCP registration, installed
+Markdown/workflow bytes, commands, processes, configuration reads, logging,
+output, and performance remain on the legacy path.
+
+| Capability ID | Kind | Existing owner | Compatibility default | Process override |
+|---|---|---|---:|---|
+| `memory.write` | MCP tool | `memory_write` | on | `CAIRN_CAPABILITY_MEMORY_WRITE` |
+| `memory.search` | MCP tool | `memory_search` | on | `CAIRN_CAPABILITY_MEMORY_SEARCH` |
+| `notes.distill` | offline job | note distillation CLI/timer | off | `CAIRN_CAPABILITY_NOTES_DISTILL` |
+| `wiki` | operating workflow | installed wiki commands/workflows | on | `CAIRN_CAPABILITY_WIKI` |
+| `graph` | operating workflow | installed graph commands | inherited from `graphify.enabled`, otherwise off | `CAIRN_CAPABILITY_GRAPH` |
+| `security.audit` | operating workflow | installed security commands/workflows | on | `CAIRN_CAPABILITY_SECURITY_AUDIT` |
+| `route.check` | MCP tool | existing token-miser routing delegate | on | `CAIRN_CAPABILITY_ROUTE_CHECK` |
+| `context.explore` | MCP tool | existing token-miser exploration delegate | on | `CAIRN_CAPABILITY_CONTEXT_EXPLORE` |
+
+Manage project overrides in `.ai/capabilities.json` through the CLI rather than
+editing JSON:
+
+```bash
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities list
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities status --json
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities disable context.explore
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities reset context.explore
+CAIRN_CAPABILITY_CONTRACT=1 cairn capabilities logging enable
+```
+
+Process overrides take precedence over project values, which take precedence
+over compatibility defaults. `reset` removes an explicit override and restores
+the inherited state; it does not mean enabled. Changes to the four MCP
+capabilities (`memory.write`, `memory.search`, `route.check`, and
+`context.explore`) require a fresh memory-server start and disabled tools are
+omitted from `tools/list`. Offline and operating workflows resolve state at
+each invocation. Enabling the master does not enable `notes.distill` or graph
+when their compatibility inputs remain off.
+
+Callback records are local, payload-free operating evidence, not evaluation
+results or telemetry. They require the contract, callback logging, and local
+trajectory capture to be enabled together. Cairnkeep makes no capability gain,
+memory-quality, or efficiency claim from this instrumentation; Phase 19 must
+first create an explicit all-enabled baseline and measure one-disabled states.
+See the [operating guide](docs/operating.md#managed-capability-contract-opt-in),
+[storage contract](docs/storage.md#capability-callback-storage), and
+[privacy flow](docs/privacy-and-data-flow.md#capability-callback-flow).
+
+### Evaluation harness (opt-in, measurement only)
+
+`CAIRN_EVAL=1` enables `cairn eval` for a committed schema-v1 task set and an
+explicit operator-owned adapter program. `validate` resolves immutable inputs,
+limits, commands, digests, output containment, and a deterministic serial
+schedule without invoking the adapter. `run` measures from-scratch Run 1 versus
+a fresh Run 2 that can see only its own task's immutable note snapshot.
+`ablate` measures an explicit all-eight-capabilities-on baseline against one
+exactly-one-disabled treatment, with both passes in both arms. Execution prints
+the invocation estimate and requires `--yes`; there is no retry, inference,
+provider, endpoint, credential, model, or network default.
+
+The canonical local JSON report records optional reported turns/tokens/cost,
+independently verified pass state, full and note-eligible populations,
+missingness, paired deltas, capability/notes/revision digests, and seeded
+bootstrap uncertainty. Turns compare only under exact matching turn-semantics
+compatibility IDs; token totals are never inferred and unknown verifier results
+are never counted as pass or fail. Reports describe estimates and
+inconclusive/small-sample conditions; they do not claim causality,
+significance, quality change, or efficiency change.
+
+The bundled fake task set and adapter are deterministic, offline framework
+fixtures. They cannot support a Cairnkeep performance statement. Any future
+efficiency statement requires a separate committed `live-evaluation` artifact
+whose source, task-set, report, schema, note-snapshot, missingness, runtime, and
+claim anchors all pass `scripts/verify-phase19-runtime-evidence.mjs`. No such
+live claim or evidence artifact is shipped here, and external paper calibration
+is neither a Cairnkeep result nor an acceptance target.
+
+Reports and note snapshots stay under
+`.agentfs/eval/experiments/<experiment-id>/`; default uninstall retains them,
+while explicit purge is backup-first and revertible. Cancellation retains an
+inspectable partial report. POSIX process-group cleanup is tested; Windows
+descendant-process-tree termination is not guaranteed. See the
+[operating guide](docs/operating.md#evaluation-harness-opt-in),
+[storage contract](docs/storage.md#evaluation-report-and-note-snapshot-storage),
+and [privacy flow](docs/privacy-and-data-flow.md#evaluation-adapter-and-report-flow).
+
+### Typed memory nodes and structured import (opt-in)
+
+`CAIRN_TYPED_MEMORY_NODES=1` adds schema-v1 `node_type`, canonical `tags`,
+`address_space`, hard list/search filters (`node_types`, `tags_all`,
+`tags_any`), and exactly one new MCP tool: `memory_import`. The flag is read
+when each server/session is created, so restart after changing it. Unset keeps
+the existing 14 tools, schemas, response roots, raw values, files, processes,
+network behavior, and output unchanged. It adds no read/edit/update/delete
+aliases; `memory_supersede` remains the sole edit operation.
+
+Core types are `memory`, `knowledge`, `hindsight`, `shared`, and `provenance`;
+extensions use a namespaced form such as `team:runbook`. Tags are ASCII
+lowercase, with whitespace and underscores normalized to hyphens, deduplicated,
+and sorted. Filters are applied before ranking. Exact key/tag/type hits precede
+semantic results; without a working configured embedding endpoint, search uses
+stable local substring matching.
+
+`memory_import` accepts one inline schema-v1 batch for one concrete scope and
+one `memory`, `project-notes`, or `shared-notes` address. It supports 1–256
+unique relative keys, values up to 256 KiB each and 5 MiB total, optional
+`import_id`, `dry_run`, and `conflict_policy: reject|supersede`. Results contain
+only digests, counts, keys, and actions—never supplied values. The default
+reject policy cannot overwrite; explicit supersede preserves typed history.
+Note addresses require `scope: project` and logical keys, never filesystem
+paths. See the [operating guide](docs/operating.md#typed-memory-nodes-and-note-address-spaces-opt-in).
+
+### Compaction continuity and artifacts (opt-in)
+
+`CAIRN_COMPACTION_CAPTURE=1` captures only harness-produced compaction summaries
+from the pinned Claude Code `PostCompact` 2.1.219 and 2.1.220 payloads and
+OpenCode `session.compacted` 1.17.20 seam. It stores redacted immutable revisions locally and injects the latest
+valid structured goals, decisions, TODOs, and critical errors when a session
+starts. A resumed session is preferred; a fresh session falls back to the
+newest valid project summary and marks stale context for validation. The raw
+redacted summary is available only through an explicit read. Cairnkeep never
+generates or triggers compaction.
+
+`CAIRN_ARTIFACT_STORE=1` independently exposes exactly four stdio MCP tools:
+`artifact_write`, `artifact_read`, `artifact_list`, and `artifact_delete`.
+The initial kinds are exactly `compaction_summary`, `diff`, `test_output`, and
+`generated_file`. Generated-file paths are labels only; the server never reads
+them. Operators can inspect retained local data whether or not MCP writes are
+currently enabled:
+
+```bash
+cairn artifact list --kind compaction_summary --json
+cairn artifact show ARTIFACT-ID --json
+cairn artifact delete ARTIFACT-ID --dry-run --json
+cairn artifact prune --dry-run --include-protected --json
+```
+
+Both capabilities are default-off, local, and require no key, model, endpoint,
+telemetry, or network. Remote tools require double consent:
+`CAIRN_ARTIFACT_STORE=1` plus `CAIRN_ARTIFACT_HTTP=1`, as well as the existing
+bearer, `Host`, and validated `X-Cairn-Project` controls. Artifact HTTP never
+exposes trajectory data. See the [operating guide](docs/operating.md#compaction-continuity-and-artifacts-opt-in),
+[storage contract](docs/storage.md#artifact-storage), and
+[privacy flows](docs/privacy-and-data-flow.md#compaction-and-artifact-flows).
+
 ## More
 
 - **Guided learning paths and video scripts** — [docs/learning/README.md](docs/learning/README.md)

package/bin/cairn

@@ -32,8 +32,30 @@ Usage:
                            Install/update the Claude Code operating layer (commands,
                            agents, hooks) into ~/.claude, or into DIR for a single
                            project (--live-root <project>/.claude).
+  cairn sync-pi [--apply] [--live-root DIR]
+                           Install/update the Pi trajectory extension into
+                           ~/.pi/agent, or into DIR for an isolated Pi root.
   cairn doctor             Health-check the memory server and configured LLM /
-                           embedding endpoints, git provider, and store.
+                           embedding endpoints, git provider, and stores.
+                           Use --repair for derived trajectory/typed metadata,
+                           indexes, and interrupted note transactions.
+  cairn trajectory <list|show|prune>
+                           Inspect and prune opt-in local session trajectories.
+  cairn artifact <list|show|delete|prune>
+                           Inspect and delete opt-in local artifacts. List/show
+                           support --json; delete supports --dry-run; prune
+                           supports --dry-run and --include-protected.
+  cairn capabilities <list|status|enable|disable|reset|logging>
+                           Inspect and manage project capability state. MCP changes
+                           require a memory-server restart; operating changes apply
+                           on the next invocation.
+  cairn notes <distill|search-error|promote|doctor>
+                           Compile closed trajectories into local hindsight notes,
+                           search exact failure signatures, promote corroborated
+                           notes, or validate the note store.
+  cairn eval <validate|run|ablate|report|prune|delete>
+                           Validate or run default-off local evaluations, inspect
+                           reports, and manage retained experiment results.
   cairn memory <path|export|import>
                            Relocate global-scope memory. `path` prints its location;
                            `export <file.tgz>` takes a WAL-safe snapshot (requires
@@ -41,7 +63,8 @@ Usage:
   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 ...]
+  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--live-root DIR]
+                  [--pi-live-root DIR] [PROJECT ...]
                            Reverse what cairnkeep installed/modified (operating
                            layer, hook registrations, MCP registration, audit
                            timer, and any given projects' bootstrap scaffold).
@@ -72,9 +95,27 @@ case "$cmd" in
     #   claude mcp add cairn-memory -s user -- cairn memory-server
     exec node "$CAIRN_ROOT/mcp-memory-server/dist/index.js" "$@"
     ;;
+  trajectory)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/trajectory-cli.js" "$@"
+    ;;
+  artifact)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/artifact-cli.js" "$@"
+    ;;
+  capabilities)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/capability-cli.js" "$@"
+    ;;
+  notes)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/note-cli.js" "$@"
+    ;;
+  eval)
+    exec node "$CAIRN_ROOT/mcp-memory-server/dist/eval-cli.js" "$@"
+    ;;
   sync)
     exec "$CAIRN_ROOT/scripts/sync-claude-assets.sh" "$@"
     ;;
+  sync-pi)
+    exec "$CAIRN_ROOT/scripts/sync-pi-assets.sh" "$@"
+    ;;
   audit-timer)
     exec "$CAIRN_ROOT/scripts/install-audit-timer.sh" "$@"
     ;;

package/claude/capability-contract/hooks/capability-command-finish.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Stop/StopFailure/CwdChanged/SessionEnd hook: lifecycle settlement transport.
+set -euo pipefail
+
+case "${CAIRN_CAPABILITY_CONTRACT:-}" in
+  1|true|TRUE|yes|YES|on|ON) ;;
+  *) exit 0 ;;
+esac
+
+INFRA_ROOT="@@INFRA_ROOT@@"
+COORDINATOR="$INFRA_ROOT/mcp-memory-server/dist/capability-cli.js"
+[ -f "$COORDINATOR" ] || exit 0
+
+input=$(cat) || exit 0
+validated=$(printf '%s' "$input" | python3 /dev/fd/3 3<<'PY'
+import json
+import re
+import sys
+
+common = {"session_id", "transcript_path", "cwd", "hook_event_name"}
+optional = {"prompt_id", "permission_mode", "effort", "agent_id", "agent_type"}
+shapes = {
+    "Stop": ({"stop_hook_active", "last_assistant_message", "background_tasks", "session_crons"}, set()),
+    "StopFailure": ({"error"}, {"error_details", "last_assistant_message"}),
+    "CwdChanged": ({"old_cwd", "new_cwd"}, set()),
+    "SessionEnd": ({"reason"}, set()),
+}
+errors = {
+    "rate_limit", "overloaded", "authentication_failed", "oauth_org_not_allowed",
+    "billing_error", "invalid_request", "model_not_found", "server_error",
+    "max_output_tokens", "unknown",
+}
+reasons = {"clear", "resume", "logout", "prompt_input_exit", "bypass_permissions_disabled", "other"}
+
+try:
+    value = json.load(sys.stdin)
+    if not isinstance(value, dict) or not common <= set(value):
+        raise ValueError
+    event = value["hook_event_name"]
+    if event not in shapes:
+        raise ValueError
+    event_required, event_optional = shapes[event]
+    required = common | event_required
+    if not required <= set(value) or set(value) - required - optional - event_optional:
+        raise ValueError
+    for name in ("session_id", "transcript_path", "cwd"):
+        if not isinstance(value[name], str):
+            raise ValueError
+    session = value["session_id"]
+    if not isinstance(session, str) or not re.fullmatch(r"(?:cairn:)?[A-Za-z0-9][A-Za-z0-9._:-]{0,255}", session) or session == "unknown":
+        raise ValueError
+    if event == "Stop":
+        if not isinstance(value["stop_hook_active"], bool) or not isinstance(value["last_assistant_message"], str):
+            raise ValueError
+        if not isinstance(value["background_tasks"], list) or not isinstance(value["session_crons"], list):
+            raise ValueError
+        operation, body = "harness-terminal", {"outcome": "success"}
+    elif event == "StopFailure":
+        if value["error"] not in errors:
+            raise ValueError
+        operation, body = "harness-terminal", {"outcome": "error"}
+    elif event == "SessionEnd":
+        if value["reason"] not in reasons:
+            raise ValueError
+        operation, body = "harness-terminal", {"outcome": "abandoned"}
+    else:
+        if not isinstance(value["old_cwd"], str) or not isinstance(value["new_cwd"], str):
+            raise ValueError
+        operation, body = "harness-cwd", {"old_cwd": value["old_cwd"], "new_cwd": value["new_cwd"]}
+    body.update({"schema_version": 1, "harness": "claude-code", "session_id": session})
+    print(operation)
+    print(json.dumps(body, separators=(",", ":")))
+except Exception:
+    sys.exit(1)
+PY
+) || exit 0
+
+operation=${validated%%$'\n'*}
+payload=${validated#*$'\n'}
+printf '%s' "$payload" | node "$COORDINATOR" "$operation" >/dev/null 2>&1 || true
+exit 0

package/claude/capability-contract/hooks/capability-command-start.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# UserPromptExpansion hook: deterministic operating-capability admission.
+set -euo pipefail
+
+case "${CAIRN_CAPABILITY_CONTRACT:-}" in
+  1|true|TRUE|yes|YES|on|ON) ;;
+  *) printf '{}\n'; exit 0 ;;
+esac
+
+INFRA_ROOT="@@INFRA_ROOT@@"
+COORDINATOR="$INFRA_ROOT/mcp-memory-server/dist/capability-cli.js"
+FIXED_BLOCK='{"decision":"block","reason":"capability disabled"}'
+
+block() {
+  printf '%s\n' "$FIXED_BLOCK"
+  exit 2
+}
+
+[ -f "$COORDINATOR" ] || block
+input=$(cat) || block
+
+validated=$(printf '%s' "$input" | python3 /dev/fd/3 "$PWD" 3<<'PY'
+import json
+import os
+import re
+import sys
+
+required = {
+    "session_id", "transcript_path", "cwd", "hook_event_name",
+    "expansion_type", "command_name", "command_args", "command_source", "prompt",
+}
+optional = {"prompt_id", "permission_mode", "effort", "agent_id", "agent_type"}
+commands = {"wiki-ingest", "wiki-query", "wiki-lint", "graphify", "security-audit"}
+
+try:
+    value = json.load(sys.stdin)
+    if not isinstance(value, dict) or set(value) - required - optional or not required <= set(value):
+        raise ValueError
+    if value["hook_event_name"] != "UserPromptExpansion":
+        raise ValueError
+    if value["expansion_type"] not in {"slash_command", "mcp_prompt"}:
+        raise ValueError
+    if value["command_name"] not in commands:
+        raise ValueError
+    for name in required - {"hook_event_name", "expansion_type"}:
+        if not isinstance(value[name], str):
+            raise ValueError
+    session = value["session_id"]
+    if not isinstance(session, str) or not re.fullmatch(r"(?:cairn:)?[A-Za-z0-9][A-Za-z0-9._:-]{0,255}", session) or session == "unknown":
+        raise ValueError
+    event_root = os.path.realpath(value["cwd"])
+    process_root = os.path.realpath(sys.argv[1])
+    if not os.path.isabs(value["cwd"]) or event_root != process_root or not os.path.isdir(event_root):
+        raise ValueError
+    print(json.dumps({
+        "schema_version": 1,
+        "harness": "claude-code",
+        "command": value["command_name"],
+        "session_id": session,
+        "project_root": event_root,
+    }, separators=(",", ":")))
+except Exception:
+    sys.exit(1)
+PY
+) || block
+
+decision=$(printf '%s' "$validated" | node "$COORDINATOR" harness-before 2>/dev/null) || {
+  printf '{}\n'
+  exit 0
+}
+
+case "$decision" in
+  '{"schema_version":1,"decision":"block","reason":"capability-disabled"}') block ;;
+  '{"schema_version":1,"decision":"allow"}') printf '{}\n' ;;
+  *) printf '{}\n' ;;
+esac

package/claude/hooks/compaction-capture.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# PostCompact hook: persist the harness-produced compaction summary locally.
+# The hook never generates or changes a summary and always fails open.
+set -euo pipefail
+
+case "${CAIRN_COMPACTION_CAPTURE:-}" in
+  1|true|TRUE|yes|YES|on|ON) ;;
+  *) exit 0 ;;
+esac
+
+repo="$(pwd)"
+ARTIFACT_ENTRY="@@INFRA_ROOT@@/mcp-memory-server/dist/artifact-cli.js"
+[ -f "$ARTIFACT_ENTRY" ] || exit 0
+
+# The payload has no version field. Resolve the running harness locally so an
+# unpinned future shape cannot be accepted merely because its keys look known.
+harness_version=$(claude --version 2>/dev/null | sed -nE 's/[^0-9]*([0-9]+\.[0-9]+\.[0-9]+).*/\1/p' | head -1)
+[ -n "$harness_version" ] || harness_version=unknown
+
+# Forward the documented PostCompact payload unchanged. The local CLI owns
+# shape validation, redaction, and persistence; this boundary stays bounded
+# and cannot block or fail the harness event.
+node "$ARTIFACT_ENTRY" capture-claude "$repo" --harness-version "$harness_version" <&0 >/dev/null 2>&1 &
+capture_pid=$!
+(
+  sleep 3
+  kill -KILL "$capture_pid" >/dev/null 2>&1 || true
+) &
+watchdog_pid=$!
+wait "$capture_pid" >/dev/null 2>&1 || true
+kill "$watchdog_pid" >/dev/null 2>&1 || true
+wait "$watchdog_pid" >/dev/null 2>&1 || true
+
+exit 0