Out of the box, Claude forgets everything between API calls. If a support agent learns a customer's preferred name on Monday, it relearns it on Tuesday — unless you replay the whole prior conversation, which gets expensive fast. The memory tool solves this differently: it lets Claude read and write small files in a persistent directory called /memories, so durable facts ("the customer's fiscal year ends in March," "this team deploys on Thursdays") outlive any single session.
Crucially, this is a client tool. Claude issues memory commands; your application executes them against storage you own — a local directory, a database, an object store. Anthropic never hosts the memory contents. For enterprises, that means memory sits inside your existing data governance boundary, not a new one.
How it works
You declare the tool as {"type": "memory_20250818", "name": "memory"} (the name must be exactly memory, and there is no input schema to write). The tool is generally available on the Messages API with no beta header, on all Claude 4 and later models. When it is present, the API automatically injects a memory-protocol system prompt that instructs Claude to check its memory directory before doing anything else — so at the start of a task Claude will typically issue a view on /memories to see what it already knows.
Your handler must implement six commands: view (with an optional line range), create, str_replace (omitting new_str deletes the old text), insert, delete, and rename. A few implementation details from the official docs are worth building in from day one: view should truncate text files longer than 16,000 characters, and files over 999,999 lines should return an error.
Scoping memory to a user or workspace
Because you own the storage, scoping is entirely a mapping decision in your handler. The paths Claude sees always start with /memories; your code decides what that prefix points at. Map it per user (/data/memories/<user_id>/…) and each person gets a private memory. Map it per team or workspace and knowledge is shared. Map it per agent and you get task-specific memory. Claude never sees the real paths, so switching scopes requires no prompt changes.
/memories — a request for /memories/../../secrets.env must fail. The official docs are explicit that path-traversal defenses are your responsibility.Getting started quickly
The official SDKs ship helpers so you don't hand-roll the command dispatch: Python and C# provide BetaAbstractMemoryTool to subclass, and Python and TypeScript additionally include BetaLocalFilesystemMemoryTool, a ready-made local-directory backend that is fine for prototyping.
from anthropic import AnthropicBedrockMantle
client = AnthropicBedrockMantle(aws_region="us-east-1")
resp = client.messages.create(
model="anthropic.claude-sonnet-5",
max_tokens=1024,
tools=[{"type": "memory_20250818", "name": "memory"}],
messages=[{"role": "user",
"content": "Remember: our billing cutoff is the 25th."}],
)
# resp.content will include a tool_use block, e.g. a `create` or
# `str_replace` command targeting a path under /memoriesWhat belongs in memory (and what doesn't)
Memory works best for small, durable, high-value facts: preferences, conventions, project state, lessons learned. It is not a document store or a vector database — keep files short so view stays cheap. For long-running agents, the docs recommend pairing memory with context editing (client-side pruning of old tool results) and compaction (server-side summarization): memory holds what must persist, while the conversation window is trimmed aggressively. Also plan an inspection and retention story — memory files are model-written content, so treat them like any other user-adjacent data your compliance team may want to review or purge.
Platform availability
Because execution happens in your code, the memory tool is broadly portable: generally available on the first-party Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, and in beta on Microsoft Foundry. It is eligible for Zero Data Retention, which follows naturally from the design — the "memory" never leaves your infrastructure.
Where to go next
See context editing and compaction for the two context-management features memory is designed to pair with, or the feature matrix for platform-by-platform support.