@basicmemory/openclaw-basic-memory 0.24.1 → 1.0.0

package/skills/memory-capture/SKILL.md

@@ -7,6 +7,17 @@ description: "Capture a working thread's current state into one coherent Basic M
 
 Capture the gist of a working thread — the decisions made, insights surfaced, and context built — into a single coherent Basic Memory note that reflects where the thread has landed.
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## Purpose
 
 A thread has a beginning, middle, and end. Things change as the conversation progresses: an early decision gets revised, a problem looks different in light of new information, a trade-off is settled differently than it first seemed. When this skill is invoked, capture the **current state of understanding**, not the history of how it got there.
@@ -33,31 +44,31 @@ To rewrite the same note on re-capture instead of duplicating, key the note to a
 
 > **Example (hosts with a JSONL transcript):** some agents write a per-session transcript whose filename is a stable session UUID. If yours does, you can derive the id from the most-recently-modified transcript file and use it as `thread_id`. This is optional — only do it if your host actually exposes such a transcript.
 
-**If no stable id is available**, match the existing note by title/topic instead: search for a note covering the same thread (`search_notes(query="<topic>")`), and if you find the one this thread already produced, rewrite it. Omit `thread_id` and rely on a consistent title.
+**If no stable id is available**, match the existing note by title/topic instead: search for a note covering the same thread (`bm_search(query="<topic>", project="<project>")`), and if you find the one this thread already produced, rewrite it. Omit `thread_id` and rely on a consistent title.
 
 ## Decision Flow
 
 1. **Determine the thread key.** Use a stable session/thread id if your agent exposes one; otherwise plan to match by title/topic.
 2. **Search Basic Memory** for the existing thread note.
-   - With a thread id, use `metadata_filters` (not `query`) — full-text query doesn't reliably match YAML frontmatter custom fields:
+   - With a thread id, use `filters` (not `query`) — full-text query doesn't reliably match YAML frontmatter custom fields:
      ```python
-     search_notes(
-         metadata_filters={"thread_id": "<thread-id>"},
+     bm_search(
+         filters={"thread_id": "<thread-id>"},
          project="<project>"
      )
      ```
    - Without one, search by topic and identify the note this thread already produced:
      ```python
-     search_notes(query="<thread topic>", project="<project>")
+     bm_search(query="<thread topic>", project="<project>")
      ```
 3. **If a match is found:**
    - Read the existing note as JSON (use the full permalink returned by search) and keep its `checksum`
    - Synthesize a new version that integrates the latest understanding from the conversation
-   - Overwrite via `write_note` with `overwrite=True` and `expected_checksum` set to that checksum (same title, same `thread_id` if used, same directory). A `NOTE_REVISION_CONFLICT` error means another session changed the note since you read it: read it again and re-synthesize
+   - Overwrite via `bm_write` with `overwrite=True` and `expected_checksum` set to that checksum using the returned `file_path` as `identifier` (same `thread_id` if used). A `REVISION_CONFLICT` error means another session changed the note since you read it: read it again and re-synthesize
 4. **If no match is found:**
    - Synthesize the note from the conversation
-   - If you have a thread id, pass `metadata={"thread_id": "<thread-id>"}` to `write_note` (it surfaces as a custom frontmatter field)
-   - Save it. If `write_note` lists similar existing notes, check whether one of them is this thread's note before keeping the new one
+   - If you have a thread id, pass `metadata={"thread_id": "<thread-id>"}` to `bm_write` (it surfaces as a custom frontmatter field)
+   - Save it. If `bm_write` lists similar existing notes, check whether one of them is this thread's note before keeping the new one
 
 ## Synthesis Rules
 
