AI Guides › Step-by-step guides
By Nigel Guy · 7 min read
Most people give each AI tool its own pile of instructions: a long CLAUDE.md here, a pasted preamble there, a different version in every agent. The piles drift apart, contradict each other, and none of them records what was decided last week. The fix is not a cleverer prompt. It is one small folder of plain files that every agent reads in the same order before it replies.
The rule: keep one source of truth in plain Markdown, give it a fixed read order, and make each file answer exactly one question.
A note on provenance. This guide was prompted by a social post describing a "seven-file memory structure" shared by seven agents. We could not verify that post's exact files, so nothing below claims to be that structure. What follows is our own seven-file design, built on behaviour that the official Claude Code and Codex documentation confirm.
You need:
CLAUDE.md, and since v2.1.277 can read AGENTS.md directly. Codex reads AGENTS.md. Many other coding agents read AGENTS.md too, according to agents.md.Cost: the files are free. The tools that read them have their own plans, so check the current £ price on each vendor's pricing page at checkout.
Two limits shape the design. Claude Code's docs advise keeping each CLAUDE.md under about 200 lines, because longer files cost context and reduce adherence. Codex stops adding AGENTS.md content once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. Short files are not tidiness, they are a requirement.
| # | File | The one question it answers | Who edits it |
|---|---|---|---|
| 1 | AGENTS.md |
Where do I start, and in what order do I read? | You, rarely |
| 2 | memory/01-role.md |
Who am I in this project, and who am I serving? | You |
| 3 | memory/02-rules.md |
What must I always or never do? | You |
| 4 | memory/03-state.md |
What is true right now? | Agent and you |
| 5 | memory/04-decisions.md |
What has been decided, and why? | Agent proposes, you approve |
| 6 | memory/05-glossary.md |
What do our terms, names and places mean? | You |
| 7 | memory/06-handoff.md |
What happened last session, and what is next? | Agent, every session |
The order runs from stable to volatile. Identity and rules rarely change; the handoff changes daily. Reading the stable files first gives the agent a frame before it meets the moving parts.
Make a memory/ folder at the project root and an AGENTS.md beside it. The entry file is only an index. It names the read order and nothing else, so it stays tiny.
How the entry file pulls in the other six depends on the tool, and this is the beginner trap.
Claude Code supports @path/to/file imports inside CLAUDE.md. Imported files are expanded and loaded at launch, up to four hops deep, and relative paths resolve from the file that contains the import. Create a CLAUDE.md containing:
@AGENTS.md
and put the other imports in AGENTS.md itself:
Read these in order before replying.
@memory/01-role.md
@memory/02-rules.md
@memory/03-state.md
@memory/04-decisions.md
@memory/05-glossary.md
@memory/06-handoff.md
Per the docs, imports organise a long file but do not reduce its context cost, because everything loads at launch.
For tools where we have not confirmed import support, do not assume @ works. Say in words "open these files in this order", and accept that the agent may or may not follow it. Claude's docs make the same point: a CLAUDE.md that only tells Claude in words to read AGENTS.md depends on Claude choosing to open the file. If you rely on a tool we have not checked, test it with Step 5.
Keep every file under about 40 lines. Use short imperative sentences and concrete values. The templates:
Here is a prompt to draft them from what you already have.
You are a documentation editor helping me set up a shared memory folder that several AI agents will read before every reply.
Goal: produce six short Markdown files (role, rules, state, decisions, glossary, handoff), each under 40 lines, each answering one question only.
My inputs:
- Project: [PROJECT_NAME_AND_PURPOSE]
- Who the agent serves: [AUDIENCE]
- Existing instructions or notes to mine: [PASTED_NOTES]
- Style requirements: [STYLE_RULES]
- Current status and next action: [CURRENT_STATE]
Steps:
1. List any information you need that I have not given. Ask me for it and stop. Do not guess names, dates or decisions.
2. Sort my notes into the six files. Put each fact in exactly one file.
3. Write each file with a heading naming the question it answers, then short imperative bullets.
4. Flag any two instructions that contradict each other and ask which wins.
5. Self-check before answering: every file under 40 lines, no duplicated facts, no invented details, every rule testable.
Output: six fenced code blocks, each preceded by its filename.
Fill in the five bracketed items.
The seventh file only works if it is updated. At the end of each session, send:
You are closing this session. Update memory/06-handoff.md using only what happened in this conversation.
Write: (1) what we finished, (2) what is unresolved, (3) the single next action, (4) any decision that should move to memory/04-decisions.md, marked "proposed".
Rules: do not edit any other file. Do not record anything I did not confirm. If you are unsure whether something was decided, list it under unresolved.
Self-check: is every line traceable to this conversation? If not, delete it. Show me the new file contents for approval before saving.
Session notes, if any: [OPTIONAL_NOTES]
Claude Code also has auto memory, where Claude writes its own notes, stored per project under ~/.claude/projects/<project>/memory/, with the first 200 lines or 25KB loaded each session. It is separate from your folder, so do not expect other agents to see it. Run /memory in a session to inspect or toggle it.
/memory to see which instruction files loaded.04-decisions.md.CLAUDE.md or CLAUDE.local.md exists in your working directory or above it, Claude Code's default is to read those instead of AGENTS.md. The @AGENTS.md import in Step 2 avoids that surprise.