使用智能体记忆

默认情况下，每个 Managed Agents 会话都以全新的上下文开始。当会话结束时，智能体积累的任何状态都会消失。"Memory store"（记忆存储）让智能体能够跨会话携带信息：用户偏好、项目约定、先前的错误以及领域上下文。

概述

记忆存储是一个工作区范围内、针对 Claude 优化的文本文档集合。当您将存储附加到会话时，它会作为一个目录挂载到会话的沙箱中。智能体使用与操作文件系统其余部分相同的文件工具来读写它，并且描述每个挂载的说明会自动添加到系统提示中，告诉智能体应该在哪里查找。这些交互需要智能体工具集；请确保在创建智能体时启用它。在自托管沙箱上，该目录不是实时挂载。相反，SDK 的环境工作进程会在智能体的工具运行之前将每个附加的存储下载到您的沙箱中，并使该副本与存储保持同步。

存储中的每条记忆（memory）都通过路径寻址，可以直接通过 API 或 Claude Console 读取和编辑，从而支持调优、导入和导出。

对记忆的每次更改都会创建一个不可变的记忆版本（memory version），为智能体写入的所有内容提供审计跟踪和时间点恢复能力。

创建记忆存储

为存储指定 name 和 description。描述会传递给智能体，告诉它存储中包含什么内容。

store_id=$(ant beta:memory-stores create \
  --name "User Preferences" \
  --description "Per-user preferences and project context." \
  --transform id --raw-output)

记忆存储的 id（memstore_...）是您在将存储附加到会话时需要传递的值。

预填充内容（可选）

在任何智能体运行之前，为存储预加载参考资料：

ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/formatting_standards.md" \
  --content "All reports use GAAP formatting. Dates are ISO-8601..." \
  > /dev/null

将记忆存储附加到会话

记忆存储在创建会话时通过会话的 resources[] 数组附加。与文件资源不同，记忆存储只能在会话创建时附加；不支持在运行中的会话中添加或移除记忆存储。对于云端和自托管环境上的会话，附加记忆存储的方式相同；自托管环境仅接受 memory_store 资源。

可以选择包含 instructions，为智能体应如何使用此存储提供会话特定的指导。它会与存储的 name 和 description 一起展示给智能体，上限为 4,096 个字符。

您还可以配置 access。它默认为 read_write（在以下示例中显式展示），但也支持 read_only。

ant beta:sessions create <<YAML
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.
YAML

每个会话最多支持 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 错误。

ant beta:memory-stores:memories list \
  --memory-store-id "$store_id" \
  --path-prefix "/"

有关完整参数和响应模式，请参阅列出记忆参考。

读取记忆

获取单条记忆会返回完整内容。

ant beta:memory-stores:memories retrieve \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id"

有关完整参数和响应模式，请参阅检索记忆参考。

创建记忆

memories.create 在给定的 path 处创建一条记忆。创建操作不会覆盖；要更改现有记忆，请使用 memories.update。

mem=$(ant beta:memory-stores:memories create \
  --memory-store-id "$store_id" \
  --path "/preferences/formatting.md" \
  --content "Always use tabs, not spaces." \
  --format json)
mem_id=$(jq -r '.id' <<< "$mem")
mem_sha=$(jq -r '.content_sha256' <<< "$mem")

有关完整参数和响应模式，请参阅创建记忆参考。

更新记忆

memories.update 通过 ID 修改现有记忆。您可以更改 content、path（重命名）或两者。以下示例将一条记忆重命名到归档路径：

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --path "/archive/2026_q1_formatting.md" \
  > /dev/null

有关完整参数和响应模式，请参阅更新记忆参考。

安全的内容编辑（乐观并发）

为避免覆盖并发写入，请传递 content_sha256 前置条件。只有当存储的内容哈希仍与您读取时的哈希匹配时，更新才会生效；如果不匹配，请重新读取记忆并针对最新状态重试。

ant beta:memory-stores:memories update \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --content "CORRECTED: Always use 2-space indentation." \
  --precondition "{type: content_sha256, content_sha256: $mem_sha}" \
  > /dev/null

删除记忆

ant beta:memory-stores:memories delete \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  > /dev/null

有关完整参数和响应模式，请参阅删除记忆参考。

