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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/tursodatabase-agentfs
Generated for open source discovery and AI-assisted research.

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.

GitHub: https://github.com/tursodatabase/agentfs
OSRepos URL: https://osrepos.com/repo/tursodatabase-agentfs

## 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.

## Topics

- agents
- filesystem
- sqlite
- turso
- Rust
- AI
- Database
- Open Source

## Repository Information

Last analyzed by OSRepos: Sat Sep 05 2026 21:29:51 GMT+0100 (Western European Summer Time)
Detail views: 2
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:
bash
curl -fsSL https://agentfs.ai/install | bash

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

Inspect and interact with the filesystem:
bash
$ 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):
bash
$ agentfs mount my-agent ./mnt


### Using the SDK
Install the SDK in your project (e.g., for TypeScript):
bash
npm install agentfs-sdk

Then, use it in your agent code:
typescript
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](https://github.com/tursodatabase/agentfs/tree/main/examples).

## Links
*   **User Manual**: A comprehensive guide to the AgentFS CLI and SDK. [MANUAL.md](https://github.com/tursodatabase/agentfs/blob/main/MANUAL.md)
*   **Agent Filesystem Specification**: Technical details of the SQLite schema. [SPEC.md](https://github.com/tursodatabase/agentfs/blob/main/SPEC.md)
*   **SDK Examples**: Working code examples for various integrations. [examples/](https://github.com/tursodatabase/agentfs/tree/main/examples)
*   **Turso Database**: The underlying in-process SQL database compatible with SQLite. [https://github.com/tursodatabase/turso](https://github.com/tursodatabase/turso)
*   **Introducing AgentFS**: Learn about the motivation behind AgentFS. [https://turso.tech/blog/agentfs](https://turso.tech/blog/agentfs)
*   **AgentFS with FUSE**: Details on mounting agent filesystems. [https://turso.tech/blog/agentfs-fuse](https://turso.tech/blog/agentfs-fuse)
*   **AgentFS in the Browser**: Running AgentFS with WebAssembly. [https://turso.tech/blog/agentfs_browser](https://turso.tech/blog/agentfs_browser)