记忆库使用指南-Agent 观测与优化 AgentLoop(AgentLoop)-阿里云帮助中心

本文介绍如何选择记忆来源、创建记忆库、接入应用、检索和维护长期记忆。首次体验可以选择手动写入，使用一段示例对话验证完整流程；已有 Agent 轨迹或业务数据集时，可以在创建向导中配置对应的数据源。基础概念请参见记忆库产品介绍。

前提条件

已创建智能体空间，并能进入该空间的 AgentLoop 控制台。
已确定需要保存的信息，以及用来关联记忆的业务用户、Agent 或应用标识。
使用 Agent 轨迹作为来源时，当前空间已有可用的 Agent 轨迹。
使用 Dataset 作为来源时，已准备同空间的数据集，并具有读取权限；字段要求见下文。
通过接口接入应用时，运行环境能够访问控制台提供的 Endpoint。

步骤一：创建记忆库

1. 选择数据源

填写记忆库名称和可选的描述，然后选择数据源类型。

类型	输入方式	示例
手动写入	应用通过接口提交对话	为 `cooking_memory` 写入用户的饮食偏好
Agent 轨迹	持续读取当前空间的 Agent 轨迹	从生活助手的运行轨迹中抽取用户背景
Dataset	读取同空间中符合要求的数据集	从整理过的客户对话数据集中抽取事实

单击下一步。数据源类型创建后不可修改；请先确定数据准备方式。

2. 配置过滤条件或 Schema

手动写入

无需配置来源过滤条件，直接进入下一步。建库后按“步骤二”接入应用并提交对话。

Agent 轨迹

参数	用途
服务名	选择或输入需要消费的服务名，支持如 `customer-*` 的尾缀通配；留空表示不按服务名限制
Agent 名称	选择或输入需要消费的 Agent，留空表示不按 Agent 名称限制
最小步数	跳过低于指定步数的轨迹，填写非负整数
起始时间	指定从什么时间开始消费；留空时从创建记忆库的时刻开始
排除降级轨迹	按需排除降级的轨迹
SLS 检索语句	为来源增加检索条件，与前面的过滤条件共同生效

同一名称列表中的多个取值表示任选其一；不同过滤项之间需要同时满足。来源是已组装的 Agent 轨迹，输入结果取决于当前空间实际采集的数据。选择较早的起始时间前，应确认相应历史数据仍可读取。

轨迹中的用户、Agent、应用标识应能对应到希望积累记忆的业务对象。检索时使用实际关联的标识，不要假定每条轨迹都包含业务用户 ID。

Dataset

选择同一智能体空间中的 Dataset 名称。Schema 契约为 MemorySourceV1。
选择版本策略：增量跟随持续读取新增序列的数据；固定版本全量读取指定版本的快照。固定版本需要填写实际版本名称，增量跟随可指定起始 seq。
按需填写过滤条件（where），筛选要处理的记录。
检查额外字段。需要供模型理解的字段选择抽取输入并填写含义说明；其他字段选择忽略。未声明的额外列不会自动成为抽取输入。

来源 Dataset 必须包含以下九个固定字段。

字段	类型	说明
`sourceId`	text	一条输入的来源标识，使用稳定、非空的值
`messages`	json	非空消息数组，每条消息包含 `role` 和 `content`；角色为 `user`、`assistant`、`system` 或 `tool`
`timestamp`	long	正整数 Unix 时间戳，单位为秒
`userId`	text	业务用户标识
`agentId`	text	Agent 标识
`appId`	text	应用标识
`runId`	text	运行标识
`metadata`	json	业务元数据对象，无额外信息时可使用 `{}`
`lineage`	json	来源说明对象，其中 `sourceKind` 为 `trajectory`、`dataset` 或 `api`

四个业务标识至少有一个非空。不要将 JSON 数组或对象重复编码成 JSON 字符串；毫秒时间戳需要先转换为秒。

下面是一条 Dataset 输入示例，仅用于说明字段结构。导入时将来源标识、时间戳、消息和业务标识替换为实际值。

{
  "sourceId": "conversation-001",
  "messages": [{"role": "user", "content": "我喜欢清淡、少辣的菜"}],
  "timestamp": 1788796800,
  "userId": "user-001",
  "agentId": "cooking-assistant",
  "appId": "cooking-app",
  "runId": "",
  "metadata": {},
  "lineage": {"sourceKind": "dataset"}
}

需要关联外部业务信息时，先在数据处理流程中完成关联和字段整理，再将结果写入来源 Dataset。来源 Dataset 与抽取后保存长期记忆的结果 Dataset 是不同的资源。

3. 配置策略

首次验证可以选择事实抽取与合并更新，保留默认参数。围绕用户习惯积累画像时，可选择C 端用户画像；需要企业业务背景时，可选择B 端数字孪生；需要限定具体抽取目标时，可选择自定义指令。

在范围与审计中，可以指定召回至少需要提供的一类业务标识，例如 userId。详细参数和两种存储模式的区别，参见配置记忆抽取与存储策略。

4. 预览并创建

检查预览确认中的数据源、过滤条件和策略摘要。可以粘贴代表性样本，单击运行预览，查看抽取事实、存储动作和跳过原因；轨迹或 Dataset 来源也可以不粘贴样本，从已配置来源抽样。

