@basicmemory/openclaw-basic-memory 0.2.3 → 0.23.0

package/README.md

@@ -18,6 +18,14 @@ Over time, your agent builds a knowledge base that grows with you. Context that
 
 Learn more: [basicmemory.com](https://basicmemory.com) · [GitHub](https://github.com/basicmachines-co/basic-memory) · [Docs](https://docs.basicmemory.com)
 
+Source now lives in the canonical [`basic-memory`](https://github.com/basicmachines-co/basic-memory) repository under `integrations/openclaw/`. The npm package remains `@basicmemory/openclaw-basic-memory`.
+
+Maintainer check from the monorepo root:
+
+```bash
+just package-check-openclaw
+```
+
 ## What this plugin does
 
 This plugin connects Basic Memory to OpenClaw so your agent can:
@@ -45,6 +53,7 @@ Then install the plugin:
 
 ```bash
 openclaw plugins install @basicmemory/openclaw-basic-memory
+openclaw plugins enable openclaw-basic-memory --slot memory
 openclaw gateway restart
 ```
 
@@ -54,7 +63,8 @@ Verify:
 
 ```bash
 openclaw plugins list
-openclaw plugins info openclaw-basic-memory
+openclaw plugins inspect openclaw-basic-memory --json
+openclaw plugins doctor
 ```
 
 ## Configuration
@@ -63,8 +73,15 @@ openclaw plugins info openclaw-basic-memory
 
 ```json5
 {
-  "openclaw-basic-memory": {
-    enabled: true
+  plugins: {
+    entries: {
+      "openclaw-basic-memory": {
+        enabled: true
+      }
+    },
+    slots: {
+      memory: "openclaw-basic-memory"
+    }
   }
 }
 ```
@@ -75,16 +92,23 @@ This uses sensible defaults: auto-generated project name, maps to your workspace
 
 ```json5
 {
-  "openclaw-basic-memory": {
-    enabled: true,
-    config: {
-      project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
-      projectPath: ".",            // Project directory (default: workspace root)
-      memoryDir: "memory/",        // Where task notes live
-      memoryFile: "MEMORY.md",     // Working memory file
-      autoCapture: true,           // Record conversations as daily notes
-      autoRecall: true,            // Inject active tasks + recent activity at session start
-      debug: false                 // Verbose logging
+  plugins: {
+    entries: {
+      "openclaw-basic-memory": {
+        enabled: true,
+        config: {
+          project: "my-agent",        // BM project name (default: "openclaw-{hostname}")
+          projectPath: ".",            // Project directory (default: workspace root)
+          memoryDir: "memory/",        // Where task notes live
+          memoryFile: "MEMORY.md",     // Working memory file
+          autoCapture: true,           // Record conversations as daily notes
+          autoRecall: true,            // Inject active tasks + recent activity at session start
+          debug: false                 // Verbose logging
+        }
+      }
+    },
+    slots: {
+      memory: "openclaw-basic-memory"
     }
   }
 }
@@ -172,21 +196,27 @@ openclaw basic-memory status
 
 ## Bundled skills
 
-Six skills ship with the plugin — no installation needed:
+Ten skills ship with the plugin — no installation needed:
 
-- **memory-tasks** — structured task tracking that survives context compaction
-- **memory-reflect** — periodic consolidation of recent notes into durable memory
 - **memory-defrag** — cleanup and reorganization of memory files
-- **memory-schema** — schema lifecycle (infer, create, validate, diff)
+- **memory-ingest** — import existing material into Basic Memory
+- **memory-lifecycle** — manage note/project lifecycle workflows
+- **memory-literary-analysis** — analyze texts and reading notes
 - **memory-metadata-search** — query notes by frontmatter fields
 - **memory-notes** — guidance for writing well-structured notes
+- **memory-reflect** — periodic consolidation of recent notes into durable memory
+- **memory-research** — research synthesis into durable notes
+- **memory-schema** — schema lifecycle (infer, create, validate, diff)
+- **memory-tasks** — structured task tracking that survives context compaction
 
 ### Updating skills
 
 ```bash
-npx skills add basicmachines-co/basic-memory-skills --agent openclaw
+bun run fetch-skills
 ```
 
+In the monorepo, this copies from the canonical top-level [`skills/`](../../skills) directory into the generated `integrations/openclaw/skills/` package bundle.
+
 ## Task notes
 
 The plugin works well with structured task notes in `memory/tasks/`:
@@ -238,7 +268,7 @@ Cloud extends local-first — still plain Markdown, still yours. [Start a free t
 - [Security](./SECURITY.md) — how auto-installation and data handling work
 - [Development](./DEVELOPMENT.md) — contributing, tests, publishing
 - [Basic Memory docs](https://docs.basicmemory.com)
-- [Issues](https://github.com/basicmachines-co/openclaw-basic-memory/issues)
+- [Issues](https://github.com/basicmachines-co/basic-memory/issues)
 
 ## Telemetry
 

package/bm-client.ts

@@ -100,6 +100,7 @@ export interface ProjectListResult {
   is_default?: boolean
   isDefault?: boolean
   workspace_name?: string | null
+  workspace_slug?: string | null
   workspace_type?: string | null
   workspace_tenant_id?: string | null
 }
@@ -198,7 +199,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") ||
@@ -213,6 +214,22 @@ function asString(value: unknown): string | null {
   return typeof value === "string" ? value : null
 }
 
+function projectMatchesWorkspace(
+  project: ProjectListResult,
+  workspace: string,
+): boolean {
+  const requested = workspace.trim().toLowerCase()
+  if (!requested) return true
+
+  return [
+    project.workspace_name,
+    project.workspace_slug,
+    project.workspace_tenant_id,
+  ].some(
+    (value) => typeof value === "string" && value.toLowerCase() === requested,
+  )
+}
+
 export class BmClient {
   private bmPath: string
   private project: string
@@ -465,6 +482,10 @@ export class BmClient {
     return structuredPayload
   }
 
+  private routedProject(project?: string): string {
+    return project ?? this.project
+  }
+
   async ensureProject(projectPath: string): Promise<void> {
     const payload = await this.callTool("create_memory_project", {
       project_name: this.project,
@@ -491,13 +512,18 @@ export class BmClient {
   }
 
   async listProjects(workspace?: string): Promise<ProjectListResult[]> {
-    const args: Record<string, unknown> = { output_format: "json" }
-    if (workspace) args.workspace = workspace
-
-    const payload = await this.callTool("list_memory_projects", args)
+    const payload = await this.callTool("list_memory_projects", {
+      output_format: "json",
+    })
 
     if (isRecord(payload) && Array.isArray(payload.projects)) {
-      return payload.projects as ProjectListResult[]
+      const projects = payload.projects as ProjectListResult[]
+      if (workspace) {
+        return projects.filter((project) =>
+          projectMatchesWorkspace(project, workspace),
+        )
+      }
+      return projects
     }
 
     throw new Error("invalid list_memory_projects response")
@@ -519,9 +545,9 @@ export class BmClient {
       page: 1,
       page_size: limit,
       output_format: "json",
+      project: this.routedProject(project),
     }
     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
@@ -546,8 +572,8 @@ export class BmClient {
       identifier,
       include_frontmatter: options.includeFrontmatter === true,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("read_note", args)
 
@@ -585,8 +611,8 @@ export class BmClient {
       content,
       directory: folder,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
     if (overwrite !== undefined) args.overwrite = overwrite
 
     const payload = await this.callTool("write_note", args)
@@ -632,8 +658,8 @@ export class BmClient {
       url,
       depth,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("build_context", args)
 
@@ -651,8 +677,8 @@ export class BmClient {
     const args: Record<string, unknown> = {
       timeframe,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("recent_activity", args)
 
@@ -675,12 +701,12 @@ export class BmClient {
       operation,
       content,
       output_format: "json",
+      project: this.routedProject(project),
     }
     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)
 
@@ -712,8 +738,8 @@ export class BmClient {
     const args: Record<string, unknown> = {
       identifier,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("delete_note", args)
 
@@ -741,8 +767,8 @@ export class BmClient {
       identifier,
       destination_folder: newFolder,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("move_note", args)
 
@@ -770,10 +796,12 @@ export class BmClient {
     identifier?: string,
     project?: string,
   ): Promise<SchemaValidationResult> {
-    const args: Record<string, unknown> = { output_format: "json" }
+    const args: Record<string, unknown> = {
+      output_format: "json",
+      project: this.routedProject(project),
+    }
     if (noteType) args.note_type = noteType
     if (identifier) args.identifier = identifier
-    if (project) args.project = project
 
     const payload = await this.callTool("schema_validate", args)
 
@@ -793,8 +821,8 @@ export class BmClient {
       note_type: noteType,
       threshold,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("schema_infer", args)
 
@@ -812,8 +840,8 @@ export class BmClient {
     const args: Record<string, unknown> = {
       note_type: noteType,
       output_format: "json",
+      project: this.routedProject(project),
     }
-    if (project) args.project = project
 
     const payload = await this.callTool("schema_diff", args)
 
@@ -845,13 +873,19 @@ 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) {
-      log.debug(`append failed, will create: ${getErrorMessage(err)}`)
+      if (!isNoteNotFoundError(err)) {
+        log.error(`conversation append failed: ${getErrorMessage(err)}`, err)
+        throw err
+      }
+
+      log.debug(
+        `conversation note missing, will create: ${getErrorMessage(err)}`,
+      )
     }
 
     // Create the note with frontmatter and first entry
@@ -868,7 +902,7 @@ export class BmClient {
     ].join("\n")
 
     try {
-      await this.writeNote(title, content, "conversations", undefined, true)
+      await this.writeNote(title, content, "conversations")
       log.debug(`created conversation note: ${title}`)
     } catch (err) {
       log.error("conversation index failed", err)

package/commands/cli.ts

@@ -1,4 +1,4 @@
-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"
@@ -167,7 +167,6 @@ export function registerCli(
           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}`)
         })
     },

