@basicmemory/openclaw-basic-memory 0.24.0 → 1.0.0

package/commands/cli.ts

@@ -1,5 +1,5 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
-import type { BmClient } from "../bm-client.ts"
+import { type BmClient, searchResultText } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { log } from "../logger.ts"
 
@@ -31,13 +31,12 @@ export function registerCli(
           }
 
           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 text = searchResultText(r)
+            if (text) {
               const preview =
-                r.content.length > 100
-                  ? `${r.content.slice(0, 100)}...`
-                  : r.content
+                text.length > 100 ? `${text.slice(0, 100)}...` : text
               console.log(`  ${preview}`)
             }
           }

package/commands/slash.ts

@@ -2,7 +2,7 @@ import { execSync } from "node:child_process"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 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"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -62,7 +62,7 @@ export function registerCommands(
       } catch (err) {
         log.error("/remember failed", err)
         return {
-          text: "Failed to save memory. Is Basic Memory running?",
+          text: `Failed to save memory: ${describeToolError(err)}`,
         }
       }
     },
@@ -89,7 +89,7 @@ export function registerCommands(
         }
 
         const lines = results.map((r, i) => {
-          const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : ""
+          const score = r.score ? ` (score ${r.score.toFixed(2)})` : ""
           return `${i + 1}. ${r.title}${score}`
         })
 
@@ -99,7 +99,7 @@ export function registerCommands(
       } catch (err) {
         log.error("/recall failed", err)
         return {
-          text: "Failed to search. Is Basic Memory running?",
+          text: `Failed to search: ${describeToolError(err)}`,
         }
       }
     },

package/context-engine/basic-memory-context-engine.ts

@@ -1,25 +1,30 @@
-import type {
-  AssembleResult,
-  BootstrapResult,
-  CompactResult,
-  ContextEngine,
-  SubagentSpawnPreparation,
-} from "openclaw/plugin-sdk"
 import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"
 import type { BmClient } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { selectCaptureTurn } from "../hooks/capture.ts"
 import { loadRecallState } from "../hooks/recall.ts"
 import { log } from "../logger.ts"
+import type {
+  AssembleResult,
+  BootstrapResult,
+  CommitTurnResult,
+  CompactResult,
+  ContextEngine,
+  SubagentSpawnPreparation,
+} from "./types.ts"
 
 export const MAX_ASSEMBLE_RECALL_CHARS = 1200
 const TRUNCATED_RECALL_SUFFIX = "\n\n[Basic Memory recall truncated]"
 const SUBAGENT_HANDOFF_FOLDER = "agent/subagents"
 const MAX_SUBAGENT_RECALL_CHARS = 800
+// OpenClaw's reply for "nothing to say", used by heartbeat polls and silent
+// maintenance turns.
+const SILENT_REPLY_TOKEN = "NO_REPLY"
 
 type BootstrapParams = Parameters<NonNullable<ContextEngine["bootstrap"]>>[0]
 type AssembleParams = Parameters<ContextEngine["assemble"]>[0]
 type AfterTurnParams = Parameters<NonNullable<ContextEngine["afterTurn"]>>[0]
+type CommitTurnParams = Parameters<NonNullable<ContextEngine["commitTurn"]>>[0]
 type CompactParams = Parameters<ContextEngine["compact"]>[0]
 type PrepareSubagentSpawnParams = Parameters<
   NonNullable<ContextEngine["prepareSubagentSpawn"]>
@@ -53,6 +58,19 @@ function boundRecallContext(context: string): string {
   return `${trimmed}${TRUNCATED_RECALL_SUFFIX}`
 }
 
