Managed Agents - Memory Stores / 托管智能体 - 记忆存储

Public beta. Memory stores ship under the agent-memory-2026-07-22 beta header; the SDK sets it automatically on all client.beta.memory_stores.* calls. Don't add managed-agents-2026-04-01 to these calls - sending both headers on a memory store request returns a 400. Attaching a store to a session is a session call and still uses managed-agents-2026-04-01. If client.beta.memory_stores is missing, upgrade to the latest SDK release.

公开测试版。 记忆存储（memory stores）通过 agent-memory-2026-07-22 测试版标头提供；SDK 会在所有 client.beta.memory_stores.* 调用上自动设置该标头。不要在这些调用上添加 managed-agents-2026-04-01 —— 在记忆存储请求上同时发送两个标头会返回 400。把存储挂载到会话属于会话调用，仍然使用 managed-agents-2026-04-01。如果 client.beta.memory_stores 不存在，请升级到最新版 SDK。

Sessions are ephemeral by default - when one ends, anything the agent learned is gone. A memory store is a workspace-scoped collection of small text documents that persists across sessions. When a store is attached to a session (via resources[]), it is mounted into the container as a filesystem directory; the agent reads and writes it with the ordinary file tools, and a system-prompt note tells it the mount is there.

会话默认是临时的 —— 会话结束后，智能体学到的任何内容都会消失。记忆存储（memory store） 是一个以工作区为作用域、可跨会话持久存在的小型文本文档集合。当存储被挂载到某个会话时（通过 resources[]），它会以文件系统目录的形式挂载进容器；智能体用普通文件工具读写它，同时系统提示词中会有一条说明告知它该挂载点存在。

Every mutation to a memory produces an immutable memory version (memver_...), giving you an audit trail and point-in-time rollback/redact.

对记忆的每次变更都会产生一个不可变的记忆版本（memver_...），为你提供审计轨迹以及按时间点回滚/抹除的能力。

Warning: Never store credentials, API keys, or tokens in memory stores. Memories persist across sessions and are returned verbatim into future contexts - a key written once is replayed into every later session that mounts the store. Use vault environment_variable credentials instead (shared/managed-agents-tools.md -> Vaults). If a secret has already been written, delete the memory and redact the affected versions (see "Redact a version" below).

警告：绝不要在记忆存储中保存凭据、API 密钥或令牌。 记忆会跨会话持久存在，并被逐字返回到未来的上下文中 —— 一个只写入过一次的密钥会被重放到之后每一个挂载该存储的会话中。请改用保管库（vault）的 environment_variable 凭据（见 shared/managed-agents-tools.md -> Vaults）。如果密钥已被写入，请删除该记忆并抹除受影响的版本（见下文"Redact a version"）。

【评论】该警告源于记忆跨会话持久并逐字回灌未来上下文的机制：任何写入的机密都会被自动重放，属于针对数据泄漏面的一条关键防护条款。

Object model / 对象模型

Create a store / 创建存储

description is passed to the agent so it knows what the store contains - write it for the model, not for humans.

description 会传给智能体，让它知道存储里有什么 —— 请为模型而不是为人类来写这段描述。

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

Other SDKs: TypeScript client.beta.memoryStores.create({...}); Go client.Beta.MemoryStores.New(ctx, ...). See shared/managed-agents-api-reference.md -> SDK Method Reference for the full per-language table.

其他 SDK：TypeScript 使用 client.beta.memoryStores.create({...})；Go 使用 client.Beta.MemoryStores.New(ctx, ...)。完整的各语言对照表见 shared/managed-agents-api-reference.md -> SDK Method Reference。

Stores support retrieve / update / list (with include_archived, created_at_{gte,lte} filters) / delete / archive. Archive makes the store read-only - existing session attachments continue, new sessions cannot reference it; no unarchive.

存储支持 retrieve / update / list（带 include_archived、created_at_{gte,lte} 过滤器）/ delete / archive。归档会让存储变为只读 —— 已存在的会话挂载继续有效，新会话无法再引用它；且不支持取消归档。

Seed with content (optional) / 预填充内容（可选）

Pre-load reference material before any session runs. memories.create creates a memory at the given path; if a memory already exists there the call returns 409 (memory_path_conflict_error, with the conflicting_memory_id). The store ID is the first positional argument.

在任何会话运行之前预加载参考资料。memories.create 会在给定 path 处创建一条记忆；如果该路径已存在记忆，调用会返回 409（memory_path_conflict_error，附带 conflicting_memory_id）。存储 ID 是第一个位置参数。

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

Attach to a session / 挂载到会话

Memory stores go in the session's resources[] array alongside file and github_repository resources (see shared/managed-agents-environments.md -> Resources). Memory stores attach at session create time only - sessions.resources.add() does not accept memory_store. Sessions on self-hosted environments attach them the same way (and memory_store is the only resource type those environments accept) - see the self-hosted note below.

