本文介绍如何在方舟 Managed Agents 中使用记忆存储（Memory Store），为 Agent 提供可跨 Session 保留的长期记忆。默认情况下，每个 Session 都从新的上下文开始。Session 结束后，Agent 在本次运行中积累的偏好、约定、排障经验或业务背景不会自动带到下一次任务中。Memory Store 用于保存这些可复用信息，并在后续 Session 中重新挂载给 Agent 使用。 ## 基本概念将 Memory Store 挂载到 Session 后，它会以目录形式出现在沙箱内，Agent 可以访问记忆内容。 > Agent 仅可读取记忆内容，不具备对记忆的写权限。每条 Memory 都有独立路径，您可以通过 API 或控制台直接读取、创建、更新和删除。使用 Memory Store 时，需要在创建 Agent 时启用 Agent Toolset。Agent 通过标准文件工具读取挂载目录，系统会自动为 Agent 提供说明，告知该记忆目录的位置和用途。 ## 创建 Memory Store 创建 Memory Store 时需要提供 `name` 和 `description`。其中 `description` 会展示给 Agent，用于说明这个 Store 中保存的内容和使用场景。 ```bash store=$( curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "", "description": "" }' ) STORE_ID=$(jq -er '.id' <<<"$store") echo "Memory Store ID: $STORE_ID" ``` 返回的 Memory Store ID 通常形如 `memstore_...`。创建 Session 并挂载记忆时，需要传入该 ID。 ## 预置 Memory 内容在 Agent 开始运行前，可以先向 Store 中写入参考资料，例如项目规范、用户偏好、输出格式、术语表等。 ```bash curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID/memories" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/.md", "content": "" }' ``` 单条 Memory 的内容上限为 100 KB，约 25k tokens。单个 Store 最多保存 2,000 条 Memory。建议将记忆拆成多个小而聚焦的文件，避免使用长文档。 ## 挂载 Memory Store 到 Session Memory Store 需要在创建 Session 时通过 `resources` 数组挂载。与文件和代码仓库资源不同，Memory Store 只能在 Session 创建时挂载，不支持在运行中的 Session 中追加或移除。可以通过 `instructions` 为本次 Session 提供额外使用说明，例如要求 Agent 在开始任务前先读取偏好文件。`instructions` 会连同 Store 的名称和描述一起展示给 Agent，长度上限为 4,096 字符。 ```bash session=$( curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d @- <" } ] } EOF ) printf '%s\n' "$session" SESSION_ID=$(jq -er '.id' <<<"$session") ``` 单个 Session 最多挂载 10 个 Memory Store。可以按不同使用场景拆分 Store，例如用户偏好、项目上下文、团队共享规范分别管理，并为每个 Store 设置独立访问权限和生命周期。 ## Agent 如何访问 Memory * 挂载后的 Memory Store 会出现在沙箱的 `/mnt/memory/` 目录下。Agent 使用标准文件工具读取和写入其中的文件。 * Agent 对 Memory 有只读权限，即可以读取 Memory，但不能写入或修改。 * Agent 对 Memory 的读写会作为普通工具调用出现在 Session 事件流中，例如 `agent.tool_use` 和 `agent.tool_result`。 ## 查看和编辑 Memory 您可以通过 API 管理 Memory，用于人工审核、纠正错误记忆、导入初始化资料或导出内容。 ### 查询 Memory 列表可通过 `path_prefix` 按路径前缀浏览 Memory，类似查看目录。 ```bash curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID/memories?path_prefix=/&order_by=path&depth=2" \ -H "Authorization: Bearer $ARK_API_KEY" \ | jq -r '.data[] | "\(.type) \(.path)"' ``` ### 读取 Memory 读取单条 Memory 会返回完整内容。 ```bash curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID/memories/$MEMORY_ID" \ -H "Authorization: Bearer $ARK_API_KEY" \ | jq -r '.content' ``` ### 创建 Memory `create` 会在指定 `path` 下新建 Memory；如果路径已存在，不会覆盖原内容。修改已有 Memory 请使用更新接口。 ```bash memory=$( curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID/memories" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/path/of/the/memory", "content": "" }' ) MEMORY_ID=$(jq -r '.id' <<<"$memory") MEMORY_SHA=$(jq -r '.content_sha256' <<<"$memory") ``` ### 更新 Memory 更新接口可修改内容、路径，或同时修改二者。修改路径可用于重命名或归档。 ```bash curl -sS --fail-with-body -X POST "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID/memories/$MEMORY_ID" \ -H "Authorization: Bearer $ARK_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "/new/path" }' ``` ### 删除 Memory ```bash curl -sS --fail-with-body -X DELETE "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID/memories/$MEMORY_ID" \ -H "Authorization: Bearer $ARK_API_KEY" ``` ## 管理 Memory Store 除创建外，Memory Store 还支持查询、删除等操作。 ### 查询 Store 列表 ```bash curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores" \ -H "Authorization: Bearer $ARK_API_KEY" ``` ### 删除 Store ```bash curl -sS --fail-with-body -X DELETE "https://ark.cn-beijing.volces.com/api/v3/memory_stores/$STORE_ID" \ -H "Authorization: Bearer $ARK_API_KEY" ``` ## 最佳实践当 Store 达到 2,000 条 Memory 上限后，新 Memory 写入会失败，包括直接调用创建接口，以及 Agent 写入尚不存在的新路径。已有 Memory 仍可读取和更新。建议按以下方式管理长期记忆： * **按用途拆分 Store** ：不要把所有内容放进一个通用 Store。可以按用户、团队共享知识、项目上下文分别建 Store。 * **在接近上限前整理内容** ：定期删除过期或重复 Memory，或将碎片化内容整理成更稳定的摘要 Store。

火山方舟