What is the Claude memory tool in the API, and how does it work?

Short answer

The memory tool is an Anthropic-provided API tool (type memory_20250818) that lets Claude create, read, edit, rename and delete files in a /memories directory between conversations. It runs client-side: Claude only requests the operations and your application executes them against storage you control. It is separate from the memory in the Claude app, and you are responsible for path validation and what gets stored.

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:

  1. Path traversal. A path like /memories/../../secrets.env can reach files outside the directory. Validate every path, resolve it to canonical form and reject anything outside /memories, including URL-encoded variants.
  2. Sensitive data. Claude usually refuses to write sensitive information to memory, but for guarantees you add your own filtering before writing.
  3. Size. Cap file sizes and how much view returns; let Claude page through with view_range.
  4. 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.

Sources

  1. Memory tool (Claude Platform docs)
  2. Use Claude's chat search and memory (Claude Help Center)
  3. Managing context on the Claude Developer Platform (Claude blog, September 29, 2025)
The first half hour · free

What does your AI forget?

  1. 01You tell us which AI you use and where it keeps starting over.
  2. 02We show what a shared memory changes there, on your own examples.
  3. 03You keep the plan, with or without Bombos.
Piet Baudoin
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.