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

package/tools/memory-provider.ts

@@ -0,0 +1,327 @@
+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 { BmClient } from "../bm-client.ts"
+import type { BasicMemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+/**
+ * Search MEMORY.md for lines matching the query.
+ * Returns matching lines with 1 line of surrounding context.
+ */
+async function searchMemoryFile(
+  query: string,
+  workspaceDir: string,
+  memoryFile: string,
+): Promise<string> {
+  try {
+    const filePath = resolve(workspaceDir, memoryFile)
+    const content = await readFile(filePath, "utf-8")
+    const lines = content.split("\n")
+    const queryLower = query.toLowerCase()
+    const terms = queryLower.split(/\s+/).filter((t) => t.length > 0)
+
+    // Find lines that match any search term
+    const matchingIndices = new Set<number>()
+    for (let i = 0; i < lines.length; i++) {
+      const lineLower = lines[i].toLowerCase()
+      if (terms.some((term) => lineLower.includes(term))) {
+        // Add the matching line + 1 line before/after for context
+        if (i > 0) matchingIndices.add(i - 1)
+        matchingIndices.add(i)
+        if (i < lines.length - 1) matchingIndices.add(i + 1)
+      }
+    }
+
+    if (matchingIndices.size === 0) return ""
+
+    // Group consecutive lines into snippets
+    const sorted = [...matchingIndices].sort((a, b) => a - b)
+    const snippets: string[] = []
+    let current: string[] = []
+    let lastIdx = -2
+
+    for (const idx of sorted) {
+      if (idx !== lastIdx + 1 && current.length > 0) {
+        snippets.push(current.join("\n"))
+        current = []
+      }
+      current.push(`- ${lines[idx]}`)
+      lastIdx = idx
+    }
+    if (current.length > 0) snippets.push(current.join("\n"))
+
+    return snippets.join("\n…\n")
+  } catch {
+    return ""
+  }
+}
+
+/**
+ * Search for active tasks via BM knowledge graph.
+ * Uses structured metadata filtering via search_by_metadata for precise querying.
+ * Falls back to filesystem scan if metadata search fails.
+ */
+async function searchActiveTasks(
+  query: string,
+  client: BmClient,
+  workspaceDir: string,
+  memoryDir: string,
+): Promise<string> {
+  // Try structured metadata search first
+  try {
+    const filters: Record<string, unknown> = { type: "task", status: "active" }
+    const metaResults = await client.searchByMetadata(filters, 10)
+
+    if (metaResults.results.length > 0) {
+      // If the caller provided a query, filter results by keyword match
+      const queryLower = query.toLowerCase()
+      const terms = queryLower.split(/\s+/).filter((t) => t.length > 0)
+
+      const filtered =
+        terms.length > 0
+          ? metaResults.results.filter((r) => {
+              const text = `${r.title} ${r.content ?? ""}`.toLowerCase()
+              return terms.some((term) => text.includes(term))
+            })
+          : metaResults.results
+
+      if (filtered.length > 0) {
+        const matches: string[] = []
+        for (const r of filtered) {
+          const score = r.score ? ` (${r.score.toFixed(2)})` : ""
+          const preview =
+            (r.content ?? "").length > 200
+              ? `${(r.content ?? "").slice(0, 200)}…`
+              : (r.content ?? "")
+          matches.push(
+            `- **${r.title}**${score} — ${r.file_path}\n  > ${preview.replace(/\n/g, "\n  > ")}`,
+          )
+        }
+        return matches.join("\n\n")
+      }
+    }
+  } catch (err) {
+    log.debug(
+      "BM metadata task search failed, falling back to filesystem scan",
+      err,
+    )
+  }
+
+  // Fallback: filesystem scan for tasks not yet indexed
+  try {
+    const tasksDir = resolve(workspaceDir, memoryDir, "tasks")
+    let entries: import("node:fs").Dirent[]
+    try {
+      entries = (await readdir(tasksDir, {
+        withFileTypes: true,
+      })) as unknown as import("node:fs").Dirent[]
+    } catch {
+      return ""
+    }
+
+    const queryLower = query.toLowerCase()
+    const terms = queryLower.split(/\s+/).filter((t) => t.length > 0)
+    const matches: string[] = []
+
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".md")) continue
+
+      const filePath = join(entry.parentPath ?? tasksDir, entry.name)
+      const content = await readFile(filePath, "utf-8")
+
+      const statusMatch = content.match(/status:\s*(\S+)/)
+      const status = statusMatch?.[1] ?? "unknown"
+      if (status === "done") continue
+
+      const contentLower = content.toLowerCase()
+      const matchesQuery =
+        terms.length === 0 || terms.some((term) => contentLower.includes(term))
+      if (!matchesQuery) continue
+
+      const titleMatch = content.match(/title:\s*(.+)/)
+      const title = titleMatch?.[1] ?? entry.name.replace(/\.md$/, "")
+      const stepMatch = content.match(/current_step:\s*(\S+)/)
+      const currentStep = stepMatch?.[1] ?? "?"
+
+      const contextMatch = content.match(
+        /## Context\s*\n([\s\S]*?)(?=\n##|\n---|$)/,
+      )
+      const context = contextMatch?.[1]?.trim().slice(0, 150) ?? ""
+
+      matches.push(
+        `- **${title}** (status: ${status}, step: ${currentStep})\n  ${context}`,
+      )
+    }
+
+    return matches.join("\n")
+  } catch {
+    return ""
+  }
+}
+
+// Store workspace dir for use in memory_search (set during service start)
+let _workspaceDir = ""
+export function setWorkspaceDir(dir: string) {
+  _workspaceDir = dir
+}
+
+/**
+ * Register composited memory_search and memory_get tools.
+ *
+ * memory_search queries 3 sources in parallel:
+ * 1. MEMORY.md — grep/text search
+ * 2. BM knowledge graph — semantic + FTS search
+ * 3. Active tasks — memory/tasks/ files with status != done
+ *
+ * memory_get reads a specific note by identifier.
+ */
+export function registerMemoryProvider(
+  api: OpenClawPluginApi,
+  client: BmClient,
+  cfg: BasicMemoryConfig,
+): void {
+  // --- composited memory_search ---
+  api.registerTool(
+    {
+      name: "memory_search",
+      label: "Memory Search",
+      description:
+        "Search across all memory sources: MEMORY.md (working memory), " +
+        "Basic Memory knowledge graph (long-term archive), and active tasks. " +
+        "Returns composited results from all sources.",
+      parameters: Type.Object({
+        query: Type.String({
+          description: "Search query — natural language or keywords",
+        }),
+      }),
+      async execute(_toolCallId: string, params: { query: string }) {
+        log.debug(`memory_search: query="${params.query}"`)
+
+        const workspaceDir = _workspaceDir || process.cwd()
+
+        // Query all 3 sources in parallel
+        const [memoryMd, bmResults, taskResults] = await Promise.all([
+          searchMemoryFile(params.query, workspaceDir, cfg.memoryFile),
+          client
+            .search(params.query, 5)
+            .then((results) => {
+              if (results.length === 0) return ""
+              return results
+                .map((r) => {
+                  const score = r.score ? ` (${r.score.toFixed(2)})` : ""
+                  const preview =
+                    (r.content ?? "").length > 200
+                      ? `${(r.content ?? "").slice(0, 200)}…`
+                      : (r.content ?? "")
+                  const source = r.file_path || r.permalink
+                  return `- ${source}${score}\n  > ${preview.replace(/\n/g, "\n  > ")}`
+                })
+                .join("\n\n")
+            })
+            .catch((err) => {
+              log.error("BM search failed in composited search", err)
+              return "(search unavailable)"
+            }),
+          searchActiveTasks(params.query, client, workspaceDir, cfg.memoryDir),
+        ])
+
+        // Build composited result
+        const sections: string[] = []
+
+        if (memoryMd) {
+          sections.push(`## ${cfg.memoryFile}\n${memoryMd}`)
+        }
+
+        if (bmResults) {
+          sections.push(`## Knowledge Graph (${cfg.memoryDir})\n${bmResults}`)
+        }
+
+        if (taskResults) {
+          sections.push(`## Active Tasks\n${taskResults}`)
+        }
+
+        if (sections.length === 0) {
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "No matches found across memory sources.",
+              },
+            ],
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: sections.join("\n\n"),
+            },
+          ],
+        }
+      },
+    },
+    { names: ["memory_search"] },
+  )
+
+  // --- memory_get (unchanged) ---
+  api.registerTool(
+    {
+      name: "memory_get",
+      label: "Memory Get",
+      description:
+        "Read a specific note from the knowledge graph by title, permalink, or path. " +
+        "Returns the full note content. Use after memory_search to read a specific result in full.",
+      parameters: Type.Object({
+        path: Type.String({
+          description:
+            "Note identifier — title, permalink, memory:// URL, or file path",
+        }),
+        from: Type.Optional(
+          Type.Number({
+            description:
+              "Starting line number (ignored — included for compatibility)",
+          }),
+        ),
+        lines: Type.Optional(
+          Type.Number({
+            description:
+              "Number of lines to read (ignored — included for compatibility)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { path: string; from?: number; lines?: number },
+      ) {
+        log.debug(`memory_get: path="${params.path}"`)
+
+        try {
+          const note = await client.readNote(params.path)
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `# ${note.title}\n\n${note.content}`,
+              },
+            ],
+          }
+        } catch (err) {
+          log.error("memory_get failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Could not read "${params.path}". It may not exist in the knowledge graph.`,
+              },
+            ],
+          }
+        }
+      },
+    },
+    { names: ["memory_get"] },
+  )
+}

