AI Agent Memory: Notes, Compaction and Context Editing Compared

An agent that works for hours will eventually have more history than fits in its context window, and what it does at that point decides whether the job finishes. AI agent memory is the set of mechanisms that answer one question: when the window is full, what does the agent still know? There are three common answers. The agent can write notes to storage and read them back, the platform can summarize old turns, or the application can clear old tool results by rule. This guide compares them using the current Claude API documentation, because that documentation describes all three precisely. For the basics of the loop that fills the window, see how AI agents work.

Why a bigger window is not the whole answer

A context window is working memory. Anthropic's engineering team treats it as a finite resource and reports that a model's ability to accurately recall information from the context decreases as the context grows, which it calls context rot.^[2] Their stated goal is the smallest set of high-signal tokens that makes the desired outcome likely.^[2] That framing matches what we cover in long context windows: capacity versus reliability: fitting text in the window is a different property from using it reliably.

There is also a plain cost reason. Everything in the window is sent and billed on every turn of the loop; see tokens, context windows and what an AI request costs.

Mechanism 1: notes in external storage

The idea is old. The 2023 MemGPT paper proposed "virtual context management", borrowing from operating systems that move data between fast and slow memory so a system appears to have more memory than it does, and evaluated it on document analysis and multi-session chat.^[5] Anthropic's engineering post describes the same pattern as structured note-taking: the agent regularly writes notes to memory outside the context window and reads them back later. Their example is Claude playing Pokémon, keeping tallies, maps and strategy notes across thousands of game steps.^[2]

Anthropic ships this as the memory tool. The documented facts:

• Claude stores and retrieves information in a directory of memory files under /memories, and the files persist between sessions.^[1]
• It is client-side. Claude requests file operations and your application executes them against storage you control, such as a per-user directory or keys in a database.^[1]
• The tool entry is {"type": "memory_20250818", "name": "memory"}, and the documentation lists six commands: view, create, str_replace, insert, delete and rename.^[1]
• When the tool is present, the API adds a system instruction to view the memory directory first and to assume the context may be reset at any moment.^[1]

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Remember that Acme Corp prefers email follow-ups."}],
    tools=[memory],
)
print(runner.until_done().content)

This is the documentation's own Python example, shortened. Because you own the handler, you own the risks. The documentation warns that a path such as /memories/../../secrets.env can escape the directory unless every path in every command is validated, and recommends capping file sizes, expiring stale files and stripping sensitive data before writing.^[1] Our reading: treat the memory directory like any untrusted-writer input, because an agent that read a poisoned web page may write that content into its own memory. The security checklist in how AI agents work, and how to secure them applies directly.

The documentation also describes a pattern for work that spans many sessions: a first session sets up a progress log and a feature checklist, each later session starts by reading them, and each session ends by updating the log. It adds that a feature should be marked complete only after end-to-end verification.^[1]

Mechanism 2: compaction

Compaction replaces the older turns of a conversation with a summary that Claude writes on the server, so you need no summarization code of your own.^[3] The documentation describes two beta forms. With compaction on demand, you decide when by sending a request, and the returned block goes first in messages in place of the messages it summarizes; its beta header is compact-2026-09-04. With compaction at a token threshold, the API compacts when input tokens reach a trigger you set.^[3] A third option is your own summarizer on the client.^[3]

The trade-off is built into the word summary. Anthropic's engineering post says that when it compacts, Claude Code keeps architectural decisions and unresolved bugs while dropping redundant tool output, and advises first maximizing recall, then improving precision.^[2] The documentation notes you can write your own summarization prompt when the default summary drops something a later turn needs, and that recent turns can be kept word for word.^[3] Both are admissions that a summary can lose a detail the next step depends on.

Mechanism 3: context editing

Context editing clears content by rule instead of summarizing it. It is applied server-side before the prompt reaches Claude, so your client keeps the full history.^[4] Two strategies are documented (beta header context-management-2025-06-27):

• Tool result clearing (clear_tool_uses_20250919) clears the oldest tool results once a threshold is crossed and replaces each with placeholder text. Defaults: trigger at 100,000 input tokens, keep the 3 most recent tool use and result pairs. Options include clear_at_least, exclude_tools and clear_tool_inputs.^[4]
• Thinking block clearing (clear_thinking_20251015) manages thinking blocks from earlier assistant turns.^[4]

Caching matters here. The documentation says tool result clearing invalidates cached prompt prefixes when content is cleared, and recommends clear_at_least so each clear removes enough tokens to justify losing the cache.^[4] That is the practical cost of this mechanism: a smaller window, but a cache miss on the next call.

Side by side

The "what can go wrong" row for notes and the last row are our synthesis of the documented behaviour, not benchmark results. We did not run a test comparing them.

How to choose

1. Does the work span sessions or survive restarts? You need external notes. Neither compaction nor context editing is documented as cross-session storage.
2. Is one conversation simply getting long? Start with compaction, and write a custom summarization prompt if you can name what must never be dropped.
3. Are large tool outputs (search results, file reads) the bulk of the window? Context editing targets exactly that. Exclude tools whose output you will need again.
4. Is it a long-running agent? The memory documentation suggests both: compaction keeps the active context small, and memory preserves the information that must survive summarization.^[1]

Whichever you pick, evaluate it. A memory mechanism changes what the model sees, so the only reliable check is a task suite that runs to the length where you expect forgetting; see how to read an AI benchmark claim for why vendor numbers will not answer that for your workload.

What remains uncertain

Compaction and context editing are marked beta in the documentation we read on 2026-10-14, so parameters and defaults may change. We have not measured how much each mechanism degrades task success; the sources describe the designs, not comparative accuracy. If you rely on one, re-read the linked pages before deploying.