Your agent now has a job (Lesson 28.1) and hands (Lesson 28.2). But there is still a gap: what happens between runs? A chat window forgets everything when it closes. An agent that forgets everything re-reads the same sources, repeats the same work, and never notices what changed.

State closes that gap.

Context is a conversation; state is operational memory

Every model has a context window — the text it can see right now. That window is generous and temporary. It holds the current instructions, the recent tool results, the draft in progress. When the run ends, it evaporates.

State is what survives: durable, structured facts the next step — or the next morning's run — can load back in. Think of it this way: context is the desk you are working on; state is the filing cabinet you return to tomorrow.

An agent needs state even with a very long context window, for three reasons:

1. Runs end. A schedule fires, a queue worker finishes, a container restarts. The next run starts with an empty desk. 2. Work is longer than one conversation. A five-source check with retries, errors, and a pending review does not fit comfortably — or cheaply — in a single transcript. 3. Decisions need compact facts, not transcripts. "Source 3 of 5 done, 2 findings saved, 1 error pending retry" is a better decision input than fifty pages of chat history.

What belongs in run state

A minimal run state answers six questions at a glance:

Nothing exotic. If a future debugger — possibly you, three weeks from now — can reconstruct what happened from these six fields, the state design works.

Where state lives

You already met every storage option in earlier parts. The choice depends on how durable and queryable the facts need to be:

• Markdown. Human-readable rules, review packets, handoff notes. Great for anything a person reviews.
• JSON. Structured run records: job IDs, step lists, error counts. Easy to load, validate, and diff.
• Database rows. Operational memory at scale: thousands of findings, deduplication, search by ticker or date. Part VI taught you when a pile of files becomes a database.
• Queues. Pending and in-progress work: which jobs are waiting, which worker owns them, what retries remain. Part VII taught you the queue as the agent's to-do list.
• Logs. The append-only truth: every tool call, its inputs, its result or error, its timestamp. Logs are how you audit a run after the fact.

A small agent typically uses three at once: JSON for the run record, Markdown for the human-facing packet, logs for the audit trail. Databases and queues earn their place when runs multiply.

Worked example: the ingestion agent that resumes

Imagine a document-ingestion agent. Each night it processes a folder of PDFs: extract text, check freshness, save a record, flag anything needing review.

Without state, a crash at file 40 of 100 means starting over — reprocessing 39 files, re-calling the model 39 times, paying twice.

With state, each file carries a status:

invoice-001.pdf → done (saved 2026-09-11, record #481)
invoice-002.pdf → done (saved 2026-09-11, record #482)
invoice-003.pdf → failed: extraction error, retry 1 of 3
invoice-004.pdf → pending
...

A retry loads the state, skips everything marked done, retries the one failure, and continues from the first pending file. The run resumes the missing step instead of starting blindly. That resume behavior — not the model's cleverness — is what makes the agent reliable enough to schedule overnight.

Notice the discipline: statuses are written by the program after each validated step, not narrated by the model from memory. "Done" means a record exists at a known location with a passing check. Anything else is pending, failed, or awaiting review.

Check your understanding

1. In your own words, what is the difference between context and state? 2. Why does a long context window not remove the need for state? 3. Which of the six run-state fields would you check first if a run crashed halfway? 4. When does a JSON run record stop being enough and a database start making sense?

Exercise: design a minimal JSON state record

For your AGENT-CARD.md agent, write a state record for one imagined run. Use this shape:

{
  "job_id": "watcher-2026-09-12-001",
  "goal": "Check 5 approved sources for 2 competitors",
  "sources": [
    {"url": "https://example.com/feed-a", "status": "done", "findings": 1},
    {"url": "https://example.com/feed-b", "status": "done", "findings": 0},
    {"url": "https://example.com/feed-c", "status": "failed", "error": "timeout", "retry": "1 of 3"},
    {"url": "https://example.com/feed-d", "status": "pending"},
    {"url": "https://example.com/feed-e", "status": "pending"}
  ],
  "errors": [{"source": "feed-c", "type": "timeout", "at": "2026-09-12T09:04Z"}],
  "pending_review": ["review/2026-09-12-packet.md"],
  "output": "review/2026-09-12-packet.md",
  "owner": "Darin"
}

Finish line: one JSON record with a job ID, a per-source status list, at least one error entry, a pending-review pointer, and an output path.

Verify: simulate a crash after source 2. Load your record and answer: which sources can be skipped, which must be retried, and where does the partial output live? If you cannot answer from the record alone, add the missing field.

Common failure: storing a transcript ("the model said…") instead of statuses. State records facts a program can act on — done, pending, failed, retry count — not narration.

Next, you assemble the pieces into the smallest loop that can actually run.