Align project bootstrap with workspace memory and default BM project

Author: phernandez

README.md

@@ -85,7 +85,7 @@ Add to your OpenClaw config:
 }
 ```
 
-This uses sensible defaults: auto-generated project name, watches `~/.openclaw/workspace/memory/`, captures conversations.
+This uses sensible defaults: auto-generated project name, maps Basic Memory to your workspace `memory/` directory, and captures conversations.
 
 ### Full configuration
 ```json5
@@ -95,7 +95,7 @@ This uses sensible defaults: auto-generated project name, watches `~/.openclaw/w
     config: {
       project: "my-agent",                          // BM project name (default: "openclaw-{hostname}")
       bmPath: "bm",                                 // Path to BM CLI binary
-      projectPath: "~/.openclaw/workspace/memory/",  // Directory BM watches and indexes
+      projectPath: "~/.openclaw/workspace/memory/",   // Optional override; supports absolute, ~/..., or workspace-relative paths
       memoryDir: "memory/",                          // Relative memory dir for task scanning
       memoryFile: "MEMORY.md",                       // Working memory file for grep search
       autoCapture: true,                             // Index conversations automatically
@@ -115,7 +115,7 @@ This uses sensible defaults: auto-generated project name, watches `~/.openclaw/w
 |--------|------|---------|-------------|
 | `project` | string | `"openclaw-{hostname}"` | Basic Memory project name |
 | `bmPath` | string | `"bm"` | Path to Basic Memory CLI binary |
-| `projectPath` | string | `"~/.openclaw/workspace/memory/"` | Directory for BM project data |
+| `projectPath` | string | `"memory/"` | Directory for BM project data (resolved from workspace unless absolute) |
 | `memoryDir` | string | `"memory/"` | Relative path for task scanning |
 | `memoryFile` | string | `"MEMORY.md"` | Working memory file (grep-searched) |
 | `autoCapture` | boolean | `true` | Auto-index agent conversations |
@@ -124,6 +124,8 @@ This uses sensible defaults: auto-generated project name, watches `~/.openclaw/w
 
 Snake_case aliases (`memory_dir`, `memory_file`) are also supported.
 
+On startup, the plugin ensures the configured BM project exists at `projectPath` by running `bm project add <project> <path> --default` when needed.
+
 ## How It Works
 
 ### File Watching

bm-client.test.ts

@@ -1,6 +1,7 @@
 import { beforeEach, describe, expect, it, jest } from "bun:test"
 import {
   BmClient,
+  isProjectAlreadyExistsError,
   isMissingEditNoteCommandError,
   isNoteNotFoundError,
   isUnsupportedStripFrontmatterError,
@@ -66,6 +67,15 @@ Warning: something happened
         isNoteNotFoundError(new Error("No such command 'edit-note'")),
       ).toBe(false)
     })
+
+    it("detects project already exists errors", () => {
+      expect(
+        isProjectAlreadyExistsError(new Error("Project 'x' already exists")),
+      ).toBe(true)
+      expect(isProjectAlreadyExistsError(new Error("permission denied"))).toBe(
+        false,
+      )
+    })
   })
 })
 
@@ -172,6 +182,54 @@ describe("BmClient behavior", () => {
     )
   })
 
+  it("ensureProject ignores already-exists errors", async () => {
+    const execRaw = jest
+      .fn()
+      .mockRejectedValue(new Error("Project 'test-project' already exists"))
+    ;(client as any).execRaw = execRaw
+
+    await expect(client.ensureProject("/tmp/memory")).resolves.toBeUndefined()
+    expect(execRaw).toHaveBeenCalledWith([
+      "project",
+      "add",
+      "test-project",
+      "/tmp/memory",
+      "--default",
+    ])
+  })
+
+  it("ensureProject throws when project creation fails for other reasons", async () => {
+    const execRaw = jest
+      .fn()
+      .mockRejectedValue(new Error("permission denied"))
+    ;(client as any).execRaw = execRaw
+
+    await expect(client.ensureProject("/tmp/memory")).rejects.toThrow(
+      'failed to ensure project "test-project" at "/tmp/memory"',
+    )
+    expect(execRaw).toHaveBeenCalledWith([
+      "project",
+      "add",
+      "test-project",
+      "/tmp/memory",
+      "--default",
+    ])
+  })
+
+  it("ensureProject passes --default when project is created", async () => {
+    const execRaw = jest.fn().mockResolvedValue("")
+    ;(client as any).execRaw = execRaw
+
+    await expect(client.ensureProject("/tmp/memory")).resolves.toBeUndefined()
+    expect(execRaw).toHaveBeenCalledWith([
+      "project",
+      "add",
+      "test-project",
+      "/tmp/memory",
+      "--default",
+    ])
+  })
+
   it("indexConversation does not create fallback note on non-not-found edit errors", async () => {
     ;(client as any).editNote = jest
       .fn()

bm-client.ts

@@ -122,6 +122,11 @@ export function isMissingEditNoteCommandError(err: unknown): boolean {
   )
 }
 
+export function isProjectAlreadyExistsError(err: unknown): boolean {
+  const msg = getErrorMessage(err).toLowerCase()
+  return msg.includes("project") && msg.includes("already exists")
+}
+
 export function isNoteNotFoundError(err: unknown): boolean {
   const msg = getErrorMessage(err).toLowerCase()
   if (isMissingEditNoteCommandError(err)) return false
@@ -194,10 +199,23 @@ export class BmClient {
 
   async ensureProject(projectPath: string): Promise<void> {
     try {
-      await this.execRaw(["project", "add", this.project, projectPath])
-    } catch {
-      // Silently ignore — most likely the project already exists.
-      // This is expected on every restart after first setup.
+      await this.execRaw([
+        "project",
+        "add",
+        this.project,
+        projectPath,
+        "--default",
+      ])
+    } catch (err) {
+      if (isProjectAlreadyExistsError(err)) {
+        // Expected after first startup.
+        return
+      }
+      throw new Error(
+        `failed to ensure project "${this.project}" at "${projectPath}": ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      )
     }
   }
 

