💭 in your head · nothing to type
You now have AGENTS.md, TODO.md, STATE.md and a CLAUDE.md with the line @AGENTS.md.
Don't see these as "documentation" — picture them as handing over the watch to a new lighthouse keeper. The outgoing keeper leaves not just a manual, but everything needed to keep the light burning. The quirks of the mechanism, the rhythm of the waves in this bay, where the door creaks in a storm.
Run it through your head: what in your files already passes on the "living knowledge" of the lighthouse? What are you still keeping only in your own head — knowledge that someday needs to be handed over?
💭 in your head · nothing to type
A good memory system isn't a one-shot setup. It's a living system.
Don't think of this as rules — picture a jazz musician passing the head arrangement to a new band. Not notes on paper, but a living feel — how to hold a pause, where to improvise, where the structure has to stand firm.
Catch the moment: the last time Claude played something in the wrong key — that was a signal. What would you add to the score so the next "musician" feels the right groove from the first bar?
| Event | Where to update |
|---|---|
| Architecture changed | AGENTS.md, the project sections |
| New stack added | AGENTS.md, "Stack" |
| Task completed | TODO.md |
| Session ended | STATE.md: where you stopped, what's next |
| Agent made a mistake you fixed | AGENTS.md, "Rules" |
| Mid-session clarification the agent must keep using | A normal message in the session (or a rule in AGENTS.md if later sessions need it too) |
/btw doesn't fit here: it's a side question about the current session, and it isn't added to the conversation history.
A rule in AGENTS.md is the first step, not the last: the agent can miss a rule or lose it in a long session, but it can't get around a check. The stabilization loop:
AGENTS.md: "NEVER…", "ALWAYS…".