Recycling Context

24.1 The Case for Discarding #

Section 4.3 established the mechanism: models become more likely to err when the context contains their prior errors,⁸ multi-turn performance degrades roughly 39 percent driven by over-reliance on early assumptions,⁹ and the largest real failure category is a wrong belief formed early and never revisited.¹⁰ Section 12.1 established that performance degrades with input length independent of relevance.³⁵

Taken together, these say something uncomfortable: a long session accumulates commitment rather than understanding.

The corollary is that clearing context is no mere cost-saving measure trading away quality. On a session that has gone wrong, clearing context is the quality measure.

24.2 Four Operations #

Most harnesses perform the first automatically, and the second automatically at a threshold. The third and fourth remain manual, and that is where the judgment lives.

24.3 Compaction, and What It Silently Costs #

Compaction replaces older messages with a summary once the window fills. It is necessary, and it carries three costs that are routinely underestimated.

It breaks the cache, from the compaction point forward. The summary is different content in the same position, so everything after it is a miss on the next turn. Be precise about the scope, because “one full-price turn” overstates it in both directions. Tool definitions and the system block sit ahead of the replacement and can still be read from cache—Claude Code documents reusing the system-prompt layer across a compaction, and reloading project context from disk, which hits when the instruction files have not changed since session start.⁴⁸ And the replacement is a summary, so the rebuilt suffix is much shorter than what it replaced. The expensive request is usually the summarization call itself, not the turn after it—and that call reads your warm prefix too, unless the session has been idle past the cache lifetime, which is why /compact costs most on a long-resumed session. Expect a rebuilt suffix, not a cold request.

It loses conversation-only instructions. Vendor documentation warns that specific instructions given early in a conversation may not survive summarization.⁵³ Be precise about which of four things you mean because they behave differently: something said once in chat is summarized and can vanish; a request-level system field is re-sent on every call and is not part of the summarized history at all; a root instruction file may be re-read from disk and re-injected, which Claude Code documents doing after /compact; and a path-scoped rule reloads only when a matching file is next read.⁴⁸ Anything that must hold for the whole task belongs in a file the agent re-reads, not in a chat message—which is what the root-file behavior automates, and what the pattern below does by hand on hosts that do not.

It loses the wrong things. A summarizer optimizing for information density will drop the constraint you stated once in turn three because it appeared once and looked incidental.

The mitigation for the second and third is the practical heart of this section:

<!-- CONSTRAINTS.md — re-read by the agent at every task boundary -->
# Standing constraints for this task

These apply for the entire task and survive compaction because this file
is re-read, not remembered.

- Target Python 3.11. No 3.12+ syntax.
- Do not modify anything under `src/generated/`.
- Do not add dependencies.
- Every change must keep `make test` green. Run it before claiming done.
- If you cannot satisfy a constraint, stop and say so. Do not work around it.

Re-read CONSTRAINTS.md, then continue with step 4.

That one-line prompt issued after a compaction event is worth more than any amount of prompt engineering applied to the original message. It costs about 125 tokens (with the CONSTRAINTS.md), and it restores the constraints the compaction dropped.

Better still, the re-injection can be made automatic. Claude Code fires a SessionStart hook with a compact matcher after compaction completes, and plain text the hook writes to stdout is added to the context—the documented use for it is precisely this: reload primer context and re-inject project rules.⁴⁸ Note which event that is. A PostCompact event also exists, and carries the matcher distinguishing an automatic trigger from a manual one, but its stdout reaches only the debug log; the events whose output reaches the model are SessionStart, UserPromptSubmit, UserPromptExpansion, and PostModelSwitch. Registering this on PostCompact gets you a hook that runs, exits clean, and injects nothing. A hook fires on the event rather than on the model’s cooperation (§19.1), so moving constraint re-injection from a habit into a hook converts it from something you must remember into something that happens whether or not you do.

#!/usr/bin/env bash
# .claude/hooks/post-compact.sh - re-inject standing constraints after compaction.
# Registered under hooks.SessionStart, matcher "compact", in .claude/settings.json.
set -euo pipefail
[[ -f CONSTRAINTS.md ]] || exit 0
printf 'Standing constraints for this task, re-read after compaction:\n\n'
cat CONSTRAINTS.md
exit 0

