Alex, Morgan, and Sam are writing a physics paper together. They share one cairn over HTTP. Each works in their own session, on their own machine, with their own identity — and the project memory stays coherent.
The paper is a measurement of a new physics observable in LHC Run 3 data. Three collaborators are splitting the work:
Owns event selection, control regions, systematic uncertainties. Writes most of the analysis-decisions.
Runs the fit, generates closure tests, flags pulls and residuals. Logs the findings the methods discussion responds to.
Drafts the manuscript, tracks references, structures the methods section around the decisions Alex and Morgan land.
Their cairn — shared-physics-paper — lives on a group machine. The cairn mcp server runs there as a long-lived process on HTTP transport, bound to the group's network. Each collaborator's project repo on their own laptop carries a cairn.toml pointing at that server:
[cairn]
endpoint = "https://group-server.example.org/mcp"
name = "shared-physics-paper"Each contributor's bearer token authorizes the network connection; their author parameter on each write claims the identity. The two are deliberately separate: the token gets you onto the wire, the author says who you are. The cairn trusts contributors to claim themselves honestly — like signing a paper in a shared lab notebook.
It's a working Tuesday. All three have Claude Code open, each in their own copy of the project repo. They're not in a call; they're in async-collaboration mode. The cairn is the shared substrate they all reach.
Alex has been studying MET-balance plots and concludes the 30 GeV leading-jet cut is being dominated by pileup-induced fake jets. She tells her agent:
The agent calls add_decision against the HTTP server. The server allocates D-002 (D-001 was the V+jets control-region decision from two weeks ago), validates Q-001 exists in the cairn-wide id index, writes state/decisions.yaml on the group machine with author: alex, commits. Alex's confirmation:
Recorded D-002 in state/decisions.yaml; related: Q-001.She follows up with three more writes over the next ten minutes — an action item (A-001: produce updated efficiency tables), a decision to keep the existing trigger threshold (D-003), and a nuisance-grouping decision (D-004). Each landing on the same shared cairn, each attributed to alex.
While Alex is writing decisions, Morgan is running 1000-toy closure tests in a Jupyter notebook. The smoothing window of 5 bins over-smooths the third peak in the toy distribution by 1.3σ. Morgan opens her Claude Code session:
The agent writes knowledge/findings/2026-05-23-smoothing-window-of-5-bins-over-smooths-the-third-peak-in-th.md attributed to morgan. A few minutes later she adds a second finding (ttbar normalization pulls), and an action item (A-002: rerun toys with extended nuisances).
Crucially, Morgan never had to ask "which cairn?" or "what id should this be?" The server allocates ids; the cairn.toml at her cwd dispatches the calls; her bearer token gets her in; her --author morgan claims the attribution. Two findings + one action, no coordination overhead.
Sam is drafting the methods section. He wants to record the editorial decision to organize the section around the four orthogonal control regions, and a second decision to cite Hughes et al. 2026 as the canonical smoothing reference. He needs the latter to reference Alex's just-landed luminosity-nuisance decision.
Sam's agent reads the cairn's state/decisions.yaml via the MCP get_decisions tool — finds Alex's runtime allocations, picks D-004, and dispatches Sam's write:
The server allocates D-005, validates that D-004 exists, writes related: [D-004]. Sam adds a second decision (D-006: methods-section organization) and an action item (A-003: circulate the draft by Friday).
At the end of the afternoon, the cairn holds six decisions, three findings, one open question, three action items. Every entity carries the right author. No duplicate ids. No mis-routed writes. Three people, three sessions, one coherent project memory.
The server-side add_decision tool serializes id allocation: even though Alex's and Sam's writes interleave in time, no one gets a duplicate id, and the sequence D-002, D-003, D-004, D-005, D-006 is dense (no gaps from failed-then-retried writes). Same for action items — A-001 through A-003 reflect the actual race order of allocation across all three writers, not any client's internal ordering.
Attribution is per-call. Each write tool requires an author (or assignee) parameter naming a registered collaborator. The server validates against state/collaborators.yaml and refuses unknown ids loudly. The bearer token authorizes the connection but doesn't pick the author — that's the writer's job.
Cross-references work because the cairn-wide id index is server-side. When Sam's write claims related: [D-004], the server checks D-004 exists right now, in this same cairn, regardless of which collaborator allocated it or when. No two-phase commit, no eventual consistency — the writes serialize through a single process on a single disk.
The concurrency is loose. Three collaborators in three sessions interleave at the timescale of paragraphs and CLI invocations — every few seconds, not every few microseconds. That's exactly the texture of multi-author paper work: realistic interleaving, clean serialization, no race-condition surprises when two writers happen to land at the same moment.
Each collaborator works on their own copy of the project repo (their code, their drafts, their notebooks). The cairn is the only shared piece. There's no merge conflict on a paper draft because the paper draft isn't shared through cairn; cairn holds the decisions about it. The substrate is git; the project repo and the cairn are two separate git repos that happen to know about each other.
By the time the paper is ready to circulate, the cairn holds the project's case history. Every methodological choice has a decision entry with the context that produced it. Every closure-test surprise sits in knowledge/findings/ with a date and an author. The open questions that drove the design — JER double-counting, the right reference for the smoothing prescription — are still there, now answered, with the decisions that resolved them linked back.
Six months from now, when a referee asks why the leading-jet pT cut is 40 GeV rather than 30, no one has to dig through Slack history or guess from commit messages. The answer is in D-002 with Alex's name on it. The lit search that motivated it is in Sam's related chain. The closure tests that confirmed it didn't break the fit are Morgan's findings from that Tuesday.
Adding a fourth author later means handing them the endpoint, a token, and a pointer to PROJECT.md. They read a few minutes of context — what's open, what's decided, who's working on what — and start contributing on Monday rather than spending a week catching up. The shared cairn is what makes that possible.