Mem0 pi-agent-plugin 的 status 技能剖析四步健康检查与 --deep 记忆质量分析【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain本文为 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-loaderstatus负责健康检查与诊断。它不是独立实现诊断逻辑的程序而是指导 LLM agent 使用mem0_memory工具按固定步骤执行探测并汇报——这一点对理解下文各检查项的执行方式很关键。标准健康检查四项 Check 的完整流程Check 1API 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。这三者的实际解析逻辑分散在两个源文件中user_idsrc/entry.ts 的resolveUserId()按顺序回退——配置文件userId→ 环境变量$USER→$USERNAME→os.userInfo().username→ 兜底字符串default。这与技能描述的from config, env, or system user完全对应且最后的default就是技能中 WARN 所指的falls back to defaults情形。project_idsrc/memory/scoping.ts 的detectAppId()执行git rev-parse --show-toplevel3 秒超时取 git 仓库根的目录名作为 app_idgit 检测失败时回退到当前目录名。因此 monorepo 的所有子目录共享同一个 project 记忆池——这也是 README 中 Monorepo-aware 特性的实现依据。session_idsrc/memory/scoping.ts 的detectRunId()对会话文件路径做 SHA-256 哈希并截取前 12 位十六进制字符无会话文件时返回unknownWARN 情形。这三个值在 src/entry.ts 的session_start事件钩子中组装进scopeCtx此后所有mem0_memory工具调用与/mem0-status命令都复用同一份上下文。Check 3连通性探测技能规定使用mem0_memory工具执行actionsearch、queryhealth 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工具执行actionadd、contentHealth check probe — safe to delete.成功PASS — 随后必须清理删除这条探针记忆失败FAIL — 展示错误。对应实现位于 src/memory/tools.tsadd分支以[{ 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 userkartik, projectmy-app, sessionabc123 PASS Connectivity 142ms PASS Write/Read write delete OK All checks passed.任一检查失败时需在汇总后追加一个## Troubleshooting小节给出针对该失败项的具体修复步骤而非笼统的请检查配置。扩展模式--deep记忆质量分析以/mem0-status --deep形式调用时在标准四项检查之外追加一轮记忆质量扫描由三项子检查组成。质量检查 1重复记忆Duplicates用mem0_memory的actionget_all拉取全部记忆在同一分类category内部两两比较文本重叠度——共享名词超过 60% 的配对计为疑似重复。报告格式Potential duplicates: N pairs [mem0:id1] ~ [mem0:id2] — both about shared topicget_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.jsonAPI Key 缺失时插件整体禁用status 技能的前置条件不成立。Check 1 输出密钥时遵守前 6 字符 ...的脱敏约定不要把完整 Key 写入诊断输出。Check 4 的探针记忆必须删除质量扫描发现的重复/过期/矛盾项应引导执行/mem0-dream而不是用mem0_memory逐条手工删除破坏性操作应走带确认的流程。所有检查都跑完再汇总单点失败不中断最终输出保持## mem0 health汇总块格式失败项附## Troubleshooting具体修复步骤。综合来看status技能的价值在于把插件到底能不能用拆解为可独立归因的四层——配置层API Key、作用域层身份三元组、网络层搜索连通、数据层写入/删除能力——并可通过--deep进一步下钻到记忆数据本身的质量问题是 Pi Agent 场景下排查 Mem0 集成故障的标准诊断流程。【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mem0 pi-agent-plugin 的 status 技能剖析：四步健康检查与 --deep 记忆质量分析
Mem0 pi-agent-plugin 的 status 技能剖析四步健康检查与 --deep 记忆质量分析【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain本文为 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-loaderstatus负责健康检查与诊断。它不是独立实现诊断逻辑的程序而是指导 LLM agent 使用mem0_memory工具按固定步骤执行探测并汇报——这一点对理解下文各检查项的执行方式很关键。标准健康检查四项 Check 的完整流程Check 1API 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。这三者的实际解析逻辑分散在两个源文件中user_idsrc/entry.ts 的resolveUserId()按顺序回退——配置文件userId→ 环境变量$USER→$USERNAME→os.userInfo().username→ 兜底字符串default。这与技能描述的from config, env, or system user完全对应且最后的default就是技能中 WARN 所指的falls back to defaults情形。project_idsrc/memory/scoping.ts 的detectAppId()执行git rev-parse --show-toplevel3 秒超时取 git 仓库根的目录名作为 app_idgit 检测失败时回退到当前目录名。因此 monorepo 的所有子目录共享同一个 project 记忆池——这也是 README 中 Monorepo-aware 特性的实现依据。session_idsrc/memory/scoping.ts 的detectRunId()对会话文件路径做 SHA-256 哈希并截取前 12 位十六进制字符无会话文件时返回unknownWARN 情形。这三个值在 src/entry.ts 的session_start事件钩子中组装进scopeCtx此后所有mem0_memory工具调用与/mem0-status命令都复用同一份上下文。Check 3连通性探测技能规定使用mem0_memory工具执行actionsearch、queryhealth 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工具执行actionadd、contentHealth check probe — safe to delete.成功PASS — 随后必须清理删除这条探针记忆失败FAIL — 展示错误。对应实现位于 src/memory/tools.tsadd分支以[{ 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 userkartik, projectmy-app, sessionabc123 PASS Connectivity 142ms PASS Write/Read write delete OK All checks passed.任一检查失败时需在汇总后追加一个## Troubleshooting小节给出针对该失败项的具体修复步骤而非笼统的请检查配置。扩展模式--deep记忆质量分析以/mem0-status --deep形式调用时在标准四项检查之外追加一轮记忆质量扫描由三项子检查组成。质量检查 1重复记忆Duplicates用mem0_memory的actionget_all拉取全部记忆在同一分类category内部两两比较文本重叠度——共享名词超过 60% 的配对计为疑似重复。报告格式Potential duplicates: N pairs [mem0:id1] ~ [mem0:id2] — both about shared topicget_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.jsonAPI Key 缺失时插件整体禁用status 技能的前置条件不成立。Check 1 输出密钥时遵守前 6 字符 ...的脱敏约定不要把完整 Key 写入诊断输出。Check 4 的探针记忆必须删除质量扫描发现的重复/过期/矛盾项应引导执行/mem0-dream而不是用mem0_memory逐条手工删除破坏性操作应走带确认的流程。所有检查都跑完再汇总单点失败不中断最终输出保持## mem0 health汇总块格式失败项附## Troubleshooting具体修复步骤。综合来看status技能的价值在于把插件到底能不能用拆解为可独立归因的四层——配置层API Key、作用域层身份三元组、网络层搜索连通、数据层写入/删除能力——并可通过--deep进一步下钻到记忆数据本身的质量问题是 Pi Agent 场景下排查 Mem0 集成故障的标准诊断流程。【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考