memory-doctor

Memory Doctor

bm doctor 会检查用户本地的 Basic Memory 项目，并报告问题所在。每个问题都会附上对应的修复命令（如果有）。Doctor 的检查只会读取信息；不会更改项目笔记或索引。建议执行的修复操作会更改内容，因此只有在用户同意后才能运行。

此技能需要可使用 bm（或 basic-memory）命令的 shell。

适用场景

• 搜索找不到用户确认存在的笔记，或重复返回同一篇笔记
• 笔记已保存，但文件没有变化，或情况相反
• 用户询问 Basic Memory 是否正常工作，或要求“检查”或“修复”
• 崩溃、导入中断或移动项目文件夹之后

运行

先只生成报告。此操作很快，且 JSON 格式稳定：

bm doctor --skip-self-test --json

添加 --project NAME 可检查单个项目。如果不使用 --skip-self-test，doctor 还会运行自检：在一次性沙盒中写入、编入索引并搜索一篇笔记。此操作需要几秒钟，可验证安装本身是否正常。如果报告没有问题，但某些功能仍似乎有故障，请运行此自检。

阅读报告

{
  "projects": [
    {
      "name": "work",
      "findings": [
        {
          "check": "search_index",
          "severity": "error",
          "summary": "1 search row does not match a current note, observation or relation.",
          "evidence": ["entity id=99, entity_id=99"],
          "action": {"kind": "reindex_search", "full": true},
          "command": "bm reindex --search --full --project work"
        }
      ],
      "has_errors": true
    }
  ],
  "skipped_cloud_projects": ["research"],
  "self_test": {"outcome": "skipped"},
  "has_errors": true
}

严重级别	含义	处理方式
error	不修复就无法消除	提供 command；如果它为 null，则说明相关证据
warning	需要处理，可能会自行恢复	如果有 command，则提供该命令
info	工作进行期间的正常状态	告知用户；正在运行的服务会完成此操作，执行 command 则可立即完成

索引会在后台追上进度。如果文件索引仍在运行，搜索结果中出现重复、缺失或多余的条目属于 warning，因为索引过程可能会清除这些问题；索引稳定后，这些问题就会变为 error。如果报告中只有 info，则没有问题。如果没有正在运行的 Basic Memory 服务，后台就不会编入索引，因此对于 info 发现也应提供 command。

云项目会列在 skipped_cloud_projects 下：这些项目在服务端编入索引，本地命令无法修复。

修复

1. 用通俗的语言向用户总结发现：涉及哪个项目、有什么问题，以及修复操作会做什么。将使用同一命令的发现归为一组。
2. 按 doctor 输出的原样显示每个 command，并在运行前征求用户同意。bm reindex --search --full 会重新读取项目中的每个文件，项目较大时可能需要较长时间。
3. 运行用户同意执行的命令。
4. 再次运行 bm doctor --skip-self-test --json，并确认问题已消失。

如果某项发现没有 command，不要自行编造。说明证据显示的情况（例如哪些文件已在磁盘上更改，而较新的保存操作仍在等待），并让用户自行决定。

退出代码

没有错误且自检通过（或已跳过）时，bm doctor 以 0 退出；否则以 1 退出。警告和信息不会导致命令失败。