记忆工具使Claude能够通过记忆文件目录在对话之间存储和检索信息。Claude可以创建、读取、更新和删除在会话之间持续存在的文件，使其能够随着时间的推移积累知识，而无需将所有内容保留在上下文窗口中。
记忆工具在客户端运行——您可以通过自己的基础设施控制数据的存储位置和方式。
记忆工具目前处于测试阶段。要启用它，请在您的API请求中使用测试版头部context-management-2025-06-27。请通过我们的反馈表单联系我们，分享您对此功能的反馈。 使用场景
- 在多个代理执行之间维护项目上下文
- 从过去的交互、决策和反馈中学习
- 随着时间的推移构建知识库
- 启用跨对话学习，让Claude在重复工作流程中不断改进
工作原理
启用后，Claude在开始任务之前会自动检查其记忆目录。Claude可以在/memories目录中创建、读取、更新和删除文件，以存储在工作过程中学到的内容，然后在未来的对话中引用这些记忆，以更有效地处理类似任务或从中断的地方继续。
由于这是一个客户端工具，Claude会进行工具调用来执行记忆操作，而您的应用程序在本地执行这些操作。这让您完全控制记忆的存储位置和方式。为了安全起见，您应该将所有记忆操作限制在/memories目录中。
示例：记忆工具调用的工作方式
当您要求Claude帮助完成任务时，Claude会自动首先检查其记忆目录。以下是典型交互的样子：
1. 用户请求：
2. Claude检查记忆目录：
"我将帮助您回复客户服务工单。让我检查一下我的记忆以获取任何先前的上下文。"
{
"type": "tool_use",
"id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"name": "memory",
"input": {
"command": "view",
"path": "/memories"
}
}
{
"type": "tool_result",
"tool_use_id": "toolu_01C4D5E6F7G8H9I0J1K2L3M4",
"content": "Directory: /memories\n- customer_service_guidelines.xml\n- refund_policies.xml"
}
{
"type": "tool_use",
"id": "toolu_01D5E6F7G8H9I0J1K2L3M4N5",
"name": "memory",
"input": {
"command": "view",
"path": "/memories/customer_service_guidelines.xml"
}
}
{
"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..."
}
"根据您的客户服务指南，我可以帮助您制作回复。请分享工单详情..."
支持的模型
记忆工具可用于：
- 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)
入门指南
要使用记忆工具：
- 在您的API请求中包含测试版头部
context-management-2025-06-27
- 将记忆工具添加到您的请求中
- 为记忆操作实现客户端处理程序
要在您的应用程序中处理记忆工具操作，您需要为每个记忆命令实现处理程序。我们的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分页浏览内容。
记忆过期
考虑定期清理长时间未访问的记忆文件。
路径遍历保护
恶意路径输入可能试图访问/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
}
}
]
}
)
context_management={
"edits": [
{
"type": "clear_tool_uses_20250919",
"exclude_tools": ["memory"]
}
]
}
