The Missing Abstraction for AI Agents: The Agent Filesystem

As more and more developers build AI agents and autonomous systems, often in sandboxed environments, one challenge stands out: how do you effectively manage agent state while maintaining trust and auditability? The unpredictable nature of AI agents makes this particularly challenging, which is why you really want visibility into every decision, every file created, and every state change. While you can restrict what an agent can do (and need to do so in many cases), it's often a good strategy to allow the agent to do what it needs to do, as long as you can capture its state, audit the state, and iterate on it.

A SQLite database, itself being just a file, is perfect for capturing agent state. But after talking agent developers, we found that people preferred to consume SQLite at a higher level of abstraction. That's why we've built AgentFS SDK, an agent filesystem abstraction. AgentFS provides a unified interface for agents to manage all their state in a single SQLite database, making it queryable via SQL, portable across environments, and fully auditable. Instead of cobbling together databases, logging systems, and file storage, you get everything in one place: a POSIX-like filesystem for artifacts, a key-value store for agent state, and automatic tool call tracking for complete observability.

With AgentFS, you can snapshot an agent's entire runtime by copying a single file, debug complex behaviors with SQL queries, and reproduce exact execution states for testing. It's the missing piece that lets you handle the data challenges in your agent sandboxes.

#The Problem: Managing Unpredictable AI Systems

At their core, autonomous systems like AI agents are inherently unpredictable. Their decision-making process, which involves intricate chains of reasoning and interaction with the environment, can lead to unforeseen outcomes. While you can impose restrictions on their actions, what you actually need is visibility into their operations when they deviate from the expected path.

This visibility into agent operations is critical for various reasons beyond development and debugging to understand why an agent made a specific decision. For example, you need observability for:

Regulatory compliance: Meeting audit requirements for AI-driven processes
Accountability: Having a clear record when agents make costly mistakes
Continuous improvement: Analyzing past behavior to refine future performance
Reproducibility: Recreating exact conditions for testing and validation

However, many traditional approaches fall short because they involve cobbling together multiple tools: databases for state storage, logging systems for audit trails, traditional local file systems for artifacts, and version control for history. This fragmentation of the state not only creates complexity but also leaves gaps in observability. Furthermore, local filesystems themselves can have their own problems: often, some sandboxing environments don’t have one, and when they do, operating persistent volumes at scale is nobody’s idea of fun.

#The Agent Filesystem Abstraction

To solve the problem of agent observability, the developers we talked to consistently made the same point: they want a filesystem abstraction specifically designed for agents. The following requirements kept emerging:

Queryability: Finding specific state transitions or decision points quickly
Versioning: Understanding how the state evolved over time
Portability: Moving state between environments seamlessly
Durability: Ensuring the state survives crashes and restarts

Interestingly, developers kept mentioning that SQLite seemed like the perfect fit for this agent filesystem, but it wasn't clear how to effectively leverage it for agent-specific needs. Therefore, we build AgentFS, an SDK built on top of Turso (a SQLite-compatible database) that provides a comprehensive filesystem abstraction for AI agents.

#Architecture: SQLite as the Foundation

AgentFS SDK provides three essential interfaces for agents:

Filesystem: a POSIX-like virtual filesystem for files and directories
Key-value: a key-value store for agent state and context
Toolcall: an audit trail tool for debugging and analysis.

AgentFS at its heart is an agent-specific filesystem implemented on top of SQLite database. Everything an agent does — every file it creates, every piece of state it stores, every tool it invokes — lives in a single SQLite database file, as illustrated by Figure 1.

This design choice brings several advantages:

Single file simplicity: The entire agent runtime—files, state, history—is stored in a single SQLite file. You can move it between machines, check it into version control, or deploy it anywhere.
Built-in auditability: Every file operation, tool call, and state change is recorded in SQLite. Query your agent's complete history with SQL to debug issues, analyze behavior, or meet compliance requirements.
Instant reproducibility: Snapshot an agent's state at any point by making a copy of the SQLite database file. Restore it later to reproduce exact execution states, test what-if scenarios, or roll back mistakes.
SQL-powered analysis: Since everything is in SQLite, you can use standard SQL queries to analyze agent behavior, extract metrics, or build custom observability tools.

The AgentFS SDK consists of two parts: state capture and state management. State capture provides the SDK interfaces that agents use to interact with the system. State management implements the agent filesysystem specification, which defines a SQLite schema for agent filesystems, using the Turso database.

#Capturing agent state

