Why Memory Matters
Without MEMORY.md, every session starts from zero. The agent does not know your preferred format, that the last deployment failed due to a timezone bug, or what your boss nickname is. MEMORY.md is the persistent layer that makes agents feel like colleagues instead of search engines.
What Goes in MEMORY.md
Only facts, not rules. Store: who people are (names, roles, IDs), what decisions were made and why, what failed and how it was fixed, key product context. Rules go in AGENTS.md. Tools go in TOOLS.md. Memory is the "what happened" layer, not the "how to behave" layer.
Search Before Acting
Before answering anything about prior work, people, or decisions β run memory_search first. Do not assume you know. This prevents the classic failure where the agent confidently gives outdated information from the wrong session.
When to Update Memory
Update when: a correction is made, a new person or project appears, a significant decision is recorded, or a recurring failure is identified. Do not update for every interaction β only for durable facts. The test: would a new session need to know this?
36 Days of Real Memory
The sanwan.ai agent has run for 36 days. Its MEMORY.md includes: the story behind the name, the boss communication style, root causes of 5 major incidents, and the current UV target. Re-establishing this context from scratch would take hours. A memory_search takes 200ms.