记忆工具

通过在您的应用程序中实现记忆工具的文件操作，让 Claude 能够跨对话存储和检索信息。

"Memory tool"（记忆工具）让 Claude 能够在一个记忆文件目录中跨对话存储和检索信息。Claude 可以创建、读取、更新和删除在会话之间持久保存的文件，随着时间的推移积累知识，而无需将所有内容都保留在 "context window"（上下文窗口）中。

记忆支持即时上下文检索。智能体不是预先加载所有相关信息，而是将其学到的内容记录在记忆文件中，并按需读取。这使活动上下文专注于当前任务，这对于长时间运行的会话非常重要，否则这些会话会使上下文窗口不堪重负。有关更广泛的模式，请参阅有效的上下文工程。

记忆工具在客户端运行：Claude 请求文件操作，由您的应用程序执行这些操作。您可以通过自己的基础设施控制数据的存储位置和方式。

使用场景

跨多个智能体会话维护项目上下文
将过去交互、决策和反馈中的经验教训应用于新任务
随着时间的推移建立知识库

工作原理

启用记忆工具后，Claude 会在开始任务之前自动检查其记忆目录。在工作过程中，Claude 将学到的内容存储在 /memories 下的文件中，并在之后的对话中读取这些文件以继续先前的工作。

由于记忆工具是客户端工具，Claude 只会请求记忆操作。您的应用程序针对您控制的存储执行每个请求，并在 tool_result 块中返回结果（请参阅处理工具调用）。/memories 路径是一个前缀，您的处理程序将其映射到实际存储上，例如每个用户的目录或数据库中的键。记忆完全存在于您的应用程序中。当之后的对话发送相同的 tools 条目且您的处理程序提供相同的存储时，该对话将从相同的记忆继续。出于安全考虑，请将所有记忆操作限制在 /memories 目录内（请参阅路径遍历保护）。

示例：记忆工具调用的工作方式

典型的交互如下所示：

1. 用户请求：

"Help me respond to this customer service ticket."

2. Claude 检查记忆目录：

"I'll help you respond to the customer service ticket. Let me check my memory for any previous context."

Claude 调用记忆工具：

{
  "type": "tool_use",
  "id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories"
  }
}

3. 您的应用程序返回目录内容：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Here're the files and directories up to 2 levels deep in /memories, excluding hidden items and node_modules:\n4.0K\t/memories\n1.5K\t/memories/customer_service_guidelines.xml\n2.0K\t/memories/refund_policies.xml"
}

4. Claude 读取相关文件：

{
  "type": "tool_use",
  "id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "name": "memory",
  "input": {
    "command": "view",
    "path": "/memories/customer_service_guidelines.xml"
  }
}

5. 您的应用程序返回文件内容：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
  "content": "Here's the content of /memories/customer_service_guidelines.xml with line numbers:\n     1\t<guidelines>\n     2\t<addressing_customers>\n     3\t- Always address customers by their first name\n     4\t- Use empathetic language\n..."
}

6. Claude 使用记忆提供帮助：

"Based on your customer service guidelines, I can help you craft a response. Please share the ticket details..."

记忆工具在所有 Claude 4 及更高版本的模型上可用。有关 Anthropic 提供的工具的完整列表，请参阅工具参考。

入门

使用记忆工具需要两个步骤：

将记忆工具添加到您的请求中。tools 条目 {"type": "memory_20250818", "name": "memory"} 就是全部配置：name 必须为 memory，并且您无需为 Anthropic 提供的工具定义输入模式。
为每个记忆命令实现客户端处理程序。您的处理程序必须拒绝 /memories 之外的路径，因此在编写之前请先阅读路径遍历保护。

基本用法

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Help me respond to this customer service ticket.",
        }
    ],
    tools=[{"type": "memory_20250818", "name": "memory"}],
)

print(message)

实现记忆处理程序

Claude 对类似上述请求的回复以一个 tool_use 块结束，该块请求一个记忆操作，例如 view /memories。您的应用程序执行该操作并在 tool_result 块中返回结果，然后将对话发送回去以便 Claude 继续：这就是标准的工具使用循环。

