How File-Based Architecture Makes AI Agents Debuggable

When an AI agent does something wrong — and it will — you need to answer two questions fast: what happened, and why? If your agent state lives in a database, the answer requires a SQL client, the right query, and knowledge of the schema. If it lives in an API, you need auth tokens, endpoint documentation, and a way to correlate events across services. If it lives in files, the answer is ls and cat. The Debugging Tax Every layer of abstraction between you and the agent's state is a debugging tax. Each layer adds latency to your investigation: Architecture To see what happened Time to first insight Database (SQLite/Postgres) Open client, write query, parse results 2-5 minutes API-based state Authenticate, find endpoint, decode response 3-10 minutes File-based state ls .batty/inboxes/eng-1-1/new/ 5 seconds At 2am when an agent has been looping for an hour, those minutes matter. File-based state gives you instant visibility with tools you already know. What File-Based Looks Like Batty stor