memory-tool changedagents-and-tools/tool-use/memory-tool
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+17added
Lines−17removed
From line
106
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 106, old and new numbered
/
from line 106
106106
107107Using the memory tool takes two steps:
108108
1091. Add the memory tool to your request. The `tools` entry `{"type": "memory_20250818", "name": "memory"}` is the entire configuration: the `name` must be `memory`, and you don't define an input schema for an Anthropic-provided tool.
1091. Add the memory tool to your request. The `tools` entry `{"type": "memory_20250818", "name": "memory"}` is the entire configuration: the `name` must be `memory`, and you don’t define an input schema for an Anthropic-provided tool.
1101102. Implement a client-side handler for each memory command. Your handler must reject paths outside `/memories`, so read [Path traversal protection](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#path-traversal-protection) before you write it.
111111
112112## Basic usage
from line 279
279279
280280## Implement the memory handler
281281
282Claude's reply to a request like the previous one ends with a `tool_use` block that requests a memory operation, such as `view /memories`. Your application runs the operation and returns the result in a `tool_result` block, then sends the conversation back so Claude can continue: the standard [tool-use loop](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
282Claude’s reply to a request like the previous one ends with a `tool_use` block that requests a memory operation, such as `view /memories`. Your application runs the operation and returns the result in a `tool_result` block, then sends the conversation back so Claude can continue: the standard [tool-use loop](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
283283
284Four SDKs provide memory tool helpers that handle the tool interface and the loop. Subclass `BetaAbstractMemoryTool` (Python and C#), use `betaMemoryTool` (TypeScript), or implement `BetaMemoryToolHandler` (Java) to back memory with your own storage, such as files on disk, a database, cloud storage, or encrypted files. Python and TypeScript also ship a ready-made local-filesystem implementation, `BetaLocalFilesystemMemoryTool`. The helper and tool-runner surfaces live in your SDK's beta namespace even though the memory tool itself doesn't require a beta header. The Go and Ruby SDKs have no memory helper, so those examples run the tool-use loop themselves, and PHP wraps your handler closure in its generic `BetaRunnableTool`. All three use an in-memory store that you replace with your own storage.
284Four SDKs provide memory tool helpers that handle the tool interface and the loop. Subclass `BetaAbstractMemoryTool` (Python and C#), use `betaMemoryTool` (TypeScript), or implement `BetaMemoryToolHandler` (Java) to back memory with your own storage, such as files on disk, a database, cloud storage, or encrypted files. Python and TypeScript also ship a ready-made local-filesystem implementation, `BetaLocalFilesystemMemoryTool`. The helper and tool-runner surfaces live in your SDK’s beta namespace even though the memory tool itself doesn’t require a beta header. The Go and Ruby SDKs have no memory helper, so those examples run the tool-use loop themselves, and PHP wraps your handler closure in its generic `BetaRunnableTool`. All three use an in-memory store that you replace with your own storage.
285285
286286<CodeGroup exclude="shell">
287287 ```python Python
from line 706
706706 ```
707707</CodeGroup>
708708
709The in-memory stores in the Go, PHP, and Ruby examples keep them self-contained: each one dispatches on the `command` field in the `tool_use` block's `input` and returns the strings described under [Tool commands](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#tool-commands). A production handler also needs the [path validation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#path-traversal-protection) these demonstration stores skip. For the SDKs' own complete examples, see:
709The in-memory stores in the Go, PHP, and Ruby examples keep them self-contained: each one dispatches on the `command` field in the `tool_use` block’s `input` and returns the strings described under [Tool commands](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#tool-commands). A production handler also needs the [path validation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#path-traversal-protection) these demonstration stores skip. For the SDKs’ own complete examples, see:
710710
711711* Python: [examples/memory/basic.py](https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py)
712712* TypeScript: [examples/tools-helpers-memory.ts](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts)
from line 747
747747* Excludes hidden items (files starting with `.`) and `node_modules`
748748* Uses a tab character between the size and the path
749749
750The first `view` of `/memories` on an empty store is not an error. Where your SDK ships a local-filesystem memory tool, `BetaLocalFilesystemMemoryTool`, it creates the memory root before Claude's first call and returns the list header followed by a single size-and-path line for the empty directory itself.
750The first `view` of `/memories` on an empty store is not an error. Where your SDK ships a local-filesystem memory tool, `BetaLocalFilesystemMemoryTool`, it creates the memory root before Claude’s first call and returns the list header followed by a single size-and-path line for the empty directory itself.
751751
752752**For files:** Return file contents with a header and line numbers:
753753
from line 773
773773 100 Line one hundred
774774```
775775
776Claude's tool description also says that `view` displays image files (`.jpg`, `.jpeg`, and `.png`) and truncates the text view of files longer than 16,000 characters. Expect `view` calls on image paths and follow-up ranged views of long files.
776Claude’s tool description also says that `view` displays image files (`.jpg`, `.jpeg`, and `.png`) and truncates the text view of files longer than 16,000 characters. Expect `view` calls on image paths and follow-up ranged views of long files.
777777
778778#### Error handling
779779
from line 799
799799
800800* **File already exists:** `"Error: File {path} already exists"`
801801
802Claude's tool description says `create` "creates or overwrites" a file, so expect `create` calls on paths that already exist. Returning the error is the reference behavior, and overwriting instead is a valid implementation choice.
802Claude’s tool description says `create` “creates or overwrites” a file, so expect `create` calls on paths that already exist. Returning the error is the reference behavior, and overwriting instead is a valid implementation choice.
803803
804804### str\_replace
805805
from line 814
814814}
815815```
816816
817`new_str` is optional for `str_replace`: when it's omitted, `old_str` is deleted without a replacement.
817`new_str` is optional for `str_replace`: when it’s omitted, `old_str` is deleted without a replacement.
818818
819819#### Return values
820820
from line 828
828828
829829#### Directory handling
830830
831If the path is a directory, return a "file does not exist" error.
831If the path is a directory, return a “file does not exist” error.
832832
833833### insert
834834
from line 856
856856
857857#### Directory handling
858858
859If the path is a directory, return a "file does not exist" error.
859If the path is a directory, return a “file does not exist” error.
860860
861861### delete
862862
from line 908
908908
909909## Prompting guidance
910910
911When the memory tool is present in your request's `tools`, the API automatically adds this instruction to the system prompt. You don't need to send it yourself:
911When the memory tool is present in your request’s `tools`, the API automatically adds this instruction to the system prompt. You don’t need to send it yourself:
912912
913913```text wrap
914914IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
from line 919
919919ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.
920920```
921921
922Claude's tool description already tells it to keep the memory directory organized, so you don't need to repeat that instruction. If Claude still creates cluttered memory files, you can reinforce it in your prompt:
922Claude’s tool description already tells it to keep the memory directory organized, so you don’t need to repeat that instruction. If Claude still creates cluttered memory files, you can reinforce it in your prompt:
923923
924924```text wrap
925925Note: when editing your memory folder, always try to keep its content up-to-date, coherent and organized. You can rename or delete files that are no longer relevant. Do not create new files unless necessary.
926926```
927927
928You can also guide what Claude writes to memory. For example: "Only write down information relevant to \<topic> in your memory system."
928You can also guide what Claude writes to memory. For example: “Only write down information relevant to \<topic> in your memory system.”
929929
930930## Security considerations
931931
from line 941
941941
942942### Memory expiration
943943
944Periodically delete memory files that haven't been accessed in a long time.
944Periodically delete memory files that haven’t been accessed in a long time.
945945
946946### Path traversal protection
947947
from line 955
955955* Resolve paths to their canonical form and verify they remain within the memory directory
956956* Reject paths containing sequences such as `../`, `..\\`, or other traversal patterns
957957* Watch for URL-encoded traversal sequences (`%2e%2e%2f`)
958* Use your language's built-in path security utilities (for example, Python's `pathlib.Path.resolve()` and `relative_to()`)
958* Use your language’s built-in path security utilities (for example, Python’s `pathlib.Path.resolve()` and `relative_to()`)
959959
960960## Error handling
961961
962The memory tool uses similar error-handling patterns to the [text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool#handle-errors). Each command's error messages are listed under [Tool commands](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#tool-commands). To return an error to Claude, set `is_error` to `true` on the tool result and put the message in `content`:
962The memory tool uses similar error-handling patterns to the [text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool#handle-errors). Each command’s error messages are listed under [Tool commands](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool#tool-commands). To return an error to Claude, set `is_error` to `true` on the tool result and put the message in `content`:
963963
964964```json
965965{
No line in this hunk matches that.