Cairn — An Agent-Native Research Collaboration Framework

§1 — What Cairn is

A research group's accumulated thinking, made durable and queryable.

Cairn is a tool and design standard for hybrid human/AI research collaboration. It defines a small set of repository conventions, file schemas, and agent skills, and provides a Python package plus an MCP server that lets every Claude Code session read from and write to a project's shared memory — the decisions, findings, open questions, action items, meeting notes, and tracked alternative explorations that accumulate over the life of a project.

The name borrows from the stone markers travelers build along trails — cairns. Each person who passes adds to the pile. The cairn persists for those who follow, points to the path, and survives the absence of any individual builder. Its construction is collective; its inspection is open; its purpose is to make the accumulated knowledge available to anyone walking the route later.

The word carries over: a research project's repository, organized following Cairn's conventions, is itself a cairn. There is one cairn per project. Cairn — capitalized — is the framework that defines what a cairn looks like and provides the tooling to create and operate one. A cairn sits alongside a project's code, data, and paper repositories, never inside one of them.

Research groups already have collective knowledge. It lives in meetings, side conversations, individual memories, scattered docs, and the slow accretion of folklore among long-tenured members. Cairn is an attempt to make that substrate explicit, durable, and shared — without burdening the group with overhead that the agent itself can absorb.

§2 — Two foundational commitments

Where work happens, and where state lives.

Cairn's design choices are driven by two paired commitments: one about where work happens, the other about where state lives. Holding both lines simultaneously is what makes the framework feel like a quiet collaborator rather than a new tool to learn.

Augmentation, not replacement.

Cairn does not redirect how collaborators work. They keep using their normal tools — git, Zoom, Slack, email, paper, conversation — at their normal rhythm. An agent listens in those native channels and writes structured notes into the cairn as a side effect. The agent's role is facilitator, not stenographer: it may ask focused clarifying questions, but it does not propose new rituals or interrupt the user's flow.

Substrate as specification.

All canonical project state lives in a git repository — plain markdown and YAML files, inspectable in any editor, versioned by git. Every other component (MCP server, vector indices, dashboards, agent skills) is a derived view that reads from or proposes writes to that substrate. No proprietary backend. Stop-and-rebuild yields identical results.

The first commitment says how: the people doing the work shouldn't have to think about cairn very often. The second says where: project memory is files in git, reproducible from itself. Together they describe what cairn is for, and what other tools in this space typically aren't.

A useful test, when designing or evaluating any feature: would a thoughtful new collaborator joining the project naturally be doing this same thing? If yes, an agent should do it transparently. If it requires the user to learn a new verb, adopt a new tool, or perform a new ceremony, it violates the second principle.

§3 — What it looks like in use

Five scenes from a cairn-equipped project.

The Tuesday meeting you missed

A collaborator who was traveling on Tuesday opens Claude Code in the project repo on Thursday morning. They ask the agent what was decided on Tuesday. The agent calls the cairn's MCP list_decisions tool with a date filter, finds the three decisions logged during the meeting, names them by their D-NNN IDs, and offers to load the rationale for any that look surprising. The user picks one, reads two paragraphs of context, and asks a follow-up question about a related open question (Q-014) the decision didn't resolve. The decision was captured by whoever drove the discussion; the catching-up reader never had to be there.

Onboarding six months in

A new postdoc joins. Their first Claude Code session reads PROJECT.md, the collaborators list, and the most recent month of decisions and findings — a few minutes of context vs. days of meeting recordings and Slack archaeology. When they ask "why are we using stratified resampling rather than SMOTE?", the agent surfaces D-007 with its context, links it to the finding 2025-08-12-stratified-beats-smote, and shows the open question that was resolved in the process. The first week is spent contributing rather than catching up.

Bootstrapping from an existing project repo

A group adopting cairn for an already-running project doesn't start from a blank slate. Their Claude Code agent follows the bundled bootstrap_from_repo skill: surveys the code repo's README, any docs/decisions/ ADRs, the git merge history, contributor list, and prominent TODO markers; drafts a single batched proposal of inferred collaborators, decisions, findings, and open questions; gets one consent gate from the user; and writes each entry with its actual historical date and structured PR / commit provenance. By the end of the bootstrap, the cairn reflects the project's pre-cairn history as faithfully as the agent could reconstruct it — and live capture starts from a grounded baseline rather than a void.

