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

> AI agent memory is what an agent keeps when its context window fills up or a session ends. Compaction swaps the conversation for a summary. Tool-result clearing drops old tool output the agent can fetch again. A memory tool lets the agent write notes to files and read them in the next session. Each one handles a different kind of growth.

Mindket editors · Published 2026-11-06 · Updated 2026-11-06 · https://mindket.com/learn/context-engineering/agent-memory

## In short

- Find out what is filling the window before you choose a fix.
- Let old file reads go when the agent can open the file again.
- Name the figures a summary must carry, or expect them gone.
- Keep the memory folder small, sorted and free of secrets.

## Before you start

You need a working agent loop, like the one in [Build an AI agent with the Claude API](https://mindket.com/learn/claude-api/build-ai-agent-claude-api), and the reason long windows hurt accuracy from [the context rot lesson](https://mindket.com/learn/context-engineering/context-rot). 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](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/context_engineering/context_engineering_tools.ipynb) 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](https://github.com/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.

**Peak context in the cookbook's runs** Tokens in the window at the highest point of each run, as printed in the notebook. The two memory rows are a follow-up task, so compare them with each other.

- No context management: 335,279 tokens
- Tool-result clearing: 173,137 tokens
- Compaction: 169,164 tokens
- Second session, empty memory: 333,977 tokens
- Second session, with memory: 172,623 tokens

Source: [Claude cookbooks: Context engineering tools notebook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/context_engineering/context_engineering_tools.ipynb) (read 2026-11-06)

## 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.

| Setting | Compaction | Tool-result clearing | Memory tool |
| --- | --- | --- | --- |
| Type | `compact_20260112` | `clear_tool_uses_20250919` | `memory_20250818` |
| Beta header | `compact-2026-01-12` | `context-management-2025-06-27` | None |
| Fires when | Input passes `trigger`, 150K by default and 50K at least | Input passes `trigger`, 100K by default | The model calls it |
| Keeps | A summary of the whole conversation | The last 3 tool uses by default, set with `keep` | Whatever the agent chose to write |
| Gives up | Verbatim wording and rare specifics | Old results, until the agent fetches them again | A tool call for every read and write |

## 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.

````python
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](https://mindket.com/learn/claude-api/claude-prompt-caching), 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:

````python
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](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) 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](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)).
- OpenAI's Responses API compacts on the server once `context_management` sets a `compact_threshold`, or on request through `/responses/compact`. The [compaction guide](https://developers.openai.com/api/docs/guides/compaction) 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](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/automatic-context-compaction.ipynb) 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](https://mindket.com/learn/harness-engineering/long-running-agents) 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](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb) 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](https://mindket.com/blog/claude-md-file) 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.

| Command | What it does | Parameters |
| --- | --- | --- |
| `view` | Shows a folder or a file | `path` |
| `create` | Creates or overwrites a file | `path`, `file_text` |
| `str_replace` | Replaces text in a file | `path`, `old_str`, `new_str` |
| `insert` | Inserts text at a line number | `path`, `insert_line`, `insert_text` |
| `delete` | Deletes a file or a folder | `path` |
| `rename` | Renames or moves a file | `old_path`, `new_path` |

## 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](https://developers.openai.com/cookbook/examples/agents_sdk/session_memory) builds two custom sessions. One, `TrimmingSession`, subclasses the SDK's `SessionABC`, the [same base class](https://github.com/openai/openai-agents-python/blob/main/src/agents/memory/sqlite_session.py) as the `SQLiteSession` that [the Agents SDK lesson](https://mindket.com/learn/openai-api/openai-agents-sdk) 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](https://mindket.com/learn/context-engineering/just-in-time-context) covers it.

| If your agent has | Try first | Watch for |
| --- | --- | --- |
| Sessions that span days or weeks | Memory tool | Stale notes once facts change |
| Large tool results it can fetch again | Clearing | The agent re-reading what was just cleared |
| Mostly dialogue and reasoning | Compaction | Figures summarized away |
| Tool results it cannot fetch again, such as uploads | Compaction rather than clearing | How well the summary keeps those results |
| Sessions that stay well under the window | No compaction | Lost detail you did not need to lose |

