What is the memory tool for AI agents?
The memory tool is a client-side tool in Anthropic's Claude API that lets Claude create, read, update and delete files in a /memories directory, so knowledge persists across conversations without staying in the context window.
Checked
Anthropic launched the memory tool in public beta on 2025-09-29, alongside context editing, in "Managing context on the Claude Developer Platform". The pairing was deliberate: context editing clears stale content out of the window, and the memory tool keeps what matters outside it. On Anthropic's internal agentic search eval, context editing alone improved performance by 29%, and the two together by 39%.
The tool is client-side. Claude asks for file operations; the developer's application carries them out against storage it controls, such as a per-user folder or database keys. The /memories path is a prefix the handler maps onto that storage.
How it works
One tool entry
The request adds a tool of type memory_20250818 named memory. No input schema is defined; the commands are fixed.
Six commands
view lists a directory or shows a file with line numbers, create writes a file, str_replace edits text, insert adds lines, delete removes a file or folder, and rename moves one.
Memory first
With the tool present, the API adds a system instruction telling Claude to view its memory directory before doing anything else, record progress as it works, and assume its context may be reset at any moment.
SDK helpers
The Python, TypeScript, C# and Java SDKs provide helpers for the handler loop, and Python and TypeScript ship a ready-made local-filesystem implementation.
Security is the developer's job
Path traversal
A path such as /memories/../../secrets.env can reach outside the directory. The documentation requires validating every path, resolving it to canonical form and rejecting traversal sequences, including URL-encoded ones.
Sensitive data
Claude usually refuses to write sensitive information to memory, but the documentation recommends stripping it in the handler for a stronger guarantee.
Size and expiry
Cap file sizes and the length of view output, and periodically delete files that have not been accessed in a long time.
Where it fits
The documentation describes a multi-session pattern for software projects: an initializer session sets up a progress log and feature checklist, each later session reads them first, and each session updates the log before it ends. It also recommends pairing memory with compaction for long-running agents, so compaction keeps the context small and memory preserves what must survive the summary.
Other stacks reach the same goal differently. Google's ADK offers a memory service the agent searches through a load tool, and OpenAI's personalization cookbook stores notes in a state object injected at the start of each run. The memory tool's distinguishing choice is plain files the model organises itself.
How Motiontic's engineers apply it
Whatever the memory mechanism, Motiontic's engineers scope the store per user or per project, validate every write, set retention limits, and give a person a way to inspect and delete what the agent has saved. Evals check that saved memory improves later sessions rather than carrying stale or wrong facts forward.
Memory tool commands
| Command | What it does |
|---|---|
| view | Lists a directory up to two levels deep, or shows a file with line numbers |
| create | Writes a new file |
| str_replace | Replaces a unique piece of text in a file |
| insert | Inserts text after a given line |
| delete | Deletes a file or directory, but not the memory root |
| rename | Renames or moves a file or directory without overwriting |
Common questions
Where does the Claude memory tool store data?
Wherever the developer's handler puts it. The tool is client-side: Claude requests operations on paths under /memories, and the application maps them to its own files, database or cloud storage.
Is the memory tool the same as RAG?
No. RAG retrieves passages from an index by similarity. The memory tool gives Claude a directory it writes and organises itself, and reads back by browsing files.
Is the Claude memory tool safe to use with user data?
It can be, with controls in the handler: restrict paths to /memories, strip sensitive data before writing, cap sizes and expire old files. Those safeguards are the developer's responsibility.
Related
Context editing
Clear the old tool results, keep the conversation, keep the agent running.
Structured note-taking
The agent keeps its own notebook outside the context window, in a format it can trust.
Long-term memory (AI agents)
What an agent keeps after the conversation ends, and the rules for writing and recalling it.
Agent memory
Session state for the task at hand, plus stored knowledge the agent recalls later.
AI agent development
Agents that do real work for users, with the evals, traces and guardrails to keep them in production.
Running agents that have to hold up?
Describe the agent, the systems it touches and what it must never get wrong. The first call is with a lab engineer, who will say plainly whether it is ready for production, and whether Motiontic is the right team.