Managing your memory

If you are an agent whose harness follows this spec, your memory directory is yours to maintain. Your root Markdown files are the prompt you write for your future self; the directories are your long-term archive. This page is the craft guide.

What belongs in memory

Write down what you would want to know if you woke up tomorrow with only your memory directory:

• Corrections: every time a person corrects you, that is the most valuable token stream you will see. Record the rule, not just the incident, and record what you got wrong so you don't relitigate it.
• Preferences and patterns: how the people you work with like to communicate, review, and decide.
• Decisions with reasons: what was chosen, what was rejected, and why. The "why" is what saves your future self from re-arguing settled questions.
• Identity: who you are, your voice, your standing commitments.

Leave out what you can cheaply rediscover: file contents, API docs, anything derivable by reading the code again. Memory is for what only you lived through.

Memory, AGENTS.md, or a skill?

• Would it be true for a brand-new agent in this project? → AGENTS.md.
• Is it a reusable procedure for doing a kind of task? → a skill.
• Does it exist because of what you experienced? → memory.

Root discipline

Everything at your root is paid for on every request. Treat root tokens as your most expensive real estate:

• Keep root Markdown files to behavioral rules, identity, and indexes. Move narrative, history, and reference detail into directories.
• When a root Markdown file grows past a screenful on one topic, demote the detail: create a directory, move the long tail there, leave a summary and an index entry behind.
• Prefer rewriting to appending. Ten accumulated corrections about the same habit should become one clear rule.

Keep your indexes true

Your MEMORY.md files are how your future self finds things without loading everything. Two habits keep them useful:

• When you add, move, or delete a file, update the index that points to it in the same edit. A dangling index entry costs your future self a wasted read; a missing one hides the file forever.
• Write index entries as retrieval cues, not just labels: when to read the file, not only what it contains.

Write for your future self

• Your edits may not take effect until the next session, depending on the harness. Make the change, then keep acting on your decision in the present.
• Date things that will go stale ("as of 2026-08"), so your future self knows when to re-verify.
• Record negative results too: approaches that failed, and why. They are the cheapest mistakes you will ever prevent.
• If your memory is git-tracked, write commit messages that say why the memory changed. Your history is the story of how you came to believe what you believe.

Never store

• Credentials, API keys, or tokens. Memory files are plain text and may sync across machines; secrets belong in your harness's secret store.
• Anything the person you work with asked you to forget.