@basicmemory/openclaw-basic-memory 0.24.1 → 1.0.0

package/index.ts

@@ -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.ts"
@@ -12,6 +14,7 @@ import {
 } from "./config.ts"
 import { BasicMemoryContextEngine } from "./context-engine/basic-memory-context-engine.ts"
 import { initLogger, log } from "./logger.ts"
+import { buildBasicMemoryCapability } from "./memory/basic-memory-capability.ts"
 import { CONVERSATION_SCHEMA_CONTENT } from "./schema/conversation-schema.ts"
 import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.ts"
 import { registerContextTool } from "./tools/build-context.ts"
@@ -19,10 +22,6 @@ import { registerDeleteTool } from "./tools/delete-note.ts"
 import { registerEditTool } from "./tools/edit-note.ts"
 import { registerProjectListTool } from "./tools/list-memory-projects.ts"
 import { registerWorkspaceListTool } from "./tools/list-workspaces.ts"
-import {
-  registerMemoryProvider,
-  setWorkspaceDir,
-} from "./tools/memory-provider.ts"
 import { registerMoveTool } from "./tools/move-note.ts"
 import { registerReadTool } from "./tools/read-note.ts"
 import { registerSchemaDiffTool } from "./tools/schema-diff.ts"
@@ -31,20 +30,71 @@ import { registerSchemaValidateTool } from "./tools/schema-validate.ts"
 import { registerSearchTool } from "./tools/search-notes.ts"
 import { registerWriteTool } from "./tools/write-note.ts"
 
-export function isCommandAvailable(command: string): boolean {
+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: string): Promise<boolean> {
   try {
-    execFileSync(command, ["--version"], { stdio: "ignore" })
+    await execFileAsync(command, ["--version"])
     return true
   } catch {
     return false
   }
 }
 