@@ -125,23 +136,23 @@ The title should reflect the thread's topic. On update, the title can be refined
 ## MCP Tools Used
 
 ```python
-# Find existing thread note by thread id (use metadata_filters, not query)
-search_notes(
-    metadata_filters={"thread_id": "<thread-id>"},
+# Find existing thread note by thread id (use filters, not query)
+bm_search(
+    filters={"thread_id": "<thread-id>"},
     project="<project>"
 )
 
 # Or, without a thread id, find it by topic
-search_notes(query="<thread topic>", project="<project>")
+bm_search(query="<thread topic>", project="<project>")
 
 # Read existing thread note (use the full permalink from search results)
-read_note(
+bm_read(
     identifier="<full-permalink>",
     project="<project>"
 )
 
 # Create
-write_note(
+bm_write(
     title="<title>",
     content="<markdown body — frontmatter is generated from title/tags/metadata>",
     directory="<folder>",
@@ -151,11 +162,11 @@ write_note(
 )
 
 # Overwrite an existing note (same path), only the revision you read
-existing = read_note(identifier="<full-permalink>", output_format="json", project="<project>")
-write_note(
-    title="<same title>",
+existing = bm_read(identifier="<full-permalink>", output_format="json", project="<project>")
+bm_write(
+    identifier=existing["file_path"],
+    title="<updated title>",
     content="<new content>",
-    directory="<same folder>",
     tags=["..."],
     metadata={"thread_id": "<same thread-id>"},  # omit if no stable id
     overwrite=True,

package/skills/memory-comark/SKILL.md

@@ -19,6 +19,17 @@ The full vocabulary, every prop, and every data grammar are in
 [references/components.md](references/components.md). Read it before using a
 component you have not used before.
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## Pick a component
 
 Most notes need only these. The reference has the rest (39 in total).
@@ -138,13 +149,13 @@ Semantics to state honestly in the surrounding prose:
 
 ### Check the rendered result before you quote it
 
-In Basic Memory Cloud, `read_note(view="text")` returns the note as a reader
+In Basic Memory Cloud, `bm_read(identifier="<note>", view="text", project="<project>")` returns the note as a reader
 sees it: every component as plain Markdown, with live queries run now. Read it
 back after writing a live view and confirm the view has rows before you state a
 number in prose. A query over a field no note has renders an empty view.
 
 Elsewhere, only the browser runs the query, so run the equivalent read yourself
-(for example `search_notes` with metadata filters; see the
+(for example `bm_search` with metadata filters; see the
 memory-metadata-search skill).
 
 A live chart's body is its **snapshot**: the rows readers see when live data
@@ -154,7 +165,7 @@ as a snapshot in prose and keep them in the chart's row grammar.
 
 ## Edit a note that already has components
 
-- Change one component with `edit_note` (`find_replace` on its directive line or
+- Change one component with `bm_edit` (`find_replace` on its directive line or
   rows). Do not rewrite the whole note to change one value.
 - The rich editor normalizes formatting when a person edits the note: attribute
   order changes and YAML blocks come back as JSON. Values survive; do not fight
@@ -168,9 +179,9 @@ as a snapshot in prose and keep them in the chart's row grammar.
 ## When a component shows an error
 
 A broken component renders a coded problem and a fix inside its own frame; the
-rest of the note still renders. In Basic Memory Cloud, `write_note` and
-`edit_note` list these problems under **Component problems** in their result
-(they never block the write), so fix them right away with `edit_note`. `comark(7)` in the manual
+rest of the note still renders. In Basic Memory Cloud, `bm_write` and
+`bm_edit` list these problems under **Component problems** in their result
+(they never block the write), so fix them right away with `bm_edit`. `comark(7)` in the manual
 (`memory://man/comark(7)`) is a quick reference to the syntax and codes. The
 codes you will meet most:
 

package/skills/memory-continue/SKILL.md

@@ -7,6 +7,17 @@ description: "Resume prior work by rebuilding context from the Basic Memory grap
 
 Resume previous work by reconstructing context from the Basic Memory knowledge graph, so the assistant can pick up across sessions instead of starting cold.
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## When to Use
 
 - Starting a new session and you need to pick up where you left off
