Read the headline claim first — the Claude memory tool lets your agent remember things across sessions — and then read the second sentence of Anthropic's own documentation, which quietly takes it back:

The memory tool operates client-side: Claude requests file operations, and your application executes them.

Sit with that. The feature named "memory" ships no memory. What Anthropic gives you is a tool schema, a set of six command specifications, an auto-injected system prompt, and a directory path — /memories — that does not exist anywhere until you make it exist. Everything that turns this into persistence, the actual bytes on actual disk, is your code. "Giving Claude memory" is really becoming Claude's filesystem.

That's not a knock. It's the most important thing to understand before you wire it up, because it relocates the entire problem — and the entire risk — from Anthropic's servers into your handler.

The directory is a fiction#

Here's how a turn actually goes. The model, working on a task, emits a tool_use block:

{ "name": "memory", "input": { "command": "view", "path": "/memories" } }

Your application receives that, lists whatever you've decided /memories corresponds to, and returns the listing in a tool_result. The model reads a relevant file the same way, then keeps working. When it learns something worth keeping, it emits a create or str_replace, and again you perform the write.

The path /memories/customer_guidelines.xml is not a location. It's a prefix your handler maps onto real storage — a per-user directory, a set of keys in a database, encrypted blobs in object storage. A later conversation "continues from the same memory" for exactly one reason: it sends the same tools entry and your handler serves the same store. There is no session, no server-side thread, no magic. Persistence is a property of your backend's continuity, not the tool's.

The command set is small and unsurprising — view, create, str_replace, insert, delete, rename — and if that list reads like a text editor, that's because it is one. This is filesystem memory, not vector memory: the model navigates named files and edits them in place, rather than embedding-and-retrieving from a store it can't see. The upshot is that the model's memory is legible — you can open /memories and read exactly what your agent thinks it knows, which is a debugging luxury the vector approaches don't hand you.

Which means the security is yours, all of it#

Now the part that should make you slow down. You are executing, verbatim, file operations that a language model composed — and that model's inputs include whatever a user, a retrieved document, or a tool result put in front of it. So consider the path:

/memories/../../secrets.env

Nothing in the tool stops that. If your handler naively joins that onto a base directory and reads it, the model just exfiltrated your environment file, and it may have done so because a prompt-injection string in some fetched web page told it to. Anthropic flags this directly and hands you the checklist: validate that every path starts with /memories, resolve to canonical form and confirm it stays inside the memory root, reject ../ and ..\\, watch for URL-encoded traversal like %2e%2e%2f, and lean on your language's path utilities. None of that is optional. You built a filesystem the model drives; the model's steering wheel is reachable by anyone who can get text into its context.

The memory tool is a client-side tool wearing a server-side feature's clothes. The persistence is convenient; the trust boundary is the whole job.

There's more that lands on you than traversal: capping file sizes so a runaway agent can't write a gigabyte, expiring stale files, and stripping sensitive data before it's written (the model usually refuses to store secrets, but "usually" is not a security control). The SDKs help — Python and TypeScript ship a ready-made BetaLocalFilesystemMemoryTool — but the reference local implementation exists to be replaced, and the demo in-memory stores in the Go and Ruby examples skip the path validation on purpose, with a note that a production handler must add it back.

Memory and context editing are a pair, not a synonym#

The number you'll see quoted — Anthropic reports a 39% improvement on long-running agentic tasks — belongs to memory plus context editing, and it's worth being precise about which half does the work. Context editing is a separate, server-side feature that automatically clears old tool_use/tool_result pairs from the window before they're counted, keeping the active context small. That's where most of the token savings come from. Memory is what survives that clearing: the model writes what matters to /memories precisely so that when editing (or compaction) wipes the transcript, the important state is still on disk to be read back.

That's why the API, when the memory tool is present, injects a system prompt you don't write yourself — one that opens with "ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE" and warns the model to "assume interruption." The model is being told, at the platform level, to treat its own context as disposable and its memory files as the source of truth. Editing is the forgetting; memory is the remembering; the system prompt is the discipline that stitches them together.

So what is it, actually#

The Claude memory tool is a well-specified protocol for a model to drive a filesystem you own, plus the platform-level prompting to make it use that filesystem like a durable notebook. It is genuinely useful — legible, portable across Bedrock and Vertex, eligible for zero-data-retention — and it is genuinely a foot-gun if you treat "client-side" as an implementation footnote instead of the headline. The mental model that keeps you safe is the accurate one: Anthropic didn't give your agent a memory. It gave your agent a request format, and made you the memory. Build the store like the trust boundary it is, pair it with context editing so the window stays cheap, and you get an agent that survives its own interruptions — without handing the model a path straight out of the sandbox.