Skip to content

feat(memory): support qmd query rerank toggle#90304

Merged
osolmaz merged 3 commits into
mainfrom
codex/61834-qmd-no-rerank
Jun 5, 2026
Merged

feat(memory): support qmd query rerank toggle#90304
osolmaz merged 3 commits into
mainfrom
codex/61834-qmd-no-rerank

Conversation

@osolmaz

@osolmaz osolmaz commented Jun 4, 2026

Copy link
Copy Markdown
Member

Opened on behalf of Onur Solmaz (@osolmaz).

AI-assisted contribution prepared from the codex/61834-qmd-no-rerank branch.

Summary

QMD can run query mode without reranking, but OpenClaw had no config path for that option. This adds memory.qmd.rerank: false so users can keep QMD query mode while skipping the slower reranker.

Fixes #61834.

What Changed

  • Added memory.qmd.rerank to config types, schema, labels, help, and generated config baseline.
  • Direct QMD query calls now append --no-rerank when memory.qmd.searchMode is query and memory.qmd.rerank is false.
  • MCP QMD query calls now send rerank: false for default qmd.query and explicit searchTool: "query" configurations.
  • Left search, vsearch, and non-query custom mcporter search tool overrides unchanged.
  • Updated QMD memory docs and config reference.

Real behavior proof

  • Behavior addressed: OpenClaw now exposes QMD's no-rerank query behavior through config-level memory.qmd.rerank: false.
  • Real environment tested: Local macOS checkout with QMD 2.5.3 installed globally; temp QMD index over OpenClaw docs collection openclaw-docs.
  • Exact steps or command run after this patch: qmd query "lex: memory qmd" --no-rerank --format json -n 2 -c openclaw-docs, plus focused OpenClaw Vitest coverage for direct CLI args, MCP args, config schema, and resolved config.
  • Evidence after fix: QMD returned JSON hits for qmd://openclaw-docs/concepts/memory-qmd.md and qmd://openclaw-docs/reference/memory-config.md; OpenClaw unit tests verify direct qmd query includes --no-rerank and MCP qmd.query receives rerank:false.
  • Observed result after fix: The upstream no-rerank query path works locally, and OpenClaw now builds the right CLI/MCP arguments from memory.qmd.rerank:false.
  • What was not tested: I did not run a full live OpenClaw Gateway/agent turn with mcporter and a real QMD MCP server; the MCP path is covered by focused argument-level unit tests and inspected against QMD 2.5.3's MCP tool schema.

Verification

  • pnpm docs:list
  • node scripts/run-vitest.mjs packages/memory-host-sdk/src/host/backend-config.test.ts
  • node scripts/run-vitest.mjs src/config/schema.test.ts src/config/schema.help.quality.test.ts
  • node scripts/run-vitest.mjs extensions/memory-core/src/memory/qmd-manager.test.ts
  • OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree node scripts/run-vitest.mjs extensions/memory-core/src/memory/qmd-manager.test.ts packages/memory-host-sdk/src/host/backend-config.test.ts src/config/schema.test.ts src/config/schema.help.quality.test.ts
  • pnpm config:docs:check
  • pnpm docs:check-mdx
  • pnpm format:docs:check
  • git diff --check
  • codex review --base origin/main
  • qmd query "lex: memory qmd" --no-rerank --format json -n 2 -c openclaw-docs

Note: repo-wide pnpm format:check is not green on this checkout because of 125 pre-existing formatting issues outside this branch. I ran targeted oxfmt on the touched TypeScript files instead.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation extensions: memory-core Extension: memory-core size: M maintainer Maintainer-authored PR labels Jun 4, 2026
@clawsweeper

clawsweeper Bot commented Jun 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 4, 2026, 10:21 PM ET / 02:21 UTC.

Summary
The branch adds optional memory.qmd.rerank config/schema/docs support and maps false to QMD CLI --no-rerank and MCP rerank:false for query-mode calls.

PR surface: Source +20, Tests +213, Docs +7, Generated 0. Total +240 across 14 files.

Reproducibility: not applicable. this is an opt-in feature PR, not a bug reproduction request. Source inspection shows current main has no config path for QMD no-rerank behavior, and the branch adds that path.

Review metrics: 1 noteworthy metric.

  • Public config surface: 1 added field. memory.qmd.rerank becomes a user-facing config key, so maintainers should notice the QMD version-floor and upgrade behavior before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Decide whether the documented QMD 2.1+ floor is acceptable or require a runtime guard before merge.
  • [P2] Add a live Gateway/mcporter QMD MCP run only if maintainers want end-to-end proof for that path.

Risk before merge

  • [P1] memory.qmd.rerank:false is a new public config surface whose runtime behavior depends on QMD 2.1+; opted-in users on older QMD can still pass unsupported CLI or MCP parameters unless maintainers accept the documented version floor.
  • [P1] The proof covers real QMD 2.5.3 CLI behavior and focused OpenClaw argument tests, but not a full live Gateway turn through mcporter and a real QMD MCP server.

Maintainer options:

  1. Accept The Documented QMD Floor
    Maintainers can merge the current docs-backed opt-in contract if failures for older QMD users who set memory.qmd.rerank:false are acceptable.
  2. Guard Older QMD Before Merge
    Add a focused capability or version check so OpenClaw diagnoses or ignores the rerank toggle before passing unsupported inputs to QMD older than 2.1.
  3. Require Full MCP Proof
    Ask for a live Gateway or mcporter-backed QMD MCP run if maintainers want end-to-end proof beyond the current CLI and argument-level coverage.

Next step before merge

  • Human maintainer review is the right next action because the PR is protected and the remaining question is whether to accept the documented QMD 2.1+ opt-in contract.

