Operates on the user's Git repository to checkpoint and recover coding sessions: cairn_checkpoint snapshots the working tree onto a shadow branch (cairn/snapshots/{session}/{checkpoint}) without committing, and cairn_rollback auto-stashes uncommitted work (git stash push -u), resets the repo hard to the chosen checkpoint while keeping the user on their own branch, then generates a handoff. Optionally creates a cairn/recovery/* branch for an inspection-only rollback.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cairn checkpoint this session before I refactor auth"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local MCP server that checkpoints AI coding sessions and — when things go wrong — recovers them with context. Not just a rollback. An informed restart.
See DESIGN.md for the full design document.
pip install cairn-mcp # heuristic-only
pip install cairn-mcp[ai] # with LiteLLM for auto-labels, handoffs, embeddingsRelated MCP server: Total Recall
cd your-project
cairn init # writes cairn.toml, gitignores .cairn/, installs ~/.cairn
claude mcp add cairn -- cairn startThen add @~/.cairn/cairn_agent.md to your tool's always-loaded context file
(CLAUDE.md, .cursorrules, .windsurfrules, or .roo/rules/cairn.md).
Full requirements and per-tool setup (Claude Code, Codex CLI, OpenCode, Roo Code, and others) are in INSTALL.md.
Command | What it does |
| Run the MCP server (stdio); a session starts on connect |
| Mark active sessions for this directory as ended |
| List sessions and checkpoints (or purged sessions) |
| Dismiss current drift signals (false positive) |
| Set up |
| Score drift detection against synthetic scenarios |
| List past eval runs |
Cairn exposes exactly six tools. Descriptions are terse and responses are compact JSON — the whole Cairn footprint in the model's context is budgeted at under 300 tokens.
Tool | Mode | What it does | Returns |
| async, fire-and-forget | Snapshot the working tree onto a shadow branch; |
|
| sync, atomic | Auto-stash, reset to checkpoint, write handoff + recovery gate ( |
|
| sync (drains queue first) | Run all drift signals: scope drift, write loops, error recurrence, semantic shift, token pressure |
|
| async | Record reported context usage for the token-pressure signal |
|
| async | Record a write/error/decision event for drift analysis |
|
| sync | Delete the |
|
flowchart TD
AI["AI coding tool<br/>(Claude Code / Cursor / Roo / Windsurf)"] -->|MCP protocol| SRV["Cairn MCP server<br/>(session starts on connect)"]
SRV --> CP["cairn_checkpoint(label?)"]
SRV --> LOG["cairn_log_event / cairn_log_usage"]
SRV --> DRIFT["cairn_check_drift()"]
SRV --> RB["cairn_rollback(checkpoint_id)"]
SRV --> ACK["cairn_acknowledge_handoff()"]
%% checkpoint path (async)
CP -->|"ACK immediately: {status: queued, id}"| AI
CP -.enqueue.-> Q["operation queue<br/>(worker thread)"]
Q --> SNAP["git snapshot on shadow branch<br/>cairn/snapshots/{session}/{checkpoint}"]
SNAP --> ROW["insert checkpoint row in SQLite"]
ROW -->|"on failure: revert git ref"| Q
%% logging path
LOG --> DB[("SQLite<br/>.cairn/cairn.db")]
%% drift path
DRIFT --> DET{"drift signals?<br/>scope drift · write loops ·<br/>error recurrence · semantic shift"}
DET -->|no| CLEAN["{drift: false}"] --> AI
DET -->|yes| EV["{drift: true, evidence, suggested_restore}"] --> AI
EV --> USER{"user decides"}
USER -->|dismiss| DISMISS["cairn dismiss<br/>(signals reset)"]
USER -->|inspect| INSPECT["rollback with inspect=true<br/>creates cairn/recovery/* branch"]
USER -->|rollback| RB
%% rollback path (sync)
RB --> STASH["git stash push -u<br/>(uncommitted work preserved)"]
STASH --> RESET["git reset --hard to checkpoint<br/>(user stays on their branch)"]
RESET --> HANDOFF["generate HANDOFF.md<br/>(LiteLLM or heuristic)"]
HANDOFF --> GATE["write .cairn/RECOVERY_ACTIVE gate"]
GATE -->|"{status: restored, stash_ref}"| AI
%% recovery path (next session)
GATE -.next session, branch matches.-> ACK
ACK --> ARCHIVE["delete gate, archive handoff,<br/>AI reads HANDOFF.md and resumes informed"]pip install -e .[dev]
pytestThis server cannot be deployed
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Persistent memory and drift detection for AI agents across session restarts.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
Shared memory across AI dev tools: each session hands its context to the next, not starting cold.
