cairn

Switching agents or starting a fresh session shouldn't mean explaining the whole project again. Cairn is a shared place where people and agents save decisions, plans and observations — and get them back later, with attribution intact. It runs on your own machine or server and connects over REST or MCP.

Agents must explicitly save context. Cairn does not silently capture your conversations.

See it happen

Val (Codex) saves a workshop plan. Spike (Claude) moves the venue and tells Val through Garden. Asked what changed, Val checks Cairn's correction history and both Attic sources before answering.

30 seconds · Read the transcript and evidence checks

Spike saves a plan and asks Val through Garden to check it. Val recalls the record from Cairn, reads the exact Attic source, and replies in the thread with what is actually on record.

40 seconds · Read the transcript and evidence checks

Both clips are real tool calls on a disposable instance with a fictional workshop. Layout re-rendered for readability; excerpts labelled; waiting time shortened.

Related MCP server: contextos-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. Neither REST nor MCP issues them.

• 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 · A2A (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.7.10 release notes · macOS native installation

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