AgentFS

The filesystem for agents.

---

⚠️ Warning: This software is ALPHA; use only for development, testing, and experimentation. We are working to make it production-ready, but do not use it for critical data until it is ready.

🎯 What is AgentFS?

AgentFS is a filesystem explicitly designed for AI agents. Just as traditional filesystems provide file and directory abstractions for applications, AgentFS provides the storage abstractions that AI agents need.

AgentFS provides four components:

• SDK - TypeScript and Rust libraries for programmatic filesystem access
• CLI - Command-line interface for managing agent filesystems
• Specification - SQLite-based agent filesystem specification
• Sandbox - Linux-compatible execution environment with agent filesystem support (experimental)

Read more about the motivation for AgentFS in the announcement blog post.

🧑‍💻 Getting Started

Using the CLI

Initialize an agent filesystem:

$ agentfs init
Created agent filesystem: agent.db

Inspect the agent filesystem from outside:

$ agentfs fs ls
f hello.txt

$ agentfs fs cat hello.txt
hello from agent

You can also run a program in an experimental sandbox with the agent filesystem mounted at /agent:

$ agentfs run /bin/bash
Welcome to AgentFS!

$ echo "hello from agent" > /agent/hello.txt
$ cat /agent/hello.txt
hello from agent
$ exit

Read the User Manual for complete documentation.

Using the SDK

Install the SDK in your project:

npm install agentfs-sdk

Use it in your agent code:

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: [...] }
);

Examples

AgentFS includes examples demonstrating integration with popular AI frameworks:

• Mastra - Research assistant using the Mastra AI framework
• Claude Agent SDK - Research assistant using Anthropic's Claude Agent SDK

See the examples directory for more details.

💡 Why AgentFS?

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.

Reproducibility: Snapshot an agent's state at any point with cp agent.db snapshot.db. Restore it later to reproduce exact execution states, test what-if scenarios, or roll back mistakes.

Portability: The entire agent runtime—files, state, history —is stored in a single SQLite file. Move it between machines, check it into version control, or deploy it to any system where Turso runs.

Simplicity: No configuration files, no database servers, no distributed systems. Just a single file and a simple API.

Sandboxing: Run agents in an isolated Linux environment where filesystem access is controlled and monitored. Perfect for testing untrusted code or enforcing security policies.

🔧 How AgentFS Works?

AgentFS is an agent filesystem accessible through an SDK that provides three essential interfaces for agent state management:

• Filesystem: A POSIX-like filesystem for files and directories
• Key-Value: A key-value store for agent state and context
• Toolcall: A toolcall audit trail for debugging and analysis

At the heart of AgentFS is the agent filesystem, a complete SQLite-based storage system for agents implemented using Turso. 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.

📚 Learn More

• User Manual - Complete guide to using the AgentFS CLI and SDK
• Agent Filesystem Specification - Technical specification of the agent filesystem SQLite schema
• SDK Examples - Working code examples using AgentFS
• Turso database - an in-process SQL database, compatible with SQLite.

📝 License

MIT