添加并验证记忆库

在智能体开发服务平台（AgentWorks）中，记忆库用于保存可在后续交互中检索的事实、偏好和上下文。本页使用一个专用测试记忆库，从 TOOL 开始完成验证。交互模式决定记忆如何写入和取回；TOOL 表示智能体通过记忆工具完成这两项操作，便于在 Trace 中核对。

判断是否需要记忆库

根据需要保留的信息选择合适的能力：

• 只需理解当前对话中已经说过的内容：使用会话上下文。
• 需要检索产品手册、制度或其他已入库资料：使用知识库。
• 需要在后续会话中继续检索事实或偏好：使用记忆库。

新会话会使用新的对话上下文，但不会创建、清空或隔离记忆库。需要了解 API 和渠道会话的区别时，参见管理 API 会话、调用任务和中断和管理渠道会话。

理解 AgentWorks 如何使用记忆

会话上下文让智能体继续理解这一段对话，记忆库则保存以后还要使用的内容。以下流程以智能体实例 A 为例，展示智能体实例 A 如何在第一段会话中保存“项目代号是 ALPHA-101”，再在后续新会话中取回这条记忆。

图表预览

注意

取回记忆的智能体实例可以不同

流程中由智能体实例 A 保存和取回记忆。智能体实例 B 如果也连接同一个记忆库，同样可以取回其中的记忆。两个实例是否共享记忆，取决于它们是否连接同一个记忆库；只要仍连接同一个记忆库，创建新实例或使用新的 session_id 都不会自动分出一份独立记忆。

使用记忆库时，请注意以下三点：

• 开始新会话或清空渠道会话不会删除记忆库中的条目，只会让后续消息不再沿用原来的对话上下文。
• 多个智能体实例只要连接同一个记忆库，就会使用同一份记忆；不同的 session_id 不会自动把记忆分开。
• 记忆内容有误或不再需要时，应编辑或删除对应的记忆条目。清空会话不能代替这项操作。

准备并连接记忆库

第一次验证时，使用一个专用测试记忆库、一个测试智能体模板、一个测试智能体实例和一个测试调用方。不要把测试记忆库连接到供其他用户创建实例的智能体模板。

理解两种连接方式

记忆库可以直接新建，不需要先创建记忆模板。

记忆库管理 中列出的每个记忆库，都是一个已经创建、可以保存记忆条目的具体资源。在智能体模板的 插件配置 中添加记忆时，可以看到两种连接方式：

• 记忆 - 实例：连接一个已经存在的记忆库。多个智能体实例选择同一个记忆库时，会使用同一份记忆内容。
• 记忆 - 模板：选择环境中已经提供的记忆模板。创建智能体实例时，平台根据该模板为这个实例准备记忆库。没有可选模板时，不能使用这种方式。

第一次验证使用 记忆 - 实例，连接自己新建的专用测试记忆库。需要为多个智能体实例规划共享或独立资源时，再参见选择记忆库的使用范围。

准备专用测试记忆库

以下入口仅在租户已启用记忆能力时可用。按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。

1. 打开 记忆库管理。

   打开记忆库

2. 单击 记忆库 下拉框旁的 管理记忆库。

3. 单击 新建记忆库，填写 名称 *和可选的 描述，然后单击 创建。

4. 从页面的 记忆库 下拉框中选择新建的测试记忆库。

下拉框中的每一项显示一个记忆库的名称和 mem-* 资源 ID。切换选择后，页面上的记忆操作会作用于所选记忆库。

将测试记忆库连接到智能体

1. 创建或编辑仅用于验证的智能体模板，打开 插件配置。
2. 单击 添加插件，在 类型 中选择 记忆 - 实例。
3. 在 选择实例 中选择测试记忆库。
4. 在 交互模式 中选择 TOOL，并在系统提示词中说明哪些信息可以保存，以及何时使用记忆工具。
5. 保存智能体模板，创建新的测试智能体实例，或更新已有测试实例的配置。

选择记忆库的使用范围

记忆库由谁共同使用，与记忆如何写入和检索是两件事。共享范围由智能体模板连接的是现有记忆库还是可用的记忆模板决定。

多个智能体实例有意共享记忆

选择 记忆 - 实例 时，从该智能体模板创建的所有智能体实例都会连接所选的现有记忆库。只有这些实例确实应访问同一组记忆时，才使用这种方式。

警告

现有记忆库是共享数据范围

同一个现有记忆库不会根据渠道用户、API 调用方或 session_id 自动拆分其中的记忆。不要把个人或私有记忆库连接到供其他用户创建实例的智能体模板。

需要保存个人信息时，请为每个隔离范围准备单独的智能体模板和记忆库，或由业务系统管理按用户区分的长期记忆。专属智能体实例本身不改变已经共享的记忆库引用。