## How Andrej Karpathy lets a model keep its own wiki

Andrej Karpathy, a founding member of OpenAI, [posted on 2 April 2026](https://x.com/karpathy/status/2039805659525644595) 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](https://x.com/karpathy/status/2040470801506541998) for your own agent to build from. [The gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 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](https://www.youtube.com/watch?v=eW3oTyfeWZ0) on Claude's own channel covers when to run `/compact` and when `/clear`.

> You rarely ever write or edit the wiki manually, it's the domain of the LLM.
>
> Andrej Karpathy, AI researcher and educator, a founding member of OpenAI, [X](https://x.com/karpathy/status/2039805659525644595) (read 2026-11-06)

[![Andrej Karpathy (@karpathy) on X, 2 April 2026, under the heading LLM Knowledge Bases: he has been using LLMs to build personal knowledge bases for topics of research interest.](https://mindket.com/blog/shots/x-karpathy-llm-knowledge-bases.webp?v=7550af1a0dcb)](https://x.com/karpathy/status/2039805659525644595)

Andrej Karpathy on X, 2 April 2026

[Context Management in Claude Code](https://www.youtube.com/watch?v=eW3oTyfeWZ0)

Claude's official YouTube channel on when to use /compact and /clear in Claude Code, published 18 May 2026.

> 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.

## Check yourself

1. An agent keeps re-reading files it could open again at any time, and those reads fill its window. Which tool fits first?

   A. Compaction
   B. Tool-result clearing
   C. The memory tool
   D. A bigger context window

   Answer: B. Clearing drops old results the agent can fetch again and keeps the record of each call, with no model call of its own.

2. What happens to the default compaction prompt when you pass your own instructions?

   A. Your text is added after it
   B. The API merges the two
   C. Your text replaces it completely
   D. It still runs for the first compaction

   Answer: C. Custom instructions replace the default prompt, so they must ask for state and next steps too.

3. Why add exclude_tools: ["memory"] when you combine clearing with the memory tool?

   A. So the agent keeps track of what it just saved
   B. So memory files are encrypted
   C. Because the memory tool needs its own beta header

   Answer: A. Without it, clearing can remove memory reads and writes, and the agent loses track of what it saved.

4. In the cookbook's research run, what did the compaction summary lose?

   A. Which animals the agent had read about
   B. Its next steps
   C. The facts central to the task
   D. Single cells from appendix tables

   Answer: D. The probe found all three central facts in the summary and none of the three appendix specifics.

## Frequently asked questions

### What is AI agent memory?

It is everything an agent carries past the limit of one context window or one session. Inside a session that means compaction and clearing old tool results. Across sessions it means notes the agent writes to files and reads back, such as the memory tool's `/memories` folder or Claude Code's `MEMORY.md`.

### What is the difference between compaction and a memory tool?

Compaction rewrites the current window as a summary, so it helps within one session and loses detail. A memory tool writes to storage outside the window, so notes reach the next session exactly as written, though only what the agent chose to save.

### Can context editing clear old thinking blocks too?

Yes, when extended thinking is on. The memory cookbook adds a `clear_thinking_20251015` edit with a `keep` count of thinking turns, and it has to come first in the `edits` list. Set `keep` to "all" when cache hits matter more than the room.

### Where does the memory tool store its files?

Wherever your code puts them. The tool is client-side: Claude sends commands such as `view` or `create` for paths under `/memories`, and your handler maps them to a folder, a database or cloud storage.

### Is Claude Code's auto memory the same as the memory tool?

No. One is part of Claude Code, which keeps its notes in a folder of its own unless you name another with the `autoMemoryDirectory` setting. The other is a tool in the Messages API, and your own handler decides where each file goes. They share one habit: an agent leaving notes for its next session.

## Sources

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

[Browse AI agents](https://mindket.com/agents)