An Unpruned Scratchpad Eventually Does More Harm Than Good

Writing a scratchpad is the easy part. A store that carries an agent’s state across sessions, whether that is a file in a coding agent’s workspace or a record in the datastore behind a deployed system, can be stood up in an afternoon, and on day one it does exactly what it promises. The difficulty is not authorship. It is keeping that state worth reading after weeks and months of active use, because a scratchpad left to accumulate does not simply stop helping. It decays in two directions at once. It bloats until processing it is itself a cost, and it goes stale until acting on it is a mistake. Both are the default trajectory of a store that gets appended to far more often than it gets pruned, and both are avoidable only by treating maintenance as an ongoing practice rather than a one-time setup. The scratchpad that keeps its value is not the one that was written well. It is the one that is kept lean, kept structured, and kept true, every session, on purpose.

Scratchpads bloat by default

The reason a scratchpad grows without bound is structural, not careless. Every session that touches the project has an obvious reason to add to it and no comparable pressure to remove. A session that reaches a decision records it. A session that hits a dead end notes it. A session that opens a question writes it down. But the session that finally resolves that question is usually busy with the resolution, and clearing the now-obsolete entry is the kind of tidying that feels safe to defer. So the store grows monotonically. New state lands on top of old state, and the old state rarely leaves. What began compact enough to read at a glance becomes something where finding the current state means scanning past a sediment of everything that was ever current.

That growth is not merely untidy. It is a direct tax on the thing the scratchpad exists to provide. The agent loads the whole thing, and a longer record consumes more of the context window before any real work begins, costs more to process on every session, and buries the handful of entries that actually describe the present under a much larger volume that describes the past. Past a certain size it stops being a fast orientation and becomes a slow one, which is the opposite of its purpose. The fix is not heroic discipline applied occasionally. It is a size ceiling with an enforcement rule attached. Decide on a length the record has no business exceeding, and let breaching it be the thing that forces a pruning pass before any new content goes in. The cap does not have to be precise. Its job is to convert an open-ended growth curve into a bounded one by making the record’s size something a session is periodically forced to notice, rather than something that silently ratchets upward until it is a problem nobody chose.

The substrate has to be a system of record, not a cache

One choice sits underneath all of this and is easy to get wrong precisely because so many systems already have a fast, convenient place to stash state. A scratchpad is not a cache. A cache holds data you can afford to lose, because anything evicted can be recomputed from a more authoritative source. The scratchpad’s contents have no such source. The dead end already explored, the reasoning behind a decision, the path the project chose not to take: none of that is recoverable once it is gone, which is the entire reason the scratchpad exists rather than being re-derived each session. Back it with a store that evicts under memory pressure or expires entries on a timer, and it will quietly discard exactly the state the pattern was meant to preserve, usually without anyone noticing until a session opens missing the context it depended on. A cache can sit in front of the scratchpad for speed, but the system of record underneath has to be durable. This is also the line that separates the scratchpad from a retrieval store of accumulated knowledge: the latter grows on purpose and is queried in slices, while the scratchpad is loaded whole and held to the current state and nothing more.

Structure is what keeps it scannable

Length is only half of readability. A short record with no shape is still hard to act on, and a long one with a clear shape can stay usable well past the point where an unstructured one would have collapsed. The structure that works divides the record into a small number of blocks, each with a different lifespan and a different maintenance rule, so that a session reading or pruning it always knows where a given piece of state belongs and how long it is meant to live.

Four blocks cover what the record needs to hold. The first is a run of timestamped entries, and the timestamp is the point: a note stamped three weeks back against a task that has since shipped announces itself as removable during a pruning pass, where an undated note leaves that call to guesswork. The second is a decision log, the architectural choices with the reasoning kept beside each one, and it turns over more slowly than anything else because a sound choice keeps earning its place long after it is made; entries land here and mostly stay, since a reversal is rare and the recorded reasoning is exactly what stops a later session from undoing the choice without realizing it. The third is a current-state block, a single account of where the work sits at this moment, governed by one rule: overwrite it each session, never grow it by appending, so it can never curdle into a stack of past states wearing the mask of the present. The fourth is an open-questions block, the unsettled items waiting for the next session to pick up, and it drains as fast as it fills, because a question that gets answered has its entry pulled. What the four-block shape buys is a home and a lifespan for every kind of state, which turns both writing and pruning into something close to mechanical instead of a judgment the author has to argue out afresh each time.

