D5 · Context & Reliability › Cluster 3 · Managing Long Conversations

3.5 · The Memory Tool / External Memory

Persist beyond the window

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.

🔑 Because memory is external files, it's the right home for facts that must survive exactly — names, IDs, decisions, progress logs — the very things a lossy summary (3.3) or a clear (3.4) would blur or drop.

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.

⚠️ Because you execute the file ops, security is your responsibility. A malicious path like /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.

Multi-session pattern: an initializer session writes a progress log + task checklist to /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

flowchart TD subgraph S1["Session 1 (context window A)"] A1["Claude learns a fact"] --> A2["tool_use: memory create
/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
Rule of thumb: use in-window strategies (3.2–3.4) to control what the model sees this turn; use external memory for what must persist across turns, windows, and sessions.

EXAM TRAPS

Trap: "The memory tool is server-side / Anthropic stores my memory." → It's client-executed. Claude requests file ops; your app runs them against storage you control. Nothing persists on Anthropic's side.
Trap: "Memory needs a beta header." → No — {"type": "memory_20250818", "name": "memory"} is generally available on the Messages API, no beta header, on Claude 4+.
Trap: Skipping path validation. → Because you execute the ops, a path like /memories/../../secrets.env can escape the directory. Enforce the /memories prefix and reject traversal — it's your responsibility.
Trap: Treating memory as a replacement for context editing. → They're complementary: context editing clears the window; memory preserves what must survive the clear. Long agents use both.

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.