Filesystem as Context

Problem

Keeping every plan revision, note, and verbatim tool output in the live window pushes the agent toward the window limit, raises per-turn cost, and degrades reasoning as relevant signal is buried under bulk. Truncating or dropping that material blindly loses state the agent still depends on later in the task, and a window that overflows mid-task forces an abrupt summarize-or-die compaction that can discard exactly the detail a later step needs.

Solution

The agent maintains its working state as files rather than as live context. A plan lives in a file such as todo.md that the agent rewrites as steps complete; running 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 the full content back into context only for the step that needs it, then drops it again. Because the content is restorable from disk, compaction is lossless: the window holds a lean view while the filesystem holds the full state. This makes the filesystem the externalized memory of record, distinct from in-context note-taking, which keeps notes live, and from eviction, which discards consumed payloads behind a marker.

When to use

• The task runs over many turns and generates more state than the window holds.
• Tool outputs are large and only needed intermittently rather than 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.