When the agent performs operations, we need to capture them for later analysis. For example, you might want to capture:

Decision trees and reasoning paths - The logic behind each action
Intermediate computations - Results that inform future decisions
External API responses - Data retrieved from other systems
User interactions - Commands, feedback, and corrections
Error states and recovery attempts - What went wrong and how the agent responded
File operations - Every read, write, and modification
Configuration changes - How agent settings evolved over time

You perform state capture using the AgentFS SDK. The more comprehensive state capture you do, the deeper your introspection into agent behavior becomes, making debugging and improvement much more systematic. The AgentFS project also includes a highly experimental sandbox for automatically capturing state, aimed at agent infrastructure builders.

#Storing agent state

The storage layout in SQLite files is defined by the agent filesystem specification. The schema consists of multiple tables, providing efficient storage for files, key-value pairs, and toolcall audit.

Filesystem storage operates with two main SQLite tables for file organization: the inode table and the dentry table. The dentry (directory entry) table is responsible for storing file and directory paths. It essentially keeps track of what everything is called and where it's located in the folder structure. This table is kept separate as it also acts as a cache for faster lookups. The inode table, however, is the key player in the storage of the actual file contents and metadata, such as size, permissions, and timestamps. Each file has an inode that contains its data and properties. In short, dentries manage the names and organization, while inodes handle the actual content and file information, similar to what an operating system kernel does.

The other two interfaces, key-value and toolcall audit log, are straightforward. Key-value storage consists of a single SQLite table that maps each key to its JSON-serialized value. The toolcall audit log is represented as a single append-only table. In other words, unlike filesystem and key-value storage tables, the toolcall table rows are never mutated; only new rows are inserted. This ensures auditability in case the agent does something unexpected.

#The AgentFS SDK

The AgentFS SDK provides programmatic access to all agent filesystem features through a familiar API.

If you're using TypeScript or JavaScript, you can install the SDK in your project:

npm install agentfs-sdk

For Rust projects, run:

cargo add agentfs-sdk

The SDK provides interfaces for the different types of state. For example, you would use the TypeScript SDK in your agent code as follows:

import { AgentFS } from 'agentfs-sdk';

const agent = await AgentFS.open('./agent.db');

// Key-value operations
await agent.kv.set('user:preferences', { theme: 'dark' });
const prefs = await agent.kv.get('user:preferences');

// Filesystem operations
await agent.fs.writeFile('/output/report.pdf', pdfBuffer);
const files = await agent.fs.readdir('/output');

// Tool call tracking
await agent.tools.record(
  'web_search',
  Date.now() / 1000,
  Date.now() / 1000 + 1.5,
  { query: 'AI' },
  { results: [...] }
);

In other words, you first use the AgentFS.open method to open a SQLite database file using Turso, and then use the different interfaces, filesystem, key-value, and toolcalls from the AgentFS object.

#Example: Research Assistant Agent

To demonstrate AgentFS in action, we built a research assistant agent that answers questions about database research. The agent searches through papers from top-tier database conferences (VLDB and SIGMOD) to provide informed, research-backed answers.

Built with the Mastra AI agent framework, the research assistant follows a straightforward workflow:

Search for relevant papers - Queries Semantic Scholar's API to find papers matching the research question
Download and extract content - Fetches PDFs of relevant papers and extracts their text
Persist to filesystem - Stores paper contents in AgentFS for efficient retrieval and caching
Generate targeted summaries - Analyzes the stored papers and synthesizes an answer specific to the original research question

This example showcases how AgentFS handles real-world agent tasks: managing downloaded files, caching processed content, and maintaining state across multiple operations. The filesystem abstraction makes it simple to store and retrieve research papers without worrying about the underlying storage implementation.

You can find the complete source code for the example on Github.

#Summary

The agent filesystem abstraction addresses a fundamental challenge in AI agent development: managing state in unpredictable, autonomous systems. By building on top of SQLite, instead of scattered files and ad-hoc solutions, you get:

Everything in one SQLite file
Snapshotting and versioning for free
SQL queries for debugging and analysis
Easy reproducibility for testing and development

The power of the agent filesystem is its simplicity — everything in one place, queryable with SQL, portable as a single file. Treat agent state like a filesystem, but implement it as a database. This gives you the simplicity of files with the power of structured data. It's particularly useful when your agents need to maintain complex state across runs, coordinate with other agents, or when you need to debug what went wrong in production.

To try it out, check out AgentFS on GitHub and start building more observable AI systems that you can trust today.