---
title: "How does the Claude memory tool work for agents?"
description: "Claude's memory tool lets an agent read and write files under /memories; your application runs every operation and decides where the memory is stored."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# How does Anthropic's memory tool for Claude agents work?

Short answer

The memory tool in the Claude API lets an agent keep files in a /memories directory across conversations. Claude only asks for operations such as view, create, str\_replace, insert, delete and rename; your application runs them on storage you control. It pairs with context editing and compaction, so an agent can save what matters before old context is cleared or summarized.

*Piet Baudoin · published November 17, 2026 · November 17, 2026*

## What the tool actually is

The memory tool is one of the tools Anthropic provides in the Claude API. You switch it on with a single entry in the `tools` list: `{"type": "memory_20250818", "name": "memory"}`. That is the whole configuration. You do not write an input schema, and the name must be `memory`.

What makes it different from most memory products is where the memory lives. Anthropic does not store it. The documentation calls the tool client-side: Claude asks for a file operation, your application runs it and sends back the result in a normal `tool_result` block. The path `/memories` is only a prefix that your code maps onto real storage, such as a folder per user or rows in a database. A later conversation continues from the same memory when it sends the same tool and your handler serves the same store.

When the tool is present, the API adds a short protocol to the system prompt on its own. It tells Claude to view its memory directory before doing anything else, to record progress as it works, and to assume its context window may be reset at any moment.

## The six commands

| Command | What Claude asks for | What your handler does |
| --- | --- | --- |
| `view` | Show a directory or a file, optionally a line range | List files up to two levels deep, or return the file with line numbers |
| `create` | Write a new file | Create it (the reference behavior errors if it exists; overwriting is allowed) |
| `str_replace` | Replace one exact piece of text | Replace it, or report that it was missing or not unique |
| `insert` | Add text after a given line | Insert it, line 0 means the top of the file |
| `delete` | Remove a file or directory | Delete it, but never the `/memories` root |
| `rename` | Move or rename a file or directory | Move it, and refuse to overwrite an existing destination |

The Python and TypeScript SDKs ship a ready-made local file implementation, `BetaLocalFilesystemMemoryTool`. Python and C# let you subclass `BetaAbstractMemoryTool`, TypeScript has `betaMemoryTool` and Java has `BetaMemoryToolHandler`, so you can back memory with your own storage. Go, Ruby and PHP have no dedicated helper; you run the tool loop yourself.

## How it fits with context editing and compaction

Memory is one half of keeping a long-running agent on track. The other half is removing what no longer belongs in the context window.

1.  **Context editing** (beta header `context-management-2025-06-27`) clears old tool results once the input passes a threshold you set, by default 100,000 input tokens, keeping the three most recent tool uses unless you change it.
2.  **Compaction** summarizes the whole conversation on the server when it approaches the window limit.
3.  **Memory** keeps what must survive either of those. With context editing switched on, Claude gets an automatic warning when the clearing threshold is near, so it can write important results to memory files first.

