使用代理记忆

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



概述

"Memory store"（记忆存储）是一个以工作区为范围、针对 Claude 优化的文本文档集合。当您将存储附加到会话时，它会作为目录挂载到会话的沙箱中。代理使用与文件系统其余部分相同的文件工具来读取和写入它，并且描述每个挂载的说明会自动添加到系统提示中，告诉代理去哪里查找。这些交互需要代理工具集；请确保在代理创建期间启用它。

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

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



创建记忆存储

为存储指定 name 和 description。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[] 数组附加。与文件和仓库资源不同，记忆存储只能在会话创建时附加；不支持在运行中的会话中添加或移除记忆存储。

可以选择包含 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"

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



编辑删除（redact）版本

Redact（编辑删除）会从历史版本中清除内容，同时保留审计跟踪（谁在何时做了什么）。可将其用于合规工作流，例如移除泄露的密钥、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。



记忆管理最佳实践

当存储达到其 2,000 条记忆的上限时，对新记忆的写入会失败：包括直接的 memories.create 调用以及代理对未映射路径的文件写入。现有记忆仍然可读可编辑。以下实践可帮助您保持在上限之下，并在达到上限时优雅地恢复。

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

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

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

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