Shared graph memory · local-first · MIT

Agents change code.
Cairn remembers why.

A local MCP server that gives every coding agent the same memory — decisions with their reasoning, changes with provenance, open questions, risks, and handoffs. Written as Markdown you own, connected as a graph they can query.

npx cairn
  • Node 20+
  • 14 MCP tools
  • Zero native binaries
  • No telemetry
127.0.0.1:4242 workspace
The Cairn workspace showing the vault brief, note and link counts, open threads, recent decisions, a memory map, and agents in the vault. The Cairn workspace in dark theme, showing the same brief and memory overview.
Wire the agents you already run
  • Claude Code
  • Cursor
  • Antigravity
  • VS Code
  • Codex
  • Gemini CLI
  • Windsurf
  • Zed
  • OpenCode

The reset problem

Every session starts from zero. Your project doesn't have to.

Claude Code, Cursor, Codex, Copilot — each one boots clean. So tradeoffs get relitigated, decisions get quietly reversed, and the reason a file looks the way it does disappears with the chat window.

Without shared memory

The project forgets

  1. A decision is made in chat.

    The reasoning, the rejected alternatives, the constraint that forced it.

  2. The chat closes.

    Only the code survives. The rationale does not.

  3. The next agent proposes the opposite.

    It has no way to know the question was already settled.

  4. Nobody remembers which one won.

    Or why. Or what would have to change for the old call to be right again.

With Cairn

The project remembers

  1. The decision is written once.

    Context, choice, why, alternatives, consequences — with an immutable id.

  2. Every agent reads it before acting.

    Accepted decisions are constraints, not suggestions.

  3. Changes link to the decision they implement.

    Files, commits, sessions, and agents all become edges in the graph.

  4. Superseded calls stay in the graph.

    Marked superseded, linked to the replacement, never silently erased.

Memory isn't a longer prompt.
It's a place.

A prompt is carried by one session. A vault outlives every session, every agent, and every model upgrade.

Cairn keeps one vault per project — or one across all of them — and gives each agent a small, standard interface to it. The memory is a folder of Markdown. The intelligence is in the links.

The working loop

Read. Work. Record. Hand off.

Cairn isn't a write-only log. It is a loop the agent runs every session: load what is already known, act on it, record what changed, and leave the next agent a clean starting point.

  1. 01

    Recall

    Load the project brief. Search before choosing an approach. Open the notes behind a decision before editing the file it governs.

    • memory_context
    • memory_search
    • memory_get
  2. 02

    Work

    Edit code as usual. Claude Code hooks append edits to a rolling worklog; git commits are captured with files, stats, and provenance. Diffs are not stored by default.

    • capture_changes
    • cairn capture-commit
  3. 03

    Record

    One idea per note. The title is a claim. The body carries the why, the alternatives rejected, and the consequences. Link it to what it implements or blocks.

    • memory_write
    • memory_update
    • memory_link
  4. 04

    Hand off

    Close with a summary and concrete next steps. Send a direct message or a structured handoff when another agent must continue without asking what happened.

    • memory_handoff
    • memory_send
    • memory_end_session

Why it holds The loop is installed as an always-on rule in the client, so the agent knows to read before acting and write while the context is still true. Skill-aware clients also get the long-form playbook.

Architecture

A folder of Markdown.
A graph in memory. Three ways in.

No database. No daemon required for the memory to exist. The vault is the truth; everything else is derived and disposable.

Figure 01 · runtime topology request path derived / read-only
01Agents

Every client you already run

one server instance per agent

Each coding client launches its own Cairn MCP process over stdio. Its --agent handle stamps every write; its active session links them together. Hooks call back into the same store.

  • Claude Code
  • Cursor
  • Antigravity
  • VS Code
  • Codex
  • Gemini CLI
  • Windsurf
  • Zed
  • OpenCode
  • + generic
02Surfaces

Three interfaces, one contract

local processes
MCP

14 tools · 2 resources

Official SDK, tuned for model consumption: counts first, ids plus titles, single-line errors.

src/mcp/server.ts
CLI

init · connect · capture · inspect

Vault setup, client wiring, hook entrypoints, search, timeline, export, health checks.

src/cli/index.ts
Workspace

HTTP API + SSE

Password-gated UI on 127.0.0.1:4242. JSON routes and a live event stream share the same store.

src/cli/server.ts · web/
03Store

One operation surface

src/core/store.ts

