使用智能体记忆
使用记忆存储为您的智能体提供可跨会话持久保存的记忆。
默认情况下,每个 Managed Agents 会话都以全新的上下文开始。当会话结束时,智能体积累的任何状态都会消失。"Memory store"(记忆存储)让智能体能够跨会话携带信息:用户偏好、项目约定、先前的错误以及领域上下文。
概述
“memory store”(记忆存储)是一个工作区范围内、针对 Claude 优化的文本文档集合。当您将存储附加到会话时,它会作为目录挂载到会话的沙箱中。智能体使用与文件系统其他部分相同的文件工具来读写它,并且描述每个挂载的说明会自动添加到系统提示中,告诉智能体去哪里查找。这些交互需要 agent toolset(智能体工具集);请确保在创建智能体时启用它。在自托管沙箱上,该目录不是实时挂载。相反,您的环境 worker 会在智能体的工具运行之前将每个附加的存储下载到您的沙箱中,并使该副本与存储保持同步。
存储中的每条记忆(memory)都通过路径寻址,可以直接通过 API 或 Claude Console 读取和编辑,从而支持调优、导入和导出。
对记忆的每次更改都会创建一个不可变的记忆版本(memory version),为智能体写入的所有内容提供审计跟踪和时间点恢复能力。
创建记忆存储
为存储提供 name 和 description。描述会传递给智能体,告诉它该存储包含什么内容。
ant apply memory_store.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/memory_store.json
name: User Preferences
description: Per-user preferences and project context.记忆存储的 id(memstore_...)是您将存储附加到会话时传递的值。
预填充内容(可选)
在任何智能体运行之前,为存储预加载参考资料:
client.beta.memory_stores.memories.create(
store.id,
path="/formatting_standards.md",
content="All reports use GAAP formatting. Dates are ISO-8601...",
)将记忆存储附加到会话
记忆存储在创建会话时通过会话的 resources 数组附加。与文件资源不同,记忆存储只能在创建会话时附加;不支持在运行中的会话中添加或移除记忆存储。对于云端环境和自托管环境上的会话,附加记忆存储的方式相同;自托管环境仅接受 memory_store 资源。
您可以选择包含 instructions,为智能体应如何使用此存储提供特定于会话的指导。它会与存储的 name 和 description 一起展示给智能体,上限为 4,096 个字符。
您还可以配置 access。它默认为 read_write(在以下示例中显式展示),但也支持 read_only。
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
resources=[
{
"type": "memory_store",
"memory_store_id": store.id,
"access": "read_write",
"instructions": "User preferences and project context. Check before starting any task.",
}
],
)每个会话最多支持 8 个记忆存储。当记忆的不同部分有不同的所有者或访问规则时,请附加多个存储。常见原因包括:
- 共享参考资料:一个附加到许多会话的只读存储(标准、约定、领域知识),与每个会话自己的读写存储分开
- 映射到您产品的结构:为每个最终用户、团队或项目各设一个存储,同时共享单一的智能体配置
- 不同的生命周期:一个比任何单个会话存续更久的存储,或者您希望按其自身计划进行归档的存储
智能体如何访问记忆
每个附加的存储都作为 /mnt/memory/ 下的一个目录挂载到会话的沙箱中。目录名是将存储的显示名称转换为文件系统安全的 slug(转为小写,并将每段连续的非字母数字字符替换为单个连字符),因此名为 “Demo Memory” 的存储会挂载在 /mnt/memory/demo-memory/。确切路径会在会话的记忆存储资源的 mount_path 字段中返回;请从该字段读取,而不是自行构造。智能体使用标准的智能体工具集读写存储。挂载路径下的写入会持久化回存储,并在共享该存储的会话之间保持同步;写入 /mnt/memory/ 下任何其他路径都会失败,因为沙箱以只读方式挂载该父目录。每个挂载的简短描述(显示名称、挂载路径、访问模式、存储的 description 以及任何 instructions)会自动添加到系统提示中。
access 在文件系统层面强制执行:read_only 挂载会拒绝写入,而对 read_write 挂载的写入会生成归属于该会话的记忆版本。
智能体的读写操作会在事件流中显示为普通的 agent.tool_use 和 agent.tool_result 事件,对应于触及该挂载的任何工具。
查看和编辑记忆
记忆存储可以直接通过 API 管理。可用于构建审核工作流、纠正错误记忆,或在任何会话运行之前预填充存储。
列出记忆
列出存储中的记忆。结果以稳定的、由服务器定义的顺序返回。
path_prefix将列表范围限定到一个目录。它必须以/结尾,并匹配完整的路径段,因此path_prefix=/notes/会返回/notes/todo.md,但不会返回/notes-archive/todo.md。depth控制列表在path_prefix之下深入的层级:省略它(或传入0)会列出整个子树,传入1则仅列出直接子项。其他值会返回400错误。
page = client.beta.memory_stores.memories.list(
store.id,
path_prefix="/",
)
for item in page.data:
print(item.type, item.path)有关完整参数和响应结构,请参阅列出记忆可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
读取记忆
获取单条记忆会返回完整内容。
retrieved = client.beta.memory_stores.memories.retrieve(
mem.id,
memory_store_id=store.id,
)
print(retrieved.content)有关完整参数和响应结构,请参阅检索记忆可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
创建记忆
client.beta.memory_stores.memories.create() 会在给定的 path 处创建一条记忆。创建操作不会覆盖已有内容;要更新现有记忆,请使用 client.beta.memory_stores.memories.update()。
mem = client.beta.memory_stores.memories.create(
store.id,
path="/preferences/formatting.md",
content="Always use tabs, not spaces.",
)有关完整参数和响应结构,请参阅创建记忆可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
更新记忆
client.beta.memory_stores.memories.update() 按 ID 修改现有记忆。您可以更改 content、path(即重命名),或两者都更改。以下示例将一条记忆重命名到归档路径:
client.beta.memory_stores.memories.update(
mem.id,
memory_store_id=store.id,
path="/archive/2026_q1_formatting.md",
)有关完整参数和响应结构,请参阅更新记忆可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
安全的内容编辑(乐观并发)
为避免覆盖并发写入,请传入 content_sha256 前置条件。只有当存储的内容哈希仍与您读取时的哈希匹配时,更新才会生效;如果不匹配,请重新读取记忆,并基于最新状态重试。
client.beta.memory_stores.memories.update(
memory_id=mem.id,
memory_store_id=store.id,
content="CORRECTED: Always use 2-space indentation.",
precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)删除记忆
client.beta.memory_stores.memories.delete(
mem.id,
memory_store_id=store.id,
)有关完整参数和响应结构,请参阅删除记忆可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
审计记忆更改
对记忆的每次变更都会创建一个不可变的记忆版本(memver_...)。使用版本端点可以审计谁在何时更改了什么、检查或恢复先前的快照,以及通过脱敏(redact)从历史记录中清除敏感内容。
版本属于存储(而非单条记忆),并且在记忆本身被删除时不会被删除,因此审计跟踪也涵盖已删除的记忆,但须遵守后文所述的保留规则。版本在写入后保留 30 天;不过,活动记忆的近期版本无论时间多久都会始终保留,因此不常更改的记忆可能会保留超过 30 天的历史记录。实时的 client.beta.memory_stores.memories.retrieve() 调用始终返回最新版本;版本端点则为您提供保留的历史记录。
没有专门的恢复端点;要回滚,请检索您想要的版本,并使用 client.beta.memory_stores.memories.update() 将其 content 写回(如果父记忆已被删除,则使用 client.beta.memory_stores.memories.create(),前提是您想要的版本仍被保留)。
过去的记忆版本可能会在 30 天后被删除。要更长时间地保留记忆历史,请通过 API 导出版本。
列出版本
列出存储的版本历史,最新的在前。以下示例筛选出单条记忆的历史:
versions = client.beta.memory_stores.memory_versions.list(
store.id,
memory_id=mem.id,
)
for version in versions:
print(f"{version.id}: {version.operation}")
version_id = versions.data[1].id有关完整参数和响应结构,请参阅列出记忆版本可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
检索版本
获取单个版本会返回与列表响应相同的字段,外加完整的 content 正文。
version = client.beta.memory_stores.memory_versions.retrieve(
version_id,
memory_store_id=store.id,
)
print(version.content)有关完整参数和响应结构,请参阅检索记忆版本可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
脱敏版本
脱敏(redact)会从历史版本中清除内容,同时保留审计跟踪(谁在何时做了什么)。可将其用于合规工作流,例如删除泄露的密钥或个人身份信息(PII),或满足用户的删除请求。
作为活动记忆当前头部的版本无法被脱敏。请先写入一个新版本(或删除该记忆),然后再对旧版本进行脱敏。
client.beta.memory_stores.memory_versions.redact(
version_id,
memory_store_id=store.id,
)有关完整参数和响应结构,请参阅脱敏记忆版本可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考。
管理记忆存储
除了 create可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。 之外,记忆存储还支持 retrieve可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。、update可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。、list可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。、archive可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。 和 delete可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。。
列出存储
列出工作区中的存储。默认情况下不包括已归档的存储;将 include_archived 设置为 true 即可包含它们。
for memory_store in client.beta.memory_stores.list(include_archived=True):
print(memory_store.id, memory_store.name, memory_store.archived_at)有关完整参数和响应结构,请参阅列出记忆存储可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
归档存储
归档会使存储变为只读,并阻止其被附加到新会话。归档是单向的;没有取消归档操作。
client.beta.memory_stores.archive(store.id)有关完整参数和响应结构,请参阅归档记忆存储可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。参考文档。
要永久删除存储可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片,按 Escape 键返回。及其所有记忆和版本,请调用 client.beta.memory_stores.delete()。
记忆管理最佳实践
当存储达到 10,000 条记忆的上限时,写入新记忆的操作会失败:包括直接的 client.beta.memory_stores.memories.create() 调用,以及智能体对未映射路径的文件写入。现有记忆仍可读取和编辑。以下实践可帮助您远低于该上限,并在达到上限时从容恢复。
-
使用专注的存储。与其使用一个大型通用存储,不如使用更小的专用存储:每个用户一个,共享领域知识一个,项目特定上下文一个。每个存储都有各自 10,000 条记忆的上限,因此限定存储范围可以降低任何单个存储被填满的可能性。
-
在存储填满之前进行精简或清理。使用
client.beta.memory_stores.memories.delete()删除过时或冗余的记忆。您还可以运行一个梦境会话,它会将零散的内容整合到一个单独的新输出存储中,而不是修改原始存储。将您的会话切换到该输出存储,然后归档或删除原始存储。 -
在合适的时候附加新存储。如果某个存储已经超出其有用范围,请为新内容附加一个全新的存储,并以
read_only访问权限附加原始存储。智能体可以从两者读取,同时只写入新存储。 -
在适当的情况下限制写入权限。仅读取共享参考资料的会话不需要
read_write。将写入权限限定在实际添加新记忆的会话上,可以更容易地追踪增长的来源。
可用性
Claude API
- 状态
- Beta
- API
- Managed Agents
- Beta 请求头
- 需要
- 模型
- 所有模型
- 注意
在记忆存储调用中同时发送
managed-agents-2026-04-01和agent-memory-2026-07-22会返回 400 错误。
Claude Platform on AWS
- 状态
- Beta
- API
- Managed Agents
- Beta 请求头
- 需要
- 模型
- 所有模型
- 注意
在 Claude Platform on AWS 上,自托管环境中的会话无法附加记忆存储。在记忆存储调用中同时发送
managed-agents-2026-04-01和agent-memory-2026-07-22会返回 400 错误。
Claude Models on Google Cloud (Anthropic managed)
- 状态
- Beta
- API
- Managed Agents
- Beta 请求头
- 需要
- 模型
- 所有模型
- 注意
在 Claude Models on Google Cloud (Anthropic managed) 上,自托管环境中的会话不支持记忆存储。在记忆存储调用中同时发送
managed-agents-2026-04-01和agent-memory-2026-07-22会返回 400 错误。
数据处理
数据处理概览适用的端点
/v1/agents/v1/sessions/v1/environments
不具备 ZDR 资格,自托管 Managed Agents 除外。会话是有状态的资源;对话记录会一直保留,直到您将其删除。 了解更多
不具备 HIPAA 资格。适用于所有 Managed Agents 子功能。
此页面对您有帮助吗?