TL;DR
A Markdown wiki maintained by an agent beats RAG for one person’s work knowledge. It still rots, because agents append by default and the same fact ends up in three versions. The fix is to classify every fact as a state (replace it in place, with a date) or an event (append only), and to enforce that with a hook and an audit, not with a polite instruction.
For two months I have kept a knowledge base about my work that I almost never write myself. Claude Code reads my mail, meeting transcripts, calendar and shared documents every morning, then updates a folder of Markdown pages: one page per client, project, idea and person, plus a task list and a one-page dashboard. I read it in Obsidian and ask it questions.
The pattern comes from Andrej Karpathy’s “LLM Wiki” idea file. The person supplies sources and questions. The model does the bookkeeping: summaries, cross-links, updates, consistency. Knowledge is compiled once and then maintained, instead of being rediscovered from raw documents on every question.
This post covers the decision I got right early, the failure I did not see coming, and the rule that fixed it.
Three layers and an index instead of a vector store#
The setup has three layers:
- Sources. Raw material the agent may read but never edit.
- The wiki. Every other Markdown file. Only the agent writes here.
- The schema. One
CLAUDE.mdfile that tells the agent how to maintain the wiki: naming, dates, source attribution, where tasks live, what to do on each operation.
There are four operations: ingest a new source, answer a question, run a health check, and take a note from conversation. Each ends with an update to INDEX.md, a line in an append-only log.md, and a git commit.
INDEX.md is the part that surprised me. It is a catalogue with one line per page, and the agent reads it first on every question. At this scale it replaces retrieval entirely.
Why I did not use RAG#
The question “do I need RAG here?” is a question about the data, not about the technology. Two things decide it: how much structure the data already carries, and how much of it there is.
RAG earns its keep on large amounts of unstructured prose, where you need to match by meaning across thousands of documents. It does badly in two places that matter for work knowledge. It cannot zoom out to a whole document or a set of documents, and it has no notion of analysis. The questions I actually ask are of the form “how does this proposal connect to what the client said in that meeting”. Those need relationships, and in a wiki the relationships are stored as links instead of being reconstructed from vector similarity.
The practical gain is that there is no index to keep in sync. No re-ingestion, no stale chunks, no two versions of one document living side by side. Answers cite a specific page and the source behind it.
There is a hard line, though. Markdown stops being enough when other people log in: several users at once, access control, live data, retrieval at scale. A wiki per person stays on the safe side of that line. A shared company knowledge base with permissions is a different architecture, not the same thing on a shared drive, and I keep the two goals apart.
How it rotted#
After less than three weeks I ran an audit script over the wiki, taken from Cole Medin’s open-source second-brain-audit skill. The first finding was in the worst possible place. A memory file loaded at the start of every session listed a team demo as an upcoming step, with the wrong date. The session had already happened, and the wiki page about it said so. For two weeks every conversation started from a plan that was no longer true.
The root cause is structural. An agent maintaining notes defaults to appending. When something changes, it adds a new line and leaves the old one in place. After a few weeks the same fact exists in several versions across several files, and the agent has no way to tell which one is current. Cole Medin later explained the same failure in a video called “Your second brain is rotting”, with a client rate that appeared as three different amounts in three files.
The most dangerous version is a conflict between the files loaded at session start and a page read later. A stale fact in an archive page does little harm. The same fact in the startup surface corrupts every future answer, because the agent sees it first.
The rule: every fact is a state or an event#
The fix, which I took from the same skill and wrote into my schema as a numbered rule, is one classification with two opposite write rules.
- A state is a single current value that changes: status, owner, deadline, price, version, file path, who is leading what. Replace it in place and date it. Never add a second line about the same thing, because that creates two answers to one question.
- An event is something that happened and stays true: a meeting, a decision, a sent proposal, a lesson learned. Append it and never edit it.
- When in doubt, record it as an event and say so. A missed state update can be recovered later. Rewritten history cannot.
A plan or a list of next steps is a state. When a step is done, it moves to history. It does not stay listed as a future step.
In practice, a client page has a short “current state” block at the top, rewritten with a date whenever something changes, and a log section below that only grows. The same split applies to the memory files.
A rule the agent follows only sometimes is not a rule#
Writing the rule into the schema is not enough on its own. Cole Medin reports trying exactly that: an instruction to date every fact, with nothing to enforce it, was followed in about 8 percent of cases in his test. The agent needs a process it is forced through, not a principle.
So the rule has two mechanical guards.
- A hook. A
PostToolUsehook in Claude Code runs after every write to a wiki page or memory file. If an entry in a state section has no date, the agent gets a warning straight away and fixes the file. The hook warns but does not block. The write goes through, and a broken hook fails open so it can never stop work. - An audit. The
/lintcommand runs a health check: contradictions, facts that are no longer true, orphan pages, missing cross-links, and drift between the index and the disk. It starts with the startup surface (the schema, the dashboard and the memory files) because that is where a stale fact does the most damage. Fixes are applied only after I approve them.
The audit script from Cole Medin’s skill now lives inside my own /lint, so there is one health check instead of two overlapping ones.
The hook has one blind spot. It sees writes made through the editing tools, not text appended from a shell command. It supports attention; it does not replace it.
Smaller lessons from the same two months#
- Context costs more than tool calls. What eats the usage limit is raw data pulled into the main conversation, such as one uncondensed meeting transcript. Heavy sources go to a subagent per unit of work, and only the distilled result comes back.
- Keep sources where they live. Meeting transcripts stay in the collaboration platform that recorded them, which also keeps the data inside the organization’s own tenant. The wiki stores a note with a link, never a copy of the transcript.
- Put repeated extraction into code. Condensing a transcript is a script, not a prompt. It is deterministic, cheaper and testable.
- Keep the mechanics generic and the specifics in one place. The skills describe how to do things. Names, paths and connectors live only in the schema, so someone else can copy the skills and replace a single section.
What I would tell someone starting one#
Start with the schema and the index, not with tooling. Decide on day one which facts are states and which are events, because retrofitting that distinction means an audit of everything you already have. Put the enforcement in a hook, not in the prompt. And keep one person per wiki until you truly need shared access, because that is the point where you are building a different system.