mem0 OpenCode 插件 mem0-status 诊断技能实战：内存连通性、身份解析与读写能力的完整体检指南

mem0-status 是 mem0 官方 OpenCode 插件内置的"健康体检"技能（slash 命令 /mem0-status），用于在记忆操作失败、搜索返回空结果或 add_memory 报错时，一次性定位问题出在 API Key、身份解析、内存工具连通性、写入能力、会话上下文还是自动整理（auto-dream）门控上。读完本文，你将掌握该技能六项检查的完整执行方法、--deep 深度质量扫描的四类问题判定标准，以及每一项检查背后的插件源码实现依据，从而能独立排查并修复 Mem0 集成中的任意一类故障。

技能定位：它是什么、何时使用

mem0-status 技能定义在 SKILL.md，其 frontmatter 明确了触发场景：

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

即：当记忆操作失败、搜索返回空、add_memory 报错，或只是想确认插件工作正常时使用。

它的执行总原则只有一句话：运行全部检查，最后输出一份汇总；不要在第一个失败处停下来（Run ALL checks, then display a single summary. Do not stop on the first failure）。这与普通"遇到错误就中断"的脚本调试不同——诊断的价值在于一次跑完拿到全局视图，例如同时发现"API Key 正常 + session 上下文缺失 + auto-dream 被门控等待"，才能推断出是 shell.env hook 没触发这一种根因，而不是三个独立问题。

该技能之所以能作为 /mem0-status 命令被输入，是因为插件的 config hook 会扫描自带的 opencode-skills/ 目录，为每个含 SKILL.md 的技能注册一条 slash 命令，并在模板中注入插件启动时已解析好的身份上下文（user_id、app_id、session_id、branch），相关注册逻辑见 opencode-mem0.ts。技能本体则通过 OpenCode 的 skills.paths 机制就地发现，无需复制到用户配置目录。

Check 1：API Key 检查

第一项检查验证 MEM0_API_KEY 是否配置。技能给出了一条只打印前 6 个字符（避免泄露完整密钥）的探测命令：

_KEY="${MEM0_API_KEY:-}"
[ -n "$_KEY" ] && echo "${_KEY:0:6}..." || echo "NOT_SET"

判定标准：

• 输出 NOT_SET：FAIL —— "No API key configured"
• 有输出（形如 m0-abc...）：PASS，命令本身已保证只打印前 6 个字符

从源码看，插件对 API Key 的解析并不只依赖当前进程环境变量。api-key.ts 中的 resolveApiKey() 会先读 process.env.MEM0_API_KEY，若为空则依次扫描 ~/.zshrc、~/.bashrc、~/.zprofile、~/.bash_profile、~/.profile 五个 shell profile 文件，用正则提取 MEM0_API_KEY= 行（兼容 export 前缀、引号包裹、行内注释），且拒绝以 $ 开头的值（说明是变量引用而非真实密钥）。这解释了一个常见现象：在 OpenCode 会话内 echo $MEM0_API_KEY 为空但插件仍可能加载成功——插件在启动时就做了兜底解析。反过来，如果 Check 1 显示 NOT_SET，优先检查 profile 文件中是否写了真实密钥而非 ${...} 占位符。

Check 2：身份解析（Identity Resolution）

Mem0 中每条记忆都归属到 user_id / app_id /（可选）run_id 上，身份解析是否正确直接决定"读到的记忆是不是这个项目、这个人的"。技能要求直接报告插件 shell.env hook 注入的 MEM0_* 环境变量，而不要在这里重新执行 git 命令。原文给出了明确理由：插件在会话启动时已经从 git 解析好了分支和项目，重新 shell 一次 git 可能与插件的解析结果不一致——例如重新执行 git branch --show-current 会打印空分支，被渲染成 (not a git repo)，而下面的 Session 检查却显示 branch=main，两行自相矛盾。"单一事实来源"（one source of truth）保证诊断报告内部一致。

