Portable Agent State with AgentFS: A Proof of Concept

(Written by Claude Opus 4.5 under the direction of Oskar Austegard)

AgentFS is a SQLite-based filesystem designed for AI agents, developed by Turso. The core idea: store all agent state—files, key-value data, tool call history—in a single portable database file. I tested whether this could enable continuity between local development and cloud-based AI environments like Claude's computer use sandbox.

Short answer: it works, with caveats.

What AgentFS Provides

AgentFS offers three storage abstractions in one SQLite file:

• Filesystem: POSIX-like file operations (read, write, mkdir, etc.)
• Key-Value Store: JSON-serialized state storage
• Tool Call Tracking: Audit trail of tool invocations with timing and error data

On Linux (and macOS with macFUSE), you can mount the database as a real filesystem via FUSE, letting agents use standard Unix tools like git, grep, and diff without SDK integration. See AgentFS with FUSE for details.

The motivation is explained in The Missing Abstraction for AI Agents: agents need auditability, reproducibility, and portability. A single queryable SQLite file delivers all three.

The Portability Question

Could you use AgentFS to maintain state across sessions in a sandboxed AI environment? Specifically:

1. Work locally (via FUSE mount or SDK)
2. Upload the .db file to Claude's environment
3. Have Claude read/modify the state
4. Download the updated database
5. Continue locally

The Test

I installed the AgentFS npm SDK in Claude's computer use environment and ran through the core operations:

npm install agentfs-sdk

Then created a test database with:

• KV entries: project config, session context
• Files: README.md, Python source, data notes
• Tool calls: simulated web_search, code_execution, and a failed file_read

All SDK operations worked:

=== Key-Value Store ===
project:name: My Portable Project
project:config: {"version":"1.0.0","lastModified":"2025-12-16T15:10:52.139Z"...}

=== Filesystem ===
Root directory contents: README.md, data, src
/src contents: analysis.py

=== Tool Call History ===
code_execution: 1 calls, 1 succeeded, avg 2000ms
file_read: 1 calls, 0 succeeded, avg 200ms
web_search: 1 calls, 1 succeeded, avg 1500ms

The database file was created, populated, and readable. Roundtrip verified.

The WAL Gotcha

SQLite uses Write-Ahead Logging by default. The actual data lives in .db-wal until checkpointed. If you only copy the .db file, you get an empty database.

For portable copies, you need both files:

test-agent.db      (4KB - schema only)
test-agent.db-wal  (709KB - actual data)

Or force a checkpoint before copying (the SDK doesn't expose this directly, so you'd need raw SQL access or to close and reopen the database).

What Works

• SDK installs and runs in Claude's Node.js environment
• All three APIs (KV, filesystem, tool calls) function correctly
• Database files can be uploaded, modified, and downloaded
• State persists across the roundtrip

What Doesn't (or Might Not)

• FUSE mounting: Almost certainly won't work in containerized AI environments—requires kernel module access
• Large files: The 709KB WAL for a few small files suggests overhead. Large binary files may be impractical
• Concurrent access: No testing of multi-agent or concurrent modification scenarios
• Session reliability: Depends on the AI environment's file handling; no guarantees the sandbox preserves state between tool calls in edge cases

Practical Use Cases

This pattern could be useful for:

• Iterative projects: Upload context at session start, download state at end, continue later
• Debugging agent behavior: Query the tool_calls table to see what an agent actually did
• Snapshotting: Copy the db file to create restore points (cp agent.db agent-checkpoint.db)
• Local development with cloud execution: Develop locally with FUSE mount, upload for cloud agent runs

It's probably not useful for:

• High-frequency state synchronization
• Large binary asset storage
• Anything requiring real-time collaboration
• Production systems (the project is explicitly Alpha)

Implementation Sketch for Skills

A Claude skill using AgentFS for portable state might look like:

// At session start
import { AgentFS } from 'agentfs-sdk';

const dbPath = '/mnt/user-data/uploads/project-state.db';
const agent = await AgentFS.open({ path: dbPath });

// Read prior context
const context = await agent.kv.get('session:context');
const lastFile = await agent.kv.get('session:lastFile');

// Do work...
await agent.fs.writeFile('/output/result.txt', output);
await agent.kv.set('session:lastFile', '/output/result.txt');

// Record tool usage
await agent.tools.record('analysis', startTime, endTime, params, result);

await agent.close();

// Copy to outputs (remember the WAL!)
// User downloads both files

Conclusion

AgentFS works as advertised in Claude's environment. The SDK is functional, the database is portable, and the abstraction makes sense. Whether it's useful depends on your workflow—if you're already doing multi-session agent work and want queryable state history, it's worth trying.

The project is Alpha software. Don't use it for anything you can't afford to lose.

Links

• GitHub: tursodatabase/agentfs (Alpha)
• User Manual
• Blog: The Missing Abstraction for AI Agents
• Blog: AgentFS with FUSE