CONCEPT A file-based tool that outlives the context window
Truncation, summarization, and context editing all operate inside the window — they decide what the model sees this turn. The memory tool reaches outside it: a file-based tool that lets Claude store and recall information across context windows and across sessions. Instead of keeping everything in context, the agent writes what it learns to memory files and reads them back on demand — just-in-time retrieval that keeps the active context focused.
Declare it as an Anthropic-provided tool — {"type": "memory_20250818", "name": "memory"} is the
entire configuration (no input schema to define). It's generally available on the Messages API — no beta
header required — on all Claude 4 and later models. When it's present, the API automatically injects a
system-prompt instruction telling Claude to check its memory directory before starting work.
CONCEPT Client-executed — you own the storage
The memory tool is client-side / client-executed. Claude only requests file
operations; your application executes each one against storage you control and returns the
result in a tool_result block — the standard tool-use loop. Operations target a
/memories directory, which is a prefix your handler maps onto real storage (a
per-user folder, database keys, cloud storage — your choice). The commands are:
view, create, str_replace, insert, delete, and
rename.
Persistence is entirely in your hands: a later conversation continues from the same memory when it
sends the same memory tool entry and your handler serves the same store. That's how memory bridges
sessions — nothing about it lives on Anthropic's servers.
/memories/../../secrets.env escapes the directory — validate every path:
require the /memories prefix, resolve to canonical form, reject ../ and URL-encoded
traversal. Don't let Claude write secrets/PII to memory.CONCEPT How it complements context editing
Memory and context editing (3.4) are designed to work together. Context editing clears stale tool results from the window to reclaim space; the memory tool preserves the information that must survive that clearing. The workflow: Claude writes durable facts to a memory file, then context editing (or compaction) safely prunes the raw transcript — because the important bits are already saved outside the window. Long-running agents typically use both.
/memories; each later session opens by view-ing those files to restore state without
re-exploring, and updates them before ending. Memory becomes the recovery mechanism across window resets.DIAGRAM Memory lives outside the window, across sessions
/memories/progress.md"] end A2 --> H["YOUR handler executes
the file op → your storage"] H --> STORE[("/memories
(your storage)")] subgraph S2["Session 2 (fresh window B)"] B1["Claude: view /memories first"] --> B2["Reads progress.md → resumes"] end STORE --> B1 STORE -.->|"survives context editing (3.4)
& compaction (3.3)"| KEEP["Durable facts persist
beyond the window"] classDef s fill:#d4edda,stroke:#28a745,color:#155724; classDef host fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class A1,A2,B1,B2,KEEP s; class H,STORE host;
CODE Declare the tool; you execute the file ops
Add the memory tool (no beta header), then implement a client-side handler for each command — validating
every path stays inside /memories.
# Memory tool is GA on the Messages API — no beta header needed. resp = client.messages.create( model="claude-opus-4-8", max_tokens=2048, tools=[{"type": "memory_20250818", "name": "memory"}], # whole config messages=messages, ) # Claude REQUESTS file ops; YOUR app executes them (client-side). import os MEM_ROOT = "/srv/app/memories" # /memories → real storage you control def handle_memory(cmd): # Path-traversal guard: reject anything that escapes /memories. real = os.path.realpath(os.path.join(MEM_ROOT, cmd["path"].lstrip("/"))) if not real.startswith(MEM_ROOT): return {"is_error": True, "content": "Error: path escapes /memories"} if cmd["command"] == "view": return read_file_or_dir(real) if cmd["command"] == "create": return write_file(real, cmd["file_text"]) # ...str_replace, insert, delete, rename → your storage # A LATER session that sends the same memory tool + same store # continues from these files — persistence beyond the window.
TRADE-OFFS External memory vs. in-window strategies
✅ Memory tool
- Persists across context windows and sessions — survives resets
- Exact recall of facts a summary would blur; just-in-time retrieval
- Complements 3.4/3.3 — prune the window, keep the knowledge
⚠️ What you take on
- You implement & secure the storage (path-traversal, size caps, PII)
- Reads/writes cost tool-use round-trips and tokens
- Only helps if Claude actually writes & re-reads the right files
EXAM TRAPS
{"type": "memory_20250818", "name":
"memory"} is generally available on the Messages API, no beta header, on Claude 4+./memories/../../secrets.env can escape the directory. Enforce the /memories prefix and
reject traversal — it's your responsibility.PRACTICE
Q1 · What makes the memory tool different from truncation, summarization, and context editing?
Those three manage what's inside the context window this turn. The memory tool stores information in external files that persist across context windows and sessions — Claude writes what it learns and reads it back on demand, so knowledge outlives any single window.
Q2 · Is the memory tool client- or server-executed, and what does that imply?
Client-executed. Claude only requests operations (view/create/str_replace/insert/delete/rename
on /memories); your application runs them against storage you control and returns a
tool_result. Implication: you own persistence and security — validate every path to prevent
traversal outside /memories.
Q3 · How does the memory tool complement context editing (3.4)?
Context editing clears stale tool results to reclaim window space; the memory tool preserves the facts that must survive that clearing. Claude writes durable info to a memory file, then editing/compaction safely prunes the raw transcript. Long-running agents use both together.