Cairn

---

A cairn is a stack of trail-marker stones. Travelers each add a stone, and everyone who follows benefits. Each coding session leaves a marker the next one follows (memory); a cairn is minimal — only the stones you need to navigate (lean, no-loss context).

Cairn sits between your AI coding agents (Claude Code, Codex, OpenCode, Cursor, …) and your code. It runs as one small server you self-host once, and every device + agent connects to it through a single MCP endpoint plus lifecycle hooks.

Why

AI agents fail on long, multi-session work in ways bigger context windows don't fix:

• They forget everything between sessions.
• They re-read files they already read, burning tokens.
• Quality decays over long tasks (context rot, reasoning drift, silent corruption).
• Memory is siloed per machine and per tool.

The bottleneck usually isn't the model's IQ — it's the context fed to it and the drift over time. Cairn fixes that.

The five pillars

1. Remember — decisions, tasks, and rationale persist across sessions, devices, and agents.
2. Compress without loss — files, shell output, and responses shrink in the window but stay fully recoverable (expand/recover). Cairn keeps the full-fidelity original; the agent gets a compact view + a handle.
3. Assemble lean context — fight context rot by feeding less, higher-signal, well-ordered context under a token budget.
4. Stay reliable — verify agent edits against retained originals, snapshot/rollback tracked files, and keep a task anchor on long tasks (active guardrails).
5. Get smarter together — learn your preferences and opt into a sanitized, federated collective knowledge pool so cheap/small models behave like senior, personalized engineers.

Proof

Run cairn bench on your own repo to see the savings. Measured on Cairn's own crates/ (25 files):

Mechanism	Before	After	Saved
AST outline reads (feed code as structure)	~59,052 tok	~5,894 tok	90%
Re-reading an unchanged file	~6,506 tok	~19 tok	99.7%
Shell output (a verbose test log)	153 lines	1 line	99%

All of it is lossless — the full original is retained and one expand away.

Status

🚧 Active development — the engine is functional today (memory, no-loss compression, context assembly, edit guardrails + reliability score, shell compression, preference learning, privacy-first sanitization, a federated collective-knowledge pool, and multi-device sync). HelixDB (graph + vectors) is Cairn's datastore, with hybrid recall — HNSW vector search fused with BM25. Point CAIRN_HELIX_URL at a HelixDB server, or use the bundled docker compose stack, which runs one for you. See the design plan.

This repo is a Cargo workspace:

Crate	Role
cairn-core	shared domain types, hashing, config
cairn-store	HelixDB graph+vector store (the StoreBackend) + content-hash blob store
cairn-context	cached reads · AST signature outlines (11 languages) · byte-identical expand
cairn-memory	remember · BM25 recall · wakeup · Ebbinghaus decay · 4-tier consolidation
cairn-assemble	token-budgeted, edge-ordered context assembler (anti-rot)
cairn-guard	verify edits vs originals · task anchor · checkpoint/rollback · reliability score
cairn-shell	RTK-style command-output compression (lossless via expand)
cairn-profile	preference learning — inject how you work
cairn-share	privacy-first sanitization — redact secrets/PII, classify shareable/review/private
cairn-mcp	MCP server (stdio)
cairn-api	axum REST API + embedded web UI
cairn-cli	the cairn binary (serve, mcp, run, hook, install, …)

Install

# Linux / macOS — one-liner (downloads the latest release binary)
curl -fsSL https://raw.githubusercontent.com/Vellixia/Cairn/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Vellixia/Cairn/main/scripts/install.ps1 | iex

# Docker — the full stack (Cairn + HelixDB), the easiest path
docker compose up -d

# From source
cargo install --git https://github.com/Vellixia/Cairn cairn-cli

Cairn stores its data in HelixDB, so cairn serve needs CAIRN_HELIX_URL set (or use the docker compose stack above, which starts one and wires it up). See Self-host with Docker.

Then run cairn serve and open http://127.0.0.1:7777.

Topology: one server, many devices