AI agent memory: compaction, tool-result clearing and a memory tool

Before you start

You need a working agent loop, like the one in Build an AI agent with the Claude API, and the reason long windows hurt accuracy from the context rot lesson. The examples are Python 3.11 or later with the anthropic package and an API key.

Two words come up all the way through. A trigger is the input token count at which an edit fires. A tool result is the block your code sends back after it runs a tool, such as the text of a file the agent asked to read.

Watch a research agent fill its window

Anthropic's context engineering cookbook hands an agent eight synthetic review papers on animals used in aging research, about 40K tokens each, and asks for a comparison. With no context management, the run printed in the notebook climbed to 335,279 tokens in five turns. It used Claude Sonnet 5.5. Every paper the agent had already summed up in its own notes was still in the window on the last turn.

On a 1M-token window that run finishes, with the first paper buried under everything read since. On a model with a 200K window, the API rejects the next request and the task stops halfway. The notebook runs every variant against the same papers, so you see what each tool changes. Each run sends hundreds of thousands to over a million input tokens across its turns. The five turns of the unmanaged run alone add up to about 1.0 million, so check your API budget before you run them all.

1. Clone anthropics/claude-cookbooks and open tool_use/context_engineering/context_engineering_tools.ipynb with tool_use/context_engineering as the working directory.
2. Put ANTHROPIC_API_KEY in a .env file and install anthropic, python-dotenv and matplotlib.
3. Run the baseline cell and write down the peak context it prints.
4. Run the clearing, compaction and memory cells. Lines marked CLEARING or COMPACTION show the turn each edit fired.
5. Compare each peak with the baseline, then read the cell that lists what the run lost.

What each run kept, and what it lost

Clearing fired four times. Each time it swapped old file contents for a short placeholder and kept the record that the read happened. By the end, seven of the eight papers were gone from the window, so the agent had to work from its notes or read them again.

Compaction fired once, on turn 4, and replaced everything before it with a summary of about 2,783 tokens. The run ended at 5,829 tokens. The notebook then searched the summary for six facts. The three central to the task survived, such as which animal is the shortest-lived vertebrate in the set. The three single cells from appendix tables did not.

Memory solves a different problem. A second session with an empty memory folder read all eight papers, including the four the first session had already read. With the first session's notes in /memories, it read four and peaked at 172,623 tokens.

Three tools for three kinds of growth

Compaction works on the whole transcript: user turns, the agent's reasoning, tool calls and their results all go into one summary. Clearing is narrower. It walks the message list and replaces only the contents of tool_result blocks, which costs no model call. The memory tool moves information out of the window altogether, into files your code stores.

Turn on all three in one request

The cookbook's last run layers the three. These settings are copied from it, with both triggers set above the first batch of reads so each edit fires late enough to see. Add {"type": "memory_20250818", "name": "memory"} to tools and handle the memory commands in your own code.

COMBO_CLEARING_TRIGGER = 200_000
COMBO_COMPACTION_TRIGGER = 180_000

betas=["context-management-2025-06-27", "compact-2026-01-12"],
context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": COMBO_CLEARING_TRIGGER},
            "keep": {"type": "tool_uses", "value": 6},
            "clear_at_least": {"type": "input_tokens", "value": 30_000},
            "exclude_tools": ["memory"],
        },
        {
            "type": "compact_20260112",
            "trigger": {"type": "input_tokens", "value": COMBO_COMPACTION_TRIGGER},
        },
    ],
},

• exclude_tools: ["memory"] keeps clearing away from the memory reads and writes. Without it the agent can lose track of what it just saved.
• clear_at_least makes every clearing free a minimum number of tokens. Clearing changes the prompt prefix and breaks the prompt cache, so a bigger cut pays for the new cache write.
• In the printed run, clearing first fired at turn 5 and then on every later turn. Compaction ran once, on that same turn 5, and summarized what was left in about 2,839 tokens, and the agent saved three notes files to /memories. It finished in 13 turns at 13,749 tokens.

Tell compaction what to keep

A summary keeps what its prompt asks for. The default prompt asks for "the state, next steps, learnings etc." inside a summary block. Pass instructions and your text replaces that prompt completely, so it must ask for state and next steps as well as the details your task cannot lose.

For the research agent, the cookbook's version names the figures the probe found at risk:

context_management={
    "edits": [{
        "type": "compact_20260112",
        "trigger": {"type": "input_tokens", "value": 150_000},
        "instructions": (
            "Summarize this research agent transcript. Preserve every "
            "quantitative lifespan figure and effect size with its "
            "source organism, and note which documents have been read "
            "and which remain. Wrap the summary in <summary></summary>."
        ),
    }]
}

• Claude Code summarizes the history and keeps architectural decisions, unresolved bugs and implementation details, then carries on with the five most recently accessed files, as Anthropic's context engineering article describes.
• Since version 2.1.299, Claude Code also compacts a conversation of 200K tokens or more that sits idle for about 54 minutes, before its one-hour prompt cache expires (CHANGELOG).
• OpenAI's Responses API compacts on the server once context_management sets a compact_threshold, or on request through /responses/compact. The compaction guide says the compaction item it returns is encrypted and opaque, so you cannot read it to check what was kept.
• Keep the trigger well above the size of a summary. The compaction cookbook warns that a trigger set too low lets the summary itself start another compaction.

Let the agent write its own notes

The memory tool gives Claude a folder, /memories, and six commands. Claude decides what to save and when, and your code carries out each command on storage you control. The API adds a system prompt that sets the habit, "ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE", so a fresh session opens by reading what the last one left.

