@basicmemory/openclaw-basic-memory 0.24.0 → 1.0.0

package/dist/tools/build-context.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerContextTool(api, client) {
     api.registerTool({
@@ -42,8 +43,13 @@ export function registerContextTool(api, client) {
                 for (const result of ctx.results) {
                     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}`);
@@ -52,7 +58,9 @@ export function registerContextTool(api, client) {
                         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}**`
@@ -85,7 +93,7 @@ export function registerContextTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: `Failed to build context for "${params.url}". Check logs for details.`,
+                            text: `Failed to build context for "${params.url}": ${describeToolError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/delete-note.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerDeleteTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/delete-note.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeNoteError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerDeleteTool(api, client) {
     api.registerTool({
@@ -38,7 +39,7 @@ export function registerDeleteTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: `Failed to delete "${params.identifier}". It may not exist.`,
+                            text: `Failed to delete "${params.identifier}": ${describeNoteError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/edit-note.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerEditTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/edit-note.js

@@ -1,12 +1,16 @@
 import { Type } from "@sinclair/typebox";
+import { describeNoteError, } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerEditTool(api, client) {
     api.registerTool({
         name: "edit_note",
         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({
@@ -18,9 +22,13 @@ export function registerEditTool(api, client) {
                 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)",
+                description: "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({
                 description: "New content to add or replace with",
@@ -29,7 +37,8 @@ export function registerEditTool(api, client) {
                 description: "Text to find (required for find_replace)",
             })),
             section: Type.Optional(Type.String({
-                description: "Section heading to replace (required for replace_section)",
+                description: "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(Type.Number({
                 description: "Expected replacement count for find_replace (default: 1)",
@@ -55,7 +64,7 @@ export function registerEditTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: `Note updated: ${note.title} (${note.permalink})`,
+                            text: `Note updated: ${note.title} (${note.permalink})\nFile: ${note.file_path}`,
                         },
                     ],
                     details: {
@@ -69,13 +78,14 @@ export function registerEditTool(api, client) {
             }
             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",
-                            text: `Failed to edit note "${params.identifier}". It may not exist.`,
-                        },
-                    ],
+                    content: [{ type: "text", text }],
                     details: {
                         identifier: params.identifier,
                         operation: params.operation,

package/dist/tools/list-memory-projects.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerProjectListTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/list-memory-projects.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError, } from "../bm-client.js";
 import { log } from "../logger.js";
 function normalizeProject(project) {
     return {
@@ -88,7 +89,7 @@ export function registerProjectListTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            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: {

package/dist/tools/list-workspaces.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerWorkspaceListTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/list-workspaces.js

@@ -1,15 +1,15 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError, } from "../bm-client.js";
 import { log } from "../logger.js";
 function formatWorkspace(ws, idx) {
-    const subscription = ws.has_active_subscription ? "active" : "none";
     return (`${idx + 1}. **${ws.name}**\n` +
-        `   Type: ${ws.workspace_type} | Role: ${ws.role} | Subscription: ${subscription}`);
+        `   Type: ${ws.workspace_type ?? "unknown"}`);
 }
 export function registerWorkspaceListTool(api, client) {
     api.registerTool({
         name: "list_workspaces",
         label: "List Workspaces",
-        description: "List all Basic Memory workspaces (personal and organization) accessible to this user. " +
+        description: "List workspaces represented by accessible Basic Memory projects. " +
             "Use it to find the workspace to pass to list_memory_projects when the same " +
             "project name may exist in more than one workspace.",
         parameters: Type.Object({}),
@@ -51,7 +51,7 @@ export function registerWorkspaceListTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: "Failed to list workspaces. Is Basic Memory running? Check logs for details.",
+                            text: `Failed to list workspaces: ${describeToolError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/move-note.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerMoveTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/move-note.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeNoteError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerMoveTool(api, client) {
     api.registerTool({
@@ -41,7 +42,7 @@ export function registerMoveTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: `Failed to move "${params.identifier}". It may not exist.`,
+                            text: `Failed to move "${params.identifier}": ${describeNoteError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/read-note.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerReadTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/read-note.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeNoteError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerReadTool(api, client) {
     api.registerTool({
@@ -57,7 +58,7 @@ export function registerReadTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: `Could not read note "${params.identifier}". It may not exist yet.`,
+                            text: `Could not read note "${params.identifier}": ${describeNoteError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/schema-diff.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerSchemaDiffTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/schema-diff.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerSchemaDiffTool(api, client) {
     api.registerTool({
@@ -67,7 +68,7 @@ export function registerSchemaDiffTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: "Schema diff failed. Check logs for details.",
+                            text: `Schema diff failed: ${describeToolError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/schema-infer.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerSchemaInferTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/schema-infer.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerSchemaInferTool(api, client) {
     api.registerTool({
@@ -51,7 +52,7 @@ export function registerSchemaInferTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: "Schema inference failed. Check logs for details.",
+                            text: `Schema inference failed: ${describeToolError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/schema-validate.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerSchemaValidateTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/schema-validate.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerSchemaValidateTool(api, client) {
     api.registerTool({
@@ -58,7 +59,7 @@ export function registerSchemaValidateTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: "Schema validation failed. Check logs for details.",
+                            text: `Schema validation failed: ${describeToolError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/search-notes.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerSearchTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/search-notes.js

@@ -1,5 +1,9 @@
 import { Type } from "@sinclair/typebox";
+import { describeToolError, searchResultText, } from "../bm-client.js";
 import { log } from "../logger.js";
+// Long enough to show a whole captured conversation turn from the matched
+// chunk, short enough that ten results stay readable.
+const MAX_PREVIEW_CHARS = 500;
 export function registerSearchTool(api, client) {
     api.registerTool({
         name: "search_notes",
@@ -7,8 +11,9 @@ export function registerSearchTool(api, client) {
         description: "Search the Basic Memory knowledge graph for relevant notes, concepts, and connections. " +
             "Returns matching notes with titles, content previews, and relevance scores. " +
             "Optionally filter by frontmatter metadata fields, tags, or status, or target " +
-            "another project. For a quick cross-source recall that also covers MEMORY.md " +
-            "and active tasks, use memory_search.",
+            "another project. This is the search for long-term memory and earlier " +
+            "conversations; memory_search covers only the workspace MEMORY.md and memory/ " +
+            "files. Read a result in full with read_note, or follow its links with build_context.",
         parameters: Type.Object({
             query: Type.String({ description: "Search query" }),
             limit: Type.Optional(Type.Number({ description: "Max results (default: 10)" })),
@@ -54,9 +59,11 @@ export function registerSearchTool(api, client) {
                 }
                 const text = results
                     .map((r, i) => {
-                    const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : "";
-                    const content = r.content ?? "";
-                    const preview = content.length > 200 ? `${content.slice(0, 200)}...` : content;
+                    const score = r.score ? ` (score ${r.score.toFixed(2)})` : "";
+                    const text = searchResultText(r);
+                    const preview = text.length > MAX_PREVIEW_CHARS
+                        ? `${text.slice(0, MAX_PREVIEW_CHARS)}...`
+                        : text;
                     return `${i + 1}. **${r.title}**${score}\n   ${preview}`;
                 })
                     .join("\n\n");
@@ -83,7 +90,7 @@ export function registerSearchTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: "Search failed. Is Basic Memory running? Check logs for details.",
+                            text: `Search failed: ${describeToolError(err)}`,
                         },
                     ],
                     details: {

package/dist/tools/write-note.d.ts

@@ -1,3 +1,3 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
+import { type BmClient } from "../bm-client.ts";
 export declare function registerWriteTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/write-note.js

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import { NoteAlreadyExistsError, NoteRevisionConflictError, } from "../bm-client.js";
+import { describeToolError, NoteAlreadyExistsError, NoteRevisionConflictError, } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerWriteTool(api, client) {
     api.registerTool({
@@ -41,7 +41,7 @@ export function registerWriteTool(api, client) {
                 description: 'Note type stored in frontmatter. Defaults to "note".',
             })),
             expected_checksum: Type.Optional(Type.String({
-                description: "Requires overwrite=true. The checksum of the note as you read it; " +
+                description: "Implies overwrite=true. The checksum of the note as you read it; " +
                     "the note is replaced only while it is still that revision.",
             })),
         }),
@@ -65,7 +65,9 @@ export function registerWriteTool(api, client) {
                 const checksumSuffix = note.checksum
                     ? `\nChecksum: ${note.checksum}`
                     : "";
-                const msg = `Note saved: ${note.title} (${note.permalink})${checksumSuffix}`;
+                // The description tells agents to cite permalink and file_path, so both
+                // must appear in the text the agent reads, not only in details.
+                const msg = `Note saved: ${note.title} (${note.permalink})\nFile: ${note.file_path}${checksumSuffix}`;
                 return {
                     content: [
                         {
@@ -84,13 +86,10 @@ export function registerWriteTool(api, client) {
             catch (err) {
                 if (err instanceof NoteAlreadyExistsError) {
                     const hint = [
-                        `Note already exists: "${params.title}" (${err.permalink})`,
+                        err.message,
                         "",
-                        "To update this note, use one of:",
-                        `  - edit_note("${err.permalink}", operation="append", content="...")`,
-                        `  - edit_note("${err.permalink}", operation="replace_section", section="...", content="...")`,
-                        `  - write_note("${params.title}", ..., overwrite=true) to fully replace`,
-                        `  - read_note("${err.permalink}", include_frontmatter=true) to inspect it first; pass its checksum as expected_checksum with overwrite=true to replace only that revision`,
+                        "Use search_notes to locate the note, then read_note to inspect its current content and checksum.",
+                        "Use edit_note for incremental changes, or write_note with overwrite=true and expected_checksum to replace the revision you read.",
                     ].join("\n");
                     return {
                         content: [{ type: "text", text: hint }],
@@ -104,9 +103,9 @@ export function registerWriteTool(api, client) {
                 if (err instanceof NoteRevisionConflictError) {
                     const current = err.currentChecksum
                         ? `Its current checksum is ${err.currentChecksum}.`
-                        : "No note exists at that path any more.";
+                        : "Read the note to obtain its current checksum.";
                     const text = [
-                        `Note revision conflict: "${params.title}" changed since it was read, so nothing was replaced. ${current}`,
+                        `Note revision conflict: ${err.message} ${current}`,
                         "",
                         "Read the note again, confirm it should still be replaced, then retry with the new checksum as expected_checksum.",
                     ].join("\n");
@@ -125,7 +124,7 @@ export function registerWriteTool(api, client) {
                     content: [
                         {
                             type: "text",
-                            text: "Failed to write note. Is Basic Memory running? Check logs for details.",
+                            text: `Failed to write note: ${describeToolError(err)}`,
                         },
                     ],
                     details: {