Nine settled decisions.

The nine #

Two of these have been tested by being wrong first. Rule 4 was broken once, on purpose, to add relates — and it took a written argument. Rule 6 is why sync --push commits only build/, even though committing nodes would be more convenient.

What this deliberately isn't #

• Not an experiment tracker. W&B and MLflow own metrics and curves; the graph links out to them.
• Not a replacement for project repos. Nothing heavy ever enters: code by repo + commit, big outputs by host:/path.
• Not a general task manager — only research commitments.
• No server, no auth, no real-time editing, no discussion threads. A static HTML file in a git repo.

And the next step is deliberately not more features. The failure mode for a project like this is building the whole system and then not using it.

Why this can exist now #

Every prior attempt died on the same rock: capture cost.

Renku does compute provenance but has no concept of a hypothesis or a dead end. W&B, MLflow and DVC track runs and artifacts, not ideas. The HCI work — Kery's Variolite and Verdant, Burrito, Hindsight — attacked exactly this and needed a discipline nobody sustains, because a graph at 60% coverage is worse than none: you can't trust a missing node to mean “not tried.”

The agent doing the work can now write the record. Every design decision here serves that one fact.

What about Graphify?

Graphify turns a codebase into a queryable knowledge graph — tree-sitter AST parsing, typed edges (calls, imports, inherits), Leiden community detection, an interactive force-directed graph.html, and a generated report naming the most-connected “god nodes”. It is good, it is fast, and it is orthogonal to this.

The distinction is the one its own commenters kept making: Graphify maps the current state of a codebase; Cairn maps the history of research decisions. Graphify does read WHY: and HACK: comments and ADRs as first-class nodes, so it captures rationale that exists in the repo — but a dead end leaves no comment, because the code was deleted. “We tried fitting published final Tg values as Tgp and the literature refutes it” is not in any AST, will never be in one, and is exactly the node that stops the idea being had twice.

Practically: run both. Graphify in a project repo to orient in the code, Cairn across projects to know what has been tried. Three of its ideas were worth taking, and two are in here:

• The generated report as an entry point. build/report.md. Its “start here” section is Graphify's god-nodes idea; its “connections across projects” section is the surprising-connections idea, except the definition can be exact here rather than heuristic.
• EXTRACTED vs INFERRED on every edge, so you always know what was read versus guessed. The analogue that matters here is contemporaneity — was this node written the day the work happened, or reconstructed six weeks later? — and it was already derivable from git, so it cost no field.
• A git merge driver that union-merges the generated graph on parallel commits. Cairn's version of that problem is build/, and sync resolves it by regenerating rather than merging.

Not taken: force-directed layout (research history has a real time axis, and a force layout throws it away), and a vector store or MCP server for search — a few hundred nodes of text parse in well under a second.

Does it pay for itself? #

Cairn tracking Cairn. Measured, not estimated: per-turn usage from 40 agent transcripts — 29,797 assistant turns — over the same five weeks that produced the first 61 nodes.

Which means the question was posed wrong. Node-writing cost is a rounding error. The interesting quantity is where in the context distribution the work happens: turns above 300k context are 31% of turns but 52% of cost.

A memory file is paid per turn, not per node, because it sits in the context re-read on every one — a 6,000-word status doc costs about 1.8%, four times what writing those 61 nodes cost. The two differ in what survives, not in what they cost.

What would make me abandon this #

All three are nodes in the graph, and none is settled.

What isn't in question is whether the code is valuable: a few thousand lines, rebuildable in a week by anyone who has read the schema. If something durable is here, it's the empirical claim about capture cost.

Three things the first backfill found #

The backfill was the first real test of the tooling, and using the result was the second. Between them:

1. The pre-commit hook probed for the wrong thing. It looked for “a python3 that can import yaml”, which on the cluster is satisfied by a 3.6.8 too old to parse lib.py — so every commit was blocked with a SyntaxError reported as schema drift. Hence scripts/find_python.sh.
2. Frontmatter did not round-trip. An unquoted comma inside a flow-style history note split the value and turned its tail into a key: note: past 1,000 systems silently became note: past 1 plus a junk key 000 systems. 17 of the 55 backfilled nodes were affected. The writer now quotes flow scalars properly, and the validator rejects unexpected keys in a history entry so the same class of corruption can't return quietly.
3. Untyped edges lost information. Three findings could only be connected in prose. Hence relates — the one schema addition.

Two node types that wanted extra fields — milestones reaching for repo and artifacts — were made to use their bodies instead.