One human, many agents, one memory.

The problem

The fix in one line: capture what every agent does through hooks that already exist, compile it once into shared project knowledge, and hand it back at the start of every session. The maintenance that kills human wikis is exactly the work a model does for free.

Graph 1

The cast

Five moving parts. Four exist today; the fifth is what's being proposed.

Graph 2

How they work together

One task, start to finish. Each step is done by a different player.

step 06 feeds step 01 — the loop closes, and each pass starts better informed than the last

Graph 3

Inside step 04–06: how knowledge is made

The proposal itself, on one page. One rule shapes it: agents write evidence, one compiler writes knowledge — and the compiler only runs on main, after a merge.

Why merge-to-main is the moment. It's not just tidy — it's the correctness gate. Knowledge about code that never merged never becomes truth, and because the compiler only ever runs on main, two agents on two branches can't fight over a page. The thing that made this hard — work stranded on branches that never land — stops being possible.

Graph 4

Inside the compile

What actually happens when a branch lands. The useful idea here is borrowed: documentation as a build artifact — kept current by infrastructure, not by anyone's discipline.

Where this differs from documenting a codebase. A tool that reads only your source can regenerate its output at any time — nothing is ever lost. Three of the four writers above work like that. But why an approach was rejected is not in the code, and no future scan will recover it. That page is accumulated, never regenerated — which is why the evidence log exists at all.

Graph 5

What's actually in docs/

Every project gets the same page set — only the values differ. That's what makes it possible to ask one question across all of them at once. Standard templates organise by topic; this one organises by how each page stays true, because that decides who may write it and what a stale page means.

The page set:

Same schema, different values. Each architecture page carries typed frontmatter from a fixed vocabulary — so one query answers across every project at once:

More than one value is often correct — a public rest API alongside internal trpc is a normal shape, not a contradiction. And extending a vocabulary is itself a decision, so it gets an ADR.

Two rules that make it trustworthy. A page that doesn't apply — deployment for a CLI tool — says applies: false with one line of reason, because an empty page is ambiguous: not-yet-written and not-applicable look identical, and an agent can't tell them apart. And an accepted decision is never edited to say something different — a new one supersedes it. Having believed something is itself information.

Graph 6

Where knowledge lives today — and what each store is for

One store is the truth: the project's own docs/ folder. Everything else is either something we read, or a copy we write out. Git provides the versioning, the history and the review — so there's no second knowledge database to keep in step.

Two things live in Orbit rather than in docs/, on purpose:

What this simplification removes. An earlier draft kept versioned knowledge inside Orbit and synced copies out to each machine. Git already does versioning, history, diffing and review — so that whole layer is gone, along with the sync protocol, the local cache, and the question of what happens when two machines edit the same page. Pull requests answer it instead.

Graph 7

Who is responsible for what

The design works because each player has a narrow job and an explicit list of things it may not do.

Graph 8

When the docs get written

Evidence is captured continuously, but docs/ is only rewritten at moments where the work is settled. Three triggers, in order of how much they matter.

evidence is recorded the moment it happens · docs are rewritten when the work settles

Graph 9

How two agents work the same project without colliding

Three agents can run on one project at once, on different machines. Collisions are prevented by construction rather than resolved afterwards.

The whole trick: agents only ever add, and only one component ever rewrites. Everything else is a copy that can be thrown away and rebuilt.

Graph 10

Onboarding a project

Two commands total. One per machine, one per project — and the repository is never touched.

What that actually installs, and where:

Why the split: half these projects are client work, where writing anything into the repo is unacceptable — so those keep a zero footprint and publish elsewhere. Personal projects get the better deal: the knowledge lives with the code, versioned by git and reviewable in a pull request like any other change.

Status

What already runs, what doesn't

The substrate is in daily use and covered by 645 tests. The knowledge layer is entirely unbuilt.

Two rules that shape everything

Constraints

If you're reviewing this

What would help most

Detail

Where the specifics live

This page is deliberately high level. The full architecture — content-class conflict policy, the authority model, the completeness fields, identity resolution, the 7-phase rollout, and the four corrections a prior review forced — sits in the decision register and the plan document.