The State File - Memory That Lasts
The agent forgets everything between runs. A simple file that remembers is the quiet backbone of every loop that actually works
The Simplest Idea That Matters Most
This piece sounds almost too dumb to be important: a loop needs a memory file. A place outside the conversation that records what's done, what's in progress, and what's next. That's it. Yet it's the structural backbone of every production loop - leave it out and the loop falls apart.
Remember the goldfish problem from Lesson 59? Agents forget everything between runs. A loop without a memory file restarts its entire mental model from zero every single time. A loop with one picks up exactly where it left off.
What a State File Looks Like
It can be a Markdown file, a JSON file, or even a board in a tool like Linear. The format doesn't matter; the persistence does. Here's a JSON example for a CI-triage loop:
{
"loop_id": "ci-triage",
"last_run": "2026-06-15T03:30:00Z",
"status": {
"failures_classified": 7,
"fixes_drafted": 3,
"escalated_to_humans": 4
},
"in_progress": [
{ "branch": "fix-auth-refresh", "status": "awaiting_ci" }
],
"lessons_learned": [
"Windows runner hits TLS issues; fall back to bash.",
"Checkout tests need the stripe webhook secret; skip if missing."
]
}lessons_learned. That's the loop getting smarter over time - recording the gotchas it hit so future runs don't repeat them. A state file isn't just a to-do list; it's the loop's growing experience.What the Memory Buys You
Tomorrow's run reads the file and continues from where today stopped - no wasted effort re-doing finished work.
If a run crashes or you stop it, nothing is lost. The state on disk is the truth, not the conversation that vanished.
You can open the file any time and see exactly what the loop tried, what passed, and what's still open. No mystery.
Forcing the loop to re-read a base file each cycle keeps it anchored to the real goal - a trick we'll lean on hard in the next lesson to prevent "drift."
Where to Keep It
IN-REPO MARKDOWN (STATE.md at your project root) ✓ version-controlled, visible, dead simple ✓ best for solo devs and small, tight teams EXTERNAL SYSTEM (a database, or a Linear board) ✓ survives across multiple repos ✓ gives a whole team shared visibility ✓ best for bigger, cross-team loops
STATE.md. A plain Markdown file in your project root is enough for your first loop. You can graduate to fancier storage later if the loop grows up.Hands-On: Create Your STATE.md
STATE.md for your candidate loop. Give it four sections: Last run (a date), Done (what's finished), In progress (what's mid-flight), and Lessons learned (gotchas to remember). Fill in a realistic first entry as if the loop just ran once. This file is a required piece of your capstone - and in the capstone's interactive helper, you'll get a starter version generated for you automatically.A persistent memory (Markdown/JSON/Linear) outside the conversation that records done, in-progress, and next
Memory must live on disk because the agent loses context between runs
Recording gotchas so the loop gets smarter over time instead of repeating mistakes
A state file lets each run continue where the last stopped, surviving crashes and stops
A simple in-repo Markdown file - the right starting point for your first loop
Databases or Linear boards for loops that span repos or need team-wide visibility