echo "user_id=${MEM0_USER_ID:-${USER:-default}}"
echo "project_id=${MEM0_APP_ID:-}"
echo "branch=${MEM0_BRANCH:-main}"
_S="$HOME/.mem0/settings.json"
_SCOPE="$(grep -o '"default_scope"[[:space:]]*:[[:space:]]*"[a-z]*"' "$_S" 2>/dev/null | grep -o '[a-z]*"$' | tr -d '"')"
echo "default_scope=${_SCOPE:-project}"

四个值的来源与判定：

• user_id：来自 MEM0_USER_ID，回退到 $USER
• project_id：来自 MEM0_APP_ID
• branch：来自 MEM0_BRANCH（插件解析值；不在 git 仓库中时回退为 main）。原样报告，不要杜撰 (not a git repo) 之类的字符串
• default_scope：来自 ~/.mem0/settings.json 的 default_scope 字段，缺失时回退 project。这是未显式指定 scope 时记忆工具使用的默认范围，可用 /mem0-scope 修改

判定标准：user_id 和 project_id 均非空为 PASS；project_id 为空为 WARN —— 提示 shell.env hook 可能没有触发（需重启 OpenCode）。

这些环境变量的注入点在 opencode-mem0.ts 的 shell.env hook：

output.env.MEM0_USER_ID = userId;
output.env.MEM0_APP_ID = appId;
output.env.MEM0_SESSION_ID = sessionId;
output.env.MEM0_BRANCH = branch;
output.env.MEM0_GLOBAL_SEARCH = globalSearch ? "true" : "false";

而四个值各自的解析策略（决定了报告里应该看到什么）在插件启动函数中实现：

• user_id：getUserId() 优先 MEM0_USER_ID 环境变量，其次 os.userInfo().username，最后回退 USER/USERNAME，兜底 unknown；
• project_id（app_id）：getProjectId() 优先 MEM0_APP_ID，其次执行 git remote get-url origin 并由 parseProjectFromRemote() 解析出 owner-repo 形式（一个正则同时兼容 https、scp 风格 ssh、自定义主机别名、可选的 .git 后缀与尾部斜杠）。这个选择让 app_id 在 clone、worktree、仓库子目录间保持稳定；没有可用 remote 时回退到 git rev-parse --show-toplevel 的根目录名，再回退到 cwd 目录名；
• branch：getBranch() 执行 git branch --show-current，空则 main。

default_scope 的读取逻辑对应 scope.ts 的 resolveDefaultScope()：插件每次记忆操作都会重新读取 ~/.mem0/settings.json，所以通过 /mem0-scope 修改默认范围后立即生效，无需重启。三个 scope 的语义见 scope.ts：project 只限本仓库（user_id + app_id 过滤）、session 只限本次运行（额外加 run_id）、global 跨全部项目（读用 app_id="*"，写时丢弃 app_id 使其成为用户级记忆）。

Check 3：记忆工具连通性

用一次最小代价的搜索调用验证"插件 → mem0ai SDK → Mem0 Platform"这条链路是否通：

• 调用 search_memories，参数为：
  • query="health check"
  • filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}
  • top_k=1

判定：成功返回即为 PASS（即使结果为空）——空结果只说明作用域内还没有记忆，不说明链路有问题；报错则 FAIL 并展示错误消息。

这条链路的实现可对照 opencode-mem0.ts 中 search_memories 工具的定义：top_k（或 limit）默认 10，技能显式传 1 是为了最小化探测成本；若未显式给 filters，插件会按默认 scope 自动补上 user_id + app_id 过滤（见 readScopeFilters()），所以诊断时按技能指定的 filters 原样传入即可与插件自身行为对齐。搜索成功、但 Check 2 中身份为空，基本可以定位到 hook 注入问题；搜索报 401 则回到 Check 1 检查密钥有效性。

Check 4：记忆写入能力

搜索通不等于写入通（异步事件、鉴权范围都可能出问题），因此需要一次带清理的完整写-查-删闭环。

调用 add_memory：

