Scratchpad Patterns: Giving an Agent Somewhere to Think

An agent's working memory is the transcript, and the transcript is the thing you are constantly trying to shrink. Every plan the model formed, every conclusion it reached, every dead end it ruled out lives in exactly the place you will compact away on turn twenty.

A scratchpad breaks that dependency. Give the agent a file it owns, tell it to record what it has worked out, and its conclusions stop being hostage to context management. The pattern is simple; the discipline around what goes on it is where it succeeds or fails.

Why a file rather than a message

Anything in the conversation is subject to compaction, truncation and the attention penalty that applies to the middle of a long context. Anything in a file is durable, re-readable on demand, and survives the process dying.

That durability is the whole point. A scratchpad written to disk means a resumed session can recover the agent's reasoning without replaying its transcript, and a human picking up a stalled run can read what it thought it was doing. Agent resumption patterns covers using it that way.

It also externalises state that would otherwise be re-derived. An agent that has already worked out which module owns the failing behaviour should not have to work that out again after compaction, and a file is the cheapest way to make sure it does not.

What belongs on it

Four categories, and keeping to them is what stops the file bloating.

The plan: the steps the agent intends to take, with their status. This is the single most useful entry, because it is what a compacted agent loses first and misses most.

Established facts: concrete findings with identifiers intact. "Auth middleware lives in src/auth/middleware.ts and is registered in server.ts line 42" is worth more than any amount of narration, because it saves a search.

Ruled out: what has been tried and did not work, and why. This is the field that prevents the most common wasted-cost pattern in long sessions, where an agent retraces a dead end it explored twenty turns earlier.

Open questions: things the agent could not determine and may need a human for. This makes the file a handoff document as well as a memory.

What does not belong

Narration. "Now I will read the config file" is a sentence about the transcript, not a finding, and a scratchpad full of these is a second transcript with all the same problems and none of the compaction.

Raw tool output. If the agent pastes a file into the scratchpad, it has moved the context problem rather than solved it. Record the conclusion drawn from the output, not the output.

Anything already in the system prompt. Duplicating constraints there wastes tokens on every read and creates two sources of truth that can drift apart. System prompts covers what belongs in the durable instruction layer instead.

Write-through discipline

A scratchpad only works if it is current, and models do not reliably maintain one unprompted. Two mechanisms make it stick.

The first is instruction: state in the system prompt that the scratchpad must be updated after every step that establishes a fact, completes a plan item, or rules something out. Be specific about the trigger, because a vague "keep notes updated" is followed early in a session and forgotten later.

The second is structural: make the harness re-inject the scratchpad content near the end of the context every few turns, or after every compaction. The model then sees its own notes in a position where attention is strong, and stale entries become obvious to it.

Some teams go further and require a scratchpad update as part of the state transition out of any phase that produced findings. That converts a habit into a gate. Agent state machines covers where those gates belong.

Two shapes: living document or append-only log

A living document is rewritten in place — the plan is edited as items complete, findings are revised as understanding improves. It stays small and reads well, and it loses history. This is the right default for a single agent working a single task.

An append-only log never rewrites, only adds. Nothing is lost, ordering is preserved, and the file grows without bound. This suits multi-agent work and any run you will need to audit, where knowing when something was believed matters as much as what.

The hybrid that works well in practice is a living document for plan and current findings, plus an append-only decision log for choices with reasons. The first stays cheap to re-read; the second is only read when someone is investigating. Subagents and delegation covers using a shared scratchpad as the coordination surface between agents.

Cap the size, deliberately

The scratchpad is re-read, so it is prompt content with the same cost profile as anything else. An unbounded one recreates the exact problem it was introduced to solve.

Set an explicit ceiling and instruct the agent to prune when it approaches it — completed plan items collapse to a line, superseded findings are dropped, ruled-out approaches keep only their conclusion. Pruning is a normal maintenance operation, not a failure.

Check the size in your traces. A scratchpad that has grown past its ceiling usually means the agent has been narrating into it, and the fix is in the instruction rather than the ceiling. Summarisation in agent loops covers the same discipline applied to the transcript.

When it is not worth it

Short sessions do not need one. If a task finishes in five turns and never approaches the window, a scratchpad is pure overhead — extra tool calls, extra tokens, extra opportunity for the agent to spend a turn on bookkeeping instead of work.

The threshold is roughly the point where compaction becomes likely, or where a human might need to pick the work up. Below that, the transcript is your scratchpad and it is doing fine. Agent memory and context management covers deciding which memory mechanism a workload actually needs.