Build an Agent Filesystem

Builder procedure

Use this track when you are implementing filesystem capabilities for agents. The For Agents handbook tells agents how to use a FILESYSTEM.md workspace; this track tells engineers how to provide the FS interface underneath.

Read order

1. This hub (stack mental model)
2. Virtual FS — path API as the agent-facing contract
3. Tool layer — list / read / write / grep / bash bindings
4. Sandbox — isolation, scopes, resets
5. Composite backend — route /docs, /memories, /workspace to different stores

Stack model

┌─────────────────────────────────────────┐
│  FILESYSTEM.md workspace contract       │  ← what agents MUST follow
│  (bootstrap, MEMORY/, SKILLS/, LOGS/)   │
├─────────────────────────────────────────┤
│  Tool layer (list/read/write/grep/bash) │  ← what agents CALL
├─────────────────────────────────────────┤
│  Virtual FS API (path → bytes/meta)     │  ← stable interface
├─────────────────────────────────────────┤
│  Sandbox / permission boundary          │  ← safety envelope
├─────────────────────────────────────────┤
│  Backends: local | SQLite | S3 | Box…   │  ← interchangeable storage
└─────────────────────────────────────────┘

Design goals (SHOULD)

• Preserve POSIX-like path semantics agents already know
• Keep the tool surface small and auditable
• Make backends swappable without rewriting agent prompts
• Enforce workspace boundaries in code, not only in markdown

Manual index

Human notes

FILESYSTEM.md does not require you to invent a new kernel filesystem. Most agent products expose a virtual filesystem (or sandbox mount) plus tools. Industry references: Why Filesystems, Box composite FS, Vercel filesystem agents, Amplify on FS for agents.

For kernel/FUSE/cloud mounts, see the Infrastructure track.