最佳实践

更新时间：2026-05-27

以一个完整的端到端场景为例，说明如何从零开始使用 Agent 记忆服务，并总结各操作阶段的实践要点和常见反模式。

以下示例中使用的环境变量 $MEMORY_API_BASE_URL 和 $MEMORY_API_KEY：

MEMORY_API_BASE_URL：https://cloud.memory.bj.baidubce.com/api
MEMORY_API_KEY：
- 在控制台"API Key"页签中创建，具体见API Key 管理
- 通过 export MEMORY_API_KEY=<your-api-key> 设置

完整使用示例：工程助手 Agent

以下展示一个工程助手 Agent 从创建记忆库到日常使用的完整流程。假设开发者 Alice 使用该 Agent 管理前端项目的知识。

第一天：创建记忆库并写入初始知识

1. 创建记忆库

在控制台创建一个记忆库，ID 为 project-frontend。

2. 配置记忆库

设置提示词，引导系统在正确的方向上提取和推理：

配置项	设置
存储提示词	提取技术决策、架构选型、依赖约束、代码规范和阻碍问题。忽略闲聊和日程安排。
观察提示词	识别技术偏好、架构模式、反复出现的阻碍和团队共识。关注稳定模式，忽略一次性事件。
反思提示词	你是一名资深前端工程助手。回答时优先参考历史技术决策和项目规范，风格简洁直接。
怀疑度	3
字面度	4
共情度	2

3. 写入项目文档

将项目的技术方案文档存入记忆库：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/memories/retain" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "items": [{
      "content": "前端项目技术方案：框架使用 React 18 + TypeScript，样式使用 Tailwind CSS，状态管理使用 Zustand（从 Redux 迁移），构建工具使用 Vite，组件文档使用 Storybook，部署平台为 Vercel。代码规范：函数式组件 + Hooks，禁止 class 组件，ESLint + Prettier 强制执行。",
      "context": "architecture document",
      "document_id": "tech-spec-v1",
      "tags": ["project:frontend", "team:engineering"]
    }]
  }'
            

4. 写入第一次对话记录

Alice 与 Agent 的对话结束后，将对话存入记忆库：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/memories/retain" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "items": [{
      "content": "Alice (2026-05-25T10:00:00+08:00): 帮我写一个登录页面\nAgent (2026-05-25T10:00:05+08:00): 好的，我会使用 React + TypeScript + Tailwind 来实现。需要表单验证吗？\nAlice (2026-05-25T10:00:30+08:00): 用 zod 做表单验证，登录接口用 /api/auth/login\nAgent (2026-05-25T10:02:00+08:00): 已完成登录页面，使用 zod 验证，调用了 /api/auth/login 接口",
      "context": "coding session",
      "document_id": "session-20260525",
      "timestamp": "2026-05-25T10:00:00+08:00",
      "tags": ["user:alice", "project:frontend"]
    }]
  }'
            

注意：使用稳定的 document_id（如 session-日期），后续同一会话有新对话时用 update_mode: "append" 追加，而不是创建新文档。

第二天：Agent 自动参考历史记忆

Alice 发起新对话时，Agent 先检索相关记忆：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/recall" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "query": "这个用户常用的前端技术栈和代码规范是什么？",
    "budget": "mid",
    "tags": ["user:alice", "project:frontend"],
    "tags_match": "all_strict"
  }'
            

检索返回 Alice 的技术偏好和项目规范，Agent 据此直接推荐符合习惯的方案，无需重复询问。

对话结束后，Agent 主动存储新信息：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/memories/retain" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "items": [{
      "content": "Alice 要求新增权限管理模块，使用 RBAC 模型，角色定义在后端 /api/roles 接口返回。",
      "context": "coding session",
      "document_id": "session-20260526",
      "tags": ["user:alice", "project:frontend"]
    }]
  }'
            

第三天：团队协作和知识共享

团队新成员 Bob 也使用同一个记忆库。由于所有记忆都带有 project:frontend 标签，Bob 检索时能获取项目的完整技术背景：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/recall" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "query": "项目的前端技术方案和代码规范",
    "budget": "mid",
    "tags": ["project:frontend"],
    "tags_match": "any_strict"
  }'
            

Alice 需要一份综合的项目状态总结时，使用反思而非检索：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/reflect" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "query": "请总结这个前端项目的当前技术架构、已完成的功能模块和待开发的模块。",
    "budget": "high",
    "tags": ["project:frontend"],
    "tags_match": "any_strict",
    "include_facts": true
  }'
            

存储 Retain 最佳实践

内容格式

做法	说明
保留原始内容	传入完整的对话、文档或笔记，不要预总结——系统会自动提取事实和关系
使用自然语言	写完整句子，包含"谁、做了什么、何时、为什么"
避免预总结	"用户使用 React"比"用户偏好：React"更有上下文价值

正确做法	错误做法
传入完整对话文本	只传摘要"用户偏好 React + TS"
保留时间线信息	删掉时间标记，只保留结论
标明内容来源和角色	混在一起无法区分谁说了什么

context 字段

始终设置 context，说明数据的来源和性质。它直接影响事实提取的质量。

正确做法	错误做法
`context: "project onboarding"`	`context: "data"`
`context: "code review session"`	不设置 context
`context: "weekly standup notes"`	`context: "conversation"`

document_id

使用稳定的标识符，实现"同 ID = 更新"而非"每次新建"。