有四个 SDK 提供了记忆工具辅助程序，用于处理工具接口和循环。继承 BetaAbstractMemoryTool（Python 和 C#）、使用 betaMemoryTool（TypeScript）或实现 BetaMemoryToolHandler（Java），即可用您自己的存储来支持记忆，例如磁盘上的文件、数据库、云存储或加密文件。Python 和 TypeScript 还附带了一个现成的本地文件系统实现 BetaLocalFilesystemMemoryTool。尽管记忆工具本身不需要 beta 标头，但辅助程序和工具运行器接口位于每个 SDK 的 beta 命名空间中。Go 和 Ruby SDK 没有记忆辅助程序，因此这些示例自行运行工具使用循环，而 PHP 则将您的处理程序闭包包装在其通用的 BetaRunnableTool 中。这三者都使用内存存储，您可以将其替换为自己的存储。

import anthropic
from anthropic.tools import BetaLocalFilesystemMemoryTool

client = anthropic.Anthropic()
memory = BetaLocalFilesystemMemoryTool(base_path="./memory")

runner = client.beta.messages.tool_runner(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Remember that customer Acme Corp prefers email follow-ups.",
        }
    ],
    tools=[memory],
)

final_message = runner.until_done()
print(final_message.content)

Go、PHP 和 Ruby 示例中的内存存储使它们保持自包含：每个示例都根据 tool_use 块的 input 中的 command 字段进行分派，并返回工具命令下描述的字符串。生产环境的处理程序还需要这些演示存储所跳过的路径验证。有关各 SDK 自己的完整示例，请参阅：

Python：examples/memory/basic.py
TypeScript：examples/tools-helpers-memory.ts
C#：MemoryToolExample
Java：BetaMemoryToolExample.java

工具命令

您的客户端实现必须处理以下命令。这些规范描述了推荐的行为和返回字符串：Claude 会读取您的工具结果中包含的任何文本，因此如果您的应用程序需要，您可以返回不同的字符串。

view

显示目录内容或文件内容，可选指定行范围：

{
  "command": "view",
  "path": "/memories/notes.txt",
  "view_range": [1, 10]
}

view_range 是可选的，适用于文本文件视图：[start_line, end_line] 返回这些行，[start_line, -1] 返回从 start_line 到文件末尾的所有内容。

返回值

对于目录： 返回一个显示文件和目录及其大小的列表：

Here're the files and directories up to 2 levels deep in {path}, excluding hidden items and node_modules:
{size}\t{path}
{size}\t{path}/{filename1}
{size}\t{path}/{filename2}

列出最多 2 层深度的文件
显示人类可读的大小（例如 5.5K、1.2M）
排除隐藏项（以 . 开头的文件）和 node_modules
在大小和路径之间使用制表符

在空存储上首次对 /memories 执行 view 不是错误。SDK 的本地文件系统记忆工具（BetaLocalFilesystemMemoryTool）会在 Claude 首次调用之前创建记忆根目录，并返回列表标头，后跟空目录本身的一行大小和路径。

对于文件： 返回带有标头和行号的文件内容：

Here's the content of {path} with line numbers:
{line_numbers}{tab}{content}

行号格式：

宽度： 6 个字符，右对齐并用空格填充
分隔符： 行号和内容之间使用制表符
索引： 从 1 开始（第一行为第 1 行）
行数限制： 超过 999,999 行的文件应返回错误："File {path} exceeds maximum line limit of 999,999 lines."

示例输出：

Here's the content of /memories/notes.txt with line numbers:
     1	Hello World
     2	This is line two
    10	Line ten
   100	Line one hundred

Claude 的工具描述还指出，view 可以显示图像文件（.jpg、.jpeg 和 .png），并会截断超过 16,000 个字符的文件的文本视图。请预期会有针对图像路径的 view 调用，以及对长文件的后续范围视图调用。

错误处理

文件或目录不存在： "The path {path} does not exist. Please provide a valid path."

create

创建新文件：

