使用代理记忆

Managed Agents API 会话默认是临时的。当会话结束时，代理学到的任何内容都会消失。记忆存储让代理能够跨会话保留学习内容：用户偏好、项目约定、之前的错误和领域背景。

概述

记忆存储是一个工作区范围的文本文档集合，针对 Claude 进行了优化。当一个或多个记忆存储附加到会话时，代理会在开始任务前自动检查存储，并在完成后写入持久化学习内容 - 您这边无需额外的提示或配置。

存储中的每个记忆可以通过 API 或 Console 直接访问和编辑，允许调整、导入和导出记忆。

对记忆的每次更改都会创建一个不可变的记忆版本来支持审计和回滚记忆更改。

创建记忆存储

为存储指定一个 name 和 description。描述会传递给代理，告诉它存储包含什么内容。

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)
print(store.id)  # memstore_01Hx...

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

用内容填充它（可选）

在任何代理运行之前，用参考资料预加载存储：

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

将记忆存储附加到会话

记忆存储在会话的 resources[] 数组中附加。

可选地包含一个 prompt，如果您想为 Claude 提供会话特定的指令，说明如何使用此记忆存储。它会与记忆存储的 name 和 description 一起提供给 Claude，并且上限为 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",
            "prompt": "User preferences and project context. Check before starting any task.",
        }
    ],
)

每个会话最多支持 8 个记忆存储。当记忆的不同部分有不同的所有者或访问规则时，附加多个存储。常见原因：

• 共享参考资料 - 一个只读存储附加到许多会话（标准、约定、领域知识），与每个会话自己的读写学习内容分开。
• 映射到您产品的结构 - 每个最终用户、每个团队或每个项目一个存储，同时共享单个代理配置。
• 不同的生命周期 - 一个存储比任何单个会话的生命周期更长，或者您想按自己的计划存档。

记忆工具

当记忆存储附加到会话时，代理会自动获得对记忆工具的访问权限。代理与记忆存储的交互被注册为事件流中的 agent.tool_use 事件。

查看和编辑记忆

记忆存储可以通过 API 直接管理。使用此功能来构建审查工作流、纠正错误的记忆或在任何会话运行之前填充存储。

列出记忆

列表不返回记忆内容，只返回对象元数据。使用 path_prefix 进行目录范围的列表（包括尾部斜杠：/notes/ 匹配 /notes/a.md 但不匹配 /notes_backup/old.md）。

page = client.beta.memory_stores.memories.list(
    store.id,
    path_prefix="/",
)
for memory in page.data:
    print(
        f"{memory.path}  ({memory.size_bytes} bytes, sha={memory.content_sha256[:8]})"
    )

读取记忆

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

mem = client.beta.memory_stores.memories.retrieve(
    memory_id,
    memory_store_id=store.id,
)
print(mem.content)

创建记忆

使用 memories.write 通过路径来 upsert 记忆。如果路径处不存在任何内容，则创建它；如果记忆已经存在，其内容会被替换。要通过 mem_... ID 变更现有记忆（例如，重命名其路径或安全地应用内容编辑），请改用 memories.update（见下面的更新记忆）。

mem = client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use tabs, not spaces.",
)

安全写入（乐观并发）

将 precondition={"type": "not_exists"} 传递给 memories.write 以使其成为仅创建保护。如果路径处已存在记忆，写入会返回 409 memory_precondition_failed 而不是替换它。在填充存储时使用此功能，您想避免覆盖现有内容。

client.beta.memory_stores.memories.write(
    memory_store_id=store.id,
    path="/preferences/formatting.md",
    content="Always use 2-space indentation.",
    precondition={"type": "not_exists"},
)

要安全地编辑现有记忆（读取、修改、写回而不覆盖并发更改），请改用 memories.update 和 content_sha256 前置条件。见下面的更新记忆。

更新记忆

memories.update() 通过其 mem_... ID 修改现有记忆。您可以在一次调用中更改 content、path（重命名）或两者。

重命名到已占用的路径会返回 409 conflict。调用者必须删除或重命名阻止程序，或传递 precondition={"type": "not_exists"} 以使重命名成为无操作（如果目标处已存在任何内容）。

下面的示例将记忆重命名为存档路径：

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    path="/archive/2026_q1_formatting.md",
)

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

要编辑记忆的内容而不覆盖并发写入，请传递 content_sha256 前置条件。更新仅在存储的哈希仍与您读取的哈希匹配时应用；不匹配时返回 409 memory_precondition_failed，此时您重新读取记忆并针对新状态重试。

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,
)

可选地传递 expected_content_sha256 进行条件删除。

审计记忆更改

对记忆的每次变更都会创建一个不可变的记忆版本（memver_...）。版本在父记忆的生命周期内累积，并形成其下方的审计和回滚表面。实时 memories.retrieve 调用总是返回当前头部；版本端点提供完整历史。

每次变更都会写入新版本：

• 对路径的第一个 memories.write 创建一个带有 operation: "created" 的版本。
• 更改 content、path 或两者的 memories.update 创建一个带有 operation: "modified" 的版本。
• memories.delete 创建一个带有 operation: "deleted" 的版本。

使用版本端点来审计哪个用户或代理何时更改了什么，检查或恢复先前的快照，以及使用 redact 从历史中清除敏感内容。

列出版本

列出存储的分页版本元数据，最新的优先。按 memory_id、operation（created、modified 或 deleted）、session_id、api_key_id 或 created_at_gte/created_at_lte 时间范围进行筛选。列表响应不包括 content 正文；当您需要完整内容时，使用 retrieve 获取单个版本。

for v in client.beta.memory_stores.memory_versions.list(
    store.id,
    memory_id=mem.id,
):
    print(f"{v.id}: {v.operation}")

检索版本

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

version = client.beta.memory_stores.memory_versions.retrieve(
    version_id,
    memory_store_id=store.id,
)
print(version.content)

编辑版本

编辑会从历史版本中清除内容，同时保留审计跟踪（谁做了什么，何时做的）。将其用于合规工作流，例如删除泄露的秘密、个人身份信息或用户删除请求。编辑会硬清除 content、content_sha256、content_size_bytes 和 path；所有其他字段（包括参与者和时间戳）都会保留。

client.beta.memory_stores.memory_versions.redact(
    version_id,
    memory_store_id=store.id,
)