What it is
The memory tool gives an agent you build on the Claude API a place to write down what it learns, and to read it back in a later session. Claude can create, read, update and delete files in a directory that persists between conversations, so it builds up knowledge over time without keeping everything in the context window. Anthropic frames it as just-in-time context retrieval: instead of loading everything up front, the agent records what it learns and reads it back on demand.
You add it with one line in tools:
{"type": "memory_20250818", "name": "memory"}
That is the whole configuration. The name must be memory, and you do not define an input schema because it is an Anthropic-provided tool.
How it runs
The tool is client-side. Claude asks for an operation; your application performs it and returns the result in a tool_result. The /memories path is a prefix your handler maps onto real storage: a folder per user, keys in a database, cloud storage, encrypted files. When the tool is present, the API adds an instruction to the system prompt telling Claude to view its memory directory before doing anything else and to record progress as it goes, assuming its context window can be reset at any moment.
| Command | What it does |
|---|---|
| view | Lists the directory (two levels deep) or shows a file with line numbers |
| create | Creates a file (Claude’s description says “creates or overwrites”) |
| str_replace | Replaces an exact, unique piece of text in a file |
| insert | Inserts text after a given line |
| delete | Deletes a file or directory, never the /memories root |
| rename | Renames or moves a file or directory |
The Python and TypeScript SDKs ship a ready-made local-filesystem version, BetaLocalFilesystemMemoryTool. Python and C# let you subclass BetaAbstractMemoryTool to back it with your own storage; TypeScript has betaMemoryTool, Java BetaMemoryToolHandler.
What you are responsible for
Because your application runs every file operation, the safeguards are yours:
- Path traversal. A path like
/memories/../../secrets.envcan reach files outside the directory. Validate every path, resolve it to canonical form and reject anything outside/memories, including URL-encoded variants. - Sensitive data. Claude usually refuses to write sensitive information to memory, but for guarantees you add your own filtering before writing.
- Size. Cap file sizes and how much
viewreturns; let Claude page through withview_range. - Expiry. Delete memory files that have not been used in a long time.
Pair it with compaction or context editing
For long-running agents Anthropic suggests combining tools. Compaction summarizes the conversation on the server when it nears the context limit; context editing clears specific tool results on the client. The memory tool keeps what must survive that summarizing. For multi-session software work the documentation describes a pattern: a first session sets up a progress log and a feature checklist, every later session starts by reading them, and each session ends by updating the log.
Anthropic gives numbers from its own internal agentic-search evaluation: context editing alone improved performance by 29 percent, and combining the memory tool with context editing improved it by 39 percent over baseline. In a 100-turn web search, context editing cut token consumption by 84 percent. These are the vendor’s measurements, not independent ones, but they show that the largest gain came from using the memory tool together with context management. The memory tool also works on its own.
The misunderstanding: this turns on memory in Claude
Developers sometimes expect that adding the memory tool makes the Claude app remember things, or the other way round. They are separate. Memory in the Claude app (Settings > Your Claude) is stored by Anthropic and managed by the user; see does Claude have memory. With the memory tool, the memory files live in your storage; contents Claude reads are returned as tool results and sent back to the API. A later conversation continues from the same memory only when it sends the same tool and your handler serves the same store.
What this means for a team
The memory tool gives you full control over where memory lives, which is useful for compliance: Anthropic lists it as eligible for zero data retention. But it is a file interface, not a memory system. Deciding what is worth remembering, who may read which file, how two agents avoid overwriting each other, and how a correction from one user reaches the others is all left to your code. Each agent you build gets its own pile of files unless you design otherwise. Background on the wider pattern: what is AI agent memory and a memory layer for AI agents.
Where Bombos fits
If you are building your own agents, the memory tool is the socket and Bombos can be what plugs into it. Bombos is a plugin that gives every AI tool a team uses, your own agents as well as Claude, Claude Code, ChatGPT, Copilot and Cursor, one shared memory with team knowledge, rules learned from corrections and what already lives in mail, documents and repos, traceable to its source, in the cloud or on your own server. One person can try it first for their own agents.
Related questions
Is the memory tool the same as memory in the Claude app?
No. Memory in the Claude app is a product feature Anthropic stores for you. The memory tool is an API building block: the files live in your own application and storage.
Does the memory tool need a beta header?
No. The tool itself does not require a beta header. The SDK helpers and the tool runner live in the SDKs' beta namespace.
Which models support it?
Anthropic's documentation says the memory tool is available on all Claude 4 and later models, on the Claude API and on Amazon Bedrock, Google Cloud and Microsoft Foundry.
Can I use it with the Agent SDK or Claude Code?
The documentation covers the Messages API and SDK helpers. Claude Code has its own memory files (CLAUDE.md and auto memory), described on a separate page.
