@basicmemory/openclaw-basic-memory 0.1.0-alpha.1

package/tools/schema-validate.ts

@@ -0,0 +1,100 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerSchemaValidateTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  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: string,
+        params: { noteType?: string; identifier?: string; project?: string },
+      ) {
+        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 as unknown as Record<string, unknown>
+          if ("error" in result && typeof resultRecord.error === "string") {
+            return {
+              content: [{ type: "text" as const, text: resultRecord.error }],
+            }
+          }
+
+          const lines: string[] = []
+          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" as const, text: lines.join("\n") }],
+            details: result,
+          }
+        } catch (err) {
+          log.error("schema_validate failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Schema validation failed. Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "schema_validate" },
+  )
+}

package/tools/search-notes.ts

@@ -0,0 +1,130 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerSearchTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  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.Record(Type.String(), Type.Unknown(), {
+            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: string,
+        params: {
+          query: string
+          limit?: number
+          project?: string
+          metadata_filters?: Record<string, unknown>
+          tags?: string[]
+          status?: string
+        },
+      ) {
+        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" as const,
+                  text: "No matching notes found in the knowledge graph.",
+                },
+              ],
+            }
+          }
+
+          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" as const,
+                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" as const,
+                text: "Search failed. Is Basic Memory running? Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "search_notes" },
+  )
+}

package/tools/write-note.ts

@@ -0,0 +1,78 @@
+import { Type } from "@sinclair/typebox"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerWriteTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "write_note",
+      label: "Write Note",
+      description:
+        "Create or update a note in the Basic Memory knowledge graph. " +
+        "Notes are stored as Markdown files with semantic structure " +
+        "(observations, relations) that build a connected knowledge graph.",
+      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)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: {
+          title: string
+          content: string
+          folder: string
+          project?: string
+        },
+      ) {
+        log.debug(`write_note: title=${params.title} folder=${params.folder}`)
+
+        try {
+          const note = await client.writeNote(
+            params.title,
+            params.content,
+            params.folder,
+            params.project,
+          )
+
+          const msg = `Note saved: ${note.title} (${note.permalink})`
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: msg,
+              },
+            ],
+            details: {
+              title: note.title,
+              permalink: note.permalink,
+              file_path: note.file_path,
+            },
+          }
+        } catch (err) {
+          log.error("write_note failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Failed to write note. Is Basic Memory running? Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "write_note" },
+  )
+}

package/types/openclaw.d.ts

@@ -0,0 +1,24 @@
+declare module "openclaw/plugin-sdk" {
+  export interface OpenClawPluginApi {
+    pluginConfig: unknown
+    logger: {
+      info: (msg: string) => void
+      warn: (msg: string) => void
+      error: (msg: string, ...args: unknown[]) => void
+      debug: (msg: string) => void
+    }
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    registerTool(tool: any, options: any): void
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    registerCommand(command: any): void
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    registerCli(handler: any, options?: any): void
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    registerService(service: any): void
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    on(event: string, handler: (...args: any[]) => any): void
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+  export function stringEnum(values: readonly string[]): any
+}