Step 9 — Memory and the Wiki
Step 9 · Memory
An assistant with no memory is a stranger every morning. An assistant with bad memory is worse: confidently wrong about your own household, forever.
The design decision I would keep above all others: everything it remembers is a plain markdown file. Not a database, not an opaque store. Text I can open, read, edit, search and back up with anything.
Why plain files
Section titled “Why plain files”Four reasons, and they compound.
- You can read them. If you are not sure what the agent believes about your household, you open a file and look. No query, no interface.
- You can correct them by hand. When something is wrong, you fix the line.
- They survive the agent. Replace the platform, and your household’s knowledge is still a folder of files.
- They diff. You can see exactly what changed this week, which is how you catch drift early.
If your agent’s memory is a database you cannot read, you have outsourced your household’s knowledge to something you cannot inspect. That is a decision worth making deliberately rather than by default.
Two layers
Section titled “Two layers”| Layer | What it is | Size | Who writes it |
|---|---|---|---|
| Working memory | One small file loaded into every conversation | Small, with a hard limit | The agent, and me |
| The wiki | A folder of markdown pages, one per subject | Grows over time | The agent, on a nightly job |
Working memory is deliberately tiny. It has a character budget, and when it fills up I have to retire something to add something. That constraint is a feature — it forces the file to stay high-signal. Mine holds the standing rules, the household’s stable preferences, and the things that must apply to every single conversation.
The wiki is where detail lives. Recipes, trips, people, suppliers, procedures. It is not loaded into every conversation; the agent reads the index, then opens the pages it needs.
Do this
Section titled “Do this”- Create a single memory file the agent loads before every reply. Keep it small and curated.
- Create a wiki folder of markdown pages, one per subject.
- Write a schema file — the rules for the wiki, so it does not turn to sludge. Mine covers frontmatter, cross-links, and when to split a page.
- Write an index file — a catalogue listing every page with a one-line summary. The agent reads this first.
- Write a log file — append-only, one line per action with a date. This is the household’s history, and it is the file I read most.
- Schedule a nightly job that reviews the day and updates the wiki. Mine runs at 22:00.
- Read it back periodically. See below.
The conventions that keep a wiki usable
Section titled “The conventions that keep a wiki usable”Left alone, a wiki becomes an unsearchable pile. These rules, borrowed and adapted, keep mine usable at nearly fifty pages:
| Rule | Why |
|---|---|
| Lowercase, hyphenated filenames | Any tool can link to them |
| Frontmatter on every page | Date, source, status — machine-readable |
| Every page links to at least two others | Orphan pages become invisible |
| An index entry for every page | The index is how anything is found |
| A log line for every change | The history is the point |
| Split a page past about 200 lines | Long pages stop being read |
| Prefer tables to prose | Scannable beats literary |
The rule that matters most
Section titled “The rule that matters most”Memory records what the household said. It does not record what the agent concluded.
This looks academic. It is the most important thing on this page.
When someone tells the agent something — “I do not eat shellfish” — that is a fact, and it belongs in memory.
When the agent notices something — “they skipped breakfast on Tuesday, so perhaps they do not eat breakfast” — that is an inference. Written into memory, it becomes indistinguishable from an instruction. And because memory is read before every conversation, an inferred fact becomes a rule nobody ever set.
A stored fact gets repeated back to the household for years. Storing an inference is how you teach an assistant something you never meant to teach it.
What must never go in
Section titled “What must never go in”- Credentials, keys or tokens. Never in memory, never in a note, never in a message log.
- Inferences presented as facts.
- Transient state — a mood, a one-off frustration, a temporary change of plan.
- Anything it should look up instead. Memory is for what does not change and cannot be derived.
The review loop
Section titled “The review loop”Unmanaged memory degrades. It bloats, contradicts itself, and the useful part gets harder to find.
So the same nightly job does three things: it consolidates the day’s detail into durable summaries, it retires anything contradicted by something newer rather than deleting it, and it surfaces what the agent believes so I can correct it.
That last one is the part people skip. Someone should be able to read back what the agent thinks it knows. If that list is never read, a wrong belief can live for years.
Checkpoint
Section titled “Checkpoint”- You can open the memory file and read what the agent believes
- There is an index, and every page is in it
- There is a log, and it has an entry per change
- The nightly job runs and you have seen it change something
- You have read back its beliefs at least once and corrected something
Step 10 — Backups, because none of this survives a dead machine without them.