工具

内存工具

Claude 的内存工具使其能够通过内存文件目录在对话间存储和检索信息。

内存工具使 Claude 能够通过内存文件目录在对话间存储和检索信息。Claude 可以创建、读取、更新和删除在会话间持久保存的文件，使其能够随着时间推移积累知识，而无需将所有内容保留在上下文窗口中。

内存工具在客户端运行——你可以通过自己的基础设施控制数据的存储位置和方式。

内存工具目前处于测试阶段。要启用它，请在 API 请求中使用测试版标头 context-management-2025-06-27。

请通过我们的反馈表单分享你对此功能的反馈。

用例

在多个代理执行间维护项目上下文
从过去的交互、决策和反馈中学习
随着时间推移构建知识库
启用跨对话学习，使 Claude 在重复工作流中不断改进

工作原理

启用后，Claude 在开始任务前会自动检查其内存目录。Claude 可以在 /memories 目录中创建、读取、更新和删除文件，以存储其工作时学到的内容，然后在未来对话中引用这些记忆，以更有效地处理类似任务或从中断处继续。

由于这是一个客户端工具，Claude 会进行工具调用来执行内存操作，你的应用程序在本地执行这些操作。这使你能够完全控制内存的存储位置和方式。出于安全考虑，你应该将所有内存操作限制在 /memories 目录中。

示例：内存工具调用如何工作

当你要求 Claude 帮助完成任务时，Claude 会自动先检查其内存目录。以下是典型交互的样子：

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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- 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 Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)

快速开始

要使用内存工具：

在 API 请求中包含测试版标头 context-management-2025-06-27
将内存工具添加到你的请求中
为内存操作实现客户端处理程序

要在应用程序中处理内存工具操作，你需要为每个内存命令实现处理程序。我们的 SDK 提供内存工具助手来处理工具接口——你可以子类化 BetaAbstractMemoryTool（Python）或使用 betaMemoryTool（TypeScript）来实现你自己的内存后端（基于文件、数据库、云存储、加密文件等）。

有关工作示例，请参阅：

Python：examples/memory/basic.py
TypeScript：examples/tools-helpers-memory.ts

基本用法

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "I'\''m working on a Python web scraper that keeps crashing with a timeout error. Here'\''s the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPlease help me debug this."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

工具命令

你的客户端实现需要处理这些内存工具命令：

view

显示目录内容或文件内容，支持可选的行范围：

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // 可选：查看特定行
}

create

创建或覆盖文件：

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

str_replace

替换文件中的文本：

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

insert

在特定行插入文本：

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

delete

删除文件或目录：

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

rename

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

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

提示指导

当包含内存工具时，我们会自动将此指令包含到系统提示中：

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 写入内存的内容，例如，"仅将与 <topic> 相关的信息写入你的内存系统。"

安全考虑

实现内存存储时，以下是重要的安全问题：

敏感信息

Claude 通常会拒绝在内存文件中写下敏感信息。但是，你可能想要实现更严格的验证，以去除可能的敏感信息。

文件存储大小

考虑跟踪内存文件大小，并防止文件增长过大。考虑添加内存读取命令可以返回的最大字符数，并让 Claude 分页浏览内容。

内存过期

考虑定期清除在较长时间内未被访问的内存文件。

路径遍历保护

恶意路径输入可能会尝试访问 /memories 目录外的文件。你的实现必须验证所有路径以防止目录遍历攻击。

考虑这些防护措施：

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

错误处理

内存工具使用与文本编辑器工具相同的错误处理模式。常见错误包括文件未找到、权限错误和无效路径。

与上下文编辑一起使用

内存工具可以与上下文编辑结合使用，当对话上下文超过配置的阈值时，它会自动清除旧的工具结果。这种组合使长时间运行的代理工作流能够避免超过上下文限制。

它们如何协同工作

启用上下文编辑且对话接近清除阈值时，Claude 会自动收到警告通知。这会促使 Claude 在这些结果从上下文窗口中清除之前，将工具结果中的任何重要信息保存到内存文件中。

工具结果被清除后，Claude 可以在需要时从内存文件中检索存储的信息，有效地将内存视为其工作上下文的扩展。这使 Claude 能够：

继续复杂的多步工作流，而不会丢失关键信息
即使在工具结果被移除后，也能引用过去的工作和决策
在超过典型上下文限制的对话中保持连贯的上下文
随着时间推移构建知识库，同时保持活跃上下文窗口的可管理性

示例工作流

考虑一个有许多文件操作的代码重构项目：

Claude 对文件进行许多编辑，生成许多工具结果
当上下文增长并接近你的阈值时，Claude 收到警告
Claude 将迄今为止所做的更改总结到内存文件中（例如，/memories/refactoring_progress.xml）
上下文编辑自动清除较旧的工具结果
Claude 继续工作，在需要回忆已完成的更改时引用内存文件
工作流可以无限期继续，Claude 管理活跃上下文和持久内存

配置

要同时使用这两个功能：

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # 你的其他工具
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

你也可以排除内存工具调用被清除，以确保 Claude 始终能够访问最近的内存操作：

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}

工具

内存工具

Claude 的内存工具使其能够通过内存文件目录在对话间存储和检索信息。