每个智能体实例分别使用记忆库

环境中已有可选的 记忆 - 模板 时，可以在智能体模板的 插件配置 中选择它。平台会在创建智能体实例时，根据所选模板为该实例准备记忆库资源；同一个智能体实例会在后续会话中继续使用该资源。

记忆库管理 页面只管理已经创建的记忆库，不提供记忆模板创建入口。如果 记忆 - 模板 没有可选项，请联系平台管理员确认当前环境是否提供记忆模板。不要用一个包含私有数据的共享记忆库代替独立资源。

有关智能体模板、智能体实例和能力资源之间的关系，参见为多个智能体实例规划记忆库。

验证多个调用方的记忆范围

业务要求不同用户不能互相读取记忆时，为两个测试用户准备不同的记忆库，再完成以下验证：

1. 用户 A 保存“我的测试颜色是红色”。
2. 用户 B 保存“我的测试颜色是蓝色”。
3. 两位用户分别开始新会话并询问自己的测试颜色。
4. 确认用户 A 只得到红色，用户 B 只得到蓝色，且双方都无法检索另一方的测试事实。
5. 分别删除两条测试记忆并再次确认。

任何一位用户能够检索到另一位用户的测试事实时，应停止保存个人信息，并检查两个智能体实例是否连接了同一个记忆库。无法为不同用户准备独立记忆库时，请由业务系统管理按用户区分的长期记忆。

选择写入和检索方式

交互模式 是记忆插件中的配置项。选择模式时，需要分别判断信息如何写入记忆库，以及以后需要这段记忆时，检索结果如何提供给模型。交互模式不会改变智能体连接的是哪个记忆库，也不会改变该记忆库的共享范围。

理解自动处理和工具调用的区别

在 TOOL 模式中，智能体的模型根据用户输入、系统提示词和记忆工具说明，决定是否调用工具保存或检索记忆。

两种名称以 AUTO_EXTRACT 开头的模式不依赖模型调用工具完成写入。智能体回复后，AgentWorks 自动从本次用户输入和回复中提取适合保留的内容，并写入记忆库。该处理可能在回复完成后继续，因此看到智能体回复不表示记忆已经写入。

AUTO_EXTRACT_AND_INSERT 还会在模型处理当前输入前，根据最新用户输入自动检索相关记忆。以下流程显示匹配的记忆如何参与本次模型处理，以及后续输入为什么会重新触发检索：

图表预览

会话上下文保留实际发生的对话，记忆库继续保存原始条目。每次检索到的匹配内容只参与当次模型处理，不会作为一轮对话加入会话上下文。

自动提供的记忆会直接影响回答并占用模型上下文。如果同一事实同时存在旧值和新值，或者存在错误、重复或不完整的条目，智能体可能使用过期信息或给出不一致的回答。发现问题时，在 记忆库管理 中选择对应记忆库，搜索相关对象、编号和旧值：内容仍需保留但存在错误时进行编辑；内容已经失效、重复或不应继续使用时将其删除。完成处理后，开始新会话并使用固定问题重新验证回答。具体步骤参见搜索、纠正和删除记忆。

使用 TOOL 获得可检查的记忆流程

建议从 TOOL 开始。该模式不会自动从交互中提取并写入记忆，也不会在后续运行开始前自动提供相关记忆。智能体在需要时调用记忆工具保存、检索、修改或删除内容，相关调用会出现在 Trace 中。这种方式适合需要确认每一步是否实际发生的场景，也是第一次验收记忆能力时的推荐选择。

例如，可以在系统提示词中加入以下要求：

当用户明确要求记住一项稳定事实时，调用 add_memory。保存的内容应包含完整的对象、属性和值。只有工具返回成功后，才能告诉用户已经保存。需要回忆以前保存的事实时，调用 search_memory。

然后发送“请记住：项目 ALPHA-101 的验收颜色是青色”。在 Trace 中确认智能体调用了 add_memory，并且 content 是完整事实。开始新会话后询问“项目 ALPHA-101 的验收颜色是什么？”，再确认智能体调用了 search_memory 并返回正确答案。

使用 AUTO_EXTRACT_AND_INSERT 自动提供相关记忆

AUTO_EXTRACT_AND_INSERT 会从交互中自动提取适合保存的内容并写入记忆库；在后续交互中，AgentWorks 自动检索相关记忆，并把结果加入模型本次运行的上下文。名称中的 INSERT 表示把检索结果加入模型上下文，不表示向记忆库新增记录。完成 TOOL 基线验证后，可以用一条独立、完整的事实测试这种方式，例如“项目 ALPHA-101 的验收颜色是青色”。

自动提取可能把一段输入拆成多条记忆。一次输入包含多个对象、编号或属性时，拆分后的条目可能缺少原有关系。用于业务数据前，请在相同调用方的新会话中确认回答仍能准确还原事实。管理页面能够找到对应条目时，再核对提取结果；无法查看条目而业务又要求逐条审阅、纠正或删除时，请改用 TOOL。

