@basicmemory/openclaw-basic-memory 0.24.1 → 1.0.0

package/skills/memory-reflect/SKILL.md

@@ -13,6 +13,17 @@ month, and puts it where someone will look for it.
 Inspired by sleep-time compute: memory forms best between working sessions,
 not during them.
 
+## 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
 
 - **Scheduled**: once or twice a day, or on a heartbeat
@@ -26,23 +37,23 @@ not during them.
 ```python
 # The last reflection is the checkpoint. Titles carry date and time, so the
 # newest sorts first.
-list_directory(dir_name="reflections", sort="title_desc", page_size=1)
+bm_list(path="reflections", sort="title_desc", page_size=1, project="<project>")
 
 # Everything changed since that date (json gives one row per note). With no
-# reflection yet, use timeframe="7d".
-recent_activity(timeframe="2026-10-13", output_format="json", page_size=50)
-# Ask for page=2, 3, ... until a page returns fewer than page_size rows.
+# reflection yet, use since="7d".
+bm_project(command="recent", since="2026-10-13", items=["note"], output_format="json", page_size=50, project="<project>")
+# Ask for page=2, 3, ... until has_more is false.
 
 # Read each changed note in full before judging it
-read_note(identifier="meetings/2026-10-14-launch-sync")
+bm_read(identifier="meetings/2026-10-14-launch-sync", project="<project>")
 ```
 
 Timeframes count whole days, so the window can overlap the last reflection.
 Skip notes it lists as `reviewed`, and notes you wrote in an earlier
 reflection, unless someone edited them since.
 
-`recent_activity` looks back at most a year. If the last reflection is older
-than that, use `timeframe="365d"` and record in this reflection that changes
+`bm_project(command="recent", project="<project>")` looks back at most a year. If the last reflection is older
+than that, use `since="365d"` and record in this reflection that changes
 before that window were not reviewed.
 
 ### 2. Decide what lasts
