Lesson 1: Beyond Memory, There's State

Learning goals:

• In one sentence, tell "memory" (the context you feed the model) apart from "execution state" (the running scene the harness is holding), and give an example of each
• Name at least three concrete grounds for why "a crash is especially deadly to a long task," and say which part of the run each one points at
• Given a list of things a running harness is juggling, decide whether each is memory, execution state, or a disk output — and whether it survives the process being killed

Prerequisites: You've finished the earlier courses in this series and understand the stop_reason-driven harness loop from "Agent Harness Fundamentals: Loops and Control" and context management from "Context Engineering: Spending Finite Attention Where It Counts" | Next: Lesson 2 >>

Turn 23, and the process gets killed

Picture the harness you wrote in "Agent Harness Fundamentals: Loops and Control" running a long task that takes 40 turns: read a batch of files, analyze them one at a time, and append conclusions to a report as it goes. On turn 23, the process gets killed — maybe a deployment update, maybe the server lost power, maybe you fat-fingered Ctrl+C.

You check the disk: the report files from the first 22 turns are all there; NOTES.md (that task-progress summary you set up in "Context Engineering: Spending Finite Attention Where It Counts") still records "which file I've analyzed up to, and what the conclusion was." Looks like not much was lost — just restart the process and pick up where it left off.

But once you restart you find the messages array in runAgent is empty — it has to rebuild from [{ role: "user", content: userInput }]. The turns counter is back to zero. tokensUsed is back to zero too. And if the crash landed on turn 23 right between "the model named a tool" and "the tool result got pushed back into messages," that tool call — whether it had just started running or had already finished — now leaves no trace either.

The task doesn't resume from turn 23; it starts over from turn 1. The files on disk are all there, but the harness's own record of "how far did I get" left nothing behind.

What memory is, what state is

Before this course can teach what it's here to teach, it has to draw a line against a concept that's easy to blur.

Memory is the context you feed the model — Course 5, "Agent Memory and State," covers how to persist it across sessions, and Course 8, "Context Engineering: Spending Finite Attention Where It Counts," covers exactly what you feed the model to look at each turn. It answers the question "what has the model seen?" NOTES.md is one vehicle for memory: it's already written to disk, and the next turn or the next session can read it back and drop it into the prompt.

Execution state is the running scene the harness process itself is holding — the messages array, counters like turns and tokensUsed, the tool call that hasn't been recorded yet. It answers the question "does the harness remember how far it got?"

The key difference between the two isn't "what the content is" but "where it lives right now." Memory may already be on disk (NOTES.md sits in the filesystem, and whether the process lives or dies doesn't change that it's still there); execution state, by default, lives only in the process's memory — the thing the line let messages = [...] creates, until someone deliberately writes it to disk, gets reclaimed along with the memory the moment the process exits. Nothing in the last section — messages, turns, tokensUsed, the dangling tool call — is written to disk on its own.

This state is exactly what this course will teach you to turn into something that can be written to disk and restored.

Why this is make-or-break for long tasks

First, do the accounting: "Agents can run for long periods of time, maintaining state across many tool calls."¹ That's precisely why the messages array on turn 23 keeps growing. But it also means "Agents are stateful and errors compound."¹: the more state piles up, the moment something in the chain goes wrong the cost isn't linear, it stacks.

Add one more: "Without effective mitigations, minor system failures can be catastrophic for agents."¹ Putting "minor" and "catastrophic" side by side describes exactly the turn-23 situation — the process getting killed is an ordinary operations event on its own, but it wipes 22 turns of execution state in one stroke, and that's what magnifies the cost.

After an error, "When errors occur, we can't just restart from the beginning: restarts are expensive and frustrating for users."¹ So what you want to build is a system where, "Instead, we built systems that can resume from where the agent was when the errors occurred."¹ — which is why "beyond memory, there's state" isn't an academic distinction but the foundation for whether a long task can survive an interruption.