场景	推荐 document_id
一次对话	`session-20260525`
一份技术文档	`tech-spec-v1`
一个工单	`ticket-12345`
一个周期性同步	`daily-sync-20260525`

错误做法：每次存储都生成随机 ID，导致同一内容的记忆重复累积。

tags 命名规范

采用统一的 维度:值 格式，确保存储和检索时使用一致的标签体系：

格式	示例	用途
`user:<id>`	`user:alice`	按用户隔离
`project:<name>`	`project:frontend`	按项目隔离
`team:<name>`	`team:engineering`	按团队隔离
`topic:<name>`	`topic:auth`	按主题分类

多租户最低要求：每个存储请求至少包含 user:<id> 标签。省略标签的记忆对所有用户可见。

timestamp

始终设置 timestamp，启用时间维度的检索策略。对于对话，使用对话开始的时间。

检索 Recall 最佳实践

budget 选择

budget	延迟	使用场景
low	50-100ms	简单事实查询、高频 Agent 循环
mid	100-300ms	日常使用（默认推荐）
high	300-500ms	深度探索、复杂跨主题问题

多租户标签匹配

场景	推荐	说明
个人使用	`any`	包含用户的记忆和公共知识
多用户共享库	`any_strict`	只返回当前用户的记忆，排除无标签的公共知识
需要同时限定用户和项目	`all_strict`	只返回同时匹配两个标签的记忆

何时用检索、何时用反思

用检索	用反思
Agent 自己推理，只需要原始事实	需要系统综合分析后直接给答案
需要精确引用或逐条审计	需要总结、画像、趋势判断
延迟敏感（50-500ms）	回答质量优先（1-10s）
查找具体某条记忆	需要多步推理的综合结论

反思 Reflect 最佳实践

提示词编写

提示词决定了反思的角色定位和回答方向。写得越具体，输出越稳定。

质量	示例
好	你是一名资深前端工程助手。回答时优先参考历史技术决策和项目规范，风格简洁直接。
好	你是一名客服助手，拥有该客户的完整历史。引用过往工单和解决方案。回答简洁，聚焦解决方案。
差	提取所有信息——过于笼统，会产生噪声
差	要有帮助——不是具体的推理引导

性格设置推荐

Agent 类型	怀疑度	字面度	共情度
代码审查	4	5	1
客服助手	2	3	4
个人助理	2	2	4
医疗助手	5	4	3
研究助手	4	4	2

结构化输出

当需要程序化处理反思结果时，使用 response_schema：

                Bash
                
            

                curl "$MEMORY_API_BASE_URL/reflect" \
  -H "Authorization: Bearer $MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "project-frontend",
    "query": "这个用户最适合什么前端框架？",
    "budget": "low",
    "response_schema": {
      "type": "object",
      "properties": {
        "recommendation": {"type": "string"},
        "confidence": {"type": "string", "enum": ["low", "medium", "high"]},
        "reasons": {"type": "array", "items": {"type": "string"}}
      },
      "required": ["recommendation", "confidence", "reasons"]
    }
  }'
            

返回的 structured_output 字段包含按 Schema 解析的结构化结果，便于下游业务逻辑直接消费。

心智模型最佳实践

何时创建

高频查询，且每次都希望得到稳定的结构化回答
内容需要跨多条事实和观察的综合，而非单条事实
主题边界清楚，可以用一句查询描述
原始事实很多，直接推理成本高或输出不稳定

按知识维度拆小

一个名为"用户的所有信息"的心智模型价值很低。应按维度拆分：

场景	推荐	不推荐
个人助手	用户技术画像、沟通偏好、当前项目	用户的一切信息
客服系统	客户画像、常见工单处理、升级路径	全部客服知识
工程助手	代码规范、部署流程、当前架构	整个工程知识库
销售助手	客户画像、采购偏好、风险点	客户全部信息

查询语句编写

查询要具体，包含主题边界和输出重点：

好	差
总结 Alice 稳定的技术背景、常用语言和框架、当前项目	总结 Alice
这个前端项目的代码规范和部署流程	项目信息
这个客户过去三个月的沟通偏好和投诉趋势	客户情况

常见反模式

反模式	问题	修正方式
存储前先总结	丢失实体关系、时间标记和结构上下文	传入原始内容，系统自动提取事实
每次存储使用随机 document_id	同一内容产生重复记忆	使用稳定的会话/文档/工单 ID
不设置 context 字段	事实提取质量显著下降	始终说明数据来源和性质
用 metadata 做过滤	metadata 不可过滤	用 tags 做范围过滤
提示词模糊笼统	提取结果噪声多、价值低	明确说明领域、数据类型和要忽略的内容
多租户库使用 tags_match="any"	记忆跨用户泄露	使用 any_strict 或 all_strict
存储后立即检索同一内容	存储是写操作，提取尚未完成	存储在对话结束后，检索在下一次对话开始时
一个心智模型覆盖所有内容	准确率低、刷新慢、难以限定范围	每个知识维度一个心智模型
所有检索都用 high budget	成本高、延迟大，通常没必要	简单查找用 low，日常用 mid，深度探索用 high
存储时不设 timestamp	时间维度的检索策略失效	始终设置事件实际发生的时间

评价此篇文章

有帮助没帮助

迁移指南

接入方式

百度智能云

向量数据库 VectorDB