The wider pattern generalizes past compaction. Any constraint you find yourself restating by hand after a predictable event is a candidate for a hook on that event, and the hook catalog covers session start, session end, prompt submission, and both sides of compaction.⁴⁸ A habit that depends on you remembering it is a control only while you remember it.

24.4 Deciding When to Reset #

The signals follow, in rough order of how strongly each argues for a clean start:

The second row is the underrated case. Finishing the migration work and moving on to the API refactor in the same session carries forty thousand tokens of migration context into a task where every one of them is a distractor.

24.5 Resetting Well #

A reset starts over with everything learned and none of the mess. The prompt below extracts that state to a file before the context is cleared.

<!-- The handoff pattern: write state to disk, then clear. -->

Before I clear the context, write a handoff to HANDOFF.md containing:

1. What we were trying to accomplish (2 sentences).
2. What is now done, with file paths.
3. What is left, as a numbered list.
4. Any constraint or decision we established that is not obvious from
   the code — especially anything we ruled out and why.
5. The exact command to verify current state.

Do not include narrative. Do not include anything I can read in the diff.

Then, in a fresh session:

Read HANDOFF.md and CONSTRAINTS.md. Then continue from item 1 of the
remaining work. Do not re-do anything listed as done.

This is a deliberate externalization of state from the context window into the filesystem, and it is the pattern behind every published account of long-horizon agentic work: specification, plan, implementation notes, and a running decision log live in repository files rather than in the window, with verification after each milestone.⁵⁴

Item four is what makes the handoff significant. “We ruled out approach X because it breaks the streaming path” is information that exists nowhere else and would cost the fresh session an hour to rediscover.

24.6 Pruning Specific Content #

Where the harness supports it, removing a single large tool result costs less than a full reset. The function below walks the history backward, keeps the most recent tool results intact, and replaces older oversized ones with a stub.

def prune_large_tool_results(messages, keep_bytes=2_000, keep_recent=3):
    """Replace oversized tool results with a stub, preserving the most
    recent ones. Invalidates cache from the first replacement onward."""
    out, tool_seen = [], 0
    for msg in reversed(messages):
        content = msg.get("content")
        if isinstance(content, list):
            new_blocks = []
            # Reversed here too. Parallel tool use puts several results in one
            # message (§4.2), so walking blocks forward inside a backward walk
            # over messages would preserve the oldest of a batch.
            for block in reversed(content):
                if isinstance(block, dict) and block.get("type") == "tool_result":
                    tool_seen += 1
                    size = len(str(block.get("content", "")).encode("utf-8"))
                    if tool_seen > keep_recent and size > keep_bytes:
                        block = {**block,
                                 "content": f"[pruned: {size} bytes, "
                                            f"re-run the tool if needed]"}
                new_blocks.append(block)
            msg = {**msg, "content": list(reversed(new_blocks))}
        out.append(msg)
    return list(reversed(out))

Both reversals are required, and the inner one is easy to omit. A turn that made three parallel tool calls comes back as one user message carrying three tool_result blocks, so “most recent” is an ordering within a message as well as across them; iterating blocks forward inside a backward walk preserves the earliest of a batch and prunes the newest, which is exactly backward. Restoring the original block order before returning keeps the rendered history readable. The threshold is measured on encoded bytes because len() on a Python string counts code points—for non-Latin text that is two to four times off the number the stub reports.

The stub text is doing that on purpose. Replacing content with an explicit marker that says what was there and how to get it back is materially better than deleting silently because the model can decide to re-fetch rather than reasoning as though the data never existed.

Two caveats apply. Pruning invalidates cache from the first modified position onward, so the next turn is expensive. And there is no published measurement that selective pruning outperforms full reset on software engineering tasks. The mechanism is sound and the benefit remains unmeasured. [unmeasured]

24.7 The Working Rhythm #

As a working habit, it goes like this:

That rhythm costs nothing to adopt, and it addresses the largest measured failure categories in agentic work directly.