AgentFS: The Filesystem Designed for AI Agents and Their State Management

Summary

AgentFS is an innovative filesystem specifically engineered for AI agents, providing robust storage abstractions. It leverages SQLite to offer auditability, reproducibility, and portability for agent states, tool calls, and file operations. This solution simplifies debugging, analysis, and deployment of AI agents by encapsulating their entire runtime into a single, queryable database file.

Use at your own risk

OSRepos shares public repositories for knowledge and discovery only. Any installation, execution, configuration, or use of code from these repositories is the user's own responsibility. Always review the repository, source code, dependencies, licenses, and security implications before running or installing anything. OSRepos is not responsible for issues, damages, or losses resulting from third-party repositories.

Introduction

AgentFS is a specialized filesystem designed explicitly for AI agents, offering the necessary storage abstractions for their operations. It comprises an SDK for programmatic access in TypeScript, Python, and Rust, a CLI for managing agent filesystems, and a SQLite-based specification. This project aims to provide a structured and auditable environment for agent state management.

Why Use and Benefits

AgentFS offers significant advantages for managing agent state:

Auditability: Every file operation, tool call, and state change is recorded in a SQLite database, allowing you to query your agent's complete history for debugging, analysis, or compliance.
Reproducibility: You can snapshot an agent's state at any point and restore it later to reproduce exact execution states, test scenarios, or roll back mistakes.
Portability: The entire agent runtime, including files, state, and history, is stored in a single SQLite file, making it easy to move between machines, check into version control, or deploy.

AgentFS differs from other solutions by operating at the filesystem layer, providing unique capabilities. Unlike Bubblewrap, it offers persistence and queryability of the upper filesystem. It complements Docker Sandboxes by focusing on structured state management and audit trails within a secure environment. Compared to Git worktrees, AgentFS provides system-wide, enforced copy-on-write isolation, handling untracked files and ensuring safety for untrusted agents. The choice of the filesystem layer, backed by SQLite and Turso, enables queryable data, snapshotting, time-travel forking, and SDK support in diverse environments like serverless or browsers.

Installation

Using the CLI

Install the AgentFS CLI with a simple curl command:

curl -fsSL https://agentfs.ai/install | bash

Initialize an agent filesystem:

$ agentfs init my-agent
Created agent filesystem: .agentfs/my-agent.db
Agent ID: my-agent

Inspect and interact with the filesystem:

$ agentfs fs my-agent ls
Using agent: my-agent
f hello.txt

$ agentfs fs my-agent cat hello.txt
hello from agent

You can also mount an agent filesystem using FUSE (Linux) or NFS (macOS):

$ agentfs mount my-agent ./mnt

Using the SDK

Install the SDK in your project (e.g., for TypeScript):

npm install agentfs-sdk

Then, use it in your agent code:

import { AgentFS } from 'agentfs-sdk';

// Persistent storage with identifier
const agent = await AgentFS.open({ id: 'my-agent' });

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

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

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

Examples

The AgentFS repository includes various examples demonstrating integration with popular AI frameworks. These include research assistants built with Mastra, Anthropic's Claude Agent SDK, and OpenAI Agents. Other examples showcase usage with Firecracker VMs, Vercel AI SDK, and Cloudflare Workers. You can explore these in the examples directory.