记忆存储与 file、github_repository 资源一起放入会话的 resources[] 数组（见 shared/managed-agents-environments.md -> Resources）。记忆存储只能在创建会话时挂载 —— sessions.resources.add() 不接受 memory_store。自托管（self-hosted） 环境上的会话以相同方式挂载（并且 memory_store 是这些环境接受的唯一资源类型）—— 见下文自托管说明。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",  # or "read_only"; default is "read_write"
            "instructions": "User preferences and project context. Check before starting any task.",
        }
    ],
)

Max 8 memory stores per session. Attach multiple when different slices of memory have different owners or lifecycles - e.g. one read-only shared-reference store plus one read-write per-user store, or one store per end-user/team/project sharing a single agent config.

每个会话最多 8 个记忆存储。 当不同的记忆切片拥有不同的所有者或生命周期时，可以挂载多个存储 —— 例如一个只读的共享参考资料存储加一个按用户划分的可读写存储；或在共享同一智能体配置时，按最终用户/团队/项目各挂载一个存储。

How the agent sees it (FUSE mount) / 智能体如何感知它（FUSE 挂载）

Each attached store is mounted in the session container at /mnt/memory/<store-name>/. The agent interacts with it using the standard file tools (bash, read, write, edit, glob, grep) - there are no dedicated memory tools. On cloud sandboxes access: "read_only" makes the mount read-only at the filesystem level (on self-hosted sandboxes it is enforced by the worker's write/edit tools and the upload path - see below); "read_write" allows the agent to create, edit, and delete files under it. A short description of each mount (name, path, instructions, access) is automatically injected into the system prompt so the agent knows the store exists without you having to mention it.

每个挂载的存储会以 /mnt/memory/<store-name>/ 路径挂载到会话容器中。智能体使用标准文件工具（bash、read、write、edit、glob、grep）与之交互 —— 没有专用的记忆工具。在云端沙箱上，access: "read_only" 会在文件系统层面把挂载点设为只读（在自托管沙箱上则由 worker 的 write/edit 工具及上传路径强制执行 —— 见下文）；"read_write" 允许智能体在其下创建、编辑和删除文件。每个挂载点的一段简短描述（名称、路径、instructions、访问权限）会自动注入系统提示词，因此无需你提及，智能体也知道该存储存在。

Writes the agent makes under the mount are persisted back to the store and produce memory versions just like host-side memories.update calls.

智能体在挂载点下所做的写入会持久化回存储，并像宿主侧的 memories.update 调用一样产生记忆版本。

Self-hosted sandboxes: a synced local copy, not a live mount. On a self_hosted environment the SDK worker (EnvironmentWorker - Python, TypeScript, Go; the ant CLI worker does not mount stores) downloads each attached store to the same /mnt/memory/<store-name>/ path and reconciles it with the store on an interval, so writes are visible to other sessions only after sync, conflicts resolve in favor of the store, and read_only is enforced by the worker's tools rather than the filesystem (bash can still alter the local copy). Everything else - sync interval, per-session secret, host prep, troubleshooting - lives in shared/managed-agents-self-hosted-sandboxes.md § Memory stores. Not available on self-hosted environments on Claude Platform on AWS.

自托管沙箱：是同步的本地副本，不是实时挂载。 在 self_hosted 环境上，SDK worker（EnvironmentWorker —— Python、TypeScript、Go；ant CLI worker 不挂载存储）会把每个挂载的存储下载到同样的 /mnt/memory/<store-name>/ 路径，并按固定间隔与存储进行协调同步，因此写入只有在同步之后才对其他会话可见，冲突以存储侧为准，而 read_only 由 worker 的工具而非文件系统强制执行（bash 仍可修改本地副本）。其余内容 —— 同步间隔、每会话 secret、宿主机准备、故障排查 —— 见 shared/managed-agents-self-hosted-sandboxes.md § Memory stores。Claude Platform on AWS 上的自托管环境不支持此功能。

【评论】自托管模式下只读约束依赖 worker 工具而非文件系统，bash 仍可绕过修改本地副本，这是文档明示的防护边界差异，而非隐藏限制。

Manage memories directly (host-side) / 直接管理记忆（宿主侧）

Use these for review workflows, correcting bad memories, or seeding stores out-of-band.

这些操作可用于审阅流程、纠正不良记忆，或在带外预填充存储。

List / 列出

Returns Memory | MemoryPrefix entries - a MemoryPrefix (type: "memory_prefix", just a path) is a directory-like node when listing hierarchically. Use path_prefix to scope (include a trailing slash: "/notes/" matches /notes/a.md but not /notes_backup/old.md) and depth to bound the tree walk. Pass view="full" to include content in each item; the default "basic" returns metadata only.

返回 Memory | MemoryPrefix 条目 —— MemoryPrefix（type: "memory_prefix"，仅含一个 path）在层级列举时表现为类似目录的节点。用 path_prefix 划定范围（要包含末尾斜杠："/notes/" 匹配 /notes/a.md 但不匹配 /notes_backup/old.md），用 depth 限制树遍历深度。传 view="full" 可让每个条目包含 content；默认的 "basic" 只返回元数据。

for m in client.beta.memory_stores.memories.list(store.id, path_prefix="/"):
    if m.type == "memory":
        print(f"{m.path}  ({m.content_size_bytes} bytes, sha={m.content_sha256[:8]})")
    else:  # "memory_prefix"
        print(f"{m.path}/")

Read / 读取

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

retrieve defaults to view="full" (content included); view matters mainly on list endpoints.

retrieve 默认为 view="full"（包含内容）；view 主要在列举（list）端点上才有意义。

Create vs. update / 创建与更新

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

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

Optimistic concurrency (precondition on update) / 乐观并发控制（update 的前置条件）

memories.update accepts a precondition so you can read -> modify -> write back without clobbering a concurrent writer. The only supported type is content_sha256. On mismatch the API returns 409 (memory_precondition_failed_error) - re-read and retry against fresh state.

memories.update 接受一个 precondition，让你可以读取 -> 修改 -> 写回而不覆盖并发写入者的更改。目前唯一支持的类型是 content_sha256。不匹配时 API 返回 409（memory_precondition_failed_error）—— 请重新读取并基于最新状态重试。

client.beta.memory_stores.memories.update(
    mem.id,
    memory_store_id=store.id,
    content="CORRECTED: Always use 2-space indentation.",
    precondition={"type": "content_sha256", "content_sha256": mem.content_sha256},
)

Delete / 删除

client.beta.memory_stores.memories.delete(mem.id, memory_store_id=store.id)

Pass expected_content_sha256 for a conditional delete.

传入 expected_content_sha256 可执行条件删除。

Audit and rollback - memory versions / 审计与回滚 - 记忆版本

Every mutation creates an immutable memver_... snapshot. Versions accumulate for the lifetime of the parent memory; memories.retrieve always returns the current head, the version endpoints give you history.

每次变更都会创建一个不可变的 memver_... 快照。版本在其父记忆的生命周期内持续累积；memories.retrieve 始终返回当前最新版本，而版本端点为你提供历史记录。

Each version also records created_by - an actor object with type in session_actor / api_actor / user_actor - and, after redaction, redacted_at + redacted_by.

每个版本还会记录 created_by —— 一个 type 取值为 session_actor / api_actor / user_actor 的操作者对象 —— 以及在抹除之后的 redacted_at + redacted_by。

List versions / 列出版本

Newest-first, paginated. Filter by memory_id, operation, session_id, api_key_id, or created_at_gte / created_at_lte. Pass view="full" to include content; default is metadata-only.

按最新在前排列，分页返回。可按 memory_id、operation、session_id、api_key_id 或 created_at_gte / created_at_lte 过滤。传 view="full" 可包含 content；默认仅返回元数据。

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

Retrieve a version / 获取单个版本

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

Redact a version / 抹除某个版本

Scrubs content from a historical version while preserving the audit trail (actor + timestamps). Clears content, content_sha256, content_size_bytes, and path; everything else stays. Use for leaked secrets, PII, or user-deletion requests.

从历史版本中清除内容，同时保留审计轨迹（操作者 + 时间戳）。会清空 content、content_sha256、content_size_bytes 和 path；其余字段保持不变。适用于泄漏的机密、PII（个人身份信息）或用户删除请求。

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

Endpoint reference / 端点参考

See shared/managed-agents-api-reference.md -> Memory Stores / Memories / Memory Versions for the full HTTP method/path tables. Raw HTTP base path:

完整的 HTTP 方法/路径表见 shared/managed-agents-api-reference.md -> Memory Stores / Memories / Memory Versions。原始 HTTP 基础路径：

POST   /v1/memory_stores
POST   /v1/memory_stores/{memory_store_id}/archive
GET    /v1/memory_stores/{memory_store_id}/memories
PATCH  /v1/memory_stores/{memory_store_id}/memories/{memory_id}
GET    /v1/memory_stores/{memory_store_id}/memory_versions
POST   /v1/memory_stores/{memory_store_id}/memory_versions/{version_id}/redact

For cURL examples and the CLI (ant beta:memory-stores ...), WebFetch the Memory URL in shared/live-sources.md -> Managed Agents.

如需 cURL 示例和 CLI（ant beta:memory-stores ...），请通过 WebFetch 访问 shared/live-sources.md -> Managed Agents 中的 Memory URL。