# Memory Doctor

Check local Basic Memory projects with bm doctor, explain the findings, and run the...

- Repository: https://github.com/basicmachines-co/basic-memory (4440 stars)
- Category: Writing
- License: AGPL-3.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add basicmachines-co/basic-memory --skill memory-doctor -g -a claude-code -y`
Codex: `npx skills add basicmachines-co/basic-memory --skill memory-doctor -g -a codex -y`
Cursor: `npx skills add basicmachines-co/basic-memory --skill memory-doctor -g -a cursor -y`
Gemini CLI: `npx skills add basicmachines-co/basic-memory --skill memory-doctor -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add basicmachines-co/basic-memory`

## Description

Check local Basic Memory projects with bm doctor, explain the findings, and run the suggested fixes once the user agrees. Use when search misses or repeats notes, or a save looks lost.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

## 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

## 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.

## 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
}
```

The rest: https://github.com/basicmachines-co/basic-memory/blob/HEAD/skills/memory-doctor/SKILL.md