@basicmemory/openclaw-basic-memory 0.2.2 → 0.2.4

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 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"
@@ -33,15 +33,14 @@ import { registerWriteTool } from "./tools/write-note.ts"
 
 const BASIC_MEMORY_RELEASE_TAG = "v0.20.2"
 
-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)
@@ -159,4 +158,4 @@ export default {
       },
     })
   },
-}
+})

package/openclaw.plugin.json

@@ -23,6 +23,7 @@
     "skills/memory-defrag",
     "skills/memory-ingest",
     "skills/memory-lifecycle",
+    "skills/memory-literary-analysis",
     "skills/memory-metadata-search",
     "skills/memory-notes",
     "skills/memory-reflect",
@@ -52,16 +53,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",
@@ -85,18 +96,27 @@
     "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",
+        "additionalProperties": false,
         "properties": {
           "url": { "type": "string" },
           "api_key": { "type": "string" }
-        }
+        },
+        "required": ["url", "api_key"]
       }
     },
     "required": []

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
   "repository": {
@@ -11,7 +13,7 @@
   "files": [
     "index.ts",
     "bm-client.ts",
-    "context-engine/",
+    "context-engine/basic-memory-context-engine.ts",
     "config.ts",
     "logger.ts",
     "commands/cli.ts",
@@ -35,6 +37,7 @@
     "schema/task-schema.ts",
     "schema/conversation-schema.ts",
     "skills/",
+    "dist/",
     "scripts/fetch-skills.ts",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",
@@ -53,25 +56,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 check-types && 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"
   }
 }

package/tools/build-context.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/delete-note.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/edit-note.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/list-memory-projects.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient, ProjectListResult } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/list-workspaces.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient, WorkspaceResult } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/memory-provider.ts

@@ -1,7 +1,7 @@
 import { readdir, readFile } from "node:fs/promises"
 import { join, resolve } from "node:path"
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { log } from "../logger.ts"

package/tools/move-note.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/read-note.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/schema-diff.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/schema-infer.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/schema-validate.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 

package/tools/search-notes.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { log } from "../logger.ts"
 
@@ -26,10 +26,14 @@ export function registerSearchTool(
           }),
         ),
         metadata_filters: Type.Optional(
-          Type.Record(Type.String(), Type.Unknown(), {
-            description:
-              "Filter by frontmatter fields. Supports equality, $in, $gt/$gte/$lt/$lte, $between, and array-contains operators.",
-          }),
+          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(), {

package/tools/write-note.ts

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 import type { BmClient } from "../bm-client.ts"
 import { NoteAlreadyExistsError } from "../bm-client.ts"
 import { log } from "../logger.ts"