记忆检索与调试

记忆检索与调试界面是 Snail AI 记忆系统的核心运维工具，帮助管理员搜索、预览、调试记忆的检索效果，并对记忆条目进行手动管理操作。

进入检索与调试

在「记忆系统」管理页面中，点击任意记忆库卡片，即可进入该记忆库的检索与调试界面。界面以全屏抽屉形式打开，分为左右两个区域：

区域	位置	功能
参数与配置面板	左侧（宽 360px）	设置检索参数和调整检索配置
搜索与结果区域	右侧	输入查询、执行搜索、查看检索结果

记忆搜索

搜索参数

在左侧的参数面板中，需要设置以下检索参数：

参数	必填	说明
当前记忆库	自动	显示当前选中的记忆库名称和 ID
Agent ID	是	目标智能体的 ID，用于限定搜索范围
User ID	是	目标用户的 ID，用于限定搜索范围
Conversation ID	否	可选的对话 ID，进一步缩小搜索范围到特定对话

执行搜索

在左侧面板中填写 Agent ID 和 User ID。
在右侧的搜索框中输入查询文本（例如"用户的数据库选择"）。
点击「搜索」按钮或按 Enter 键执行搜索。
系统将调用记忆调试接口（/memory/config/{id}/debug），使用当前记忆库的配置参数进行向量检索。

搜索结果

搜索结果以卡片列表形式展示，每条结果包含：

排名序号：结果在返回列表中的位置。
相似度评分：语义相似度分数（百分比形式，如 85.3%）。
记忆类型：FACT/DECISION/PREFERENCE/TASK_PROGRESS/REFERENCE。
记忆标题：记忆条目的标题。
记忆内容：记忆条目的完整内容。

调试建议

尝试不同的查询措辞，观察检索结果的变化，评估记忆的语义覆盖度。
如果关键记忆未被召回，考虑调整相似度阈值或切换融合策略。
检查返回结果的相似度分数分布，帮助确定合理的阈值设置。

检索配置实时调整

在左侧面板的下方，可以实时调整检索配置参数。这些参数会自动同步保存到后端（防抖 450ms），调整后立即对下一次搜索生效。

可调参数

参数	说明	范围
最大召回数	每次检索最多返回的记忆条数	1-100
查询改写	是否对查询语句进行改写优化后再检索	开/关
融合策略	混合检索的融合方法	RRF / 加权求和
RRF K 值	RRF 融合的 K 参数（仅 RRF 策略时显示）	1-200
稠密向量权重	向量检索的权重（仅加权求和策略时显示）	0-1
启用阈值过滤	是否启用相似度阈值过滤	开/关
相似度阈值	低于此值的记忆将被过滤（仅启用阈值时显示）	0-1
启用重排序	是否使用 Rerank 模型重排序	开/关
重排序模型	选择 RERANKER 类型的模型（仅启用重排序时显示）	下拉选择
进入重排序数量	送入 Rerank 模型的候选数量（仅启用重排序时显示）	1-500

自动保存

检索配置的修改会自动同步保存到服务端。面板右上角会显示"同步中..."状态提示。这意味着你在此处的调整不仅影响当前调试，也会影响智能体在实际对话中的记忆检索行为。

上下文预览

上下文预览功能展示智能体在实际对话中收到的完整上下文信息，帮助你理解记忆是如何被注入到对话中的。

通过 API 接口 GET /memory/agent/{agentId}/conversations/{conversationId}/context-preview 可以获取上下文预览数据。

预览内容

上下文预览返回以下信息：

字段	说明
`messages`	滑动窗口中的对话消息列表，每条包含角色（user/assistant）和内容
`memories`	通过向量检索召回的记忆列表
`estimatedTokens`	完整上下文的预估 Token 数
`compressionApplied`	是否应用了上下文压缩

上下文预览有助于：

确认记忆是否按预期被注入到上下文中。
评估 Token 消耗，判断是否需要调整滑动窗口大小或最大召回数。
验证上下文压缩策略是否正确工作。

手动记忆管理

除了自动提取，管理员还可以对记忆进行手动管理操作。

按对话查看记忆

通过 API 接口 GET /memory/conversation/{conversationId} 可以查看特定对话产生的所有记忆，支持 limit 参数控制返回数量。

按类型查看记忆

通过 API 接口 GET /memory/agent/{agentId} 可以查看智能体的所有记忆，支持按类型过滤：

类型	说明
`FACT`	事实类记忆
`DECISION`	决策类记忆
`PREFERENCE`	偏好类记忆
`TASK_PROGRESS`	任务进度类记忆
`REFERENCE`	参考资料类记忆

查看最近记忆

通过 API 接口 GET /memory/agent/{agentId}/recent 可以查看最近一段时间内创建的记忆，支持 days 和 limit 参数。

关键词搜索

通过 API 接口 POST /memory/search 可以使用关键词搜索记忆：

json

{
  "query": "数据库选型",
  "agentId": 1,
  "types": ["FACT", "DECISION"],
  "limit": 10,
  "days": 30
}

状态管理操作

对单条记忆可以执行以下状态变更操作：

操作	API 接口	说明
归档	`POST /memory/{id}/archive`	将活跃记忆归档，不再参与自动检索
压制	`POST /memory/{id}/suppress`	压制/屏蔽记忆，完全不参与检索
激活	`POST /memory/{id}/activate`	重新激活已归档或已压制的记忆
更新	`PUT /memory/{id}`	修改记忆的标题、内容、类型、标签等属性
删除	`DELETE /memory/{id}`	永久删除记忆

典型使用场景

归档：对话中产生的临时性信息（如短期任务进度），任务完成后归档。
压制：提取出的记忆信息有误或不再准确时，进行压制。
激活：之前归档的记忆重新变得相关时，重新激活。

手动提取记忆

通过 API 接口 POST /memory/agent/{agentId}/conversations/{conversationId}/extract 可以对特定对话手动触发记忆提取，无需等待自动提取间隔。

返回结果包含：

字段	说明
`extractedCount`	本次提取的记忆条数
`memories`	提取出的记忆条目列表

记忆统计

通过 API 接口 GET /memory/agent/{agentId}/stats 可以查看智能体的记忆统计信息：

字段	说明
`totalMemories`	记忆总数
`byType`	按类型分布统计
`mostUsed`	被访问次数最多的记忆 ID 列表
`retrievalEffectiveness`	检索有效性评分
`dateRange`	统计的时间范围

调试最佳实践

从典型查询开始：使用用户最常问的问题作为检索查询，验证记忆是否能有效覆盖。
对比不同配置：通过实时调整检索参数，对比不同配置下的召回效果。
关注长尾场景：除了常见查询，也要测试边缘场景的检索质量。
监控 Token 消耗：通过上下文预览评估 Token 使用情况，避免过多记忆注入导致上下文溢出。
定期清理：对已过时或不准确的记忆进行归档或压制，保持记忆库的质量。

记忆检索与调试 ​

进入检索与调试 ​

记忆搜索 ​

搜索参数 ​

执行搜索 ​

搜索结果 ​

检索配置实时调整 ​

可调参数 ​

上下文预览 ​

预览内容 ​

手动记忆管理 ​

按对话查看记忆 ​

按类型查看记忆 ​

查看最近记忆 ​

关键词搜索 ​

状态管理操作 ​

手动提取记忆 ​

记忆统计 ​

调试最佳实践 ​