Memory and context

Name the failure before you fix it - same habit as the levers in b1:

• Overflow - a long task (big tool results, many turns) exceeds the window. Symptoms: API errors, truncated inputs, sudden quality cliffs late in a run. Loud, easy to spot.
• Eviction - to keep running, old turns get dropped or trimmed. Symptoms: the agent re-fetches things it already knew, contradicts its own earlier finding, or ignores an instruction given at turn 1. Quiet, easy to miss - this is the memory-off signature you will reproduce in the demo.

Bigger windows delay the problem; they do not remove it. Three reasons the toolkit still matters:

• Cost and latency scale with context - every turn re-reads the whole history. A lean context is a cheaper, faster agent.
• Long tasks are unbounded - an agent that monitors tickets all day will outgrow any window eventually.
• Runs end - the window empties when the process exits. Anything the agent should know NEXT run needs long-term memory: a store, a file, a session - never the window itself.

Compaction is one extra API call: when the estimated token count crosses a threshold, ask the model to summarize the history - keeping every number, finding and standing instruction - then replace the old turns with that summary and continue. Bolt this onto your b2 loop:

from anthropic import Anthropic

client = Anthropic()
THRESHOLD = 8000  # rough token budget before we compact

def estimate_tokens(messages):
    return sum(len(str(m["content"])) for m in messages) // 4

def maybe_compact(messages):
    if estimate_tokens(messages) < THRESHOLD:
        return messages
    transcript = "\n".join(f"{m['role']}: {m['content']}" for m in messages[:-4])
    summary = client.messages.create(
        model="claude-opus-5",
        max_tokens=500,
        messages=[{"role": "user", "content":
            "Summarize this agent transcript for the agent itself. "
            "Keep EVERY number, finding, and standing instruction:\n\n"
            + transcript}],
    ).content[0].text
    return ([{"role": "user",
              "content": "[Summary of earlier turns]\n" + summary}]
            + messages[-4:])  # keep the freshest turns verbatim

The summarize-then-continue trade: you spend one call and lose verbatim detail, but the numbers, findings and instructions travel forward instead of falling off the edge. The summary prompt is the whole game - "keep every standing instruction" is what saves "exclude refunds".

A scratchpad moves key findings OUT of the message history entirely. The agent appends findings to a notes list (or a file), and the loop injects the notes into the system prompt every turn - so even aggressive trimming cannot evict them:

notes = []  # lives OUTSIDE messages - trimming cannot touch it

def remember(finding):
    notes.append(finding)  # e.g. "Feb completed revenue = $271"

def system_prompt():
    return (BASE_PROMPT
        + "\n\nScratchpad - re-read before every step:\n"
        + "\n".join("- " + n for n in notes))

# in the loop: expose remember() as a tool, and rebuild
# the system prompt from notes on every messages.create call

Expose remember as a tool and the agent decides what is worth keeping - the same move Anthropic's memory tool and file-based agent memory make. Write one note per confirmed finding, not per raw tool result, or the scratchpad becomes a second overflowing context.