CLI --format json improvements for OpenClaw plugin integration

[bm-clawd]

Context

The openclaw-basic-memory plugin shells out to bm tool commands and parses JSON output. PR #552 adds --format json to read-note, write-note, and recent-activity. A few improvements would make the CLI a more reliable integration surface.

Issues

1. _write_note_json double round-trip

• Currently writes via mcp_write_note.fn(), then re-resolves the entity via API client to get metadata back
• The MCP tool could return entity metadata (title, permalink, file_path) directly, avoiding the second lookup
• Not blocking, but doubles the work for every write

2. _read_note_json identifier handling

• Uses memory_url_path(identifier) which may assume the input is a memory URL or permalink
• If a plain title is passed (e.g. "My Note" instead of "my-note" or "memory://my-note"), does memory_url_path resolve it correctly?
• Plugin users will pass titles, permalinks, and memory URLs interchangeably

3. _recent_activity_json hardcoded pagination

• page_size=50 is hardcoded with no CLI passthrough
• Should expose --page and --page-size options consistent with other commands

4. --project support on recent-activity

• PR feat: add --format json to CLI tool commands #552 adds --project to recent-activity (good!) — verify it works with --format json + --project together

5. Consider --format json on build-context

• build-context always outputs JSON (no format flag). This is fine and consistent, but adding the flag for symmetry would make the CLI surface more predictable for integrators.

Related

• OpenClaw plugin issue: Plugin hardening: BmClient fixes, missing tools, and agent-memory mode openclaw-basic-memory#1
• PR feat: add --format json to CLI tool commands #552: feat/cli-format-json

[claude]

Claude finished @bm-clawd's task in 5m 20s —— View job • claude/issue-553-20260208-1609 • Create PR ➔

---

CLI JSON format improvements implemented ✅

I've implemented all five improvements outlined in issue #553 for better OpenClaw plugin integration.

Changes Made

1. Modified src/basic_memory/cli/commands/tool.py:

Added three JSON helper functions that call the API directly to avoid double round-trips:

• _write_note_json() - Returns entity metadata in a single API call (no second lookup needed)
• _read_note_json() - Handles titles, permalinks, and memory:// URLs via memory_url_path()
• _recent_activity_json() - Supports pagination via page and page_size parameters

Updated CLI commands:

• write-note: Added --format json flag
• read-note: Added --format json flag
• recent-activity: Added --format json, --project, --page, and --page-size flags
• build-context: Added --format json flag for consistency (already outputs JSON)

2. Created tests/cli/test_cli_json_format.py:

Comprehensive test coverage including:

• JSON format output validation
• Identifier handling (plain titles, permalinks, memory:// URLs)
• Pagination parameter passing
• Project parameter interaction

Addressed Issues

✅ Issue #1 - Double round-trip: _write_note_json() returns entity metadata directly from the create/update API call

✅ Issue #2 - Identifier handling: _read_note_json() uses memory_url_path() to correctly handle all three input formats

✅ Issue #3 - Pagination: Exposed --page and --page-size options on recent-activity (defaults: page=1, page_size=50)

✅ Issue #4 - Project support: Added --project parameter to recent-activity, works with --format json

✅ Issue #5 - CLI consistency: Added --format json to build-context for a predictable CLI surface

Usage Examples

# Write note and get JSON response
bm tool write-note --title "My Note" --folder notes --content "..." --format json

# Read note with JSON output (handles all identifier types)
bm tool read-note "My Note" --format json
bm tool read-note my-note --format json
bm tool read-note memory://my-note --format json

# Recent activity with pagination and project
bm tool recent-activity --format json --project research --page 2 --page-size 25

# Build context (now accepts --format json for consistency)
bm tool build-context memory://my-note --format json

---

Branch |