火山方舟
火山方舟
文档指南
请输入
- 文档首页
火山方舟Managed Agents管理 Agent 上下文持久化记忆
复制全文
下载 pdf持久化记忆
文档反馈
问问助手本文介绍如何在方舟 Managed Agents 中使用记忆存储（Memory Store），为 Agent 提供可跨 Session 保留的长期记忆。
默认情况下，每个 Session 都从新的上下文开始。Session 结束后，Agent 在本次运行中积累的偏好、约定、排障经验或业务背景不会自动带到下一次任务中。Memory Store 用于保存这些可复用信息，并在后续 Session 中重新挂载给 Agent 使用。
基本概念
将 Memory Store 挂载到 Session 后，Agent 可以根据挂载时配置的访问权限读取或修改记忆内容。
每条 Memory 都有独立路径，您可以通过 API 或控制台直接读取、创建、更新和删除。
使用 Memory Store 时，需要在创建 Agent 时启用 Agent Toolset。可执行的操作由挂载时的 access 决定。
创建 Memory Store
创建 Memory Store 时必须提供 name；description 可选。提供 description 时，该字段会展示给 Agent，用于说明这个 Store 中保存的内容和使用场景。
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": "<MEMORY_STORE_NAME>",
"description": "<MEMORY_STORE_DESCRIPTION>"
}'
)
STORE_ID=$(jq -er '.id' <<<"$store")
echo "Memory Store ID: $STORE_ID"
返回的 Memory Store ID 通常形如 memstore-...。创建 Session 并挂载记忆时，需要传入该 ID。
预置 Memory 内容
在 Agent 开始运行前，可以先向 Store 中写入参考资料，例如项目规范、用户偏好、输出格式、术语表等。
根据写入数量选择接口：
- 调用 创建记忆 写入单条 Memory，适合补充零散内容。
- 调用 批量创建记忆 批量写入多条 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": "/<MEMORY_1>.md",
"content": "<CONTENT_OF_THE_MEMORY>"
}'
单条 Memory 的内容上限为 100 KiB（102400 字节），约 25k tokens。单个 Store 最多保存 2,000 条 Memory。建议将记忆拆成多个小而聚焦的文件，避免使用长文档。
挂载 Memory Store 到 Session
Memory Store 需要在创建 Session 时通过 resources 数组挂载。与文件和代码仓库资源不同，Memory Store 只能在 Session 创建时挂载，不支持在运行中的 Session 中追加或移除。
以下示例将访问权限显式设置为 read_only，使 Agent 可以读取 Memory Store，但不能修改其中的内容。
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
{
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"resources": [
{
"type": "memory_store",
"memory_store_id": "$STORE_ID",
"access": "read_only"
}
]
}
EOF
)
printf '%s\n' "$session"
SESSION_ID=$(jq -er '.id' <<<"$session")
单个 Session 最多挂载 10 个 Memory Store。可以按不同使用场景拆分 Store，例如用户偏好、项目上下文、团队共享规范分别管理，并为每个 Store 设置独立访问权限和生命周期。
Agent 如何访问 Memory
- read_only：Agent 可以浏览、读取和搜索 Memory，但不能修改内容。
- read_write：Agent 除了读取 Memory，还可以创建、更新、删除或移动内容。修改会保存在挂载的 Memory Store 中，供后续 Session 继续使用。
- Agent 对 Memory 的读取会作为普通工具调用出现在 Session 事件流中，例如 agent.tool_use 和 agent.tool_result。
查看和编辑 Memory
查询 Memory 列表
可通过 path_prefix 按路径前缀浏览 Memory，类似查看目录。
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 会返回完整内容。
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 请使用更新接口。
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": "<CONTENT_OF_THE_MEMORY>"
}'
)
MEMORY_ID=$(jq -r '.id' <<<"$memory")
MEMORY_SHA=$(jq -r '.content_sha256' <<<"$memory")
更新 Memory
更新接口可修改内容、路径，或同时修改二者。修改路径可用于重命名或归档。
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
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 列表
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/memory_stores" \
-H "Authorization: Bearer $ARK_API_KEY"
删除 Store
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 写入会失败。已有 Memory 仍可读取和更新。建议按以下方式管理长期记忆：
- 按用途拆分 Store：不要把所有内容放进一个通用 Store。可以按用户、团队共享知识、项目上下文分别建 Store。
- 在接近上限前整理内容：定期删除过期或重复 Memory，或将碎片化内容整理成更稳定的摘要 Store。
最近更新时间：2026.09.30 19:29:04
这个页面对您有帮助吗？
有用
有用
无用
无用