The short answer
AI agents already understand filesystems. Training corpora are full of ls, cat, grep, path navigation, and incremental edits. When you give an agent a navigable tree of files instead of a stuffed prompt or an opaque retrieval blob, you get:
- Precise retrieval (
grep, path lookup) instead of approximate similarity - On-demand context (load only what the task needs)
- Debuggable execution (you can see which files were read and written)
- A stable interface that can sit on local disk, sandbox FS, SQLite-backed virtual files, S3, or enterprise content platforms
FILESYSTEM.md does not invent “filesystems for agents.” It standardizes the workspace contract on top of that emerging consensus: which files bootstrap the agent, what is loaded on demand, where memory and logs live, and how behavior files map across harnesses.
What the industry is converging on
Three recent pieces capture complementary layers of the same idea:
| Source | Core claim | Layer |
|---|---|---|
| Amplify Partners — File systems for agents | Agents need FS-like interfaces more than OLTP/object-store semantics; today’s POSIX FS may need evolution for agent-scale concurrency | Infrastructure & storage thesis |
| Vercel Academy — Building Filesystem Agents | Structure domain data as files, give the agent bash, keep context minimal and debuggable | Application pattern / how to build |
| Box — Filesystems as the context layer | A filesystem is an interface contract; backends can be Box, SQLite, local disk via a composite FS | Enterprise context layer / backends |
Related foundations (still essential reading):
- Vercel — How to build agents with filesystems and bash
- LangChain — How agents can use filesystems for context engineering
- Manus — Context Engineering for AI Agents
Why not “just put everything in the prompt”?
Prompt stuffing fails as soon as workflows become multi-step:
- Token budgets collapse under large transcripts, repos, or document sets
- Ordering and provenance get fuzzy
- Failures are hard to audit (“what did the model actually see?”)
Filesystem agents invert this: metadata and paths first, full content only when needed.
Why not vector search alone?
Vector retrieval is strong for semantic “find something like X.” It is weak when you need:
- An exact string, clause, or config value
- Deterministic re-reads of the same artifact
- Structured hierarchies (customer → tickets → calls)
Filesystem operations (grep, cat path/to/file) return exact results. Many production systems combine both: vectors as an index, files as the source of truth.
Why not OLTP databases or object stores as the primary agent interface?
Amplify’s analysis is a useful map:
- OLTP databases excel at typed rows, transactions, and joins. Most agent artifacts are irregular documents, code, logs, and drafts — schemas and row APIs add friction.
- Object stores excel at large durable blobs. Agents often need many small, frequently updated files with hierarchical navigation and append-friendly workflows.
You can emulate a filesystem on top of either. At that point the agent-facing contract is still “files and paths.” FILESYSTEM.md assumes that contract and standardizes the project layout and bootstrap rules agents should follow.
Filesystem as interface, not “only local disk”
Box’s framing matters for production: the agent sees one tree (/docs, /memories, /workspace), while backends differ. LangChain Deep Agents–style composite backends make the same point — SQLite rows can surface as virtual files; cloud storage can back /docs/ without changing agent tools.
Implications for FILESYSTEM.md:
MEMORY/,SKILLS/,PROJECTS/, andLOGS/are logical directories- Implementations MAY map them to local disk, sandbox FS, or remote backends
- The MUST/SHOULD rules are about what the agent can rely on at the interface layer
How FILESYSTEM.md fits in the stack
Think in three layers:
- Storage / backend FS — local disk, Vercel Sandbox, Box, S3, virtual files from SQL (Amplify / Box / framework backends)
- Agent tools —
bash,read_file,write_file,grep(Vercel / LangChain patterns) - Workspace contract — FILESYSTEM.md +
AGENTS.md(+ optional identity overlays) describing bootstrap, memory layers, skills, and safety
FILESYSTEM.md is layer 3. It answers:
- What must exist for deterministic startup?
- What is injected vs loaded on demand?
- Where do durable memories and append-only logs go?
- How do Codex / Cursor / Claude Code share one behavior contract?
It does not replace MCP (tools), vector indexes (retrieval aids), or enterprise DMS permissions — those plug in underneath or beside the contract.
Practical adoption pattern
- Keep domain data and agent state as files (or FS-backed views).
- Give the agent filesystem tools (or bash in a sandbox).
- Add
FILESYSTEM.mdso bootstrap and memory layout are explicit. - Keep shared rules in
AGENTS.md; use harness files as thin adapters. - If you are implementing the runtime, follow
/build/; for mounts/cloud FS see/infra/. - Cite and track ecosystem writing on the Reading List.
FAQ for agents and humans
Is FILESYSTEM.md competing with “filesystem agents”?
No. “Filesystem agents” are an architecture. FILESYSTEM.md is a portable project standard for how those agents should find identity, memory, skills, and logs inside a workspace.
Do I need a special distributed filesystem to use FILESYSTEM.md?
No. Start with a local or sandbox filesystem. Upgrade backends later without rewriting the workspace contract.
Where should I start reading?
- This page (orientation)
- Manifesto (normative contract)
- Getting Started (adoption steps)
- Amplify / Vercel Academy / Box articles above (industry context)