Give Your AI Agent a Virtual Filesystem with Multiple Storage Backends

Every agent you build has the same problem: it needs to pull data from cloud storage, query a database, and write files to disk. Normally that means wiring up three different integrations with three different APIs. The virtual filesystem pattern collapses all of that into a single abstraction the agent already understands: folders and files.

The Core Idea

You give your agent one filesystem interface, but behind the scenes each path routes to a completely different storage backend. The agent calls standard filesystem operations like listFiles, readFile, and writeFile. It has no idea whether it is talking to S3, SQLite, or local disk.

Diagram showing one agent connected to one filesystem that branches to S3 and Local Disk backends

In the example shown, a sales assistant agent gets access to three paths:

/docs/ routes to an S3 bucket containing company documentation, pricing strategies, and product info.
/memories/ routes to a SQLite database storing customer profiles and conversation history.
/workspace/ routes to the local filesystem where the agent writes its final output.

Building the Composite Backend

The implementation starts with a function called createCompositeBackend. Inside it, you create three separate backend instances:

A FilesystemBackend pointing to your workspace directory
A SQLiteBackend connected to your database file
An S3Backend wired up to your cloud bucket

Code showing the three backend instantiations: FilesystemBackend, SQLiteBackend, and S3Backend with their configurations

Then you wrap them all inside a CompositeBackend and map each path to the right backend:

Code showing CompositeBackend mapping /workspace/ to workspaceBackend, /memories/ to sqliteBackend, and /docs/ to s3Backend

Virtual Files from Database Queries

The most interesting trick is how the SQLite backend handles file listings. When the agent lists files in /memories/users/, the backend runs a SQL query, pulls every user from the table, and generates JSON files on the fly. Those files do not actually exist anywhere on disk. They are synthesized from the database at read time.

Code showing the virtual file structure where /memories/users/{name}.json maps to SELECT * FROM users, and the listFiles function that queries the database and returns file objects

The same pattern works for conversation history. A request for /memories/history/{name}.md triggers a JOIN query across users and conversations, then formats the result as markdown. The agent reads it like a normal file.

Putting It Together

Once the composite backend is built, you call createDeepAgent, passing in your model, the composite backend, a checkpointer for memory, and a system prompt that tells the agent what lives where.

When you run it, the agent browses company docs from S3, reads customer profiles from SQLite, and writes a fully personalized sales proposal to your local workspace folder. The agent never needs to know anything about the underlying storage. It just reads and writes files.

Key Takeaways

A virtual filesystem lets agents use standard file operations against any storage backend (S3, SQLite, local disk)
The composite backend pattern routes different paths to different storage systems transparently
Database records can be synthesized into virtual files at read time, so agents interact with structured data as if it were a folder of documents