{
  "command": "create",
  "path": "/memories/notes.txt",
  "file_text": "Meeting notes:\n- Discussed project timeline\n- Next steps defined\n"
}

返回值

成功： "File created successfully at: {path}"

错误处理

文件已存在： "Error: File {path} already exists"

Claude 的工具描述指出 create 会"创建或覆盖"文件，因此请预期会有针对已存在路径的 create 调用。返回错误是参考行为，而改为覆盖也是一种有效的实现选择。

str_replace

替换文件中的文本：

{
  "command": "str_replace",
  "path": "/memories/preferences.txt",
  "old_str": "Favorite color: blue",
  "new_str": "Favorite color: green"
}

new_str 对于 str_replace 是可选的：省略时，old_str 将被删除而不进行替换。

返回值

成功： "The memory file has been edited."，后跟带行号的已编辑文件片段

错误处理

文件不存在： "Error: The path {path} does not exist. Please provide a valid path."
未找到文本： "No replacement was performed, old_str `\{old_str}` did not appear verbatim in {path}."
重复文本： 当 old_str 出现多次时，返回："No replacement was performed. Multiple occurrences of old_str `\{old_str}` in lines: {line_numbers}. Please ensure it is unique"

目录处理

如果路径是目录，则返回"文件不存在"错误。

insert

在特定行插入文本：

{
  "command": "insert",
  "path": "/memories/todo.txt",
  "insert_line": 2,
  "insert_text": "- Review memory tool documentation\n"
}

insert_text 插入在第 insert_line 行之后，0 表示插入到文件开头。

返回值

成功： "The file {path} has been edited."

错误处理

文件不存在： "Error: The path {path} does not exist"
无效行号： "Error: Invalid `insert_line` parameter: {insert_line}. It should be within the range of lines of the file: [0, {n_lines}]"

目录处理

如果路径是目录，则返回"文件不存在"错误。

delete

删除文件或目录：

{
  "command": "delete",
  "path": "/memories/old_file.txt"
}

返回值

成功： "Successfully deleted {path}"

错误处理

文件或目录不存在： "Error: The path {path} does not exist"

目录处理

递归删除目录及其所有内容。工具描述告知 Claude 它不能删除 /memories 目录本身，因此请拒绝路径为记忆根目录的 delete 操作。

rename

重命名或移动文件或目录：

{
  "command": "rename",
  "old_path": "/memories/draft.txt",
  "new_path": "/memories/final.txt"
}

返回值

成功： "Successfully renamed {old_path} to {new_path}"

错误处理

源不存在： "Error: The path {old_path} does not exist"
目标已存在： 返回错误（不要覆盖）："Error: The destination {new_path} already exists"

目录处理

重命名目录。工具描述告知 Claude 它不能重命名 /memories 目录本身，因此请拒绝 old_path 为记忆根目录的 rename 操作。

提示指导

当记忆工具出现在您请求的 tools 中时，API 会自动将以下指令添加到 "system prompt"（系统提示）中。您无需自行发送：

IMPORTANT: ALWAYS VIEW YOUR MEMORY DIRECTORY BEFORE DOING ANYTHING ELSE.
MEMORY PROTOCOL:
1. Use the `view` command of your `memory` tool to check for earlier progress.
2. ... (work on the task) ...
   - As you make progress, record status / progress / thoughts etc in your memory.
ASSUME INTERRUPTION: Your context window might be reset at any moment, so you risk losing any progress that is not recorded in your memory directory.

Claude 的工具描述已经告知它保持记忆目录井然有序，因此您无需重复该指令。如果 Claude 仍然创建杂乱的记忆文件，您可以在提示中加以强化：

Note: 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.

您还可以引导 Claude 向记忆中写入什么内容。例如："Only write down information relevant to <topic> in your memory system."

安全注意事项

您的应用程序会执行 Claude 请求的每个文件操作，因此以下安全措施由您负责：

敏感信息

Claude 通常会拒绝将敏感信息写入记忆文件。为了获得更强的保证，请添加验证，在处理程序写入文件之前剥离敏感数据。