• text="Health check probe — safe to delete."
• user_id=<active_user_id>
• app_id=<active_project_id>
• metadata={"type": "health_check", "probe": true}
• infer=False（原文档如此；插件实现里 infer 缺省且 confidence>=1.0 时也会自动置为 false，见 add_memory 执行逻辑）

v3 平台的写入是异步的：add_memory 的响应返回 event_id 而非最终记忆。需要用事件工具轮询处理结果——插件把该工具注册为 get_event_status，实现是对 REST 端点 GET /v1/event/<event_id>/ 的直接调用，见 opencode-mem0.ts。

判定标准：

• 状态 SUCCEEDED：PASS —— 从事件结果中提取 memory ID，然后调用 delete_memory 删除该探针记录完成清理
• 5 秒后状态仍为 PENDING：PASS（写请求已被接受，只是处理延迟）
• 报错：FAIL —— 展示错误

另外注意：add_memory 在执行时会为 metadata 补默认值——缺省 confidence=0.7、source="opencode"、type="task_learning"（技能里显式传了 type="health_check" 会覆盖它）、当前 session_id、files=["*"] 和分支名，均在 opencode-mem0.ts 中可见。这意味着探针记忆写入后确实带完整元数据，delete_memory 按 ID 删除是干净可靠的。

Check 5：会话上下文（Session Context）

验证插件的 shell.env hook 是否把会话上下文注入到了 shell 环境：

echo "session_id=${MEM0_SESSION_ID:-}"
echo "app_id=${MEM0_APP_ID:-}"
echo "branch=${MEM0_BRANCH:-}"

判定：

• 三者均非空：PASS —— "Session active"
• 任一缺失：WARN —— "Plugin env vars not set; shell.env hook may not have fired"

MEM0_SESSION_ID 由插件在启动时用时间戳加 3 字节随机数生成（形如 ses_<ts>_<hex>，见 generateSessionId()），每个 OpenCode 会话唯一，并被 scope=session 的记忆范围用作 run_id。如果 Check 2 能读到 MEM0_APP_ID 而 Check 5 读不到 MEM0_SESSION_ID，说明环境变量注入发生在会话启动之后（例如中途安装/升级了插件），典型修复动作就是重启 OpenCode。

Check 6：Auto-dream 就绪状态

这项检查解释 auto-dream（记忆自动整理/consolidation）当前是否有资格运行，若没有，精确指出被哪个门控（gate）挡住。规则是：auto-dream 每个会话最多运行一次，且只有三个门控全部通过才会运行——距上次整理的时间 ≥ minHours、期间累计会话数 ≥ minSessions、项目记忆数 ≥ minMemories。

读取门控状态与阈值：

_ST="$HOME/.mem0/mem0-dream-state.json"
_SET="$HOME/.mem0/settings.json"
echo "sessions_since=$(grep -o '"sessionsSince"[[:space:]]*:[[:space:]]*[0-9]*' "$_ST" 2>/dev/null | grep -o '[0-9]*$' || echo 0)"
echo "last_consolidated_ms=$(grep -o '"lastConsolidatedAt"[[:space:]]*:[[:space:]]*[0-9]*' "$_ST" 2>/dev/null | grep -o '[0-9]*$' || echo 0)"
echo "min_hours=$(grep -o '"minHours"[[:space:]]*:[[:space:]]*[0-9]*' "$_SET" 2>/dev/null | grep -o '[0-9]*$' || echo 24)"
echo "min_sessions=$(grep -o '"minSessions"[[:space:]]*:[[:space:]]*[0-9]*' "$_SET" 2>/dev/null | grep -o '[0-9]*$' || echo 5)"
echo "min_memories=$(grep -o '"minMemories"[[:space:]]*:[[:space:]]*[0-9]*' "$_SET" 2>/dev/null | grep -o '[0-9]*$' || echo 20)"
echo "now_s=$(date +%s)"
echo "dream_env=${MEM0_DREAM:-unset}"