Nothing leaves unless a rule makes it leave

Structure tells you where things go. What it does not tell you is what comes out or when, and until something answers that, the answer is nothing and never. The failure is not that people disagree about what to remove. It is that removal has no natural trigger, so it defaults to never. A policy exists to supply the trigger.

For a resolved entry, the trigger is the resolution itself. Whoever closes the issue clears its entry in the same sitting, not on some later pass, because the later pass is the whole problem: an entry parked for future cleanup is an entry still sitting there weeks on, quietly feeding a session that had no way to know it had gone obsolete. For the current-state block, the rule is the one already named: rewrite it every session so it describes the present and only the present. For state that is genuinely worth preserving as history, a completed milestone or a resolved investigation someone may want to revisit, the answer is to move it out of the active store into a separate archive rather than to keep it inline. Archiving preserves the record without paying for it on every read, which is the distinction that matters: the active scratchpad is optimized for reflecting current truth cheaply, and history that no longer describes the present belongs somewhere the agent is not forced to load each session. The single principle underneath all of it is that at any given moment the scratchpad should carry what holds now and none of what merely used to. Pruning is how a store that only ever gets added to is held to that standard.

Standing rules outrank session state

A scratchpad does not sit alone. It shares the project with the agent’s standing instructions, the layer that holds the stable rules, conventions, and permissions meant to apply across every session. The two are easy to confuse because both configure the agent’s behavior, but they hold different kinds of truth, and the difference determines which one wins when they disagree. The standing instructions hold settled state, rules that change rarely because they encode decisions meant to persist. The scratchpad holds evolving state: the work underway, the calls made this session, the threads still hanging. Where the two disagree, the standing rules are the ones that hold, because a rule set deliberately to persist across sessions should not be quietly overturned by a note that captures the state of one particular afternoon.

That precedence has to be stated, not assumed. If the ordering is left implicit, the agent has no principled way to resolve a conflict between a standing rule and a scratchpad entry that points the other way, and it may settle the clash in whatever direction the immediate context happens to push, which is unpredictable exactly when predictability matters. The remedy is a single explicit line in the standing instructions that names the scratchpad as session state and declares that, in any conflict, the standing rules govern. That one sentence removes the ambiguity. Without it, the two are peers in the agent’s eyes, and a transient note can end up outranking a settled decision purely because it happened to be more recent or more specific. Making the hierarchy visible is what keeps the evolving state from silently overriding the settled rules.

A shared scratchpad inherits every problem of shared state

The moment a scratchpad is readable by more than the one agent run that wrote it, it stops being private working memory and becomes shared state. For a team of developers, that boundary is committing it to version control, where a colleague can open the record and see the decisions made in sessions they were not part of and the dead ends already mapped so nobody re-walks them. For a deployed system, it is the same slot being read and written by concurrent runs, or by several agents cooperating on one job. Either way the gain is real: individual discovery becomes shared knowledge, which is exactly the leverage a long-running effort wants. And either way it arrives with the coordination costs that any shared mutable state carries, costs that have to be designed for rather than discovered.

