Mem0 pi-agent-plugin 的 status 技能剖析：四步健康检查与 --deep 记忆质量分析

本文为 mem0 仓库中 Pi Agent 插件（integrations/pi-agent-plugin）的 status 技能（SKILL.md）详解。该技能是 agent 侧的"自检诊断"入口：当记忆操作失败、搜索返回空结果或需要确认插件是否正常工作时使用。读完后你将掌握：status 技能的完整执行流程（API Key 校验、身份解析、连通性探测、写入能力验证）、其输出格式规范，以及 --deep 扩展模式下对重复、过期、矛盾记忆的三类质量扫描方法，并能结合 src/memory/tools.ts 等源码理解每一项检查背后的真实调用链。

技能定位：agent 可执行的健康检查手册

status 技能是一个标准的 Pi Agent Skill，其 frontmatter 声明如下（见 SKILL.md）：

---
name: status
description: Diagnoses Mem0 connectivity, API key validity, and memory read/write functionality. Use when memory operations fail, searches return empty, or to verify the plugin is working correctly.
---

技能的核心约束是：Run ALL checks, then display a single summary. Do not stop on the first failure. 即四项检查全部执行完毕后一次性汇总输出，而不是遇到第一个失败就中断。这与排障场景的诉求一致——一次诊断应给出完整故障面，而不是一堆零散的报错。

在整个插件中，8 个技能各自覆盖一个能力域（remember、search、forget、tour、dream、pin、status、context-loader），status 负责健康检查与诊断。它不是独立实现诊断逻辑的"程序"，而是指导 LLM agent 使用 mem0_memory 工具按固定步骤执行探测并汇报——这一点对理解下文各检查项的执行方式很关键。

标准健康检查：四项 Check 的完整流程

Check 1：API Key 校验

技能要求验证 API Key 是否已配置，并指明插件有两个加载来源：

• 环境变量 MEM0_API_KEY；
• 配置文件 ~/.pi/agent/mem0-config.json。

判定规则：

• 未配置：FAIL — 报告 "No API key configured"；
• 已配置：PASS — 只展示前 6 个字符加 ...（例如 m0-dVe...），避免在终端输出中泄露完整密钥。

源码可以印证这两个加载来源及其优先级。src/config/index.ts 中 loadConfig() 先读取 ~/.pi/agent/mem0-config.json（路径由 os.homedir() + ".pi/agent" 拼接），JSON 解析失败时静默回退到默认值；随后环境变量覆盖文件配置：

if (process.env.MEM0_API_KEY) {
  config.apiKey = process.env.MEM0_API_KEY;
}
if (process.env.MEM0_USER_ID) {
  config.userId = process.env.MEM0_USER_ID;
}

即 MEM0_API_KEY / MEM0_USER_ID 环境变量优先于配置文件。同时，src/entry.ts 中如果 config.apiKey 为空，插件会直接打印警告并整体禁用扩展（"Extension disabled."）——因此 Check 1 FAIL 时，后续三项检查在真实环境中都不会执行，诊断时以该行为准。

Check 2：身份解析（Identity resolution）

技能要求报告解析后的三个身份维度：

• user_id：来自配置、环境变量或系统用户；
• project_id：从当前目录自动检测；
• session_id：当前会话标识符。

判定规则：user_id 和 project_id 非空即 PASS；任何一项回退到默认值则 WARN。

这三者的实际解析逻辑分散在两个源文件中：

1. user_id：src/entry.ts 的 resolveUserId() 按顺序回退——配置文件 userId → 环境变量 $USER → $USERNAME → os.userInfo().username → 兜底字符串 "default"。这与技能描述的"from config, env, or system user"完全对应，且最后的 "default" 就是技能中 WARN 所指的"falls back to defaults"情形。
2. project_id：src/memory/scoping.ts 的 detectAppId() 执行 git rev-parse --show-toplevel（3 秒超时），取 git 仓库根的目录名作为 app_id；git 检测失败时回退到当前目录名。因此 monorepo 的所有子目录共享同一个 project 记忆池——这也是 README 中 "Monorepo-aware" 特性的实现依据。
3. session_id：src/memory/scoping.ts 的 detectRunId() 对会话文件路径做 SHA-256 哈希并截取前 12 位十六进制字符；无会话文件时返回 "unknown"（WARN 情形）。

这三个值在 src/entry.ts 的 session_start 事件钩子中组装进 scopeCtx，此后所有 mem0_memory 工具调用与 /mem0-status 命令都复用同一份上下文。

Check 3：连通性探测

技能规定使用 mem0_memory 工具执行 action="search"、query="health check"：

• 调用成功（即使返回空结果）：PASS；
• 调用报错：FAIL — 展示错误信息。

从 src/memory/tools.ts 看，search 分支会先经 resolveSearchFilters(scope, scopeCtx) 生成过滤条件（project 作用域下为 { user_id, app_id }），再调用 mem0.search(query, { filters })。这里有一个值得注意的诊断细节：空结果与调用失败是两种不同状态——搜索无命中返回 matchCount: 0，属于 PASS；只有网络、认证或服务端异常抛出错误才是 FAIL。排障时若看到 Check 3 FAIL，应重点核对 API Key 有效性与网络可达性；若 PASS 但记忆总是搜不到，则问题更可能出在身份/作用域（回到 Check 2）。

