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

package/commands/cli.ts

@@ -0,0 +1,176 @@
+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"
+
+export function registerCli(
+  api: OpenClawPluginApi,
+  client: BmClient,
+  cfg: BasicMemoryConfig,
+): void {
+  api.registerCli(
+    // biome-ignore lint/suspicious/noExplicitAny: openclaw SDK does not ship types
+    ({ program }: { program: any }) => {
+      const cmd = program
+        .command("basic-memory")
+        .description("Basic Memory knowledge graph commands")
+
+      cmd
+        .command("search")
+        .argument("<query>", "Search query")
+        .option("--limit <n>", "Max results", "10")
+        .action(async (query: string, opts: { limit: string }) => {
+          const limit = Number.parseInt(opts.limit, 10) || 10
+          log.debug(`cli search: query="${query}" limit=${limit}`)
+
+          const results = await client.search(query, limit)
+
+          if (results.length === 0) {
+            console.log("No notes found.")
+            return
+          }
+
+          for (const r of results) {
+            const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : ""
+            console.log(`- ${r.title}${score}`)
+            if (r.content) {
+              const preview =
+                r.content.length > 100
+                  ? `${r.content.slice(0, 100)}...`
+                  : r.content
+              console.log(`  ${preview}`)
+            }
+          }
+        })
+
+      cmd
+        .command("read")
+        .argument("<identifier>", "Note title, permalink, or memory:// URL")
+        .option("--raw", "Return raw markdown including frontmatter", false)
+        .action(async (identifier: string, opts: { raw?: boolean }) => {
+          log.debug(`cli read: identifier="${identifier}"`)
+
+          const note = await client.readNote(identifier, {
+            includeFrontmatter: opts.raw === true,
+          })
+          console.log(`# ${note.title}`)
+          console.log(`permalink: ${note.permalink}`)
+          console.log(`file: ${note.file_path}`)
+          console.log("")
+          console.log(note.content)
+        })
+
+      cmd
+        .command("edit")
+        .argument("<identifier>", "Note title, permalink, or memory:// URL")
+        .requiredOption(
+          "--operation <operation>",
+          "Edit operation: append|prepend|find_replace|replace_section",
+        )
+        .requiredOption("--content <content>", "Edit content")
+        .option("--find-text <text>", "Text to find for find_replace")
+        .option("--section <heading>", "Section heading for replace_section")
+        .option(
+          "--expected-replacements <n>",
+          "Expected replacement count for find_replace",
+          "1",
+        )
+        .action(
+          async (
+            identifier: string,
+            opts: {
+              operation:
+                | "append"
+                | "prepend"
+                | "find_replace"
+                | "replace_section"
+              content: string
+              findText?: string
+              section?: string
+              expectedReplacements: string
+            },
+          ) => {
+            const expectedReplacements =
+              Number.parseInt(opts.expectedReplacements, 10) || 1
+            log.debug(
+              `cli edit: identifier="${identifier}" op=${opts.operation} expected_replacements=${expectedReplacements}`,
+            )
+
+            const result = await client.editNote(
+              identifier,
+              opts.operation,
+              opts.content,
+              {
+                find_text: opts.findText,
+                section: opts.section,
+                expected_replacements: expectedReplacements,
+              },
+            )
+
+            console.log(`Edited: ${result.title}`)
+            console.log(`permalink: ${result.permalink}`)
+            console.log(`file: ${result.file_path}`)
+            console.log(`operation: ${result.operation}`)
+            if (result.checksum) {
+              console.log(`checksum: ${result.checksum}`)
+            }
+          },
+        )
+
+      cmd
+        .command("context")
+        .argument("<url>", "Memory URL to navigate")
+        .option("--depth <n>", "Relation hops to follow", "1")
+        .action(async (url: string, opts: { depth: string }) => {
+          const depth = Number.parseInt(opts.depth, 10) || 1
+          log.debug(`cli context: url="${url}" depth=${depth}`)
+
+          const ctx = await client.buildContext(url, depth)
+
+          if (!ctx.results || ctx.results.length === 0) {
+            console.log(`No context found for "${url}".`)
+            return
+          }
+
+          for (const result of ctx.results) {
+            console.log(`## ${result.primary_result.title}`)
+            console.log(result.primary_result.content)
+            console.log("")
+          }
+        })
+
+      cmd
+        .command("recent")
+        .option("--timeframe <t>", "Timeframe (e.g. 24h, 7d)", "24h")
+        .action(async (opts: { timeframe: string }) => {
+          log.debug(`cli recent: timeframe="${opts.timeframe}"`)
+
+          const results = await client.recentActivity(opts.timeframe)
+
+          if (results.length === 0) {
+            console.log("No recent activity.")
+            return
+          }
+
+          for (const r of results) {
+            console.log(`- ${r.title} (${r.permalink})`)
+          }
+        })
+
+      cmd
+        .command("status")
+        .description("Show plugin status")
+        .action(() => {
+          console.log(`Project: ${cfg.project}`)
+          console.log(`Project path: ${cfg.projectPath}`)
+          console.log(`BM CLI: ${cfg.bmPath}`)
+          console.log(`Memory dir: ${cfg.memoryDir}`)
+          console.log(`Memory file: ${cfg.memoryFile}`)
+          console.log(`Auto-capture: ${cfg.autoCapture}`)
+          console.log(`Cloud: ${cfg.cloud ? cfg.cloud.url : "disabled"}`)
+          console.log(`Debug: ${cfg.debug}`)
+        })
+    },
+    { commands: ["basic-memory"] },
+  )
+}