这些默认值（24 / 5 / 20）不是技能凭空规定的，而是插件代码中的常量 DREAM_DEFAULTS，配置加载逻辑 loadDreamConfig() 从 ~/.mem0/settings.json 的 dream 块逐项覆盖，且 MEM0_DREAM 环境变量取值 false/0/no/off 时会强制禁用（优先于配置文件）。状态文件 mem0-dream-state.json 记录 lastConsolidatedAt（毫秒时间戳）、sessionsSince 与 lastSessionId，由 incrementSessionCount() 在每个新会话首条消息时 +1，成功后由 recordDreamCompletion() 重置计数。

对于记忆数，复用 Check 3/4 已拿到的项目记忆数即可，或调用 get_memories 加项目过滤、page_size=1，读响应里的 count。

逐门计算：

• time：hours_since = (now_s - last_consolidated_ms/1000) / 3600，≥ min_hours 通过；last_consolidated_ms 为 0 表示从未运行过 → time 门直接通过（与源码 checkCheapGates() 中 lastConsolidatedAt 缺省 0 的行为一致）
• sessions：sessions_since ≥ min_sessions 通过
• memories：项目记忆数 ≥ min_memories 通过

报告规则：

• dream_env 为 false/0/no/off，或 settings 中 dream.enabled 为 false：WARN —— "Auto-dream disabled"
• 三门全过：PASS —— "eligible (runs at next session start)"（下一次会话启动时运行，因为触发点挂在会话初始化流程里）
• 其余：WARN —— 列出被挡住的门，例如 sessions 2/5, memories 3/20。原文强调：这是预期状态，不是错误——auto-dream 只是在等待。用户也可以立即运行 /mem0-dream 手动整理，或在 ~/.mem0/settings.json 的 dream 块中调低阈值。

从源码结构看，触发路径为：会话首条消息时插件检查 dreamConfig.enabled && dreamConfig.auto，调用 checkCheapGates + checkMemoryGate，全部通过后还要拿到一个文件锁（~/.mem0/mem0-dream.lock，acquireDreamLock() 使用 wx 独占写标志防并发，超过 1 小时的僵尸锁会被回收），最后把 DREAM_PROTOCOL 整理协议注入 agent 上下文。这也解释了状态行里的措辞——PASS 表示"下次会话启动注入协议"，而不是"现在就在跑"。

汇总展示格式

所有检查跑完后，按原文档规定的格式输出一份单一汇总（示例，其中 m0-dVe...、user=kartik、project=mem0 等为示意值）：

## mem0 status

PASS  API Key         m0-dVe...
PASS  Identity        user=kartik, project=mem0, branch=main
PASS  Default scope   project
PASS  Memory Tools    142ms
PASS  Write/Read      write + delete OK
PASS  Session         session_id=abc123, app_id=mem0, branch=main
WARN  Auto-dream      waiting — sessions 2/5, memories 3/20 (/mem0-dream to run now)

All checks passed.

两条语义要点：

• Auto-dream 行是信息性的：这里的 WARN 意为"等待门控通过"，不是失败；就绪显示 PASS，关闭则显示 "disabled"
• 任何检查失败时，追加一个 ## Troubleshooting 小节，针对每个失败给出具体修复步骤（例如 NOT_SET → 配置 MEM0_API_KEY；project_id 为空 → 重启 OpenCode 让 shell.env hook 触发；搜索 401 → 核对 echo $MEM0_API_KEY 是否为 m0- 开头的平台密钥）

扩展模式：--deep 记忆质量扫描

以 --deep 调用（如 /mem0-status --deep）时，在标准 6 项检查之外追加一次只读的质量扫描——发现问题但不动手修改，修复交给 /mem0-dream。

Quality Check 1：重复（Duplicates）

调用 get_memories，filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}，page_size=200。在同一 metadata.type 组内比较所有记忆两两之间的文本重叠度（共享名词/关键词 > 60% 视为高重叠），报告：

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

这与 /mem0-dream 技能中的近重复判定启发式保持一致（同 type、>60% 显著名词重叠、且均未 pinned，见 mem0-dream/SKILL.md），因此 --deep 报出的候选对就是后续 dream 会自动合并的集合。

