@basicmemory/openclaw-basic-memory 0.2.3 → 0.23.0

package/dist/tools/schema-infer.js

@@ -0,0 +1,66 @@
+import { Type } from "@sinclair/typebox";
+import { log } from "../logger.js";
+export function registerSchemaInferTool(api, client) {
+    api.registerTool({
+        name: "schema_infer",
+        label: "Schema Infer",
+        description: "Analyze existing notes of a given type and suggest a Picoschema definition. " +
+            "Examines observation categories and relation types to infer required and optional fields.",
+        parameters: Type.Object({
+            noteType: Type.String({
+                description: 'The note type to analyze (e.g., "person", "meeting", "Task")',
+            }),
+            threshold: Type.Optional(Type.Number({
+                description: "Minimum frequency (0-1) for a field to be suggested as optional. Default 0.25.",
+            })),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            log.debug(`schema_infer: noteType="${params.noteType}" threshold=${params.threshold ?? 0.25}`);
+            try {
+                const result = await client.schemaInfer(params.noteType, params.threshold, params.project);
+                const lines = [
+                    `**Type:** ${result.entity_type}`,
+                    `**Notes analyzed:** ${result.notes_analyzed}`,
+                ];
+                if (result.suggested_required.length > 0) {
+                    lines.push(`**Required fields:** ${result.suggested_required.join(", ")}`);
+                }
+                if (result.suggested_optional.length > 0) {
+                    lines.push(`**Optional fields:** ${result.suggested_optional.join(", ")}`);
+                }
+                if (result.field_frequencies.length > 0) {
+                    lines.push("", "### Field Frequencies");
+                    for (const f of result.field_frequencies) {
+                        lines.push(`- **${f.name}** — ${(f.percentage * 100).toFixed(0)}% (${f.count} notes)`);
+                    }
+                }
+                if (Object.keys(result.suggested_schema).length > 0) {
+                    lines.push("", "### Suggested Schema", "```json", JSON.stringify(result.suggested_schema, null, 2), "```");
+                }
+                return {
+                    content: [{ type: "text", text: lines.join("\n") }],
+                    details: result,
+                };
+            }
+            catch (err) {
+                log.error("schema_infer failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Schema inference failed. Check logs for details.",
+                        },
+                    ],
+                    details: {
+                        noteType: params.noteType,
+                        threshold: params.threshold ?? 0.25,
+                        error: "schema_infer_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "schema_infer" });
+}

package/dist/tools/schema-validate.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { BmClient } from "../bm-client.ts";
+export declare function registerSchemaValidateTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/schema-validate.js

@@ -0,0 +1,73 @@
+import { Type } from "@sinclair/typebox";
+import { log } from "../logger.js";
+export function registerSchemaValidateTool(api, client) {
+    api.registerTool({
+        name: "schema_validate",
+        label: "Schema Validate",
+        description: "Validate notes against their Picoschema definitions. " +
+            "Validates a specific note by identifier, or all notes of a given type.",
+        parameters: Type.Object({
+            noteType: Type.Optional(Type.String({
+                description: 'Note type to batch-validate (e.g., "person", "meeting")',
+            })),
+            identifier: Type.Optional(Type.String({
+                description: "Specific note to validate (permalink, title, or path)",
+            })),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            log.debug(`schema_validate: noteType="${params.noteType ?? ""}" identifier="${params.identifier ?? ""}"`);
+            try {
+                const result = await client.schemaValidate(params.noteType, params.identifier, params.project);
+                // Handle error responses from BM (e.g., no schema found)
+                const resultRecord = result;
+                if ("error" in result && typeof resultRecord.error === "string") {
+                    return {
+                        content: [{ type: "text", text: resultRecord.error }],
+                        details: result,
+                    };
+                }
+                const lines = [];
+                if (result.entity_type) {
+                    lines.push(`**Type:** ${result.entity_type}`);
+                }
+                lines.push(`**Notes:** ${result.total_notes ?? 0} | **Valid:** ${result.valid_count ?? 0} | **Warnings:** ${result.warning_count ?? 0} | **Errors:** ${result.error_count ?? 0}`);
+                if (result.results && result.results.length > 0) {
+                    lines.push("");
+                    for (const r of result.results) {
+                        const status = r.valid ? "valid" : "invalid";
+                        lines.push(`- **${r.identifier}** — ${status}`);
+                        for (const w of r.warnings) {
+                            lines.push(`  - warning: ${w}`);
+                        }
+                        for (const e of r.errors) {
+                            lines.push(`  - error: ${e}`);
+                        }
+                    }
+                }
+                return {
+                    content: [{ type: "text", text: lines.join("\n") }],
+                    details: result,
+                };
+            }
+            catch (err) {
+                log.error("schema_validate failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Schema validation failed. Check logs for details.",
+                        },
+                    ],
+                    details: {
+                        noteType: params.noteType ?? null,
+                        identifier: params.identifier ?? null,
+                        error: "schema_validate_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "schema_validate" });
+}

package/dist/tools/search-notes.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { BmClient } from "../bm-client.ts";
+export declare function registerSearchTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/search-notes.js

@@ -0,0 +1,97 @@
+import { Type } from "@sinclair/typebox";
+import { log } from "../logger.js";
+export function registerSearchTool(api, client) {
+    api.registerTool({
+        name: "search_notes",
+        label: "Knowledge Search",
+        description: "Search the Basic Memory knowledge graph for relevant notes, concepts, and connections. " +
+            "Returns matching notes with titles, content previews, and relevance scores. " +
+            "Optionally filter by frontmatter metadata fields, tags, or status.",
+        parameters: Type.Object({
+            query: Type.String({ description: "Search query" }),
+            limit: Type.Optional(Type.Number({ description: "Max results (default: 10)" })),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+            metadata_filters: Type.Optional(Type.Object({}, {
+                additionalProperties: true,
+                description: "Filter by frontmatter fields. Supports equality, $in, $gt/$gte/$lt/$lte, $between, and array-contains operators.",
+            })),
+            tags: Type.Optional(Type.Array(Type.String(), {
+                description: "Filter by frontmatter tags (all must match)",
+            })),
+            status: Type.Optional(Type.String({
+                description: "Filter by frontmatter status field",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            const limit = params.limit ?? 10;
+            log.debug(`search_notes: query="${params.query}" limit=${limit} project="${params.project ?? "default"}"`);
+            const metadata = params.metadata_filters || params.tags || params.status
+                ? {
+                    filters: params.metadata_filters,
+                    tags: params.tags,
+                    status: params.status,
+                }
+                : undefined;
+            try {
+                const results = await client.search(params.query, limit, params.project, metadata);
+                if (results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "No matching notes found in the knowledge graph.",
+                            },
+                        ],
+                        details: {
+                            count: 0,
+                            results: [],
+                        },
+                    };
+                }
+                const text = results
+                    .map((r, i) => {
+                    const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : "";
+                    const content = r.content ?? "";
+                    const preview = content.length > 200 ? `${content.slice(0, 200)}...` : content;
+                    return `${i + 1}. **${r.title}**${score}\n   ${preview}`;
+                })
+                    .join("\n\n");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Found ${results.length} notes:\n\n${text}`,
+                        },
+                    ],
+                    details: {
+                        count: results.length,
+                        results: results.map((r) => ({
+                            title: r.title,
+                            permalink: r.permalink,
+                            score: r.score,
+                        })),
+                    },
+                };
+            }
+            catch (err) {
+                log.error("search_notes failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Search failed. Is Basic Memory running? Check logs for details.",
+                        },
+                    ],
+                    details: {
+                        count: 0,
+                        results: [],
+                        query: params.query,
+                        error: "search_notes_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "search_notes" });
+}

package/dist/tools/write-note.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { BmClient } from "../bm-client.ts";
+export declare function registerWriteTool(api: OpenClawPluginApi, client: BmClient): void;

package/dist/tools/write-note.js

@@ -0,0 +1,80 @@
+import { Type } from "@sinclair/typebox";
+import { NoteAlreadyExistsError } from "../bm-client.js";
+import { log } from "../logger.js";
+export function registerWriteTool(api, client) {
+    api.registerTool({
+        name: "write_note",
+        label: "Write Note",
+        description: "Create a note in the Basic Memory knowledge graph. " +
+            "If the note already exists, returns an error by default. " +
+            "Pass overwrite=true to replace, or use edit_note for incremental updates.",
+        parameters: Type.Object({
+            title: Type.String({ description: "Note title" }),
+            content: Type.String({
+                description: "Note content in Markdown format",
+            }),
+            folder: Type.String({ description: "Folder to write the note in" }),
+            project: Type.Optional(Type.String({
+                description: "Target project name (defaults to current project)",
+            })),
+            overwrite: Type.Optional(Type.Boolean({
+                description: "Set to true to replace an existing note. Defaults to false.",
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            log.debug(`write_note: title=${params.title} folder=${params.folder}`);
+            try {
+                const note = await client.writeNote(params.title, params.content, params.folder, params.project, params.overwrite);
+                const msg = `Note saved: ${note.title} (${note.permalink})`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: msg,
+                        },
+                    ],
+                    details: {
+                        title: note.title,
+                        permalink: note.permalink,
+                        file_path: note.file_path,
+                    },
+                };
+            }
+            catch (err) {
+                if (err instanceof NoteAlreadyExistsError) {
+                    const hint = [
+                        `Note already exists: "${params.title}" (${err.permalink})`,
+                        "",
+                        "To update this note, use one of:",
+                        `  - edit_note("${err.permalink}", operation="append", content="...")`,
+                        `  - edit_note("${err.permalink}", operation="replace_section", section="...", content="...")`,
+                        `  - write_note("${params.title}", ..., overwrite=true) to fully replace`,
+                        `  - read_note("${err.permalink}") to inspect current content first`,
+                    ].join("\n");
+                    return {
+                        content: [{ type: "text", text: hint }],
+                        details: {
+                            title: params.title,
+                            permalink: err.permalink,
+                            error: "note_already_exists",
+                        },
+                    };
+                }
+                log.error("write_note failed", err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Failed to write note. Is Basic Memory running? Check logs for details.",
+                        },
+                    ],
+                    details: {
+                        title: params.title,
+                        folder: params.folder,
+                        error: "write_note_failed",
+                    },
+                };
+            }
+        },
+    }, { name: "write_note" });
+}

package/index.ts

@@ -1,6 +1,6 @@
-import { execSync } from "node:child_process"
+import { execFileSync } from "node:child_process"
 
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"
 import { BmClient } from "./bm-client.ts"
 import { registerCli } from "./commands/cli.ts"
 import { registerSkillCommands } from "./commands/skills.ts"
@@ -31,17 +31,23 @@ import { registerSchemaValidateTool } from "./tools/schema-validate.ts"
 import { registerSearchTool } from "./tools/search-notes.ts"
 import { registerWriteTool } from "./tools/write-note.ts"
 
-const BASIC_MEMORY_RELEASE_TAG = "v0.20.2"
+export function isCommandAvailable(command: string): boolean {
+  try {
+    execFileSync(command, ["--version"], { stdio: "ignore" })
+    return true
+  } catch {
+    return false
+  }
+}
 
-export default {
+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",
-  kind: "memory" as const,
   configSchema: basicMemoryConfigSchema,
 
-  register(api: OpenClawPluginApi) {
+  register(api) {
     const cfg = parseConfig(api.pluginConfig)
 
     initLogger(api.logger, cfg.debug)
@@ -88,27 +94,31 @@ export default {
 
         // Auto-install bm CLI if not found
         const bmBin = cfg.bmPath || "bm"
-        try {
-          execSync(`command -v ${bmBin}`, { stdio: "ignore" })
-        } catch {
+        if (!isCommandAvailable(bmBin)) {
           log.info("bm CLI not found on PATH — attempting auto-install...")
           try {
-            execSync("command -v uv", { stdio: "ignore" })
+            if (!isCommandAvailable("uv")) {
+              throw new Error("uv not found")
+            }
             log.info(
               "installing basic-memory via uv (this may take a minute)...",
             )
-            const result = execSync(
-              `uv tool install "basic-memory @ git+https://github.com/basicmachines-co/basic-memory.git@${BASIC_MEMORY_RELEASE_TAG}" --force`,
-              { encoding: "utf-8", timeout: 120_000, stdio: "pipe" },
+            const result = execFileSync(
+              "uv",
+              ["tool", "install", "basic-memory", "--force"],
+              {
+                encoding: "utf-8",
+                timeout: 120_000,
+                stdio: ["ignore", "pipe", "pipe"],
+              },
             )
             log.info(
               `basic-memory installed: ${result.trim().split("\n").pop()}`,
             )
             // Verify it worked
-            try {
-              execSync(`command -v ${bmBin}`, { stdio: "ignore" })
+            if (isCommandAvailable(bmBin)) {
               log.info("bm CLI now available on PATH")
-            } catch {
+            } 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).",
               )
@@ -159,4 +169,4 @@ export default {
       },
     })
   },
-}
+})

package/openclaw.plugin.json

@@ -23,8 +23,10 @@
     "skills/memory-defrag",
     "skills/memory-ingest",
     "skills/memory-lifecycle",
+    "skills/memory-literary-analysis",
     "skills/memory-metadata-search",
     "skills/memory-notes",
+    "skills/memory-onboarding",
     "skills/memory-reflect",
     "skills/memory-research",
     "skills/memory-schema",
@@ -52,16 +54,26 @@
       "help": "Path to the basic-memory CLI binary (default: 'bm')",
       "advanced": true
     },
-    "indexInterval": {
-      "label": "Index Interval (seconds)",
-      "placeholder": "300",
-      "help": "Seconds between periodic re-indexing sweeps",
-      "advanced": true
-    },
     "autoCapture": {
       "label": "Auto-Capture",
       "help": "Automatically index conversation content after each turn"
     },
+    "captureMinChars": {
+      "label": "Capture Min Characters",
+      "placeholder": "10",
+      "help": "Minimum user/assistant text length before auto-capture indexes a turn",
+      "advanced": true
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically load relevant Basic Memory context when a session starts"
+    },
+    "recallPrompt": {
+      "label": "Recall Prompt",
+      "placeholder": "Check for active tasks and recent activity...",
+      "help": "Prompt used to gather initial Basic Memory context",
+      "advanced": true
+    },
     "debug": {
       "label": "Debug Logging",
       "help": "Enable verbose debug logs",
@@ -72,11 +84,6 @@
       "placeholder": ".",
       "help": "Filesystem path for Basic Memory project data (defaults to workspace root; relative paths resolve from workspace)",
       "advanced": true
-    },
-    "cloud": {
-      "label": "Cloud Backend",
-      "help": "Optional cloud backend config (url + api_key). If present, uses cloud instead of local BM.",
-      "advanced": true
     }
   },
   "configSchema": {
@@ -85,19 +92,19 @@
     "properties": {
       "project": { "type": "string" },
       "memoryDir": { "type": "string" },
+      "memory_dir": { "type": "string" },
       "memoryFile": { "type": "string" },
+      "memory_file": { "type": "string" },
       "bmPath": { "type": "string" },
-      "indexInterval": { "type": "number", "minimum": 30, "maximum": 3600 },
       "autoCapture": { "type": "boolean" },
+      "captureMinChars": { "type": "number", "minimum": 0 },
+      "capture_min_chars": { "type": "number", "minimum": 0 },
+      "autoRecall": { "type": "boolean" },
+      "auto_recall": { "type": "boolean" },
+      "recallPrompt": { "type": "string" },
+      "recall_prompt": { "type": "string" },
       "debug": { "type": "boolean" },
-      "projectPath": { "type": "string" },
-      "cloud": {
-        "type": "object",
-        "properties": {
-          "url": { "type": "string" },
-          "api_key": { "type": "string" }
-        }
-      }
+      "projectPath": { "type": "string" }
     },
     "required": []
   }

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.2.3",
+  "version": "0.23.0",
   "type": "module",
-  "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "description": "Basic Memory plugin for OpenClaw \u2014 local-first knowledge graph for agent memory",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/basicmachines-co/openclaw-basic-memory"
+    "url": "https://github.com/basicmachines-co/basic-memory.git",
+    "directory": "integrations/openclaw"
   },
   "files": [
     "index.ts",
     "bm-client.ts",
-    "context-engine/",
+    "context-engine/basic-memory-context-engine.ts",
     "config.ts",
     "logger.ts",
     "commands/cli.ts",
@@ -35,6 +38,7 @@
     "schema/task-schema.ts",
     "schema/conversation-schema.ts",
     "skills/",
+    "dist/",
     "scripts/fetch-skills.ts",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",
@@ -53,25 +57,40 @@
   },
   "scripts": {
     "postinstall": "bash scripts/setup-bm.sh || true",
+    "build": "tsc -p tsconfig.build.json",
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
     "lint:fix": "bunx @biomejs/biome check --write .",
     "fetch-skills": "bun scripts/fetch-skills.ts",
-    "prepack": "bun scripts/fetch-skills.ts",
+    "prepack": "bun run fetch-skills && bun run build",
     "test": "bun test",
     "test:int": "BM_INTEGRATION=1 BM_BIN=${BM_BIN:-./scripts/bm-local.sh} bun test integration --timeout 120000",
     "test:coverage": "bun test --coverage",
-    "release:check": "bun run check-types && bun test && npm pack --dry-run"
+    "release:check": "bun run fetch-skills && bun run check-types && bun run lint && bun run build && bun test && npm pack --dry-run"
   },
   "openclaw": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.5.2",
+      "minGatewayVersion": "2026.5.2"
+    },
+    "build": {
+      "openclawVersion": "2026.5.4",
+      "pluginSdkVersion": "2026.5.4"
+    },
+    "install": {
+      "minHostVersion": ">=2026.5.2"
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
     "@types/node": "^20.0.0",
-    "openclaw": "^2026.3.8",
+    "openclaw": "^2026.5.4",
     "typescript": "^5.9.3"
   }
 }