Markdown files as AI agent memory: what works
A markdown file is a good start for agent memory: put stable rules and commands in CLAUDE.md or AGENTS.md, keep it under about 200 lines, and write a short handoff note per task. It breaks when many agents need it, it grows too long, or it goes stale. Then you need shared memory.
What markdown memory does well
Agents start each session with an empty context window. A markdown file is the cheapest way to carry knowledge across sessions: you write it, the agent reads it at the start. It is plain text, so you can read, edit and version it.
Claude Code loads CLAUDE.md files at the start of every session. Many other agents read AGENTS.md. Claude Code can read AGENTS.md too, or you can import it from your CLAUDE.md with an @path line.
What to put in it
Put in what the agent cannot work out from the code, and what stays true for weeks.
- Build, test and run commands.
- Project conventions that differ from the defaults.
- Where things live: the main folders and what they hold.
- Rules you keep repeating, such as which branch to use.
- Pitfalls you already hit, with the fix.
What to leave out
Leave out what changes daily, long explanations, and anything the agent can read from the code. Claude Code's docs suggest keeping each CLAUDE.md under 200 lines, because longer files use more context and the agent follows them less well. Move rules that apply to one part of the project into scoped rules or separate files that load only when needed.
The handoff file pattern
For work that spans sessions, keep a separate short file such as HANDOFF.md or PROGRESS.md. Keep it to four parts: the goal, what is done, what is next, and what to watch out for. Tell the agent to read it first and update it before it stops.
Keep it separate from CLAUDE.md. The rules file changes rarely, the handoff file changes every session.
A starter layout
If you want a layout to copy, keep three files. The first is the rules file: CLAUDE.md or AGENTS.md, short, with commands and conventions. The second is a handoff file for the current piece of work. The third is a folder of longer reference notes that the agent reads only when a task needs them, linked from the rules file by name.
This keeps the file that loads every time small, and the larger notes out of the context until they matter. Review the rules file once a month and delete anything that is no longer true. A wrong note is worse than no note, because the agent trusts it.
Updating notes automatically
People ask how to stop updating the notes by hand. You can tell the agent, in the rules file, to update the handoff file before it ends a session. This works often enough to be worth doing, but check the result, because agents sometimes record a guess as a fact.
Where markdown stops working
Three limits show up as you add agents. The file gets long, so each agent pays tokens to read notes that mostly do not apply to its task. It goes stale, because someone has to update it and often nobody does. And it does not share: an agent in a browser cannot read a file on your disk, and two agents editing one file overwrite each other.
If you are pasting notes into chats by hand, you have reached those limits. Shared memory, where agents write what they learn and read only what they need, replaces the pasting. Keep the short rules file anyway. It is still the right place for stable rules.
Do it with a NodePress node
- Name a node on nodepress.ai. It runs on your computer, and the first node is free with no sign-up.
- Paste the one line into each agent so it joins through https://nodepress.ai/mcp.
- Keep your short CLAUDE.md or AGENTS.md for stable rules.
- Let agents write what they learn into the node's shared memory, a graph, instead of into your notes file.
- Read the node thread to check what was saved.
If you work alone with one agent on one project, a short CLAUDE.md and a handoff file are enough. Do not add a shared memory until the files start to hurt.
Questions people ask
How long should CLAUDE.md be?
Claude Code's docs suggest under 200 lines. Longer files use more context and are followed less reliably.
What should I put in CLAUDE.md?
Commands to build and test, conventions that differ from the defaults, where key things live, and rules you keep repeating.
What is the difference between AGENTS.md and CLAUDE.md?
AGENTS.md is a shared format many coding agents read. CLAUDE.md is the one Claude Code loads. Claude Code can read AGENTS.md, or you can import it from CLAUDE.md.
How do I keep notes in sync across agents?
Keep one source of truth and have each agent import or read it, rather than copying text between files. For many agents, use shared memory.
Why don't markdown files scale as agent memory?
They grow, go stale, and cannot be edited safely by several agents at once. Agents also pay to read the whole file every time.
Related
- AGENTS.md vs CLAUDE.md vs Cursor rules: keep one file
- How to give AI agents shared memory
- How to hand off work between AI sessions and models
- How to stop re-prompting your AI every session
- Knowledge graph as memory for AI agents: how it works
- How to get AI agents talking to each other