记忆工具

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

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

使用场景

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

工作原理

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

由于这是一个客户端工具，Claude会进行工具调用来执行记忆操作，而您的应用程序在本地执行这些操作。这让您完全控制记忆的存储位置和方式。为了安全起见，您应该将所有记忆操作限制在/memories目录中。

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

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

1. 用户请求：

"帮我回复这个客户服务工单。"

2. Claude检查记忆目录：

"我将帮助您回复客户服务工单。让我检查一下我的记忆以获取任何先前的上下文。"

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使用记忆来提供帮助：

"根据您的客户服务指南，我可以帮助您制作回复。请分享工单详情..."

支持的模型

记忆工具可用于：

• 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.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)

入门指南

要使用记忆工具：

1. 在您的API请求中包含测试版头部context-management-2025-06-27
2. 将记忆工具添加到您的请求中
3. 为记忆操作实现客户端处理程序

基本用法

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"
}

提示指导

当包含记忆工具时，我们会自动将此指令添加到系统提示中：

重要：在做任何其他事情之前，始终查看您的记忆目录。
记忆协议：
1. 使用您的`memory`工具的`view`命令检查早期进度。
2. ...（处理任务）...
     - 在取得进展时，在您的记忆中记录状态/进度/想法等。
假设中断：您的上下文窗口可能随时重置，因此您面临丢失未记录在记忆目录中的任何进度的风险。

如果您观察到Claude创建杂乱的记忆文件，您可以包含此指令：

注意：编辑记忆文件夹时，始终尝试保持其内容最新、连贯和有组织。您可以重命名或删除不再相关的文件。除非必要，否则不要创建新文件。

您还可以指导Claude向记忆中写入什么，例如，"只在您的记忆系统中记录与<主题>相关的信息。"

安全考虑

以下是实现记忆存储时的重要安全考虑：

敏感信息

Claude通常会拒绝在记忆文件中写下敏感信息。但是，您可能希望实现更严格的验证，以过滤掉潜在的敏感信息。

文件存储大小

考虑跟踪记忆文件大小并防止文件变得过大。考虑为记忆读取命令可以返回的最大字符数添加限制，并让Claude分页浏览内容。

记忆过期

考虑定期清理长时间未访问的记忆文件。

路径遍历保护

考虑这些安全措施：

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

错误处理

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

与上下文编辑一起使用

记忆工具可以与上下文编辑结合使用，当对话上下文超出配置的阈值时，它会自动清除旧的工具结果。这种组合使得长时间运行的代理工作流程成为可能，否则会超出上下文限制。

它们如何协同工作

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

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

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

示例工作流程

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

1. Claude对文件进行大量编辑，生成许多工具结果
2. 随着上下文增长并接近您的阈值，Claude收到警告
3. Claude将到目前为止所做的更改总结到记忆文件中（例如，/memories/refactoring_progress.xml）
4. 上下文编辑自动清除较旧的工具结果
5. Claude继续工作，在需要回忆已完成的更改时引用记忆文件
6. 工作流程可以无限期地继续，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"]
        }
    ]
}