@basicmemory/openclaw-basic-memory 0.24.0 → 1.0.0

package/dist/bm-client.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -5,22 +6,23 @@ import { log } from "./logger.js";
 const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000];
 export class NoteAlreadyExistsError extends Error {
     permalink;
-    constructor(title, permalink) {
-        super(`Note already exists: "${title}" (${permalink})`);
+    constructor(title, permalink, message) {
+        super(message ?? `Note already exists: "${title}" (${permalink})`);
         this.name = "NoteAlreadyExistsError";
         this.permalink = permalink;
     }
 }
 /**
- * write_note refused a conditional overwrite: the note is no longer the
+ * bm_write refused a conditional overwrite: the note is no longer the
  * revision named by expected_checksum. Nothing was written; currentChecksum is
- * the revision to re-read and retry against (null once no note owns the path).
+ * available revision when supplied by a server. A null value means unknown;
+ * 1.0 puts revision details in the refusal message, not a checksum field.
  */
 export class NoteRevisionConflictError extends Error {
     permalink;
     currentChecksum;
-    constructor(title, permalink, currentChecksum) {
-        super(`Note revision conflict: "${title}" changed since it was read`);
+    constructor(title, permalink, currentChecksum, message) {
+        super(message ?? `Note revision conflict: "${title}" changed since it was read`);
         this.name = "NoteRevisionConflictError";
         this.permalink = permalink;
         this.currentChecksum = currentChecksum;
@@ -38,21 +40,24 @@ export class BmToolError extends Error {
     }
 }
 const REQUIRED_TOOLS = [
-    "search_notes",
-    "read_note",
-    "write_note",
-    "edit_note",
-    "build_context",
-    "recent_activity",
-    "list_memory_projects",
-    "list_workspaces",
-    "create_memory_project",
-    "delete_note",
-    "move_note",
-    "schema_validate",
-    "schema_infer",
-    "schema_diff",
+    "bm_search",
+    "bm_read",
+    "bm_write",
+    "bm_edit",
+    "bm_context",
+    "bm_project",
+    "bm_delete",
+    "bm_move",
+    "bm_schema",
 ];
+/**
+ * The text to preview for a search hit. `content` is the start of the note,
+ * so for a long note (a day of captured conversation) the matching part can
+ * sit far below any preview cut-off; the matched chunk is the part that hit.
+ */
+export function searchResultText(result) {
+    return result.matched_chunk?.trim() || result.content || "";
+}
 function getErrorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -80,19 +85,24 @@ function isRecoverableConnectionError(err) {
         msg.includes("failed to start bm mcp stdio") ||
         msg.includes("client is closed"));
 }
-function isNoteNotFoundError(err) {
-    const msg = getErrorMessage(err).toLowerCase();
-    return (msg.includes("entity not found") ||
-        msg.includes("note not found") ||
-        msg.includes("resource not found") ||
-        msg.includes("could not find note matching") ||
-        msg.includes("404"));
+export function isNoteNotFoundError(err) {
+    return (err instanceof BmToolError &&
+        parseRefusalPayload(err.toolMessage)?.error === "NOT_FOUND");
+}
+function conversationDate(date) {
+    return date.toISOString().split("T")[0];
+}
+// Host advancement keys are opaque and may contain characters that would end
+// an HTML comment, so the note stores a fixed-length digest instead.
+function conversationTurnMarker(turnKey) {
+    const digest = createHash("sha256").update(turnKey).digest("hex").slice(0, 32);
+    return `<!-- openclaw-turn:${digest} -->`;
 }
 function asString(value) {
     return typeof value === "string" ? value : null;
 }
 // In JSON mode BM reports a refused write as a tool error whose text is the
-// refusal payload itself ({"error": "NOTE_ALREADY_EXISTS", ...}). Any other
+// refusal payload itself ({"error": "ALREADY_EXISTS", ...}). Any other
 // error text (plain-text failures, older servers) is not a refusal payload.
 function parseRefusalPayload(text) {
     let parsed;
@@ -104,6 +114,24 @@ function parseRefusalPayload(text) {
     }
     return isRecord(parsed) && typeof parsed.error === "string" ? parsed : null;
 }
+/**
+ * The server's own explanation of a failed tool call, for showing to an agent.
+ * A refusal payload becomes "CODE: message"; other tool text passes through.
+ */
+export function describeToolError(err) {
+    if (!(err instanceof BmToolError))
+        return getErrorMessage(err);
+    const payload = parseRefusalPayload(err.toolMessage);
+    if (!payload)
+        return err.toolMessage || err.message;
+    const message = asString(payload.message);
+    return message ? `${payload.error}: ${message}` : String(payload.error);
+}
+/** describeToolError, but saying plainly when the note does not exist. */
+export function describeNoteError(err) {
+    const reason = describeToolError(err);
+    return isNoteNotFoundError(err) ? `it does not exist. ${reason}` : reason;
+}
 function projectMatchesWorkspace(project, workspace) {
     const requested = workspace.trim().toLowerCase();
     if (!requested)
@@ -120,26 +148,93 @@ export class BmClient {
     cwd;
     env;
     shouldRun = false;
+    // True only between start() and stop(), i.e. while the plugin service owns
+    // the BM MCP session. A lazy connection opened by a tool or memory call in a
+    // one-shot CLI process leaves this false.
+    serviceRunning = false;
+    // Connect plus project creation, started by start(). Tool calls wait for
+    // it so none can reach a project that does not exist yet. Null when the
+    // client was never started (tests, one-shot CLI readers).
+    startup = null;
+    startupRetry = null;
+    projectPath;
+    prepare;
     client = null;
     transport = null;
     connectPromise = null;
     retryDelaysMs = [...DEFAULT_RETRY_DELAYS_MS];
+    // Conversation captures run one at a time so a turn-key duplicate check
+    // and the append that follows it cannot interleave with another capture.
+    conversationWrites = Promise.resolve();
     constructor(bmPath, project) {
         this.bmPath = bmPath;
         this.project = project;
     }
-    async start(options) {
+    /**
+     * Connect to BM and create the plugin's project.
+     *
+     * Returns the startup promise; callers that must not block (the plugin
+     * service, which OpenClaw gives only a few seconds) can leave it running.
+     * Tool calls made meanwhile wait for it. If it fails, the next tool call
+     * runs it again, so a transient failure does not leave the plugin dead.
+     */
+    start(options) {
         this.shouldRun = true;
+        this.serviceRunning = true;
         if (options?.cwd) {
             this.cwd = options.cwd;
         }
         if (options?.env) {
             this.env = options.env;
         }
+        if (options?.projectPath) {
+            this.projectPath = options.projectPath;
+        }
+        if (options?.prepare) {
+            this.prepare = options.prepare;
+        }
+        this.startup = this.runStartup();
+        return this.startup;
+    }
+    async runStartup() {
+        await this.prepare?.();
         await this.connectWithRetries();
+        if (this.projectPath)
+            await this.createProject(this.projectPath);
+    }
+    async waitForStartup() {
+        if (!this.startup)
+            return;
+        try {
+            await this.startup;
+        }
+        catch (err) {
+            // Trigger: the startup this call was waiting on failed.
+            // Why: the service no longer fails on a slow or failed start, so the
+            //   first tool call afterwards is the place to recover.
+            // Outcome: one fresh attempt, shared by concurrent callers; its error
+            //   reaches the tool if it fails too.
+            if (!this.serviceRunning)
+                throw err;
+            if (this.startupRetry === null) {
+                this.startupRetry = this.runStartup().finally(() => {
+                    this.startupRetry = null;
+                });
+                this.startup = this.startupRetry;
+            }
+            await this.startupRetry;
+        }
+    }
+    isServiceRunning() {
+        return this.serviceRunning;
     }
     async stop() {
         this.shouldRun = false;
+        this.serviceRunning = false;
+        // Let an in-flight startup settle first, so it cannot reconnect after
+        // the disconnect below.
+        await this.startup?.catch(() => undefined);
+        this.startup = null;
         await this.disconnectCurrent(this.client, this.transport);
         this.client = null;
         this.transport = null;
@@ -297,6 +392,11 @@ export class BmClient {
         throw new Error(`BM MCP unavailable: ${getErrorMessage(lastErr)}`);
     }
     async callTool(name, args) {
+        await this.waitForStartup();
+        return this.callStructured(name, args);
+    }
+    // Ungated: startup itself calls this to create the project.
+    async callStructured(name, args) {
         const result = await this.callToolRaw(name, args);
         if (!isRecord(result) || result.structuredContent === undefined) {
             throw new Error(`BM MCP tool ${name} returned no structured payload`);
@@ -310,36 +410,45 @@ export class BmClient {
     routedProject(project) {
         return project ?? this.project;
     }
-    // project_id names one exact project, so it is sent alone: pairing it with
-    // a name (or the plugin's default project) would make routing depend on
-    // server-side precedence rather than on what the caller asked for.
+    // The 1.0 project parameter accepts either a name or an exact project UUID.
     routing(project, projectId) {
         if (projectId !== undefined)
-            return { project_id: projectId };
+            return { project: projectId };
         return { project: this.routedProject(project) };
     }
     async ensureProject(projectPath) {
-        const payload = await this.callTool("create_memory_project", {
-            project_name: this.project,
-            project_path: projectPath,
+        await this.waitForStartup();
+        await this.createProject(projectPath);
+    }
+    async createProject(projectPath) {
+        const payload = await this.callStructured("bm_project", {
+            command: "create",
+            name: this.project,
+            path: projectPath,
             set_default: true,
             output_format: "json",
         });
         if (!isRecord(payload)) {
-            throw new Error("invalid create_memory_project response");
+            throw new Error("invalid bm_project response");
         }
     }
     async listWorkspaces() {
-        const payload = await this.callTool("list_workspaces", {
-            output_format: "json",
-        });
-        if (isRecord(payload) && Array.isArray(payload.workspaces)) {
-            return payload.workspaces;
+        const projects = await this.listProjects();
+        const workspaces = new Map();
+        for (const project of projects) {
+            if (project.workspace_tenant_id && project.workspace_name) {
+                workspaces.set(project.workspace_tenant_id, {
+                    tenant_id: project.workspace_tenant_id,
+                    name: project.workspace_name,
+                    workspace_type: project.workspace_type ?? null,
+                });
+            }
         }
-        throw new Error("invalid list_workspaces response");
+        return [...workspaces.values()];
     }
     async listProjects(workspace) {
-        const payload = await this.callTool("list_memory_projects", {
+        const payload = await this.callTool("bm_project", {
+            command: "list",
             output_format: "json",
         });
         if (isRecord(payload) && Array.isArray(payload.projects)) {
@@ -349,7 +458,7 @@ export class BmClient {
             }
             return projects;
         }
-        throw new Error("invalid list_memory_projects response");
+        throw new Error("invalid bm_project response");
     }
     async search(query, limit = 10, project, metadata) {
         const args = {
@@ -360,19 +469,21 @@ export class BmClient {
         };
         if (query)
             args.query = query;
-        if (metadata?.filters)
-            args.metadata_filters = metadata.filters;
-        if (metadata?.tags)
-            args.tags = metadata.tags;
-        if (metadata?.status)
-            args.status = metadata.status;
+        const filters = { ...metadata?.filters };
+        // Explicit predicates take precedence over convenience shortcuts.
+        if (metadata?.tags?.length && !("tags" in filters))
+            filters.tags = { $contains: metadata.tags };
+        if (metadata?.status && !("status" in filters))
+            filters.status = metadata.status;
+        if (Object.keys(filters).length)
+            args.filters = filters;
         if (metadata?.note_types)
             args.note_types = metadata.note_types;
         if (metadata?.entity_types)
-            args.entity_types = metadata.entity_types;
-        const payload = await this.callTool("search_notes", args);
+            args.items = metadata.entity_types.map((item) => item === "entity" ? "note" : item);
+        const payload = await this.callTool("bm_search", args);
         if (!isRecord(payload) || !Array.isArray(payload.results)) {
-            throw new Error("invalid search_notes response");
+            throw new Error("invalid bm_search response");
         }
         return payload.results;
     }
@@ -383,16 +494,16 @@ export class BmClient {
             output_format: "json",
             ...this.routing(project, options.projectId),
         };
-        const payload = await this.callTool("read_note", args);
+        const payload = await this.callTool("bm_read", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid read_note response");
+            throw new Error("invalid bm_read response");
         }
         const title = asString(payload.title);
         const permalink = asString(payload.permalink);
         const content = asString(payload.content);
         const filePath = asString(payload.file_path);
         if (!title || !permalink || content === null || !filePath) {
-            throw new Error("invalid read_note payload");
+            throw new Error("invalid bm_read payload");
         }
         return {
             title,
@@ -423,30 +534,26 @@ export class BmClient {
             args.expected_checksum = options.expectedChecksum;
         let payload;
         try {
-            payload = await this.callTool("write_note", args);
+            payload = await this.callTool("bm_write", args);
         }
         catch (err) {
             const refusal = err instanceof BmToolError ? parseRefusalPayload(err.toolMessage) : null;
-            if (refusal?.error === "NOTE_ALREADY_EXISTS") {
-                throw new NoteAlreadyExistsError(asString(refusal.title) ?? title, asString(refusal.permalink) ?? "");
+            if (refusal?.error === "ALREADY_EXISTS") {
+                throw new NoteAlreadyExistsError(asString(refusal.title) ?? title, asString(refusal.permalink) ?? "", asString(refusal.message) ?? undefined);
             }
-            if (refusal?.error === "NOTE_REVISION_CONFLICT") {
-                throw new NoteRevisionConflictError(asString(refusal.title) ?? title, asString(refusal.permalink), asString(refusal.currentChecksum));
+            if (refusal?.error === "REVISION_CONFLICT") {
+                throw new NoteRevisionConflictError(asString(refusal.title) ?? title, asString(refusal.permalink), asString(refusal.currentChecksum), asString(refusal.message) ?? undefined);
             }
             throw err;
         }
         if (!isRecord(payload)) {
-            throw new Error("invalid write_note response");
-        }
-        // Older servers returned the refusal as a successful payload.
-        if (payload.error === "NOTE_ALREADY_EXISTS") {
-            throw new NoteAlreadyExistsError(asString(payload.title) ?? title, asString(payload.permalink) ?? "");
+            throw new Error("invalid bm_write response");
         }
         const resultTitle = asString(payload.title);
         const permalink = asString(payload.permalink);
         const filePath = asString(payload.file_path);
         if (!resultTitle || !permalink || !filePath) {
-            throw new Error("invalid write_note payload");
+            throw new Error("invalid bm_write payload");
         }
         return {
             title: resultTitle,
@@ -461,33 +568,34 @@ export class BmClient {
     }
     async buildContext(url, depth = 1, project) {
         const args = {
-            url,
+            identifier: url,
             depth,
             output_format: "json",
             project: this.routedProject(project),
         };
-        const payload = await this.callTool("build_context", args);
+        const payload = await this.callTool("bm_context", args);
         if (!isRecord(payload) || !Array.isArray(payload.results)) {
-            throw new Error("invalid build_context response");
+            throw new Error("invalid bm_context response");
         }
         return payload;
     }
     async recentActivity(timeframe = "24h", project) {
         const args = {
-            timeframe,
+            command: "recent",
+            since: timeframe,
             output_format: "json",
             project: this.routedProject(project),
         };
-        const payload = await this.callTool("recent_activity", args);
-        if (Array.isArray(payload)) {
-            return payload;
+        const payload = await this.callTool("bm_project", args);
+        if (isRecord(payload) && Array.isArray(payload.results)) {
+            return payload.results;
         }
-        throw new Error("invalid recent_activity response");
+        throw new Error("invalid bm_project response");
     }
     async editNote(identifier, operation, content, options = {}, project) {
         const args = {
             identifier,
-            operation,
+            command: operation,
             content,
             output_format: "json",
             project: this.routedProject(project),
@@ -500,15 +608,15 @@ export class BmClient {
             args.expected_replacements = options.expected_replacements;
         if (options.metadata !== undefined)
             args.metadata = options.metadata;
-        const payload = await this.callTool("edit_note", args);
+        const payload = await this.callTool("bm_edit", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid edit_note response");
+            throw new Error("invalid bm_edit response");
         }
         const title = asString(payload.title);
         const permalink = asString(payload.permalink);
         const filePath = asString(payload.file_path);
         if (!title || !permalink || !filePath) {
-            throw new Error("invalid edit_note payload");
+            throw new Error("invalid bm_edit payload");
         }
         return {
             title,
@@ -524,12 +632,12 @@ export class BmClient {
             output_format: "json",
             project: this.routedProject(project),
         };
-        const payload = await this.callTool("delete_note", args);
+        const payload = await this.callTool("bm_delete", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid delete_note response");
+            throw new Error("invalid bm_delete response");
         }
-        if (payload.deleted !== true) {
-            throw new Error(`delete_note did not delete "${identifier}"`);
+        if (payload.action !== "deleted") {
+            throw new Error(`bm_delete did not delete "${identifier}"`);
         }
         return {
             title: asString(payload.title) ?? identifier,
@@ -540,17 +648,17 @@ export class BmClient {
     async moveNote(identifier, newFolder, project) {
         const args = {
             identifier,
-            destination_folder: newFolder,
+            destination: `${newFolder.replace(/\/+$/, "")}/`,
             output_format: "json",
             project: this.routedProject(project),
         };
-        const payload = await this.callTool("move_note", args);
+        const payload = await this.callTool("bm_move", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid move_note response");
+            throw new Error("invalid bm_move response");
         }
-        if (payload.moved !== true) {
+        if (payload.action !== "moved") {
             throw new Error(asString(payload.error) ??
-                `move_note did not move "${identifier}" to "${newFolder}"`);
+                `bm_move did not move "${identifier}" to "${newFolder}"`);
         }
         return {
             title: asString(payload.title) ?? identifier,
@@ -561,6 +669,7 @@ export class BmClient {
     }
     async schemaValidate(noteType, identifier, project) {
         const args = {
+            command: "validate",
             output_format: "json",
             project: this.routedProject(project),
         };
@@ -568,44 +677,77 @@ export class BmClient {
             args.note_type = noteType;
         if (identifier)
             args.identifier = identifier;
-        const payload = await this.callTool("schema_validate", args);
+        const payload = await this.callTool("bm_schema", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid schema_validate response");
+            throw new Error("invalid bm_schema response");
         }
         return payload;
     }
     async schemaInfer(noteType, threshold = 0.25, project) {
         const args = {
+            command: "infer",
             note_type: noteType,
             threshold,
             output_format: "json",
             project: this.routedProject(project),
         };
-        const payload = await this.callTool("schema_infer", args);
+        const payload = await this.callTool("bm_schema", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid schema_infer response");
+            throw new Error("invalid bm_schema response");
         }
         return payload;
     }
     async schemaDiff(noteType, project) {
         const args = {
+            command: "diff",
             note_type: noteType,
             output_format: "json",
             project: this.routedProject(project),
         };
-        const payload = await this.callTool("schema_diff", args);
+        const payload = await this.callTool("bm_schema", args);
         if (!isRecord(payload)) {
-            throw new Error("invalid schema_diff response");
+            throw new Error("invalid bm_schema response");
         }
         return payload;
     }
-    async indexConversation(userMessage, assistantResponse) {
+    /**
+     * Append one user/assistant exchange to today's conversation note.
+     *
+     * With a turnKey the capture is idempotent: the entry carries a marker
+     * derived from the key, and a key already present in today's or
+     * yesterday's note is reported as a duplicate instead of written again.
+     * Yesterday is checked because a host retry can cross midnight.
+     */
+    async indexConversation(userMessage, assistantResponse, options = {}) {
+        const write = this.conversationWrites.then(() => this.writeConversationEntry(userMessage, assistantResponse, options.turnKey));
+        this.conversationWrites = write.catch(() => undefined);
+        return write;
+    }
+    async writeConversationEntry(userMessage, assistantResponse, turnKey) {
         const now = new Date();
-        const dateStr = now.toISOString().split("T")[0];
+        const dateStr = conversationDate(now);
         const timeStr = now.toTimeString().slice(0, 5);
         const title = `conversations-${dateStr}`;
+        const marker = turnKey ? conversationTurnMarker(turnKey) : null;
+        // Trigger: the host supplied an advancement key for this turn.
+        // Why: hosts retry commits after a crash, and a second append would
+        //   duplicate the exchange in the note.
+        // Outcome: an already-recorded key short-circuits before any write.
+        if (marker) {
+            const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+            for (const candidate of [
+                title,
+                `conversations-${conversationDate(yesterday)}`,
+            ]) {
+                if (await this.noteContains(candidate, marker)) {
+                    log.debug(`conversation turn already recorded in: ${candidate}`);
+                    return "duplicate";
+                }
+            }
+        }
         const entry = [
             `### ${timeStr}`,
+            ...(marker ? [marker] : []),
             "",
             "**User:**",
             userMessage,
@@ -618,7 +760,7 @@ export class BmClient {
         try {
             await this.editNote(title, "append", entry);
             log.debug(`appended conversation to: ${title}`);
-            return;
+            return "committed";
         }
         catch (err) {
             if (!isNoteNotFoundError(err)) {
@@ -639,12 +781,19 @@ export class BmClient {
             "",
             entry,
         ].join("\n");
+        await this.writeNote(title, content, "conversations");
+        log.debug(`created conversation note: ${title}`);
+        return "committed";
+    }
+    async noteContains(identifier, text) {
         try {
-            await this.writeNote(title, content, "conversations");
-            log.debug(`created conversation note: ${title}`);
+            const note = await this.readNote(identifier);
+            return note.content.includes(text);
         }
         catch (err) {
-            log.error("conversation index failed", err);
+            if (isNoteNotFoundError(err))
+                return false;
+            throw err;
         }
     }
     getProject() {

package/dist/commands/cli.d.ts

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

package/dist/commands/cli.js

@@ -1,3 +1,4 @@
+import { searchResultText } from "../bm-client.js";
 import { log } from "../logger.js";
 export function registerCli(api, client, cfg) {
     api.registerCli(
@@ -19,12 +20,11 @@ export function registerCli(api, client, cfg) {
                 return;
             }
             for (const r of results) {
-                const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : "";
+                const score = r.score ? ` (score ${r.score.toFixed(2)})` : "";
                 console.log(`- ${r.title}${score}`);
-                if (r.content) {
-                    const preview = r.content.length > 100
-                        ? `${r.content.slice(0, 100)}...`
-                        : r.content;
+                const text = searchResultText(r);
+                if (text) {
+                    const preview = text.length > 100 ? `${text.slice(0, 100)}...` : text;
                     console.log(`  ${preview}`);
                 }
             }

package/dist/commands/slash.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 registerCommands(api: OpenClawPluginApi, client: BmClient): void;