Write, update, ranked search with snippets, graph queries, timeline, sessions, capture, messages, inbox, and handoffs. Project resolution is identical on every path: explicit argument → vault config → detected folder or package name.

  • write
  • update
  • search
  • graph
  • timeline
  • sessions
  • capture
  • messages
  • inbox
  • handoffs
04Vault

Markdown is the source of truth

durable state
Root
.cairn/
├── cairn.config.json
├── README.md
└── notes/
Notes
notes/<kind>/
└── YYYY-MM-DD-<kind>-<slug>-<id>.md
    YAML frontmatter + free Markdown
State
state/
├── auth.json      0600
├── .write.lock
├── sessions/
├── inbox/
└── backups/

Hand-editable except id. Atomic temp-file + rename. Redaction runs before anything lands. Deletion is lazy: a linked note becomes a missing placeholder, never a dangling reference.

05Index

The graph is derived

in memory only

src/core/indexer.ts scans the vault on every server start and builds nodes, typed edges, and backlinks in one pass. Virtual nodes stand in for projects, agents, sessions, and files. Delete the index and you lose nothing.

  • note nodes
  • file nodes
  • agent nodes
  • session nodes
  • backlinks
  • 16 edge types
  • auto-link by file
Read top to bottom: agents reach one of three surfaces; every surface calls the same store; the store reads and atomically writes the Markdown vault; the in-memory index is rebuilt from that vault at startup. Dashed connectors carry derived state. The vault is the only thing you must keep.
01

Nothing is locked in

Notes are Markdown with YAML frontmatter. Open the folder in Obsidian, grep it, diff it in git, edit it by hand. The app is a view, not a gatekeeper.

02

The index is disposable

No index files, no database migrations, no persisted caches. Restart the process and the graph is rebuilt from the notes that exist.

03

Three surfaces stay honest

The MCP server, the CLI, and the workspace all pass through one store, so a note written by an agent and a note written by the UI land identically.

Delete the index and you lose nothing.
Delete the vault and you lose the memory.

The memory model

Twelve kinds of note. Sixteen kinds of edge.

A note is a Markdown file with YAML frontmatter. Its kind selects the folder and the lifecycle. Its fields connect it to files, sessions, agents, and other notes — and those connections are the product.

Decision

proposed → accepted → rejected → superseded

A choice plus the why, the alternatives considered, and the consequences. One decision per note.

Change

active → committed → captured

What landed, where, and by whom. Files, stats, commit provenance, and links to the decisions it implements.

Insight

active → archived

How something actually behaves — the thing you learned by reading the code or running the test.

Question

open → answered

An unknown that blocks or shapes the work. Answers link back with an answers edge.

Answer

answered

The resolution to a question, kept as its own note so the question's history stays intact.

Spec

draft → active → archived

Behaviour another caller can rely on. The contract a later change must not quietly break.

Risk

open → mitigated → accepted

A hazard with a blast radius, not a vague worry. Include what breaks and who feels it.

Task

todo → doing → done → blocked

A promised follow-up that isn't done yet, visible to the next agent instead of buried in a summary.

Message

Direct or broadcast coordination. Unread state per agent.

Handoff

Structured work transfer: summary, next steps, open questions, files.

Session

Who worked, on what goal, with which model and client.

Note

The general-purpose kind when nothing more specific fits.

Edges agents write

Set in relations, or created with memory_link.

  • relates_toThe default connection
  • implementsA change makes a decision real
  • supportsEvidence for a claim
  • contradictsNew evidence against an old call
  • depends_onThis breaks if that changes
  • blocksA risk or question holds up a task
  • answersAn answer resolves a question
  • supersedesA newer call replaces an older one

Edges Cairn derives

Computed from fields, wikilinks, and provenance — no extra work for the agent.

  • touchesA wikilink to a file path
  • mentionsA wikilink to another note
  • part_ofNote → project node
  • authored_byNote → agent node
  • in_sessionNote → session node
  • addressed_toMessage → agent nodes
  • handoff_toHandoff → recipient
  • replies_toMessage threading
notes/decisions/2026-11-17-decision-edge-limiter-01J9ZK.md
---
id: 01J9ZK3W7Q4M8N2P6R8T0V2X4A        # immutable
kind: decision
title: Move rate limiting to the edge
status: accepted
project: orbit-api
agent: cursor
session: 01J9ZK3W7Q4M8N2P6R8T0V2X4B
created: 2026-11-17T09:14:00.000Z
tags: [performance, edge]
files: [src/edge/limiter.ts]          # → touches
related: [01J9ZJ2M6P4Q8R0T2V4X6Z8B0D] # → relates_to
relations:
  - to: 01J9ZJ2M6P4Q8R0T2V4X6Z8B0D
    type: implements
