How I built a wiki that agents maintain

Sometime in 2025 I made a page called MY OWN LEXICON. It was a glossary, a list of terms I had been using to describe how my own behaviour works, each with the definition I meant rather than the dictionary one. Looking at it I could see that the list would keep growing, that the entries referred to each other, and that what I actually wanted was not a longer glossary but a set of pages that pointed at one another and accumulated over time.

Motivation

The obvious way to publish thinking is a blog, and I did not want one. A blog post is finished when you post it, which means the pressure is on before you write anything, and the format gives you no way to say that an idea is still moving. A wiki inverts all of that. Its format assumes that everything in it is a constant work in progress, its articles stand alone so a reader can take them one at a time, and the links between them carry a relationship that a chronological feed cannot express. So I went to build a wiki, and I got stuck immediately.

The empty vault problem

The blank page problem I had was not the usual one. I was not short of things to say. I had been dumping every idea I had into chat transcripts for as long as I had been using these tools, so all the material existed, and it existed in a form nobody could read: scattered across hundreds of conversations, in the middle of exchanges about something else. What stopped me was that writing the wiki meant saying all of it again. I had already done the work of thinking it and I had no appetite for the work of transcribing it.

That is a specific problem and it has a specific shape. The material is written down but it is not addressable, and the cost of making it addressable is a second full pass by the person who least wants to do it.

Adjacent work: Obsidian

I asked Claude what tool to use, given that I wanted an AI to manage the wiki, and it suggested Obsidian. I turned that down at first, and my reason was not a good one. Obsidian felt like going backwards, an older and less interesting tool than whatever I thought I should be using, so I rejected it on status rather than on function.

What changed was noticing what an Obsidian vault actually is. It is a folder of markdown files. Everything that makes it a wiki is a convention layered on plain text: a link is a page name in double brackets, and the graph is what you get when you read all the files and follow those brackets. Nothing about it requires Obsidian to be running. Which means anything that can read and write files can maintain the wiki, and I already knew how to point Claude Code at a folder.

Three things came free from that description. The graph edges already exist, because wiki links are edges. The graph is queryable, because libraries exist that walk an Obsidian vault. And the entire maintenance problem becomes a file-editing problem, which is the one thing coding agents are unambiguously good at.

The tool did not change between my rejecting it and my adopting it. The description did.

Seeding the first articles

I wrote a system prompt describing what the wiki was for and how its articles should read, and then I fed the agent a couple of seminal articles and brain dumps I already had. It started producing pages, and the pages were right, and the reason they were right is worth being precise about.

The first articles became the models for every article after them. Not because I told the agent to imitate them, but because every new article gets written with the related existing articles pulled into context, so whatever register those early pages set keeps being resampled by everything downstream. Style, tone, and philosophical alignment all propagated from those first few pages. Steering them was the highest-leverage editing I did on the whole project, and the window for it closed while the vault still held a handful of articles.

Which is worth pulling apart, because the reason it works says something about what you are talking to.

Suppose I want a particular register and I try to describe it. Precise, unhurried, sceptical of its own claims. Every one of those words covers an enormous range of actual writing, and the model has to pick somewhere in that range before it can write a sentence. It will pick the most typical version, because typical is what it has most of, and the most typical version of "precise and sceptical" is the same voice everything else has.

Now suppose I hand it three articles instead. A language model works by continuing text, so a sample is not a description of the target, it is a point already standing on it. There is no conversion step and nothing to interpret, because continuing in the manner of what precedes is the one operation the machine is built out of.

So a style guide asks the model to construct a target from words and then aim at it. An exemplar skips the construction and hands it the target. That is why the first few articles were worth more attention than any hundred that came after: I was not writing articles, I was writing the specification, and it happened to be shaped like articles.

By the time I made the first commit on 18 November 2025, the vault held 78 articles and 26,145 lines, and three agent definitions sitting beside them:

