A wiki your agent maintains

I keep notes on most of the product decisions I have argued for. Not out of tidiness. Someone asks the same question nine months later, usually a new PM, sometimes me, and the useful answer is almost always "we tried a version of that, here is what happened." Years of that writing had piled up, so I put it behind a retrieval setup and pointed my coding agent at it. It worked in the demo sense. Ask a question, get a paragraph back, the paragraph is roughly right.

Then it stopped being roughly right.

The failure was not the model and it was not the embeddings. It was the shape of the thing. Retrieval is a lookup. You ask, it ranks chunks, it writes an answer, and then the answer evaporates. Next week the same question costs the same work. The index gets larger without getting better. Nothing I learned on Tuesday made Thursday cheaper.

Corrections were worse. A pile of documents has no opinion about which document is current. When I restate a number, or when a hypothesis turns into a result, the old version is still sitting there with perfectly good similarity to the query. So the correction does not replace anything. It joins the pile as a second opinion, and the agent hands me a blend of what I used to think and what I think now. That blend is a third answer nobody ever wrote.

The idea I took from Karpathy's LLM Wiki pattern is small. Stop storing what the model read. Store what it concluded, on a page, with links to other pages. A page has an identity that survives being rewritten. A chunk does not. Once knowledge has an address, you can do the two things a pile cannot: replace it, and restrict it.

Supersession

A page can declare that it replaces an earlier page. The earlier page stays on disk, marked as superseded, with a pointer forward. Retrieval follows the pointer and returns the current page.

That sounds procedural. In product work it is the whole game, because most of what I know is wrong first and corrected later. The activation number I quote in one quarter is not the number I quote in the next. A pricing assumption survives two experiments and dies in the third. Trial stickiness settled at 19% only after several readings that were not 19%. If every one of those readings ranks equally forever, my knowledge base is a record of my confusion.

Keeping the old page matters as much as retiring it. I want to be able to see that in March I believed something else, and what changed my mind. That is the part nobody writes down, and it is the part that makes the next decision faster. A superseded page costs a few kilobytes and answers the question "why did we stop doing it that way", which otherwise gets answered by whoever has been here longest.

Privacy tiers

Not everything worth writing down is mine to leave lying around. Enterprise escalations come with customer names attached. Pricing work is unreleased until it is not. Some notes are about people, and some are about my own read on a team.

So every page carries a tier, and the tier decides where the page can travel. Public reasoning can go anywhere, including into a piece like this one. Company detail stays in the project vault and never leaves it. Personal notes stay personal.

Without that, one specific bad habit forms. You start writing the vague version. You leave out the customer, the number, the actual reason a deal stalled, because you are not sure where the page will end up. The self-censoring happens at write time, which is exactly the moment where the detail is still in your head and free to record. Tiers cost me a field in the frontmatter and buy me the ability to write the specific thing.

Search over the top of it is keyword and embedding together. Keyword because half my queries are exact strings, a product name, an error message, a metric label. Embeddings because the other half are me not remembering what I titled the page.

The pages are plain markdown on disk, which is a decision I keep being glad about. It means my agents and I write through the same door. It also means the exit is free: delete every tool involved and the notes still open in any editor. The reason I built wiki-viewer alongside it was less noble. I wanted to read and fix pages from a phone, and from machines that are not this one, so it serves local files over a web UI with an HTTP API that agents can post to.

I have no results to report. There is no adoption number, no measured lift in anything, and one user. What I can say is where the cost lands. The tooling handles the bookkeeping, the index, the backlinks, the log. It does not do the thinking, and it cannot decide that a page is now wrong. That call is mine, every time, and the days I skip it are the days the thing starts drifting back toward being a pile.

The test I use is narrow. After I finish answering a question, is there a page that means I will not have to answer it again. Most weeks, for most questions, no. I am slowly getting better at it.