cairn

A perfect memory can still be wrong.

Cairn is a Linux-native shared memory service for humans, agents and automation. It keeps attributed observations, preserves earlier beliefs when they are corrected and lets different perspectives coexist. Scope, classification and grants are enforced by the server; a stored claim does not become established truth merely because it was remembered.

Persistence is the starting point. Accountable memory is the point.

Related MCP server: cairn

What memory has to answer

• Who said this? Facts retain provenance and a trust class.

• Who may rely on it? Realm and path scope, grants and classification govern every read and write.

• What changed? Correction and invalidation preserve history rather than silently replacing it.

• What disagrees? Disagreements retain both attributed endpoints; recording one does not decide who is right.

• Was it saved? Mutations return durable receipts. Replaying an identical operation with the same idempotency key does not create another write.

• Can search cross those boundaries? Retrieval candidates are reconciled against the authoritative catalogue before disclosure.

Install Cairn

Start with the guided installer from the root of a trusted checkout on Linux x86_64. It explains each stage, verifies the result, and can resume, roll back or remove what it installed:

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

It asks for a mode (disposable, native or docker), a name and a port, and for the two persistent modes whether you want Attic only or Attic plus semantic search. The quick install lists the prerequisites, non-interactive commands and expected result.

• Guided installer reference — every flag, stage, recovery path and the key-file procedure for semantic search.

• Disposable quickstart — throwaway Attic-only check, with the manual script behind it.

• Persistent native service — the manual systemd user-service procedure.

• Docker Compose — the manual Compose procedure.

• Kubernetes — separate manual operator path; the installer does not cover clusters.

RC2 (v0.1.0-rc.2, Python package 0.1.0rc2) adds authenticated exact evidence reads through REST /v1/read-evidence and MCP read-evidence. The response preserves accepted UTF-8 source bytes with their SHA-256 digest, independently of semantic indexing. Scope, grants and classification still govern access; reading source evidence does not validate its claims.

Semantic search requires an OpenAI API key. Installation and the Attic write/read checks work without one. The installer takes the key from a protected file, never from a command argument; see supplying the key. The manual Compose and native procedures have their own credential steps. The OpenAI key is separate from your Cairn administrator credential.

Interfaces

Cairn exposes two compatible API families over one catalogue:

• the custody and administration API at REST /v1 and MCP /v1/mcp;

• the conversation-oriented memory API at REST /memory/v1 and MCP /memory/v1/mcp.

The memory API adds arrival briefings, recall, history, remembering, correction, disagreement, suggestions, proposals and connection diagnosis. Generated OpenAPI and MCP tool documents define its wire surface. The original OpenAPI and MCP tool documents remain authoritative for /v1.

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

Use Cairn day to day

The cairn-memory command is an explicit Linux/WSL client. A strict JSON connection profile fixes the endpoint, expected instance, exact scope, classification and credential file. It never discovers credentials or records a local transcript.

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

See the everyday command guide for recall, remembering, correction, disagreement, suggestions, proposals and exact retry. The shared-memory guide explains the trust model, while the Python client and restart-safe sessions cover application integration.

Optional Codex and Claude skill packages use that same command on native Linux or inside WSL, with all checkout and runtime files on the native Linux filesystem. Installation is explicit and does not observe arbitrary desktop or web conversations. The managed cairn-chat console starts fresh subscribed CLI processes for submitted turns; only receipt-confirmed facts provide continuity. See host workflows and the CLI adapter.

Native Windows support is limited to the cairn-mcp STDIO relay for Codex. It does not install the Linux/WSL daily command or capture conversations. Follow the Windows relay setup and supply the exact trusted upstream URL for your deployment.

Start locally from source

The source quickstart needs Python 3.12, uv 0.12.0, curl and jq. It creates an isolated instance under /tmp, keeps the bootstrap credential outside the checkout and uses synthetic memory. Retrieval stays disabled, so it makes no model-provider call.

uv sync --locked

Continue with the source quickstart. This repository does not claim a published container image; deployment instructions build from a trusted checkout or use a separately reviewed digest.

Operational boundaries

• Cairn runs one serving process per SQLite data directory and requires reliable POSIX locking and fsync semantics.

• Its listener is plain HTTP. Terminate TLS and apply rate limits at a reverse proxy or ingress whenever it leaves numeric loopback.

• Bearer credentials belong in owner-only files. Neither REST nor MCP issues them.

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

• Graph-backed semantic retrieval is optional. Catalogue custody, lifecycle and audit work without it.

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

Further reading:

• Client guide — authentication, scopes, calls and retry rules

• Memory suggestions — read-only duplicate, correction and disagreement evidence

• Semantic fact search — optional representation, degradation and rebuild

• v0.1 contract — normative behaviour

• Deployment guide — Compose and Kubernetes choices

• Backup and restore — recovery procedures

• Local MCP relay — Cloudflare Access bridge for Linux and Windows clients

Development

The locked quality gate covers formatting, linting, typing, tests, generated contracts, deployment renders and dependency audit:

uv sync --locked
make check

The hosted repository check runs only on demand. In GitHub, open Actions → Check → Run workflow, select the required branch, and run it. The equivalent CLI command is:

gh workflow run check.yml --ref BRANCH

GitHub excludes the marked real Bubblewrap/namespace tests and states that boundary in the run summary. Run local make check for the complete suite; automatic pull-request and main checks cover CI policy and the wheel, while the automatic image gate remains separate.

Cairn is licensed under the Apache License 2.0. It is the memory service used by Drystane, the control plane that prompted its design.

Project information

• RC2 release notes

• Contributing

• Security reporting

• Apache License 2.0 and notices