@basicmemory/openclaw-basic-memory 0.1.0-alpha.9 → 0.1.2

package/bm-client.ts

@@ -1,14 +1,12 @@
 import { setTimeout as delay } from "node:timers/promises"
 import { Client } from "@modelcontextprotocol/sdk/client"
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
-import { trackToolCall } from "./analytics.ts"
 import { log } from "./logger.ts"
 
 const DEFAULT_RETRY_DELAYS_MS = [500, 1000, 2000]
 
 const REQUIRED_TOOLS = [
   "search_notes",
-  "search_by_metadata",
   "read_note",
   "write_note",
   "edit_note",
@@ -154,12 +152,6 @@ export interface SchemaDiffResult {
   cardinality_changes: string[]
 }
 
-export interface MetadataSearchResult {
-  results: SearchResult[]
-  current_page: number
-  page_size: number
-}
-
 function getErrorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }
@@ -197,7 +189,7 @@ function isRecoverableConnectionError(err: unknown): boolean {
   )
 }
 
-function isNoteNotFoundError(err: unknown): boolean {
+function _isNoteNotFoundError(err: unknown): boolean {
   const msg = getErrorMessage(err).toLowerCase()
   return (
     msg.includes("entity not found") ||
@@ -450,7 +442,6 @@ export class BmClient {
     name: string,
     args: Record<string, unknown>,
   ): Promise<unknown> {
-    trackToolCall(name)
     const result = await this.callToolRaw(name, args)
 
     if (!isRecord(result) || result.structuredContent === undefined) {
@@ -504,25 +495,29 @@ export class BmClient {
   }
 
   async search(
-    query: string,
+    query?: string,
     limit = 10,
     project?: string,
     metadata?: {
       filters?: Record<string, unknown>
       tags?: string[]
       status?: string
+      note_types?: string[]
+      entity_types?: string[]
     },
   ): Promise<SearchResult[]> {
     const args: Record<string, unknown> = {
-      query,
       page: 1,
       page_size: limit,
       output_format: "json",
     }
+    if (query) args.query = query
     if (project) args.project = project
     if (metadata?.filters) args.metadata_filters = metadata.filters
     if (metadata?.tags) args.tags = metadata.tags
     if (metadata?.status) args.status = metadata.status
+    if (metadata?.note_types) args.note_types = metadata.note_types
+    if (metadata?.entity_types) args.entity_types = metadata.entity_types
 
     const payload = await this.callTool("search_notes", args)
 
@@ -661,11 +656,12 @@ export class BmClient {
       identifier,
       operation,
       content,
-      find_text: options.find_text,
-      section: options.section,
-      expected_replacements: options.expected_replacements,
       output_format: "json",
     }
+    if (options.find_text) args.find_text = options.find_text
+    if (options.section) args.section = options.section
+    if (options.expected_replacements != null)
+      args.expected_replacements = options.expected_replacements
     if (project) args.project = project
 
     const payload = await this.callTool("edit_note", args)
@@ -810,31 +806,6 @@ export class BmClient {
     return payload as unknown as SchemaDiffResult
   }
 
-  async searchByMetadata(
-    filters: Record<string, unknown>,
-    limit = 20,
-    project?: string,
-  ): Promise<MetadataSearchResult> {
-    const args: Record<string, unknown> = {
-      filters,
-      limit,
-      output_format: "json",
-    }
-    if (project) args.project = project
-
-    const payload = await this.callTool("search_by_metadata", args)
-
-    if (!isRecord(payload) || !Array.isArray(payload.results)) {
-      throw new Error("invalid search_by_metadata response")
-    }
-
-    return payload as unknown as MetadataSearchResult
-  }
-
-  private isNoteNotFoundError(err: unknown): boolean {
-    return isNoteNotFoundError(err)
-  }
-
   async indexConversation(
     userMessage: string,
     assistantResponse: string,
@@ -856,22 +827,33 @@ export class BmClient {
       "---",
     ].join("\n")
 
+    // Try append first — if it fails for ANY reason, fall through to create
     try {
       await this.editNote(title, "append", entry)
       log.debug(`appended conversation to: ${title}`)
+      return
     } catch (err) {
-      if (!this.isNoteNotFoundError(err)) {
-        log.error("conversation append failed", err)
-        return
-      }
+      log.debug(`append failed, will create: ${getErrorMessage(err)}`)
+    }
 
-      const content = [`# Conversations ${dateStr}`, "", entry].join("\n")
-      try {
-        await this.writeNote(title, content, "conversations")
-        log.debug(`created conversation note: ${title}`)
-      } catch (createErr) {
-        log.error("conversation index failed", createErr)
-      }
+    // Create the note with frontmatter and first entry
+    const content = [
+      "---",
+      `title: Conversations ${dateStr}`,
+      "type: Conversation",
+      `date: "${dateStr}"`,
+      "---",
+      "",
+      `# Conversations ${dateStr}`,
+      "",
+      entry,
+    ].join("\n")
+
+    try {
+      await this.writeNote(title, content, "conversations")
+      log.debug(`created conversation note: ${title}`)
+    } catch (err) {
+      log.error("conversation index failed", err)
     }
   }
 

package/config.ts

@@ -6,11 +6,6 @@ export type CloudConfig = {
   api_key: string
 }
 
-export type DashboardConfig = {
-  enabled: boolean
-  port: number
-}
-
 export type BasicMemoryConfig = {
   project: string
   bmPath: string
@@ -23,7 +18,6 @@ export type BasicMemoryConfig = {
   recallPrompt: string
   debug: boolean
   cloud?: CloudConfig
-  dashboard: DashboardConfig
 }
 
 const ALLOWED_KEYS = [
@@ -43,7 +37,6 @@ const ALLOWED_KEYS = [
   "recall_prompt",
   "debug",
   "cloud",
-  "dashboard",
 ]
 
 function assertAllowedKeys(
@@ -113,22 +106,6 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
     }
   }
 
-  let dashboard: DashboardConfig = { enabled: false, port: 3838 }
-  if (
-    cfg.dashboard &&
-    typeof cfg.dashboard === "object" &&
-    !Array.isArray(cfg.dashboard)
-  ) {
-    const d = cfg.dashboard as Record<string, unknown>
-    dashboard = {
-      enabled: typeof d.enabled === "boolean" ? d.enabled : false,
-      port:
-        typeof d.port === "number" && d.port > 0 && d.port < 65536
-          ? d.port
-          : 3838,
-    }
-  }
-
   return {
     project:
       typeof cfg.project === "string" && cfg.project.length > 0
@@ -167,7 +144,6 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
           : "Check for active tasks and recent activity. Summarize anything relevant to the current session.",
     debug: typeof cfg.debug === "boolean" ? cfg.debug : false,
     cloud,
-    dashboard,
   }
 }
 

package/hooks/recall.ts

@@ -1,8 +1,4 @@
-import type {
-  BmClient,
-  MetadataSearchResult,
-  RecentResult,
-} from "../bm-client.ts"
+import type { BmClient, RecentResult, SearchResult } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
 import { log } from "../logger.ts"
 
@@ -11,14 +7,14 @@ import { log } from "../logger.ts"
  * Returns empty string if nothing was found.
  */
 export function formatRecallContext(
-  tasks: MetadataSearchResult,
+  tasks: SearchResult[],
   recent: RecentResult[],
   prompt: string,
 ): string {
   const sections: string[] = []
 
-  if (tasks.results.length > 0) {
-    const taskLines = tasks.results.map((t) => {
+  if (tasks.length > 0) {
+    const taskLines = tasks.map((t) => {
       const preview =
         t.content.length > 120 ? `${t.content.slice(0, 120)}...` : t.content
       return `- **${t.title}** — ${preview}`
@@ -46,7 +42,10 @@ 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.search(undefined, 5, undefined, {
+          note_types: ["Task"],
+          status: "active",
+        }),
         client.recentActivity("1d"),
       ])
 
@@ -54,7 +53,7 @@ export function buildRecallHandler(client: BmClient, cfg: BasicMemoryConfig) {
       if (!context) return {}
 
       log.debug(
-        `recall: ${tasks.results.length} active tasks, ${recent.length} recent items`,
+        `recall: ${tasks.length} active tasks, ${recent.length} recent items`,
       )
 
       return { context }

package/index.ts

@@ -1,10 +1,6 @@
-import type { Server } from "node:http"
+import { execSync } from "node:child_process"
+
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
-import {
-  EVENT_PLUGIN_INSTALLED,
-  EVENT_PLUGIN_STARTED,
-  track,
-} from "./analytics.ts"
 import { BmClient } from "./bm-client.ts"
 import { registerCli } from "./commands/cli.ts"
 import { registerSkillCommands } from "./commands/skills.ts"
@@ -14,10 +10,11 @@ import {
   parseConfig,
   resolveProjectPath,
 } from "./config.ts"
-import { createDashboardServer } from "./dashboard/server.ts"
+
 import { buildCaptureHandler } from "./hooks/capture.ts"
 import { buildRecallHandler } from "./hooks/recall.ts"
 import { initLogger, log } from "./logger.ts"
+import { CONVERSATION_SCHEMA_CONTENT } from "./schema/conversation-schema.ts"
 import { TASK_SCHEMA_CONTENT } from "./schema/task-schema.ts"
 import { registerContextTool } from "./tools/build-context.ts"
 import { registerDeleteTool } from "./tools/delete-note.ts"
@@ -53,8 +50,6 @@ export default {
       `project=${cfg.project} memoryDir=${cfg.memoryDir} memoryFile=${cfg.memoryFile}`,
     )
 
-    track(EVENT_PLUGIN_INSTALLED)
-
     const client = new BmClient(cfg.bmPath, cfg.project)
 
     // --- BM Tools (always registered) ---
@@ -89,13 +84,47 @@ export default {
     registerCli(api, client, cfg)
 
     // --- Service lifecycle ---
-    let dashboardServer: Server | undefined
-
     api.registerService({
       id: "openclaw-basic-memory",
       start: async (ctx: { config?: unknown; workspaceDir?: string }) => {
         log.info("starting...")
 
+        // Auto-install bm CLI if not found
+        const bmBin = cfg.bmPath || "bm"
+        try {
+          execSync(`command -v ${bmBin}`, { stdio: "ignore" })
+        } catch {
+          log.info("bm CLI not found on PATH — attempting auto-install...")
+          try {
+            execSync("command -v uv", { stdio: "ignore" })
+            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@main" --force',
+              { encoding: "utf-8", timeout: 120_000, stdio: "pipe" },
+            )
+            log.info(
+              `basic-memory installed: ${result.trim().split("\n").pop()}`,
+            )
+            // Verify it worked
+            try {
+              execSync(`command -v ${bmBin}`, { stdio: "ignore" })
+              log.info("bm CLI now available on PATH")
+            } catch {
+              log.error(
+                "bm installed but not found on PATH. You may need to add uv's bin directory to your PATH (typically ~/.local/bin).",
+              )
+            }
+          } catch (_uvErr) {
+            log.error(
+              "Cannot auto-install basic-memory: uv not found. " +
+                "Install uv first (brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh), " +
+                "then restart the gateway.",
+            )
+          }
+        }
+
         const workspace = ctx.workspaceDir ?? process.cwd()
         const projectPath = resolveProjectPath(cfg.projectPath, workspace)
         cfg.projectPath = projectPath
@@ -104,46 +133,30 @@ export default {
         await client.ensureProject(projectPath)
         log.debug(`project "${cfg.project}" at ${projectPath}`)
 
-        // Seed Task schema if not already present
-        try {
-          await client.readNote("schema/Task")
-          log.debug("Task schema already exists, skipping seed")
-        } catch {
+        // Seed schemas if not already present
+        for (const [name, content] of [
+          ["Task", TASK_SCHEMA_CONTENT],
+          ["Conversation", CONVERSATION_SCHEMA_CONTENT],
+        ] as const) {
           try {
-            await client.writeNote("Task", TASK_SCHEMA_CONTENT, "schema")
-            log.debug("seeded Task schema note")
-          } catch (err) {
-            log.debug("Task schema seed failed (non-fatal)", err)
+            await client.readNote(`schema/${name}`)
+            log.debug(`${name} schema already exists, skipping seed`)
+          } catch {
+            try {
+              await client.writeNote(name, content, "schema")
+              log.debug(`seeded ${name} schema note`)
+            } catch (err) {
+              log.debug(`${name} schema seed failed (non-fatal)`, err)
+            }
           }
         }
 
         setWorkspaceDir(workspace)
 
-        // Start dashboard if enabled
-        if (cfg.dashboard.enabled) {
-          dashboardServer = createDashboardServer({
-            port: cfg.dashboard.port,
-            client,
-          })
-          dashboardServer.listen(cfg.dashboard.port, () => {
-            log.info(
-              `dashboard running at http://localhost:${cfg.dashboard.port}`,
-            )
-          })
-        }
-
-        track(EVENT_PLUGIN_STARTED, { project: cfg.project })
         log.info("connected — BM MCP stdio session running")
       },
       stop: async () => {
         log.info("stopping BM MCP session...")
-        if (dashboardServer) {
-          await new Promise<void>((resolve) =>
-            dashboardServer?.close(() => resolve()),
-          )
-          dashboardServer = undefined
-          log.info("dashboard stopped")
-        }
         await client.stop()
         log.info("stopped")
       },

package/openclaw.plugin.json

@@ -56,11 +56,6 @@
       "label": "Cloud Backend",
       "help": "Optional cloud backend config (url + api_key). If present, uses cloud instead of local BM.",
       "advanced": true
-    },
-    "dashboard": {
-      "label": "Dashboard",
-      "help": "Web dashboard for visualizing the knowledge graph (enabled, port)",
-      "advanced": true
     }
   },
   "configSchema": {
@@ -81,13 +76,6 @@
           "url": { "type": "string" },
           "api_key": { "type": "string" }
         }
-      },
-      "dashboard": {
-        "type": "object",
-        "properties": {
-          "enabled": { "type": "boolean" },
-          "port": { "type": "number", "minimum": 1, "maximum": 65535 }
-        }
       }
     },
     "required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basicmemory/openclaw-basic-memory",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.2",
   "type": "module",
   "description": "Basic Memory plugin for OpenClaw — local-first knowledge graph for agent memory",
   "license": "MIT",
@@ -9,7 +9,6 @@
     "url": "https://github.com/basicmachines-co/openclaw-basic-memory"
   },
   "files": [
-    "analytics.ts",
     "index.ts",
     "bm-client.ts",
     "config.ts",
@@ -34,6 +33,7 @@
     "tools/write-note.ts",
     "types/openclaw.d.ts",
     "schema/task-schema.ts",
+    "schema/conversation-schema.ts",
     "skills/",
     "scripts/setup-bm.sh",
     "openclaw.plugin.json",

package/schema/conversation-schema.ts

@@ -0,0 +1,33 @@
+/**
+ * Canonical Conversation schema note content, seeded into new projects on first startup.
+ * If the schema already exists (user may have customized it), seeding is skipped.
+ */
+export const CONVERSATION_SCHEMA_CONTENT = `---
+title: Conversation
+type: schema
+entity: Conversation
+version: 1
+schema:
+  date: "string, ISO date YYYY-MM-DD"
+  session_id?: "string, unique session identifier"
+  channel?: "string, where the conversation happened (webchat, telegram, discord, etc)"
+  participants?: "array, who was in the conversation"
+  topic?: "string, brief description of main topic"
+  summary?: "string, one-paragraph summary of key points"
+  key_decisions?: "array, decisions made during conversation"
+  action_items?: "array, things to do as a result"
+settings:
+  validation: warn
+---
+
+# Conversation
+
+A record of a conversation session between the agent and user(s).
+
+## Observations
+- [convention] Conversation files live in memory/conversations/ with format conversations-YYYY-MM-DD.md
+- [convention] Messages are appended as the conversation progresses
+- [convention] Summary and key_decisions populated at session end or by memory-reflect
+- [convention] Skip routine greetings, heartbeat acks, and tool call details
+- [convention] Focus on decisions, actions taken, and key context needed for continuity
+`

package/tools/memory-provider.ts

@@ -60,8 +60,8 @@ async function searchMemoryFile(
 
 /**
  * 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.
+ * Uses search_notes with note_types and status filters for precise querying.
+ * Falls back to filesystem scan if search fails.
  */
 async function searchActiveTasks(
   query: string,
@@ -69,44 +69,29 @@ async function searchActiveTasks(
   workspaceDir: string,
   memoryDir: string,
 ): Promise<string> {
-  // Try structured metadata search first
+  // Try structured 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")
+    const results = await client.search(query || undefined, 10, undefined, {
+      note_types: ["task"],
+      status: "active",
+    })
+
+    if (results.length > 0) {
+      const matches: string[] = []
+      for (const r of results) {
+        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,
-    )
+    log.debug("BM task search failed, falling back to filesystem scan", err)
   }
 
   // Fallback: filesystem scan for tasks not yet indexed