Quality Check 2：过期记忆（Stale memories）

满足以下任一条件即标记：

• metadata.type 为 session_state 或 compact_summary 且超过 90 天
• metadata.confidence < 0.3 且超过 30 天

Stale candidates: <N>
  [mem0:<id>] — session_state, 142d old

90 天的 session_state/compact_summary 保留期正是 dream 技能的内置保留策略默认值；而插件确实会周期性产生这两类元数据——压缩（compaction）钩子写入 type: "session_state" 记忆（compactionHook）、每条消息按 3 条一批的自动捕获等，所以长期项目里这类记忆会自然累积。

Quality Check 2b：低置信度记忆（Low-confidence memories）

凡 metadata.confidence < 0.5 的记忆（不限年龄）单独统计，与 stale 分开报告：

Low-confidence memories: <N>
  [mem0:<id>] — confidence=0.3, "<content preview>"

置信度来源可以参考写入路径：add_memory 未显式给 confidence 时默认 0.7（opencode-mem0.ts），"remember this" 类显式请求会以 confidence=1.0、infer=false 落库，而自动捕获（auto_capture）固定 0.7——因此 < 0.5 的记忆通常来自平台侧推理抽取时给出的低分，值得人工复核。

Quality Check 3：矛盾（Contradictions）

在每个 metadata.type 组内，标记就同一主题断言对立事实的记忆对。使用语义判断——找否定模式、冲突的工具/框架选择、被反转的决策（例如 "Deploy to ECS" vs "Deploy to Vercel"）：

Possible contradictions: <N>
  [mem0:<idA>] vs [mem0:<idB>] — conflicting on "<topic>"

Quality Check 4：孤儿记忆（Orphan memories）

metadata.type 未设置、或不在 17 个已知编码类（coding categories）之内的记忆。这类记忆通常是写入时未正确打标签：

Untagged/orphan memories: <N>

质量汇总

## Memory Quality

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

• 全部为 0：输出 Memory quality: clean.
• 任一非 0：追加 Run /mem0-dream to fix.

/mem0-dream 会执行自动整理（合并重复、按保留策略修剪、交互式消解矛盾），--deep 本身则保持只读，两者分工明确。

输出格式约定：为什么禁用 Markdown

原文档末尾有一条贯穿性的格式约束，值得单独强调：输出中不要使用 Markdown。原因是 OpenCode TUI 逐字渲染文本——**bold**、## 标题、| 表格 | 语法都会以原始字符显示出来。技能要求用纯文本 + 缩进组织结构：短横线做列表、空格对齐列（而不是 Markdown 表格）。上面的展示模板本身就遵循了这一规则（例如 PASS API Key 用空格对齐而非表格）。这一约定与 /mem0-dream 等兄弟技能的输出格式说明完全一致，是该插件所有技能的共同约定。

相关文件索引

文件	作用
mem0-status/SKILL.md	本技能完整定义（6 项检查 + --deep 质量扫描 + 展示格式）
opencode-mem0.ts	插件主入口：工具注册、shell.env 注入、身份解析、auto-dream 触发
dream.ts	auto-dream 门控、状态文件、文件锁与 DREAM_PROTOCOL 协议
scope.ts	project/session/global 三种范围的过滤与写入参数解析
project.ts	从 git remote 解析稳定的 app_id（owner-repo）
api-key.ts	API Key 解析（环境变量 + shell profile 兜底）
mem0-dream/SKILL.md	质量扫描发现问题的修复入口：合并/修剪/矛盾消解
OpenCode 插件 README	插件安装、hooks 与工具总览、troubleshooting 表

适用前提小结：以上全部行为基于当前仓库中 .opencode-plugin/ 目录下的 TypeScript 实现（纯 TS，无 Python、无 MCP 服务器）；MEM0_* 环境变量只在 shell.env hook 触发后的会话内有效，因此所有检查均应在一个已安装插件并重启后的 OpenCode 会话中执行。