Claude's Memory Tool + Context Editing: Agent Memory That Survives the Context Window

Give an agent a real job — audit a repo, work a support queue, run research over dozens of sources — and it hits the same wall every time: the context window fills up. Each tool call, each search result, each file it reads gets stapled to the conversation, and eventually the run either gets truncated, starts forgetting the beginning, or dies outright on context exhaustion. A bigger window buys you time, but you still pay to carry all of that on every single turn, and the useful signal drowns in old tool output you no longer need.

Anthropic's answer is two features that attack the problem from opposite ends. Context editing throws away what the agent no longer needs from the active conversation. The memory toolkeeps what it will need later — outside the context window, in files. I run an agent whose entire cross-session brain is a directory of small markdown files plus an index it reads first, so I've lived in this pattern daily. Let me break down both.

The memory tool lets Claude create, read, update, and delete files in a dedicated /memories directory that persists between conversations. The important design choice: it runs client-side. Claude never touches your disk — it requests an operation, your application executes it against whatever storage you control, and you hand the result back in a tool result block. That store can be a folder on disk, rows in a database, encrypted blobs in cloud storage — Claude only sees the /memories prefix.

Wiring it up is almost anticlimactic. The entire tool configuration is one entry — no input schema, and on the Messages API no beta header:

const message = await anthropic.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 2048,
  messages: [{ role: "user", content: "Help me with this ticket." }],
  tools: [{ type: "memory_20250818", name: "memory" }],
});

Your side of the deal is a handler for six commands: view, create, str_replace, insert, delete, and rename. If you don't want to write those by hand, the Python and TypeScript SDKs ship a ready-made local-filesystem implementation you can point at a directory and be done. The tool is generally available and works on every Claude 4 and later model.

What makes it more than a scratchpad is just-in-time retrieval. When the tool is present, the API quietly prepends a protocol to the system prompt that tells Claude to view its memory directory before doing anything else, and to write progress back as it works. So the agent checks memory at the start of a task, reads back only the files relevant to what it's doing, and leaves the rest on disk. The active context carries a two-line directory listing instead of everything the agent has ever learned. That's the whole trick: knowledge lives in files, and only the slice you need for this step ever enters the window. It's the same “keep state out of the prompt” discipline I leaned on when MCP tool definitions were quietly eating my context window.

Memory handles what to keep. Context editing handles what to throw away. As a conversation approaches its token limit, context editing automatically removes stale tool calls and their results from the working context while preserving the conversation flow. The searches from turn three that you already summarized, the file you read and acted on forty turns ago — that bulk gets cleared so the run can keep going instead of choking on its own history.

The numbers are the reason to care. In Anthropic's 100-turn web-search evaluation, context editing let agents finish workflows that would otherwise have failed on context exhaustion, and cut token consumption by 84%. On their internal agentic-search tasks, context editing alone gave a 29% performance lift, and combining it with the memory tool pushed that to 39%. That performance gain is the counterintuitive part: trimming context doesn't just save money, it makes the agent better, because the model isn't hunting for the relevant fact buried under ninety turns of dead tool output.

Worth knowing: context editing is a client-side clearing of specific tool results, which is different from compaction, a separate feature that summarizes the whole conversation server-side when it nears the window limit. They're not rivals — on a genuinely long agent you can run both, letting compaction shrink the running history while memory preserves the facts that must survive any summary.

Here's the catch of a client-side tool: your application executes every file operation Claude asks for. If you naively join the path Claude sends onto your storage root, a request for /memories/../../.env walks straight out of the memory directory and into your secrets. This is the classic path-traversal attack, and it is on you, not Anthropic, to block it.

The rule is simple and non-negotiable: resolve every path to its canonical form and confirm it still lives inside /memories before you touch disk. Reject ../ sequences, watch for URL-encoded variants like %2e%2e%2f, and use your language's real path utilities rather than string matching:

import path from "node:path";

const ROOT = path.resolve("/srv/agent-memory");

function safePath(requested: string): string {
  const resolved = path.resolve(ROOT, "." + requested); // strip leading /
  if (resolved !== ROOT && !resolved.startsWith(ROOT + path.sep)) {
    throw new Error("path escapes /memories");
  }
  return resolved;
}

While you're there, add the boring guardrails too: cap how large a memory file can grow, strip anything sensitive before it's written (Claude usually refuses to store secrets, but “usually” isn't a control), and expire files that haven't been read in a long time. Get path validation right and the memory tool is production-safe; skip it and you've built a remote file-read primitive for anyone who can talk to your agent. If you've read my take on putting real cost controls on autonomous loops, this is the same mindset: assume the loop will do the wrong thing, and make the wrong thing impossible.

Not every agent needs this. A single-shot call, a short tool loop that finishes inside one window — leave it alone, memory is overhead you won't use. Reach for these two when the shape of the work matches:

• Turn on context editing the moment an agent's runs get long enough to bump the window — research agents, multi-file code work, anything with heavy tool output. It's the cheapest win here: less spend, longer runs, and usually better answers.
• Add the memory tool when work spans multiple sessions and the next run genuinely needs to resume — a project the agent returns to, a support context that accumulates, preferences it should learn once and reuse.
• Use the multi-session pattern for software work: an initializer session writes a progress log and a feature checklist to memory, and every later session reads them first, works one feature, verifies it end-to-end, then updates the log before it exits.
• Skip both for stateless, high-volume, one-and-done calls where per-request memory would only add latency and a storage bill.

The mistake I see most is reaching for a bigger context window when the real fix is architectural. If your agent keeps running out of room, the answer usually isn't “pay to carry more” — it's “stop carrying what you don't need.” That's the same lesson behind what a subagent actually costs you in tokens: the win is in what never enters the window in the first place.

• The memory tool (memory_20250818) gives an agent files in /memories that persist across conversations — client-side, all Claude 4+ models, GA on the Messages API with no beta header.
• It's just-in-time retrieval: the agent reads back only the memory files relevant to the current step, so knowledge lives on disk, not in the window.
• Context editing auto-clears stale tool results near the token limit — 84% fewer tokens on a 100-turn run, plus a 29% quality lift on its own and 39% paired with memory.
• Pair them: context editing forgets the raw noise, memory keeps the distilled signal — write to memory before the cleanup clears it.
• The must-not-ship bug is path traversal: validate every path resolves inside /memories before touching disk. This is your responsibility, not the API's.
• Skip both for short, stateless calls; reach for them when runs get long or work spans sessions.

If you want the full tool-loop mechanics that sit underneath all of this, my production walkthrough of building AI agents with the Claude API covers how tool calls, results, and the loop actually fit together, and Anthropic's own memory tool documentation has the exact command specs and security notes.