Memory tool (memory_20250818)
Status: DOCUMENTED · LIVE_VERIFIED 2026-09-18 (h8 on haiku 4.5 → tool_use{name:"memory", input:{"command":"view","path":"/memories"}}; j6 count_tokens 1576). Client-side storage was not implemented in the probe.
Sources: Memory tool · Tool reference · Release notes 2025-09-29 / 2026-02-17.
Last verified: 2026-09-18.
Definition
{"type": "memory_20250818", "name": "memory"}No beta header since 2026-02-17 (launched in beta 2025-09-29). name must be memory. Available on all Claude 4+ models. Client-executed: Claude only requests file operations under the virtual /memories prefix; your handler maps them to real storage (per-user dir, DB…). The API injects a system-prompt "MEMORY PROTOCOL" telling Claude to view its memory directory before anything else and to record progress (hence the first call is always view /memories).
Commands (tool_use.input.command) and reference return strings
| Command | Params | Success string | Errors |
|---|---|---|---|
view |
path, view_range?: [start,end] (-1 = EOF) |
dir: Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:\n{size}\t{path}… · file: Here's the content of {path} with line numbers:\n + 6-wide right-aligned line numbers + tab |
The path {path} does not exist. Please provide a valid path. · >999,999 lines error |
create |
path, file_text |
File created successfully at: {path} |
Error: File {path} already exists (overwrite is an acceptable alternative) |
str_replace |
path, old_str, new_str? (omitted = delete) |
The memory file has been edited. + snippet |
not found / multiple occurrences (…in lines: {line_numbers}. Please ensure it is unique) |
insert |
path, insert_line (0 = top), insert_text |
The file {path} has been edited. |
invalid line: …should be within the range of lines of the file: [0, {n_lines}] |
delete |
path |
Successfully deleted {path} |
does not exist; refuse deleting /memories itself |
rename |
old_path, new_path |
Successfully renamed {old_path} to {new_path} |
source missing / destination exists (never overwrite); refuse renaming the root |
Claude's tool description also says view shows images (.jpg/.jpeg/.png) and truncates text over 16,000 characters — expect ranged follow-ups.
Security (your responsibility)
Path traversal (/memories/../../secrets.env, %2e%2e%2f) must be rejected — canonicalize and check the prefix. Strip sensitive data, cap file sizes and view output, expire stale files.
SDK helpers
Python anthropic.tools.BetaLocalFilesystemMemoryTool(base_path=…) / BetaAbstractMemoryTool, TypeScript betaMemoryTool, Java BetaMemoryToolHandler, C# BetaAbstractMemoryTool — used with client.beta.messages.tool_runner() (beta namespace even though the tool itself is GA). Combine with context editing (clear old tool results) or compaction for long sessions; "initializer session" pattern for multi-session coding agents.
Pricing
Tokens only; live count_tokens haiku 4.5: 1,576 tokens for a one-line prompt + memory tool (definition + injected protocol).
Examples: examples/anthropic/tools/memory/basic.{sh,py,ts}.