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 sto