@@ -21,31 +32,32 @@ Resume previous work by reconstructing context from the Basic Memory knowledge g
 
 If it's unclear, ask:
 - What topic or project should you resume?
-- What timeframe matters?
+- What since matters?
 - Any specific aspect to focus on?
 
 ### 2. Gather Context with MCP Tools
 
-**Known topic — use `build_context`.** Navigate the graph from a starting point, following relations outward:
+**Known topic — use `bm_context`.** Navigate the graph from a starting point, following relations outward:
 
 ```python
-build_context(
-    url="memory://topic-or-note-name",
+bm_context(
+    identifier="memory://topic-or-note-name",
     depth=2,           # how many relation hops to follow
-    timeframe="7d",    # bias toward recent changes
+    since="7d",        # only include changes in this window
+    project="<project>",
 )
 ```
 
-**No clear starting point — use `recent_activity`.** See what's changed and let it surface the thread:
+**No clear starting point — use `bm_project(command="recent", project="<project>")`.** See what's changed and let it surface the thread:
 
 ```python
-recent_activity(timeframe="3d", depth=1)
+bm_project(command="recent", since="3d", project="<project>")
 ```
 
-**Looking for something specific — use `search_notes`.** Find candidate notes by keyword:
+**Looking for something specific — use `bm_search`.** Find candidate notes by keyword:
 
 ```python
-search_notes(query="async client refactor", page_size=10)
+bm_search(query="async client refactor", page_size=10, project="<project>")
 ```
 
 ### 3. Read the Key Notes
@@ -53,17 +65,17 @@ search_notes(query="async client refactor", page_size=10)
 Once you've identified the relevant notes, read them in full:
 
 ```python
-read_note(identifier="note-title-or-permalink")
+bm_read(identifier="note-title-or-permalink", project="<project>")
 ```
 
 For long notes, pick before you pay for bodies. `compact=True` drops bodies from
-search results (and observations from `build_context`), and a line range or a
+search results (and observations from `bm_context`), and a line range or a
 section reads only the part you need:
 
 ```python
-search_notes(query="async client refactor", compact=True)
-read_note(identifier="note-title-or-permalink", start_line=120, end_line=180)
-cat(identifier="note-title-or-permalink", section="Status")
+bm_search(query="async client refactor", compact=True, project="<project>")
+bm_read(identifier="note-title-or-permalink", start_line=120, end_line=180, project="<project>")
+bm_read(identifier="note-title-or-permalink", section="Status", project="<project>")
 ```
 
 ### 4. Present Context to the User
@@ -76,7 +88,7 @@ Summarize what you found, incrementally:
 
 ## Memory URL Reference
 
-`build_context` and `read_note` both accept `memory://` URLs, which address notes by permalink and support wildcards for gathering groups of notes.
+`bm_context` and `bm_read` both accept `memory://` URLs. `bm_read` resolves one exact note; use `bm_context` for wildcard patterns that gather groups of notes.
 
 ```
 memory://note-title            # a single note by permalink
@@ -89,7 +101,7 @@ Use a specific note URL to anchor on one starting point; use a wildcard to pull
 
 ## Timeframe Reference
 
-`build_context` and `recent_activity` accept natural-language timeframes:
+`bm_context` and `bm_project(command="recent", project="<project>")` accept natural-language timeframes:
 
 | Timeframe | Meaning |
 |-----------|---------|
@@ -106,10 +118,10 @@ Use a specific note URL to anchor on one starting point; use a wildcard to pull
 
 ```python
 # 1. Read the spec / project note
-read_note(identifier="SPEC-24: Postgres Database Migration")
+bm_read(identifier="SPEC-24: Postgres Database Migration", project="<project>")
 
 # 2. Pull in related context and recent changes via the graph
