ClaudeContext engineeringLevel 4: Multi-tool systems

How Do You Give Claude Memory Across a Long Project?

Keep a short file with what's done, what's next and what was decided, and have each session read it first and update it last. Claude has built-in memory in the apps and in Claude Code, but a file you control is still what lets a long project survive a fresh start. You can read it, correct it and commit it.

Prompt to copy 
We're working on a long project, and every session starts from nothing. Create progress.md and keep it under 50 lines:

## Now
what we're doing, and the next single step
## Done
finished work, with commit or file references
## Decisions
each decision and its reason, in one line
## Known problems
what's broken and what we tried

At the start of every session, read it and tell me where we are in two lines. Before we stop, update it. Mark something done only after it's been verified, not when it's written.
  1. 1Read the progress notes
  2. 2Do one feature
  3. 3Verify it end to end
  4. 4Update the notes
The next session starts here
The session pattern in Anthropic's memory tool docs: each new session resumes from what the last one recorded.
  • App memorysaved as topics, per project
  • CLAUDE.mdyour instructions for Claude Code
  • Auto memoryfirst 200 lines or 25KB load
  • API memory toolyour app runs the file operations
Four places memory can live. Sources: Anthropic's memory help page, Claude Code docs and API docs, checked 6 November 2026.

Try it now

  1. 1In Claude Code or a Claude project, send the prompt above on a project you're working on now.
  2. 2Work on one thing, then ask Claude to update the file.
  3. 3Run /clear, or open a new chat, and send: "Read progress.md and tell me where we are and what's next."
  4. 4You'll know it worked if you don't have to add anything. If it asks what a decision meant, that line needs its reason written down. In a Claude project, add the updated file to project knowledge.

Use it when

Use it for work spanning several sessions: a product build, a long report, a migration or a months-long client job. Also use it whenever you find yourself explaining the same background at the start of a new chat.

Skip it when

Skip it for tasks you finish in one sitting. Don't put rules that must never be broken in a memory file either. Anthropic's docs say memory is context, not enforcement, so for those use a hook or a deny rule. And leave out anything Claude can read from the repo itself.

Why it works

Each Claude Code session begins with a fresh context window, and chats in a project don't share context. Anthropic's docs describe four places memory can live. App memory is saved as topics, and each project has its own. In Claude Code, CLAUDE.md holds your instructions, and auto memory holds Claude's notes, with the first 200 lines or 25KB loaded each session. On the API, the memory tool memory_20250818 has Claude request file operations under /memories, and your app runs them. Anthropic's prompting guide adds that git makes a good log of what's been done, with checkpoints to restore.

Example

You're rewriting a 60-page employee handbook over several weeks. progress.md says chapters 1 to 4 are approved, chapter 5 is next, the legal team rejected the phrase "unlimited leave", and the leave table has an unresolved conflict with the Italian contract. Each new chat starts by reading that file, and you never re-explain why that phrase is gone.

Going further

Anthropic suggests a different first session on long agent work: set up tests, scripts and the progress file, then iterate from there. It also says that starting a brand new context window can beat compaction, because current models are good at rediscovering state from the filesystem, if you tell them to review progress.txt, tests.json and the git log. With the API memory tool, you're responsible for validating every path, since /memories/../../secrets.env is a real traversal risk, and for capping file sizes and deleting old files. It also pairs with compaction: compaction keeps the active context small, and memory holds what must survive it.

Common mistakes

  • Letting the file grow into a diary, so it costs more to read each session and the current state gets buried.
  • Marking work done when it's written. Anthropic's pattern marks it done only after end-to-end verification.
  • Relying on app memory for project facts you can't easily inspect. Check Settings > Your Claude, or keep a file.
  • Skipping the reason behind a decision, so a later session reasonably undoes it.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Workflow How Do You Build a SaaS With Claude, One Slice at a Time? Best practice What Should Go in Your CLAUDE.md? Best practice What Should Go in a Claude Project's Instructions? Workflow Should Claude Build a Whole Feature at Once?

Beyond the course

Glossary Context window Pricing guide Claude pricing, plans and models