.claude/agents/wiki-article-writer.md   239 lines
.claude/agents/wiki-context-finder.md    62 lines
.claude/agents/wiki-reviewer.md         221 lines

The pipeline had been running for less than two days. Note the sizes, because they are the division of labour: the finder needs sixty lines to say what to go and read, and the writer and the reviewer need about four times that each, because both of them are being told what good looks like.

Agent roles

I started with a single agent that wrote articles, and it worked until it did not. The failure was context drift: as a session ran long, the instructions I had given at the start stopped governing what came out at the end, and I found myself re-explaining the same constraints every few articles. Re-instructing an agent that has forgotten is more effort than the writing it saves.

So I divided the work into roles, and each of the three exists for a different and specific reason.

The writer came first, because writing the articles was the job.

The context finder came second, because I noticed the writer needed to read before it could write. Its stated purpose is not convenience but graph quality: it surfaces the pages that relate to a new concept so that connections get made, which improves the edge density of the graph and keeps the connectivity worth having. A wiki whose articles do not link is a folder.

The reviewer came third, and it came from the most useful observation of the three. I kept having to remind the writer what the wiki was for, and I could not make those reminders stick by putting them into the writer's own prompt. An instruction that has to survive a long generation does not survive it. Moving it into a separate pass, run after the writing, made it hold.

The reviewer's job is narrower than quality control. Its own definition puts certainty calibration at the top, in capitals, above everything else it checks, and pairs the failures with their replacements rather than only banning things. This is the load-bearing section of the file, trimmed of its surrounding instructions:

### 1. Certainty Calibration (HIGHEST PRIORITY)

**RED FLAGS - Flag immediately:**
- "The brain literally implements X"
- "Research proves/shows that..."
- "This is not metaphor, this is actual mechanism"
- Deterministic predictions ("this will cause Y")
- Universal statements ("everyone experiences X")

**GOOD PATTERNS - Encourage:**
- "Appears to use X-like processes"
- "Observed in N=1 experience that..."
- Probabilistic language ("tends to", "often", "in this case")
- Explicit caveats ("This worked for Will, test it yourself")

**ACTION:** For every claim, ask: "Is this presented as useful heuristic or
scientific truth?"

Every red flag has a good pattern beside it, which is the part that makes it work: an agent told only what to avoid will avoid it by saying nothing. The wiki explains behaviour in computational language, which is a lens and not a discovery, and one agent's entire job is stopping the other agents from forgetting that.

Note that the order in which I built the three is not the order in which they run. I built writer, then context finder, then reviewer. They execute context finder, then writer, then reviewer.

What it produced

Four days after the first commit the wiki had a web reader with retrieval search over it, and the part that mattered to me was smaller and stranger than that. I could dump a chat transcript into the vault and the articles would update themselves, absorbing what was new and reconciling it with what was already written, rather than appending to the end. The transcription problem that had stopped me at the beginning had been handed to the thing that generated the transcripts.

Separation against a single pass

Everything above has a mechanism behind it. This part does not, and I would rather say so than invent one.

The three agents contain the same instructions I would put in a single prompt. Nothing is added by splitting them. I have tried the single prompt, asking for research and writing and review in one pass, and the output is worse, reliably enough that I stopped testing it.

I can see two things a real explanation would have to choose between, and I cannot tell which is true. It might be about attention: a long prompt carrying three jobs means every instruction competes with every other one, and the review instructions lose because they are about text that does not exist yet at the moment the prompt is read. Or it might be about the input: a reviewer run separately is reading a finished draft, which is a different and much more specific thing to be looking at than an intention to write one. The first says splitting helps because prompts get crowded. The second says it helps because a critic needs an object, and until the draft exists there is nothing to criticise.

Those predict different fixes. If it is crowding, a longer context window eventually dissolves the problem. If it is the object, no context window ever will, and the separation is permanent. I do not know which, and the honest position is that I kept the three agents because the three agents work.