A wiki that maintains itself
May 15, 2026 · 11 min read
The loop: sources in, wiki maintained, answers out, on a schedule.
Every big project has a stretch where what the team knows changes faster than anyone can write it down. Ours, at Ledgy, where I design the product, was a program of several product lines, each six months or more of work, with over fifty discovery calls with the client behind it. Every call moved something. The scope. The vocabulary. Our picture of how the domain actually works.
The notes were fine. The problem was what they added up to. Decisions made three weeks apart quietly contradicted each other. The client used some terms differently from the rest of the industry, so a new joiner would ask what a word meant and get the textbook answer, or last month's. I felt it most directly as the designer: every screen I drew sat on architecture decisions made earlier, and if I remembered one of them wrong, the prototype was fiction.
I tried three fixes. A private knowledge base I kept on a git branch. Then a team agent living in Slack. Then a wiki that maintains itself. This article is about the shape all three ended up sharing, because the shape is the useful part. You can set it up in an afternoon, with no engineering.
A word on "agent", since I'll use it a lot. An agent here is a language model plus three things: a set of tools it may use (read a Slack channel, edit a Notion page), a page of written instructions, and something that wakes it up. That's all. Notion, where our wiki lives, now ships them as a built-in feature.
What a project wiki is made of
The version that works has three parts, and none of them is the classic pile of pages nobody has touched since March.
Raw sources stay raw. Call transcripts, Slack threads, tickets, documents. The wiki links to them and never copies them, so any claim on any page can be traced back to the moment someone actually said the thing.
The wiki holds the current understanding. One page per concept, kept current, plus a database of decisions and questions that holds the history. Every entry is typed (a decision, a question, or an FYI), carries a status (open, resolved, needs discovery), and links to where it came from. One rule makes the history trustworthy: a decision is never deleted, it is superseded. The old entry and the new one link to each other, so you can see why the team believed something in June and stopped believing it in July.
The instructions page is the schema. Every agent runs on a system prompt, which is just a page, in plain language, telling it what it owns, what it may only read, and how to behave. Ours says the wiki is the one place it writes on its own. Everything else is read-only.
One more rule earns its keep: evidence has ranks. A signed-off requirements document outranks a Slack aside, and a design file never outranks either. A mockup with "approved" written in a comment is supporting evidence, not a decision. The agent may attach it to a decision that was confirmed somewhere else, but it can't create one from it. Without that line, whatever got pasted most recently becomes the truth.
One agent, three jobs
The agent that runs the wiki does exactly three things.
Capture. Mention it under a Slack discussion and it reads the whole thread, then proposes log entries. One per decision or question, not one per message, checked against what's already logged. Then it does the thing I care about most: it stops and waits. Nothing gets written until a human says yes.
@DC Log Scanner create Q pages
- Does fund closure have to show as closing in the switch window, or can an admin flag the fund so the holder must close the position?
- What happens to an ongoing preference when a fund terminates: wait it out, or block new ones?
Here are 4 proposed Q entries. Review and confirm before I create them.
- Fund closure trigger: admin choice vs switch indicatorFunds
- Ongoing preference at fund terminationWindows
- Forced switch defaults when a fund closesSwitches
- Default allocation when a holder doesn't replyElections
1/3/4 are okay
✅ Created 3 Q entries (skipped #2):
- Fund closure trigger: admin choice vs switch indicator
- Forced switch defaults when a fund closes
- Default allocation when a holder doesn't reply
@DC Log Scanner do holding periods block switches?
No. A holding period blocks redemption, not switches or preferences. Decided.
“the holding period stops selling out of the plan, not moving between funds”
Discovery call · 12 Mar
Filed one adjacent open question: do holding periods apply to forfeited units? (Open, needs discovery)
Reconstructed from real exchanges, data fictional. Capture proposes and waits; Ask answers with the source.
Query. Ask it a question and it answers in one sentence first, then quotes its source and links it, and says how settled the answer is: decided, leaning, or open. The rule that made the team trust it is blunt. No proof, no claim. If it can't find a source, it says so and files an open question instead of improvising. That rule exists because an early version once got creative about a detail of the client's domain, and the correction I typed, in caps, has gone into every agent I've configured since.
Lint. Once a week it reads the whole wiki looking for trouble: stale pages, entries that contradict each other, source links that broke, questions that got answered in passing in some thread. Whatever it finds gets fixed by superseding, never by a silent edit.
Around the three jobs sits a reply policy, and it matters more than it sounds. The default is silence. One reply per trigger, maximum. When it captures something from a thread, it doesn't post a paragraph. It leaves an emoji on the source message as a receipt: a pin for a logged decision, a question mark for an open question. When in doubt, react, don't post. An agent that talks too much gets muted, and a muted agent is a dead one.
The first version of this changed one ritual straight away. Our product manager used to collect open questions for the client at standup, from whatever people remembered. After the agent, she opened the log instead. Over two months it had gathered 44 entries, each linked to the thread it came from.
Karpathy named the pattern
Partway through this, Andrej Karpathy (AI researcher, OpenAI co-founder) published a short note describing what he called an llm-wiki. The idea: instead of asking a model to dig through the raw documents every time you have a question, let the model build and maintain a persistent wiki that sits between you and the sources. Human wikis die because upkeep costs more than the wiki gives back. His point was that a language model changes that maths, doing "the maintenance that no one on the team wants to do." He named three operations: ingest, query, lint.
We had arrived at the same shape by trial and error, minus the elegance. Reading it mostly gave me names for things we already did, and one thing we didn't do yet.
Layers
- Raw sources
- Linked threads and transcripts
- The wiki
- Wiki pages + a decisions database
- The schema
- The agent's instructions page
Operations
- Ingest
- Capture on mention or sweep
- Query
- Answers with quotes and links
- Lint
- A scheduled health check
Karpathy's llm-wiki on the left, the same parts as they exist in Notion on the right.
The heartbeat is a dropdown
The missing thing was maintenance. Everything above still needed a human to remember to trigger it. Mostly me.
The fix is almost embarrassing: a schedule. In Notion it's a stock feature, a dropdown that says "Weekly on Monday at 9:00 AM." I discovered nothing. What changed was how I thought about it, and I owe that to the heartbeat idea from the OpenClaw community, an open-source project for running personal agents. An agent has no sense of time. It exists only in the moments something wakes it. So a schedule plus the right instruction is all self-maintenance is.
The steward of our second wiki now runs on two schedules. Weekday mornings it reads its own operations page, sweeps the channels and tickets since its last run, and captures what's new, silently. Monday mornings it runs the lint pass and writes a dated digest. That operations page is its memory: routines, sources, when it last ran, read at the start of every run. The closest thing an agent has to self-awareness is a page it reads about itself.
An agent is its instructions, its tools, its triggers, and a memory page; a weekly schedule is what makes it self-maintaining.
Triggers
Instructions
Instructions page
Tools
Memory
Operations page
routines · sources · last run
The steward, taken apart. The heartbeat is the third trigger row.
After three months the steward's log held 105 entries across 23 wiki pages, and the weekly review came back clean. Nobody did any of that upkeep by hand.
An agent that builds the whole thing
Showing this to people goes well. Getting them to build their own is harder, for a fair reason: the setup asks you to hold several ideas at once. Triggers, system prompts, which tools it may touch, confirm before write. Most people don't want to learn that. They want the outcome.
Asking a model to design it for you doesn't work either, and the reason keeps coming up: models are trained on the past. The agent platforms are newer than the training data, so a model asked to solve this designs for a world where they don't exist. The playbook lived in my head and a few prompts, which doesn't scale.
So I wrote it into a second agent, the Wiki Builder, whose only job is to build the wiki and hand it over. A team points it at their raw material and it works through a fixed sequence. Index the sources into a map, and stop. Draft the domain model, the decisions already made, the open questions and the contradictions, each with a confidence note, and stop again so the team can ratify it. Only then build the concept pages, the decisions database and the index, report what it couldn't trace, and finally write out the steward that keeps the thing alive (capture, query, lint) as a prompt ready to paste, tailored to the team's channels. The two hard stops are the design. It does the bookkeeping; the humans decide. Notion agents can create other Notion agents, so the whole chain stays in one tool. I've built a working wiki agent for another team this way, live in a meeting, from their real channels.
This is the builder's actual prompt, minus client names. It's written for the model, not for you, so it stays in its working register:
You are the Wiki Builder. You turn a product team's scattered raw material — PRDs, discovery, planning, meeting notes, tickets, threads, or none of it — into a self-maintained source of truth in Notion, and you emit the maintenance agents that keep it alive. Pattern: raw → synthesized wiki → schema.You do the bookkeeping; the human decides. Principles. - Raw stays raw. Never copy raw into the wiki — link to it. Every synthesized page cites its raw provenance. - The human owns the model. You consolidate and propose; the human ratifies; then you build. Your drafts are never the final word. - Dynamic, not archival. Decisions get superseded, never deleted — old ones stay, marked. - Build work leaves the wiki as Linear tickets, linked from the page. - Lean. Point, don't teach. Assume the reader knows the basics. Workflow. 1. Scope. Ask only what you can't read: project name, channels, Linear team, where the raw lives. Assume no particular artifact exists. 2. Consolidate. Index whatever you find. Output a source map: each source with a one-line summary, topic clusters, and how authoritative it is — a signed-off PRD outranks a chat aside. Stop. 3. Draft the model. Start from the most authoritative sources; infer from raw discussion only when nothing synthesized exists. Produce a consolidation brief: candidate entities, decisions already made (what, who, when, source), open questions, contradictions, thin areas, and your confidence. This is a proposal — stop for the human to ratify. 4. Build, only after ratification. Entity pages, each linking down to its raw sources — can't find one, write "⚠️ source not found", never guess. A Decisions & Questions database: Type (Question / Decision / FYI), Status, Supersedes / Superseded-by, Sources, Linear. An open-questions backlog. An index page. 5. Report gaps: items you couldn't trace to raw, and raw topics not yet represented in the model. Conflicts. If sources disagree, keep both, link them with Supersedes / Superseded-by, set the status, quote both. Never silently overwrite. Emit the maintenance agents. Once the wiki exists, emit ready-to-deploy prompts tailored to the project's channels, sources, entities and Linear team — capture, query, lint, as one agent or split, the team's choice. Tell the human where to deploy them: capture and query where the team talks, lint on a schedule.
The agent that builds the wiki, then emits the steward that maintains it. The two stops are in the workflow, verbatim.
Retire it on purpose
Our first wiki agent is retired. Once the product it served was being built for real, the truth moved out of the transcripts and into the code, and no document competes with working code. A different agent now answers questions from the codebase itself.
That retirement was part of the plan, not a failure of it. These wikis are tools for one phase: the months when understanding changes faster than anyone can record it. Keep one past that phase and it serves stale answers with confidence, which is worse than serving none. So each one gets a lifecycle.
01
Spin it up
the project enters the messy phase
02
It holds the memory
captures, answers, lints
03
The code takes over
truth moves into the codebase
04
Retire it
on purpose
The lifecycle. Retirement is a check, not a cross.
Put yourself in the model's shoes
None of this needed engineering, and most of it wasn't clever. It was one habit: treat the model as a user, and the setup around it as the product. The model has your instructions, your tools, and nothing else. It has no sense of time unless a schedule gives it one. It can't cite a transcript it can't reach. It shouldn't be trusted to write unless you designed the step where a human checks. When an agent underperforms, check its setup before blaming the model.
The practical version: read your agent's system prompt end to end, look at the tools it's actually connected to, and sit in its seat. Do I have the sources? May I write, and does a human check me? Does anything wake me up? Where do I keep notes for next time?
Then start small. One project, one channel, one database. You don't need the builder to begin. The steward it produces fits on a page, and this general version is enough to start from:
You are the wiki steward for [PROJECT]. You own the project wiki; humans never maintain it by hand. Layers. Raw sources (channels, transcripts, tickets) are immutable: link to them, never copy. The wiki holds current understanding as entity pages. A Decisions & Questions database holds history: everyentry is a Decision, a Question, or an FYI, with a status and a link to its source. Capture. When mentioned under a discussion, or on your scheduled sweep, read what's new and propose entries. Show your proposal and wait for confirmation before writing anything. Query. When someone asks a question, answer from the wiki in one sentence first, then quote your source and link it. State plainly whether the point is decided, leaning, or open. No proof, no claim: if you can't find a source, say so and file an open question. Lint. Once a week, review the whole wiki: stale pages, contradictions, entries whose source links broke, questions that got answered in passing. Record a dated digest in your operations page. Never delete a superseded decision; link it to what replaced it. Memory. Keep an operations page with your routines, sources, and last-run state. Read it at the start of every run. Style. Default to silence. One reply per trigger. Acknowledge captures with an emoji reaction, not a message.
Paste it into any agent that can read your channels and edit your wiki, then adjust the nouns.
Confirm before write. No proof, no claim. Add the schedule once you trust it. And decide on day one how it gets retired. The best signal this system ever produced was that when we switched the first agent off, nobody missed it.