supersedes: [01J9ZH0K4N2P6R8T0V2X4Z6B8D]
dedupe_key: edge-rate-limit-v1       # repeat writes upsert
aliases: [01J9ZK3W7Q4M8N2P6R8T0V2X4A]
metadata:
  commit: 4f2a91c
  branch: feat/edge-limiter
---

## Context
Every request currently crosses the region to reach one
central limiter. At peak, that hop is pure added latency.

## Decision
Keep the token bucket in the edge worker. Rejected the
central Redis bucket: one more network dependency on the
hot path, and a shared failure domain.

## Consequences
Per-edge counters can drift. Reconcile on a schedule and
link the follow-up spec.
01

Identity and lifecycle

id is immutable and ULID-ish. kind selects the folder and the status machine. The title is the graph label — make it a claim, not a category.

02

The graph fields

related, relations, supersedes, and files create typed edges. Wikilinks in the body create touches and mentions. aliases keep Obsidian wikilinks resolving.

03

Provenance

project, agent, session, and created record who wrote this and when. metadata carries structured payload such as a commit sha or branch.

04

Safe writes

dedupe_key turns a repeated write into an upsert. Redaction runs first, then an atomic write. Deletion is lazy, so the graph never dangles.

Everything is hand-editable except id. If you can edit a Markdown file, you can extend the memory.

The MCP surface

Fourteen tools. Two resources.
Zero ceremony.

Cairn runs as a local MCP stdio server using the official SDK. One instance per agent: --agent stamps every write, --project scopes it, and the session id links everything written in between.

Before work

Read

Call memory_context. Search the topic, file, or error before choosing an approach.

While working

Write

Record one idea per note as it becomes true. Link it. Capture the change set after edits.

Before stopping

Hand off

Close the session with a summary, next steps, and anything the next agent must not rediscover.

Read

6 tools

Cheap, read-only calls. Safe to make often; designed to be the first thing an agent does.

Cairn read tools
ToolWhat it returnsCall it when
memory_context The living brief: decisions in force, proposals, open questions, risks, recent changes, handoffs, unread messages, active agents, and high-context files. An optional focus appends a targeted search. First call in a task, or when switching projects.
memory_search Ranked results with snippets and ids across titles, bodies, tags, files, projects, and agents. Filter by kind, status, tags, or recency; search one project or all of them. Before choosing an approach, and before writing, to avoid a near-duplicate.
memory_get One note with its full body, typed relations, links out, backlinks, files, session, and related notes. After search or context surfaces an id worth reading in full.
memory_graph JSON {nodes, edges, stats} around seed notes or a query, depth 1–4. Optional file and agent nodes. Virtual project, agent, session, and file nodes have ids. Impact analysis: what implements, depends on, blocks, touches, or supersedes something.
memory_timeline Recent activity, newest first and grouped by day. Filter by project, agent, kind, and lookback window. Catching up after time away, or building a handoff.
memory_inbox Unread messages and handoffs addressed to you, plus broadcasts. Optionally include closed handoffs. When the brief shows unread items. Set mark_read once handled.

Write

4 tools

Durable changes. Every write is redacted, linked, and serialized against other processes.

Cairn write tools
ToolWhat it returnsCall it when
memory_write A new note with kind, title, body, status, tags, files, related ids, typed relations, recipients, session, dedupe key, and metadata. Files auto-link to related notes. A decision, insight, risk, question, spec, task, or change becomes true.
memory_update Append or replace a body; change status, tags, files, relations, or metadata. Append is the default, so outcomes accumulate safely. An outcome arrives, a question is answered, or a decision is superseded.
memory_link A typed edge between two notes: relates_to, implements, supports, contradicts, depends_on, blocks, answers, supersedes. A change implements a decision, a risk blocks a task, or an answer resolves a question.
capture_changes The git change set as change memory: files, stats, commit provenance, and automatic links to related decisions. Identical captures deduplicate. Diffs are omitted by default. After edits or a commit. Use a manual change note when there is no git repo.

Coordinate

4 tools

Sessions and agent-to-agent traffic. This is what makes memory collaborative instead of a personal notebook.