-build_context(url="memory://SPEC-24*", timeframe="7d")
+bm_context(identifier="memory://SPEC-24*", since="7d", project="<project>")
 ```
 
 Then summarize: the goals, what's completed, what's pending, and any blockers or open decisions.
@@ -118,10 +130,10 @@ Then summarize: the goals, what's completed, what's pending, and any blockers or
 
 ```python
 # 1. Check recent activity
-recent_activity(timeframe="3d")
+bm_project(command="recent", since="3d", project="<project>")
 
 # 2. Read notes from the recent sessions it surfaces
-read_note(identifier="relevant-note")
+bm_read(identifier="relevant-note", project="<project>")
 ```
 
 Then list the modified notes with brief descriptions and ask which thread to dive into.
@@ -130,10 +142,10 @@ Then list the modified notes with brief descriptions and ask which thread to div
 
 ```python
 # 1. Find the topic
-search_notes(query="topic keywords")
+bm_search(query="topic keywords", project="<project>")
 
 # 2. Build context from the best match, following its relations
-build_context(url="memory://found-note-permalink", depth=2)
+bm_context(identifier="memory://found-note-permalink", depth=2, project="<project>")
 ```
 
 Then present the full picture — the note plus its connected context.
@@ -143,16 +155,24 @@ Then present the full picture — the note plus its connected context.
 Project names are user-specific. To discover what's available before scoping a search or `memory://` URL:
 
 ```python
-list_memory_projects()
+bm_project(command="list")
 ```
 
-In multi-project setups, prefix a `memory://` URL with the project name (e.g. `memory://research/papers/crdt`) to scope it.
+A qualified `memory://` URL (e.g. `memory://research/papers/crdt`) must agree
+with `project`; the prefix does not replace that required parameter.
+
+For an explicitly broader search, use one of these scopes instead:
+
+```python
+bm_search(query="topic keywords", projects=["research", "team/engineering"])
+bm_search(query="topic keywords", all_projects=True)
+```
 
 ## Guidelines
 
-1. **Start broad, then narrow.** Get an overview with `recent_activity` or a wildcard `build_context`, then drill into specific notes.
+1. **Start broad, then narrow.** Get an overview with `bm_project(command="recent", project="<project>")` or a wildcard `bm_context`, then drill into specific notes.
 2. **Present incrementally.** Share what you find as you go rather than holding everything until the end.
-3. **Follow relations.** The graph's connections are the point — `build_context` with `depth` surfaces context you wouldn't find by reading one note.
-4. **Check multiple projects.** Specs may live separately from implementation notes; discover projects with `list_memory_projects`.
+3. **Follow relations.** The graph's connections are the point — `bm_context` with `depth` surfaces context you wouldn't find by reading one note.
+4. **Check multiple projects.** Specs may live separately from implementation notes; discover projects with `bm_project(command="list")`.
 5. **Confirm understanding.** Verify the reconstructed context is what the user actually needs before acting on it.
 6. **Capture new progress.** As the resumed work advances, write it back to the graph (see the **memory-notes** skill) so the next session can continue too.

package/skills/memory-curate/SKILL.md

