Your Agent should use a File System

This is a hill I will die on. Every agent can use a file system.

The file system is an elegant way of representing state that your agent could read into context & allowing it to verify its work.

🧵on why and examples

Claude Code was what proved this to me.

Before CC, people though context windows would get long enough that you could just fit a codebase into context.

But that is not how programming works. You don't need to remember everything, you just need to know how to find it.

Here's an example from my open source email agent (https://github.com/anthropics/claude-agent-sdk-demos

Instead of dumping a ton of emails into context, I write them to a file and let the agent grep across those files.

Fundamentally this works because it lets your agent have multiple passes at a problem and let it fix its work.

In this case it can try a few different address searches, correlate them to exact lines to make sure it doesn't hallucinate and extract them in a structured way.

Some other examples of using the file system (there are tons, be creative):

Memory: Your agent can search previous conversation as markdown or JSON files to find context and link to exact architecture.

Creating React Artifacts: Agents make mistakes writing code, to display a react artifact, have your agent write to a file and then run a linting scripting and fix errors. This sort of iteration is much easier than writing a file from scratch.

Deep Research: Spin off multiple sub agents that write their findings to the file system as markdown files. Have the orchestrator agent read and search across those files to summarize, ground itself in references, etc.

Planning & Scratch Pads: Use the file system to store a plan and notes on solving a problem. Especially for hard problems with multiple subagents, this can be key to make sure you're not redoing work.

Dungeons & Dragons: Instead of having an AI DM that has to remember every single thing you've told it, let it write files that describe locations, characters, monsters, secrets, etc. and organize it well. The AI DM will then read in the context it needs depending on what is happening to the party.

--

A lot of file system examples go hand-in-hand with code generation.

I'll be writing more this week about how you can use code generation creatively to solve many different problems, not just for coding agents.

I know this is inconvenient! It would be easier if your agent could run in a lambda function.

But agents are trained like humans and so we need to give them the resources & the tools that we use- like the file system.

You can use the Claude Code SDK to do this.

Of course file systems are a big responsibility.

As agents become more general, the problem shifts to permissions.

We suggest Claude Code in a sandbox, but also have a lot of tools for settings permissions: https://code.claude.com/docs/en/agent-sdk/permissions

More content on hosting to come.