The friction concentrates on the current-state block, because it is the one part that is rewritten wholesale rather than appended to, which makes it the natural site of collisions. Two writers replacing it at once is a lost update waiting to happen, and however the substrate surfaces that, as a merge conflict in a versioned file or a clobbered record in a datastore, the collision is worth reading rather than merely resolving, because it usually means two workers were driving the same task at the same time, which is something you generally want to know. The durable remedy is ownership: whoever is driving the active task owns the current-state block for the duration, and everything else coordinates around that rather than writing over it. Ownership scales only so far. A small team, or a system where one slot maps cleanly to one unit of work, runs a single shared scratchpad without strain. Push past that, into several concurrent work streams or many agent instances contending for one slot, and the single record becomes a contention point, at which partitioning it, per developer, per feature, per conversation, per tenant, trades some of the shared-visibility benefit for writers that are not constantly colliding. The right granularity is the one that matches how the work actually divides, and it is worth choosing deliberately rather than defaulting to one slot until it starts generating collisions nobody planned for.

What the scratchpad may hold is decided before it is written to

Persisting a scratchpad persists whatever happens to be in it, and what is allowed in has to be settled before the writing, not regretted after it. The risk is not exotic. Under pressure, people and agents alike drop context into a working store fast, without stopping to ask whether it is safe to keep, and a scratchpad is precisely the sort of low-ceremony place that invites that reflex. Credentials, tokens, and keys must never land in it, because a persisted store outlives the moment. A secret committed to a versioned file is exposed to everyone who can read that history, and a secret written into a system’s datastore is exposed to every person and process with access to that store, and in neither case does deleting it afterward pull the exposure back. The same caution covers anything personal or sensitive about a user, which does not belong in a store more readers can reach than strictly need to.

Where the work means the scratchpad will routinely carry sensitive context, the answer is to constrain the slot deliberately rather than let its contents leak by default. Scope it tightly, put a retention limit on it, and record the choice where the next person will find it, so nobody later assumes the state is more widely visible, or more durable, than it is. Keeping secrets out needs a sturdier mechanism than any of that. A written rule is something that has to be followed on every write, forever, and one miss is permanent, so the control belongs at the write path instead: give the running agent no way to obtain the secret at all, or put a check on the write that refuses it. The distinction is worth the care: a policy that fails costs a bad decision later, and a secret that fails costs a secret. That constraint has a real cost. A scratchpad walled off for safety cannot carry knowledge between the people or agents walled off from it, so the coordination benefit is spent to buy the containment. The point is not that one setting is correct. It is that the trade between shared visibility and exposure should be made consciously, up front, and written down, rather than settled by accident the first time a secret lands somewhere it can never be fully removed from.

Left alone, a scratchpad becomes a graveyard

Every maintenance rule above converges on a single failure mode, the one that accounts for most of the ways a scratchpad goes wrong in practice. Entries pile up and none leave, and the record drifts into a ledger of every state the project has passed through, most of which it has already passed out of. Because the agent consumes that ledger as fact, the obsolete entries do not lie there inertly. They surface as live guidance. An approach ruled out a month ago gets proposed again; a convention that changed since gets applied in its retired form, and both arrive with full confidence, because the record offered no way to tell a living entry from a dead one. None of this is the agent malfunctioning. It is behaving exactly as a trusted state record demands, acting on the state it was handed instead of re-deriving it. The fault sits in the record, which stopped being authoritative while it was still being treated as authoritative.

This is why maintenance is not hygiene layered on top of the pattern but the condition the pattern depends on. What a scratchpad is worth at any given moment is simply how much of it still holds, and accuracy under sustained use is not something a store keeps on its own. It is produced, every session, by the same set of disciplines: a cap that keeps the record short enough to reason over, a structure that makes stale entries findable, a pruning policy that removes them at the moment they go obsolete, an explicit precedence that stops the record from overriding settled rules, and a deliberate stance on what the record is allowed to contain. Skip those, and the scratchpad does not stay neutral. It degrades into a graveyard that misleads with the same authority it was supposed to inform with, and past that point it is worse than having no scratchpad at all, because an agent with no memory at least knows it is starting cold. An agent reading a graveyard believes it is oriented, and it is oriented toward a project that no longer exists. The scratchpad is trivial to create and trivial to let rot, and the only thing standing between those two outcomes is the discipline to keep it true.