The longer the task, the heavier this bill: "The LLM will potentially operate for many turns, and you must have some level of trust in its decision-making."², and "The autonomous nature of agents means higher costs, and the potential for compounding errors."². The more turns it runs, the thicker the execution state it accumulates, and the more a single interruption can erase.

Crashes aren't rare

That "process got killed" on turn 23 sounds like a low-probability accident, but for a long task that runs dozens of turns, getting interrupted partway through isn't unusual at all. Even the most routine deployment update can collide with a running agent — which is why teams deliberately "use rainbow deployments to avoid disrupting running agents, by gradually shifting traffic from old to new versions"¹, the reason being that "whenever we deploy updates, agents might be anywhere in their process."¹.

In other words, even the people running operations assume "the agent can be interrupted at any moment" as something that will happen, and design mechanisms specifically to dodge it. Your harness has no reason to assume it'll be luckier.

The cure, in preview: this course's roadmap

The execution state lost on turn 23 has a five-step fix, which is also the order of the next five lessons:

1. Checkpoints (Lesson 2) — periodically serialize execution state like messages, turns, tokensUsed, and the dangling tool call to a checkpoint file on disk.
2. Resuming from a checkpoint (Lesson 3) — after the process restarts, read that state back out of the checkpoint file, rebuild messages, and let the loop pick up where it broke instead of starting over from turn 1.
3. Side effects and idempotency (Lesson 4) — the hardest part of resuming isn't "the state is gone," it's "some tool calls may actually have run already": which tools are safe to re-run, and which must be guarded against running twice.
4. Rewind and fork (Lesson 5) — checkpoints aren't only for disaster recovery; they also let you rewind to an earlier scene and retry, or fork off another attempt from some node.
5. Hands-on (Lesson 6) — take the machinery from the earlier lessons, fit it into the harness from "Agent Harness Fundamentals: Loops and Control," and run a long task through "killed partway, restart, run through to completion" yourself.

A community open-source roadmap built around "harness engineering" boils this down to one line: "Checkpoint state every node so you can resume, rewind, fork."³ — that's just a framing note from a community doc about what the persistence component is responsible for, not a spec this course copies verbatim, but the order it points to lines up with the five steps above.

Proportion: not every task needs this

Not every agent has to carry the checkpoint machinery. On adding complexity, "you should consider adding complexity only when it demonstrably improves outcomes."² — a task that wraps up in a few tool-call turns has only a handful of entries in messages, and if the process dies you just re-run it; the cost is asking once more, not worth designing a whole save-and-restore mechanism for.

What actually needs the machinery in this course is a scenario like turn 23 at the top: a task that runs dozens of turns, may take minutes to hours, and accumulates a large pile of un-persisted execution state along the way. To decide whether to bring in checkpoints, ask yourself one question first: if it got killed right now, can you live with the cost of re-running it? If you can't, that's when the next few lessons come in.

Recap

• Agents can run for long periods, maintaining state across many tool calls, and precisely because of that they're stateful and errors compound¹ — the more state piles up, the more a single failure can erase.
• Without effective mitigations, a minor system failure can be catastrophic for an agent¹; after an error you can't restart from the beginning, because restarts are expensive and frustrating for users, so you build systems that resume from where the error occurred¹.
• Crashes aren't rare — even a routine deployment update calls for rainbow deployments specifically to avoid disrupting running agents, because at deploy time an agent might be anywhere in its process¹.
• Autonomous operation inherently carries higher costs and the risk of compounding errors²; the longer the task, the heavier this bill, and the more it needs a mechanism that survives interruption.
• Not every task has to carry this machinery — add complexity only when it demonstrably improves outcomes², and for a task that wraps up in a few turns the cost of just re-running it is usually acceptable.
• Memory (the context fed to the model) and execution state (the running scene the harness holds) are two different things: memory may already be persisted, execution state lives only in process memory by default — and the next few lessons are about turning that execution state, too, into something that can be written to disk and restored.

>> Lesson 2: Checkpoints: Writing the Execution Scene to Disk