验证 AUTO_EXTRACT_AND_TOOL 后再使用

AUTO_EXTRACT_AND_TOOL 会从交互中自动提取适合保存的内容并写入记忆库；在后续交互中，智能体需要调用记忆工具才能检索相关记忆。在目标环境完成“自动写入 → 相同调用方开始新会话 → 实际调用记忆工具 → 返回正确事实”的完整验收前，不要把该模式作为生产默认选择。

如果自动保存后，记忆工具在新会话中无法检索到该事实，请改用已经通过验证的 TOOL。记录智能体实例、记忆库、交互模式、调用方式和测试输入，交给平台管理员排查。

测试自动模式时，等待当前交互完成，再刷新记忆内容并进行新会话验证。

完成第一次安全验证

使用不含敏感信息的一条明确事实完成写入、检索、纠正和删除闭环：

1. 让智能体保存测试事实，并在 Trace 中确认实际调用了 add_memory。
2. 在 记忆库管理 中选择测试记忆库，确认出现内容正确的条目。
3. 使用相同调用方开始新会话，再询问该事实，并在 Trace 中确认实际调用了 search_memory。通过 API 调用时不发送原来的 session_id；通过支持会话指令的渠道使用时，发送 /session new。
4. 让智能体通过 update_memory 把测试事实改为新值，再次开始新会话，确认回答使用新值且不再使用旧值。
5. 让智能体通过 delete_memory 删除测试记忆，再次开始新会话，确认智能体不再返回该事实。

智能体回复“已记录”或工具显示“已完成”，都不能单独证明记忆已经写入。至少同时检查记忆条目和新会话中的实际检索结果。需要手动新增、搜索、纠正或删除条目时，参见搜索、纠正和删除记忆。

控制质量、性能和数据风险

• 只保存后续交互确实需要的稳定事实和偏好；不要把完整对话、临时工具输出或可以从知识库检索的资料重复保存为记忆。
• 定期搜索并处理重复、过期和冲突条目。更多相似条目不等于更可靠，反而可能造成回答冲突。
• 使用固定问题比较启用和停用记忆时的正确性与延迟。检索到的记忆也会占用模型上下文。
• 使用 TOOL 时，在系统提示词中明确什么时候保存、检索、修改和删除记忆，并通过 Trace 检查实际调用。
• 使用自动方式时，不要把回复完成当作写入证明；等待自动处理完成，并检查条目和新会话结果。
• 上线前明确允许保存的信息、隔离范围、保留期限、纠错和删除责任。处理个人信息或业务敏感数据时，先完成多调用方隔离验证。

控制台提供记忆条目的新增、检索、查看、编辑和删除。保留期限、自动去重、召回阈值和最终用户自助删除需要通过组织的数据流程或外部系统管理。

评估自动检索对缓存、延迟和成本的影响

第一次验证记忆功能时不必评估提示词缓存。业务对大量调用的延迟和成本有明确目标时，再完成本节测试。

AUTO_EXTRACT_AND_INSERT 会根据每次输入提供可能不同的记忆，因此模型收到的动态内容也可能变化。提示词缓存通常只能复用相同内容或相同前缀；匹配记忆发生变化时，变化后的部分需要重新处理。这影响的是缓存能够复用多少，不表示会话或记忆数据发生不一致。具体的命中规则、复用范围和指标以所使用的模型服务为准。

TOOL 提供更明确、可检查的检索过程，但不保证延迟更低或成本更少。智能体调用记忆工具后，工具结果会参与后续模型处理；智能体取得工具结果后，还需要继续处理才能生成最终回答。因此，评估总成本时需要同时考虑模型调用、记忆检索、输入长度和提示词缓存，不能只比较自动方式和工具方式的第一次模型请求。

使用固定测试集完成对比：

1. 准备两个测试智能体模板，使用相同的模型、系统提示词和等价的测试记忆内容，只让交互模式不同。
2. 为两种模式发送相同的问题，分别记录首次测试和使用同一组问题重复测试的结果。比较时保持会话状态和记忆内容一致。
3. 检查回答是否正确、稳定，并记录端到端响应时间以及 Trace 中的模型调用和记忆工具调用。
4. 模型服务提供输入 Token、缓存 Token 或费用明细时，一并记录这些指标。
5. 使用实际业务流量的典型问题重复测试，再决定生产环境使用哪种模式。

需要自动提供相关记忆时，选择 AUTO_EXTRACT_AND_INSERT；需要明确控制检索时机并在 Trace 中核对调用时，选择 TOOL。不要仅根据预期的缓存命中率选择模式，应同时比较回答质量、延迟和总成本。