记忆库使用指南 - Agent 观测与优化 AgentLoop

AgentLoop 记忆库能够从应用对话中提取长期记忆，供应用后续交互时检索和使用。本文介绍如何创建记忆库、配置应用接入、写入对话并检索长期记忆，最后通过一个烹饪助手示例演示完整流程。首次使用建议依次完成三个检查：对话写入请求成功、能够检索到相关长期记忆、应用将检索结果加入 Agent 请求。基础概念请参见记忆库产品介绍。

前提条件

已创建智能体空间，并能够进入该空间的 AgentLoop 控制台。
已确定要接入的应用和一组用于验证的示例对话。
准备通过接口写入时，本地或应用运行环境能够访问控制台提供的 Endpoint。本文的 HTTP 示例使用 curl。

步骤一：创建记忆库

重要

新建的记忆库需要资源准备，准备完成前无法写入对话。首次写入前，请按集成方式页签的提示预留准备时间，并确认资源已就绪。

登录 AgentLoop 控制台，选择目标地域和智能体空间。
从左侧导航栏选择上下文工程，切换到记忆库页签。
单击创建记忆库，填写以下信息。
参数
是否必填
说明
记忆库名称
是
输入便于识别的名称，例如 cooking_memory
记忆库描述信息
否
说明用途和适用应用，例如“保存烹饪助手用户的饮食偏好”
单击确认。
创建后，在记忆库的概览页签检查名称和描述，确认后续操作的是目标记忆库。页面还会展示创建时间、更新时间等信息。

步骤二：创建 API Key

进入记忆库详情页，切换到 API Key 页签。
尚未创建 API Key 时，单击立即创建，按页面提示完成创建。
复制 API Key，供应用接入时使用。
API Key 为访问对应记忆库的请求提供鉴权，与记忆库和智能体空间绑定。使用当前页面提供的记忆接口时，无需另外传入记忆库名称和空间名称。建议通过服务端环境变量或应用的密钥管理方式保存 API Key，避免写入代码仓库或暴露在浏览器前端。

步骤三：接入应用并写入对话

选择接入方式

进入集成方式页签，可以选择以下方式：

方式	适用情况	操作入口
HTTP API	希望先用命令行验证，或从其他语言发起 HTTP 请求	选择 HTTP API，复制访问配置和请求示例
Python SDK	希望在 Python 应用内使用 mem0 兼容接口；不等于任意 SDK 版本和所有扩展方法都已经完成适配	选择 Python SDK，按页面提供的安装和调用示例接入

本文后续以 HTTP API 为例演示。建议使用页面中的复制按钮获取目标记忆库的配置：Endpoint 应与所选地域对应，API Key 应来自当前记忆库。

配置访问参数

将以下占位内容替换为控制台中的实际值：

export AGENTLOOP_ENDPOINT="<从集成方式页签复制的 Endpoint>"
export AGENTLOOP_API_KEY="<该记忆库的 API Key>"

写入一段对话

下面的请求与控制台 HTTP 示例使用相同的接口和参数结构，将一段对话关联到业务用户 user-001。

curl -X POST "$AGENTLOOP_ENDPOINT/v1/memories" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "我住在杭州，喜欢喝无糖美式咖啡"},
      {"role": "assistant", "content": "好的，已记住你住在杭州、喜欢无糖美式。"}
    ],
    "user_id": "user-001",
    "infer": true
  }'

参数	说明
`messages`	本次写入的对话消息列表。每条消息使用 `role` 表示角色，`content` 表示文本内容
`user_id`	对话关联的业务用户标识。后续检索该用户的记忆时使用同一标识
`infer`	示例设为 `true`，请求从对话中提取记忆

检查 HTTP 响应，确认请求成功；如果请求失败，先根据响应检查 Endpoint、API Key 和请求内容。记忆提取需要处理时间，写入成功后继续执行下一步检索，确认相关长期记忆已经可用；不要仅凭对话中的“已记住”或写入请求返回成功判断提取结果。

选择用户标识与筛选条件

写入请求中的 user_id 对应控制台长期记忆检索页面的用户 ID 字段，正文统称用户标识。用户标识将记忆关联到业务用户并限定检索对象，由应用根据已登录用户确定，写入和检索保持一致。user_id 是业务数据标识，应用仍需根据自身的用户身份和权限确定可查询的范围。接入应用时建议使用稳定的业务用户标识：同一用户跨会话复用相同的 user_id，不同用户使用各自的标识。验证上文示例时，查询用户为 user-001。

查询语句用于表达当前需要了解的信息，例如“用户的饮食偏好”或“用户喜欢喝什么咖啡”；ID 筛选项用于限定查询对象，两者应配合使用。控制台还提供 App ID、Agent ID 和 Run ID 筛选项，使用时应与实际写入数据关联的标识对应。跨会话查询用户偏好时，按用户范围检索；只有需要查询某次运行相关记忆时，再增加 Run ID 条件，避免把其他会话中的相关记忆排除在外。

步骤四：检索长期记忆

