A portable pattern for a product knowledge hub that maintains itself. It builds on Karpathy's LLM wiki and adds a second layer on top.
A Project Brain is a knowledge hub for a software product, written for an agent to read. It's a set of linked markdown files the agent opens at the start of every session and updates as work happens. The point is that knowledge compounds across sessions instead of disappearing into chat history or getting re-derived every time you ask a question.
A plain wiki is good at one kind of knowledge: one page per feature, bug, or note, holding the current state of one thing. But a product also produces another kind: decisions, milestones, risks, architecture. These span many features and they're anchored in time. The Project Brain holds both, with a hard line between them.
Four parts under a single docs/
root:
raw/
— the source inputs, kept immutable. Pasted feedback, bug reports, vision notes, transcripts. Once written they're never edited. Everything else is derived from them.wiki/
— the reactive layer. One page per feature, bug, or paste. The current state of one thing, overwritten as it changes.brain/
— the directive layer. Cross-cutting, time-anchored, append-only. Architecture, milestones, decisions, risks, open questions.SCHEMA.md
— the operating guide. Page formats, status values, workflows, lint rules. The agent reads it first, every session.
The split is by lifecycle, and it's the whole idea.
The reactive layer (wiki/
) answers "what is the state of X right now?" One source of truth per page, overwritten as things change.
The directive layer (brain/
) answers "what spans X and Y, and when?" Decisions are append-only, milestones are time-anchored, risks persist.
The one rule that holds it together: never keep the same source of truth in both layers. A feature's readiness is feature state, so it lives in the wiki. A milestone is a view over many features' readiness, so it lives in the brain and never stores its own copy. An architectural decision is a brain page, never buried inside a feature page.
Links. Cross-reference every page with[[wikilinks]]
, never relative paths. This is what turns the brain into a graph instead of a folder of files.Frontmatter. Every page carries YAML, at minimumtype
,status
,last_updated
. Directive pages add time fields (created
,target_date
,last_refreshed
) and lineage (supersedes
/superseded_by
).Status values. Each page type has a fixed set of allowed statuses. Don't invent new ones. When the status vocabulary drifts, the meaning drifts with it.
Reactive (wiki/
): feature— what it should do, where the build is, key source files, linked feedback, open questions.** bug**— summary, severity, status, repro steps, affected features.** feedback**— one raw paste, synthesized: key points, affected features, sentiment, implications.** vision**— a captured product direction: the idea, the motivation, the trade-offs.** implementation**— approach, effort, and risks for a non-trivial piece of work.
Directive (brain/
): architecture— one living technical map of the running system. It links to features, it doesn't restate them.** milestone**— a time-anchored goal. Its scope is a view over feature readiness, not a second checklist.** decision**— one append-only record per cross-cutting call: context, the decision in one line, rationale, alternatives, consequences. Never edited once accepted. Supersede it instead.risk— a register of live risks: severity, impact, mitigation, trigger signals.** open-question**— cross-cutting unknowns that aren't ready to become a decision yet.
A knowledge hub dies the moment nothing forces it to stay current. So every page type has a trigger: a user action that both produces the page and reconciles everything it touches.
| Trigger | Produces |
|---|---|
| paste feedback | a feedback page + updated feature links |
| report a bug | a bug page + affected feature updates |
| paste a vision idea | a vision page |
| a cross-cutting decision comes up | a decision page |
| a risk comes up | a risk entry |
| declare or update a milestone | a milestone view |
| ask a question | an answer, optionally filed as a page |
| ask for an audit | reconcile one page against the actual code |
| implement a spec change | refresh the affected feature pages + milestone readiness |
| archive a spec change | reconcile the brain against what shipped (below) |
The pages with no natural "user pastes X" moment are risks, open questions, and architecture. Those are the ones that rot. Give them their own refresh triggers or they turn into dead templates.
The brain fits naturally with a spec-driven workflow like OpenSpec, where each unit of work is a self-contained change (proposal, design, spec deltas, tasks) that lives in its own folder while active and gets archived once it ships. The change is the unit the brain reconciles against, and its lifecycle is what drives the directive triggers.
While you implement a change, you update the feature pages it touches: source-file lists, current status, and the milestone-readiness frontmatter the milestone views are built from. When you archive a change, you run a reconciliation pass: audit each affected feature page against what actually shipped, flip milestone readiness, and promote any decision that has become load-bearing.
The decision boundary is the part that matters. A decision scoped to one change stays in that change's design doc. A decision that spans several changes, or outlives any one of them, gets promoted into brain/decisions/
. A change workflow generates decisions constantly. This boundary sends the durable ones into the brain and lets the throwaway ones stay local.
Ingest— save the raw input toraw/
, turn it into the right page type, update every page it affects, append to the log. One paste can touch many pages.Query— read the index, read the relevant pages, answer with[[wikilink]]
citations. File a reusable answer as a new page.Audit— compare a page against reality (the code, the running system) and correct the drift. The brain is only worth as much as its agreement with the truth.Refresh— re-derive a directive page (architecture, a milestone view, a vision) from current sources.** Lint**— health-check the hub: orphan pages, stale statuses, contradictions, pages older than the code they describe, statuses outside the allowed set.
index.md
— the master catalog, one line per page ([[Page]] — one-line description
), grouped by type. The agent reads this first to know what exists. Keep it short. It's a map, not content.log.md
— append-only, one entry per operation:## [YYYY-MM-DD] operation | title
. The reactive and directive layers each keep their own. The log is how the brain remembers what it's done.
At the start of every session the agent orients directive first, reactive second:
- Read
SCHEMA.md
. - Read the recent
brain/log.md
entries to see what changed lately. - Read the active milestone page, then the open high and critical risks linked to it.
- Read the recent
wiki/log.md
entries. - Read
index.md
.
Then it waits for instruction. This order means the agent always knows the deadlines and the decisions before it touches any feature detail.
Step 1 is the one everything else depends on, and it's the one an agent is most likely to skip. The whole pattern runs on the trigger contract being read and honored, and that contract lives in SCHEMA.md
. If the agent never loads it, the brain quietly stops being maintained while still looking fine. So don't leave step 1 to good intentions. The next section is about making it happen on its own.
Before anything automated: the brain runs on the trigger contract, full stop. If the contract is in context and the agent honors it, the pattern works with zero tooling, by hand, in any agent that can read and write files. Everything below is reinforcement, not a requirement.
That matters because the useful automations are harness-specific. Hooks and subagents exist in some setups (Claude Code, for one) and not in others. Don't assume the agent you paste this into can build them, and don't treat the pattern as broken if it can't. Wire up whatever your harness supports, and where it supports nothing, fall back to reading the contract at the top of each session by hand. The forcing function is the contract, not the plumbing.
Where the plumbing exists, two automations carry most of the weight:
Inject the contract, not just the state. The most-skipped step is reading SCHEMA.md
, and it's also the most important, so make it happen automatically. A session-start hook should parse the brain and drop a summary into the agent's context on its own. The instinct is to inject only the directive state (active milestones, open high and critical risks), but that leaves the rules to chance. Inject both. Lead with the behavioral contract, then the state.
To keep this cheap, split SCHEMA.md
rather than injecting all of it:
Always inject(small, the part that must never be skipped): the trigger table, the status values, and the directive-first read order.*Inject when useful:*the current directive state, so the agent knows the deadlines and risks before it touches feature detail.*Leave on disk, read on demand:*the verbose page templates and formatting rules. The agent only needs those when it's actually writing a page, and it can openSCHEMA.md
at that moment.
The contract is maybe twenty lines. Injecting it every session costs almost nothing and removes the single highest-consequence failure mode in the whole system.
An archive reconciler does the archive trigger for you. Fired from the change-archive flow as a subagent, it audits the affected feature pages, flips milestone readiness, and drafts decision promotions for you to approve.
Both of them only surface and propose. Neither blocks. No git hook or CI gate fails because a docs update is missing, and that's deliberate. The moment you gate on docs freshness, people learn to route around it. Surfacing drift and letting the human act on it is what keeps the brain trusted.
- Knowledge compounds. Every session leaves the brain richer than it found it, instead of rebuilding context from scratch.
- The boundary stops the rot. Reactive state stays overwritable, directive decisions stay append-only, and neither corrupts the other.
- Triggers beat discipline. The hub stays current because each action produces its own page, not because someone remembered to write docs.
- The change is the unit. Tying reconciliation to the spec-change lifecycle means the brain updates exactly when the product does, and the decision boundary catches the durable knowledge while it's still fresh.
- The contract travels with the agent. Injecting the rules, not just the state, means the most-skipped step happens on its own, and the pattern degrades gracefully when the tooling to do that isn't there.
- Clear division of labor. The human curates the sources, makes the calls, and asks the questions. The agent does the rest: writing, linking, reconciling, linting.
This is deliberately product-agnostic. Drop it into any software project and you adapt four things: the feature set the wiki tracks, the status values that fit your lifecycle, the directive triggers (decisions, risks, milestones) your team actually generates, and the change workflow you wire the implement and archive reconciliation to. Keep the two-layer split, the wikilink graph, and the advisory posture. Those are the parts doing the work.