VI EN
Claude API

The memory tool in the Claude API: agents that remember across sessions

Binh 3 min read Đọc bài này bằng tiếng Việt

TL;DR

The memory tool gives Claude a directory of memory files across sessions, read on demand so context stays lean. It runs client-side: you implement six commands, you control the data, and you're responsible for blocking path traversal.

Your customer support agent learns today that "Acme prefers email follow-ups", but tomorrow, in a new conversation, it has forgotten everything. Stuffing the whole history into the prompt costs tokens and dilutes context. The Claude API's memory tool gives Claude a directory of memory files it can write, read, edit and delete across sessions. It reads them back only when needed (just-in-time), so context stays lean.

How it works: client-side

  • Add the tool {"type": "memory_20250818", "name": "memory"} to your request; no schema needed.
  • Claude only requests file operations; your application executes them and returns the result in a tool_result. The data lives on infrastructure you control: files on disk, a database, cloud storage.
  • The /memories path is just a prefix; your handler maps it to real storage, such as a per-user directory.
  • When the memory tool is present, the API adds instructions to the system prompt: always view the memory directory first, and record progress as you go since context may be reset at any time.

Six commands your handler must implement

CommandWhat it does
viewShow a directory (2 levels) or file contents with line numbers, optionally a line range
createCreate a new file
str_replaceReplace a unique piece of text in a file
insertInsert text after a given line
deleteDelete a file or directory (not /memories itself)
renameRename or move, without overwriting an existing destination

The Python and TypeScript SDKs ship BetaLocalFilesystemMemoryTool, which stores files on disk, plus a tool runner that handles the loop:

from anthropic.tools import BetaLocalFilesystemMemoryTool
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")
runner = client.beta.messages.tool_runner(
    model="claude-opus-5-5", max_tokens=1024, tools=[memory],
    messages=[{"role": "user", "content": "Remember that Acme prefers email follow-ups."}])
print(runner.until_done().content)

Combining with context management

  • Context editing: clears old tool results on the client; memory keeps what must be remembered.
  • Compaction: summarises the conversation server-side near the limit; memory preserves what must survive the summary.
  • Multi-session development pattern: the first session creates a progress log and feature checklist in memory; later sessions read them to resume and update them before ending.

Security: your responsibility

  • Path traversal: a path like /memories/../../secrets.env can escape. Check every path starts with /memories, canonicalise it and verify it stays inside, and block URL-encoded sequences such as %2e%2e%2f.
  • Sensitive data: Claude usually refuses to write sensitive information, but add a filtering step before writes.
  • Size and expiry: cap file sizes and how many characters view returns, and periodically delete files that haven't been accessed.
  • Per-user separation: don't let one user's memory leak to another.

How to apply it

  • Dev: Start with the SDK's filesystem handler, and add path validation before production.
  • Tech Lead: Design memory namespaces per tenant/user; write tests for path traversal cases.
  • PM: An "assistant that remembers customer preferences" feature is possible without storing whole conversation histories.

Sources & references

  1. Memory tool — Claude Docs
More on Claude API