预览不会写入正式记忆。预览失败时，先修正配置或输入并重新预览；确认后单击创建记忆库。样本格式参见配置记忆抽取与存储策略。

创建成功后，进入概览检查当前记忆库和数据源状态。轨迹、Dataset 来源还可以查看消费进度、最近消费窗口和最近错误，并通过暂停消费、恢复消费控制后续读取。

步骤二：接入应用

使用手动写入时，通过本节提交对话。轨迹、Dataset 来源按已配置的数据源读取；应用需要检索记忆时，同样可以创建 API Key 并配置访问参数。

创建 API Key

进入记忆库的 API Key 页签，创建并复制 API Key。该凭证绑定对应的空间和记忆库。进入集成方式页签，复制目标地域的 Endpoint；使用这些记忆接口时，无需额外在请求中指定空间名和记忆库名。

通过服务端环境变量或密钥管理方式保存凭证。下面以 HTTP API 演示，先将占位值替换为当前页面提供的配置：

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

新建资源需要准备时间。首次调用前，按集成方式页签的提示确认资源可用。

写入对话

以下请求将对话关联到业务用户 user-001，并使用 infer: true 请求抽取长期记忆。

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
  }'

先检查响应是否成功。写入受理后，长期记忆仍需经过异步抽取和存储；助手在消息中说“记住了”，也不能代替服务端结果检查。

在应用中检索

curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories/search" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "这个用户的饮食偏好是什么？",
    "user_id": "user-001",
    "top_k": 5
  }'

user_id 必须与写入时一致，top_k 是返回数量上限。也可以使用下面的接口按业务用户列出记忆，帮助检查数据是否已经写入。

curl -X POST "$AGENTLOOP_ENDPOINT/v2/memories" \
  -H "Authorization: Token $AGENTLOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-001", "limit": 20}'

Python 应用可以切换到集成方式 > Python SDK，按页面示例安装和初始化 MemoryClient。接入时以页面给出的版本、方法和参数为准。

步骤三：在控制台检索与维护记忆

验证检索结果

进入长期记忆检索页签，输入“这个用户的饮食偏好是什么？”，将用户 ID设为 user-001，设置 topK 后单击开始检索。

可按需要增加 App ID、Agent ID、Run ID、kind 或 category 等筛选条件。多个业务 ID 按 AND 关系共同过滤；只查询某个用户跨会话的偏好时，避免附加与目标记忆无关的运行 ID。

结果卡片展示记忆内容及可用的排名、修订、来源、人工编辑和审核状态。重点检查含义是否与输入一致，不要求模型逐字复述消息或生成固定条数。分数用于判断检索匹配程度，不表示事实正确率。

编辑与删除

打开一条记忆的详情，单击修改，调整记忆内容后单击保存。保存成功后刷新结果，检查最新内容；如果提示修订冲突，重新打开详情读取最新版本，再决定如何修改。

可以使用记忆卡片的删除操作清理不再需要的内容，确认前核对目标记忆。不要将删除来源数据、删除一条长期记忆和删除整个记忆库混为同一操作。

开启人工编辑保护后，自动抽取对人工修订内容提出的新变更会进入待审核状态，原内容继续保留。可以结合来源与审计记录核对原因；策略说明见配置记忆抽取与存储策略。

查看来源与召回记录

当记忆记录提供来源信息且存在相应写入日志时，可以通过来源入口查看输入。页面返回召回事件 ID 时，可跳转审计明细检查本次查询；整体情况参见查看记忆审计与统计。

步骤四：让 Agent 使用记忆

应用收到新问题后，从自身登录态或业务上下文确定用户标识，检索相关记忆，再把有用的返回内容与当前问题和必要的近期对话一起交给 Agent。

例如，同一用户在新会话中询问“今晚吃什么？”，应用可以组织以下输入：

当前问题：今晚吃什么？
相关用户记忆：用户偏好清淡、少辣的家常菜。
回答要求：结合本次问题和相关偏好给出建议，保留用户当前明确提出的新要求。

其中的记忆应来自实际检索结果。完成回答后，再按业务需要写入本轮对话，或由已配置的数据源提供后续输入。

常见问题

写入成功后为什么还没有结果？

先确认 API Key 对应的记忆库和地域，再检查写入与检索的用户标识是否一致、附加筛选是否过多。手动写入可检查输入事件；轨迹和 Dataset 来源可检查消费状态、过滤条件、起始位置及最近错误。随后结合抽取、存储审计判断是否仍在处理、被策略排除或进入待审核。

预览有结果，为什么检索不到？

样本预览不会写入正式记忆。需要实际提交输入或让数据源消费对应记录，并确认存储完成后再检索。

更改策略会重新处理全部历史数据吗？

保存策略后可以在版本历史中查看新版本，历史记忆不会因为保存操作自动全部重建。需要检查新策略效果时，先运行样本预览，再观察后续实际输入。

源数据集字段调整后停止消费怎么办？

检查概览中的最近错误，确认固定字段的名称、类型及使用到的额外字段仍满足创建时的约定。不要仅通过反复恢复消费跳过 Schema 错误；先修正数据，再核对消费状态。