+async function installBasicMemoryIfMissing(bmBin: string): Promise<void> {
+  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: BmClient): Promise<void> {
+  for (const [name, content] of [
+    ["Task", TASK_SCHEMA_CONTENT],
+    ["Conversation", CONVERSATION_SCHEMA_CONTENT],
+  ] as const) {
+    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",
+    "Local-first knowledge graph for OpenClaw — persistent memory with graph search, recall and conversation capture",
   configSchema: basicMemoryConfigSchema,
 
   register(api) {
@@ -72,9 +122,14 @@ export default definePluginEntry({
     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),
@@ -92,83 +147,37 @@ export default definePluginEntry({
       start: async (ctx: { config?: unknown; workspaceDir?: string }) => {
         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],
-        ] as const) {
-          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/memory/basic-memory-capability.ts

@@ -0,0 +1,253 @@
+import type { MemoryPluginCapability } from "openclaw/plugin-sdk/memory-host-core"
+import {
+  type BmClient,
+  isNoteNotFoundError,
+  searchResultText,
+} from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+// OpenClaw documents deriving the provider types from the public capability
+// type rather than importing its private memory-host-search facade.
+type MemoryProviderRuntime = NonNullable<
+  MemoryPluginCapability["providerRuntime"]
+>
+type MemoryProviderHandle = NonNullable<
+  Awaited<ReturnType<MemoryProviderRuntime["open"]>>["provider"]
+>
+type MemorySearchRequest = Parameters<MemoryProviderHandle["search"]>[0]
+type MemorySearchPage = Awaited<ReturnType<MemoryProviderHandle["search"]>>
+type MemoryGetRequest = Parameters<MemoryProviderHandle["get"]>[0]
+type MemoryGetResult = Awaited<ReturnType<MemoryProviderHandle["get"]>>
+type MemoryHealth = Awaited<ReturnType<MemoryProviderHandle["health"]>>
+type MemoryCallerContext = Parameters<
+  MemoryProviderRuntime["open"]
+>[0]["context"]
+type MemoryProviderFlushPlanResolver = NonNullable<
+  MemoryPluginCapability["providerFlushPlanResolver"]
+>
+
+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",
+] as const
+const FLUSH_PERSISTENCE_TOOL_NAMES = ["write_note", "edit_note"] as const
+const FLUSH_LOOKUP_TOOL_NAMES = ["search_notes", "read_note"] as const
+
+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: number | undefined): number | undefined {
+  return score === undefined ? undefined : Math.min(score, 1)
+}
+
+function excerptOf(content: string): string {
+  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: string,
+  from: number | undefined,
+  lines: number | undefined,
+): Pick<
+  Extract<MemoryGetResult, { status: "ok" }>,
+  "text" | "truncated" | "from" | "lines" | "nextFrom"
+> {
+  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: BmClient,
+  context: MemoryCallerContext,
+): MemoryProviderHandle {
+  const guarded = async <T>(run: () => Promise<T>): Promise<T> => {
+    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: MemorySearchRequest): Promise<MemorySearchPage> {
+      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: MemoryGetRequest): Promise<MemoryGetResult> {
+      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(): Promise<MemoryHealth> {
+      // 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(): Promise<void> {
+      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: MemoryProviderFlushPlanResolver = () => ({
+  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: { availableTools: Set<string> }): string[] {
+  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: BmClient,
+): MemoryPluginCapability {
+  return {
+    providerRuntime: {
+      async open({ context }) {
+        return { provider: openBasicMemoryReader(client, context) }
+      },
+    },
+    recallToolNames: RECALL_TOOL_NAMES,
+    providerFlushPlanResolver: resolveFlushPlan,
+    promptBuilder: buildPromptSection,
+  }
+}

package/openclaw.plugin.json

@@ -8,8 +8,6 @@
       "edit_note",
       "list_memory_projects",
       "list_workspaces",
-      "memory_get",
-      "memory_search",
       "move_note",
       "read_note",
       "schema_diff",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.24.1",
+  "version": "1.0.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -15,6 +15,8 @@
     "index.ts",
     "bm-client.ts",
     "context-engine/basic-memory-context-engine.ts",
+    "context-engine/types.ts",
+    "memory/basic-memory-capability.ts",
     "config.ts",
     "logger.ts",
     "commands/cli.ts",
@@ -27,7 +29,6 @@
     "tools/edit-note.ts",
     "tools/list-memory-projects.ts",
     "tools/list-workspaces.ts",
-    "tools/memory-provider.ts",
     "tools/move-note.ts",
     "tools/read-note.ts",
     "tools/schema-diff.ts",
@@ -80,8 +81,8 @@
       "minGatewayVersion": "2026.5.2"
     },
     "build": {
-      "openclawVersion": "2026.5.4",
-      "pluginSdkVersion": "2026.5.4"
+      "openclawVersion": "2026.10.9",
+      "pluginSdkVersion": "2026.10.9"
     },
     "install": {
       "minHostVersion": ">=2026.5.2"
@@ -90,7 +91,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
     "@types/node": "^20.0.0",
-    "openclaw": "^2026.5.4",
+    "openclaw": "^2026.10.6",
     "typescript": "^5.9.3"
   }
 }

package/skills/manifest.json

@@ -29,6 +29,11 @@
     "name": "memory-defrag",
     "description": "Defragment a Basic Memory project: split bloated notes, consolidate scattered facts, resolve contradictions, retire stale content. Plans first; deletes only when told. Run weekly or on demand."
   },
+  {
+    "dir": "memory-doctor",
+    "name": "memory-doctor",
+    "description": "Check local Basic Memory projects with bm doctor, explain the findings, and run the suggested fixes once the user agrees. Use when search misses or repeats notes, or a save looks lost."
+  },
   {
     "dir": "memory-ingest",
     "name": "memory-ingest",

package/skills/memory-agents/SKILL.md

@@ -11,7 +11,19 @@ short-lived agent in Cloud that reads the target, works through the Basic Memory
 tools, and changes notes as its instructions say.
 
 Agents run in Basic Memory Cloud only, on plans that include them. A local
-Basic Memory has no agent tools.
+Basic Memory has no agent tools. Confirm the connected server exposes `bm_agent`
+before starting this workflow.
+
+## Project scope
+
+If the project is unknown, discover it with `bm_project(command="list")`.
+Pass a nonempty `project` on every note, folder, context and schema call, even
+with one project or a qualified `memory://` URL. Use the chosen project's name,
+`workspace/project`, or external ID; `<project>` below is a placeholder for it.
+Recent activity also requires `project`. Search accepts `project` for one
+project, `projects` for selected projects, or `all_projects=True` explicitly.
+Discovery and bundled manuals need no project. Keep the same scope when following
+returned paths, paginating, or recovering from a refusal.
 
 ## When to Use
 
@@ -24,12 +36,13 @@ Basic Memory has no agent tools.
 
 | Tool | Does |
 |---|---|
-| `list_agents` | The project's agents and how their recent runs went |
-| `run_agent` | Starts an agent on a note; returns the run id |
-| `get_agent_run` | One run: status, notes changed, and the agent's last reply |
-| `list_agent_runs` | Recent runs, newest first, optionally for one agent |
+| `bm_agent(command="list", project="<project>")` | The project's agents and how their recent runs went |
+| `bm_agent(command="run", project="<project>")` | Starts an agent on a note; returns the run id |
+| `bm_agent(command="get", project="<project>")` | One run: status, notes changed, and the agent's last reply |
+| `bm_agent(command="runs", project="<project>")` | Recent runs, newest first, optionally for one agent |
+| `bm_agent(command="mark", project="<project>")` | Mark a run `kept` or `dismissed` with `run_id` and `decision` |
 
-Create and edit agents with `write_note` and `edit_note`. There is no separate
+Create and edit agents with `bm_write` and `bm_edit`. There is no separate
 agent tool for that.
 
 ## Write an Agent
@@ -112,10 +125,10 @@ Point the user to these before writing an agent from scratch.
 ## Run an Agent
 
 ```python
-list_agents(project="work")
-run_agent(agent="Curator", note="projects/Launch", project="work")
+bm_agent(command="list", project="work")
+bm_agent(command="run", agent="Curator", identifier="projects/Launch", project="work")
 # -> run id. Runs usually take one to a few minutes.
-get_agent_run(run_id="<run id>", project="work")
+bm_agent(command="get", run_id="<run id>", project="work")
 ```
 
 An agent changes the user's notes. Ask before running one, unless the user has
@@ -128,7 +141,7 @@ on the version the person ended with. Notes written by agents, imports, or
 
 ## Check a Run
 
-`get_agent_run` shows the status, the notes the run created, edited, moved, or
+`bm_agent(command="get", project="<project>")` shows the status, the notes the run created, edited, moved, or
 deleted, and the agent's last reply. Every reply is also kept in a run log note, `agents/runs/<agent> run <id>`. Read it for the whole
 conversation; do not edit it.