feat: add schema tools, configurable capture threshold, setup script, and simplify moveNote

- Add bm_schema_validate, bm_schema_infer, bm_schema_diff agent tools
  wrapping BM's Picoschema system for note type validation, inference,
  and drift detection
- Add searchByMetadata BmClient method; use it in memory_search task
  scanning instead of free-text query heuristics
- Add captureMinChars config field (default: 10, snake_case alias
  capture_min_chars) so auto-capture threshold is configurable
- Simplify moveNote to a single MCP call using BM's new
  destination_folder parameter — removes the redundant readNote round-trip
- Add scripts/setup-bm.sh for idempotent BM CLI install via uv,
  wired as postinstall in package.json; simplify justfile install recipe
- 18 new tests (161 total), all passing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: phernandez

README.md

@@ -15,16 +15,15 @@ For a practical runbook, see [Memory + Task Flow](./MEMORY_TASK_FLOW.md).
 
 ## Requirements
 
-1. **Basic Memory CLI** (`bm`) with MCP server support:
-   - `bm mcp --transport stdio --project <name>`
-   - MCP tools with JSON output mode: `read_note`, `write_note`, `edit_note`, `recent_activity`, `list_memory_projects`, `create_memory_project`, `delete_note`, `move_note`
-   - Structured MCP tools: `search_notes`, `build_context`
+1. **Basic Memory CLI** (`bm`) — installed automatically by `bun install` when [uv](https://docs.astral.sh/uv/) is available. Manual install:
    ```bash
-   uv tool install 'basic-memory[semantic] @ git+https://github.com/basicmachines-co/basic-memory.git@f2683291e478568cdf1676759ed98c70d7cfdac3' --with 'onnxruntime<1.24; platform_system == "Darwin" and platform_machine == "x86_64"'
+   # Latest main branch (recommended during pre-release):
+   bash scripts/setup-bm.sh
 
-   # Alternative (inside an existing Python environment):
-   uv pip install 'basic-memory[semantic] @ git+https://github.com/basicmachines-co/basic-memory.git@f2683291e478568cdf1676759ed98c70d7cfdac3' 'onnxruntime<1.24; platform_system == "Darwin" and platform_machine == "x86_64"'
+   # Or pin a specific ref:
+   BM_REF=v0.18.4 bash scripts/setup-bm.sh
    ```
+   If `uv` is not installed, the postinstall step is skipped gracefully. Install `uv` first, then re-run `bash scripts/setup-bm.sh`.
 
 2. **OpenClaw** with plugin support
 
@@ -133,6 +132,7 @@ This uses sensible defaults: auto-generated project name, maps Basic Memory to y
       memoryDir: "memory/",                          // Relative memory dir for task scanning
       memoryFile: "MEMORY.md",                       // Working memory file for grep search
       autoCapture: true,                             // Index conversations automatically
+      captureMinChars: 10,                           // Min chars to trigger auto-capture
       debug: false,                                  // Verbose logging
       cloud: {                                       // Optional cloud sync
         url: "https://cloud.basicmemory.com",
@@ -153,6 +153,7 @@ This uses sensible defaults: auto-generated project name, maps Basic Memory to y
 | `memoryDir` | string | `"memory/"` | Relative path for task scanning |
 | `memoryFile` | string | `"MEMORY.md"` | Working memory file (grep-searched) |
 | `autoCapture` | boolean | `true` | Auto-index agent conversations |
+| `captureMinChars` | number | `10` | Minimum character threshold for auto-capture (both messages must be shorter to skip) |
 | `debug` | boolean | `false` | Enable verbose debug logs |
 | `cloud` | object | — | Optional cloud sync config (`url` + `api_key`) |
 
@@ -265,7 +266,7 @@ Done tasks are filtered out of the `Active Tasks` section in composited `memory_
 After each agent turn (when `autoCapture: true`), the plugin:
 1. Extracts the last user + assistant messages
 2. Appends them as timestamped entries to a daily conversation note (`conversations-YYYY-MM-DD`)
-3. Skips very short exchanges (< 10 chars each)
+3. Skips very short exchanges (< `captureMinChars` chars each, default 10)
 
 ## Agent Tools
 
@@ -325,6 +326,26 @@ Navigate the knowledge graph — get a note with its observations and relations.
 bm_context({ url: "memory://projects/api-redesign", depth: 2 })
 ```
 
+### `bm_schema_validate`
+Validate notes against their Picoschema definitions.
+```typescript
+bm_schema_validate({ noteType: "person" })
+bm_schema_validate({ identifier: "notes/john-doe" })
+```
+
+### `bm_schema_infer`
+Analyze existing notes and suggest a Picoschema definition.
+```typescript
+bm_schema_infer({ noteType: "meeting" })
+bm_schema_infer({ noteType: "person", threshold: 0.5 })
+```
+
+### `bm_schema_diff`
+Detect drift between a schema definition and actual note usage.
+```typescript
+bm_schema_diff({ noteType: "person" })
+```
+
 ## Slash Commands
 
 - **`/remember <text>`** — Save a quick note
@@ -458,6 +479,9 @@ openclaw-basic-memory/
 │   ├── delete.ts         # bm_delete
 │   ├── move.ts           # bm_move
 │   ├── context.ts        # bm_context
+│   ├── schema-validate.ts # bm_schema_validate
+│   ├── schema-infer.ts   # bm_schema_infer
+│   ├── schema-diff.ts    # bm_schema_diff
 │   └── memory-provider.ts # Composited memory_search + memory_get
 ├── commands/
 │   ├── slash.ts          # /remember, /recall

bm-client.test.ts

@@ -301,48 +301,169 @@ describe("BmClient MCP behavior", () => {
     expect(result.file_path).toBe("notes/old-note.md")
   })
 
-  it("moveNote preserves source filename and calls move_note", async () => {
-    const callTool = jest
-      .fn()
-      .mockResolvedValueOnce(
-        mcpResult({
-          title: "My Note",
-          permalink: "notes/my-note",
-          content: "body",
-          file_path: "notes/my-note.md",
-          frontmatter: null,
-        }),
-      )
-      .mockResolvedValueOnce(
-        mcpResult({
-          moved: true,
-          title: "My Note",
-          permalink: "archive/my-note",
-          file_path: "archive/my-note.md",
-          source: "notes/my-note.md",
-          destination: "archive/my-note.md",
-        }),
-      )
+  it("schemaValidate calls schema_validate with JSON output", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        entity_type: "person",
+        total_notes: 3,
+        total_entities: 3,
+        valid_count: 3,
+        warning_count: 0,
+        error_count: 0,
+        results: [],
+      }),
+    )
     setConnected(client, callTool)
 
-    const result = await client.moveNote("notes/my-note", "archive")
+    const result = await client.schemaValidate("person")
 
-    expect(callTool).toHaveBeenNthCalledWith(1, {
-      name: "read_note",
+    expect(callTool).toHaveBeenCalledWith({
+      name: "schema_validate",
+      arguments: {
+        note_type: "person",
+        output_format: "json",
+      },
+    })
+    expect(result.entity_type).toBe("person")
+    expect(result.valid_count).toBe(3)
+  })
+
+  it("schemaValidate passes identifier when provided", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        entity_type: null,
+        total_notes: 1,
+        total_entities: 1,
+        valid_count: 1,
+        warning_count: 0,
+        error_count: 0,
+        results: [],
+      }),
+    )
+    setConnected(client, callTool)
+
+    await client.schemaValidate(undefined, "notes/my-note")
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "schema_validate",
       arguments: {
         identifier: "notes/my-note",
-        include_frontmatter: true,
         output_format: "json",
       },
     })