+/**
+ * Heartbeat polls and silent replies are host housekeeping, not
+ * conversation, so they are acknowledged without being recorded.
+ */
+function isHousekeepingTurn(
+  isHeartbeat: boolean | undefined,
+  turn: { assistantText: string },
+): boolean {
+  return (
+    isHeartbeat === true || turn.assistantText.trim() === SILENT_REPLY_TOKEN
+  )
+}
+
 function slugifySessionKey(sessionKey: string): string {
   return sessionKey
     .toLowerCase()
@@ -98,7 +116,7 @@ function buildSubagentCompletionUpdate(params: {
 }): string {
   const statusLine =
     params.reason === "completed"
-      ? "Child run completed. Durable conversation capture continues through the normal afterTurn path."
+      ? "Child run completed. Durable conversation capture continues through the normal turn commit path."
       : `Child run ended with reason: ${params.reason}.`
 
   return [
@@ -118,6 +136,18 @@ export class BasicMemoryContextEngine implements ContextEngine {
     name: "Basic Memory Context Engine",
     version: "0.1.5",
     ownsCompaction: false,
+    // OpenClaw 2026.10+ runs an engine for durable turns only when it
+    // declares both semantics; otherwise the turn degrades to "legacy" and
+    // nothing is captured (#1880).
+    // - The fence holds because assemble() passes the host's messages through
+    //   unchanged and the engine keeps no transcript of its own, so it never
+    //   reads past the admitted user entry.
+    // - Advancement is idempotent because commitTurn() records the
+    //   advancement key in the conversation note and skips keys it has seen.
+    transcriptSemantics: {
+      currentTurnFence: "before-current-turn-entry-v1",
+      turnAdvancementIdempotency: "atomic-idempotent-v1",
+    },
   } as const
 
   private readonly sessionState = new Map<string, SessionMemoryState>()
@@ -171,6 +201,41 @@ export class BasicMemoryContextEngine implements ContextEngine {
     }
   }
 
+  /**
+   * Capture one accepted turn on hosts with durable turn advancement.
+   *
+   * The host calls this instead of afterTurn() for admitted turns, and may
+   * call it again with the same advancement key after a crash. Errors
+   * propagate so the host keeps the turn queued and retries it.
+   */
+  async commitTurn(params: CommitTurnParams): Promise<CommitTurnResult> {
+    if (!this.cfg.autoCapture) return { status: "committed" }
+
+    // messages spans exactly the admitted user entry through the terminal
+    // entry, so the whole payload is the current turn.
+    const turn = selectCaptureTurn(params.messages, this.cfg.captureMinChars)
+    if (!turn || isHousekeepingTurn(params.isHeartbeat, turn)) {
+      return { status: "committed" }
+    }
+
+    log.debug(
+      `context-engine commitTurn: session=${params.sessionId} user=${turn.userText.length} assistant=${turn.assistantText.length}`,
+    )
+
+    const status = await this.client.indexConversation(
+      turn.userText,
+      turn.assistantText,
+      { turnKey: params.advancementKey },
+    )
+    return { status }
+  }
+
+  /**
+   * Capture fallback for hosts that predate commitTurn().
+   *
+   * Hosts that route a turn through commitTurn() skip afterTurn() for that
+   * turn, so the two paths never record the same exchange.
+   */
   async afterTurn(params: AfterTurnParams): Promise<void> {
     if (!this.cfg.autoCapture) return
 
@@ -179,7 +244,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
       selectCaptureTurn(newMessages, this.cfg.captureMinChars) ??
       selectCaptureTurn(params.messages, this.cfg.captureMinChars)
 
-    if (!turn) return
+    if (!turn || isHousekeepingTurn(params.isHeartbeat, turn)) return
 
     log.debug(
       `context-engine afterTurn: session=${params.sessionId} user=${turn.userText.length} assistant=${turn.assistantText.length}`,

package/context-engine/types.ts

@@ -0,0 +1,21 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core"
+
+// OpenClaw 2026.10 dropped the bare "openclaw/plugin-sdk" entry point that used
+// to export ContextEngine and its result types. Derive them from the public
+// registerContextEngine signature so we depend only on plugin-sdk/core.
+type ContextEngineFactory = Parameters<
+  OpenClawPluginApi["registerContextEngine"]
+>[1]
+
+export type ContextEngine = Awaited<ReturnType<ContextEngineFactory>>
+export type AssembleResult = Awaited<ReturnType<ContextEngine["assemble"]>>
+export type BootstrapResult = Awaited<
+  ReturnType<NonNullable<ContextEngine["bootstrap"]>>
+>
+export type CompactResult = Awaited<ReturnType<ContextEngine["compact"]>>
+export type SubagentSpawnPreparation = NonNullable<
+  Awaited<ReturnType<NonNullable<ContextEngine["prepareSubagentSpawn"]>>>
+>
+export type CommitTurnResult = Awaited<
+  ReturnType<NonNullable<ContextEngine["commitTurn"]>>
+>

package/dist/bm-client.d.ts

@@ -1,16 +1,17 @@
 export declare class NoteAlreadyExistsError extends Error {
     readonly permalink: string;
-    constructor(title: string, permalink: string);
+    constructor(title: string, permalink: string, message?: string);
 }
 /**
- * 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 declare class NoteRevisionConflictError extends Error {
     readonly permalink: string | null;
     readonly currentChecksum: string | null;
-    constructor(title: string, permalink: string | null, currentChecksum: string | null);
+    constructor(title: string, permalink: string | null, currentChecksum: string | null, message?: string);
 }
 /** A BM MCP tool returned isError; toolMessage is the tool's own error text. */
 export declare class BmToolError extends Error {
@@ -24,7 +25,14 @@ export interface SearchResult {
     content: string;
     score?: number;
     file_path: string;
+    matched_chunk?: string | null;
 }
+/**
+ * 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 declare function searchResultText(result: SearchResult): string;
 export interface NoteResult {
     title: string;
     permalink: string;
@@ -38,7 +46,7 @@ export interface EditNoteResult {
     title: string;
     permalink: string;
     file_path: string;
-    operation: "append" | "prepend" | "find_replace" | "replace_section";
+    operation: EditOperation;
     checksum?: string | null;
 }
 interface ReadNoteOptions {
@@ -55,6 +63,7 @@ interface WriteNoteOptions {
     /** Checksum of the revision read; overwrite only while it is still current. */
     expectedChecksum?: string;
 }
+export type EditOperation = "append" | "prepend" | "find_replace" | "replace_section" | "insert_before_section" | "insert_after_section";
 interface EditNoteOptions {
     find_text?: string;
     section?: string;
@@ -74,7 +83,8 @@ export interface ContextResult {
             permalink: string;
             relation_type?: string;
             from_entity?: string;
-            to_entity?: string;
+            to_entity?: string | null;
+            to_name?: string | null;
         }>;
     }>;
 }
@@ -102,10 +112,7 @@ export interface ProjectListResult {
 export interface WorkspaceResult {
     tenant_id: string;
     name: string;
-    workspace_type: string;
-    role: string;
-    organization_id?: string | null;
-    has_active_subscription: boolean;
+    workspace_type: string | null;
 }
 export interface SchemaValidationResult {
     entity_type: string | null;
@@ -156,21 +163,49 @@ export interface SchemaDiffResult {
     }>;
     cardinality_changes: string[];
 }
+export declare function isNoteNotFoundError(err: unknown): boolean;
+export type ConversationCaptureStatus = "committed" | "duplicate";
+/**
+ * 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 declare function describeToolError(err: unknown): string;
+/** describeToolError, but saying plainly when the note does not exist. */
+export declare function describeNoteError(err: unknown): string;
 export declare class BmClient {
     private bmPath;
     private project;
     private cwd?;
     private env?;
     private shouldRun;
+    private serviceRunning;
+    private startup;
+    private startupRetry;
+    private projectPath?;
+    private prepare?;
     private client;
     private transport;
     private connectPromise;
     private retryDelaysMs;
+    private conversationWrites;
     constructor(bmPath: string, project: string);
+    /**
+     * 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?: {
         cwd?: string;
         env?: Record<string, string>;
+        projectPath?: string;
+        prepare?: () => Promise<void>;
     }): Promise<void>;
+    private runStartup;
+    private waitForStartup;
+    isServiceRunning(): boolean;
     stop(): Promise<void>;
     private connectWithRetries;
     private ensureConnected;
@@ -179,9 +214,11 @@ export declare class BmClient {
     private disconnectCurrent;
     private callToolRaw;
     private callTool;
+    private callStructured;
     private routedProject;
     private routing;
     ensureProject(projectPath: string): Promise<void>;
+    private createProject;
     listWorkspaces(): Promise<WorkspaceResult[]>;
     listProjects(workspace?: string): Promise<ProjectListResult[]>;
     search(query?: string, limit?: number, project?: string, metadata?: {
@@ -195,7 +232,7 @@ export declare class BmClient {
     writeNote(title: string, content: string, folder: string, project?: string, overwrite?: boolean, options?: WriteNoteOptions): Promise<NoteResult>;
     buildContext(url: string, depth?: number, project?: string): Promise<ContextResult>;
     recentActivity(timeframe?: string, project?: string): Promise<RecentResult[]>;
-    editNote(identifier: string, operation: "append" | "prepend" | "find_replace" | "replace_section", content: string, options?: EditNoteOptions, project?: string): Promise<EditNoteResult>;
+    editNote(identifier: string, operation: EditOperation, content: string, options?: EditNoteOptions, project?: string): Promise<EditNoteResult>;
     deleteNote(identifier: string, project?: string): Promise<{
         title: string;
         permalink: string;
@@ -205,7 +242,19 @@ export declare class BmClient {
     schemaValidate(noteType?: string, identifier?: string, project?: string): Promise<SchemaValidationResult>;
     schemaInfer(noteType: string, threshold?: number, project?: string): Promise<SchemaInferResult>;
     schemaDiff(noteType: string, project?: string): Promise<SchemaDiffResult>;
-    indexConversation(userMessage: string, assistantResponse: string): Promise<void>;
+    /**
+     * 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.
+     */
+    indexConversation(userMessage: string, assistantResponse: string, options?: {
+        turnKey?: string;
+    }): Promise<ConversationCaptureStatus>;
+    private writeConversationEntry;
+    private noteContains;
     getProject(): string;
 }
 export {};