Files vs SQLite — Choosing the Right Data Layer

Rule

Agent-native apps use two data layers: files for content and configuration, SQLite for structured application data. Choose the right one based on what you're storing.

When to Use Files

Store data as files in data/ (JSON, markdown, images) when:

• Content — markdown documents, drafts, articles, slide decks
• Settings/Configuration — app settings, user preferences, sync config
• Application state — ephemeral UI state in application-state/ (compose windows, search state)
• Media — images, uploads, generated assets
• Data the agent edits directly — the agent can read/write files on the filesystem without going through an API

Files are the shared interface between the AI agent and the UI. The agent reads and writes files directly. The UI reads files via API routes. SSE streams file changes back to the UI in real-time.

How (Files)