---
title: "Claude memory tool (API) explained"
description: "The memory tool lets Claude read and write files in a /memories directory that your own application stores, so an agent keeps what it learns between sessions."
image: "https://bombos.ai/assets/og-en-v2.png"
---

# 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.

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

## 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](https://bombos.ai/en/questions/claude/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](https://bombos.ai/en/knowledge-base/what-is-ai-agent-memory/) and [a memory layer for AI agents](https://bombos.ai/en/knowledge-base/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)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
2.  [Use Claude's chat search and memory (Claude Help Center)](https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context)
3.  [Managing context on the Claude Developer Platform (Claude blog, September 29, 2025)](https://claude.com/blog/context-management)

## 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 Claude for teams

-   [Does Claude have memory across chats, and how does it work?](https://bombos.ai/en/questions/claude/does-claude-have-memory/)
-   [How do I import my ChatGPT memory into Claude?](https://bombos.ai/en/questions/claude/import-chatgpt-memory-to-claude/)
-   [How do I export my Claude memory or move it to another AI?](https://bombos.ai/en/questions/claude/export-claude-memory/)
-   [How do Claude Projects work, and what are they good for?](https://bombos.ai/en/questions/claude/how-do-claude-projects-work/)
-   [How do I turn off, reset or delete Claude memory?](https://bombos.ai/en/questions/claude/delete-or-turn-off-claude-memory/)
-   [Are Claude Projects free, and what are the limits?](https://bombos.ai/en/questions/claude/claude-projects-limits/)
-   [Claude Skills vs Projects: what is the difference, and when do you use which?](https://bombos.ai/en/questions/claude/claude-skills-vs-projects/)
-   [What does the Claude Team plan cost per seat and what do you get?](https://bombos.ai/en/questions/claude/claude-team-plan-pricing/)

[All questions about Claude for teams →](https://bombos.ai/en/questions/claude/)


---

```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":"What is the Claude memory tool in the API, and how does it work?","description":"The memory tool lets Claude read and write files in a /memories directory that your own application stores, so an agent keeps what it learns between sessions.","abstract":"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.","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/claude/claude-memory-tool-api/","inLanguage":"en-US","isPartOf":{"@type":"CollectionPage","name":"Claude for teams","url":"https://bombos.ai/en/questions/claude/"},"citation":[{"@type":"CreativeWork","name":"Memory tool (Claude Platform docs)","url":"https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool"},{"@type":"CreativeWork","name":"Use Claude's chat search and memory (Claude Help Center)","url":"https://support.claude.com/en/articles/11817273-use-claude-s-chat-search-and-memory-to-build-on-previous-context"},{"@type":"CreativeWork","name":"Managing context on the Claude Developer Platform (Claude blog, September 29, 2025)","url":"https://claude.com/blog/context-management"}]}

{"@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":"Claude for teams","item":"https://bombos.ai/en/questions/claude/"},{"@type":"ListItem","position":4,"name":"What is the Claude memory tool in the API, and how does it work?","item":"https://bombos.ai/en/questions/claude/claude-memory-tool-api/"}]}

{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"Is the memory tool the same as memory in the Claude app?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does the memory tool need a beta header?","acceptedAnswer":{"@type":"Answer","text":"No. The tool itself does not require a beta header. The SDK helpers and the tool runner live in the SDKs' beta namespace."}},{"@type":"Question","name":"Which models support it?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I use it with the Agent SDK or Claude Code?","acceptedAnswer":{"@type":"Answer","text":"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."}}]}
```