审计记忆更改

对记忆的每次变更都会创建一个不可变的记忆版本（memver_...）。使用版本端点可以审计谁在何时更改了什么、检查或恢复先前的快照，以及通过脱敏（redact）从历史记录中清除敏感内容。

版本属于存储（而非单条记忆），并且在记忆本身被删除时不会被删除，因此审计跟踪也涵盖已删除的记忆，但受下文所述的保留策略约束。版本在写入后保留 30 天；不过，活动记忆的最近版本无论存在多久都会始终保留，因此不常更改的记忆可能会保留超过 30 天的历史记录。实时的 memories.retrieve 调用始终返回最新版本；版本端点则为您提供保留的历史记录。

没有专门的恢复端点；要回滚，请检索您想要的版本，并使用 memories.update 将其 content 写回（如果父记忆已被删除，则使用 memories.create，前提是您想要的版本仍被保留）。

过去的记忆版本可能会在 30 天后被删除。要更长时间地保留记忆历史，请通过 API 导出版本。

列出版本

列出存储的版本历史，最新的在前。以下示例筛选出单条记忆的历史：

versions=$(ant beta:memory-stores:memory-versions list \
  --memory-store-id "$store_id" \
  --memory-id "$mem_id" \
  --format json)
# `list --format json` 为每个条目输出一个 JSON 对象。
jq -r '"\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -rs '.[1].id' <<< "$versions")

有关完整参数和响应模式，请参阅列出记忆版本参考。

检索版本

获取单个版本会返回与列表响应相同的字段，外加完整的 content 正文。

ant beta:memory-stores:memory-versions retrieve \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

有关完整参数和响应模式，请参阅检索记忆版本参考。

脱敏版本

脱敏会从历史版本中清除内容，同时保留审计跟踪（谁在何时做了什么）。可将其用于合规工作流，例如移除泄露的密钥、个人身份信息（PII）或处理用户删除请求。

作为活动记忆当前头部的版本无法被脱敏。请先写入一个新版本（或删除该记忆），然后再对旧版本进行脱敏。

ant beta:memory-stores:memory-versions redact \
  --memory-store-id "$store_id" \
  --memory-version-id "$version_id"

有关完整参数和响应模式，请参阅脱敏记忆版本参考。

管理记忆存储

除了 create 之外，记忆存储还支持 retrieve、update、list、archive 和 delete。

列出存储

列出工作区中的存储。默认排除已归档的存储；传递 include_archived: true 可将其包含在内。

ant beta:memory-stores list --include-archived

有关完整参数和响应模式，请参阅列出记忆存储参考。

归档存储

归档会使存储变为只读，并阻止其被附加到新会话。归档是单向的；没有取消归档操作。

ant beta:memory-stores archive --memory-store-id "$store_id"

有关完整参数和响应模式，请参阅归档记忆存储参考。

要永久移除存储及其所有记忆和版本，请使用 memory_stores.delete。

记忆管理最佳实践

当存储达到 10,000 条记忆的上限时，对新记忆的写入会失败：包括直接的 memories.create 调用以及智能体对未映射路径的文件写入。现有记忆仍然可读可编辑。以下实践可帮助您远低于上限，并在达到上限时从容恢复。

• **使用专注的存储。**与其使用一个大型通用存储，不如使用更小的专用存储：每个用户一个、共享领域知识一个、项目特定上下文一个。每个存储都有自己的 10,000 条记忆上限，因此保持存储范围明确可以降低任何单个存储被填满的可能性。

• **在存储填满之前进行精简或清理。**使用 memories.delete 删除过时或冗余的记忆。您还可以运行梦境会话，它会将碎片化的内容整合到一个单独的新输出存储中，而不是修改原始存储。将您的会话切换到该输出存储，然后归档或删除原始存储。

• **在合适的时候附加新存储。**如果某个存储已经超出其有用范围，请为新内容附加一个全新的存储，并以 read_only 访问权限附加原始存储。智能体可以从两者读取，同时只写入新存储。

• **在适当的情况下限制写入权限。**仅读取共享参考资料的会话不需要 read_write。将写入权限限定在实际添加新记忆的会话上，可以更容易地追踪增长的来源。