An emerging theme among teams implementing agents is that the file system is the ideal abstraction for many AI agents. Files, directories, and bash. This article explores that thesis, examines where it holds up, where it breaks down, and what a practical agent-oriented file system should look like.
Why Now
Arguably the most important point: LLMs are already trained on file system operations. Models have ingested enormous volumes of code, shell sessions, and repository navigation. Directory traversal, searching the filesystem, and running bash commands are native behaviors. Vercel’s Ashka Stephen put it plainly:
“LLMs have been trained on massive amounts of code. They’ve spent countless hours navigating directories, grepping through files, and managing state across complex codebases. If agents excel at filesystem operations for code, they’ll excel at filesystem operations for anything.”
Then there is the cost of MCP tool proliferation. Archil’s Hunter Leath notes that frontier teams discovered a consistent pattern: “each MCP tool that they introduced into an AI agent would subtly degrade the performance of that agent.” Every tool definition consumes context tokens for parsing instructions, accelerating context rot. The industry response has been to consolidate dozens of bespoke tools into a single bash (or Python) tool and let the model interact with data through the file system directly. Jerry Liu of LlamaIndex goes further, arguing that an agent with access to a filesystem and only 5–10 tools is as general as one with 100+ MCP tools.
Andrej Karpathy has put his finger on the same dynamic from a different angle. Karpathy has attributed Claude Code’s effectiveness to the fact that it runs on your computer, with your environment and your data, calling it “a little spirit that lives on your machine.” The filesystem is what makes that possible: the agent reads local files, writes local files, and navigates local directories — all operations the model already knows from training data.
Simon Willison’s observation, as noted by LlamaIndex, captures the direction: there are certain benefits to skills over MCPs. Skills, originally introduced by Anthropic late last year, are literally text files that agents traverse using filesystem tools. You can share a skill by pasting an API spec into a .md file. It only enters the context when the agent actually needs it, and because it’s plain text, it can describe API interactions that a direct MCP tool call cannot express. Many others have adopted the format, meaning a skill written for Claude Code mostly works in OpenAI Codex and other agents out-of-the-box.
Daniel Phiri describes this as interoperability without coordination: any two tools that can read markdown can share context and capabilities without formal standards. The file format itself becomes the API.
Architectural Principles for Agent-Friendly Codebases
External memory beyond the context window: Jerry Liu describes it directly: “I get a sense of dread every time I see the ‘Context left until auto-compact’ notification pop up on Claude Code. Once you trigger compaction, the agent inevitably gets amnesia and isn’t able to fulfill the rest of the task reliably.” Files solve this by giving agents a place to externalize partial results, evolve plans, and revisit prior work outside the context window. 1Password’s Wayne Duso and Nancy Wang put it simply: “Agents don’t just need memory. They need a workspace.”
Token-efficient progressive retrieval: Instead of stuffing everything into a prompt or relying on embedding similarity, agents narrow their search step by step: grep for keywords, read_file_range on matching lines, assemble only what matters. LangChain’s Nick Huang calls this the core of context engineering: “our job as agent engineers is to fit red to green (to make sure that the context the agent retrieves is as small of a superset of the needed information as possible).”
While the storage layer evolves from a local-disk prototype to an enterprise-grade production system independently. This separation of concerns is what helps give the pattern staying power.
Agent reasoning stays clean and focused while the storage layer evolves from a local-disk prototype to an enterprise-grade production system independently.
Auditability by default: File reads and writes leave traces. Vercel found this alone resolved a major pain point: “When the agent fails, you see exactly what files it read and what commands it ran. The execution path is visible. No black box.” 1Password builds on the same idea, arguing that filesystems give you a prerequisite for agents touching real systems: every action can be inspected, diffed, attributed, and rolled back.
Composability through Unix conventions. Agents inherit the entire Unix toolchain. Jakob Emmerling‘s FUSE (Filesystem in Userspace)-based email agent shows what that looks like in practice. Rather than building list-emails, read-email, and move-email tools, he mapped the email domain to a filesystem. Agents organize emails using mv (move file command), flag them with ln -s, and search them with grep. “We didn’t spend any time on tool design,” Emmerling writes. “We just mapped our domain to a filesystem and got intuitive tool behavior for free.”
File System as Interface Contract
One of the more interesting ideas is that a “file system” does not have to mean literal files on disk. Box‘s Andrew Wong makes this explicit:
A filesystem doesn’t have to mean literal files on disk. It’s an interface contract. The agent only needs to understand how to navigate files.
LangChain’s Deep Agents demo, documented in detail on Box’s engineering blog, puts this into practice with a backend that routes directory prefixes to different storage systems: /docs/ goes to cloud storage, /memories/ goes to SQLite (with rows synthesized into virtual JSON or Markdown files), and /workspace/ goes to local disk. The agent sees a single unified directory tree. When Wong replaced the S3 backend with Box, the agent gained enterprise capabilities (permissions, audit trails, versioned writes) with zero changes to its prompts or reasoning logic.
This separation of concerns is what helps give the pattern staying power. Agent reasoning stays clean and focused while the storage layer evolves from a local-disk prototype to an enterprise-grade production system independently.
File Systems vs. Databases
Not everyone is convinced. In particular, some argue that databases provide many of the same benefits as file systems along with substantial guarantees for correctness and safety of complex operations at scale. Richmond Alake of Oracle, a database vendor with an obvious interest in the outcome, ran benchmarks that pin down exactly where file systems fall apart.
Semantic Retrieval at Scale: On a small corpus (10 queries), both the filesystem agent (using grep) and the database agent (using vector search) scored roughly 82% on an LLM judge evaluation, essentially a tie.
Scale the corpus up (45+ queries with paraphrase variability) and the filesystem agent collapses to 29.7% while the database agent holds at 87.1%. Keyword matching fails when queries use synonyms or paraphrases that grep cannot catch.
Corpus Benchmark: FSAgent (Grep) vs. MemAgent (Vector Search)
Concurrency and Correctness
In a test of 500 concurrent writes, naive filesystem writes without locking produced only 14 entries (3% of expected). With file locking, 500/500 at 15ms. With an ACID database, 500/500 at 656ms.
Alake’s conclusion is pointed: Naive filesystem writes can be fast and still be wrong. Without locking, concurrent writes conflict with each other. You might get good throughput and still lose memory entries. If your agent’s “memory” is used for downstream reasoning, silent loss is not a performance issue. It is a correctness failure.
The deeper warning: teams that bolt on locking, atomic writes, write-ahead logs, retry logic, and metadata indexing to their filesystem-based agents are rebuilding a database with fewer guarantees.
Concurrency Test: Filestyem (No Lock) vs. Filesytem (Locked) vs. Database
Archil’s Hunter Leath finds the middle ground: databases and file systems serve different roles. Agents handling structured data will reach for databases (potentially as SQLite files living within a file system), while the file system provides the outer container for mixed, unstructured data. Alake’s summary holds: “Don’t conflate interface with substrate. Filesystems win as an interface (LLMs already know how to use them); databases win as a substrate (concurrency, auditability, semantic search).”
What File System Makes Possible
Once you commit to the filesystem as your agent’s primary interface, certain patterns become much simpler to build.
Self-improving agents: LangChain highlights an emerging pattern: agents that write their own instructions to disk after receiving user feedback. Over time the agent accumulates context it authored itself, and its capabilities grow accordingly. This is much more difficult without a mutable knowledge store.
Fuse virtual filesystems for arbitrary domains: Emmerling’s FUSE approach projects any data source (a database, an API, an object store) into the agent’s sandbox as a real filesystem, reading directly from the backend on demand. Virtual folders backed by computed attributes (like Starred/ or Needs_Action/) let agents manipulate state through bash commands without dedicated tools. Emmerling frames this as a context engineering problem: “You can think of the filesystem as a UI layer for the agent. Just like your frontend decides how to present data to users, your FUSE implementation decides how to present data to the agent.”
Snapshot and reproduce full agent state: Turso’s AgentFS takes a different approach: pack everything into one SQLite file. The virtual filesystem, the key-value store, the appendonly tool call audit log — all of it lives in a single database. To snapshot the agent, copy that file. To roll back, restore the old copy. As Turso’s Pekka Enberg and Glauber Costa put it: “Treat agent state like a filesystem, but implement it as a database.”
Skills as a distribution mechanism: Phiri documents NanoClaw’s “skills over features” approach, where new integrations are delivered as a SKILL.md file that teaches the agent how to rewrite its own installation. No plugin marketplace, no MCP server, no build step. The agent reads the skill file and follows the instructions. The distribution mechanism for new agent behavior is a text file.
Multi-agent coordination through files: LangChain describes how subagents can write findings directly to the filesystem rather than returning bloated replies to an orchestrator, which reduces “telephone game” information loss. Dex Horthy’s three-phase workflow (Research, Plan, Implement), cited in LlamaIndex’s write-up, uses files as structured handoff artifacts between phases, with human review at each gate. This, as Horthy puts it, “anecdotally massively increases the performance of coding agents.”
Vercel seems to provide the most quantified case. Their internal sales call summarization agent was running custom retrieval tooling at about $1.00 per call on Claude Opus 4.5. Swapping that for a filesystem tool and a bash tool dropped costs to roughly $0.25 per call. Output quality went up as well. The agent simply treats transcripts like a codebase: search for patterns, read the relevant sections, assemble context using tools it already knows from training. No custom retrieval logic. And because the approach leans on general code-navigation abilities, performance improves automatically as models get better at code understanding.
Reference Architecture
Drawing from the patterns across these sources, here is a practical reference architecture for an agent-oriented filesystem. This is a synthesis of recurring design choices from Vercel, LangChain, LlamaIndex, 1Password, Koylan’s BrainOS, and Turso’s AgentFS (with help from Claude’s new visualization capabilities:
Key Design Principles
- Agent.md as router: A single entry-point file structured as a decision table that maps request types to action sequences and relevant modules. Muratcan Koylan’s BrainOS demonstrates that this approach eliminates conflicting instructions across modules. His three-level progressive disclosure, routing from a compact top-level file through module instructions to data files loaded on demand, cut token usage by roughly 87% for a typical task.
- Append-only for anything the agent writes: JSONL files where the agent can add but never delete. Muratcan Koylan learned this the hard way when building BrainOS: an agent accidentally overwrote posts.jsonl and deleted three months of engagement history. His takeaway: JSONL’s append-only pattern isn’t just a convention. It’s a safety mechanism. The agent can add data. It cannot destroy data.
- Skills as files: Each capability is a plain-text file the agent reads only when relevant, so the context window stays lean. Auto-loaded reference skills (voice guides, anti-patterns) inject silently, while task-specific skills are invoked on demand.
- The filesystem as interface database as substrate: For simple use cases, literal files on disk work fine. When you need concurrent agents, semantic search, or enterprise governance, swap the backend to SQLite, Box, S3, or any combination through a composite backend pattern. The agent’s prompts and reasoning logic do not change.
- Isolation and identity for multi-agent systems: 1Password argues that production swarms require three things: a persistent runtime, explicit agent identity from creation, and access that is scoped, time-bound, and revocable. Without these, shared filesystem access creates the same “convenience-to-danger inversion” that plagued pre-container shared disks.
Security at the filesystem boundary: 1Password’s framing of controlled vs. uncontrolled swarms is useful. Most current agent demos inherit the developer’s full machine access. Production systems need the identity and isolation primitives that do not yet exist as standard infrastructure.
As they put it: “Filesystems give agents a universal, durable abstraction for memory and coordination. What they do not give you is a way to express intent, authority, or accountability at the level agents operate.”
Implications
The practical advice from these organizations is fairly consistent: start with files on disk, give the agent bash, and add database-backed storage behind the filesystem interface when scale or concurrency demands it. The filesystem is the interface layer. The storage substrate underneath can be anything from local disk to Box to SQLite, swapped without touching the agent’s prompts.
The Vercel team’s summary says it plainly: The architecture that works is “almost no architecture at all. Just filesystems and bash.”
Authors
