State and memory

How to make a long task survive the end of a session: keep progress outside the model, in files and in Git, and tell task state apart from long-term memory.

Before you start

  • Context engineering for agentsTechnique

    What information the agent receives at each moment, why more is not always better, and how to give it just enough: the essentials up front and the rest when it needs them.

    Published

Key idea: the model remembers nothing between sessions. If you want continuity, the harness has to keep progress outside the model —in files and in Git— so each new session can read it and carry on.

The problem

Imagine a project that needs several hours of work: implementing ten features. No context window can hold all of that. Sooner or later one of these happens:

  • The session ends and the next one starts from scratch.
  • The context is compacted: the client summarizes older messages to make room, and details get lost in the summary.

If the conversation is the only record of progress, the new session doesn’t know what is done, what failed, or what was decided. It may redo work, break something that worked, or call a half-finished project complete.

Think of a team working in shifts: whoever comes in doesn’t remember what the previous shift did, so they read the handover notes. The agent needs the same thing.

How it works

It helps to separate three things that are often mixed up:

Layer What it holds How long it lasts
Conversation This session’s messages and tool calls Until the session ends or is compacted
Task state Where the work stands: progress, pending items, commits As long as the task
Memory What is worth remembering: conventions, preferences Across tasks

The practical idea is that task state lives in files, not in the model’s head. Anthropic describes a harness for agents that work across many sessions like this:

  1. A list of features, all initially marked as pending.
  2. A progress file where each session notes what it did and what is left.
  3. Frequent Git commits, which act as history and make it possible to go back.
  4. Each new session starts by reading the progress file and git log, picks one feature, finishes it, and verifies it before marking it done.

Compaction is another piece, but it is not memory: it is a way of summarizing the conversation so it still fits in the window. It helps a long session continue, but a summary can drop a constraint or a detail. Whatever you can’t afford to lose, write it to a file.

Practical example

A simple progress file, PROGRESS.md, that the agent updates at the end of each session:

# Progress

## Done

- [x] summarizeReading with tests (commit a1b2c3d)
- [x] countWords ignores repeated spaces (commit d4e5f6a)

## Pending

- [ ] Export the functions from index.js
- [ ] Document the API in the README

## Notes for the next session

- Tests run with `node --test`.
- Open question: should firstSentence include the final punctuation? Not decided.

And a few lines in AGENTS.md so the cycle happens in every session:

## Long tasks

- When you start, read PROGRESS.md and the latest `git log` entries.
- Work on one pending task at a time.
- When you finish it, verify it, commit, and update PROGRESS.md.

Notice the open question: it is written down as a question, not as a decision. A careless summary could turn it into a fact.

Common mistakes

  • Trusting the agent to “remember”. It won’t. Whatever is not written to a file is lost with the session.
  • Confusing compaction with memory. A summary helps you continue; it does not decide what is worth keeping long term.
  • Saving everything as memory. Stale or wrong notes get loaded in every session and confuse more than they help. Keep only what is confirmed and review it now and then.
  • Saving secrets. A progress or memory file is no place for tokens, passwords, or personal data.
  • Marking things done without verifying. A progress file is only useful if it tells the truth. Verify each task before you mark it.

When to use it

When a task doesn’t fit in a single session, when you will pick it up another day, or when several agents work on the same project. For a short task that starts and ends in one conversation, you need none of this.

Next step

You now know what to ask for, what information to provide, and how to keep progress. The next block covers the context that repeats in every task: AGENTS.md, the file where your project introduces itself to the agent.

Sources

Accessed on 2026-10-05.

  • AGENTS.md: persistent project instructionsTechnique

    A Markdown file at the root of the repository that tells the agent how your project works: commands, conventions, and how to check changes. It is a guide, not a control mechanism.

    Published
  • Verification and evaluationTechnique

    How to check that the agent did the job right without taking its word for it: give it ways to verify itself, review both the result and the process, and compare setups honestly.

    Published