Agents are brilliant and amnesiac. Close one and reopen it, and your project, your rules, your whole world are gone. A memory file fixes that: one file the agent reads automatically at the start of every session, so it walks in already knowing the room instead of asking you again.
3.6.1The file your agent reads first
You met this idea as your rules file. The memory file is that file, made real for each tool: it holds what is always true, who you are, how you work, what must never happen, in a few lines the agent reads before it does anything.
# Project: my-app
- Stack: Next.js + Postgres. One language, TypeScript.
- New code goes under src/, one folder per feature.
- Never commit secrets. Read them from .env.
- Run the app and confirm it works before saying done.
Keep it the constitution, not the encyclopedia: the standing law, not every detail.
3.6.2Find your tool's file
Every serious agent tool auto-reads one file. Same idea, different name:
| Tool | File it reads |
|---|---|
| Claude Code | CLAUDE.md at the repo root |
| Codex | AGENTS.md at the repo root |
| Cursor and most editors | a rules file or .cursor/rules/ folder |
Find yours and treat it as the first thing you set up, not an afterthought. Any equivalent works; the file changes, the idea does not.
There is now a shared convention for this, AGENTS.md, a single file over 30 tools read the same way. If your tool supports it, one file covers most of them at once.
3.6.3No built-in file? Inject it yourself
If your agent has no native memory file, you build the behavior. Keep one canonical file, context.md, and paste it (or have a tiny wrapper prepend it) at the start of each session.
The mechanism does not matter. The principle does: the standing truth of your project reaches the agent before it does anything else.
3.6.4Keep it short, or it rots
Every line of a memory file is re-sent on every turn, so bloat is a tax you pay forever, on requests that never even touch the topic. Keep it brutally short: only what must be true always. Push topical detail into skills the agent loads on demand.
This is measured, not a hunch. Studies across thousands of projects put the useful ceiling around 150 lines; past that, the file stops helping and quietly raises cost by roughly a fifth. If yours is longer, it is doing too much.
For facts that pile up, keep an index instead of a wall:
# MEMORY.md
- Auth: we use email + magic link. Details in auth/notes.md.
- Billing: Stripe, test mode until launch. See money/stripe.md.
One line per durable fact, the detail in a linked file. Fix any line the day the fact changes; a short current file beats a long stale one every time.
3.6.5Let the agent write it, but verify what it recalls
You do not maintain this by hand. When you correct the agent, tell it to save the correction, and the file grows itself: session 1 you fix a mistake, session 40 it never repeats because the note loads every time.
Two disciplines keep it from rotting. One fact per line, deduped. And a recalled line that names a file or a setting is a hint to check, never a fact to trust: a note written months ago can point at something since renamed. Treat old memory like old documentation, verify against reality before acting on it.
3.6.6Set up your memory file
This prompt has your agent create the right file for your tool:
Act as a senior engineer setting up my agent's memory.
Find the memory file my tool auto-reads (CLAUDE.md,
AGENTS.md, or a rules file), create it at the right place,
and seed it with my stack, where code goes, and my
non-negotiables. Keep it short, only what must be true
every session. Put topical detail in separate files.
My tool and project:
Do this now: paste the prompt so your agent writes its own memory file, then read it and cut any line that is not true on every single session.