内存工具在客户端运行——你可以通过自己的基础设施控制数据的存储位置和方式。

内存工具目前处于测试阶段。要启用它，请在 API 请求中使用测试版标头 context-management-2025-06-27。

请通过我们的反馈表单分享你对此功能的反馈。

用例

在多个代理执行间维护项目上下文
从过去的交互、决策和反馈中学习
随着时间推移构建知识库
启用跨对话学习，使 Claude 在重复工作流中不断改进

工作原理

示例：内存工具调用如何工作

当你要求 Claude 帮助完成任务时，Claude 会自动先检查其内存目录。以下是典型交互的样子：

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": "Directory: /memories\n- customer_service_guidelines.xml\n- 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": "<guidelines>\n<addressing_customers>\n- Always address customers by their first name\n- 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 Sonnet 4.5 (claude-sonnet-4-5-20250929)
Claude Sonnet 4 (claude-sonnet-4-20250514)
Claude Haiku 4.5 (claude-haiku-4-5-20251001)
Claude Opus 4.5 (claude-opus-4-5-20251101)
Claude Opus 4.1 (claude-opus-4-1-20250805)
Claude Opus 4 (claude-opus-4-20250514)

快速开始

要使用内存工具：

在 API 请求中包含测试版标头 context-management-2025-06-27
将内存工具添加到你的请求中
为内存操作实现客户端处理程序

有关工作示例，请参阅：

Python：examples/memory/basic.py
TypeScript：examples/tools-helpers-memory.ts

基本用法

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "content-type: application/json" \
    --header "anthropic-beta: context-management-2025-06-27" \
    --data '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 2048,
        "messages": [
            {
                "role": "user",
                "content": "I'\''m working on a Python web scraper that keeps crashing with a timeout error. Here'\''s the problematic function:\n\n```python\ndef fetch_page(url, retries=3):\n    for i in range(retries):\n        try:\n            response = requests.get(url, timeout=5)\n            return response.text\n        except requests.exceptions.Timeout:\n            if i == retries - 1:\n                raise\n            time.sleep(1)\n```\n\nPlease help me debug this."
            }
        ],
        "tools": [{
            "type": "memory_20250818",
            "name": "memory"
        }]
    }'

工具命令

你的客户端实现需要处理这些内存工具命令：

view

显示目录内容或文件内容，支持可选的行范围：

{
  "command": "view",
  "path": "/memories",
  "view_range": [1, 10]  // 可选：查看特定行
}

create

创建或覆盖文件：

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

str_replace

替换文件中的文本：

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

insert

在特定行插入文本：

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

delete

删除文件或目录：

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

rename

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

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

提示指导

当包含内存工具时，我们会自动将此指令包含到系统提示中：

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 写入内存的内容，例如，"仅将与 <topic> 相关的信息写入你的内存系统。"

安全考虑

实现内存存储时，以下是重要的安全问题：

敏感信息

Claude 通常会拒绝在内存文件中写下敏感信息。但是，你可能想要实现更严格的验证，以去除可能的敏感信息。

文件存储大小

考虑跟踪内存文件大小，并防止文件增长过大。考虑添加内存读取命令可以返回的最大字符数，并让 Claude 分页浏览内容。

内存过期

考虑定期清除在较长时间内未被访问的内存文件。

路径遍历保护

恶意路径输入可能会尝试访问 /memories 目录外的文件。你的实现必须验证所有路径以防止目录遍历攻击。

考虑这些防护措施：

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

错误处理

内存工具使用与文本编辑器工具相同的错误处理模式。常见错误包括文件未找到、权限错误和无效路径。

与上下文编辑一起使用

它们如何协同工作

工具结果被清除后，Claude 可以在需要时从内存文件中检索存储的信息，有效地将内存视为其工作上下文的扩展。这使 Claude 能够：

继续复杂的多步工作流，而不会丢失关键信息
即使在工具结果被移除后，也能引用过去的工作和决策
在超过典型上下文限制的对话中保持连贯的上下文
随着时间推移构建知识库，同时保持活跃上下文窗口的可管理性

示例工作流

考虑一个有许多文件操作的代码重构项目：

Claude 对文件进行许多编辑，生成许多工具结果
当上下文增长并接近你的阈值时，Claude 收到警告
Claude 将迄今为止所做的更改总结到内存文件中（例如，/memories/refactoring_progress.xml）
上下文编辑自动清除较旧的工具结果
Claude 继续工作，在需要回忆已完成的更改时引用内存文件
工作流可以无限期继续，Claude 管理活跃上下文和持久内存

配置

要同时使用这两个功能：

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=4096,
    messages=[...],
    tools=[
        {
            "type": "memory_20250818",
            "name": "memory"
        },
        # 你的其他工具
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {
                    "type": "input_tokens",
                    "value": 100000
                },
                "keep": {
                    "type": "tool_uses",
                    "value": 3
                }
            }
        ]
    }
)

你也可以排除内存工具调用被清除，以确保 Claude 始终能够访问最近的内存操作：

context_management={
    "edits": [
        {
            "type": "clear_tool_uses_20250919",
            "exclude_tools": ["memory"]
        }
    ]
}