文件存储大小

跟踪记忆文件大小并限制文件可以增长到多大。考虑限制 view 命令返回的字符数，并让 Claude 使用 view_range 分页查看其余内容。

记忆过期

定期删除长时间未被访问的记忆文件。

路径遍历保护

请考虑以下安全措施：

验证所有路径都以 /memories 开头
将路径解析为其规范形式，并验证它们仍在记忆目录内
拒绝包含 ../、..\\ 等序列或其他遍历模式的路径
注意 URL 编码的遍历序列（%2e%2e%2f）
使用您所用语言内置的路径安全工具（例如 Python 的 pathlib.Path.resolve() 和 relative_to()）

错误处理

记忆工具使用与文本编辑器工具类似的错误处理模式。每个命令的错误消息列在工具命令下。要向 Claude 返回错误，请在工具结果上将 is_error 设置为 true，并将消息放入 content 中：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
  "content": "Error: The path /memories/notes.txt does not exist",
  "is_error": true
}

上下文编辑集成

记忆工具与上下文编辑配合使用，以管理长时间运行的对话。有关详细信息，请参阅上下文编辑。

与压缩配合使用

记忆工具还可以与压缩配合使用，后者在服务器端对较早的对话上下文进行摘要。上下文编辑在客户端清除特定的工具结果。当对话接近上下文窗口限制时，压缩会在服务器上自动对整个对话进行摘要。

对于长时间运行的智能体，请考虑同时使用两者：压缩无需客户端记账即可保持活动上下文较小，而记忆则保留必须在摘要后留存的信息。

多会话软件开发模式

对于跨越多个智能体会话的软件项目，请有意识地设置记忆文件，而不是在工作进行中临时编写。以下模式将记忆转变为一种恢复机制：每个新会话都从上一个会话记录的状态恢复。

该模式的工作方式

初始化会话： 第一个会话在任何实质性工作开始之前设置记忆文件。这包括进度日志（跟踪已完成的工作和接下来的工作）、功能清单（定义工作范围），以及对项目所需的任何启动或初始化脚本的引用。
后续会话： 每个新会话都以读取这些记忆文件开始。这样可以恢复项目状态，而无需重新探索代码库或回溯先前的决策。
会话结束更新： 在会话结束之前，它会用已完成的内容和剩余的内容更新进度日志。这确保下一个会话有一个准确的起点。

关键原则

一次只处理一个功能。只有在端到端验证确认功能正常工作后才将其标记为完成，而不是在代码编写完成时。这使进度日志在各个会话之间保持准确。

后续步骤

Bash 工具

在持久的 bash 会话中执行 shell 命令。

上下文编辑

使用上下文编辑在对话上下文增长时自动进行管理。

压缩

服务器端上下文压缩，用于管理接近上下文窗口限制的长对话。

工具参考

Anthropic 提供的工具目录以及可选工具定义属性的参考。

使用场景

工作原理

示例：记忆工具调用的工作方式

入门

基本用法

实现记忆处理程序

工具命令

view

返回值

错误处理

create

返回值

错误处理

str_replace

返回值

错误处理

目录处理

insert

返回值

错误处理

目录处理

delete

返回值

错误处理

目录处理

rename

返回值

错误处理

目录处理

提示指导

安全注意事项

敏感信息

文件存储大小

记忆过期

路径遍历保护

错误处理

上下文编辑集成

与压缩配合使用

多会话软件开发模式

该模式的工作方式

关键原则

后续步骤

使用场景

工作原理

示例：记忆工具调用的工作方式

入门

基本用法

实现记忆处理程序

工具命令

view

返回值

错误处理

create

返回值

错误处理

str_replace

返回值

错误处理

目录处理

insert

返回值

错误处理

目录处理

delete

返回值

错误处理

目录处理

rename

返回值

错误处理

目录处理

提示指导

安全注意事项

敏感信息

文件存储大小

记忆过期

路径遍历保护

错误处理

上下文编辑集成

与压缩配合使用

多会话软件开发模式

该模式的工作方式

关键原则

后续步骤