@basicmemory/openclaw-basic-memory 0.24.0 → 1.0.0

package/dist/commands/slash.js

@@ -1,6 +1,7 @@
 import { execSync } from "node:child_process";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { describeToolError } from "../bm-client.js";
 import { log } from "../logger.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export function registerCommands(api, client) {
@@ -52,7 +53,7 @@ export function registerCommands(api, client) {
             catch (err) {
                 log.error("/remember failed", err);
                 return {
-                    text: "Failed to save memory. Is Basic Memory running?",
+                    text: `Failed to save memory: ${describeToolError(err)}`,
                 };
             }
         },
@@ -74,7 +75,7 @@ export function registerCommands(api, client) {
                     return { text: `No notes found for: "${query}"` };
                 }
                 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}`;
                 });
                 return {
@@ -84,7 +85,7 @@ export function registerCommands(api, client) {
             catch (err) {
                 log.error("/recall failed", err);
                 return {
-                    text: "Failed to search. Is Basic Memory running?",
+                    text: `Failed to search: ${describeToolError(err)}`,
                 };
             }
         },

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

@@ -1,10 +1,11 @@
-import type { AssembleResult, BootstrapResult, CompactResult, ContextEngine, SubagentSpawnPreparation } from "openclaw/plugin-sdk";
 import type { BmClient } from "../bm-client.ts";
 import type { BasicMemoryConfig } from "../config.ts";
+import type { AssembleResult, BootstrapResult, CommitTurnResult, CompactResult, ContextEngine, SubagentSpawnPreparation } from "./types.ts";
 export declare const MAX_ASSEMBLE_RECALL_CHARS = 1200;
 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"]>>[0];
 type OnSubagentEndedParams = Parameters<NonNullable<ContextEngine["onSubagentEnded"]>>[0];
@@ -16,6 +17,10 @@ export declare class BasicMemoryContextEngine implements ContextEngine {
         readonly name: "Basic Memory Context Engine";
         readonly version: "0.1.5";
         readonly ownsCompaction: false;
+        readonly transcriptSemantics: {
+            readonly currentTurnFence: "before-current-turn-entry-v1";
+            readonly turnAdvancementIdempotency: "atomic-idempotent-v1";
+        };
     };
     private readonly sessionState;
     private readonly subagentState;
@@ -25,6 +30,20 @@ export declare class BasicMemoryContextEngine implements ContextEngine {
         ingested: boolean;
     }>;
     assemble(params: AssembleParams): Promise<AssembleResult>;
+    /**
+     * 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.
+     */
+    commitTurn(params: CommitTurnParams): Promise<CommitTurnResult>;
+    /**
+     * 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.
+     */
     afterTurn(params: AfterTurnParams): Promise<void>;
     compact(params: CompactParams): Promise<CompactResult>;
     prepareSubagentSpawn(params: PrepareSubagentSpawnParams): Promise<SubagentSpawnPreparation | undefined>;

package/dist/context-engine/basic-memory-context-engine.js

@@ -6,6 +6,9 @@ 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";
 function boundRecallContext(context) {
     if (context.length <= MAX_ASSEMBLE_RECALL_CHARS) {
         return context;
@@ -15,6 +18,13 @@ function boundRecallContext(context) {
         .trimEnd();
     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, turn) {
+    return (isHeartbeat === true || turn.assistantText.trim() === SILENT_REPLY_TOKEN);
+}
 function slugifySessionKey(sessionKey) {
     return sessionKey
         .toLowerCase()
@@ -43,7 +53,7 @@ function buildSubagentHandoffContent(params) {
 }
 function buildSubagentCompletionUpdate(params) {
     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 [
         "",
@@ -63,6 +73,18 @@ export class BasicMemoryContextEngine {
         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",
+        },
     };
     sessionState = new Map();
     subagentState = new Map();
@@ -104,13 +126,39 @@ export class BasicMemoryContextEngine {
             systemPromptAddition: state?.recallContext,
         };
     }
+    /**
+     * 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) {
+        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) {
         if (!this.cfg.autoCapture)
             return;
         const newMessages = params.messages.slice(params.prePromptMessageCount);
         const turn = selectCaptureTurn(newMessages, this.cfg.captureMinChars) ??
             selectCaptureTurn(params.messages, this.cfg.captureMinChars);
-        if (!turn)
+        if (!turn || isHousekeepingTurn(params.isHeartbeat, turn))
             return;
         log.debug(`context-engine afterTurn: session=${params.sessionId} user=${turn.userText.length} assistant=${turn.assistantText.length}`);
         try {

package/dist/context-engine/types.d.ts

@@ -0,0 +1,9 @@
+import type { OpenClawPluginApi } from "openclaw/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"]>>>;
+export {};

package/dist/context-engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -1,9 +1,15 @@
-export declare function isCommandAvailable(command: string): boolean;
-declare const _default: {
+export declare function isCommandAvailable(command: string): Promise<boolean>;
+declare const _default: Omit<{
     id: string;
     name: string;
     description: string;
-    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    kind?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["kind"];
+    configSchema?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema | (() => import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema);
+    reload?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["reload"];
+    nodeHostCommands?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["nodeHostCommands"];
+    securityAuditCollectors?: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["securityAuditCollectors"];
     register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
-} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+}, "configSchema"> & {
+    configSchema: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginConfigSchema;
+};
 export default _default;

package/dist/index.js

@@ -1,4 +1,6 @@
-import { execFileSync } from "node:child_process";
+import { execFile } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { promisify } from "node:util";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { BmClient } from "./bm-client.js";
 import { registerCli } from "./commands/cli.js";
@@ -7,6 +9,7 @@ import { registerCommands } from "./commands/slash.js";
 import { basicMemoryConfigSchema, parseConfig, resolveProjectPath, } from "./config.js";
 import { BasicMemoryContextEngine } from "./context-engine/basic-memory-context-engine.js";
 import { initLogger, log } from "./logger.js";
+import { buildBasicMemoryCapability } from "./memory/basic-memory-capability.js";
 import { CONVERSATION_SCHEMA_CONTENT } from "./schema/conversation-schema.js";
 import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.js";
 import { registerContextTool } from "./tools/build-context.js";
@@ -14,7 +17,6 @@ import { registerDeleteTool } from "./tools/delete-note.js";
 import { registerEditTool } from "./tools/edit-note.js";
 import { registerProjectListTool } from "./tools/list-memory-projects.js";
 import { registerWorkspaceListTool } from "./tools/list-workspaces.js";
-import { registerMemoryProvider, setWorkspaceDir, } from "./tools/memory-provider.js";
 import { registerMoveTool } from "./tools/move-note.js";
 import { registerReadTool } from "./tools/read-note.js";
 import { registerSchemaDiffTool } from "./tools/schema-diff.js";
@@ -22,19 +24,60 @@ import { registerSchemaInferTool } from "./tools/schema-infer.js";
 import { registerSchemaValidateTool } from "./tools/schema-validate.js";
 import { registerSearchTool } from "./tools/search-notes.js";
 import { registerWriteTool } from "./tools/write-note.js";
-export function isCommandAvailable(command) {
+const execFileAsync = promisify(execFile);
+// Async so a probe or an install never blocks OpenClaw's event loop during
+// plugin startup.
+export async function isCommandAvailable(command) {
     try {
-        execFileSync(command, ["--version"], { stdio: "ignore" });
+        await execFileAsync(command, ["--version"]);
         return true;
     }
     catch {
         return false;
     }
 }
+async function installBasicMemoryIfMissing(bmBin) {
+    if (await isCommandAvailable(bmBin))
+        return;
+    log.info("bm CLI not found on PATH — attempting auto-install...");
+    if (!(await isCommandAvailable("uv"))) {
+        throw new Error("Cannot auto-install basic-memory: uv not found. " +
+            "Install uv first (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh), " +
+            "then restart the gateway.");
+    }
+    log.info("installing basic-memory via uv (this may take a minute)...");
+    // basic-memory pins a FastMCP pre-release; without this flag uv silently
+    // installs the last release that had none (#1338).
+    const { stdout } = await execFileAsync("uv", ["tool", "install", "basic-memory", "--prerelease=allow", "--force"], { encoding: "utf-8", timeout: 120_000 });
+    log.info(`basic-memory installed: ${stdout.trim().split("\n").pop()}`);
+    if (!(await isCommandAvailable(bmBin))) {
+        throw new Error("bm installed but not found on PATH. You may need to add uv's bin directory to your PATH (typically ~/.local/bin).");
+    }
+}
+async function seedSchemas(client) {
+    for (const [name, content] of [
+        ["Task", TASK_SCHEMA_CONTENT],
+        ["Conversation", CONVERSATION_SCHEMA_CONTENT],
+    ]) {
+        try {
+            await client.readNote(`schema/${name}`);
+            log.debug(`${name} schema already exists, skipping seed`);
+        }
+        catch {
+            try {
+                await client.writeNote(name, content, "schema");
+                log.debug(`seeded ${name} schema note`);
+            }
+            catch (err) {
+                log.debug(`${name} schema seed failed (non-fatal)`, err);
+            }
+        }
+    }
+}
 export default definePluginEntry({
     id: "openclaw-basic-memory",
     name: "Basic Memory",
-    description: "Local-first knowledge graph for OpenClaw — persistent memory with graph search and composited memory_search",
+    description: "Local-first knowledge graph for OpenClaw — persistent memory with graph search, recall and conversation capture",
     configSchema: basicMemoryConfigSchema,
     register(api) {
         const cfg = parseConfig(api.pluginConfig);
@@ -54,9 +97,14 @@ export default definePluginEntry({
         registerSchemaValidateTool(api, client);
         registerSchemaInferTool(api, client);
         registerSchemaDiffTool(api, client);
-        // --- Composited memory_search + memory_get (always registered) ---
-        registerMemoryProvider(api, client, cfg);
-        log.info("registered composited memory_search + memory_get");
+        // --- Memory capability ---
+        // OpenClaw 2026.10 owns the memory_search and memory_get tool names
+        // (memory-core registers them even when another plugin holds the memory
+        // slot), so the plugin serves the host through registerMemoryCapability:
+        // gateway memory search, status and doctor, Active Memory recall, and the
+        // pre-compaction flush.
+        api.registerMemoryCapability(buildBasicMemoryCapability(client));
+        log.info("registered Basic Memory memory capability");
         api.registerContextEngine("openclaw-basic-memory", () => new BasicMemoryContextEngine(client, cfg));
         log.info("registered Basic Memory context engine");
         // --- Commands ---
@@ -68,70 +116,32 @@ export default definePluginEntry({
             id: "openclaw-basic-memory",
             start: async (ctx) => {
                 log.info("starting...");
-                // Auto-install bm CLI if not found
-                const bmBin = cfg.bmPath || "bm";
-                if (!isCommandAvailable(bmBin)) {
-                    log.info("bm CLI not found on PATH — attempting auto-install...");
-                    try {
-                        if (!isCommandAvailable("uv")) {
-                            throw new Error("uv not found");
-                        }
-                        log.info("installing basic-memory via uv (this may take a minute)...");
-                        // basic-memory pins a FastMCP pre-release; without this flag uv
-                        // silently installs the last release that had none (#1338).
-                        const result = execFileSync("uv", [
-                            "tool",
-                            "install",
-                            "basic-memory",
-                            "--prerelease=allow",
-                            "--force",
-                        ], {
-                            encoding: "utf-8",
-                            timeout: 120_000,
-                            stdio: ["ignore", "pipe", "pipe"],
-                        });
-                        log.info(`basic-memory installed: ${result.trim().split("\n").pop()}`);
-                        // Verify it worked
-                        if (isCommandAvailable(bmBin)) {
-                            log.info("bm CLI now available on PATH");
-                        }
-                        else {
-                            log.error("bm installed but not found on PATH. You may need to add uv's bin directory to your PATH (typically ~/.local/bin).");
-                        }
-                    }
-                    catch (_uvErr) {
-                        log.error("Cannot auto-install basic-memory: uv not found. " +
-                            "Install uv first (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh), " +
-                            "then restart the gateway.");
-                    }
-                }
                 const workspace = ctx.workspaceDir ?? process.cwd();
                 const projectPath = resolveProjectPath(cfg.projectPath, workspace);
                 cfg.projectPath = projectPath;
-                await client.start({ cwd: workspace });
-                await client.ensureProject(projectPath);
-                log.debug(`project "${cfg.project}" at ${projectPath}`);
-                // Seed schemas if not already present
-                for (const [name, content] of [
-                    ["Task", TASK_SCHEMA_CONTENT],
-                    ["Conversation", CONVERSATION_SCHEMA_CONTENT],
-                ]) {
-                    try {
-                        await client.readNote(`schema/${name}`);
-                        log.debug(`${name} schema already exists, skipping seed`);
-                    }
-                    catch {
-                        try {
-                            await client.writeNote(name, content, "schema");
-                            log.debug(`seeded ${name} schema note`);
-                        }
-                        catch (err) {
-                            log.debug(`${name} schema seed failed (non-fatal)`, err);
-                        }
-                    }
-                }
-                setWorkspaceDir(workspace);
-                log.info("connected — BM MCP stdio session running");
+                // bm runs with the workspace as its working directory. OpenClaw
+                // creates its default workspace only on the first agent run, and
+                // spawning into a missing directory fails with an ENOENT that names
+                // the bm binary instead of the directory.
+                await mkdir(workspace, { recursive: true });
+                // OpenClaw gives a service about 5 s to start. A first start (bm
+                // install, cold imports, first indexing) takes far longer, and a
+                // timed-out start fails the plugin. So startup runs in the
+                // background; tool calls wait for it inside BmClient, and a failed
+                // startup is retried by the next tool call instead of failing here.
+                client
+                    .start({
+                    cwd: workspace,
+                    projectPath,
+                    prepare: () => installBasicMemoryIfMissing(cfg.bmPath || "bm"),
+                })
+                    .then(async () => {
+                    log.info("connected — BM MCP stdio session running");
+                    await seedSchemas(client);
+                })
+                    .catch((err) => {
+                    log.error("Basic Memory startup failed; the next tool call will retry", err);
+                });
             },
             stop: async () => {
                 log.info("stopping BM MCP session...");

package/dist/memory/basic-memory-capability.d.ts

@@ -0,0 +1,19 @@
+import type { MemoryPluginCapability } from "openclaw/plugin-sdk/memory-host-core";
+import { type BmClient } from "../bm-client.ts";
+type MemoryProviderRuntime = NonNullable<MemoryPluginCapability["providerRuntime"]>;
+type MemoryProviderHandle = NonNullable<Awaited<ReturnType<MemoryProviderRuntime["open"]>>["provider"]>;
+type MemoryCallerContext = Parameters<MemoryProviderRuntime["open"]>[0]["context"];
+export declare const MEMORY_PROVIDER_ID = "openclaw-basic-memory";
+export declare const RECALL_TOOL_NAMES: readonly ["search_notes", "read_note", "build_context"];
+/**
+ * Open a caller-bound reader over the plugin's shared BM MCP session.
+ *
+ * The host rechecks the caller's authority around every provider call;
+ * context.assertCurrent() is also called before and after each BM request so
+ * a revoked caller is refused rather than served. Every note in the project
+ * is visible to every caller, which matches what the plugin's own
+ * search_notes and read_note tools already expose.
+ */
+export declare function openBasicMemoryReader(client: BmClient, context: MemoryCallerContext): MemoryProviderHandle;
+export declare function buildBasicMemoryCapability(client: BmClient): MemoryPluginCapability;
+export {};

package/dist/memory/basic-memory-capability.js

@@ -0,0 +1,190 @@
+import { isNoteNotFoundError, searchResultText, } from "../bm-client.js";
+import { log } from "../logger.js";
+export const MEMORY_PROVIDER_ID = "openclaw-basic-memory";
+// Agent tools this plugin registers that Active Memory may use for deep
+// recall, and that the pre-compaction flush may use to look before writing.
+export const RECALL_TOOL_NAMES = [
+    "search_notes",
+    "read_note",
+    "build_context",
+];
+const FLUSH_PERSISTENCE_TOOL_NAMES = ["write_note", "edit_note"];
+const FLUSH_LOOKUP_TOOL_NAMES = ["search_notes", "read_note"];
+const DEFAULT_MAX_RESULTS = 10;
+const MAX_EXCERPT_CHARS = 700;
+// memory-core's flush prompts use the same token for "nothing to save".
+const SILENT_REPLY_TOKEN = "NO_REPLY";
+// --- Search and retrieval ---
+/**
+ * Basic Memory fuses keyword and vector scores into [0, 1.3] (see
+ * search_reader.py FUSION_BONUS). OpenClaw compares provider scores against a
+ * caller's minScore on a 0–1 scale, so a fused score above 1 is capped at 1.
+ */
+function hostScore(score) {
+    return score === undefined ? undefined : Math.min(score, 1);
+}
+function excerptOf(content) {
+    return content.length > MAX_EXCERPT_CHARS
+        ? `${content.slice(0, MAX_EXCERPT_CHARS)}…`
+        : content;
+}
+/**
+ * Apply the host's optional line window to a note body. `from` is 1-based,
+ * matching the host's memory_get contract.
+ */
+function sliceLines(text, from, lines) {
+    if (from === undefined && lines === undefined)
+        return { text };
+    const all = text.split("\n");
+    const start = Math.max(1, from ?? 1);
+    const count = lines ?? all.length - start + 1;
+    const window = all.slice(start - 1, start - 1 + count);
+    const end = start - 1 + window.length;
+    const truncated = end < all.length;
+    return {
+        text: window.join("\n"),
+        from: start,
+        lines: window.length,
+        truncated,
+        ...(truncated ? { nextFrom: end + 1 } : {}),
+    };
+}
+/**
+ * Open a caller-bound reader over the plugin's shared BM MCP session.
+ *
+ * The host rechecks the caller's authority around every provider call;
+ * context.assertCurrent() is also called before and after each BM request so
+ * a revoked caller is refused rather than served. Every note in the project
+ * is visible to every caller, which matches what the plugin's own
+ * search_notes and read_note tools already expose.
+ */
+export function openBasicMemoryReader(client, context) {
+    const guarded = async (run) => {
+        context.assertCurrent();
+        const result = await run();
+        context.assertCurrent();
+        return result;
+    };
+    // Trigger: the reader opens while the plugin service is not running, as in
+    //   one-shot CLI commands like `openclaw memory status`.
+    // Why: the first BM call then spawns a `bm mcp` child that nothing else
+    //   will stop, and its open pipes keep the CLI process from exiting.
+    // Outcome: this reader owns that connection and stops it on close().
+    const ownsConnection = !client.isServiceRunning();
+    return {
+        capabilities: {
+            sources: ["memory"],
+            pagination: false,
+            candidates: [],
+            projectFilter: false,
+        },
+        async search(request) {
+            const results = await guarded(() => client.search(request.query, request.maxResults ?? DEFAULT_MAX_RESULTS));
+            const hits = results
+                .map((result) => ({ result, score: hostScore(result.score) }))
+                // Trigger: the caller set a score floor.
+                // Why: the host contract requires every provider to enforce minScore.
+                // Outcome: unscored or lower-scored hits are dropped.
+                .filter(({ score }) => request.minScore === undefined ||
+                (score !== undefined && score >= request.minScore))
+                .map(({ result, score }) => ({
+                reference: { providerId: MEMORY_PROVIDER_ID, id: result.permalink },
+                excerpt: excerptOf(searchResultText(result)),
+                source: result.file_path,
+                ...(score === undefined ? {} : { score }),
+            }));
+            return { hits };
+        },
+        async get(request) {
+            try {
+                const note = await guarded(() => client.readNote(request.reference.id));
+                return {
+                    status: "ok",
+                    reference: { providerId: MEMORY_PROVIDER_ID, id: note.permalink },
+                    ...sliceLines(note.content, request.from, request.lines),
+                };
+            }
+            catch (err) {
+                // A missing note is an answer; any other failure must surface so the
+                // host does not report it as an empty success.
+                if (isNoteNotFoundError(err))
+                    return { status: "not_found" };
+                throw err;
+            }
+        },
+        async health() {
+            // Listing projects proves the BM MCP session answers without reading
+            // any note content, so it is safe for status-only callers.
+            try {
+                await guarded(() => client.listProjects());
+                return { status: "ready" };
+            }
+            catch (err) {
+                log.warn(`memory health check failed: ${err instanceof Error ? err.message : String(err)}`);
+                return {
+                    status: "unavailable",
+                    message: "Basic Memory is not reachable",
+                };
+            }
+        },
+        // In the gateway the BM MCP session is shared by the whole plugin and
+        // owned by its service, so closing one caller's reader releases nothing.
+        async close() {
+            if (ownsConnection)
+                await client.stop();
+        },
+    };
+}
+// --- Pre-compaction flush ---
+const FLUSH_PROMPT = [
+    "Pre-compaction memory flush.",
+    "Save durable facts, decisions and open tasks from this session to Basic Memory.",
+    "Use search_notes or read_note first to find an existing note, then edit_note to update it;",
+    "use write_note only for a new topic.",
+    `If nothing is worth saving, reply with ${SILENT_REPLY_TOKEN}.`,
+].join(" ");
+const FLUSH_SYSTEM_PROMPT = [
+    "Pre-compaction memory flush turn.",
+    "The session is near auto-compaction; capture durable memories in Basic Memory with write_note or edit_note.",
+    `You may reply, but usually ${SILENT_REPLY_TOKEN} is correct.`,
+].join(" ");
+// Returning a tools-arm plan makes the host persist through this plugin's own
+// tools instead of appending to a workspace memory file. The host has already
+// honored agents.defaults.compaction.memoryFlush.enabled before calling this.
+const resolveFlushPlan = () => ({
+    prompt: FLUSH_PROMPT,
+    systemPrompt: FLUSH_SYSTEM_PROMPT,
+    persistenceToolNames: FLUSH_PERSISTENCE_TOOL_NAMES,
+    lookupToolNames: FLUSH_LOOKUP_TOOL_NAMES,
+});
+// --- Prompt guidance ---
+/**
+ * OpenClaw fills any capability field the slot owner leaves empty from other
+ * memory registrations, including memory-core's prompt section, which points
+ * agents at its file-only memory_search. Supplying our own section keeps the
+ * agent's guidance on the Basic Memory tools.
+ */
+function buildPromptSection(params) {
+    if (!params.availableTools.has("search_notes"))
+        return [];
+    return [
+        "## Basic Memory",
+        "Long-term memory lives in Basic Memory, a knowledge graph of Markdown notes.",
+        "Before answering questions about prior work, decisions, people or preferences, search it with search_notes and read the best match with read_note.",
+        "Earlier conversations are saved automatically in daily conversation notes.",
+        "memory_search and memory_get cover only the workspace MEMORY.md and memory/ files, not Basic Memory.",
+    ];
+}
+// --- Capability ---
+export function buildBasicMemoryCapability(client) {
+    return {
+        providerRuntime: {
+            async open({ context }) {
+                return { provider: openBasicMemoryReader(client, context) };
+            },
+        },
+        recallToolNames: RECALL_TOOL_NAMES,
+        providerFlushPlanResolver: resolveFlushPlan,
+        promptBuilder: buildPromptSection,
+    };
+}

package/dist/tools/build-context.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 registerContextTool(api: OpenClawPluginApi, client: BmClient): void;