mem0 插件 Memory Reviewer：对 AI Agent 记忆库做质量审计的完整方法论

在 Mem0 插件（面向 Claude Code、Cursor、Codex 等编码助手的记忆层插件）中，/mem0:memory-reviewer 是一个只读的记忆质量审计技能：它拉取当前项目的全部记忆，按 metadata.type 分组扫描近似重复、相互矛盾、低置信度、未打标签和过期失效五类问题，并以紧凑的报告形式输出，最后建议由 /mem0:dream 执行实际的合并与清理。读完后你将掌握：如何编写一个"只报告、不修改"的记忆审计流程，五类记忆缺陷各自的检测标准（名词重叠率、置信度阈值、180 天过期线），以及如何把它与深度健康检查、记忆固化（consolidation）技能串成一条完整的记忆治理链路。

一、Memory Reviewer 定位：记忆库的"体检报告"

Mem0 插件为编码类 Agent 提供跨会话的持久记忆。插件的 17 个 /mem0: 技能覆盖了记忆的写入（remember）、浏览（tour、peek）、删除（forget）与诊断（health）等场景，其中记忆质量的维护由两个技能分工承担：

• memory-reviewer：审计（audit）——找出重复、矛盾、低置信度记忆，只读报告，绝不修改或删除任何记忆；
• dream：固化（consolidation）——合并重复、解决矛盾、按保留策略剪枝过期条目，所有变更以 diff 形式展示并经用户确认。

这种"诊断与手术分离"的设计在 memory-reviewer 技能定义 的 Constraints 一节中有明确约束：

• Read-only——永不修改或删除记忆（那是 /mem0:dream 的职责）；
• 单次扫描最多处理 200 条记忆；
• 只报告发现，把行动决定权交给用户。

技能元数据中的 description 也说明了它的触发时机：当检索结果看起来相互冲突、运行 dream 固化之前，或做周期性记忆卫生审计时使用。

二、何时运行 Memory Reviewer

按技能文档的 When to use 一节，四种场景应触发审计：

1. 用户主动询问"check my memories"、"memory quality"、"any duplicates?"之类的问题；
2. 用户直接运行 /mem0:memory-reviewer；
3. 一次会话中发生了 5 次以上记忆写入之后（Agent 应主动建议）；
4. /mem0:health --deep 的深度质量扫描发现问题之后。

其中第 4 点把 reviewer 与 health 技能 衔接起来：health --deep 在标准 5 项连通性检查之外，会额外做重复、过期、低置信度、矛盾、孤儿（orphan）五类质量扫描，发现非零计数时统一提示 Run /mem0:dream to fix。而 reviewer 提供了更聚焦的五维报告格式，二者互补。

三、审计流程逐步解析

3.1 拉取全部记忆：get_memories 与分页上限

第一步是通过 MCP 工具 get_memories 拉取活跃项目的全部记忆，过滤条件同时约束用户与项目两个维度：

get_memories(
    filters={"AND": [
        {"user_id": "<active_user_id>"},
        {"app_id": "<active_project_id>"},
    ]},
    page_size=200,
)

若响应提示还有后续页则继续翻页，但总量上限为 200 条。这一"双键过滤"模式与插件内部的检索辅助函数完全一致：scripts/_search.py 中所有非全局搜索请求都构造 {"AND": [{"user_id": user_id}, {"app_id": project_id}, ...]} 这样的基础过滤子句，必要时再追加 {"metadata": {"type": ...}} 一类元数据条件。也就是说，reviewer 的取数口径就是插件 hooks 与 MCP 工具统一使用的标准作用域（user_id × app_id），审计对象与日常读写记忆的对象严格对齐。

MCP 侧由远程服务器 mcp.mem0.ai 提供 get_memories、search_memories 等工具，插件的 mcp_config.json 声明了服务地址与 Token ${MEM0_API_KEY} 认证头；get_memories 支持 filters 与分页，属于 README 中列出的 9 个 MCP 工具之一。

3.2 按 metadata.type 分组

第二步是按 metadata.type 分组。技能文档列出的常见类型有：

类型	语义（结合插件的编码分类法）
decision	架构/技术选型决策
convention	编码约定
anti_pattern	踩坑记录、应避免的反模式
task_learning	任务经验学习
project_profile	项目画像
user_preference	用户偏好
session_state	会话状态（时效性强）

分组是后续所有检测的前提：近似重复与矛盾都只在同一 type 组内比较。这背后的工程考量是——跨类型比较（比如一条"反模式"和一条"约定"）出现"表述相反"是正常且有用的，只有同类型内的对立面才构成真正的数据质量问题。插件会在会话启动时自动把项目的记忆分类法替换为面向编码的 17 类体系（architecture_decisions、anti_patterns、bug_fixes 等），对应实现见 setup_coding_categories.py；health --deep 的质量检查 4 正是用"是否存在已知的 17 个编码分类"来判定孤儿记忆。

3.3 五类问题的检测标准

第三步是对每个分组逐项扫描，技能文档给出的检测矩阵是这篇方法论的核心：

问题	检测方法
近似重复（Near-duplicates）	同一 type 内，去除停用词后文本的名词重叠率 > 60%
矛盾（Contradictions）	同一主题上的对立事实，例如同一组件上"用 PostgreSQL" vs "用 MySQL"
低置信度（Low-confidence）	metadata.confidence < 0.3
缺失类型（Missing type）	未设置 metadata.type
过期（Stale）	created_at 超过 180 天且无更新

几个值得展开的细节：