package/commands/skills.ts

@@ -0,0 +1,52 @@
+import { readFileSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILLS_DIR = resolve(__dirname, "..", "skills")
+
+function loadSkill(dir: string): string {
+  return readFileSync(resolve(SKILLS_DIR, dir, "SKILL.md"), "utf-8")
+}
+
+const SKILLS = [
+  { name: "tasks", dir: "memory-tasks", desc: "Task management workflow" },
+  {
+    name: "reflect",
+    dir: "memory-reflect",
+    desc: "Memory reflection workflow",
+  },
+  { name: "defrag", dir: "memory-defrag", desc: "Memory defrag workflow" },
+  { name: "schema", dir: "memory-schema", desc: "Schema management workflow" },
+  {
+    name: "notes",
+    dir: "memory-notes",
+    desc: "How to write well-structured notes",
+  },
+  {
+    name: "metadata-search",
+    dir: "memory-metadata-search",
+    desc: "Structured metadata search workflow",
+  },
+] as const
+
+export function registerSkillCommands(api: OpenClawPluginApi): void {
+  for (const skill of SKILLS) {
+    const content = loadSkill(skill.dir)
+
+    api.registerCommand({
+      name: skill.name,
+      description: skill.desc,
+      acceptsArgs: true,
+      requireAuth: true,
+      handler: async (ctx: { args?: string }) => {
+        const args = ctx.args?.trim()
+        const prefix = args
+          ? `User request: ${args}\n\nFollow this workflow:\n\n`
+          : "Follow this workflow:\n\n"
+        return { text: prefix + content }
+      },
+    })
+  }
+}

package/commands/slash.ts

@@ -0,0 +1,73 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { BmClient } from "../bm-client.ts"
+import { log } from "../logger.ts"
+
+export function registerCommands(
+  api: OpenClawPluginApi,
+  client: BmClient,
+): void {
+  api.registerCommand({
+    name: "remember",
+    description: "Save something to the Basic Memory knowledge graph",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: { args?: string }) => {
+      const text = ctx.args?.trim()
+      if (!text) {
+        return { text: "Usage: /remember <text to save as a note>" }
+      }
+
+      log.debug(`/remember: "${text.slice(0, 50)}"`)
+
+      try {
+        const title = text.length > 60 ? text.slice(0, 60) : text
+        await client.writeNote(title, text, "agent/memories")
+
+        const preview = text.length > 60 ? `${text.slice(0, 60)}...` : text
+        return { text: `Remembered: "${preview}"` }
+      } catch (err) {
+        log.error("/remember failed", err)
+        return {
+          text: "Failed to save memory. Is Basic Memory running?",
+        }
+      }
+    },
+  })
+
+  api.registerCommand({
+    name: "recall",
+    description: "Search the Basic Memory knowledge graph",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: { args?: string }) => {
+      const query = ctx.args?.trim()
+      if (!query) {
+        return { text: "Usage: /recall <search query>" }
+      }
+
+      log.debug(`/recall: "${query}"`)
+
+      try {
+        const results = await client.search(query, 5)
+
+        if (results.length === 0) {
+          return { text: `No notes found for: "${query}"` }
+        }
+
+        const lines = results.map((r, i) => {
+          const score = r.score ? ` (${(r.score * 100).toFixed(0)}%)` : ""
+          return `${i + 1}. ${r.title}${score}`
+        })
+
+        return {
+          text: `Found ${results.length} notes:\n\n${lines.join("\n")}`,
+        }
+      } catch (err) {
+        log.error("/recall failed", err)
+        return {
+          text: "Failed to search. Is Basic Memory running?",
+        }
+      }
+    },
+  })
+}

package/config.ts

