记忆工具使Claude能够通过记忆文件目录在对话之间存储和检索信息。Claude可以创建、读取、更新和删除在会话之间持续存在的文件，使其能够随着时间的推移积累知识，而无需将所有内容保留在上下文窗口中。 记忆工具在客户端运行——您可以通过自己的基础设施控制数据的存储位置和方式。
记忆工具目前处于测试阶段。要启用它，请在您的API请求中使用测试版头部context-management-2025-06-27。请通过我们的反馈表单联系我们，分享您对此功能的反馈。

​
使用场景

  • 在多个代理执行之间维护项目上下文
  • 从过去的交互、决策和反馈中学习
  • 随着时间的推移构建知识库
  • 启用跨对话学习，让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. 为记忆操作实现客户端处理程序
要在您的应用程序中处理记忆工具操作，您需要为每个记忆命令实现处理程序。我们的SDK提供记忆工具助手来处理工具接口——您可以子类化BetaAbstractMemoryTool（Python）或使用betaMemoryTool（TypeScript）来实现您自己的记忆后端（基于文件、数据库、云存储、加密文件等）。有关工作示例，请参阅：

​
基本用法

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目录之外的文件。您的实现必须验证所有路径以防止目录遍历攻击。
考虑这些安全措施：
  • 验证所有路径都以/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"]
        }
    ]
}