## Description
Add a new workspace filesystem provider backed by AgentFS, which stores
files in a Turso/SQLite database via the agentfs-sdk. This gives Mastra
agents persistent, database-backed file storage that survives across
sessions — an alternative to the existing local and S3 filesystem
providers.
The provider implements the full WorkspaceFilesystem interface:
- File operations: read, write, append, delete, copy, move
- Directory operations: mkdir, rmdir, readdir (with recursive support)
- Path operations: exists, stat
- Read-only mode enforcement
- Automatic parent directory creation on write
- Error mapping from AgentFS/POSIX codes to Mastra workspace errors
Package: @mastra/agentfs (workspaces/agentfs/)
- Peer dependency on @mastra/core >=1.4.0
- Uses agentfs-sdk ^0.6.0
- Supports three initialization modes: agentId, explicit path, or
pre-opened AgentFS instance
Also includes an example project (examples/agentfs-workspace/) with:
- A standalone filesystem demo exercising all operations
- An agent demo showing workspace tools auto-injected into an agent
Mostly generated with Claude Code, with some minor manual touch-ups.
## Type of Change
New feature (non-breaking change that adds functionality)
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added AgentFSFilesystem workspace provider for persistent,
database-backed file storage (Turso/SQLite).
* Added example workspace with runnable demos showcasing filesystem
operations and agent integration.
* **Documentation**
* Added comprehensive provider reference, usage examples, and sidebar
entry.
* Added README and changelog entries for the new provider.
* **Tests**
* Added unit and integration tests validating filesystem behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: NikAiyer <nick.aiyer@gmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>
Co-authored-by: Lennart <lekoarts@gmail.com>