Cairn coordination tools
ToolWhat it returnsCall it when
memory_start_session Registers the session, marks the agent online, and returns the project brief. Reuses a recent active session when one exists. Later writes on the connection link to it automatically. At the start of substantial work, with a concrete goal.
memory_end_session Closes the session with a summary and next steps, and lists every note captured during it. Marks the agent offline. Before finishing, so the next agent resumes from a clean summary.
memory_send A direct or broadcast message with priority and reply threading. It appears in the recipient's inbox and brief. Coordination, review requests, questions, or status. Use to: "*" only when everyone needs it.
memory_handoff A structured handoff: summary, numbered next steps, open questions, files, priority, and a link to the current session. Another agent must continue without asking you what happened.

Two resources, for clients that prefer them

Resources are read-only Markdown. Any MCP client can fetch them without calling a tool.

cairn://overview

Vault statistics plus the current project brief. A fixed URI per server.

cairn://projects/{project}/brief

The living brief for any project in the vault. The template completes known project names.

Claude Code · orbit-api
illustrative trace

memory_context{ project: "orbit-api" }

brief · decisions in force · open risks · recent changes · 1 unread handoff

memory_search{ query: "rate limiting edge", kinds: ["decision", "risk"] }

3 notes · best match: “Move rate limiting to the edge” 01J9ZK…

memory_get{ id: "01J9ZK…" }

decision · accepted · 2 backlinks · touches src/edge/limiter.ts

memory_write{ kind: "decision", title: "Reconcile edge counters hourly", files: ["src/edge/reconcile.ts"] }

recorded · auto-linked 2 related notes · session attached

capture_changes{ scope: "workspace" }

change captured · 4 files · linked to 1 decision

memory_handoff{ to: "cursor", summary: "Limiter moved; reconciliation is stubbed.", next_steps: ["Implement hourly reconcile", "Add drift alert"] }

handoff created · cursor sees it in memory_inbox

Tool names, arguments, and response shapes are real. Ids and note content are examples; exact wording varies by client and model.

Install

Two commands to a shared memory.

Node 20 or newer. Run from the project root; Cairn creates .cairn/ if it doesn't exist. Every install step is idempotent, and every file it touches is backed up first.

Before you start node --versionv20 or newer npm available via npx Git optional — only capture_changes commit scope needs it
  1. 01

    Launch

    First run creates the vault, starts the workspace, and prints a one-time password. Replace it at the first login — the generated password cannot open a lasting session.

    npx cairn
  2. 02

    Wire a client

    Writes the MCP entry, the always-on rule, and — where supported — the skill and hooks. Add several clients in one command.

    npx cairn connect claude-code --git-hooks
  3. 03

    Verify

    status prints the vault, note count, live workspace, wired clients, and the exact MCP command. doctor is a read-only health check.

    npx cairn status

Per-client wiring

Four clients are configured automatically. The rest print a snippet to paste — Cairn never edits a config it doesn't own.

  • auto-configures
  • prints a snippet

Claude Code

The full integration: MCP server, three session hooks, a git hook, the rule, and the skill.

auto-configures
npx cairn connect claude-code --git-hooks

Writes

  • .mcp.jsonProject-scope MCP server
  • .claude/settings.jsonSessionStart, PostToolUse on edits, SessionEnd
  • CLAUDE.md / AGENTS.mdMarked <!-- cairn:start --> instruction block
  • .claude/skills/cairn/SKILL.mdThe long-form agent playbook
  • .git/hooks/post-commitOnly with --git-hooks: captures every commit

Then

Restart Claude Code. The hooks inject the brief at session start, append edits to a rolling worklog, and close the session at the end.

Re-running is idempotent: existing Cairn hook groups are replaced, other hooks are preserved, and the instruction block is updated in place. Skip hooks with --no-hooks.

User scope instead of project scope
claude mcp add --scope user cairn -- node <path-to-cairn>/dist/cli/index.js mcp --vault .cairn --project <project> --agent claude-code

The agent gets a rule and a skill

Both teach the same loop at different depths. Clients without skill support still get the rule.

npx cairn skill --install
Rule

Always on

A compact session contract: read first, write decisions and changes as work happens, link them, never store secrets.

CLAUDE.md · AGENTS.md · GEMINI.md · .cursor/rules/cairn.mdc · .agents/rules/cairn.md

Skill

Loaded on demand

The long-form playbook: the full loop, note templates, examples, the tool map, and chat behaviour.

.claude/skills/cairn/SKILL.md
.agents/skills/cairn/SKILL.md

Inspect with cairn skill, print with --print or --print-rule, and install both standard locations with --install. connect installs it automatically for supported clients.

Project vault or global vault

One project, one memory — or one memory across every repo, scoped by project on each note.

