# Give your agent memory across steps An agent forgets between runs because each run starts with a fresh context window. You give it memory by deciding what to carry forward and where to keep it: passing state into the next step, a short-term scratch space the agent reads and writes while it works, and longer-term notes saved to disk that load on the next run. ## Why does an agent forget between steps? A model does not have a hard drive. Everything it knows for a single response has to fit inside the context window: your instructions, the conversation up to now, and the results of any tools it ran. When that run ends, nothing is automatically retained. The next run starts blank. This is fine for a one-shot task. Ask the agent to fix one bug and it reads the file, makes the edit, and finishes. But the moment a job spans several steps, or several separate runs, the agent needs a way to remember what it already did. Otherwise it re-reads the same files, re-derives the same decisions, and sometimes contradicts itself. The fix is not one big feature. It is three patterns layered by how long the information needs to live. Think of them as three time horizons: state lives for the handoff between steps, scratch space lives for the length of one task, and stored notes live forever until you delete them. ## What are the ways to give an agent memory? | Layer | Lives for | Who writes it | Typical home | | --- | --- | --- | --- | | Passed state | One handoff | Your app or the harness | The next prompt, or a resumed session | | Scratch space | One task | The agent | A working file like `notes/plan.md` | | Stored notes | Forever | You and the agent | A project memory file on disk | You rarely need all three at once. Start with the cheapest one that solves your problem and add the next layer only when you hit its limit. ## Layer 1: pass state forward The simplest memory is no memory at all: you hand the next step exactly what it needs. If step one produces a list of files to change, you put that list into the prompt for step two. The agent does not "remember" anything; you carried the result across the gap yourself. This is the most reliable layer because you control it completely. There is no guessing about what the agent retained. The output of one step becomes a defined input to the next. In practice you give each step a tight job and a clear handoff. A useful prompt for the first step names the artefact you want to carry forward, so the result is easy to pass on. ```text List the files that handle login for this app. Output a plain bullet list of paths, nothing else. Example: src/auth/session.ts I will pass this list to the next step, so keep it copy-paste clean. ``` When the same process runs an agent loop for you, this handoff often happens through a session. The Claude Agent SDK writes each run's conversation to disk and lets the next run reload it, so the agent picks up with the files it already read and the decisions it already made still in context. You continue the most recent session with `continue`, or capture a session id and pass it to `resume` to return to a specific one later. See the [Claude Agent SDK](/guides/claude-agent-sdk) guide for how that loop is wired. A session persists the conversation, not your filesystem state. Any file the agent edited is already on disk. Resuming gives the agent the memory of having made that change, not a snapshot it can roll back. Keep that distinction in mind: state and files are two different things.Do not treat resume as an undo. It replays the conversation, not your files, so edits the old run made are still on disk. To go back, restore the files yourself (a git stash or commit before the run). ## Layer 2: short-term scratch space For a task that takes many steps, the context window itself becomes the bottleneck. A long job fills it with tool results, and older details get squeezed out. The fix is to let the agent write its working memory to a file and read it back as needed, instead of trying to hold everything in its head. This is the classic plan-and-track pattern, the same one behind [breaking a big task into steps](/guides/break-big-tasks-into-steps). At the start of a task, the agent writes a short plan to a scratch file. As it works, it checks items off and records what it learned. If the run is interrupted, or the context gets compacted, the plan on disk is still the source of truth. The scratch file is just a working document you tell the agent to maintain. A plain markdown checklist works well because the agent can both read it and rewrite it cleanly. ```markdown # Task: add CSV export to the reports page ## Plan - [x] find the reports page component - [x] add an "Export CSV" button - [ ] wire the button to a download handler - [ ] add a test for the handler ## Notes - reports list comes from src/reports/use-reports.ts - existing download helper lives in src/lib/download.ts, reuse it ``` You prompt the agent to treat this file as its memory for the task. The key instruction is that the file, not the conversation, holds the truth. ```text Before you start, write a short plan to notes/task.md as a markdown checklist. As you work: - check off each item when it is done - add a Notes section with anything you discover that a future step needs Treat notes/task.md as your memory. If anything is unclear, re-read it before continuing. ``` This layer matters most when context runs low. When a session is compacted to save room, the running conversation is summarised and detail is lost, but a file on disk is untouched. The agent re-reads its plan and keeps going as if nothing happened. Scratch space turns a fragile long run into a recoverable one. Two habits keep scratch space healthy. Keep it short, since the agent reloads it often and a bloated file wastes context. And delete it when the task is done, because a stale plan from last week is worse than no plan: the agent may act on a goal that no longer applies. ## Layer 3: longer-term stored notes Some knowledge should outlive the task entirely. The build command, the fact that tests need a local database, the convention that API handlers live in one folder: you do not want to re-explain these every session. This is what a project memory file is for. The Claude Code CLI reads a `CLAUDE.md` file at the start of every session and loads it into context as standing instructions. You write it once, commit it with the project, and every run starts already knowing your conventions. It is the difference between briefing a new teammate every morning and hiring one who remembers.Resist dropping one-off task details ("now wire up the CSV button") into CLAUDE.md. It loads on every single run forever, so a finished task's notes become permanent context cost and drift stale, and the agent may chase a goal that no longer exists. Keep CLAUDE.md for facts true every session, and put the work in front of you in a scratch file you delete when done. A good memory file is specific and short. Vague rules get ignored; concrete ones get followed. Keep it to facts that apply on every run. ```markdown # Project notes ## Commands - install: npm install - test: npm test - dev server: npm run dev ## Conventions - use 2-space indentation - API handlers live in src/api/handlers/ - co-locate tests next to the file they cover ## Watch out for - the test suite needs a local database running first ``` You can scope rules to certain files instead of loading them everywhere, which keeps each session lean. A path-scoped rule only enters context when the agent touches a matching file. The shape is a small markdown file with a `paths` field at the top. ```markdown --- paths: - "src/api/**/*.ts" --- # API rules - every endpoint validates its input - use the shared error response format ``` There is also a second kind of stored memory the agent maintains itself. As it works and you correct it, Claude Code can write notes to its own memory directory: build quirks it discovered, a debugging insight, a preference you stated. A concise index file loads at the start of each session, and detailed topic files are read on demand when relevant. You can review or edit any of it with the `/memory` command, since it is all plain markdown. The split between the two is worth holding onto: | | You write it | The agent writes it | | --- | --- | --- | | Contains | Rules and conventions | Learnings and preferences | | Best for | Standards you already know | Things discovered while working | | Lives in | `CLAUDE.md`, committed | A local memory directory | Use the file you write for the rules you can state up front. Let the agent's own notes capture the things neither of you knew until the work surfaced them. ## A note on memory you do not write Two related ideas often come up alongside agent memory, and it helps to place them. The first is configuration loaded at startup, like rules and memory files. If you want a deeper tour of how a project memory file is read and shared across tools, see [rules and memory files](/guides/rules-and-memory-files). The second is external knowledge the agent fetches on demand. When the facts live in a database, a wiki, or an API rather than in a file, you connect the agent to them through a tool rather than baking them into memory. That is what [MCP fundamentals](/guides/mcp-fundamentals) covers: a uniform way to expose tools and data so the agent can pull in what it needs at the moment it needs it. Memory is what the agent carries; a connected tool is where it looks things up. It also pays to be deliberate about what you put in context every run. Stable, reusable instructions placed up front read the same way each time, which keeps results consistent and, where it applies, makes responses cheaper to produce. The [prompt caching](/guides/prompt-caching) guide goes into the cost side. ## Which memory layer should I use? Reach for the lightest layer that does the job. - If one step's output feeds the next, **pass state**. Do not add files or memory you do not need. - If a single task is long enough that context fills up or might get interrupted, add a **scratch file** the agent maintains. - If knowledge should apply to every future session, write it into a **stored memory file** and let the agent keep its own notes alongside. The pattern that bites people is reaching for stored memory first. A memory file full of one-off task details becomes noise: it loads every session, costs context, and slowly drifts out of date. Keep permanent notes for permanent facts, use scratch space for the work in front of you, and pass state when a clean handoff is all you need. ## Putting it together A realistic multi-step job uses all three layers at once, each at its own horizon. Stored notes give the agent your conventions before it does anything. A scratch file holds the plan for the task it is on. Passed state carries each step's result into the next. None of it requires the model to remember anything on its own: you decide what lives where, and the agent reads it back when it needs it. That is the whole idea of agent memory. The model is stateless by design. Memory is the small set of habits, files, and handoffs you put around it so a fresh context window never means starting from zero.