feat(integrations): expose note metadata fields in OpenClaw

[lastguru-net]

Why

The OpenClaw plugin exposes write_note and edit_note through its own TypeBox tool schemas and forwards calls to the Basic Memory MCP server.

Those wrappers currently omit several frontmatter parameters already supported by the corresponding MCP tools:

• write_note: metadata, tags, and note_type
• edit_note: metadata

As a result, OpenClaw agents cannot use the normal structured-note interface for tasks, schema-backed notes, status fields, priorities, nested metadata, or tags. They must instead embed YAML frontmatter inside content or modify frontmatter as text, which bypasses the cleaner MCP parameter contract and makes agent instructions inconsistent across hosts.

What changed

write_note

Added these optional OpenClaw tool parameters:

• metadata: arbitrary custom frontmatter fields, including nested objects
• tags: either an array of strings or a comma-separated string
• note_type: the note type stored in frontmatter, defaulting to the MCP behavior of note

The values are forwarded unchanged to the MCP write_note call as:

• metadata
• tags
• note_type

The existing project and overwrite behavior remains unchanged. The new fields are grouped in a typed WriteNoteOptions object inside BmClient rather than extending its positional argument list with several unrelated parameters.

edit_note

Added an optional metadata object to the OpenClaw tool schema.

It is forwarded to the MCP edit_note call alongside the selected content operation. This allows callers to update note content and merge custom frontmatter fields in one tool call.

The existing append, prepend, find/replace, and section-replacement behavior remains unchanged.

Tool schemas

Both metadata parameters use open TypeBox object schemas with arbitrary additional properties, matching the MCP tools' support for custom and nested frontmatter values.

Optional parameters are omitted from MCP payloads when they are not supplied, preserving the existing call shape for current users.

Documentation

Updated the OpenClaw documentation and agent instructions to match the expanded tool contract:

• integrations/openclaw/CLAUDE.md
  • documents metadata, tags, and note_type
  • adds structured note examples
  • explains metadata merging during edits
• integrations/openclaw/MEMORY_TASK_FLOW.md
  • replaces embedded YAML examples with dedicated note_type, tags, and metadata parameters
  • demonstrates updating task content and structured state together
• integrations/openclaw/README.md
  • expands the tool reference
  • adds a structured task example

Examples

Create a structured task:

write_note(
  title="auth-middleware-rollout",
  folder="tasks",
  note_type="Task",
  tags=["auth", "rollout"],
  metadata={
    "status": "active",
"current_step": 2,
    "scheduling": {"due": "2026-09-15"}
  },
  content="""## Context
Rolling JWT middleware to all API routes."""
)

Update content and frontmatter in one call:

edit_note(
  identifier="tasks/auth-middleware-rollout",
  operation="replace_section",
  section="## Plan",
  metadata={
    "status": "review",
"current_step": 3
  },
  content="""## Plan
[x] Deploy to staging
[ ] Review error rates
[ ] Roll out to production"""
)

Tests

Added regression coverage at both OpenClaw integration layers:

• tool schema tests verify that the new parameters are exposed
• tool handler tests verify nested metadata, tags, and note type are passed to BmClient
• BmClient tests verify the exact MCP argument names and payloads
• existing tests verify omitted optional fields preserve prior behavior

Verification

• TypeScript typecheck passed
• Biome lint passed
• TypeScript build passed
• OpenClaw test suite: 232 passed
• npm package dry-run passed
• git diff --check passed

[CLAassistant]

All committers have signed the CLA.