Filesystem as Context
Use the filesystem as externalized working memory — write plans, notes, and large tool outputs to files, keep the live window lean, and re-read only what the current step needs.
Intent & Description
🎯 Intent
Use the filesystem as the agent’s externalized working memory — writing plans, notes, and large tool outputs to files, dropping them out of the live window, and re-reading on demand.
📋 Context
An agent running a long-horizon task generates more state than the context window can hold: a multi-step plan, accumulating notes, and tool calls returning large payloads (logs, scraped pages, query dumps). The runtime can read and write files that persist across many turns.
💡 Solution
The agent maintains working state as files rather than live context. A plan lives in a file (e.g. todo.md) that the agent rewrites as steps complete; notes accumulate in a notes file; large tool outputs are written to disk and replaced in the window by a path plus a one-line description. Each turn the agent carries lightweight identifiers (file paths, line ranges, keys) and loads full content only for the step that needs it. Because content is restorable from disk, compaction is lossless — the window holds a lean view while the filesystem holds full state.
Real-world Use Case
- The task runs over many turns and generates more state than the window can hold.
- Tool outputs are large and only needed intermittently, not every turn.
- The runtime can read and write files that persist across the agent loop.
- The plan and notes should survive restarts or be inspectable by a human.
Source
📌 TL;DR
Write the plan, notes, and large payloads to files — keep the live window lean with paths and descriptions, load full content only when the current step needs it.
Advantages
- The live window stays lean across long-horizon tasks regardless of total state size.
- State is durable and restorable — window pressure doesn’t destroy detail.
- Per-turn token cost drops because bulk payloads no longer ride in every turn.
- The plan and notes survive process restarts and are human-inspectable.
Disadvantages
- Re-reading a file adds a tool round-trip and latency each time state is needed.
- The agent must know which file to re-read or it works from a stale view — no automatic freshness.
- Stale or contradictory files accumulate unless the agent prunes them actively.
- File access widens the attack surface and must respect sandbox boundaries.