记忆工具

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

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

记忆支持"just-in-time context retrieval"（即时上下文检索）。智能体不会预先加载所有相关信息，而是将其学到的内容记录在记忆文件中，并按需读取。这使活动上下文始终聚焦于当前任务，这对于长时间运行的会话非常重要，否则这些会话可能会超出上下文窗口的容量。有关更广泛的模式，请参阅有效的上下文工程。

记忆工具在"client-side"（客户端）运行：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-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 对类似上述请求的回复会以一个请求记忆操作（例如 view /memories）的 tool_use 块结尾。您的应用程序执行该操作，在 tool_result 块中返回结果，然后将对话发送回去，以便 Claude 继续：这就是标准的"tool-use loop"（工具使用循环）。

有四个 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-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"
}

对于 str_replace，new_str 是可选的：省略时，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 会自动将以下指令添加到系统提示中。您无需自行发送：

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
}

上下文编辑集成

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

与压缩配合使用

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

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

多会话软件开发模式

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

该模式的工作方式

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

关键原则

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

后续步骤

Bash 工具

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

上下文编辑

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

压缩

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

工具参考

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

用例

工作原理

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

入门

基本用法

实现记忆处理程序

工具命令

view

返回值

错误处理

create

返回值

错误处理

str_replace

返回值

错误处理

目录处理

insert

返回值

错误处理

目录处理

delete

返回值

错误处理

目录处理

rename

返回值

错误处理

目录处理

提示指导

安全注意事项

敏感信息

文件存储大小

记忆过期

路径遍历防护

错误处理

上下文编辑集成

与压缩配合使用

多会话软件开发模式

该模式的工作方式

关键原则

后续步骤

用例

工作原理

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

入门

基本用法

实现记忆处理程序

工具命令

view

返回值

错误处理

create

返回值

错误处理

str_replace

返回值

错误处理

目录处理

insert

返回值

错误处理

目录处理

delete

返回值

错误处理

目录处理

rename

返回值

错误处理

目录处理

提示指导

安全注意事项

敏感信息

文件存储大小

记忆过期

路径遍历防护

错误处理

上下文编辑集成

与压缩配合使用

多会话软件开发模式

该模式的工作方式

关键原则

后续步骤