Filesystem as Context

also known as Context Offloading, Filesystem as External Memory, File-backed Working Memory

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 runs a long-horizon task that generates more state than the context window can hold: a multi-step plan, accumulating notes, and tool calls that each return large payloads such as logs, scraped pages, or query dumps. The runtime can read and write files, and the same files persist across many turns of the loop.

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.

Forces

The window is finite but the task generates unbounded state.
Large verbatim payloads cost tokens every turn they remain live.
State dropped from the window is gone unless it was stored somewhere durable.
Re-reading a file costs a tool round-trip and latency.

Example

A coding agent is migrating a large codebase across many turns. It writes the migration plan to todo.md and checks off steps as it goes, and each test run produces a 2,000-line log. Instead of holding those logs live, the harness writes each full log to a file and leaves only the path and a one-line verdict in the window. When a later step needs the exact stack trace, the agent re-reads the relevant log file. The window stays lean across the whole migration while no detail is permanently lost.

Diagram

flowchart TD Step[Agent step] --> Gen[Plan / notes / large output produced] Gen --> Write[Write full content to file] Write --> Drop[Drop from live window<br/>keep path + one-line summary] Drop --> Lean[Lean live context] Lean --> Need{Step needs this state?} Need -- yes --> Read[Re-read file into context] Read --> Step Need -- no --> Step

Solution

Therefore:

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.

What this pattern forbids. Large outputs and notes must not stay in the live window; they are written to files and re-read only when the current step needs them.

And the patterns that stand alongside it, or against it —

complementsScratchpad★★— Give the agent a writable scratch space for intermediate notes that informs later turns but does not pollute the response.
complementsTool-Result Eviction★— Once a tool's raw output has been consumed, replace it in the live context window with a short marker of what was done, reclaiming tokens without losing that the call happened.
alternative-toContext Compaction★— When the context window nears its limit, replace the older conversation span with a model-written digest that preserves decisions, commitments, and active constraints while discarding noise, so the agent keeps running without losing the thread.
complementsSynthetic Filesystem Overlay·— Project heterogeneous enterprise data sources into a single Unix-like tree exposed through filesystem primitives so the agent reuses path semantics it already knows instead of learning a bespoke API per source.
complementsMemGPT-Style Paging★— Treat the LLM context window as RAM and external storage as disk, with the model issuing tool calls to page memory in and out.