package/tools/move-note.ts

@@ -0,0 +1,74 @@
+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 registerMoveTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "move_note",
+      label: "Move Note",
+      description:
+        "Move a note to a different folder in the Basic Memory knowledge graph. " +
+        "The note content is preserved; only the location changes.",
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "Note title, permalink, or memory:// URL to move",
+        }),
+        newFolder: Type.String({
+          description:
+            "Destination folder (e.g., 'archive', 'projects/completed')",
+        }),
+        project: Type.Optional(
+          Type.String({
+            description: "Target project name (defaults to current project)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { identifier: string; newFolder: string; project?: string },
+      ) {
+        log.debug(
+          `move_note: identifier="${params.identifier}" → folder="${params.newFolder}"`,
+        )
+
+        try {
+          const result = await client.moveNote(
+            params.identifier,
+            params.newFolder,
+            params.project,
+          )
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Moved: ${result.title} → ${result.file_path}`,
+              },
+            ],
+            details: {
+              title: result.title,
+              permalink: result.permalink,
+              file_path: result.file_path,
+            },
+          }
+        } catch (err) {
+          log.error("move_note failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Failed to move "${params.identifier}". It may not exist.`,
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "move_note" },
+  )
+}

package/tools/read-note.ts

@@ -0,0 +1,79 @@
+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 registerReadTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "read_note",
+      label: "Read Note",
+      description:
+        "Read a specific note from the Basic Memory knowledge graph by title or permalink. " +
+        "Returns the full note content including observations and relations.",
+      parameters: Type.Object({
+        identifier: Type.String({
+          description: "Note title, permalink, or memory:// URL to read",
+        }),
+        include_frontmatter: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, returns raw note content including YAML frontmatter.",
+          }),
+        ),
+        project: Type.Optional(
+          Type.String({
+            description: "Target project name (defaults to current project)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: {
+          identifier: string
+          include_frontmatter?: boolean
+          project?: string
+        },
+      ) {
+        log.debug(`read_note: identifier="${params.identifier}"`)
+
+        try {
+          const note = await client.readNote(
+            params.identifier,
+            { includeFrontmatter: params.include_frontmatter === true },
+            params.project,
+          )
+
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: note.content,
+              },
+            ],
+            details: {
+              title: note.title,
+              permalink: note.permalink,
+              file_path: note.file_path,
+              frontmatter: note.frontmatter ?? null,
+            },
+          }
+        } catch (err) {
+          log.error("read_note failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: `Could not read note "${params.identifier}". It may not exist yet.`,
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "read_note" },
+  )
+}

