Give the Agent a Scratchpad: External Working Memory

A long-running agent accumulates findings in the only place available: the conversation. By turn thirty, the useful information is scattered across two dozen tool results, mixed with everything that didn't matter, and being re-sent in full on every call.

An external scratchpad — a place the agent writes notes and reads them back — fixes this, and it does more than save tokens. It changes what the agent can do.

The tools

Three, and they're small:

note_write(key: string, content: string)     # overwrite or create
note_read(key: string) -> string
note_list() -> [{key, updated_at, size}]

Backed by anything: a dict for the run, a file, a table. The point isn't the storage; it's that findings become addressable and don't have to live in the context.

What changes

Findings survive compaction. When history gets trimmed or summarized, notes persist. An agent that wrote findings/db_layer at turn eight can read it at turn forty regardless of what happened to the transcript in between. → This is the strongest reason to add one, and it turns compaction from a lossy hazard into a routine operation.

Large intermediate results stop costing every turn. A tool returns a five-thousand-token document; the agent extracts what matters, writes a two-hundred-token note, and the document need not stay in context. Compare with the default, where that document is re-sent on every subsequent call.

Work becomes inspectable. note_list() shows what the agent has established, in a form a human can read directly. Reading five notes is faster than reading a forty-turn transcript, and it's a genuinely useful debugging surface.

Structure becomes possible. Notes can hold a plan, a checklist, an evolving hypothesis, a list of ruled-out options. The agent can revise plan rather than restating it, which sidesteps the plan-lock-in problem where a stale plan in the transcript outweighs newer evidence.

Making it work in practice

Prompt for it explicitly. Models don't reach for a scratchpad unprompted. The system prompt needs to say when to write: after establishing a fact worth keeping, after ruling something out, before compaction. Without that instruction the tools go unused.

Surface the index every turn. Inject note_list() output into the context each turn — keys and sizes only, not contents. It's small, and an agent that can't see what it has written won't read it back.

## Notes
findings/db_layer      (updated turn 8,  180 tokens)
findings/network       (updated turn 14, 90 tokens)
ruled_out              (updated turn 19, 210 tokens)
plan                   (updated turn 21, 150 tokens)

Use a key convention. Flat, predictable names. Random keys make retrieval unreliable, since the agent has to remember rather than derive them.

⚠️ Cap the size. A scratchpad with no limit becomes a place to dump everything, and then reading a note is as expensive as the original tool result. A per-note cap forces the summarization that makes it useful.

The pattern that makes long runs work

Combine it with structured run state and the compaction problem largely dissolves:

1. Tool returns something large.
2. Agent extracts the relevant part and writes a note.
3. The loop drops the raw result from the context, leaving a reference.
4. Compaction trims old turns freely — the findings are elsewhere.
5. Later turns read notes back on demand.

Context stays roughly constant regardless of run length, and nothing important is lost when history is trimmed. ✅ This is also what makes a run resumable: notes plus a work ledger reconstruct the state without the transcript.

💡 The reviewable-artifact bonus

For long autonomous runs, notes are what a human actually reads. A three-hour investigation's transcript is unreadable; its five notes — hypotheses, findings, ruled-out paths, current plan — are a report.

Worth designing for deliberately: name the keys so the note set reads as a document, and the agent produces a reviewable artifact as a side effect of working.

The takeaway

Three small tools convert the context from the only place to keep findings into just the working buffer. Prompt explicitly for writing, surface the index every turn, cap note size, and drop large raw results once they've been distilled. Context stops growing with run length, compaction stops being lossy, runs become resumable, and you get a readable record of what the agent established — for about fifty lines of code.