Project and global vault modes
ModeLocationBest for
Project default<project>/.cairn/One project, one memory. Version or ignore the vault per your policy.
Global --global~/.cairn/Many repos sharing one memory. Pass --project <name> in each client entry so writes stay separated.

Connect flags

The same command covers vault choice, scope, provenance, and a dry run.

cairn connect flags
FlagEffect
--vault <path>Use a specific vault directory.
--globalUse ~/.cairn/ instead of the project vault.
--project <name>Scope writes when the client cannot pass a project.
--agent <handle>Override the author handle recorded on every note.
--git-hooksInstall the Claude Code post-commit capture hook.
--no-hooksWire the MCP server without Claude Code hooks.
--dry-runPrint what would change; write nothing.
Uninstalling Cairn

Run npx cairn connect --dry-run to review what is wired. Then remove the cairn entry from each client config, the marked block from CLAUDE.md / AGENTS.md, the hook groups in .claude/settings.json, and the vault folder if you no longer want the memory.

Redacted copies of every file connect edited are in vault/state/backups/.

The workspace

The graph is the point.

Cairn ships a no-build web app for seeing what your agents know: a force-directed graph, a living brief, the timeline, inboxes, handoffs, agent presence, and project scopes. It updates over SSE the moment another agent writes.

127.0.0.1:4242 / graph live
The Cairn memory graph: a force-directed canvas of note nodes connected by typed edges, with a filter rail and an inspector panel.
The memory graph. Notes are nodes; project, agent, session, and file hubs are virtual nodes. Edges are typed. Pan, zoom, drag, filter by kind, and inspect any node without leaving the canvas.

Living brief

Decisions in force, attention items, recent commits, and online agents — the same brief the MCP server returns.

Graph canvas

Force layout with collision-culled labels, kind filters, search highlighting, and an inspector for links and backlinks.

Timeline

Every note grouped by day, filterable by agent or kind. The fastest way to catch up after time away.

Coordination

Inboxes, handoff boards, unread counts, and live agent presence. Work changes hands without a transcript.

Omnibox and capture

⌘K or Ctrl K searches and navigates. N captures a note from anywhere in the app.

Live, local, themeable

SSE pushes refreshes in place. Light, dark, or system. No external fonts, scripts, or CDNs; no build step.

The workspace is served from the same Node process as the API. Run npx cairn ui --open to launch it directly, or let npx cairn do both.

Security & ownership

Local by default.
Yours by construction.

The workspace and API are password-gated and bound to loopback. The memory is plain Markdown on your disk. No account, no telemetry, no hosted copy.

One folder to back up

The vault is the whole product. Copy it, sync it, version it, or move it to another machine. Cairn rebuilds everything else.

.cairn/
├── cairn.config.json      name · project · settings
├── README.md              generated orientation
├── notes/
│   ├── decisions/         2026-11-17-decision-…md
│   ├── changes/
│   ├── questions/
│   └── …                  one folder per kind
└── state/
    ├── auth.json          scrypt hash + secret · 0600
    ├── .write.lock        cross-process lock
    ├── sessions/
    ├── inbox/
    └── backups/           redacted client files · max 40
npx cairn auth status npx cairn auth reset CAIRN_NEW_PASSWORD=… npx cairn auth set-password

Reset and set-password rotate the session secret, signing out every browser. The first-run generated password cannot open a lasting session; the login page forces a replacement.

  • Back upCopy .cairn/. No database dump, no export step.
  • ShareHand a teammate the folder. The files already make sense.
  • InspectOpen it in Obsidian, grep it, or diff it in git.
  • LeaveDelete the folder. No remote copy remains.

Password by default

The UI and API require a session. Passwords are salted scrypt hashes with 64-byte keys; the session secret never leaves state/auth.json. Only health, login, auth status, and login assets are public.

Hardened sessions

HMAC-signed HttpOnly, SameSite=Strict cookies with a 12-hour TTL and an in-memory server-side allowlist. Logout, reset, or restart revokes immediately. Failed logins are throttled per client address.

Request guards

Host is parsed and allowlisted before URL handling. Mutations require JSON content type, an allowed Origin, Sec-Fetch-Site, and a session-bound double-submit CSRF token.

Redaction at the boundary

Titles, bodies, backups, and requested diffs are scanned for private keys, cloud and API token shapes, and password= / api_key= / token= assignments before they land.

Capture filters

.env*, credential stores, key files, dependency and build directories, lockfiles, binary media, and the vault itself are skipped. Diffs are omitted unless explicitly requested; captures record what changed, never the patch body.

