Put the payload on disk and the pointer in the window

The window is not the only place state can live

A 40,000-token CSV in the window is 40,000 tokens on every subsequent turn, and the model will still miscount its rows, because counting 8,000 lines of text is not what these systems are good at.

The alternative costs about ninety tokens:

<artefacts>
/work/orders.csv — 8,412 rows. Columns: order_id, customer_id, placed_at,
  status, total_inr. Query it with run_sql (DuckDB syntax, read-only).
</artefacts>

The data is on disk. The window holds its location, its shape, and how to ask it questions. SELECT status, COUNT(*) FROM 'orders.csv' GROUP BY status returns five rows and is exactly correct, which is more than the model would have managed reading all 8,412.

This is the oldest idea in computing applied to a new constraint: keep the working set small and the store large. Everything in this lesson follows from it.

What it unlocks

State that outlives the window. A long task can write intermediate results to disk, compact its context to almost nothing, and carry on. The transcript is disposable; the files are the work.

Resumability. A run that crashes at step 30 with its findings in a file can restart from the file. A run that crashed with its findings in a compacted transcript cannot.

Correctness on the operations models are worst at. Counting, summing, sorting, joining, deduplicating. Every one of these is a database’s job. sqlite3 is on almost every machine, DuckDB installs with one pip command and reads CSV and Parquet directly with no import step, and both are free. There is no cost argument for making a language model add up a column.

Handover. Files are readable by humans, by the next session, and by a different model entirely. A compacted summary is readable by none of those with any confidence.

The manifest, and why it is not optional

The predictable failure is that the model forgets a file exists. It wrote /work/findings.md at step 6, and by step 24 that mention is 40,000 tokens back, in the middle of the window, which is the position least likely to be used.

So maintain the artefact list as a block your code renders at a fixed position on every turn: the same discipline as the structured state block in the conversation module, for the same reason. Your code knows which files exist; the model should not have to remember.

Keep it to one line per artefact: path, what it is, how big, how to read it. When the list grows past a dozen entries the task has usually sprawled, and that is worth noticing on its own.

Three failure modes to design against

Stale reads. The model read a file at step 8 and believes it still knows the contents at step 20, having edited it at step 14. The stub message from the agent-loop lesson solves this, and the wording matters: say the content is stale, not merely that it was omitted.

Invented paths. A model will confidently call read_file("/work/summary.md") for a file nobody created. The error must say so plainly and list what does exist: No file at /work/summary.md. Files in /work: orders.csv, findings.md, notes/. That single line converts a dead end into a correction.

Write collisions. Two parallel sub-agents writing the same path, or a retry overwriting a good result with a partial one. Give each writer its own path, or write to a temporary file and rename atomically.

The part people skip

A file is untrusted if anything untrusted wrote it.

If your agent fetches a web page and saves it to /work/page.html, that file now contains whatever the page’s author chose to put there, including, quite possibly, a paragraph addressed to your model. When the model later reads that file, the text arrives in the window with no marker distinguishing it from material you authored. The filesystem has quietly laundered untrusted content into something that looks like your own working notes.

The defence is to keep provenance on the file, not in your head. A separate directory for anything externally sourced, a manifest entry that names it as untrusted, and a wrapper that reads such files inside explicit delimiters saying where the content came from. The next module is entirely about what follows from that, and it is the single most common way a well-built agent is turned against its owner.

The free path, which is all of it

Nothing here needs a product. A directory, sqlite3 or DuckDB, and four tools (read_file, write_file, list_files, run_sql) is the whole pattern. It runs on a laptop, it runs inside a container, and it runs against a temporary directory that you delete when the task ends, which is also the simplest data-retention policy you will ever implement.