-    expect(callTool).toHaveBeenNthCalledWith(2, {
+  })
+
+  it("schemaInfer calls schema_infer with threshold", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        entity_type: "task",
+        notes_analyzed: 10,
+        field_frequencies: [],
+        suggested_schema: {},
+        suggested_required: [],
+        suggested_optional: [],
+        excluded: [],
+      }),
+    )
+    setConnected(client, callTool)
+
+    const result = await client.schemaInfer("task", 0.5)
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "schema_infer",
+      arguments: {
+        note_type: "task",
+        threshold: 0.5,
+        output_format: "json",
+      },
+    })
+    expect(result.notes_analyzed).toBe(10)
+  })
+
+  it("schemaDiff calls schema_diff with JSON output", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        entity_type: "person",
+        schema_found: true,
+        new_fields: [{ field: "phone", frequency: 0.6 }],
+        dropped_fields: [],
+        cardinality_changes: [],
+      }),
+    )
+    setConnected(client, callTool)
+
+    const result = await client.schemaDiff("person")
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "schema_diff",
+      arguments: {
+        note_type: "person",
+        output_format: "json",
+      },
+    })
+    expect(result.new_fields).toHaveLength(1)
+  })
+
+  it("searchByMetadata calls search_by_metadata with filters", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        results: [
+          {
+            title: "Task 1",
+            permalink: "tasks/task-1",
+            content: "active task",
+            file_path: "tasks/task-1.md",
+            score: 0.9,
+          },
+        ],
+        current_page: 1,
+        page_size: 20,
+      }),
+    )
+    setConnected(client, callTool)
+
+    const result = await client.searchByMetadata(
+      { type: "task", status: "active" },
+      10,
+    )
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search_by_metadata",
+      arguments: {
+        filters: { type: "task", status: "active" },
+        limit: 10,
+        output_format: "json",
+      },
+    })
+    expect(result.results).toHaveLength(1)
+    expect(result.results[0].title).toBe("Task 1")
+  })
+
+  it("moveNote calls move_note with destination_folder in a single MCP call", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        moved: true,
+        title: "My Note",
+        permalink: "archive/my-note",
+        file_path: "archive/my-note.md",
+        source: "notes/my-note",
+        destination: "archive/my-note.md",
+      }),
+    )
+    setConnected(client, callTool)
+
+    const result = await client.moveNote("notes/my-note", "archive")
+
+    expect(callTool).toHaveBeenCalledTimes(1)
+    expect(callTool).toHaveBeenCalledWith({
       name: "move_note",
       arguments: {
         identifier: "notes/my-note",
-        destination_path: "archive/my-note.md",
+        destination_folder: "archive",
         output_format: "json",
       },
     })
+    expect(result.title).toBe("My Note")
     expect(result.file_path).toBe("archive/my-note.md")
   })