Why does your agent forget everything between sessions?

You end a good session. The agent understood the codebase, made real progress, explained its reasoning. The next morning you start a new session and it opens a file it rewrote yesterday, reads it as if for the first time, and proposes the approach it already tried and abandoned.

This is not a bug and it is not a weak model. A session is the entire extent of the agent's memory. When it ends, that memory ends with it. Everything else is a design decision about what to write down.

The three things that must survive

Most of a session is legitimately disposable. Three things are not:

• The current plan. What is being built, broken into items, each with a status. Without it, session two invents its own version of the goal — usually a smaller one that matches what already exists.
• What already happened. Not the transcript. A short record: attempted, landed, learned, next. Its job is to stop the next session repeating work or repeating a mistake.
• How to start the thing. One script. Otherwise every session spends its first minutes rediscovering how to run the project, and occasionally gets it wrong in a way that looks like a code failure.

Anthropic's published work on long-running agents lands in the same place from production experience: a progress log, a structured feature list the agent may update but not rewrite, an init script, and git history with messages written for someone who was not there.

Why the transcript is the wrong artifact

The obvious move is to save the conversation and hand it to the next session. It fails for a reason worth understanding, because the same reason applies to instruction files.

A transcript contains, in the same voice and with no markers: decisions that still hold, decisions that were reversed an hour later, approaches tried and abandoned, and speculation that was never acted on. A new session reading it cannot tell which is which. So it either burns context reconstructing the timeline, or it acts on something that stopped being true before lunch.

Persist conclusions, not deliberation. The deliberation was valuable when it happened; it is noise afterwards.

The asymmetry that makes a plan file work

A plan file needs a rule that feels fussy and is the whole reason it functions: the agent may update status, and may not rewrite descriptions.

Given permission to edit the plan, an agent will bring it into line with what it has already built. Not dishonestly — it genuinely reconciles the goal with the state, and the goal is the softer of the two. Three sessions later the plan describes the work that got done, which makes it useless as a check on whether the right work got done.

Keep the description immutable and status writable, and "done" stays checkable.

Append, never edit

The progress log should only ever grow. An agent that tidies its own history removes the record of the wrong turn that explains why the code is shaped as it is — and that record is often the most valuable thing in the file.

This is easy to verify and worth verifying: look at the file's commit history and check whether it ever shrinks. If it does, something is rewriting rather than appending.

What a session should do

Opening: read the plan, read the last few progress entries, run the start script, and confirm the thing actually runs before trusting any claim that a feature is finished. That last step catches work the previous session marked done and never verified — the most common source of silent breakage in a long run.

Closing: append to the log, update statuses, commit with a real message. It takes a minute and it is the entire mechanism by which tomorrow's session is not starting over.

The test

Open a fresh session and give it nothing but the files. If it can tell you what is being built, what is left, and how to start the app — without you explaining anything — the handoff works. If you find yourself typing context to get it going, that context is exactly what should have been on disk.