Security
Cleared: No concrete security or supply-chain regression was found; the diff does not change dependencies, lockfiles, workflows, permissions, secrets handling, or package resolution.

Review details

Best possible solution:

Land the config-level opt-in after maintainers explicitly accept the documented QMD 2.1+ requirement or add a small capability guard for older QMD installs, while keeping default reranking behavior unchanged.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is an opt-in feature PR, not a bug reproduction request. Source inspection shows current main has no config path for QMD no-rerank behavior, and the branch adds that path.

Is this the best way to solve the issue?

Yes, the config-level opt-in is a narrow maintainable solution for the linked request because it preserves QMD defaults and limits the new parameter to query mode. The remaining maintainer choice is whether a docs-only QMD 2.1+ floor is enough or a runtime guard should be added.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against de68623ffed7.

Label changes

Label justifications:

  • P2: This is a normal-priority opt-in QMD memory improvement with limited blast radius but a real config/dependency review point.
  • merge-risk: 🚨 compatibility: The new config key can make opted-in older-QMD setups pass unsupported CLI or MCP parameters during upgrade or mixed-version use.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix local QMD 2.5.3 CLI proof plus focused OpenClaw direct/MCP argument tests, with the missing full Gateway mcporter run called out explicitly.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix local QMD 2.5.3 CLI proof plus focused OpenClaw direct/MCP argument tests, with the missing full Gateway mcporter run called out explicitly.
Evidence reviewed

PR surface:

Source +20, Tests +213, Docs +7, Generated 0. Total +240 across 14 files.

View PR surface stats
Area Files Added Removed Net
Source 7 21 1 +20
Tests 4 213 0 +213
Docs 2 7 0 +7
Config 0 0 0 0
Generated 1 3 3 0
Other 0 0 0 0
Total 14 244 4 +240

What I checked:

Likely related people:

  • steipete: Recent history shows repeated work on the QMD manager, memory config, and memory docs paths, including QMD service startup and memory refactors. (role: recent area contributor; confidence: high; commits: cad83db8b2f7, 645c7b189757, 77e6e4cf87f7; files: extensions/memory-core/src/memory/qmd-manager.ts, packages/memory-host-sdk/src/host/backend-config.ts, docs/reference/memory-config.md)
  • vincentkoc: Recent history includes QMD compatibility defaults, compatibility coverage, mcporter search-tool override, and memory config/docs updates on the same behavior family. (role: QMD compatibility contributor; confidence: high; commits: 098f4eeebbed, 7c9108aaf7d0, da35718cb2bf; files: extensions/memory-core/src/memory/qmd-manager.ts, packages/memory-host-sdk/src/host/backend-config.ts, docs/concepts/memory-qmd.md)
  • shakkernerd: Current blame for the QMD MCP query-tool helper region points to Shakker's recent commit that carried the current unified query implementation shape. (role: recent area contributor of current QMD MCP code shape; confidence: medium; commits: 323c8aa87fe6; files: extensions/memory-core/src/memory/qmd-manager.ts, packages/memory-host-sdk/src/host/backend-config.ts)
  • Takhoffman: Recent commits changed active-memory QMD recall/search-mode behavior that calls into this QMD search path. (role: adjacent active-memory search contributor; confidence: medium; commits: 885209ed0330, 4f00b769251d; files: extensions/memory-core/src/memory/qmd-manager.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jun 4, 2026
@osolmaz osolmaz force-pushed the codex/61834-qmd-no-rerank branch 4 times, most recently from 5038cf4 to 66048d0 Compare June 4, 2026 12:40
@openclaw-barnacle openclaw-barnacle Bot added the plugin: bonjour Plugin integration: bonjour label Jun 4, 2026
@osolmaz osolmaz force-pushed the codex/61834-qmd-no-rerank branch from 66048d0 to 17857ea Compare June 4, 2026 12:48
@osolmaz osolmaz force-pushed the codex/61834-qmd-no-rerank branch from 17857ea to 69053c2 Compare June 5, 2026 02:14
@openclaw-barnacle openclaw-barnacle Bot removed the plugin: bonjour Plugin integration: bonjour label Jun 5, 2026
@osolmaz

osolmaz commented Jun 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Merge note:

Relevant PR checks are passing for the QMD config/memory/docs surface. The only red CI lane is check-additional-boundaries-bcd, which fails on existing origin/main qa-lab web raw fetch usage in extensions/qa-lab/web/src/app.ts and is outside this pull request touched files.

Local verification completed:

  • Focused Vitest via node scripts/run-vitest.mjs for QMD manager, backend config, and config schema/help tests.
  • Config/docs checks: config docs, docs formatter, MDX docs.
  • git diff --check origin/main...HEAD.
  • Autoreview clean.

Live behavior proof completed with isolated OpenClaw state and qmd 2.5.3: openclaw memory status reported backend qmd, memory index completed, memory search returned the fixture hits, and the QMD wrapper log showed OpenClaw spawned query with --no-rerank for memory.qmd.searchMode=query plus memory.qmd.rerank=false.

Squash merging pinned to head SHA 69053c2.

@osolmaz osolmaz merged commit 0dbf174 into main Jun 5, 2026
161 of 164 checks passed
@osolmaz osolmaz deleted the codex/61834-qmd-no-rerank branch June 5, 2026 03:19
@github-actions github-actions Bot mentioned this pull request Jun 5, 2026
Open
@clawsweeper clawsweeper Bot mentioned this pull request Jun 7, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

docs Improvements or additions to documentation extensions: memory-core Extension: memory-core maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: M status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Feature]: expose QMD no-rerank for memory.qmd query mode

1 participant

@osolmaz