近似重复的"60% 名词重叠"是余弦相似度的廉价代理。 dream 技能 的 3a 节给出了同源定义：两条记忆若"重要名词重叠超过 60%，即视为余弦相似度 > 0.9"，且必须同时满足同 metadata.type、双方均未被 pin（metadata.pinned != true）才判定为可合并的重复对。reviewer 继承同一阈值体系，保证"审计结论"与"固化动作"对重复的判定完全一致，不会出现 reviewer 说该合并、dream 却不同意的口径漂移。

置信度阈值 0.3 是插件的统一低置信线。 dream 的剪枝候选规则 2 也是"confidence < 0.3 且不包含项目独有信息（文件路径、标识符、领域名词）"。health --deep 则把 0.5 作为单独的"低置信度"报告线（与过期分开统计），可见 0.3 是"动作线"，0.5 是"预警线"，reviewer 采用的正是动作线——它报告的都是值得交给 dream 处理的问题。

180 天过期线与类型保留策略的关系。 dream 的默认保留策略是 session_state、compact_summary 90 天过期、其余类型不剪枝；reviewer 的 180 天阈值则是更宽泛的"陈旧信号"——超过半年没有更新的记忆无论什么类型都值得被审视一次，但由用户决定是否处理。

3.4 输出：紧凑摘要 + 带 ID 的问题清单

第四步输出固定格式的紧凑摘要：

memory-reviewer: project=<id> total=<N>
  duplicates:      <N> found
  contradictions:  <N> found
  low_confidence:  <N> found
  untagged:        <N> found
  stale:           <N> found

第五步，若发现问题，则逐条列出并附带记忆 ID，便于后续精确操作：

Issues:
  [duplicate] "<memory_a>" ≈ "<memory_b>" [mem0:<id_a>, mem0:<id_b>]
  [contradiction] "<memory_x>" vs "<memory_y>" [mem0:<id_x>, mem0:<id_y>]
  [low_conf] "<memory_z>" (confidence: 0.1) [mem0:<id_z>]

这种 [mem0:<id>] 的引用格式并非随手约定，而是插件生态的统一惯例：scripts/_search.py 的 format_results_for_context 在把检索结果注入 Agent 上下文时，同样以 - [{cat}] {text} [mem0:{mid}] 的格式渲染（ID 取前 8 位）。因此 reviewer 报告中的 ID 可以直接用于 MCP 的 get_memory、update_memory、delete_memory 调用，报告即工单。

3.5 收尾建议：把处置权交给 dream

第六步，若发现问题则建议："Run /mem0:dream to consolidate duplicates and resolve contradictions."

这与 dream 技能 的流程正好无缝对接：dream 同样先拉取全部记忆（page_size=200、同样的 AND 过滤），做近重复/矛盾/剪枝三类分析，打印结构化 diff 报告，等待用户对每条矛盾选择 A/B/skip，最终确认后才依次执行 delete_memory + add_memory（合并时取两者中较高的 confidence，并打上 source: "mem0-dream" 标记）。reviewer 因此扮演"术前检查单"，dream 扮演"手术台"，中间由用户确认。

四、Memory Reviewer 在记忆治理链路中的位置

把仓库中的相关技能串起来，Mem0 插件的记忆治理是一条三层链路：

1. 连通性层——/mem0:health：五项检查（API Key、身份解析、MCP 连通、读写探针、会话统计文件），确保"记忆系统本身是好的"，见 health 技能；
2. 质量层——/mem0:memory-reviewer（本文主题）与 health --deep：在"系统健康"的前提下回答"记忆数据干不干净"，五维计数报告；
3. 固化层——/mem0:dream：在用户授权下实际执行合并、剪枝与冲突消解，支持 --auto 非交互模式（自动应用合并与剪枝、跳过需人工判断的矛盾，并用 /tmp/mem0_dream_auto.lock 做 10 分钟并发锁）。

配合 README 中的技能总表可以看到 /mem0:memory-reviewer 的一句话定位："Audit memory quality — duplicates, contradictions, stale"，与 /mem0:dream（Consolidate）形成明确的分工边界。

五、可复用的方法论：如何设计一个"只读审计"技能

对想在自己的 Agent 项目中落地类似记忆治理的读者，SKILL.md 提供了几个可直接借鉴的设计决策：

1. 诊断与写操作解耦。 审计技能被显式约束为 Read-only，所有破坏性操作被推到另一个技能中并强制走 diff + 用户确认。这降低了自动化流程误删记忆的风险，也让审计可以高频、无副作用地运行（比如每次会话 5 次写入后主动触发）。
2. 一切检测都锚定可计算的条件。 名词重叠率 60%、confidence 0.3、180 天、200 条上限——都是可以在纯文本层面执行、可复现的阈值，而不依赖"看起来重复"这类模糊判断。矛盾检测是唯一需要语义判断的项，文档也明确它要求"同一主题上的对立事实"，并配合 ID 输出供人工裁决。
3. 报告携带操作句柄。 每条问题都绑定 mem0:<id>，让下游技能或用户可以直接按 ID 处置，报告本身就是一份可执行工单。
4. 与平台能力对齐而非自建索引。 取数复用 get_memories 的 AND 过滤与分页，判定阈值与 dream/health 共享同一套（60% 重叠、0.3 置信度），保证整个插件生态对"什么是坏记忆"只有一个定义。

参考文件

• memory-reviewer 技能定义——本文主题文档
• dream 记忆固化技能——重复合并、矛盾消解、剪枝的执行方
• health 健康检查技能——--deep 深度质量扫描
• mem0 插件 README——技能总表与 MCP 工具清单
• MCP 服务配置——mcp.mem0.ai 服务地址与认证方式
• 检索辅助函数——标准过滤子句与上下文渲染格式
• 编码分类法安装脚本——17 个编码导向记忆分类的定义