Files and concurrency

Writes are atomic (temp file + rename) with 0600 files and 0700 directories on POSIX. A reentrant cross-process lock is shared by MCP, CLI, and UI. Backups are redacted, capped at 40, and private.

Deploy

Run it on a laptop.
Or a team server.

Cairn is one Node process with a folder for state. The Docker image is multi-arch, runs as an unprivileged user, and expects TLS in front when you expose it.

Docker, one command

docker run -d \ -p 4242:4242 \ -v cairn_data:/data \ -e CAIRN_ALLOWED_HOSTS="cairn.example.com" \ -e CAIRN_PASSWORD="YourSecurePasswordHere" \ --name cairn \ ghcr.io/arshdeep-yadav/cairn:latest

The image starts with --host 0.0.0.0 --allow-remote, stores the vault at /data/.cairn, and probes /api/health. Add CAIRN_SECURE_COOKIE=1 once HTTPS is in front.

  • TLS in frontCaddy, Fly, or your load balancer terminates HTTPS. Cairn speaks plain HTTP on 4242.
  • Allowlist the hostSet CAIRN_ALLOWED_HOSTS to the exact public hostname — not a wildcard.
  • Keep the volume/data holds the entire memory. Without it, the container starts empty.
  • Never publish raw HTTPNo direct port-forward, no public 4242. Put a proxy and a password in front.

Environment

Cairn environment variables
VariableDefaultPurpose
CAIRN_ALLOW_REMOTE0Allow a non-loopback bind. Required outside Docker unless the flag is passed.
CAIRN_ALLOWED_HOSTSemptyComma-separated hostnames accepted in the Host header. Required for any remote bind.
CAIRN_SECURE_COOKIE0Marks auth cookies Secure. Set it when TLS terminates in front.
CAIRN_PASSWORDgeneratedSets the workspace password non-interactively on first run. Minimum 12 characters.
PORT4242Listening port.
HOST127.0.0.1Listening address. The image sets 0.0.0.0.
CAIRN_VAULTcwdDirectory containing the vault. The image sets /data/.cairn.
Is Cairn a database?

No. A vault is a folder of Markdown files with YAML frontmatter. Cairn builds an in-memory graph index at startup and throws it away on exit. There are no migrations, no index files to corrupt, and no lock-in.

Does anything leave my machine?

No. Cairn has no telemetry, no hosted service, and no external fonts, scripts, or CDNs. The workspace binds to 127.0.0.1 by default. If you deploy the container yourself, the data goes wherever you put the volume.

What happens when two agents write at once?

Read-modify-write operations take a reentrant cross-process lock at state/.write.lock, shared by the MCP server, the CLI, and the UI. Individual writes are atomic: temp file, then rename. On POSIX, files are 0600.

Can I open the vault in Obsidian or edit notes by hand?

Yes. The folder is plain Markdown. Wikilinks and aliases keep Obsidian links resolving, and frontmatter fields create the graph edges. Everything is editable except id, which the graph uses as identity.

Do I need git?

Only for commit capture. capture_changes and the post-commit hook read git; without a repository, agents can still write change notes manually with a files list. The rest of Cairn is independent of git.

Can one vault serve multiple repositories?

Yes. Initialize a global vault with --global at ~/.cairn/, point each client at it, and pass --project <name> in the server entry. Notes carry their project scope, and tools can search across all projects.

What happens if I delete a note others link to?

The note disappears; a missing placeholder node stays so the graph never has a dangling reference. Backlinks and the inspector show the gap instead of silently rewriting history.

How is this different from a long context window or a CLAUDE.md file?

Those live with one session or one repository and are rewritten wholesale. Cairn is queryable, append-only by default, shared across agents, and typed: a decision can link to the change that implements it and the risk that blocks it. Context is supplied; memory is maintained.

Which clients are supported?

Claude Code, Cursor, Antigravity, VS Code / GitHub Copilot, Codex, Gemini CLI, Windsurf, Zed, OpenCode, Omnirush, and any MCP client that accepts a stdio command. Four are configured automatically; the rest print a snippet.

What is the license and current version?

MIT. The current release is 0.1.0, requires Node 20 or newer, and ships with no native binaries.

Start here

Your agents will forget this session.
Give them somewhere to put it.

One command creates the vault, serves the workspace, and prints a password. Add a client, and the next session starts with context instead of a blank page.

npx cairn

Node 20+ · MIT · no telemetry · no hosted copy