Summary

• Problem: openclaw memory search --query "..." was documented but rejected by CLI parsing.
• Why it matters: users following built-in help examples hit unknown option '--query' and cannot run search.
• What changed: memory search now accepts both positional query and --query <text> flag alias.
• What did NOT change (scope boundary): search ranking/scoring and memory backend behavior are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: "openclaw memory search" fails with "unknown option '--query'" despite help text instructions openclaw/openclaw#25857
• Related #

User-visible / Behavior Changes

• openclaw memory search --query "deployment notes" now works as expected.
• Positional form openclaw memory search "deployment notes" still works.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Bun test runner
• Model/provider: N/A
• Integration/channel (if any): CLI
• Relevant config (redacted): default

Steps

1. Run openclaw memory search --query "deployment notes".
2. Observe parsing + execution.
3. Compare with positional search invocation.

Expected

• Both query styles are accepted and execute search.

Actual

• Previously --query was rejected as unknown option.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: bun test src/cli/memory-cli.test.ts -t "accepts --query flag for memory search" passes.
• Edge cases checked: empty query now reports explicit usage error.
• What you did not verify: full matrix of all memory backends in integration mode.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert this PR commit.
• Files/config to restore: src/cli/memory-cli.ts, src/cli/memory-cli.test.ts.
• Known bad symptoms reviewers should watch for: memory search command parse ambiguity.

Risks and Mitigations

• Risk: optional positional argument could introduce command parse ambiguity.
  • Mitigation: explicit coverage for --query alias and existing search path retained.