My agents forget everything, so I gave them a wiki

Every agent session starts blank. It doesn’t know what we decided last week, which server is live, or that I already rejected the idea it’s about to propose. I can’t carry all that in my head either, and I can’t read the code to rebuild it. So the memory has to live somewhere outside the agent.

Mine lives in a folder of Markdown files. I call it the wiki. It’s plain files. Any agent that can read a file can use it.

The pattern

I took the layout from Andrej Karpathy’s LLM-wiki gist. The idea is that knowledge gets compiled once and kept current, instead of being worked out again from raw notes on every question. I curate and ask. The agent does the writing, linking and bookkeeping. One file in the folder, a manual called SCHEMA, is the whole instruction set. Every agent reads it before touching anything else.

The layers, from the bottom up:

• Raw captures. Session reports, exports, transcripts. Added once, never edited.
• Source summaries. One page per raw capture that has been processed: what happened, what was decided, what’s open.
• Entity, concept and project pages. The compiled truth. A project page says how things are now. A concept page holds a lesson that showed up in at least two sources.
• An index and a log. The index is one line per page and gets read first. The log is append-only, one dated entry per change.

Figure: the path a fact takes before the next session can find it.

As of 6 November the folder holds 468 raw captures, 399 source summaries, 66 concept pages, 103 entity pages, 16 project pages and 6 synthesis pages. The log has about 410 dated entries since 15 September. The raw and source counts are the bulk. The compiled pages are the part agents actually read.

The rule that makes it work

Agents file durable facts before a session ends. I don’t ask each time. It’s written in my global instructions, so every session carries it. A durable fact is a decision, an incident, a lesson, a result. The agent saves the original, writes the summary, updates every compiled page it touches (usually between three and ten), rebuilds the index and adds a log line.

Absolute dates only. A page that says “yesterday” is useless a week later.

When a new fact contradicts an old one, the page states the new one and the timeline keeps the old one with its date. The top of a page is the present. History sinks.

STATE.md, written before the work

Each project also has a file at its root called STATE.md. The rule is write-ahead: before starting a task, the agent marks it in_progress. When it finishes, done, with one line saying what’s next. If a session dies halfway, the file still says where it stopped.

When an agent resumes a project, or comes back after any gap, it reads STATE.md first and checks it against the real files and servers. Then it carries on without waiting for me to say “go”.

Small memory files for me

The wiki holds the work. A separate set of small files holds how I like things done. My main working folder alone has 26 of them. Each is a few lines: a preference, a correction, a rule. One says to give full file paths because shortened ones broke twice. One says every review brief must ask for a severity from 1 to 10, and anything under 5 gets logged instead of fixed.

The wiki has a matching rule for corrections. When I fix an agent’s reading of a scope, a fact or a wording, my correction is the current truth. The agent’s guess stays in the history, labelled as wrong. Wording and visuals that other people will see are mine to decide: the agent proposes, it doesn’t ship.

What it fixed

A new session no longer starts by asking me what we’re doing. It reads the index, opens the project page and knows the state, the open items and the decisions with their reasons. I stopped re-explaining. Agents also stopped re-proposing things I’d already turned down, because the rejection is on a page with a date.

Where it broke

State files drift. Agents write them in the middle of work, so they can go stale in either direction. It has happened twice. One is fixed. One is still open.

In another project the state file ran ahead of the wiki. It recorded work that had no source page yet. The wiki marks that work as unverified rather than copying the numbers in, and that gap is still open.

Both were caught the same way: an agent didn’t take the notes on trust and checked them against the real files. That check is the rule.

Rule: notes are leads, not facts.

- Every number, status or claim you write in a notes or state file gets a date next to it (2026-11-06, never "today").
- When two notes disagree, the one with the later date wins.
- When you start or resume work, read the notes first, then check them against what is really there: the files, the live site, the server, the account. The real thing beats any note.
- If a note is wrong, fix the note and say what you fixed.
- Never tell me something is "still broken" or "still open" from a note alone. Check first, or say it's unchecked.