Own memory beyond the active window

Learning objective

Persist durable knowledge outside the window with memory files or external stores for long-horizon tasks.

Core idea

Verified findings and recovery indexes can already live outside conversation history. The Professional decision is how a production agent’s durable store is scoped, retrieved, updated, and retired across sessions and users, and which team owns those operations.

Anthropic’s memory tool requests file operations; your application executes them against storage you control. Persistence does not imply automatic correctness or unlimited active context. A useful memory system keeps recoverable knowledge outside the window and brings only the relevant, qualified portion back for the next task.

How it works

Select a memory surface and storage owner

In a Claude API request, add {"type": "memory_20250818", "name": "memory"} to tools. The name must be memory; an Anthropic-provided tool does not need a custom input_schema. The memory tool is available on all Claude 4 and later models. The memory tool requires no beta header, although SDK helpers and tool-runner interfaces live in beta namespaces.

Claude requests operations in tool_use, with input.command and a path under /memories. Your handler maps that logical prefix to real storage and returns a tool_result. Later conversations use the same memory only when they include the tool and the handler serves the same store. A model invocation alone does not provide your application with a durable backend.

Choose local files when one durable runtime and a simple operational owner fit the task. Choose an external store when replacement runtimes need the same knowledge or when your access and retention policies require centrally managed storage. The memory-tool interface can be backed by files, a database, cloud storage, or encrypted files; the storage service and policies remain yours. This is an architectural option for a production Claude system, not a requirement to use a particular database.

Python and C# provide BetaAbstractMemoryTool; TypeScript provides betaMemoryTool; Java provides BetaMemoryToolHandler. Python and TypeScript also offer BetaLocalFilesystemMemoryTool. The helper implements an interface and loop, not the organization’s storage policy. In Go and Ruby, the documentation uses a manually implemented tool loop; PHP uses a handler with BetaRunnableTool. Verify the helper for the deployed language before assuming one SDK’s name exists in another.

Claude Code provides a different surface: CLAUDE.md holds human-written persistent instructions, and auto memory holds Claude-written learnings. Both are context rather than enforced configuration. Do not equate those coding-session mechanisms with the API’s client-side /memories handler. See 7.1.1 for project instructions; this lesson concerns storage decisions for long-horizon work.

Retrieve a useful subset

Anthropic’s structured-note-taking pattern persists notes outside context and pulls them back later. Its just-in-time approach keeps lightweight identifiers rather than preloading all material. Design the store around the queries the next session must answer: what is complete, what remains unresolved, and which source establishes the finding?

Use the view command to inspect memory and its optional view_range: [start_line, end_line] parameter to page through a text file. Set storage-size limits and cap the content a view returns, as the memory documentation recommends. The application can keep extensive source material in its own archive while the note contains a compact conclusion and a source pointer. Loading the entire archive on every turn recreates the context pressure that external storage was meant to reduce.

For a software delivery spanning sessions, Anthropic documents an initializer that creates a progress log and feature checklist, subsequent sessions that read them, and an end-of-session update. Completion is recorded after end-to-end verification, not merely after code is written. Extend that discipline to other long-horizon work: record a verified outcome separately from a proposed next action, and preserve unresolved work instead of summarizing it as complete.

Memory retrieval still consumes input and tool turns. Measure the repeated view volume against the request budget in 2.4.1. If every lookup loads the same large file, split retrieval by topic or range rather than compensating with more frequent compaction.

Make scope and expiration executable

The handler, not a requested path, selects the user’s or task’s real backing store. For a multi-tenant deployment, derive that binding from authenticated application context. Keep a proposed tenant identifier inside a memory note from selecting another tenant’s storage. This binding is an application design built on the documented per-user directory or database-key mapping; see 3.2.2 for tenant authorization.

Validate every path for every operation. Checking only that text starts with /memories is insufficient: /memories/../../secrets.env can escape it. Canonicalize paths and verify they remain inside the mapped root; reject traversal forms and encoded variants. Apply the same boundary to both source and destination on rename. The documented rename operation must reject renaming the memory root and must not overwrite an existing destination.

The memory documentation recommends stripping sensitive content through handler validation, tracking file sizes, and periodically deleting files not accessed for a long time. Specify those rules in the backend’s write and cleanup paths rather than relying solely on the model’s usual refusal to save sensitive information. The storage owner defines accepted content, size caps, and expiration; the application owner defines which expired findings must be fetched again. See 5.4.2 for GDPR obligations affecting memory retention and minimization.

A saved conclusion can outlive its source revision. Before using it for a consequential decision, retrieve the source identified by the note and check the relevant version. Preserve its scope and uncertainty while updating the note. Memory should accelerate recovery of an observation, not silently promote that observation into permanent policy.

Preserve visibility of storage failures

A failed write is not a successful checkpoint. Return the documented error text in tool_result.content with is_error: true and the matching tool_use_id. Keep the unresolved persistence operation visible so the agent can recover instead of telling a successor that progress was saved. Claude requests each memory operation; your handler executes it against storage you control and returns a failed write as an error.

Compaction and memory solve complementary problems: compaction manages active history, while memory retains information beyond that history. With context editing and the memory tool together, Claude receives a warning near the clearing threshold to preserve important information. That warning enables a save attempt; the handler’s successful result establishes that it actually happened. See 2.4.3 for choosing the reduction path.

Key distinctions and trade-offs

Stored versus loaded: Persistence makes knowledge recoverable. A successful view makes selected knowledge available for inference.

Memory versus authority: A note records a finding or decision; its source and qualification determine whether it can support the next action.

Files versus external storage: Files minimize infrastructure for a suitable runtime. External storage supports shared operational policies and replacement runtimes while adding access, availability, and lifecycle responsibilities.

Longer retention improves continuity but increases stale knowledge and storage exposure. More aggressive expiration keeps the store smaller but adds source retrieval and can lose useful learning. Choose the retention policy alongside the task’s recovery requirements, not as a side effect of a model-generated filename.

Architecture / decision scenario

An education provider uses an agent to prepare course revisions across a six-week cycle. Replacement workers must resume within two minutes, and notes must remain isolated by customer institution. In an illustrative recovery trial, rebuilding context from transcripts takes eighteen minutes; reading a 1,500-token progress record plus two source passages takes forty seconds.

The tempting alternative is one shared local memory directory with every transcript pasted into it. That couples recovery to one runtime, mixes institutions, and recreates excessive context on read. The architect instead maps /memories to institution-scoped external keys selected by authenticated application context. The record holds verified progress and source pointers; view_range retrieves detail only when required.

The platform owner implements canonical path validation, sensitive-content filtering, view-size caps, and expiration. A course owner verifies outcomes before the checklist marks them complete. If a write fails, is_error: true leaves the checkpoint unresolved. A replacement reads the progress record, checks changed source revisions, and continues the unfinished scope; it does not inherit an obsolete course rule solely because a memory file repeats it.

Common exam traps

Avoid these memory mistakes:

• Assuming enabling the tool supplies hosted storage.
• Treating beta helper names as a required memory-tool beta header.
• Loading every saved note on every request.
• Binding the storage scope from agent-supplied tenant text.
• Checking a path prefix without canonical containment.
• Reporting a checkpoint as saved after a failed tool result.
• Treating a durable note as an always-valid source of truth.

What to remember

Durable memory needs a scoped backend, a selective read path, validated writes, and an expiration owner. Save verified progress with recoverable sources, confirm successful persistence, and refresh changed observations before relying on them.

Knowledge check

References

• Anthropic, Memory tool
• Anthropic, Effective context engineering for AI agents
• Anthropic, How Claude remembers your project
• Anthropic, Context editing