feat: add metadata filter support to bm_search tool and register new skills

Extend bm_search with optional metadata_filters, tags, and status parameters
so the agent has one unified search tool for both text and structured queries.
Register memory-notes and memory-metadata-search as slash command skills.

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

Author: phernandez

bm-client.test.ts

@@ -172,6 +172,64 @@ describe("BmClient MCP behavior", () => {
     expect(results[0].title).toBe("x")
   })
 
+  it("search passes metadata_filters, tags, and status to search_notes", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({
+        results: [
+          {
+            title: "Auth Design",
+            permalink: "auth-design",
+            content: "OAuth spec",
+            file_path: "specs/auth-design.md",
+            score: 0.85,
+          },
+        ],
+      }),
+    )
+    setConnected(client, callTool)
+
+    const results = await client.search("oauth", 5, "research", {
+      filters: { type: "spec", confidence: { $gt: 0.7 } },
+      tags: ["security"],
+      status: "in-progress",
+    })
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search_notes",
+      arguments: {
+        query: "oauth",
+        page: 1,
+        page_size: 5,
+        output_format: "json",
+        project: "research",
+        metadata_filters: { type: "spec", confidence: { $gt: 0.7 } },
+        tags: ["security"],
+        status: "in-progress",
+      },
+    })
+    expect(results).toHaveLength(1)
+    expect(results[0].title).toBe("Auth Design")
+  })
+
+  it("search omits metadata args when not provided", async () => {
+    const callTool = jest.fn().mockResolvedValue(
+      mcpResult({ results: [] }),
+    )
+    setConnected(client, callTool)
+
+    await client.search("test", 10)
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search_notes",
+      arguments: {
+        query: "test",
+        page: 1,
+        page_size: 10,
+        output_format: "json",
+      },
+    })
+  })
+
   it("buildContext calls build_context using output_format=json", async () => {
     const callTool = jest.fn().mockResolvedValue(
       mcpResult({

bm-client.ts

@@ -499,6 +499,11 @@ export class BmClient {
     query: string,
     limit = 10,
     project?: string,
+    metadata?: {
+      filters?: Record<string, unknown>
+      tags?: string[]
+      status?: string
+    },
   ): Promise<SearchResult[]> {
     const args: Record<string, unknown> = {
       query,
@@ -507,6 +512,9 @@ export class BmClient {
       output_format: "json",
     }
     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
 
     const payload = await this.callTool("search_notes", args)
 

commands/skills.test.ts

@@ -3,19 +3,19 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import { registerSkillCommands } from "./skills.ts"
 
 describe("skill slash commands", () => {
-  it("should register all four skill commands", () => {
+  it("should register all skill commands", () => {
     const mockApi = {
       registerCommand: jest.fn(),
     } as unknown as OpenClawPluginApi
 
     registerSkillCommands(mockApi)
 
-    expect(mockApi.registerCommand).toHaveBeenCalledTimes(4)
+    expect(mockApi.registerCommand).toHaveBeenCalledTimes(6)
 
     const names = (
       mockApi.registerCommand as jest.MockedFunction<any>
     ).mock.calls.map((call: any[]) => call[0].name)
-    expect(names).toEqual(["tasks", "reflect", "defrag", "schema"])
+    expect(names).toEqual(["tasks", "reflect", "defrag", "schema", "notes", "metadata-search"])
   })
 
   it("should set correct metadata on each command", () => {
@@ -91,6 +91,12 @@ describe("skill slash commands", () => {
 
       const schemaResult = await commands.schema.handler({})
       expect(schemaResult.text).toContain("## Picoschema Syntax Reference")
+
+      const notesResult = await commands.notes.handler({})
+      expect(notesResult.text).toContain("## Note Anatomy")
+
+      const metadataResult = await commands["metadata-search"].handler({})
+      expect(metadataResult.text).toContain("## Filter Syntax")
     })
   })
 })

commands/skills.ts

@@ -19,6 +19,8 @@ const SKILLS = [
   },
   { name: "defrag", dir: "memory-defrag", desc: "Memory defrag workflow" },
   { name: "schema", dir: "memory-schema", desc: "Schema management workflow" },
+  { name: "notes", dir: "memory-notes", desc: "How to write well-structured notes" },
+  { name: "metadata-search", dir: "memory-metadata-search", desc: "Structured metadata search workflow" },
 ] as const
 
 export function registerSkillCommands(api: OpenClawPluginApi): void {

skills/memory-metadata-search/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: memory-metadata-search
+description: "Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content."
+---
+
+# Memory Metadata Search
+
+Find notes by their structured frontmatter fields instead of (or in addition to) free-text content. Any custom YAML key in a note's frontmatter beyond the standard set (`title`, `type`, `tags`, `permalink`, `schema`) is automatically indexed as `entity_metadata` and becomes queryable.
+
+## When to Use
+
+- **Filtering by status or priority** — find all notes with `status: draft` or `priority: high`
+- **Querying custom fields** — any frontmatter key you invent is searchable
+- **Range queries** — find notes with `confidence > 0.7` or `score between 0.3 and 0.8`
+- **Combining text + metadata** — narrow a text search with structured constraints
+- **Tag-based filtering** — find notes tagged with specific frontmatter tags
+- **Schema-aware queries** — filter by nested schema fields using dot notation
+
+## Tool
+
+Use the `bm_search` tool with the optional `metadata_filters`, `tags`, and `status` parameters.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Text search query (can be empty for filter-only searches) |
+| `metadata_filters` | object | Filter by frontmatter fields (see filter syntax below) |
+| `tags` | string[] | Filter by frontmatter tags (all must match) |
+| `status` | string | Filter by frontmatter status field |
+
+## Filter Syntax
+
+Filters are a JSON dictionary. Each key targets a frontmatter field; the value specifies the match condition. Multiple keys combine with **AND** logic.
+
+### Equality
+
+```json
+{"status": "active"}
+```
+
+### Array Contains (all listed values must be present)
+
+```json
+{"tags": ["security", "oauth"]}
+```
+
+### `$in` (match any value in list)
+
+```json
+{"priority": {"$in": ["high", "critical"]}}
+```
+
+### Comparisons (`$gt`, `$gte`, `$lt`, `$lte`)
+
+```json
+{"confidence": {"$gt": 0.7}}
+```
+
+Numeric values use numeric comparison; strings use lexicographic comparison.
+
+### `$between` (inclusive range)
+
+```json
+{"score": {"$between": [0.3, 0.8]}}
+```
+
+### Nested Access (dot notation)
+
+```json
+{"schema.version": "2"}
+```
+
+### Quick Reference
+
+| Operator | Syntax | Example |
+|----------|--------|---------|
+| Equality | `{"field": "value"}` | `{"status": "active"}` |
+| Array contains | `{"field": ["a", "b"]}` | `{"tags": ["security", "oauth"]}` |
+| `$in` | `{"field": {"$in": [...]}}` | `{"priority": {"$in": ["high", "critical"]}}` |
+| `$gt` / `$gte` | `{"field": {"$gt": N}}` | `{"confidence": {"$gt": 0.7}}` |
+| `$lt` / `$lte` | `{"field": {"$lt": N}}` | `{"score": {"$lt": 0.5}}` |
+| `$between` | `{"field": {"$between": [lo, hi]}}` | `{"score": {"$between": [0.3, 0.8]}}` |
+| Nested | `{"a.b": "value"}` | `{"schema.version": "2"}` |
+
+**Rules:**
+- Keys must match `[A-Za-z0-9_-]+` (dots separate nesting levels)
+- Operator dicts must contain exactly one operator
+- `$in` and array-contains require non-empty lists
+- `$between` requires exactly `[min, max]`
+
+## Examples
+
+### Metadata-only search (empty query)
+
+```
+bm_search(query="", metadata_filters={"status": "in-progress", "type": "spec"})
+```
+
+### Text search narrowed by metadata
+
+```
+bm_search(query="authentication", metadata_filters={"status": "draft"})
+```
+
+### Filter by tags
+
+```
+bm_search(query="", tags=["security", "oauth"])
+```
+
+### Filter by status shortcut
+
+```
+bm_search(query="planning", status="active")
+```
+
+### Combined text + metadata + tags
+
+```
+bm_search(
+    query="oauth flow",
+    metadata_filters={"confidence": {"$gt": 0.7}},
+    tags=["security"],
+    status="in-progress",
+)
+```
+
+### High-priority notes in a specific project
+
+```
+bm_search(
+    query="",
+    metadata_filters={"priority": {"$in": ["high", "critical"]}},
+    project="research",
+    limit=10,
+)
+```
+
+### Numeric range query
+
+```
+bm_search(query="", metadata_filters={"score": {"$between": [0.3, 0.8]}})
+```
+
+## Tag Search Shorthand
+
+The `tag:` prefix in a query converts to a tag filter automatically:
+
+```
+# These are equivalent:
+bm_search(query="tag:tier1")
+bm_search(query="", tags=["tier1"])
+
+# Multiple tags (comma or space separated) — all must match:
+bm_search(query="tag:tier1,alpha")
+```
+
+## Example: Custom Frontmatter in Practice
+
+A note with custom fields:
+
+```markdown
+---
+title: Auth Design
+type: spec
+tags: [security, oauth]
+status: in-progress
+priority: high
+confidence: 0.85
+---
+
+# Auth Design
+
+## Observations
+- [decision] Use OAuth 2.1 with PKCE for all client types #security
+- [requirement] Token refresh must be transparent to the user
+
+## Relations
+- implements [[Security Requirements]]
+```
+
+Queries that find it:
+
+```
+# By status and type
+bm_search(query="", metadata_filters={"status": "in-progress", "type": "spec"})
+
+# By numeric threshold
+bm_search(query="", metadata_filters={"confidence": {"$gt": 0.7}})
+
+# By priority set
+bm_search(query="", metadata_filters={"priority": {"$in": ["high", "critical"]}})
+
+# By tag shorthand
+bm_search(query="tag:security")
+
+# Combined text + metadata
+bm_search(query="OAuth", metadata_filters={"status": "in-progress"})
+```
+
+## Guidelines
+
+- **Use metadata filters for structured queries.** If you're looking for notes by a known field value (status, priority, type), metadata filters are more precise than text search.
+- **Use text search for content queries.** If you're looking for notes *about* something, text search is better. Combine both when you need precision.
+- **Custom fields are free.** Any YAML key you put in frontmatter becomes queryable — no schema or configuration required.
+- **Multiple filters are AND.** `{"status": "active", "priority": "high"}` requires both conditions.
+- **Use empty query for filter-only searches.** Pass `query=""` with `metadata_filters` when you only need structured filtering.
+- **Dot notation for nesting.** Access nested YAML structures with dots: `{"schema.version": "2"}` queries the `version` key inside a `schema` object.
+- **Tags and status are convenient shortcuts.** Use the dedicated `tags` and `status` parameters for common fields, or `metadata_filters` for anything else.