@@ -65,8 +76,8 @@ For each item, ask:
 Find the durable note for each item before writing anything:
 
 ```python
-search_notes(query="launch checklist owner")
-build_context(url="memory://projects/launch")
+bm_search(query="launch checklist owner", project="<project>")
+bm_context(identifier="memory://projects/launch", project="<project>")
 ```
 
 - **Say when it holds.** A fact with a date gets a qualifier (see
@@ -91,19 +102,20 @@ build_context(url="memory://projects/launch")
   checksum to the edit, so the edit applies only to the revision you read.
 
   ```python
-  note = read_note(identifier="Launch Plan", output_format="json")
-  edit_note(
+  note = bm_read(identifier="Launch Plan", output_format="json", project="<project>")
+  bm_edit(
       identifier="Launch Plan",
-      operation="replace_section",
+      command="replace_section",
       section="## Owners",
       content="- [owner] Maya owns the launch checklist",
       expected_checksum=note["checksum"],
+      project="<project>",
   )
   ```
 
   If the edit reports a checksum conflict, someone changed the note after you
   read it: read it again and decide again from the new text.
-- **The topic has no note**: create one with `write_note`, following
+- **The topic has no note**: create one with `bm_write`, following
   **memory-notes**: a clear title, observations with categories, and relations.
 - **Link back**: every consolidated fact names its source, e.g.
   `- derived_from [[2026-10-14 Launch Sync]]`, so a reader can check it.

package/skills/memory-research/SKILL.md

@@ -7,6 +7,17 @@ description: "Research an external subject on the web and synthesize it into a s
 
 Research an external subject, synthesize what you find, and create a structured Basic Memory entity — with the user's approval.
 
+## 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.
+
 ## Workflow
 
 ### Step 1: Web Research
@@ -36,8 +47,8 @@ Search for current information across multiple sources. Aim for 3-5 searches to
 Before proposing a new entity, search Basic Memory:
 
 ```python
-search_notes(query="Acme Corp")
-search_notes(query="acme")
+bm_search(query="Acme Corp", project="<project>")
+bm_search(query="acme", project="<project>")
 ```
 
 Try name variations — full name, abbreviation, acronym, domain name.
@@ -45,7 +56,7 @@ Try name variations — full name, abbreviation, acronym, domain name.
 If the entity already exists:
 - Report what you found in Basic Memory alongside your web research
 - Offer to update the existing note with new information
-- Use `edit_note` to append new observations or update outdated ones
+- Use `bm_edit` to append new observations or update outdated ones
 
 If the entity doesn't exist, proceed to evaluation.
 
@@ -109,7 +120,7 @@ After approval, create a structured note. Adapt the template to the entity type:
 #### Organization
 
 ```python
-write_note(
+bm_write(
   title="Acme Corp",
   directory="organizations",
   note_type="organization",
@@ -135,14 +146,15 @@ write_note(
 - [additional observations from research findings]
 
 ## Relations
-- [Link to related entities already in the knowledge graph]"""
+- [Link to related entities already in the knowledge graph]""",
+  project="<project>",
 )
 ```
 
 #### Person
 
 ```python
-write_note(
+bm_write(
   title="Jane Smith",
   directory="people",
   note_type="person",
@@ -163,14 +175,15 @@ write_note(
 - [source] Researched on YYYY-MM-DD
 
 ## Relations
-- works_at [[Organization]]"""
+- works_at [[Organization]]""",
+  project="<project>",
 )
 ```
 
 #### Technology
 
 ```python
-write_note(
+bm_write(
   title="Technology Name",
   directory="concepts",
   note_type="concept",
@@ -192,13 +205,14 @@ write_note(
 - [source] Researched on YYYY-MM-DD
 
 ## Relations
-- [Link to related concepts, tools, or projects in the knowledge graph]"""
+- [Link to related concepts, tools, or projects in the knowledge graph]""",
+  project="<project>",
 )
 ```
 
 Adapt these templates freely. The key elements are: note_type/tags parameters, an overview, structured details, observations with categories, and relations.
 
-If `write_note` reports similar existing notes, check whether one of them is this
+If `bm_write` reports similar existing notes, check whether one of them is this
 entity before keeping the new note; merge or link instead of duplicating.
 
 ### Step 6: Store Source Context
@@ -207,11 +221,12 @@ If the user provided context with their request, capture it in the entity:
 
 ```python
 # User said: "Acme Corp — saw their demo at the conference last week"
-edit_note(
+bm_edit(
   identifier="Acme Corp",
-  operation="insert_after_section",
+  command="insert_after_section",
   section="Observations",
-  content="- [context] Saw their demo at conference, week of 2026-02-17"
+  content="- [context] Saw their demo at conference, week of 2026-02-17",
+  project="<project>",
 )
 ```
 

package/skills/memory-schema/SKILL.md

@@ -7,6 +7,17 @@ description: "Manage Basic Memory schemas: find unschemaed notes, infer and edit
 
 Manage structured note types using Basic Memory's Picoschema system. Schemas define what fields a note type should have, making notes uniform, queryable, and validatable.
 
+## 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
 
 - **New note type emerging** — you notice several notes share the same structure (meetings, people, decisions)
@@ -112,12 +123,12 @@ settings:
 
 Look for clusters of notes that share structure but have no schema:
 
-1. **Search by type**: `search_notes(note_types=["meeting"])` — if many notes share a `type` but no `schema/Meeting.md` exists, it's a candidate.
+1. **Search by type**: `bm_search(note_types=["meeting"], project="<project>")` — if many notes share a `type` but no `schema/Meeting.md` exists, it's a candidate.
 
-2. **Infer a schema**: Use `schema_infer` to analyze existing notes and generate a suggested schema:
+2. **Infer a schema**: Use `bm_schema(command="infer", project="<project>")` to analyze existing notes and generate a suggested schema:
    ```python
-   schema_infer(note_type="Meeting")
-   schema_infer(note_type="Meeting", threshold=0.5)  # fields in 50%+ of notes
+   bm_schema(command="infer", note_type="Meeting", project="<project>")
+   bm_schema(command="infer", note_type="Meeting", threshold=0.5, project="<project>")  # fields in 50%+ of notes
    ```
    The threshold (0.0–1.0) controls how common a field must be to be included. Default is usually fine; lower it to catch rarer fields.
 
@@ -128,7 +139,7 @@ Look for clusters of notes that share structure but have no schema:
 Write the schema note to `schema/<EntityName>`:
 
 ```python
-write_note(
+bm_write(
   title="Meeting",
   directory="schema",
   note_type="schema",
@@ -150,7 +161,8 @@ Schema for meeting notes.
 ## Observations
 - [convention] Meeting notes live in memory/meetings/ or as daily entries
 - [convention] Always include date and topic
-- [convention] Action items should become tasks when complex"""
+- [convention] Action items should become tasks when complex""",
+  project="<project>",
 )
 ```
 
@@ -168,13 +180,13 @@ Check how well existing notes conform to their schema:
 
 ```python
 # Validate all notes of a type
-schema_validate(note_type="Meeting")
+bm_schema(command="validate", note_type="Meeting", project="<project>")
 
 # Validate a single note
-schema_validate(identifier="meetings/2026-02-10-standup")
+bm_schema(command="validate", identifier="meetings/2026-02-10-standup", project="<project>")
 ```
 
-**Important:** `schema_validate` checks for schema fields as **observation categories** in the note body — e.g., a `status` field expects `- [status] active` as an observation. Fields stored only in frontmatter metadata won't satisfy validation. To pass cleanly, include schema fields as both frontmatter values (for metadata search) and observations (for schema validation).
+**Important:** `bm_schema(command="validate", project="<project>")` checks for schema fields as **observation categories** in the note body — e.g., a `status` field expects `- [status] active` as an observation. Fields stored only in frontmatter metadata won't satisfy validation. To pass cleanly, include schema fields as both frontmatter values (for metadata search) and observations (for schema validation).
 
 Validation reports **missing required fields** (as observation categories, or relations
 for entity-reference fields) and **invalid enum values**. Undeclared observation categories
@@ -188,10 +200,10 @@ type-checked.
 
 ## Detecting Drift
 
-Over time, notes evolve and schemas lag behind. Use `schema_diff` to find divergence:
+Over time, notes evolve and schemas lag behind. Use `bm_schema(command="diff", project="<project>")` to find divergence:
 
 ```python
-schema_diff(note_type="Meeting")
+bm_schema(command="diff", note_type="Meeting", project="<project>")
 ```
 
 Diff reports:
@@ -203,15 +215,14 @@ Diff reports:
 
 When note structure changes:
 
-1. **Run diff** to see current state: `schema_diff(note_type="Meeting")`
-2. **Update the schema note** via `edit_note` with the `metadata` parameter. Top-level
+1. **Run diff** to see current state: `bm_schema(command="diff", note_type="Meeting", project="<project>")`
+2. **Update the schema note** via `bm_edit` with the `metadata` parameter. Top-level
    keys are replaced whole, so pass the complete updated `schema` map along with the new
    `version`:
    ```python
-   edit_note(
+   bm_edit(
      identifier="schema/Meeting",
-     operation="append",
-     content="",
+     command="set_metadata",
      metadata={
        "version": 2,
        "schema": {
@@ -221,10 +232,11 @@ When note structure changes:
          "decisions?(array)": "string, decisions made",
          "location?": "string, where it happened"
        }
-     }
+     },
+     project="<project>",
    )
    ```
-3. **Re-validate** to confirm existing notes still pass: `schema_validate(note_type="Meeting")`
+3. **Re-validate** to confirm existing notes still pass: `bm_schema(command="validate", note_type="Meeting", project="<project>")`
 4. **Fix outliers** — update notes that don't conform to the new schema
 
 ### Evolution Guidelines
@@ -238,10 +250,10 @@ When note structure changes:
 ## Workflow Summary
 
 ```
-1. Notice repeated note structure → infer schema (schema_infer)
-2. Review + create schema note   → write to schema/ (write_note)
-3. Validate existing notes       → check conformance (schema_validate)
-4. Fix outliers                  → edit non-conforming notes (edit_note)
-5. Periodically check drift      → detect divergence (schema_diff)
-6. Evolve schema as needed       → update schema note (edit_note)
+1. Notice repeated note structure → infer schema (bm_schema(command="infer", project="<project>"))
+2. Review + create schema note   → write to schema/ (bm_write)
+3. Validate existing notes       → check conformance (bm_schema(command="validate", project="<project>"))
+4. Fix outliers                  → edit non-conforming notes (bm_edit)
+5. Periodically check drift      → detect divergence (bm_schema(command="diff", project="<project>"))
+6. Evolve schema as needed       → update schema note (bm_edit)
 ```

package/skills/memory-tasks/SKILL.md

@@ -7,6 +7,17 @@ description: "Task management via Basic Memory schemas: create, track, and resum
 
 Manage work-in-progress using Basic Memory's schema system. Tasks are just notes with `type: Task` — they live in the knowledge graph, validate against a schema, and survive context compaction.
 
+## 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 multi-step work** (3+ steps, or anything that might outlast the context window)
@@ -42,10 +53,10 @@ settings:
 
 ## Creating a Task
 
-When work qualifies, create a task note. Use `write_note` with `note_type="Task"` and put queryable fields in `metadata`:
+When work qualifies, create a task note. Use `bm_write` with `note_type="Task"` and put queryable fields in `metadata`:
 
 ```python
-write_note(
+bm_write(
   title="Descriptive task name",
   directory="tasks",
   note_type="Task",
@@ -75,18 +86,19 @@ What future-you needs to pick up this work. Include:
 - Key file paths and repos involved
 - Decisions already made and why
 - What was tried and what worked/didn't
-- Where to look for related context"""
+- Where to look for related context""",
+  project="<project>",
 )
 ```
 
-**Why both frontmatter and observations?** Fields in `metadata` (stored as frontmatter) power `search_notes` with `metadata_filters`. Fields as observations (`- [status] active`) power `schema_validate`. Include queryable fields in both places for full coverage.
+**Why both frontmatter and observations?** Fields in `metadata` (stored as frontmatter) power `bm_search` with `filters`. Fields as observations (`- [status] active`) power `bm_schema(command="validate", project="<project>")`. Include queryable fields in both places for full coverage.
 
 ### Key Principles
 
 - **Steps are concrete and checkable** — "Implement X in file Y", not "figure out stuff"
 - **Context is for post-amnesia resumption** — Write it as if explaining to a smart person who knows nothing about what you've been doing
 - **Relations link to other entities** — `parent_task [[Other Task]]`, `related_to [[Some Note]]`
-- **Note types are normalized to snake_case** — `write_note(note_type="Task")` stores `type: task`, and `note_types=["Task"]` or `note_types=["task"]` both match it.
+- **Note types are normalized to snake_case** — `bm_write(note_type="Task", project="<project>")` stores `type: task`, and `note_types=["Task"]` or `note_types=["task"]` both match it.
 
 ## Resuming After Compaction
 
@@ -94,7 +106,7 @@ On session start or after compaction:
 
 1. **Search for active tasks:**
    ```python
-   search_notes(note_types=["task"], status="active")
+   bm_search(note_types=["task"], filters={"status": "active"}, project="<project>")
    ```
 
 2. **Read the task note** to get full context
@@ -122,15 +134,15 @@ edit. Two sessions often update the same task, for example in a pre-compaction
 flush; a revision conflict means the other one wrote first, so re-read before
 writing.
 
-Update frontmatter too, with the `metadata` parameter (empty `content` leaves the body alone):
+Update frontmatter too, with `command="set_metadata"` and the `metadata` parameter (the body stays unchanged):
 ```python
-task = read_note(identifier="tasks/descriptive-task-name", output_format="json")
-edit_note(
+task = bm_read(identifier="tasks/descriptive-task-name", output_format="json", project="<project>")
+bm_edit(
   identifier="tasks/descriptive-task-name",
-  operation="append",
-  content="",
+  command="set_metadata",
   metadata={"current_step": 3},
-  expected_checksum=task["checksum"]
+  expected_checksum=task["checksum"],
+  project="<project>",
 )
 ```
 
@@ -148,7 +160,7 @@ Add a brief summary of what was accomplished and any follow-up needed.
 
 When a compaction event is imminent:
 
-1. Find all active tasks: `search_notes(note_types=["task"], status="active")`
+1. Find all active tasks: `bm_search(note_types=["task"], filters={"status": "active"}, project="<project>")`
 2. For each, update:
    - `current_step` to reflect actual progress
    - `context` with everything needed to resume
@@ -161,14 +173,14 @@ With BM's schema system, tasks are fully queryable:
 
 | Query | What it finds |
 |-------|--------------|
-| `search_notes(note_types=["task"])` | All tasks |
-| `search_notes(note_types=["task"], status="active")` | Active tasks |
-| `search_notes(note_types=["task"], status="blocked")` | Blocked tasks |
-| `search_notes(note_types=["task"], metadata_filters={"assigned_to": "claude"})` | My tasks |
-| `search_notes("blockers", note_types=["task"])` | Tasks with blockers |
-| `search_notes(note_types=["task"], time_kind="due", valid_overlaps="[2026-10-14,2026-10-21)")` | Tasks with a step due this week |
-| `schema_validate(note_type="Task")` | Validate all tasks against schema |
-| `schema_diff(note_type="Task")` | Detect drift between schema and actual task notes |
+| `bm_search(note_types=["task"], project="<project>")` | All tasks |
+| `bm_search(note_types=["task"], filters={"status": "active"}, project="<project>")` | Active tasks |
+| `bm_search(note_types=["task"], filters={"status": "blocked"}, project="<project>")` | Blocked tasks |
+| `bm_search(note_types=["task"], filters={"assigned_to": "claude"}, project="<project>")` | My tasks |
+| `bm_search("blockers", note_types=["task"], project="<project>")` | Tasks with blockers |
+| `bm_search(note_types=["task"], time_kind="due", valid_overlaps="[2026-10-14,2026-10-21)", project="<project>")` | Tasks with a step due this week |
+| `bm_schema(command="validate", note_type="Task", project="<project>")` | Validate all tasks against schema |
+| `bm_schema(command="diff", note_type="Task", project="<project>")` | Detect drift between schema and actual task notes |
 
 ### Due Dates
 
@@ -189,4 +201,4 @@ also returns overdue items.
 - **Context > steps** — Steps tell you what to do; context tells you why and how
 - **Close finished tasks** — Don't leave completed work as `active`
 - **Link related tasks** — Use `parent_task [[X]]` or relations to connect related work
-- **Schema validation is your friend** — Run `schema_validate(note_type="Task")` periodically to catch incomplete tasks
+- **Schema validation is your friend** — Run `bm_schema(command="validate", note_type="Task", project="<project>")` periodically to catch incomplete tasks

package/tools/build-context.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
-import type { BmClient } from "../bm-client.ts"
+import { type BmClient, describeToolError } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 export function registerContextTool(
@@ -67,8 +67,15 @@ export function registerContextTool(
             const primary = result.primary_result
             sections.push(`## ${primary.title}\n${primary.content}`)
 
-            if (result.observations?.length > 0) {
-              const obs = result.observations
+            // The note body already contains its observations as
+            // "- [category] text" lines, so listing them again doubled the
+            // output. Only observations missing from the shown body (for
+            // example when the server truncates a long note) are listed.
+            const unseen = (result.observations ?? []).filter(
+              (o) => !primary.content?.includes(`[${o.category}] ${o.content}`),
+            )
+            if (unseen.length > 0) {
+              const obs = unseen
                 .map((o) => `- [${o.category}] ${o.content}`)
                 .join("\n")
               sections.push(`### Observations\n${obs}`)
@@ -78,7 +85,9 @@ export function registerContextTool(
               const rels = result.related_results
                 .map((r) => {
                   if (r.type === "relation") {
-                    return `- ${r.relation_type} → **${r.to_entity}**`
+                    return r.to_entity
+                      ? `- ${r.relation_type} → **${r.to_entity}**`
+                      : `- ${r.relation_type} → **${r.to_name ?? "unknown"}** (no note yet)`
                   }
                   const label = r.relation_type
                     ? `${r.relation_type} → **${r.title}**`
@@ -111,7 +120,7 @@ export function registerContextTool(
             content: [
               {
                 type: "text" as const,
-                text: `Failed to build context for "${params.url}". Check logs for details.`,
+                text: `Failed to build context for "${params.url}": ${describeToolError(err)}`,
               },
             ],
             details: {

package/tools/delete-note.ts

@@ -1,6 +1,6 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
-import type { BmClient } from "../bm-client.ts"
+import { type BmClient, describeNoteError } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 export function registerDeleteTool(
@@ -55,7 +55,7 @@ export function registerDeleteTool(
             content: [
               {
                 type: "text" as const,
-                text: `Failed to delete "${params.identifier}". It may not exist.`,
+                text: `Failed to delete "${params.identifier}": ${describeNoteError(err)}`,
               },
             ],
             details: {

package/tools/edit-note.ts

@@ -1,6 +1,10 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
-import type { BmClient } from "../bm-client.ts"
+import {
+  type BmClient,
+  describeNoteError,
+  type EditOperation,
+} from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 export function registerEditTool(
@@ -13,8 +17,11 @@ export function registerEditTool(
       label: "Edit Note",
       description:
         "Incrementally edit an existing note in the Basic Memory knowledge graph. " +
-        "Supports append, prepend, find/replace, and section replacement " +
-        "without rewriting the entire note. The result returns the note's " +
+        "Supports append, prepend, find/replace, replacing a section, and inserting " +
+        "next to a section heading, without rewriting the entire note. To add to a " +
+        "specific section (for example a new observation), use insert_after_section " +
+        "with that heading; append always adds to the very end of the note. " +
+        "The result returns the note's " +
         "permalink and file_path: cite those exact values when confirming " +
         "the edit — never report a save that no tool call performed.",
       parameters: Type.Object({
@@ -27,11 +34,15 @@ export function registerEditTool(
             Type.Literal("prepend"),
             Type.Literal("find_replace"),
             Type.Literal("replace_section"),
+            Type.Literal("insert_before_section"),
+            Type.Literal("insert_after_section"),
           ],
           {
             description:
-              "Edit operation: append (add to end), prepend (add to start), " +
-              "find_replace (replace matching text), replace_section (replace a heading section)",
+              "Edit operation: append (add to end of note), prepend (add to start), " +
+              "find_replace (replace matching text), replace_section (replace a heading section), " +
+              "insert_after_section (add directly below a heading, at the top of its section), " +
+              "insert_before_section (add directly above a heading, at the end of the section before it)",
           },
         ),
         content: Type.String({
@@ -45,7 +56,8 @@ export function registerEditTool(
         section: Type.Optional(
           Type.String({
             description:
-              "Section heading to replace (required for replace_section)",
+              "Section heading, e.g. 'Observations' (required for replace_section, " +
+              "insert_before_section and insert_after_section; not allowed with other operations)",
           }),
         ),
         expected_replacements: Type.Optional(
@@ -74,7 +86,7 @@ export function registerEditTool(
         _toolCallId: string,
         params: {
           identifier: string
-          operation: "append" | "prepend" | "find_replace" | "replace_section"
+          operation: EditOperation
           content: string
           find_text?: string
           section?: string
@@ -103,7 +115,7 @@ export function registerEditTool(
             content: [
               {
                 type: "text" as const,
-                text: `Note updated: ${note.title} (${note.permalink})`,
+                text: `Note updated: ${note.title} (${note.permalink})\nFile: ${note.file_path}`,
               },
             ],
             details: {
@@ -116,13 +128,14 @@ export function registerEditTool(
           }
         } catch (err) {
           log.error("edit_note failed", err)
+          // Trigger: any edit failure, including invalid arguments and
+          //   checksum conflicts, not only a missing note.
+          // Why: a blanket "may not exist" sent agents hunting for the wrong
+          //   problem; the server's message says what to change.
+          // Outcome: the agent sees the server's reason verbatim.
+          const text = `Failed to edit note "${params.identifier}": ${describeNoteError(err)}`
           return {
-            content: [
-              {
-                type: "text" as const,
-                text: `Failed to edit note "${params.identifier}". It may not exist.`,
-              },
-            ],
+            content: [{ type: "text" as const, text }],
             details: {
               identifier: params.identifier,
               operation: params.operation,

package/tools/list-memory-projects.ts

@@ -1,6 +1,10 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
-import type { BmClient, ProjectListResult } from "../bm-client.ts"
+import {
+  type BmClient,
+  describeToolError,
+  type ProjectListResult,
+} from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 function normalizeProject(project: ProjectListResult) {
@@ -102,7 +106,7 @@ export function registerProjectListTool(
             content: [
               {
                 type: "text" as const,
-                text: "Failed to list Basic Memory projects. Is Basic Memory running? Check logs for details.",
+                text: `Failed to list Basic Memory projects: ${describeToolError(err)}`,
               },
             ],
             details: {