package/commands/skills.ts

@@ -1,11 +1,9 @@
-import { readFileSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const SKILLS_DIR = resolve(__dirname, "..", "skills")
-const MANIFEST_PATH = resolve(SKILLS_DIR, "manifest.json")
 
 interface ManifestEntry {
   dir: string
@@ -13,9 +11,22 @@ interface ManifestEntry {
   description: string
 }
 
-function loadManifest(): ManifestEntry[] {
+function resolveSkillsDir(api: OpenClawPluginApi): string {
+  if (api.resolvePath) {
+    return api.resolvePath("skills")
+  }
+
+  const sourceRootSkills = resolve(__dirname, "..", "skills")
+  if (existsSync(sourceRootSkills)) {
+    return sourceRootSkills
+  }
+
+  return resolve(__dirname, "..", "..", "skills")
+}
+
+function loadManifest(skillsDir: string): ManifestEntry[] {
   try {
-    const raw = readFileSync(MANIFEST_PATH, "utf-8")
+    const raw = readFileSync(resolve(skillsDir, "manifest.json"), "utf-8")
     return JSON.parse(raw) as ManifestEntry[]
   } catch {
     throw new Error(
@@ -24,16 +35,66 @@ function loadManifest(): ManifestEntry[] {
   }
 }
 
-function loadSkill(dir: string): string {
-  return readFileSync(resolve(SKILLS_DIR, dir, "SKILL.md"), "utf-8")
+function loadSkill(skillsDir: string, dir: string): string {
+  return readFileSync(resolve(skillsDir, dir, "SKILL.md"), "utf-8")
+}
+
+/**
+ * List a skill's bundled resource files (references/, assets/, ...) so the
+ * command can tell the assistant where they live on disk. SKILL.md workflows
+ * reference these by relative path; without the mapping, bundled commands
+ * would direct the assistant to files it was never given. evals/ is excluded
+ * as test fixtures.
+ */
+function listResourceFiles(skillsDir: string, dir: string): string[] {
+  const root = resolve(skillsDir, dir)
+  const files: string[] = []
+  const walk = (rel: string) => {
+    for (const entry of readdirSync(resolve(root, rel), {
+      withFileTypes: true,
+    })) {
+      const relPath = rel ? `${rel}/${entry.name}` : entry.name
+      if (entry.isDirectory()) {
+        if (relPath !== "evals") walk(relPath)
+      } else if (relPath !== "SKILL.md") {
+        files.push(relPath)
+      }
+    }
+  }
+  walk("")
+  return files.sort()
+}
+
+function resourceSection(
+  skillsDir: string,
+  dir: string,
+  files: string[],
+): string {
+  if (files.length === 0) return ""
+  const lines = files
+    .map((f) => `- \`${f}\` → ${resolve(skillsDir, dir, f)}`)
+    .join("\n")
+  return (
+    "\n\n## Bundled resource files\n\n" +
+    "This skill references companion files by relative path. They are installed at:\n\n" +
+    `${lines}\n\n` +
+    "When the workflow directs you to read one of these files, read it from the absolute path listed above."
+  )
 }
 
 export function registerSkillCommands(api: OpenClawPluginApi): void {
-  const manifest = loadManifest()
+  const skillsDir = resolveSkillsDir(api)
+  const manifest = loadManifest(skillsDir)
 
   for (const entry of manifest) {
     const commandName = entry.dir.replace(/^memory-/, "")
-    const content = loadSkill(entry.dir)
+    const content =
+      loadSkill(skillsDir, entry.dir) +
+      resourceSection(
+        skillsDir,
+        entry.dir,
+        listResourceFiles(skillsDir, entry.dir),
+      )
 
     api.registerCommand({
       name: commandName,

package/commands/slash.ts

@@ -1,7 +1,7 @@
 import { execSync } from "node:child_process"
 import { dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-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"
 
@@ -16,7 +16,9 @@ export function registerCommands(
     description: "Install or update the Basic Memory CLI (requires uv)",
     requireAuth: true,
     handler: async () => {
-      const scriptPath = resolve(__dirname, "..", "scripts", "setup-bm.sh")
+      const scriptPath = api.resolvePath
+        ? api.resolvePath("scripts/setup-bm.sh")
+        : resolve(__dirname, "..", "scripts", "setup-bm.sh")
       log.info(`/bm-setup: running ${scriptPath}`)
 
       try {

package/config.ts

@@ -1,11 +1,6 @@
 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
@@ -17,7 +12,6 @@ export type BasicMemoryConfig = {
   autoRecall: boolean
   recallPrompt: string
   debug: boolean
-  cloud?: CloudConfig
 }
 
 const ALLOWED_KEYS = [
@@ -36,7 +30,6 @@ const ALLOWED_KEYS = [
   "recallPrompt",
   "recall_prompt",
   "debug",
-  "cloud",
 ]
 
 function assertAllowedKeys(
@@ -98,14 +91,6 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
         ? (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
@@ -143,7 +128,6 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
           ? (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,
   }
 }