memory-doctor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memory Doctor

bm doctor

checks the user's local Basic Memory projects and reports what is wrong. Each problem comes with the command that fixes it, when one exists. Doctor's checks only read; they never change a project's notes or index. The fixes it suggests do change things, so run them only after the user agrees.

This skill needs a shell with the

bm

(or

basic-memory

) command.

bm doctor

会检查用户的本地 Basic Memory 项目并报告存在的问题。每个问题都会附带用于修复它的命令（如果存在）。Doctor 的检查操作仅执行读取；它绝不会更改项目的笔记或索引。它建议的修复会进行更改，因此只能在用户同意后运行。

此 skill 需要一个可使用

bm

（或

basic-memory

）命令的 shell。

When to Use

何时使用

Search misses a note the user knows exists, or returns the same note twice
A note was saved but its file did not change, or the reverse
The user asks whether Basic Memory is working, or to "check" or "fix" it
After a crash, an interrupted import, or moving a project's folder

搜索未找到用户明确知道存在的笔记，或返回了同一笔记两次
笔记已保存，但对应文件没有变化，或者情况相反
用户询问 Basic Memory 是否正常工作，或要求“检查”或“修复”它
发生崩溃、导入被中断，或移动了项目的文件夹之后

Run It

运行方式

Start with the report alone. It is fast and has a stable JSON shape:

bash

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

Add

--project NAME

to check one project. Without

--skip-self-test

, doctor also runs a self-test: it writes, indexes and searches a note in a throwaway sandbox, which takes a few seconds and proves the install itself works. Run it when the report is clean but something still seems broken.

先只运行报告。它速度很快，且输出具有稳定的 JSON 结构：

bash

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

添加

--project NAME

可检查单个项目。如果不使用

--skip-self-test

，doctor 还会运行自检：它会在一个一次性沙箱中写入、索引并搜索一条笔记，耗时数秒，可证明安装本身能够正常工作。当报告看起来正常但仍有问题时，请运行它。

Read the Report

阅读报告

json

{
  "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
}

Severity	Meaning	What to do
`error`	Will not go away without a fix	Offer the `command` ; if it is null, explain the evidence
`warning`	Needs attention, may recover on its own	Offer the `command` if there is one
`info`	Expected while work is in progress	Mention it; a running server finishes it, and the `command` finishes it now

Indexing catches up in the background. A duplicate, missing or extra search row is a

warning

while file indexing is still running, because the pass may clear it, and becomes an

error

once indexing has settled. If the report has only

info

findings, nothing is wrong. When no Basic Memory server is running, nothing indexes in the background, so offer the

command

on an

info

finding too.

Cloud projects are listed under

skipped_cloud_projects

: they are indexed on the server, and local commands cannot fix them.

json

{
  "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

下：它们在服务器上进行索引，本地命令无法修复这些问题。

Fix

修复

Summarize the findings for the user in plain words: which project, what is wrong, and what the fix does. Group findings that share a command.
Show each
```
command
```
exactly as doctor printed it and ask before running it.
```
bm reindex --search --full
```
re-reads every file in the project and can take a while on a large one.
Run the commands the user approves.
Run
```
bm doctor --skip-self-test --json
```
again and confirm the findings are gone.

When a finding has no

command

, do not invent one. Say what the evidence shows (for example, which files changed on disk while a newer save was waiting) and let the user decide.

用通俗语言向用户总结发现：哪个项目存在什么问题，以及该修复会做什么。将共用同一命令的发现归为一组。
完全按照 doctor 输出的形式显示每个
```
command
```
，并在运行前征求用户同意。
```
bm reindex --search --full
```
会重新读取项目中的每个文件，在大型项目中可能耗时较长。
运行用户批准的命令。
再次运行
```
bm doctor --skip-self-test --json
```
，确认这些发现已消失。

当某项发现没有

command

时，不要自行编造命令。说明证据所显示的内容（例如，磁盘上哪些文件发生了变化，而较新的保存操作仍在等待），并让用户自行决定。

Exit Codes

退出码

bm doctor

exits 0 when there are no errors and the self-test passed (or was skipped), and 1 otherwise. Warnings and info never fail it.

当没有错误且自检通过（或被跳过）时，

bm doctor

的退出码为 0；其他情况下为 1。

warning

和

info

永远不会导致命令失败。