Notes are only as good as what the agent chose to write. Two lines from the cookbook steer it. The first tells the agent to write down only information relevant to a topic you name. The second, for a folder that keeps sprawling, asks it to keep the content "up-to-date, coherent and organized" and lets it rename or delete files that are no longer relevant. For work across many sessions, a first session can lay out a progress log and a checklist before any real work, the pattern the long-running agents lesson builds on.

Treat the folder as untrusted input. Memory files go back into Claude's context, so text planted in them works like a prompt injection. The memory cookbook says to validate every path so ../ cannot escape the folder, and to keep passwords, API keys and personal data out. Give each user or project its own folder.

Claude Code runs two memory systems side by side. CLAUDE.md holds the rules you write and commit, as the CLAUDE.md guide shows. Auto memory holds what Claude writes for itself: since version 2.1.59 it saves useful context on its own, managed with /memory. Its MEMORY.md index is cut at 200 lines or 25KB, and since 2.1.75 memory files carry last-modified timestamps so Claude can tell fresh notes from stale ones.

Trim or summarize the chat itself

A chat app runs into the same wall with no files at all, because the conversation itself grows. OpenAI's session memory cookbook builds two custom sessions. One, TrimmingSession, subclasses the SDK's SessionABC, the same base class as the SQLiteSession that the Agents SDK lesson sets up. It keeps the last N user turns, eight by default, and drops the rest. The other, SummarizingSession, is a plain class with the same four methods. It keeps a few recent turns word for word and folds the older ones into a summary once the chat passes context_limit turns.

Trimming is predictable. It adds no latency, but the user meets sudden amnesia about anything older. A summary keeps long-range memory at the price of a model call at each refresh, and it can carry a wrong fact forward turn after turn, which the cookbook calls context poisoning. Its advice: trim for tool-heavy, independent tasks, and summarize for long planning or analysis threads.

Pick by what fills the window

Ask which problem your agent has before you add a tool, since each layer brings settings to tune and interactions to trace. The cookbook maps workloads to a first choice:

Leave memory out when every session should start fresh, as in a chatbot for the public where each conversation must stay independent. Leave compaction out when sessions fit easily, because you would trade detail for room you never use. Leave clearing out when the agent compares passages side by side and cannot re-read its way back fast enough. Loading less in the first place is the other half of the job, and just-in-time context covers it.

How Andrej Karpathy lets a model keep its own wiki

Andrej Karpathy, a founding member of OpenAI, posted on 2 April 2026 about knowledge bases that an LLM builds for him. Source articles and papers go into a raw/ folder, and the model compiles them into a wiki of Markdown files with summaries, concept pages and links. His research wiki had grown to about 100 articles and 400K words. He had expected to need fancy RAG, yet the model kept index files and short summaries well enough to find what it needed at that size.

Two days later he shared the idea as a file for your own agent to build from. The gist adds an index.md the agent reads first, an append-only log.md and a schema file such as CLAUDE.md or AGENTS.md. That is the shape that makes /memories hold up: an index read first, notes the agent owns and a regular lint pass for contradictions and stale claims. Give your memory folder all three before it holds more than a handful of files.

For the Claude Code side, a short video on Claude's own channel covers when to run /compact and when /clear.

A screenshot of X's own embed of the post, taken on 6 November 2026, with the time in UTC. X cuts the post short with Show more. Select it to open the post on X.

Common mistakes

• Clearing the memory tool's own results along with the rest, so the agent forgets what it saved a turn ago.
• Writing compaction instructions as one extra line. They replace the default prompt, so state and next steps vanish unless you ask for them.
• Combining a context_management compaction edit with runner.compact_before_next_turn(). The tool runner refuses, so pick one per runner.
• Reading memory files back as trusted instructions, or letting API keys and personal data land in them.
• Compacting short tasks or ones that need a full audit trail, where the lost detail matters more than the room gained.
• Pruning the window OpenAI's /responses/compact returns instead of passing it on whole.

Try it yourself

• Run the cookbook's clearing cell twice, with keep at 4 and at 8. How many file reads does the agent repeat?
• Write compaction instructions that keep one appendix figure, then check whether the summary still holds it.
• Delete exclude_tools from the all-three settings and watch what the agent does after a clearing fires.
• Open Claude Code's /memory in one of your projects and read what auto memory has saved so far.

Frequently asked questions

Sources

1. Claude cookbooks: Context engineering tools notebook (read November 6, 2026)https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/context_engineering/context_engineering_tools.ipynb
2. Claude cookbooks: Context editing and memory for long-running agents (read November 6, 2026)https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb
3. Claude cookbooks: Automatic context compaction (read November 6, 2026)https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/automatic-context-compaction.ipynb
4. Anthropic Engineering: Effective context engineering for AI agents (read November 6, 2026)https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
5. Claude Code CHANGELOG on GitHub (read November 6, 2026)https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
6. OpenAI API docs: Compaction (read November 6, 2026)https://developers.openai.com/api/docs/guides/compaction
7. OpenAI Cookbook: Short-term memory management with sessions (read November 6, 2026)https://developers.openai.com/cookbook/examples/agents_sdk/session_memory
8. GitHub: openai-agents-python, sqlite_session.py (read November 6, 2026)https://github.com/openai/openai-agents-python/blob/main/src/agents/memory/sqlite_session.py
9. X: Andrej Karpathy on LLM knowledge bases (read November 6, 2026)https://x.com/karpathy/status/2039805659525644595
10. X: Andrej Karpathy shares the LLM Wiki idea file (read November 6, 2026)https://x.com/karpathy/status/2040470801506541998
11. GitHub Gist: Andrej Karpathy, LLM Wiki (read November 6, 2026)https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
12. YouTube: Claude, Context Management in Claude Code (read November 6, 2026)https://www.youtube.com/watch?v=eW3oTyfeWZ0