记忆存储 Retain 是将重要信息写入 Agent 记忆服务的过程，帮助 AI 把有价值的信息“记下来”，让这些信息在后续对话、任务和团队协作中持续发挥作用。

通过把对话内容、项目文档、邮件、会议纪要、工单记录或业务事件保存到记忆库中，系统会自动从中提取关键信息，例如事实、实体、关系和时间线索，并建立索引，方便后续检索和推理使用。

什么时候需要存储记忆

在以下场景中，建议使用 Retain 写入长期记忆：

• 对话轮次结束后：对话内容，包括用户偏好、问题背景、关键结论或后续待办事项等。
• Agent 完成任务后：任务结果、重要决策、失败原因或下一步计划。
• 收到重要外部资料时：文档、邮件、会议纪要、项目说明或业务记录等内容。

例如，对话中说明了常用技术栈、项目目标或写作风格，这些信息都可以写入记忆，供 AI 后续自动参考。

需要提供哪些信息

使用文档ID管理内容

多次写入同一份文档或同一段会话内容时，建议使用稳定的文档ID。

文档ID可以理解为一份内容的唯一标识。使用相同的文档ID写入新内容时，系统会更新原有内容，而不是重复创建多份相似记忆。

例如，同一个项目说明文档后续发生了修改，只需要继续使用同一个文档ID写入新版本，系统就可以存储原有关系并更新内容。推荐每个会话、文档、工单或项目资料使用一个固定的文档ID，后续更新时继续沿用。

使用标签管理范围

标签用于区分不同用户、项目、团队或业务场景下的记忆范围。在检索和推理时，系统可以根据标签筛选相关记忆，避免不同用户或项目的数据混用。

建议按照维度设计标签，例如：user:alice, project:atlas, team:backend对于个人使用场景，可以使用用户标签；对于项目协作场景，可以使用项目或团队标签。如果多个 Agent 共享同一个记忆库，建议通过标签明确区分不同用户、项目和权限范围。

使用建议

• 在关键节点写入记忆：建议在任务完成、对话阶段结束、收到重要文档或外部信息后写入记忆，帮助 AI 保留有价值的上下文。
• 保留完整背景信息：写入内容时，尽量包含“谁、做了什么、何时发生、为什么重要”等信息，避免只写零散关键词。
• 使用自然语言描述内容：推荐直接写入完整句子或段落，让系统更容易理解上下文、提取事实和建立关联。
• 为同一份内容设置稳定的文档ID：对于同一段对话、同一个工单或同一份文档，建议使用固定的文档ID，便于后续更新和管理。
• 标明内容来源：可以通过内容说明记忆来自哪里，例如客服对话、代码评审、会议纪要或项目文档，方便后续理解记忆背景。
• 使用标签区分范围：在多用户、多项目或多团队场景中，建议使用标签标记用户、项目或团队范围，避免不同数据混用。
• 避免写入敏感信息：不要将 API Key、密码、访问令牌、个人敏感信息或未脱敏数据写入记忆。

请求示例

写入一条对话记忆

1curl "$MEMORY_API_BASE_URL/memories/retain" \
2  -H "Authorization: Bearer $MEMORY_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "bank_id": "'"$MEMORY_BANK_ID"'",
6    "items": [{
7      "content": "用户表示前端技术栈使用 TypeScript + React + Tailwind，状态管理从 Redux 迁移到了 Zustand。",
8      "context": "project onboarding",
9      "document_id": "session-20260525",
10      "timestamp": "2026-05-25T10:00:00+08:00",
11      "tags": ["user:alice", "project:frontend"]
12    }]
13  }'

返回示例

1{
2  "success": true,
3  "bank_id": "my-bank",
4  "items_count": 1,
5  "async": false,
6  "usage": {
7    "input_tokens": 156,
8    "output_tokens": 89,
9    "total_tokens": 245
10  }
11}

追加内容到已有会话

当对话继续时，使用相同的 document_id 和 update_mode: "append" 追加新内容，而非重新发送全部历史：

1curl "$MEMORY_API_BASE_URL/memories/retain" \
2  -H "Authorization: Bearer $MEMORY_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "bank_id": "'"$MEMORY_BANK_ID"'",
6    "items": [{
7      "content": "团队决定引入 Storybook 做组件文档，部署在 Vercel 上。",
8      "document_id": "session-20260525",
9      "update_mode": "append",
10      "tags": ["user:alice", "project:frontend"]
11    }]
12  }'