@@ -0,0 +1,152 @@
+import { homedir, hostname } from "node:os"
+import { isAbsolute, resolve } from "node:path"
+
+export type CloudConfig = {
+  url: string
+  api_key: string
+}
+
+export type BasicMemoryConfig = {
+  project: string
+  bmPath: string
+  memoryDir: string
+  memoryFile: string
+  projectPath: string
+  autoCapture: boolean
+  captureMinChars: number
+  autoRecall: boolean
+  recallPrompt: string
+  debug: boolean
+  cloud?: CloudConfig
+}
+
+const ALLOWED_KEYS = [
+  "project",
+  "bmPath",
+  "memoryDir",
+  "memory_dir",
+  "memoryFile",
+  "memory_file",
+  "projectPath",
+  "autoCapture",
+  "captureMinChars",
+  "capture_min_chars",
+  "autoRecall",
+  "auto_recall",
+  "recallPrompt",
+  "recall_prompt",
+  "debug",
+  "cloud",
+]
+
+function assertAllowedKeys(
+  value: Record<string, unknown>,
+  allowed: string[],
+  label: string,
+): void {
+  const unknown = Object.keys(value).filter((k) => !allowed.includes(k))
+  if (unknown.length > 0) {
+    throw new Error(`${label} has unknown keys: ${unknown.join(", ")}`)
+  }
+}
+
+function defaultProject(): string {
+  return `openclaw-${hostname()
+    .replace(/[^a-zA-Z0-9-]/g, "-")
+    .toLowerCase()}`
+}
+
+function expandUserPath(path: string): string {
+  if (path === "~") return homedir()
+  if (path.startsWith("~/")) return `${homedir()}/${path.slice(2)}`
+  return path
+}
+
+export function resolveProjectPath(
+  projectPath: string,
+  workspaceDir: string,
+): string {
+  const expanded = expandUserPath(projectPath)
+  if (isAbsolute(expanded)) return expanded
+  return resolve(workspaceDir, expanded)
+}
+
+export function parseConfig(raw: unknown): BasicMemoryConfig {
+  const cfg =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {}
+
+  if (Object.keys(cfg).length > 0) {
+    assertAllowedKeys(cfg, ALLOWED_KEYS, "basic-memory config")
+  }
+
+  // Support both camelCase and snake_case for memory_dir / memory_file
+  const memoryDir =
+    typeof cfg.memoryDir === "string" && cfg.memoryDir.length > 0
+      ? cfg.memoryDir
+      : typeof cfg.memory_dir === "string" &&
+          (cfg.memory_dir as string).length > 0
+        ? (cfg.memory_dir as string)
+        : "memory/"
+
+  const memoryFile =
+    typeof cfg.memoryFile === "string" && cfg.memoryFile.length > 0
+      ? cfg.memoryFile
+      : typeof cfg.memory_file === "string" &&
+          (cfg.memory_file as string).length > 0
+        ? (cfg.memory_file as string)
+        : "MEMORY.md"
+
+  let cloud: CloudConfig | undefined
+  if (cfg.cloud && typeof cfg.cloud === "object" && !Array.isArray(cfg.cloud)) {
+    const c = cfg.cloud as Record<string, unknown>
+    if (typeof c.url === "string" && typeof c.api_key === "string") {
+      cloud = { url: c.url, api_key: c.api_key }
+    }
+  }
+
+  return {
+    project:
+      typeof cfg.project === "string" && cfg.project.length > 0
+        ? cfg.project
+        : defaultProject(),
+    projectPath:
+      typeof cfg.projectPath === "string" && cfg.projectPath.length > 0
+        ? cfg.projectPath
+        : memoryDir,
+    bmPath:
+      typeof cfg.bmPath === "string" && cfg.bmPath.length > 0
+        ? cfg.bmPath
+        : "bm",
+    memoryDir,
+    memoryFile,
+    autoCapture: typeof cfg.autoCapture === "boolean" ? cfg.autoCapture : true,
+    captureMinChars:
+      typeof cfg.captureMinChars === "number" && cfg.captureMinChars >= 0
+        ? cfg.captureMinChars
+        : typeof cfg.capture_min_chars === "number" &&
+            (cfg.capture_min_chars as number) >= 0
+          ? (cfg.capture_min_chars as number)
+          : 10,
+    autoRecall:
+      typeof cfg.autoRecall === "boolean"
+        ? cfg.autoRecall
+        : typeof cfg.auto_recall === "boolean"
+          ? (cfg.auto_recall as boolean)
+          : true,
+    recallPrompt:
+      typeof cfg.recallPrompt === "string" && cfg.recallPrompt.length > 0
+        ? cfg.recallPrompt
+        : typeof cfg.recall_prompt === "string" &&
+            (cfg.recall_prompt as string).length > 0
+          ? (cfg.recall_prompt as string)
+          : "Check for active tasks and recent activity. Summarize anything relevant to the current session.",
+    debug: typeof cfg.debug === "boolean" ? cfg.debug : false,
+    cloud,
+  }
+}
+
+export const basicMemoryConfigSchema = {
+  parse: parseConfig,
+}