commands/cli.ts

@@ -158,6 +158,7 @@ export function registerCli(
         .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}`)

config.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test"
-import { parseConfig } from "./config.ts"
+import { homedir } from "node:os"
+import { parseConfig, resolveProjectPath } from "./config.ts"
 
 describe("config", () => {
   describe("parseConfig", () => {
@@ -12,7 +13,7 @@ describe("config", () => {
       expect(config.autoCapture).toBe(true)
       expect(config.debug).toBe(false)
       expect(config.project).toMatch(/^openclaw-/)
-      expect(config.projectPath).toMatch(/\.openclaw\/workspace\/memory\//)
+      expect(config.projectPath).toBe("memory/")
       expect(config.cloud).toBeUndefined()
     })
 
@@ -67,6 +68,11 @@ describe("config", () => {
       expect(config.projectPath).toBe("/custom/project/path")
     })
 
+    it("should default projectPath to memoryDir", () => {
+      const config = parseConfig({ memoryDir: "notes/" })
+      expect(config.projectPath).toBe("notes/")
+    })
+
     it("should use provided autoCapture", () => {
       expect(parseConfig({ autoCapture: false }).autoCapture).toBe(false)
       expect(parseConfig({ autoCapture: true }).autoCapture).toBe(true)
@@ -124,4 +130,24 @@ describe("config", () => {
       expect(() => parseConfig({})).not.toThrow()
     })
   })
+
+  describe("resolveProjectPath", () => {
+    it("resolves relative projectPath against workspace", () => {
+      expect(resolveProjectPath("memory/", "/tmp/workspace")).toBe(
+        "/tmp/workspace/memory",
+      )
+    })
+
+    it("expands tilde paths", () => {
+      expect(resolveProjectPath("~/memory", "/tmp/workspace")).toBe(
+        `${homedir()}/memory`,
+      )
+    })
+
+    it("keeps absolute paths unchanged", () => {
+      expect(resolveProjectPath("/var/data/memory", "/tmp/workspace")).toBe(
+        "/var/data/memory",
+      )
+    })
+  })
 })

config.ts

@@ -1,4 +1,5 @@
 import { homedir, hostname } from "node:os"
+import { isAbsolute, resolve } from "node:path"
 
 export type CloudConfig = {
   url: string
@@ -46,6 +47,18 @@ function defaultProject(): string {
     .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)
@@ -87,7 +100,7 @@ export function parseConfig(raw: unknown): BasicMemoryConfig {
     projectPath:
       typeof cfg.projectPath === "string" && cfg.projectPath.length > 0
         ? cfg.projectPath
-        : `${homedir()}/.openclaw/workspace/memory/`,
+        : memoryDir,
     bmPath:
       typeof cfg.bmPath === "string" && cfg.bmPath.length > 0
         ? cfg.bmPath

index.ts

@@ -4,7 +4,11 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { BmClient } from "./bm-client.ts"
 import { registerCli } from "./commands/cli.ts"
 import { registerCommands } from "./commands/slash.ts"
-import { basicMemoryConfigSchema, parseConfig } from "./config.ts"
+import {
+  basicMemoryConfigSchema,
+  parseConfig,
+  resolveProjectPath,
+} from "./config.ts"
 import { buildCaptureHandler } from "./hooks/capture.ts"
 import { initLogger, log } from "./logger.ts"
 import { registerContextTool } from "./tools/context.ts"
@@ -62,10 +66,13 @@ export default {
       start: async (ctx: { config?: unknown; workspaceDir?: string }) => {
         log.info("starting...")
 
-        await client.ensureProject(cfg.projectPath)
-        log.debug(`project "${cfg.project}" at ${cfg.projectPath}`)
-
         const workspace = ctx.workspaceDir ?? process.cwd()
+        const projectPath = resolveProjectPath(cfg.projectPath, workspace)
+        cfg.projectPath = projectPath
+
+        await client.ensureProject(projectPath)
+        log.debug(`project "${cfg.project}" at ${projectPath}`)
+
         setWorkspaceDir(workspace)
 
         // Start `bm watch` as a long-running child process.

openclaw.plugin.json

@@ -40,8 +40,8 @@
     },
     "projectPath": {
       "label": "Project Path",
-      "placeholder": "~/.basic-memory/openclaw/",
-      "help": "Filesystem path for the Basic Memory project data",
+      "placeholder": "~/.openclaw/workspace/memory/",
+      "help": "Filesystem path for Basic Memory project data (relative paths resolve from workspace); created automatically if missing",
       "advanced": true
     },
     "cloud": {