@basicmemory/openclaw-basic-memory 0.2.4 → 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:
@@ -207,6 +215,8 @@ Ten skills ship with the plugin — no installation needed:
 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/`:
@@ -258,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

@@ -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,4 +1,4 @@
-import { existsSync, 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/plugin-entry"
@@ -39,13 +39,62 @@ 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 skillsDir = resolveSkillsDir(api)
   const manifest = loadManifest(skillsDir)
 
   for (const entry of manifest) {
     const commandName = entry.dir.replace(/^memory-/, "")
-    const content = loadSkill(skillsDir, entry.dir)
+    const content =
+      loadSkill(skillsDir, entry.dir) +
+      resourceSection(
+        skillsDir,
+        entry.dir,
+        listResourceFiles(skillsDir, entry.dir),
+      )
 
     api.registerCommand({
       name: commandName,

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,15 +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>
-    assertAllowedKeys(c, ["url", "api_key"], "basic-memory cloud config")
-    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
@@ -144,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,
   }
 }
 

package/context-engine/basic-memory-context-engine.ts

@@ -1,4 +1,10 @@
-import type { AgentMessage } from "@mariozechner/pi-agent-core"
+import type {
+  AssembleResult,
+  BootstrapResult,
+  CompactResult,
+  ContextEngine,
+  SubagentSpawnPreparation,
+} from "openclaw/plugin-sdk"
 import { delegateCompactionToRuntime } from "openclaw/plugin-sdk/core"
 import type { BmClient } from "../bm-client.ts"
 import type { BasicMemoryConfig } from "../config.ts"
@@ -11,41 +17,16 @@ const TRUNCATED_RECALL_SUFFIX = "\n\n[Basic Memory recall truncated]"
 const SUBAGENT_HANDOFF_FOLDER = "agent/subagents"
 const MAX_SUBAGENT_RECALL_CHARS = 800
 
-type AssembleResult = {
-  messages: AgentMessage[]
-  estimatedTokens: number
-  systemPromptAddition?: string
-}
-
-type BootstrapResult = {
-  bootstrapped: boolean
-  importedMessages?: number
-  reason?: string
-}
-
-type CompactResult = {
-  ok: boolean
-  compacted: boolean
-  reason?: string
-  result?: {
-    summary?: string
-    firstKeptEntryId?: string
-    tokensBefore: number
-    tokensAfter?: number
-    details?: unknown
-    sessionId?: string
-    sessionFile?: string
-  }
-}
-
-interface ContextEngine {
-  readonly info: {
-    id: string
-    name: string
-    version?: string
-    ownsCompaction?: boolean
-  }
-}
+type BootstrapParams = Parameters<NonNullable<ContextEngine["bootstrap"]>>[0]
+type AssembleParams = Parameters<ContextEngine["assemble"]>[0]
+type AfterTurnParams = Parameters<NonNullable<ContextEngine["afterTurn"]>>[0]
+type CompactParams = Parameters<ContextEngine["compact"]>[0]
+type PrepareSubagentSpawnParams = Parameters<
+  NonNullable<ContextEngine["prepareSubagentSpawn"]>
+>[0]
+type OnSubagentEndedParams = Parameters<
+  NonNullable<ContextEngine["onSubagentEnded"]>
+>[0]
 
 interface SessionMemoryState {
   recallContext: string
@@ -147,10 +128,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
     private readonly cfg: BasicMemoryConfig,
   ) {}
 
-  async bootstrap(params: {
-    sessionId: string
-    sessionFile: string
-  }): Promise<BootstrapResult> {
+  async bootstrap(params: BootstrapParams): Promise<BootstrapResult> {
     if (!this.cfg.autoRecall) {
       this.sessionState.delete(params.sessionId)
       return { bootstrapped: false, reason: "autoRecall disabled" }
@@ -183,11 +161,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
     return { ingested: false }
   }
 
-  async assemble(params: {
-    sessionId: string
-    messages: AgentMessage[]
-    tokenBudget?: number
-  }): Promise<AssembleResult> {
+  async assemble(params: AssembleParams): Promise<AssembleResult> {
     const state = this.sessionState.get(params.sessionId)
 
     return {
@@ -197,16 +171,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
     }
   }
 
-  async afterTurn(params: {
-    sessionId: string
-    sessionFile: string
-    messages: AgentMessage[]
-    prePromptMessageCount: number
-    autoCompactionSummary?: string
-    isHeartbeat?: boolean
-    tokenBudget?: number
-    runtimeContext?: Record<string, unknown>
-  }): Promise<void> {
+  async afterTurn(params: AfterTurnParams): Promise<void> {
     if (!this.cfg.autoCapture) return
 
     const newMessages = params.messages.slice(params.prePromptMessageCount)
@@ -227,24 +192,13 @@ export class BasicMemoryContextEngine implements ContextEngine {
     }
   }
 
-  async compact(params: {
-    sessionId: string
-    sessionFile: string
-    tokenBudget?: number
-    force?: boolean
-    currentTokenCount?: number
-    compactionTarget?: "budget" | "threshold"
-    customInstructions?: string
-    runtimeContext?: Record<string, unknown>
-  }): Promise<CompactResult> {
+  async compact(params: CompactParams): Promise<CompactResult> {
     return delegateCompactionToRuntime(params)
   }
 
-  async prepareSubagentSpawn(params: {
-    parentSessionKey: string
-    childSessionKey: string
-    ttlMs?: number
-  }): Promise<{ rollback: () => Promise<void> } | undefined> {
+  async prepareSubagentSpawn(
+    params: PrepareSubagentSpawnParams,
+  ): Promise<SubagentSpawnPreparation | undefined> {
     const parentState = this.sessionState.get(params.parentSessionKey)
     const noteTitle = buildSubagentNoteTitle(params.childSessionKey)
 
@@ -284,10 +238,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
     }
   }
 
-  async onSubagentEnded(params: {
-    childSessionKey: string
-    reason: "deleted" | "completed" | "swept" | "released"
-  }): Promise<void> {
+  async onSubagentEnded(params: OnSubagentEndedParams): Promise<void> {
     const handoff = this.subagentState.get(params.childSessionKey)
     if (!handoff) return
 

package/dist/bm-client.d.ts

@@ -64,6 +64,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;
 }
@@ -147,6 +148,7 @@ export declare class BmClient {
     private disconnectCurrent;
     private callToolRaw;
     private callTool;
+    private routedProject;
     ensureProject(projectPath: string): Promise<void>;
     listWorkspaces(): Promise<WorkspaceResult[]>;
     listProjects(workspace?: string): Promise<ProjectListResult[]>;