@@ -9,6 +9,17 @@ Maintain a healthy, well-connected knowledge graph. As notes accumulate, it pays
 
 This skill curates the **knowledge graph** — the notes, relations, and tags that make up the knowledge base. (For the notes' content — splitting bloated notes, consolidating scattered facts, retiring stale entries — see **memory-defrag**.)
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## When to Use
 
 - Asked to organize, clean up, or improve the knowledge base
@@ -26,12 +37,12 @@ Orphans have no relations to other notes — they're islands in the graph.
 
 ```python
 # List notes, then read each to inspect its Relations section
-search_notes(query="*", search_type="text", page_size=50)
-read_note(identifier="note-to-check")
+bm_search(query="*", mode="text", page_size=50, project="<project>")
+bm_read(identifier="note-to-check", project="<project>")
 # Orphans have an empty (or missing) Relations section
 ```
 
-`query="*"` lists everything only with `search_type="text"`. A note whose body
+`query="*"` lists everything only with `mode="text"`. A note whose body
 links to other notes, with wikilinks or ordinary Markdown links, is not an
 orphan even without a Relations section.
 
@@ -47,9 +58,9 @@ If the `bm` CLI is available, `bm orphans` lists notes with no relations in one
 Analyze a note's content and propose meaningful connections.
 
 ```python
-read_note(identifier="note-to-analyze")
+bm_read(identifier="note-to-analyze", project="<project>")
 # Pull out key terms, then search for related notes
-search_notes(query="key terms from the note")
+bm_search(query="key terms from the note", project="<project>")
 ```
 
 Suggest relations based on shared topics, complementary content (problem/solution,
@@ -67,14 +78,15 @@ question/answer), sequence (part 1 → part 2), or hierarchy (parent concept →
 
 Custom relation types are fine — use whatever verb is descriptive.
 
-Add a confirmed relation with `edit_note`:
+Add a confirmed relation with `bm_edit`:
 
 ```python
-edit_note(
+bm_edit(
     identifier="API Design Decisions",
-    operation="insert_after_section",
+    command="insert_after_section",
     section="Relations",
     content="- depends_on [[Rate Limiter]]",
+    project="<project>",
 )
 ```
 
@@ -82,10 +94,11 @@ edit_note(
 `## Relations`. Then append the section instead:
 
 ```python
-edit_note(
+bm_edit(
     identifier="API Design Decisions",
-    operation="append",
+    command="append",
     content="\n## Relations\n- depends_on [[Rate Limiter]]",
+    project="<project>",
 )
 ```
 
@@ -94,7 +107,7 @@ edit_note(
 Find notes that may cover the same ground.
 
 ```python
-search_notes(query="topic keywords")
+bm_search(query="topic keywords", project="<project>")
 # Compare results for: similar titles, overlapping observations,
 # shared tags, close-together timestamps
 ```
@@ -107,36 +120,38 @@ search_notes(query="topic keywords")
 
 ```python
 # Point an older note at the one that replaces it
-edit_note(
+bm_edit(
     identifier="DB Schema v1",
-    operation="insert_after_section",
+    command="insert_after_section",
     section="Relations",
     content="- updates [[DB Schema v2]]",
+    project="<project>",
 )
 ```
 
 ### 4. Folder Organization Review
 
 ```python
-list_directory(dir_name="/", depth=3)
+bm_find(path="/", depth=3, project="<project>")
 ```
 
 Look for overcrowded folders, single-note folders, inconsistent naming, and notes
 that belong elsewhere. Suggest grouping related notes into topic folders, adding
 subfolders for large categories, and a consistent naming convention. Move misplaced
-notes with `move_note`. By default the permalink stays the same after a move, so links keep resolving. Projects with `update_permalinks_on_move` enabled rewrite it from the new path.
+notes with `bm_move`. By default the permalink stays the same after a move, so links keep resolving. Projects with `update_permalinks_on_move` enabled rewrite it from the new path.
 
 ```python
-move_note(
+bm_move(
     identifier="API Design Decisions",
-    destination_path="architecture/api-design-decisions.md",
+    destination="architecture/api-design-decisions.md",
+    project="<project>",
 )
 ```
 
 ### 5. Tag Consistency
 
 ```python
-search_notes(query="*", search_type="text", page_size=100)
+bm_search(query="*", mode="text", page_size=100, project="<project>")
 # Inspect tag patterns across results
 ```
 
@@ -151,7 +166,7 @@ Look for:
 After finding a cluster of related notes, build a navigation hub.
 
 ```python
-write_note(
+bm_write(
     title="Architecture Decisions Index",
     directory="indexes",
     tags=["architecture", "index"],
@@ -174,6 +189,7 @@ A hub linking architecture-related decisions and patterns.
 
 ## Relations
 - indexes [[Architecture]]""",
+    project="<project>",
 )
 ```
 
@@ -182,19 +198,19 @@ A hub linking architecture-related decisions and patterns.
 Find notes lacking structure and fill them in.
 
 ```python
-read_note(identifier="sparse-note")
+bm_read(identifier="sparse-note", project="<project>")
 ```
 
 If the note is missing an Observations section, suggest categories. If it has no
 Relations, suggest links. If it has no tags, suggest relevant ones. If it lacks
-context, suggest adding background. Apply with `edit_note`.
+context, suggest adding background. Apply with `bm_edit`.
 
 ## Curation Workflows
 
 Scale the pass to the request. A health check reports orphans, likely duplicates,
-recent activity (`recent_activity`), and folder distribution. A deep session works
+recent activity (`bm_project(command="recent", project="<project>")`), and folder distribution. A deep session works
 through the capabilities above in whatever order the findings suggest. A topic pass
-maps one subject with `search_notes` and `build_context`, fills the gaps it finds, and
+maps one subject with `bm_search` and `bm_context`, fills the gaps it finds, and
 ends with a hub note.
 
 ## Best Practices
@@ -204,7 +220,7 @@ ends with a hub note.
 3. **Preserve permalinks.** Changing a permalink breaks inbound `memory://` links. Moves keep the permalink by default (unless the project enables `update_permalinks_on_move`).
 4. **Explain suggestions.** Say *why* a relation or merge makes sense.
 5. **Respect the existing system.** Enhance the user's organization — don't impose a new taxonomy.
-6. **Show the graph.** Use `build_context` to help the user see how notes connect.
+6. **Show the graph.** Use `bm_context` to help the user see how notes connect.
 
 ## Example Conversations
 

package/skills/memory-defrag/SKILL.md

@@ -10,6 +10,17 @@ time notes grow past their topic, the same fact lands in several places, old
 facts contradict new ones, and finished work lingers. Defrag fixes the content;
 **memory-curate** handles links, relations, and tags.
 
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
+
 ## When to Run
 
 - **Periodic**: weekly or every other week
@@ -25,18 +36,18 @@ Walk the whole project, not just recent changes. Stale content is usually in
 notes nobody touched lately.
 
 ```python
-# Every folder and note. Ask for page=2, 3, ... until a page returns fewer
-# than page_size entries.
-list_directory(dir_name="/", depth=10, page_size=200)
+# Every folder and note within depth 10. Page until has_more is false;
+# descend into deeper folders separately if the project has them.
+bm_find(path="/", depth=10, page_size=100, project="<project>")
 
 # Recently busy notes, to look at first
-recent_activity(timeframe="30d", output_format="json", page_size=50)
+bm_project(command="recent", since="30d", output_format="json", page_size=50, project="<project>")
 
 # Notes on one topic, to spot overlap
-search_notes(query="launch plan")
+bm_search(query="launch plan", project="<project>")
 
 # Commitments due on or before today: finished work that lingers, or overdue items
-search_notes(time_kind="due", valid_overlaps="(,2026-10-14]")
+bm_search(time_kind="due", valid_overlaps="(,2026-10-14]", project="<project>")
 ```
 
 Read every note you might change, in full. For each, note its topic, size, last
@@ -105,7 +116,7 @@ status: proposed
 - Make one change at a time. Read each note as JSON before you edit it and pass
   its checksum as `expected_checksum`, so the edit applies only to the revision
   you read; on a checksum conflict, read again and recheck the plan line. Keep
-  relations pointing at the right note after a split or move (`move_note` keeps
+  relations pointing at the right note after a split or move (`bm_move` keeps
   links working; a new note needs links added).
 
 ### 5. Record what was done

package/skills/memory-doctor/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: memory-doctor
+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."
+---
+
+# 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
+}
+```
+
+| 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.
+
+## Fix
+
+1. 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.
+2. 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.
+3. Run the commands the user approves.
+4. 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.
+
+## 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.