mem0-plugin Health 技能详解五项连通性体检与记忆质量深度审计【免费下载链接】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/embedchainmem0-plugin 是 Mem0 为 Claude Code、Cursor、Codex 等编码智能体提供的插件见 integrations/mem0-plugin/README.md它通过 MCP 服务器与生命周期 Hook 为智能体提供跨会话的持久记忆。当记忆操作失败、搜索返回空结果、MCP 连接中断时插件内置的health技能integrations/mem0-plugin/skills/health/SKILL.md提供了一套结构化的诊断流程五项连通性检查逐项排查 API 密钥、身份解析、MCP 读写能力与会话统计状态--deep扩展模式还能对存量记忆做重复、过期、矛盾、孤儿四类质量扫描。读完本文你可以掌握这套体检流程的每一步操作、判定标准以及它背后的身份解析链、Hook 机制与统计文件实现。技能定位与执行总原则health技能的元数据声明了它的触发场景SKILL.md 的 frontmattername: health description: Diagnoses mem0 connectivity, API key validity, and memory read/write functionality. Use when memory operations fail, searches return empty, add_memory errors occur, MCP connection drops, or to verify the plugin is working correctly.即当记忆操作失败、搜索返回空、add_memory报错、MCP 连接掉线或只是想验证插件是否正常工作时应调用它。文档给出了一条关键执行原则运行全部检查项后再展示单一汇总不要在第一处失败时就停下Run ALL checks, then display a single summary. Do not stop on the first failure.。这样做的好处是用户可以一次拿到完整的故障面而不是逐项排雷。整个诊断体系由四条链路构成下文按检查顺序逐一展开并结合插件源码说明每项检查实际验证的底层机制。检查一API 密钥是否配置第一步用最轻量的方式确认密钥存在且只打印前 6 位以避免在会话日志中泄露完整密钥_KEY${MEM0_API_KEY:-${CLAUDE_PLUGIN_OPTION_MEM0_API_KEY:-}} [ -n $_KEY ] echo ${_KEY:0:6}... || echo NOT_SET判定标准很直接输出NOT_SETFAIL— No API key configured已设置PASS命令本身只回显前 6 个字符如m0-dVe...。从源码看密钥解析的完整优先级链检查一验证的是最终生效的MEM0_API_KEY而插件实际的密钥解析逻辑在 _identity.sh 中优先级依次为MEM0_API_KEY环境变量显式设置 / shell profileCLAUDE_PLUGIN_OPTION_API_KEY由 Claude Code 的 userConfig 注入对应安装时提示输入的密钥CLAUDE_PLUGIN_OPTION_MEM0_API_KEY旧版 userConfig 变量名从 shell profile 文件~/.zshrc、~/.bashrc、~/.zprofile、~/.bash_profile、~/.profile中用grep提取export MEM0_API_KEY...字面量。第 4 条 fallback 值得注意桌面应用如 Claude Cowork不会从 shell profile 继承环境变量只读PATH因此 _identity.sh 特意做了基于 grep 的提取——只接受字面量值跳过${OTHER_VAR}这类变量引用避免 source 整个 profile 产生副作用。这也解释了 health 检查只查MEM0_API_KEY和CLAUDE_PLUGIN_OPTION_MEM0_API_KEY两个变量的原因其余来源最终都会归一到MEM0_API_KEY。MCP 连接本身的认证方式由 mcp_config.json 定义服务器地址为https://mcp.mem0.ai/mcp/请求头Authorization: Token ${MEM0_API_KEY}。所以检查一失败意味着后面所有 MCP 调用都会失败它是整条诊断链的地基。检查二身份解析user_id / project_id / branchmem0 的记忆是按身份隔离的所有读写都要携带user_id与app_id项目 ID。health 检查要求用插件自己的解析脚本来解析身份确保诊断结果与 Hook 实际使用的值一致SCRIPT_DIR${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}}/scripts source $SCRIPT_DIR/_identity.sh 2/dev/null echo user_id${MEM0_RESOLVED_USER_ID:-} echo project_id${MEM0_PROJECT_ID:-} echo branch${MEM0_BRANCH:-}注意这里用CLAUDE_PLUGIN_ROOT/CODEX_PLUGIN_ROOT/CURSOR_PLUGIN_ROOT三级变量逐级回退以适配不同平台注入的插件根目录。当CLAUDE_PLUGIN_ROOT不可用时的退化路径为user_id取自MEM0_USER_ID或$USERproject_id取自MEM0_PROJECT_ID或查~/.mem0/project_map.json中$PWD的映射branchgit branch --show-current。判定标准三项全部非空为PASS任何一项退化为默认值则为WARN。源码级解析细节_identity.sh对user_id的处理极简L48-L57有MEM0_USER_ID就用它否则用$USER再否则为default。若MEM0_USER_ID与系统用户不同还会导出_MEM0_IDENTITY_ANNOTATION形如 (override; default: xxx)最终出现在会话启动横幅的状态行里提醒当前用户身份是显式覆盖值。project_id与branch的解析在 _project.sh 中项目 ID 的完整优先级为MEM0_PROJECT_ID环境变量显式覆盖~/.mem0/project_map.json按$PWD查找需要jqGit remote slug去掉协议前缀与.git后缀保留最后两级路径owner/repo其余/、:替换为-例如gitgithub.com:mem0ai/mem0.git→mem0ai-mem0解析成功后还会把该PWD → slug映射持久化回project_map.json见 L56-L61下次同目录启动直接命中第 2 级兜底$PWD的 basename。branch取git branch --show-current失败则记为unknown。之所以要求用插件自己的脚本解析而非手工推导是因为 on_session_start.sh 在会话启动时会把解析结果MEM0_SESSION_ID、MEM0_RESOLVED_USER_ID、MEM0_PROJECT_ID、MEM0_BRANCH、MEM0_API_KEY写入CLAUDE_ENV_FILE供后续 Bash 工具调用和 MCP 配置继承——health 检查直接 source 同一脚本保证诊断身份 运行时身份不会出现检查通过但 Hook 用错身份的偏差。另外_identity.sh 还会从~/.mem0/settings.json加载一组用户可改的配置并导出为环境变量这些默认值与后文的保留策略直接相关配置项环境变量默认值用途auto_saveMEM0_AUTO_SAVEtrue是否自动捕获记忆auto_searchMEM0_AUTO_SEARCHtrue是否自动检索记忆search_limitMEM0_SEARCH_LIMIT10检索返回条数上限retention_session_daysMEM0_RETENTION_SESSION_DAYS90session 类记忆保留天数confidence_thresholdMEM0_CONFIDENCE_THRESHOLD0.3置信度阈值global_searchMEM0_GLOBAL_SEARCHfalse是否全局搜索跨用户/项目debugMEM0_DEBUGfalse是否写~/.mem0/hooks.log调试日志检查三MCP 服务器连通性读路径通过 MCP 调用search_memories发一次最小化的真实查询queryhealth checkfilters{AND: [{user_id: active_user_id}, {app_id: active_project_id}]}top_k1判定标准只要能成功返回哪怕结果为空即为 PASS——空结果只说明没有匹配记忆不代表链路有问题调用报错才是FAIL并需展示错误信息。输出格式中还包含实测延迟如PASS MCP Connection 142ms这是唯一能真实验证 MCP 服务器https://mcp.mem0.ai/mcp/可达性、且同时验证密钥被服务端接受的一步检查一只证明本地有密钥本检查才证明密钥有效 网络通畅 服务在线。从源码结构看这一步也顺带验证了user_idapp_id过滤语法是否可用——enforce_metadata_defaults.sh 这个 PreToolUse Hook 会在智能体遗漏身份参数时自动注入filters.AND[]见 L78-L135health 检查显式带上 filters等价于验证了 Hook 注入后的最终形态。检查四记忆写入能力写路径读通之后再验证写链路。调用add_memory写入一条探针记忆textHealth check probe — safe to delete.user_idactive_user_idapp_idactive_project_idmetadata{type: health_check, probe: true}inferFalse关键细节是inferFalse探针写入不经过 LLM 抽取直接落库保证写入的是确定性数据而不是模型改写后的内容。mem0 v3 API 的写入是异步的add_memory返回event_id而非记忆 ID需要再调get_event_status(event_idevent_id)轮询处理状态。判定规则分三档事件状态判定后续动作SUCCEEDEDPASS从事件结果中提取记忆 ID调用delete_memory清理探针不留垃圾数据PENDING5 秒后仍未完成PASS视为写入已受理、处理延迟服务端队列拥堵不等于链路故障报错FAIL展示错误信息SUCCEEDED 后立即删除构成一次完整的写→确认→读→删闭环既然能从事件中取回记忆 ID 并成功删除说明delete_memory这条路径同样可用这正是汇总行PASS Write/Read write delete OK的由来。这里还有一个容易被忽略的机制type: health_check这个 metadata 字段是探针的自报家门与插件的元数据强制机制一脉相承。enforce_metadata_defaults.sh 在处理add_memory调用时若 metadata 缺少字段会自动补齐默认值confidence0.7、files[*]、sourceauto_capture、typetask_learning并注入session_id来自/tmp/mem0_session_id_$USER用于会话内追踪。探针显式带了type就不会被改写成task_learning从而在后续质量扫描检查metadata.type中可被清晰识别为探针残留。检查五会话统计追踪器最后确认本地统计文件是否正常工作STATS_FILE/tmp/mem0_session_stats_${USER}.json if [ -f $STATS_FILE ] python3 -c import json; json.load(open($STATS_FILE)) 2/dev/null; then echo OK else echo FAIL fi该文件由 session_stats.py 维护STATS_FILE /tmp/mem0_session_stats_{USER}.json每个用户单文件、会话初始化时重置。它记录adds写入次数、searches检索次数、categories/category_counts按类别统计、recent_ids最近 50 条记忆 ID见 L45和started时间戳供/mem0:stats类技能汇总会话内的记忆活动。写入时机在 on_session_start.sh 中可以确认SessionStartHook 在source startup时执行session_stats.py init重置统计并在CLAUDE_ENV_FILE中持久化身份变量。之后 PreToolUse 阶段的 enforce_metadata_defaults.sh 在每次add_memory/search_memories/get_memories工具调用时异步记录add/search计数源码注释说明插件 MCP 工具不触发 PostToolUse Hook故统计放在 PreToolUse 侧。判定要点文件不存在不一定是故障——文档明确提示它由SessionStartHook 创建、由后续 Hook 更新如果它缺失很可能是会话 Hook 还没触发过应先发一条消息再重新检查。只有发过消息后仍缺失或 JSON 无法解析才真正说明 Hook 链断裂。debug配置开启后所有 Hook 的 stderr 会追加到~/.mem0/hooks.log见 on_session_start.sh可作为进一步排查入口。诊断结果展示格式五项检查全部跑完后按如下格式输出单一汇总## mem0 health PASS API Key m0-dVe... PASS Identity userkartik, projectmem0, branchmain PASS MCP Connection 142ms PASS Write/Read write delete OK PASS Session Tracker stats file active All checks passed.每行对应一项检查值中携带最小化的证据密钥前缀、身份三元组、延迟、读写结果、统计文件状态。若任何一项失败必须在汇总后追加## Troubleshooting小节逐项给出对应的具体修复步骤而不是笼统建议重新配置。结合前文的机制各失败项的典型修复方向是API Key 失败 → 按 README 的 Step 1 重新配置shell profile 或桌面应用本地环境变量编辑器身份 WARN → 检查MEM0_USER_ID/MEM0_PROJECT_ID或清理~/.mem0/project_map.jsonMCP 失败 → 核对网络与密钥有效性会话追踪失败 → 触发一次对话再复查并开debug看~/.mem0/hooks.log。扩展模式--deep记忆质量审计以/mem0:health --deep方式调用时在标准五项检查之外追加一轮记忆质量扫描。数据源统一为get_memoriesfilters{AND: [{user_id: active_user_id}, {app_id: active_project_id}]}page_size200拉取全量项目记忆后本地分析。质量检查 1重复记忆Duplicates在同一metadata.type分组内两两比较文本重叠度共享名词/关键词 60% 判定为疑似重复输出Potential duplicates: N pairs [mem0:id1] ≈ [mem0:id2] — both about shared topic按类型分组比较是有意为之decision与bug_fix两条记忆即使措辞相近也可能记录不同事实组内比较才能避免误报。质量检查 2过期记忆Stale memories标记满足以下任一条件的记忆metadata.type为session_state或compact_summary且超过90 天metadata.confidence 0.3且超过30 天。Stale candidates: N [mem0:id] — session_state, 142d old90 天阈值与配置默认值呼应retention_session_days默认即 90_identity.sh而 0.3 的置信度下限对应confidence_threshold默认值L72。这两个数字同时出现在dream技能的内置保留策略表中session_state/compact_summary默认保留 90 天见 dream/SKILL.md说明 health 的过期判定与 dream 的修剪策略使用同一套标尺——health 负责发现dream 负责处置。质量检查 2b低置信度记忆Low-confidence独立于过期判断凡metadata.confidence 0.5不论年龄单独列出Low-confidence memories: N [mem0:id] — confidence0.3, content preview与 0.3 的过期门槛不同0.5 是值得人工审视的提示线单独成组报告可避免低置信度但仍在有效期内的记忆被误判为过期。质量检查 3矛盾记忆Contradictions在同一metadata.type组内标记就同一主题断言相反事实的配对。文档强调使用语义判断——寻找否定模式、冲突的工具/框架选型、被推翻的决策而不是字面匹配Possible contradictions: N [mem0:idA] vs [mem0:idB] — conflicting on topic质量检查 4孤儿记忆Orphans未设置metadata.type或metadata.type不属于17 个已知编码类别的记忆视为未经正确打标的孤儿数据Untagged/orphan memories: N类别体系的自动安装由 auto_setup_categories.py 在会话启动后台完成on_session_start.sh正常情况下新写入的记忆都会带合法type出现孤儿通常意味着某次写入绕过了元数据强制 Hook例如global_search模式或其他工具直写平台。质量汇总与处置## Memory Quality Duplicates: N · Stale: N · Contradictions: N · Orphans: N全部为 0输出Memory quality: clean.任一非零追加一句Run /mem0:dream to fix.dream技能integrations/mem0-plugin/skills/dream/SKILL.md是配套的自动整合流程拉取全项目记忆 → 按保留策略parse_mem0_config.py解析项目mem0.md失败则用内置默认识别近重复、矛盾与过期项 → 以 diff 形式展示全部拟议变更 →经用户批准后才执行合并、修剪与冲突消解。health 与 dream 由此构成体检—治疗的分工闭环health 的--deep输出量化问题面dream 在用户确认下修复。小结health技能把 mem0-plugin 的运行时链路拆成五个可独立判定的观测点并刻意选择与生产路径同源的验证方式检查二直接 source 生产 Hook 使用的 _identity.sh / _project.sh检查三/四走与 Hook 注入后一致的filters.AND[]过滤语法检查五验证 session_stats.py 所维护的统计文件。任何诊断通过但实际不工作的缝隙都源于诊断路径与生产路径不一致该设计正是为消除这类缝隙。排查时建议按顺序执行先标准五项定位断点密钥 → 身份 → 读 → 写 → Hook 链再以--deep评估存量记忆质量发现问题后交由dream在用户确认下完成整合。【免费下载链接】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），仅供参考