cairn

Continue the work. Recall saved decisions, plans and observations across sessions and agents.
Challenge the claim. Every claim carries who said it; corrections keep the earlier record; a disagreement keeps both sides.
Control access. Scope, grants and classification are checked on every read and write.

Semantic search is optional. Agents must explicitly save context; Cairn does not silently capture conversations.

See it happen

A handover that includes the mistakes. Val (Codex) records an incomplete fix for a real deepdiff bug. Spike (Claude) picks the work up through Cairn and disputes it. An independent verifier tests both fixes and validates Spike's. A fresh Claude session then uses Cairn to write the pull request text.

91-second edited demo · Full transcript · Evidence and checks

Real tool calls on a disposable instance. Headings and summaries are written for the edit; excerpts are verbatim and labelled; waiting time is shortened.

Minimal mechanism demos: a correction with Garden and Attic · a plan checked against its Attic source

Try it: run the disposable quickstart — one throwaway instance, no OpenAI API key.

Related MCP server: Agent Memory

Install

The guided installer explains each stage, verifies the result, and can resume, roll back or remove what it installed. Run it from the root of a checkout of this repository on Linux x86_64. The public repository on GitHub, veridian69/cairn, is the distribution source; record the revision you install from.

git clone https://github.com/veridian69/cairn.git
cd cairn
git rev-parse HEAD
./cairn-install

It asks for a mode, a name and a port. New here? Choose disposable — Attic-only memory, no OpenAI key, stopped after verification; blitz removes it.

To install a specific release, check out its tag after cloning and record that revision instead.

Semantic search is optional everywhere and requires an OpenAI API key, read from a protected file — see supplying the key. Custody, lifecycle and audit all work without it.

Platform notes. The source launcher accepts host Python 3.12–3.14; Cairn's locked managed application runtime and container use Python 3.14. macOS runs foreground and native background memory plus Attic via a login-scoped LaunchAgent (validated on macOS 26, Intel and Apple Silicon; logout/login and macOS 12 untested) — but Garden is not supported on macOS. Native Windows support is limited to the cairn-mcp STDIO relay for Codex (setup).

Full flag, stage and recovery reference: guided installer.

Then, day to day

uv sync --locked
uv run --locked cairn-memory --profile ./memory-profile.json check
uv run --locked cairn-memory --profile ./memory-profile.json arrive <<'JSON'
{"query":"Current decisions and unfinished work"}
JSON

cairn-memory is explicit by design: a strict JSON connection profile fixes the endpoint, instance, scope, classification and credential file. It never discovers credentials and keeps no local transcript. See the everyday command guide.

How it fits together

Two compatible API families over one catalogue: custody and administration at REST /v1 and MCP /v1/mcp, and the conversation-oriented memory API at REST /memory/v1 and MCP /memory/v1/mcp — arrival briefings, recall, history, remembering, correction, disagreement, suggestions, proposals and connection diagnosis.

flowchart LR
    C[Clients and agent hosts] --> T{REST or MCP}
    T --> A[Scope, grant and classification checks]
    A --> S[Cairn authority]
    S --> Q[(SQLite catalogue)]
    S --> E[Hash-chained audit]
    Q --> O[Durable outboxes]
    O -. optional .-> V[Evidence adapter]
    O -. optional .-> P[Semantic projection]
    P -. candidates .-> S

Generated contracts define the wire surface: memory OpenAPI · memory MCP tools · /v1 OpenAPI · /v1 MCP tools.

• One serving process per SQLite data directory; requires reliable POSIX locking and fsync.

• The listener is plain HTTP. Terminate TLS and rate-limit at a reverse proxy or ingress before it leaves numeric loopback.

• Bearer credentials live in owner-only files. The memory API never issues or discovers them; /v1 administration issues a credential to an admin and returns its plaintext once.

• Browser connectors (claude.ai, ChatGPT) reach Cairn only through cairn-edge behind Cloudflare Access. The edge maps each inbound path to its own principal and holds that principal's credential, so nothing at the edge becomes a principal silently.

• Recalled text is attributed, untrusted data. It must never become system or developer instructions.

• Graph-backed semantic retrieval is optional.

• Docker Compose and conformant Kubernetes are supported shapes. The OpenShift overlay is statically validated with no claimed target acceptance.

• This repository claims no published container image; deploy from a trusted checkout or a separately reviewed digest.

Further reading

Client guide · Shared-memory guide · Python client · Restart-safe sessions · Host workflows · Memory suggestions · Semantic fact search · v0.1 contract · Deployment · Backup and restore · Local MCP relay · Edge for browser connectors · Garden agent chat

Development

uv sync --locked
make check

The locked gate covers formatting, linting, typing, tests, generated contracts, deployment renders and dependency audit. The hosted check runs on demand: Actions → Check → Run workflow, or gh workflow run check.yml --ref BRANCH. GitHub excludes the marked Bubblewrap/namespace tests and says so in the run summary — run make check locally for the complete suite.

Contributing · Security reporting · v0.8.2 release notes · macOS native installation

Apache-2.0 (license · notices). Cairn is the memory service behind Drystane, the control plane that prompted its design.