Pair coding with backdated capture

Two collaborators are working through a refactor together over a video call. The lead's Claude Code agent is in the call's transcript — listening, asking the occasional clarifying question, summarizing decisions back to confirm wording. Every time the pair commits to an approach ("let's drop the SHA index, the path-based one is good enough"), the agent records it as a decision via add_decision, attributed to both authors via the planned plural-author schema (ADR-0011) or to a consensus collaborator in the interim. The pair never alt-tabs to a notes app, never picks who gets credit, never logs anything by hand.

An async AI collaborator

The group's literature monitor runs nightly. It's registered in the cairn as a collaborator with type: ai-collaborator and configured permissions. Each night it pulls new arXiv papers in the project's subject area, summarizes the ones that bear on open questions or recent findings, and writes them as findings under its own attribution into a dedicated branch — never main. In the morning, the group's lead skims the proposed branch, accepts what's useful, ignores or rejects what isn't, and the day's work starts from a slightly richer prior than yesterday's.

Two scenarios worked through in more detail — concrete examples of what each user does and how the agent reaches the right cairn: one user, many cairns · many users, one cairn.

§4 — How it works

A git repo, an MCP server, two access modes.

The cairn — files in git

A cairn is a standalone git repository organized following Cairn's conventions. State files (YAML) hold decisions, open questions, action items, goals, and collaborators. Markdown files hold meeting notes, findings, exploration manifests, and the project's overview. Every write is attributed via git authorship; every change is versioned. The repo can be cloned, forked, archived, exported — all the things git already does well.

This is the entire base substrate. You can use a cairn with nothing but a text editor and the cairn CLI, and it works. The git history is the single source of truth.

The MCP server — the agent's interface

On top of the substrate, the cairn mcp server exposes about 30 read and write tools to Claude Code: whoami, status, add_decision, add_finding, add_action, complete_action, add_open_question, resolve_open_question, semantic project-section getters and setters, exploration lifecycle, skill discovery, and lookups. One server serves all of a user's cairns; each tool accepts a cairn parameter naming the target, and defaults to the only registered cairn when there's just one.

Critically, the MCP server owns no state. Every byte it returns is reproducible from the cairn's files. Every write the server accepts goes through the same Python functions the CLI uses. The MCP server is a derived view that happens to be the agent's natural interface.

Client and server access modes

Most of the time you're in client mode: a Claude Code session opened wherever real work happens — typically your project's code repository, but in future also a Zoom transcript, a Slack thread, or any other native channel. The cairn is a transparent backend the agent calls into via MCP; you may not even notice it's there. This is the everyday surface.

Server mode is for occasional maintenance — working inside the cairn directory itself, often through the cairn CLI, for a deep debrief, a structural cleanup, planning the next meeting, or spelunking through accumulated history. Most cairn-using sessions are client-mode; server-mode sessions are deliberate.

The agent's posture

The MCP server's session-start instructions orient the agent to the facilitator-not-stenographer role: capture quietly during conversation, ask focused clarifying questions only on substance, never propose new rituals or ask the user to run CLI commands, debrief at the end of a working block rather than micro-confirming every capture inline. The bundled skills (log-finding, log-decision, log-action, debrief, bootstrap_from_repo, and others) codify the workflows the agent should follow when the corresponding trigger fires in conversation.

§5 — Get started

Five minutes to your first cairn.

The full setup walkthrough lives in QUICKSTART.md. The condensed shape:

Install: pipx install 'cairn[mcp] @ git+https://github.com/cranmer/cairn'.
Register the cairn: cairn register myproject ./myproject-cairn --init (scaffolds and registers in one step).
Wire MCP into Claude Code: claude mcp add --scope user cairn -- cairn mcp. One-time, ever — same command no matter how many cairns you have.
Pair your project repo: cd myproject && cairn link --name myproject.
Open a Claude Code session in your project repo and ask the agent "what cairn tools do you have?" to confirm. For a project with existing history, follow up with "please bootstrap this cairn from this project repo" and the agent will follow the bootstrap_from_repo skill.

Two scenarios are documented in QUICKSTART.md with concrete commands: starting from scratch (new project), and bootstrapping from an existing project repository's accumulated history. The same setup serves both.

Source on GitHub · Quickstart · Architecture · ADRs