使用智能体记忆

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



概述

记忆存储是一个工作区范围内的文本文档集合，专为 Claude 优化。当您将存储附加到会话时，它会作为目录挂载到会话的沙箱内。智能体使用与操作文件系统其余部分相同的文件工具来读写它，并且描述每个挂载点的说明会自动添加到系统提示中，告诉智能体在哪里查找。这些交互需要智能体工具集；请确保在创建智能体时启用它。

存储中的每条记忆（memory）都通过路径寻址，可以直接通过 API 或 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[] 数组附加。与文件和代码仓库资源不同，记忆存储只能在会话创建时附加；不支持在运行中的会话上添加或移除记忆存储。

可选地包含 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/ 下的目录挂载到会话的沙箱内。目录名是存储的显示名称经过清理后的文件系统安全标识符（转为小写；连续的非字母数字字符替换为单个连字符），因此名为 "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 过滤，以便像浏览目录一样浏览某个路径：

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

有关完整参数和响应架构，请参阅列出记忆参考文档。



读取记忆

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

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)
jq -r '.data[] | "\(.id): \(.operation)"' <<< "$versions"
version_id=$(jq -r '.data[1].id' <<< "$versions")

有关完整参数和响应架构，请参阅列出记忆版本参考文档。



检索版本

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

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

有关完整参数和响应架构，请参阅检索记忆版本参考文档。



编辑版本

编辑（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 删除过时或冗余的记忆。您还可以运行梦境会话（dreaming session），它会将碎片化的内容整合到一个单独的新输出存储中，而不是修改原始存储。将您的会话切换到该输出存储，然后归档或删除原始存储。

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

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