Check 4：写入能力验证

技能规定使用 mem0_memory 工具执行 action="add"、content="Health check probe — safe to delete."：

• 成功：PASS — 随后必须清理，删除这条探针记忆；
• 失败：FAIL — 展示错误。

对应实现位于 src/memory/tools.ts：add 分支以 [{ role: "user", content }] 形式调用 mem0.add()，并附带按作用域解析的 userId/appId/runId 参数及 10 个默认自定义分类（DEFAULT_CUSTOM_CATEGORIES）。探针写入成功后的删除走 delete 分支（需要 memory_id，即 add/search 返回的 ID）。这条"写入后立即删除探针"的纪律保证健康检查不会污染用户的真实记忆池——尤其当探针会带上 project 作用域的 app_id 时。

输出格式

所有检查完成后，技能要求输出单一汇总块：

## mem0 health

PASS  API Key          m0-dVe...
PASS  Identity         user=kartik, project=my-app, session=abc123
PASS  Connectivity     142ms
PASS  Write/Read       write + delete OK

All checks passed.

任一检查失败时，需在汇总后追加一个 ## Troubleshooting 小节，给出针对该失败项的具体修复步骤（而非笼统的"请检查配置"）。

扩展模式：--deep 记忆质量分析

以 /mem0-status --deep 形式调用时，在标准四项检查之外追加一轮记忆质量扫描，由三项子检查组成。

质量检查 1：重复记忆（Duplicates）

用 mem0_memory 的 action="get_all" 拉取全部记忆，在同一分类（category）内部两两比较文本重叠度——共享名词超过 60% 的配对计为疑似重复。报告格式：

Potential duplicates: <N> pairs
  [mem0:<id1>] ~ [mem0:<id2>] — both about "<shared topic>"

get_all 分支（src/memory/tools.ts）直接透传 resolveSearchFilters 生成的作用域过滤器，返回结果经 truncateOutput 截断（最多 200 行 / 50KB）——当记忆量大时，质量扫描应意识到工具输出可能被截断，必要时分页或缩小作用域拉取。

质量检查 2：过期记忆（Stale memories）

标记那些超过 180 天且近期未被访问的记忆。这类记忆通常是历史偏好或旧项目上下文的残留，是 dream 整理流程中"prune stale entries"的主要目标。

质量检查 3：矛盾记忆（Contradictions）

在每个分类内部，标记相互断言对立事实的记忆配对（例如两条 preferences 记忆给出了互斥的偏好）。

质量汇总

## Memory Quality

Duplicates: <N> · Stale: <N> · Contradictions: <N>

三个计数全为 0 时输出 Memory quality: clean.；只要任一计数非零，就追加一句 Run /mem0-dream to fix.——即把质量问题直接路由到插件的自动整理（Dream consolidation）能力：合并重复、清理过期、消解矛盾。这样 status 与 dream 两个技能形成了"诊断 → 修复"的闭环。

与 /mem0-status 命令的关系：两条并行的诊断路径

插件为 status 能力提供了 agent 技能与用户命令两条路径，二者值得对照理解：

• /mem0-status 命令（人工快速查看）：src/commands.ts 中注册的处理器调用 mem0.getAll({ filters }) 探测连通性并统计项目内记忆数，输出连接状态、User/Project/Session 三元组、默认作用域、searchThreshold、自动捕获与 Dream 开关等配置项。它不做写入探测，也不做质量扫描。
• status 技能（agent 深度诊断）：本文所述的完整四步检查 + 可选质量分析，覆盖"写入是否可用"这一 /mem0-status 不覆盖的维度。

两者共享同一份 scopeCtx 与 loadConfig() 配置，所以技能中报告的身份信息与 /mem0-status 输出的 User/Project/Session 应一致——若不一致，说明会话状态（session_start 钩子是否已执行、git 检测是否失败）出了问题，这本身就是一个有用的诊断信号。

适用前提与实操要点

• 前提：已通过 pi install npm:@mem0/pi-agent-plugin 安装插件，并按 README.md 配置好 MEM0_API_KEY 或 ~/.pi/agent/mem0-config.json；API Key 缺失时插件整体禁用，status 技能的前置条件不成立。
• Check 1 输出密钥时遵守"前 6 字符 + ..."的脱敏约定，不要把完整 Key 写入诊断输出。
• Check 4 的探针记忆必须删除；质量扫描发现的重复/过期/矛盾项应引导执行 /mem0-dream，而不是用 mem0_memory 逐条手工删除（破坏性操作应走带确认的流程）。
• 所有检查都跑完再汇总，单点失败不中断，最终输出保持 ## mem0 health 汇总块格式，失败项附 ## Troubleshooting 具体修复步骤。

综合来看，status 技能的价值在于把"插件到底能不能用"拆解为可独立归因的四层——配置层（API Key）、作用域层（身份三元组）、网络层（搜索连通）、数据层（写入/删除能力）——并可通过 --deep 进一步下钻到记忆数据本身的质量问题，是 Pi Agent 场景下排查 Mem0 集成故障的标准诊断流程。