Anthropic describes the pattern as just-in-time retrieval: instead of loading everything up front, the agent writes down what it learns and reads it back when the task needs it. For multi-session coding work, the documentation recommends a deliberate setup: a first session that creates a progress log and feature checklist, later sessions that start by reading them, and an update of the log before each session ends. More on the summarizing side in [What is context compaction?](https://bombos.ai/en/questions/context-engineering/what-is-context-compaction/)

## The misunderstanding: “Anthropic manages the memory”

Many developers read “memory tool” and expect a managed memory service, like the memory in the Claude app. It is not. Anthropic supplies the interface and the prompting; you supply storage, retention and security. That has consequences:

-   **Path traversal is your problem.** The documentation warns that a path such as `/memories/../../secrets.env` can reach files outside the memory folder, and that your handler must validate every path in every command.
-   **Size and expiry are your problem.** Anthropic suggests capping file sizes, limiting how much `view` returns and deleting files that have not been read for a long time.
-   **Sensitive data is mostly your problem.** Claude usually refuses to write sensitive information to memory, but for stronger guarantees you strip it before writing.
-   **Organization is partly your problem.** If Claude creates cluttered files, the documentation suggests adding an instruction to keep the folder coherent and to avoid new files unless needed.

The upside of this design is control: data retention is yours, which is why the tool is eligible for zero data retention.

## What this means for a team

The memory tool gives one agent a notebook. Whether two agents, or two colleagues, share that notebook depends entirely on how you map `/memories` to storage. Map it per user and every person’s agent learns alone. Map it to one shared folder and you have shared memory, but also the questions that come with it: who may overwrite whose notes, how you stop one bad entry from spreading (see [What is memory poisoning in AI agents?](https://bombos.ai/en/questions/ai-memory/what-is-memory-poisoning-in-ai-agents/)), and how you see which note an answer relied on. And the memory only exists for agents built on the Claude API with this tool. Your colleagues in ChatGPT, Copilot or Cursor do not see it. For the wider picture, see [How can a team share one AI memory?](https://bombos.ai/en/questions/ai-memory/how-to-share-ai-memory-across-a-team/)

## Where Bombos fits

The memory tool is a good fit for one agent’s working notes. When what an agent learns has to reach the rest of the team and its other AI tools, that is a different layer. Bombos is a plugin that gives Claude, Claude Code, ChatGPT, Copilot, Codex, Cursor, Grok and your own agents one shared memory, with team knowledge, learned rules and what already sits in mail, documents and repos. You can see what each answer rests on, and it runs in our cloud or on your own server. One developer can try it first for their own agents.

## Related questions

Where does the Claude memory tool store data?

Wherever you decide. The tool is client-side: Claude requests a file operation and your handler runs it, for example on local files, a database or cloud storage. /memories is only a path prefix that your handler maps onto that storage.

Does the memory tool need a beta header?

No. Per Anthropic's documentation (November 2026), the tool itself does not need a beta header. The SDK helpers and tool runner do live in the SDKs' beta namespace, and context editing still uses the beta header context-management-2025-06-27.

Is the memory tool the same as memory in the Claude app?

No. The memory in claude.ai is a product feature for people using the app. The memory tool is an API building block for developers who build their own agents, and you implement the storage yourself.

Which models support the memory tool?

Anthropic's documentation says it is available on all Claude 4 and later models, and that it is eligible for zero data retention and HIPAA readiness.

## Sources

1.  [Memory tool (Claude API docs)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
2.  [Context editing (Claude API docs)](https://platform.claude.com/docs/en/build-with-claude/context-editing)
3.  [Effective context engineering for AI agents (Anthropic)](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)

## 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](https://bombos.ai/assets/team/piet-klein.jpg)

**Piet Baudoin**You talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe

## More questions about AI memory

-   [How does memory work in an n8n AI agent?](https://bombos.ai/en/questions/ai-memory/how-does-memory-work-in-n8n-ai-agents/)
-   [What are the types of memory in AI agents?](https://bombos.ai/en/questions/ai-memory/types-of-ai-agent-memory/)
-   [What is Hindsight agent memory and how does it work?](https://bombos.ai/en/questions/ai-memory/what-is-hindsight-agent-memory/)
-   [What is a memory OS for AI agents (MemoryOS, MemOS, MIRIX)?](https://bombos.ai/en/questions/ai-memory/what-is-a-memory-os-for-ai-agents/)
-   [What is Vertex AI Memory Bank and how does it work?](https://bombos.ai/en/questions/ai-memory/what-is-vertex-ai-memory-bank/)
-   [How do you evaluate the memory of an LLM agent?](https://bombos.ai/en/questions/ai-memory/how-to-evaluate-llm-agent-memory/)
-   [How do you give an LLM long-term memory?](https://bombos.ai/en/questions/ai-memory/how-to-give-an-llm-long-term-memory/)
-   [How can a team share one AI memory across ChatGPT, Claude and Cursor?](https://bombos.ai/en/questions/ai-memory/how-to-share-ai-memory-across-a-team/)

[All questions about AI memory →](https://bombos.ai/en/questions/ai-memory/)


---

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","url":"https://bombos.ai/","logo":"https://bombos.ai/assets/bombos-bee.png","description":"Bombos is the memory layer under every AI your team uses. One shared memory for Claude, ChatGPT, Copilot, Cursor and your own agents, that learns how you work.","sameAs":["https://www.linkedin.com/company/bombos-ai","https://www.youtube.com/@truebombos","https://www.instagram.com/truebombos/","https://bsky.app/profile/bombostrue.bsky.social","https://www.threads.com/@truebombos","https://mastodon.social/@Bombos","https://www.tiktok.com/@truebombos","https://t.me/truebombos","https://www.pinterest.com/truebombos/","https://github.com/bombos-ai","https://linktr.ee/bombos.ai","https://bombosai.substack.com","https://hashnode.com/@bombosai","https://hackernoon.com/u/bombos","https://dev.to/bombos"],"email":"info@bombos.ai","areaServed":["NL","Europe"],"knowsLanguage":["nl","en"],"contactPoint":{"@type":"ContactPoint","email":"info@bombos.ai","contactType":"sales","url":"https://bombos.ai/en/contact/","availableLanguage":["nl","en"]}},{"@type":"WebSite","@id":"https://bombos.ai/#website","name":"Bombos","url":"https://bombos.ai/","inLanguage":["nl-NL","en"],"publisher":{"@id":"https://bombos.ai/#organization"}}]}

{"@context":"https://schema.org","@type":"Article","headline":"How does Anthropic's memory tool for Claude agents work?","description":"Claude's memory tool lets an agent read and write files under /memories; your application runs every operation and decides where the memory is stored.","abstract":"The memory tool in the Claude API lets an agent keep files in a /memories directory across conversations. Claude only asks for operations such as view, create, str_replace, insert, delete and rename; your application runs them on storage you control. It pairs with context editing and compaction, so an agent can save what matters before old context is cleared or summarized.","datePublished":"2026-11-17T00:00:00.000Z","dateModified":"2026-11-17T00:00:00.000Z","author":{"@type":"Person","name":"Piet Baudoin"},"publisher":{"@type":"Organization","@id":"https://bombos.ai/#organization","name":"Bombos","logo":{"@type":"ImageObject","url":"https://bombos.ai/assets/bombos-bee.png"}},"image":"https://bombos.ai/assets/og-en-v2.png","mainEntityOfPage":"https://bombos.ai/en/questions/ai-memory/how-does-the-claude-memory-tool-work/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"AI memory","url":"https://bombos.ai/en/questions/ai-memory/"},"citation":[{"@type":"CreativeWork","name":"Memory tool (Claude API docs)","url":"https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool"},{"@type":"CreativeWork","name":"Context editing (Claude API docs)","url":"https://platform.claude.com/docs/en/build-with-claude/context-editing"},{"@type":"CreativeWork","name":"Effective context engineering for AI agents (Anthropic)","url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents"}]}

{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Bombos","item":"https://bombos.ai/en/"},{"@type":"ListItem","position":2,"name":"Questions","item":"https://bombos.ai/en/questions/"},{"@type":"ListItem","position":3,"name":"AI memory","item":"https://bombos.ai/en/questions/ai-memory/"},{"@type":"ListItem","position":4,"name":"How does Anthropic's memory tool for Claude agents work?","item":"https://bombos.ai/en/questions/ai-memory/how-does-the-claude-memory-tool-work/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Where does the Claude memory tool store data?","acceptedAnswer":{"@type":"Answer","text":"Wherever you decide. The tool is client-side: Claude requests a file operation and your handler runs it, for example on local files, a database or cloud storage. /memories is only a path prefix that your handler maps onto that storage."}},{"@type":"Question","name":"Does the memory tool need a beta header?","acceptedAnswer":{"@type":"Answer","text":"No. Per Anthropic's documentation (November 2026), the tool itself does not need a beta header. The SDK helpers and tool runner do live in the SDKs' beta namespace, and context editing still uses the beta header context-management-2025-06-27."}},{"@type":"Question","name":"Is the memory tool the same as memory in the Claude app?","acceptedAnswer":{"@type":"Answer","text":"No. The memory in claude.ai is a product feature for people using the app. The memory tool is an API building block for developers who build their own agents, and you implement the storage yourself."}},{"@type":"Question","name":"Which models support the memory tool?","acceptedAnswer":{"@type":"Answer","text":"Anthropic's documentation says it is available on all Claude 4 and later models, and that it is eligible for zero data retention and HIPAA readiness."}}]}
```