控制台长期记忆检索页签用于人工验证检索效果；应用通过代码检索记忆时，按集成方式页签提供的接口示例调用。

进入记忆库的长期记忆检索页签。
输入查询语句，例如“这个用户喜欢喝什么咖啡？”。

按需填写以下参数。

参数	说明
topK	指定期望返回的记忆数量上限，例如 `5`；实际返回数量以结果为准
用户 ID	按记忆关联的业务用户标识筛选，本示例填写 `user-001`
App ID	按记忆关联的 App 标识筛选
Agent ID	按记忆关联的 Agent 标识筛选
Run ID	按记忆关联的运行标识筛选

单击开始检索，在检索结果区域查看记忆内容。
检索上述示例时，可重点检查是否返回与“无糖美式咖啡”有关的信息。实际提取文字、语言和条目数可能不同，请判断含义是否与输入一致。页面中的分数表示检索匹配置信度，可以帮助判断结果与当前问题的匹配程度；分数不代表记忆内容已经经过事实核实，也不代表应用必须将所有返回结果都交给 Agent。

步骤五：让 Agent 使用记忆

应用接入记忆后，可以采用以下流程：

收到新问题：从应用的登录态或业务上下文确定用户标识。
检索记忆：按当前问题和该用户标识查询相关记忆。具体接口调用使用集成方式页签中的示例。
组织模型输入：将相关记忆作为背景资料，与当前问题、必要的近期对话一起加入请求。
生成回答：由 Agent 结合当前要求和历史背景回答问题。
写入本轮对话：将本轮实际发生的交互写入记忆库，供后续提取和检索。
应用应保留当前问题中的明确要求。例如，历史记忆为“喜欢咖啡”，但用户本次要求“推荐不含咖啡的饮品”时，应将本次要求一并提供给 Agent。检索结果为空时，也可以由应用使用当前问题和已有会话上下文继续处理。

完整示例：为烹饪助手补充用户偏好

本示例复用步骤三的写入请求结构、步骤四的检索操作和步骤五的输入组织方式，说明应用后续交互时如何使用记忆，不依赖特定 Agent 框架。

阶段	操作	检查重点
写入偏好	使用步骤三的 HTTP 请求结构，将消息内容替换为“我喜欢清淡、少辣的家常菜”，仍关联 `user-001`	请求成功，用户标识正确
验证提取	在控制台查询“用户的饮食偏好”，用户 ID 填写 `user-001`	检索结果含有与清淡、少辣有关的信息
新会话提问	同一用户开启新会话询问“今晚吃什么？”	应用继续使用相同用户标识检索相关记忆
组织回答	将相关偏好与新问题一起提供给 Agent	应用确实将检索结果加入请求，回答参考了相关偏好

可按以下结构组织输入，其中的记忆内容应来自实际检索结果：

当前问题：
今晚吃什么？
相关用户记忆（背景资料）：
用户偏好清淡、少辣的家常菜。
回答要求：
结合当前问题和相关偏好给出建议；用户本次提出的明确要求优先。

这是上下文组织示例，具体回答取决于当前问题、检索结果和模型。验证时先确认记忆被检索到，再确认应用确实使用了这些记忆，不要仅凭一次回答推断整个接入流程已经正确。

常见问题

刚创建记忆库，为什么还不能立即写入？

新建资源需要准备时间。请按集成方式页签的提示预留准备时间并确认就绪，参见步骤一开头的提示；资源准备完成后，仍需检查写入请求的响应并验证长期记忆检索。

写入成功，但没有检索结果，应该检查什么？

按以下顺序检查：

当前控制台中的记忆库是否与写入请求使用的 API Key 对应。
写入时的 user_id 是否与检索时的用户 ID 一致。
App ID、Agent ID、Run ID 等附加条件是否排除了目标数据。
查询语句是否与输入内容相关，可以先使用“用户的咖啡偏好”等明确的问题验证。
对话是否仍在处理，可以稍后重试检索。
暂时没有结果不能单独说明数据已经丢失。排查时请结合写入响应、查询条件和后续检索结果判断，用户标识与筛选条件的取值原则参见上文“选择用户标识与筛选条件”。

创建记忆库后，Agent 会自动记住用户吗？

应用需要接入对话写入和记忆检索，并将相关结果加入模型请求。控制台创建记忆库和 API Key 只是接入准备。

是否需要把全部历史对话都放入每次模型请求？

应用可以根据当前任务，将相关长期记忆与必要的近期对话组合使用。长期记忆用于补充可复用的背景；本次问题中的具体指代、临时要求等仍需要当前会话上下文。

可以直接使用其他记忆 SDK 的所有方法吗？

接入时请以当前记忆库的集成方式页签为准，使用其中提供的方法、参数和 Endpoint，并逐项验证应用所需的操作。mem0 兼容接口不等于任意 SDK 版本和所有扩展方法都已经完成适配。

参数	是否必填	说明
记忆库名称	是	输入便于识别的名称，例如 `cooking_memory`
记忆库描述信息	否	说明用途和适用应用，例如“保存烹饪助手用户的饮食偏好”