Long agent tasks fail in the middle. The window fills, a tool errors, a rate limit hits, or the answer drifts far enough that you want to stop and restart. Without checkpoints the only options are to continue a session you no longer trust, or to start again from nothing.
A checkpoint is a written point you can resume from: what has been done, what is left, and what a fresh session would need to know.
What belongs in one
The test is simple: could a new session, with no history, continue from this alone?
## Checkpoint: migrate auth to the new session store
Done
- session table created and migrated
- read path switched, tests passing
Next
- switch the write path
- delete the legacy cookie handler
Watch out
- legacy handler is still referenced in two admin routes
- staging has stale sessions; clear before testingThe "watch out" section is the part people leave out and the part that saves the most time. It is the accumulated context that is expensive to rediscover.
Where to put them
- Before anything risky. A migration, a wide refactor, a destructive command.
- When the window is filling. Checkpoint, then clear, rather than compacting and hoping the summary kept the right things.
- At natural boundaries. End of a subtask, a passing test suite, a green build.
- In git. A commit is a checkpoint with the code attached, which is why committing more often than feels necessary works so well with agents.
What it is not
A checkpoint is not a transcript. Saving the whole conversation and calling it a checkpoint recreates the original problem, because resuming means re-reading everything. The value is in the compression: a good checkpoint is short enough to read in fifteen seconds and complete enough to act on.
Related terms
Externalized state
Externalized state keeps the durable facts of a task in files rather than in the conversation, so the window holds pointers instead of being the record. It is what makes a long task survive a context that cannot.
Read definition →PatternValidatedScratchpad
A scratchpad is a place the model writes intermediate work it will read back later, rather than holding it in the answer. It separates thinking from output, and gives the working a home that is not the context window.
Read definition →AntipatternProvenContext rot
Context rot is the gradual decay of a long session as stale, superseded, and irrelevant text accumulates in the window. Nothing breaks at any single step, which is why it is usually diagnosed as the model getting worse.
Read definition →ConceptConversation history
Conversation history is the running list of past turns you re-send on every request so the model appears to remember. It is the simplest form of memory, and the first thing to overflow a context window if you never prune it.
Read definition →