memory-doctor — Claude Code skill: Basic Memory checks
The memory-doctor Claude Code skill checks local Basic Memory projects and explains its findings. It runs when search misses or repeats notes, or a save seems to have gone missing.
AGPL-3.0 249 installs ★ 4,660 updated 2026-10-24
npx skills add basicmachines-co/basic-memory --skill memory-doctor -a claude-codeWhat memory-doctor does
The skill runs bm doctor, interprets its project reports, and explains the issues it finds. The check reads data only. It shows suggested repair commands and runs them only after the user approves.
A shell with the bm or basic-memory command is required. The default check skips the self-test; run that test if the report is clean but the issue persists. It writes a note in a temporary sandbox, then indexes and searches for it. Cloud projects appear separately because local commands cannot repair them.
After approved repairs, the skill runs the check again. A full search reindex reads every project file and may take a while on a large project.
What it helps with
- find why search misses an existing note
- investigate duplicate search results
- check whether a saved note changed its file
- diagnose Basic Memory after a crash or interrupted import
- apply a suggested repair after approval
Example prompts for the agent
- Check Basic Memory: search misses a note that should be there.
- Check the
workproject and explain why search returns duplicates. - Run a check after an interrupted import and show the repair commands.
How to install memory-doctor
1Skills CLI (Vercel)
npx skills add basicmachines-co/basic-memory --skill memory-doctor -a claude-code2Manually: put the files in place
~/.claude/skills/memory-doctor/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/memory-doctor/
1Skills CLI (Vercel)
npx skills add basicmachines-co/basic-memory --skill memory-doctor -a codex2Manually: put the files in place
.agents/skills/memory-doctor/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add basicmachines-co/basic-memory --skill memory-doctor -a cursor2Manually: put the files in place
.cursor/skills/memory-doctor/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install basicmachines-co/basic-memory skills/memory-doctor2Manually: put the files in place
.github/skills/memory-doctor/SKILL.md1Skills CLI (Vercel)
npx skills add basicmachines-co/basic-memory --skill memory-doctor -a gemini-cli2Platform CLI
gemini skills install https://github.com/basicmachines-co/basic-memory --path skills/memory-doctorManually: put the files in place
.devin/skills/memory-doctor/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add basicmachines-co/basic-memory --skill memory-doctor -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about memory-doctor
How do I install memory-doctor in Claude Code?
Run npx skills add basicmachines-co/basic-memory --skill memory-doctor -a claude-code. The skill file is at ~/.claude/skills/memory-doctor/SKILL.md.
What does memory-doctor do?
It checks local Basic Memory projects with bm doctor, explains the results, and offers repair commands. It runs those commands only after the user agrees.
What does memory-doctor need to run?
It needs a shell with the bm or basic-memory command. Cloud projects are indexed on the server, so local commands cannot repair them.