package/tools/schema-diff.ts

@@ -0,0 +1,104 @@
+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 registerSchemaDiffTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerTool(
+    {
+      name: "schema_diff",
+      label: "Schema Diff",
+      description:
+        "Detect drift between a Picoschema definition and actual note usage. " +
+        "Identifies new fields in notes not declared in the schema, " +
+        "declared fields no longer used, and cardinality changes.",
+      parameters: Type.Object({
+        noteType: Type.String({
+          description:
+            'The note type to check for drift (e.g., "person", "meeting")',
+        }),
+        project: Type.Optional(
+          Type.String({
+            description: "Target project name (defaults to current project)",
+          }),
+        ),
+      }),
+      async execute(
+        _toolCallId: string,
+        params: { noteType: string; project?: string },
+      ) {
+        log.debug(`schema_diff: noteType="${params.noteType}"`)
+
+        try {
+          const result = await client.schemaDiff(
+            params.noteType,
+            params.project,
+          )
+
+          if (!result.schema_found) {
+            return {
+              content: [
+                {
+                  type: "text" as const,
+                  text: `No schema found for type "${params.noteType}". Use schema_infer to generate one.`,
+                },
+              ],
+            }
+          }
+
+          const lines: string[] = [`**Type:** ${result.entity_type}`]
+
+          if (
+            result.new_fields.length === 0 &&
+            result.dropped_fields.length === 0 &&
+            result.cardinality_changes.length === 0
+          ) {
+            lines.push("No drift detected — schema and notes are in sync.")
+          } else {
+            if (result.new_fields.length > 0) {
+              lines.push("", "### New Fields (in notes, not in schema)")
+              for (const f of result.new_fields) {
+                lines.push(
+                  `- **${f.name}** — ${(f.percentage * 100).toFixed(0)}% of notes`,
+                )
+              }
+            }
+
+            if (result.dropped_fields.length > 0) {
+              lines.push("", "### Dropped Fields (in schema, not in notes)")
+              for (const f of result.dropped_fields) {
+                lines.push(`- **${f.name}** — declared in ${f.declared_in}`)
+              }
+            }
+
+            if (result.cardinality_changes.length > 0) {
+              lines.push("", "### Cardinality Changes")
+              for (const c of result.cardinality_changes) {
+                lines.push(`- ${c}`)
+              }
+            }
+          }
+
+          return {
+            content: [{ type: "text" as const, text: lines.join("\n") }],
+            details: result,
+          }
+        } catch (err) {
+          log.error("schema_diff failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Schema diff failed. Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "schema_diff" },
+  )
+}

package/tools/schema-infer.ts

@@ -0,0 +1,103 @@
+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 registerSchemaInferTool(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  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: string,
+        params: { noteType: string; threshold?: number; project?: string },
+      ) {
+        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: string[] = [
+            `**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" as const, text: lines.join("\n") }],
+            details: result,
+          }
+        } catch (err) {
+          log.error("schema_infer failed", err)
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: "Schema inference failed. Check logs for details.",
+              },
+            ],
+          }
+        }
+      },
+    },
+    { name: "schema_infer" },
+  )
+}