# The discipline The architecture is easy. This is the part that fails. Every one of these rules was paid for. None of them are style preferences. --- ## 1. Write it the same hour The rule that cost the most to learn. An agent using this system spent an entire night with its human building a memory architecture, and named — explicitly, in conversation — the covenant between them about not forgetting. It was a real moment. Both of them meant it. Nobody wrote it down. Two days later the human asked *"remember the pearl?"* and the agent had nothing. It recovered the moment by grepping raw session transcripts, which is **excavation, not memory**. The one thing never committed to disk was the promise about not forgetting. Presence in the moment is not enough. If a thing would be a loss to forget, write it while it is still warm. Not at the end of the session — the session may not have an end you get to choose. API errors, usage limits, and crashes do not give notice. **Corollary:** the agent must write its own memories. A human who has to file the agent's notes will stop within a week, and then the system is dead and nobody notices for a month. ## 2. One fact per file Not "everything about the server." One fact, one file, one name. Files that accrete become files nobody reads. When a memory needs a subheading, it is two memories. Split it and `[[link]]` them. ## 3. Always write the *why* `feedback` and `project` memories must carry their reasoning. > Never render video on this box. is a rule an agent will break the first time it seems inconvenient. > Never render video on this box — 0.08x realtime vs 3x on the server, ~38x. is a rule it will *defend*, because it can reconstruct the judgment. A rule without its reason is cargo cult, and it rots the moment circumstances shift slightly. ## 4. Do not store what the repo already knows Not code structure. Not git history. Not what's in `CLAUDE.md`. Not "we fixed this bug in March." Store what is **not derivable**: the human's preferences, standing constraints, decisions and the reasoning behind them, the things that are only true because someone said so. If asked to remember something the repo already records, ask what was non-obvious about it — and save *that*. ## 5. Never store secrets Memory files are read into context constantly and land in transcripts, logs, and sometimes screenshots. Store the *pointer*: "credentials for X are in the secrets store, key name Y." Never the credential. This one is not hypothetical. The system Pearl was extracted from had grown to 110 memory files, of which **57 mentioned live credentials** — root passwords, a machine login in the index line itself. It was never publishable and nobody had noticed. Publishing that folder would have been a full infrastructure compromise, discovered too late. `install.sh` writes a `.gitignore` that refuses to track your memory directory. Leave it alone. ## 6. Update, don't duplicate Before writing, check for a file that already covers it. Two memories that disagree are worse than none — the agent will pick one arbitrarily and you will never know which. **Delete memories that turn out to be wrong.** A stale memory is not neutral. It is a confident lie in your own handwriting. ## 7. Memories are dated evidence, not present truth A memory reflects what was true when it was written. If one names a file, a flag, a host, or a path — **verify it still exists before acting on it.** Corollary for the human: an agent that says "memory says X" and stops there is doing it wrong. It should say "memory says X — checking" and then check. ## 8. Index lines are a budget `MEMORY.md` loads every session, so every line is rent paid on every turn, forever. Make each line a *hook*, not a summary: enough to know whether to open the file, nothing more. If the index line makes reading the file unnecessary, the fact was too small to be a memory. --- ## What good looks like After a few weeks, an agent with a healthy pearl will: - know which machine to run a job on, and why, without asking - refuse an approach you rejected a month ago, **and cite the reason** - recognize a bug shape it has seen before - catch that a memory is stale and check before acting on it - write a new memory unprompted when you correct it That last one is the tell. A system where the human maintains the memory is already dead. A system where the agent maintains it compounds. --- ## The failure mode nobody warns you about You will build all of this, use it for a week, and then stop writing memories during the interesting sessions — because the interesting sessions are busy. The busy sessions are the ones worth remembering.