package/hooks/capture.ts

@@ -0,0 +1,95 @@
+import type { BmClient } from "../bm-client.ts"
+import type { BasicMemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+/**
+ * Extract text content from a message object.
+ */
+function extractText(msg: Record<string, unknown>): string {
+  const content = msg.content
+  if (typeof content === "string") return content
+
+  if (Array.isArray(content)) {
+    const parts: string[] = []
+    for (const block of content) {
+      if (!block || typeof block !== "object") continue
+      const b = block as Record<string, unknown>
+      if (b.type === "text" && typeof b.text === "string") {
+        parts.push(b.text)
+      }
+    }
+    return parts.join("\n")
+  }
+
+  return ""
+}
+
+/**
+ * Find the last user+assistant turn from the messages array.
+ */
+function getLastTurn(messages: unknown[]): {
+  userText: string
+  assistantText: string
+} {
+  let lastUserIdx = -1
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i]
+    if (
+      msg &&
+      typeof msg === "object" &&
+      (msg as Record<string, unknown>).role === "user"
+    ) {
+      lastUserIdx = i
+      break
+    }
+  }
+
+  if (lastUserIdx < 0) return { userText: "", assistantText: "" }
+
+  let userText = ""
+  let assistantText = ""
+
+  for (let i = lastUserIdx; i < messages.length; i++) {
+    const msg = messages[i] as Record<string, unknown>
+    if (!msg?.role) continue
+    const text = extractText(msg)
+    if (msg.role === "user") userText = text
+    else if (msg.role === "assistant") assistantText = text
+  }
+
+  return { userText, assistantText }
+}
+
+/**
+ * Build the post-turn capture handler for Mode B.
+ *
+ * After each agent turn, extracts the conversation content and indexes it
+ * into the Basic Memory knowledge graph as a conversation note.
+ */
+export function buildCaptureHandler(client: BmClient, cfg: BasicMemoryConfig) {
+  const minChars = cfg.captureMinChars
+  return async (event: Record<string, unknown>) => {
+    if (
+      !event.success ||
+      !Array.isArray(event.messages) ||
+      event.messages.length === 0
+    ) {
+      return
+    }
+
+    const { userText, assistantText } = getLastTurn(event.messages)
+
+    if (!userText && !assistantText) return
+    if (userText.length < minChars && assistantText.length < minChars) return
+
+    log.debug(
+      `capturing conversation: user=${userText.length} chars, assistant=${assistantText.length} chars`,
+    )
+
+    try {
+      await client.indexConversation(userText, assistantText)
+    } catch (err) {
+      log.error("capture failed", err)
+    }
+  }
+}

package/hooks/recall.ts

@@ -0,0 +1,66 @@
+import type {
+  BmClient,
+  MetadataSearchResult,
+  RecentResult,
+} from "../bm-client.ts"
+import type { BasicMemoryConfig } from "../config.ts"
+import { log } from "../logger.ts"
+
+/**
+ * Format recalled context from active tasks and recent activity.
+ * Returns empty string if nothing was found.
+ */
+export function formatRecallContext(
+  tasks: MetadataSearchResult,
+  recent: RecentResult[],
+  prompt: string,
+): string {
+  const sections: string[] = []
+
+  if (tasks.results.length > 0) {
+    const taskLines = tasks.results.map((t) => {
+      const preview =
+        t.content.length > 120 ? `${t.content.slice(0, 120)}...` : t.content
+      return `- **${t.title}** — ${preview}`
+    })
+    sections.push(`## Active Tasks\n${taskLines.join("\n")}`)
+  }
+
+  if (recent.length > 0) {
+    const recentLines = recent.map((r) => `- ${r.title} (${r.file_path})`)
+    sections.push(`## Recent Activity\n${recentLines.join("\n")}`)
+  }
+
+  if (sections.length === 0) return ""
+
+  return `${sections.join("\n\n")}\n\n---\n${prompt}`
+}
+
+/**
+ * Build the pre-turn recall handler.
+ *
+ * On agent_start, queries active tasks and recent activity from Basic Memory,
+ * then returns formatted context for injection into the conversation.
+ */
+export function buildRecallHandler(client: BmClient, cfg: BasicMemoryConfig) {
+  return async (_event: Record<string, unknown>) => {
+    try {
+      const [tasks, recent] = await Promise.all([
+        client.searchByMetadata({ entity_type: "Task", status: "active" }, 5),
+        client.recentActivity("1d"),
+      ])
+
+      const context = formatRecallContext(tasks, recent, cfg.recallPrompt)
+      if (!context) return {}
+
+      log.debug(
+        `recall: ${tasks.results.length} active tasks, ${recent.length} recent items`,
+      )
+
+      return { context }
+    } catch (err) {
+      log.error("recall failed", err)
+      return {}
+    }
+  }
+}