@basicmemory/openclaw-basic-memory 0.24.1 → 1.0.0

package/tools/list-workspaces.ts

@@ -1,13 +1,16 @@
 import { Type } from "@sinclair/typebox"
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
-import type { BmClient, WorkspaceResult } from "../bm-client.ts"
+import {
+  type BmClient,
+  describeToolError,
+  type WorkspaceResult,
+} from "../bm-client.ts"
 import { log } from "../logger.ts"
 
 function formatWorkspace(ws: WorkspaceResult, idx: number): string {
-  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"}`
   )
 }
 
@@ -20,7 +23,7 @@ export function registerWorkspaceListTool(
       name: "list_workspaces",
       label: "List Workspaces",
       description:
-        "List all Basic Memory workspaces (personal and organization) accessible to this user. " +
+        "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({}),
@@ -65,7 +68,7 @@ export function registerWorkspaceListTool(
             content: [
               {
                 type: "text" as const,
-                text: "Failed to list workspaces. Is Basic Memory running? Check logs for details.",
+                text: `Failed to list workspaces: ${describeToolError(err)}`,
               },
             ],
             details: {

package/tools/move-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 registerMoveTool(
@@ -62,7 +62,7 @@ export function registerMoveTool(
             content: [
               {
                 type: "text" as const,
-                text: `Failed to move "${params.identifier}". It may not exist.`,
+                text: `Failed to move "${params.identifier}": ${describeNoteError(err)}`,
               },
             ],
             details: {

package/tools/read-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 registerReadTool(
@@ -86,7 +86,7 @@ export function registerReadTool(
             content: [
               {
                 type: "text" as const,
-                text: `Could not read note "${params.identifier}". It may not exist yet.`,
+                text: `Could not read note "${params.identifier}": ${describeNoteError(err)}`,
               },
             ],
             details: {

package/tools/schema-diff.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 registerSchemaDiffTool(
@@ -93,7 +93,7 @@ export function registerSchemaDiffTool(
             content: [
               {
                 type: "text" as const,
-                text: "Schema diff failed. Check logs for details.",
+                text: `Schema diff failed: ${describeToolError(err)}`,
               },
             ],
             details: {

package/tools/schema-infer.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 registerSchemaInferTool(
@@ -91,7 +91,7 @@ export function registerSchemaInferTool(
             content: [
               {
                 type: "text" as const,
-                text: "Schema inference failed. Check logs for details.",
+                text: `Schema inference failed: ${describeToolError(err)}`,
               },
             ],
             details: {

package/tools/schema-validate.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 registerSchemaValidateTool(
@@ -89,7 +89,7 @@ export function registerSchemaValidateTool(
             content: [
               {
                 type: "text" as const,
-                text: "Schema validation failed. Check logs for details.",
+                text: `Schema validation failed: ${describeToolError(err)}`,
               },
             ],
             details: {

package/tools/search-notes.ts

@@ -1,8 +1,16 @@
 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,
+  searchResultText,
+} from "../bm-client.ts"
 import { log } from "../logger.ts"
 
+// 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: OpenClawPluginApi,
   client: BmClient,
@@ -15,8 +23,9 @@ export function registerSearchTool(
         "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(
@@ -98,10 +107,12 @@ export function registerSearchTool(
 
           const text = results
             .map((r, i) => {
-              const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : ""
-              const content = r.content ?? ""
+              const score = r.score ? ` (score ${r.score.toFixed(2)})` : ""
+              const text = searchResultText(r)
               const preview =
-                content.length > 200 ? `${content.slice(0, 200)}...` : content
+                text.length > MAX_PREVIEW_CHARS
+                  ? `${text.slice(0, MAX_PREVIEW_CHARS)}...`
+                  : text
               return `${i + 1}. **${r.title}**${score}\n   ${preview}`
             })
             .join("\n\n")
@@ -128,7 +139,7 @@ export function registerSearchTool(
             content: [
               {
                 type: "text" as const,
-                text: "Search failed. Is Basic Memory running? Check logs for details.",
+                text: `Search failed: ${describeToolError(err)}`,
               },
             ],
             details: {

package/tools/write-note.ts

@@ -1,7 +1,8 @@
 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,
   NoteAlreadyExistsError,
   NoteRevisionConflictError,
 } from "../bm-client.ts"
@@ -73,7 +74,7 @@ export function registerWriteTool(
         expected_checksum: Type.Optional(
           Type.String({
             description:
-              "Requires overwrite=true. The checksum of the note as you read it; " +
+              "Implies overwrite=true. The checksum of the note as you read it; " +
               "the note is replaced only while it is still that revision.",
           }),
         ),
@@ -123,7 +124,9 @@ export function registerWriteTool(
           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: [
               {
@@ -141,13 +144,10 @@ export function registerWriteTool(
         } 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 {
@@ -163,9 +163,9 @@ export function registerWriteTool(
           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")
@@ -186,7 +186,7 @@ export function registerWriteTool(
             content: [
               {
                 type: "text" as const,
-                text: "Failed to write note. Is Basic Memory running? Check logs for details.",
+                text: `Failed to write note: ${describeToolError(err)}`,
               },
             ],
             details: {

package/dist/tools/memory-provider.d.ts

@@ -1,15 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
-import type { BmClient } from "../bm-client.ts";
-import type { BasicMemoryConfig } from "../config.ts";
-export declare function setWorkspaceDir(dir: string): void;
-/**
- * Register composited memory_search and memory_get tools.
- *
- * memory_search queries 3 sources in parallel:
- * 1. MEMORY.md — grep/text search
- * 2. BM knowledge graph — semantic + FTS search
- * 3. Active tasks — memory/tasks/ files with status != done
- *
- * memory_get reads a specific note by identifier.
- */
-export declare function registerMemoryProvider(api: OpenClawPluginApi, client: BmClient, cfg: BasicMemoryConfig): void;

package/dist/tools/memory-provider.js

@@ -1,275 +0,0 @@
-import { readdir, readFile } from "node:fs/promises";
-import { join, resolve } from "node:path";
-import { Type } from "@sinclair/typebox";
-import { log } from "../logger.js";
-/**
- * Search MEMORY.md for lines matching the query.
- * Returns matching lines with 1 line of surrounding context.
- */
-async function searchMemoryFile(query, workspaceDir, memoryFile) {
-    try {
-        const filePath = resolve(workspaceDir, memoryFile);
-        const content = await readFile(filePath, "utf-8");
-        const lines = content.split("\n");
-        const queryLower = query.toLowerCase();
-        const terms = queryLower.split(/\s+/).filter((t) => t.length > 0);
-        // Find lines that match any search term
-        const matchingIndices = new Set();
-        for (let i = 0; i < lines.length; i++) {
-            const lineLower = lines[i].toLowerCase();
-            if (terms.some((term) => lineLower.includes(term))) {
-                // Add the matching line + 1 line before/after for context
-                if (i > 0)
-                    matchingIndices.add(i - 1);
-                matchingIndices.add(i);
-                if (i < lines.length - 1)
-                    matchingIndices.add(i + 1);
-            }
-        }
-        if (matchingIndices.size === 0)
-            return "";
-        // Group consecutive lines into snippets
-        const sorted = [...matchingIndices].sort((a, b) => a - b);
-        const snippets = [];
-        let current = [];
-        let lastIdx = -2;
-        for (const idx of sorted) {
-            if (idx !== lastIdx + 1 && current.length > 0) {
-                snippets.push(current.join("\n"));
-                current = [];
-            }
-            current.push(`- ${lines[idx]}`);
-            lastIdx = idx;
-        }
-        if (current.length > 0)
-            snippets.push(current.join("\n"));
-        return snippets.join("\n…\n");
-    }
-    catch {
-        return "";
-    }
-}
-/**
- * Search for active tasks via BM knowledge graph.
- * Uses search_notes with note_types and status filters for precise querying.
- * Falls back to filesystem scan if search fails.
- */
-async function searchActiveTasks(query, client, workspaceDir, memoryDir) {
-    // Try structured search first
-    try {
-        const results = await client.search(query || undefined, 10, undefined, {
-            note_types: ["task"],
-            status: "active",
-        });
-        if (results.length > 0) {
-            const matches = [];
-            for (const r of results) {
-                const score = r.score ? ` (${r.score.toFixed(2)})` : "";
-                const preview = (r.content ?? "").length > 200
-                    ? `${(r.content ?? "").slice(0, 200)}…`
-                    : (r.content ?? "");
-                matches.push(`- **${r.title}**${score} — ${r.file_path}\n  > ${preview.replace(/\n/g, "\n  > ")}`);
-            }
-            return matches.join("\n\n");
-        }
-    }
-    catch (err) {
-        log.debug("BM task search failed, falling back to filesystem scan", err);
-    }
-    // Fallback: filesystem scan for tasks not yet indexed
-    try {
-        const tasksDir = resolve(workspaceDir, memoryDir, "tasks");
-        let entries;
-        try {
-            entries = (await readdir(tasksDir, {
-                withFileTypes: true,
-            }));
-        }
-        catch {
-            return "";
-        }
-        const queryLower = query.toLowerCase();
-        const terms = queryLower.split(/\s+/).filter((t) => t.length > 0);
-        const matches = [];
-        for (const entry of entries) {
-            if (!entry.isFile() || !entry.name.endsWith(".md"))
-                continue;
-            const filePath = join(entry.parentPath ?? tasksDir, entry.name);
-            const content = await readFile(filePath, "utf-8");
-            const statusMatch = content.match(/status:\s*(\S+)/);
-            const status = statusMatch?.[1] ?? "unknown";
-            if (status === "done")
-                continue;
-            const contentLower = content.toLowerCase();
-            const matchesQuery = terms.length === 0 || terms.some((term) => contentLower.includes(term));
-            if (!matchesQuery)
-                continue;
-            const titleMatch = content.match(/title:\s*(.+)/);
-            const title = titleMatch?.[1] ?? entry.name.replace(/\.md$/, "");
-            const stepMatch = content.match(/current_step:\s*(\S+)/);
-            const currentStep = stepMatch?.[1] ?? "?";
-            const contextMatch = content.match(/## Context\s*\n([\s\S]*?)(?=\n##|\n---|$)/);
-            const context = contextMatch?.[1]?.trim().slice(0, 150) ?? "";
-            matches.push(`- **${title}** (status: ${status}, step: ${currentStep})\n  ${context}`);
-        }
-        return matches.join("\n");
-    }
-    catch {
-        return "";
-    }
-}
-// Store workspace dir for use in memory_search (set during service start)
-let _workspaceDir = "";
-export function setWorkspaceDir(dir) {
-    _workspaceDir = dir;
-}
-/**
- * Register composited memory_search and memory_get tools.
- *
- * memory_search queries 3 sources in parallel:
- * 1. MEMORY.md — grep/text search
- * 2. BM knowledge graph — semantic + FTS search
- * 3. Active tasks — memory/tasks/ files with status != done
- *
- * memory_get reads a specific note by identifier.
- */
-export function registerMemoryProvider(api, client, cfg) {
-    // --- composited memory_search ---
-    api.registerTool({
-        name: "memory_search",
-        label: "Memory Search",
-        description: "Search across all memory sources: MEMORY.md (working memory), " +
-            "Basic Memory knowledge graph (long-term archive), and active tasks. " +
-            "Returns composited results from all sources. Use it for broad recall; use " +
-            "search_notes when you need metadata, tag, or status filters or a specific project.",
-        parameters: Type.Object({
-            query: Type.String({
-                description: "Search query — natural language or keywords",
-            }),
-        }),
-        async execute(_toolCallId, params) {
-            log.debug(`memory_search: query="${params.query}"`);
-            const workspaceDir = _workspaceDir || process.cwd();
-            // Query all 3 sources in parallel
-            const [memoryMd, bmResults, taskResults] = await Promise.all([
-                searchMemoryFile(params.query, workspaceDir, cfg.memoryFile),
-                client
-                    .search(params.query, 5)
-                    .then((results) => {
-                    if (results.length === 0)
-                        return "";
-                    return results
-                        .map((r) => {
-                        const score = r.score ? ` (${r.score.toFixed(2)})` : "";
-                        const preview = (r.content ?? "").length > 200
-                            ? `${(r.content ?? "").slice(0, 200)}…`
-                            : (r.content ?? "");
-                        const source = r.file_path || r.permalink;
-                        return `- ${source}${score}\n  > ${preview.replace(/\n/g, "\n  > ")}`;
-                    })
-                        .join("\n\n");
-                })
-                    .catch((err) => {
-                    log.error("BM search failed in composited search", err);
-                    return "(search unavailable)";
-                }),
-                searchActiveTasks(params.query, client, workspaceDir, cfg.memoryDir),
-            ]);
-            // Build composited result
-            const sections = [];
-            if (memoryMd) {
-                sections.push(`## ${cfg.memoryFile}\n${memoryMd}`);
-            }
-            if (bmResults) {
-                sections.push(`## Knowledge Graph (${cfg.memoryDir})\n${bmResults}`);
-            }
-            if (taskResults) {
-                sections.push(`## Active Tasks\n${taskResults}`);
-            }
-            if (sections.length === 0) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: "No matches found across memory sources.",
-                        },
-                    ],
-                    details: {
-                        query: params.query,
-                        sectionCount: 0,
-                        hasMemoryFileMatches: false,
-                        hasKnowledgeGraphMatches: false,
-                        hasTaskMatches: false,
-                    },
-                };
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: sections.join("\n\n"),
-                    },
-                ],
-                details: {
-                    query: params.query,
-                    sectionCount: sections.length,
-                    hasMemoryFileMatches: memoryMd.length > 0,
-                    hasKnowledgeGraphMatches: bmResults.length > 0,
-                    hasTaskMatches: taskResults.length > 0,
-                },
-            };
-        },
-    }, { names: ["memory_search"] });
-    // --- memory_get (unchanged) ---
-    api.registerTool({
-        name: "memory_get",
-        label: "Memory Get",
-        description: "Read a specific note from the knowledge graph by title, permalink, or path. " +
-            "Returns the full note content. Use after memory_search to read a specific result in full.",
-        parameters: Type.Object({
-            path: Type.String({
-                description: "Note identifier — title, permalink, memory:// URL, or file path",
-            }),
-            from: Type.Optional(Type.Number({
-                description: "Starting line number (ignored — included for compatibility)",
-            })),
-            lines: Type.Optional(Type.Number({
-                description: "Number of lines to read (ignored — included for compatibility)",
-            })),
-        }),
-        async execute(_toolCallId, params) {
-            log.debug(`memory_get: path="${params.path}"`);
-            try {
-                const note = await client.readNote(params.path);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `# ${note.title}\n\n${note.content}`,
-                        },
-                    ],
-                    details: {
-                        title: note.title,
-                        permalink: note.permalink,
-                        file_path: note.file_path,
-                    },
-                };
-            }
-            catch (err) {
-                log.error("memory_get failed", err);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Could not read "${params.path}". It may not exist in the knowledge graph.`,
-                        },
-                    ],
-                    details: {
-                        path: params.path,
-                        error: "memory_get_failed",
-                    },
-                };
-            }
-        },
-    }, { names: ["memory_get"] });
-}