Answer
How should persistent work state be stored?
In plain files, in the project, under version control. A database is more capable and nobody can read it during an incident.
Plain text files in the project, under version control. The requirement is that a person can read and correct the state during an incident, which rules out anything needing a client or a query to inspect.
The instinct is that state belongs in a store designed for state: a database, a key-value service, a queue. Those are the right answer for a system with many concurrent participants and high throughput, and they are the wrong answer for agent work, which has neither. What agent work has instead is a requirement that is unusual: the state must be legible and editable by a person at the exact moment something has gone wrong.
That requirement rules out most of the sophisticated options. During an incident, a plain file can be opened, read, understood and corrected in seconds by whoever is present. A database row requires a client, a connection and a query, and the person available may be able to do none of those. This is not a hypothetical convenience — the value of state is realised almost entirely at the moment of failure.
Version control adds three properties that matter here. The history, so a state that has become wrong can be compared with what it was. Attribution, so it is possible to see what changed it. And a merge story, so two things writing the same state produce a visible conflict rather than a silent overwrite. None of these is available in a file sitting on a machine, and all of them cost nothing extra when the state lives in the project.
The state should be in the project rather than beside it. Work state that lives somewhere central and separate becomes detached from the code, the plan and the artefacts it describes, and it goes stale in a way nobody notices because nothing brings the two together. Keeping it in the repository means it moves with the work and is present whenever the work is.
Two structural points. Append rather than overwrite wherever the history has value, particularly for decisions, because the current-state view can be derived from an append-only record and the reverse is not true. And keep the state small enough to read in full: a state file that has grown beyond a page has become a log, and a log is a different artefact serving a different purpose.
One genuine exception. Where several runs genuinely operate concurrently on shared state, files are the wrong mechanism and something with real locking is required. That situation is rarer than it looks, and the first question is usually whether the concurrency is necessary rather than how to support it, because concurrent writes to shared state is the arrangement that produces the least debuggable failures.
State that requires a tool to read is state nobody will look at when it matters, which is the only time anyone looks.
Siddharth Sharma, Context Theory
Related questions
What format should the file use?
Whatever is readable by a person and parseable if something needs to read it, which in practice means structured text with obvious keys. The format matters far less than the size and the location, and choosing a format is the part of this decision that consumes the most discussion and affects the least.
Should the agent be allowed to write the state file?
Yes, and it should not be the only writer, because a state file that only a system maintains is one a person cannot correct without fighting it. The arrangement that works is that the file is ordinary — a person edits it when needed, and the next run reads whatever is there.
METHOD
Every figure below carries its source and the date it was verified. Nothing on this page is asserted.
The numbers on this page.
| What | Value | Specific to |
|---|---|---|
| Sub-15-minute compliance — automated routing vs manual only | 62.5% vs 39.1% | Category-wide |
| Firms that never responded to a web enquiry at all | 23% | Category-wide |
2026 speed-to-lead benchmark · verified
Oldroyd, McElheran & Elkington, "The Short Life of Online Sales Leads", Harvard Business Review (March 2011) · 1.25M inbound leads across 2,241 US firms · verified
What is specific to this page.
| Kind | Claim | Check it against |
|---|---|---|
| Software | The defining requirement for agent work state is legibility and editability by a person at the moment of failure, which rules out stores requiring a client, a connection or a query to inspect. | Attempting to read and correct the current work state during a simulated incident with only the tools present on the machine. |
| Workflow | Version control supplies history for comparing a corrupted state against its previous form, attribution for what changed it, and visible conflicts instead of silent overwrites, none of which a loose file on a machine provides. | Comparing recovery options for a wrong state value under version control and without it. |
| Response | State stored centrally and separately from the work becomes detached from the code, plan and artefacts it describes and goes stale without any mechanism bringing the two together. | Checking whether an existing central state store matches the current condition of the work it describes. |
| Constraint | A current-state view is derivable from an append-only record while the reverse is not, which makes appending the correct default wherever the history carries value, particularly for decisions. | Attempting to reconstruct the sequence of decisions from a file that has been overwritten at each change. |
Each row would be wrong on another industry's page. Where a sourced figure exists it is in the table above instead; these are the constraints that shape the work and do not happen to be numbers.
Start with the measurement.
Reading about a benchmark is not the same as knowing your own number. The audit produces yours, measured rather than estimated.
$497 · delivered in 5 business days · credited against month one