Wiki Brain Operating Model

The brain is the wiki's pages plus one command, kb. Every session starts with a short card of active projects and pinned pages, kb finds and opens everything else, and facts learned anywhere queue as notes that one weekly session writes into their pages.

What agents actually did

Before this design, the global preset told every session to read the wiki AGENTS.md and the operations hub, and AGENTS.md added SOUL.md, USER.md and HEARTBEAT.md. That is about 80 KB, roughly 20,000 tokens, before any work. Over the 691 Claude sessions from 2026-10-20 to 2026-11-03: Source: Claude transcripts under ~/.claude/projects, counted 2026-11-03

Sessions skipped the boot and used Claude memory, whose index is already in their context and whose write path the harness teaches. Agents use memory that is put in front of them. They do not search for things they do not know exist.

Retrieval was the second gap. Two eval files score it. evals/kb-retrieval-heldout.json holds 37 lookups written after kb was tuned; no page was edited to fit them, and the retrieval doctor gates on it. evals/kb-retrieval.json holds 58 lookups that tuned kb and three pages' aliases, so its score runs high. Measured 2026-11-03, with evals/run-baselines.py for rg and qmd search:

The Mac's load average was about 115 during these runs, so all wall times are high. qmd query, the hybrid mode with reranking, took about two minutes a lookup at that load and was not scored.

Principles

1. Context is the budget. Boot carries what every task needs: the Mac rules, how to use kb, and the card. That is about 2,000 tokens, loaded with no tool call.
2. Names trigger lookups. The card names the active projects and pinned pages, so a task's nouns match something the agent already sees.
3. One command answers. kb <words> ranks pages by title, alias and slug first, then summary, headings and text. An exact name always wins.
4. Answer first. A page's opening blockquote says what the thing is and what is true now. kb get prints the top 50 lines and an outline, and agents stop there unless they need more.
5. One owner per fact. A fact lives on one page. Other pages link to it.
6. Freshness is measured. updated: is the day someone last checked a page. A page that binds a repo is stale when that repo has newer commits.
7. Writes queue for one writer. Sessions outside the wiki run kb note, and the weekly harvest writes the notes in. Parallel sessions never race on the same page.
8. Markdown is the truth. The kb index, qmd, _index.md and the card are caches that rebuild from the pages.

How a session uses it

1. A session starts in any directory. The global preset loads the Mac rules, the kb instructions and the card. Claude imports config/brain-card.md; Codex reads the same file and runs kb card only when it is missing.
2. The task says "fix the Turboslide export". Turboslide is on the card, so the agent runs kb get turboslide and gets the path, the repo, the live site, the top of the page and an outline with line numbers.
3. A vaguer task gets kb <words>. Each result shows the summary, the type, the last-checked date, whether the page is private, and the section that best matches with its line.
4. The agent fixes the export and learns something durable. It runs kb note turboslide "PPTX export embeds every theme font" --source "Turboslide session, 2026-11-04". The note lands in ~/.local/share/kevin-wiki/inbox/, outside every git checkout.
5. At 06:40 every day the intake rebuilds qmd and the indexes and rewrites the card. Projects with new commits move up; a project leaves the card after 21 quiet days.
6. At 09:00 every Monday the harvest session reads kb inbox and kb stale, shows Kevin one table of changes, writes the approved ones and marks those notes done.
7. npm run status counts both queues. npx tsx scripts/doctor.ts --only retrieval fails when the top-5 hit rate on the held-out set drops under 85%.

Lifecycle

Sessions working inside a Kevin-Wiki worktree skip the queue and edit pages directly. They follow Wiki State Machines for publishing.

Commands

Names resolve by path, slug, title, alias or retired slug from wiki/meta/wiki-redirects.json. Agents may read private pages, and nothing public may quote them. qmd query stays for meaning search when kb finds nothing useful.

Page shape

A page is ready for retrieval when:

• title and aliases hold every name an agent would type: domains, repo names, abbreviations, old names.
• The opening blockquote says what the thing is and what is true now, in one or two sentences.
• updated: is the day someone last checked the page against its sources.
• A project page binds what it describes: repo: for local checkouts and url: for the live site. kb stale and the card read both.
• card: true pins a page every session should know exists. Keep pins under ten.
• Detail follows in sections. History goes in a dated Timeline with sources.

A long page is fine when its top answers. The outline and the best-section hint put the rest one jump away. See Wiki Page Format for every frontmatter field.

Filing and merging

• One canonical page per subject. Filing Decision Tree picks the directory. Folders are navigation; identity lives in slugs, titles, aliases and redirects.
• Merge a thin page into a stronger owner as a section, ledger row or timeline line. Add its title as an alias and its slug to wiki/meta/wiki-redirects.json.
• Generated pages (skill views, registries, indexes) stay generated. Edit their sources. See Generated Surface Contract.
• Nothing is deleted for being small. It is folded, generated or redirected.
• Corpus-wide moves follow private page. Check retired names with kb get <old-slug>.

What each store is for

USER.md, SOUL.md, HEARTBEAT.md and the operations hub left the boot on 2026-11-03. kb finds them like any other page.

Retired on 2026-11-03

Kevin retired the typed graph in brain/ on 2026-11-03: goals, loops, workflows, objects, sources and review queues, about 700 KB. With it went /system, the workflow router, session replay, the source analyzers, the review-receipt pipeline, and the brain-object override in the privacy gate. No agent read the graph to answer a question, brain/loops.json statuses were written by hand, and the privacy override nearly published three private pages on 2026-11-02. The files are in ~/repos/_retired/brain-graph-20261103/. The session index and the memory ledger stayed, and memory records now name wiki pages as owners.

23 project pages bind no repo or site (kb stale --unbound). Most are employers, clubs and finished hackathon entries, which cannot go stale.

---

Timeline

• 2026-11-03 | Retired the typed brain graph, /system, session replay and the review pipeline, on Kevin's call. The page set the privacy gate publishes did not change. Source: Kevin, 2026-11-03
• 2026-11-03 | Rebuilt the model from measured agent behavior. The boot dropped from about 20,000 tokens of pages nobody opened to a 2,000-token preset and card. kb replaced rg and qmd as the first lookup (95% top-5 on 37 held-out queries, against 16% for rg and 65% for qmd search). Writes from other directories now queue through kb note for the weekly harvest, and 51 project pages bind their repos so kb stale measures freshness. Source: Kevin, 2026-11-03; evals/kb-retrieval.json; Claude transcripts, 2026-10-20 to 2026-11-03
• 2026-08-10 | Aligned the compiled-brain model with typed goals, loops, durable objects, workflows, sources, proof and callable graph APIs. private page
• 2026-08-10 | Clarified that compiled wiki knowledge, user and interaction memory, raw sources and session state are separate planes. Source: X/@hwchase17; X/@mem0ai; X/@thedankoe
• 2026-07-15 | Linked the shape model to private page, the one owner for compaction, merges, redirects and retrieval proof. private page
• 2026-07-01 | Added Generated Surface Contract as the source and projection layer for generated pages, registries, qmd, redirects and ledgers. private page
• 2026-06-27 | Established the operating model after the skill-source folder work: flatten meaning, combine weak articles, keep generated inventories generated. private page