自托管沙箱中的记忆存储

自托管环境上的会话附加记忆存储的方式与云环境上的会话完全相同。在创建会话时将它们列在 resources 中，如将记忆存储附加到会话中所示。一个会话最多可接受 8 个记忆存储。

区别在于由谁来实体化存储。在自托管环境上，由您的 worker（而不是 Anthropic 的基础设施）将每个存储下载到沙箱中，并将智能体的更改同步回去。

要求

• 能够挂载记忆存储的 worker： 使用 ant CLI 1.33.0 或更高版本，或者 Python、TypeScript 或 Go SDK 中的 EnvironmentWorker。
• POSIX 文件系统： 不支持 Windows 主机，因为 worker 在打开记忆文件时需要 O_NOFOLLOW。建议使用区分大小写的文件系统，以免仅大小写不同的记忆路径发生冲突。
• 可写的 /mnt/memory 目录： 请参阅准备主机。
• 工作项的 secret： 如果由您自己的代码启动 worker，请转发工作项的 secret给它。

准备主机

在启动 worker 之前，请创建父目录，并使其对运行 worker 的用户可写：

sudo mkdir -p /mnt/memory && sudo chown "$USER" /mnt/memory

不要自行创建每个存储的目录。worker 会在会话开始时创建每个存储的 mount_path 目录（例如 /mnt/memory/user-preferences），并在会话结束时将其删除。如果该路径上已存在内容，worker 将拒绝启动该会话的工作。

在每个会话一个沙箱模式中，沙箱镜像需要一个可写的 /mnt/memory。您无需将记忆目录绑定挂载到主机，因为 worker 会在沙箱退出之前将其内容上传到存储。

隔离共享同一存储的会话

两个会话无法在同一主机上同时挂载同一个存储，因为两者都需要相同的路径。如果您的会话附加了同一个存储，请在每个文件系统上只运行一个会话。为每个会话提供其自己的沙箱即可满足此规则。

worker 如何处理记忆

当 worker 认领一个其会话附加了记忆存储的工作项时，它会：

1. 将每个存储下载到其 mount_path。 这与云会话使用的 /mnt/memory/ 下的目录相同，会话的系统提示会向智能体描述该目录。例如，名为"User Preferences"的存储会位于 /mnt/memory/user-preferences/。
2. 向文件工具开放这些目录。 智能体使用与在工作目录中相同的文件工具来处理记忆。
3. 在工具调用后协调更改， 每个同步间隔最多一次（默认为 15 秒）。存储中发生更改的记忆会写入磁盘，智能体更改的文件会上传到存储。
4. 在会话结束时执行最终同步。 它会在最多 30 秒内刷新所有仍待处理的上传，然后删除它创建的目录。

Anthropic 一侧的记忆存储仍然是唯一可信来源。记忆版本、脱敏，以及在 Console 中查看或编辑记忆，其工作方式与云会话相同。智能体对记忆的读取和写入会作为普通工具事件出现在事件流中。

由于每个 worker 按间隔进行同步，在一个会话中写入的更改只有在两个会话都完成同步后，才会对另一个正在运行的会话可见。在默认间隔下，这通常远少于一分钟。云沙箱上的会话几乎可以立即看到彼此的更改。

每个存储目录都包含一个名为 .anthropic-memory-store 的标记文件，用于将该目录与其存储关联起来。请保留该文件：worker 不会同步标记文件缺失或被修改的目录。

配置同步

有两个 EnvironmentWorker 选项控制记忆行为。在构造 worker 的任何位置设置它们，包括在 webhook 处理程序中。ant CLI worker 始终使用默认值。

同步间隔

memory_sync_interval 设置会话运行期间已附加的存储与服务器协调的频率。

较短的间隔可以缩小另一个会话看到过时记忆的时间窗口，但代价是更多的记忆存储请求。

仅在其会话不附加任何记忆存储的 worker 上禁用记忆支持。已禁用的 worker 既不下载也不同步存储，因此附加了存储的会话将在没有这些存储的情况下运行，即使其系统提示仍然描述了它们。

启用记忆支持时，如果某个附加了存储的会话的工作项到达时没有 secret，该工作项将失败，而不是在没有记忆的情况下运行。请参阅记忆存储挂载失败。

删除

memory_sync_deletions 设置智能体在本地删除的文件是否也从存储中删除。上传和下载不受影响。

例如，要每 10 秒同步一次，并且仅记录 worker 本应执行的删除操作：

worker = EnvironmentWorker(
    client,
    environment_id=environment_id,
    environment_key=environment_key,
    workdir="/workspace",
    memory_sync_interval=10,  # seconds
    memory_sync_deletions="log_only",
)

只读存储和冲突

对于以 access: "read_only" 附加的存储，write 和 edit 工具会拒绝更改其目录中的文件。worker 从不从中上传任何内容。

通过 bash，或通过您从沙箱提供的自定义工具或 MCP 服务器所做的更改，不会在本地被阻止。这些更改永远不会同步到存储，并且该记忆的下一次远程更改会覆盖它们。如果本地副本本身在会话期间必须保持不变：

• 为该智能体禁用 bash 工具，并且不要为其提供任何会写入沙箱文件系统的自定义工具。
• 不要以只读方式挂载存储路径。worker 本身必须创建该目录并将下载的记忆写入其中。

冲突以存储为准进行解决。假设智能体更改了一个记忆文件，而该文件自会话上次同步以来在存储中也发生了更改。在下一次同步时，worker 会保留存储的版本，用它覆盖本地文件，并记录一条警告。write 和 edit 工具本身会成功执行，不会有错误传递给智能体。如果智能体的更改仍然适用，它可以在同步后重新读取该文件并再次进行更改。

故障排除

有关 worker 的日志消息及其修复方法，请参阅记忆存储挂载失败。