PR #58736: fix(memory): prefer --mask over --glob for qmd collection pattern flag

• Repository: openclaw/openclaw
• Author: GitZhangChi
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/58736

Description (problem / solution / changelog)

Fixes #58618 Related #58643

Summary

• Problem: QMD 2.0.1 accepts the --glob flag during collection add, but silently ignores it and falls back to the default **/*.md pattern. This causes strictly scoped collections (e.g., MEMORY.md) to be created as full-workspace collections instead.
• Why it matters: It breaks multi-agent memory initialization. When OpenClaw tries to add a second collection under the same directory with a different pattern, QMD throws a path+pattern conflict, resulting in memory-alt-* registration failures on every gateway restart. It also silently pulls unintended files into the LLM memory context.
• What changed: Defaulted collectionPatternFlag to --mask so OpenClaw uses the working flag first.
• What did NOT change: The fallback mechanism is preserved for older environments where --mask might not be supported.

Change Type

• Bug fix
• Feature
• Security hardening

Root Cause

collectionPatternFlag initializes as null, causing OpenClaw's negotiation logic to try --glob first. Because the qmd CLI does not exit with an error code when it ignores --glob, OpenClaw falsely assumes the flag succeeded and never falls back to --mask. Consequently, every collection is effectively created with the catch-all **/*.md pattern.

Evidence & Repro

Observed on gateway startup with QMD enabled. The narrower memory.md collection collides with an already-created memory-root-* collection:

12:05:19+08:00 [memory] qmd collection add skipped for memory-alt-tg: 
qmd collection add ~/.openclaw/workspace --name memory-alt-tg --glob memory.md failed (code 1): 
A collection already exists for this path and pattern:
Name: memory-root-tg (qmd://memory-root-tg/)
Pattern: **/*.md

Use 'qmd update' to re-index it, or remove it first with 'qmd collection remove memory-root-tg'

Expected: memory-root-* and memory-alt-* coexist in the same workspace targeting different patterns (**/.md vs MEMORY.md). Actual: The first collection is forced to **/.md, blocking the second.

Testing & Verification

• Updated Tests: extensions/memory-core/src/memory/qmd-manager.test.ts
• Added regression coverage to verify addCollection() correctly prefers --mask over --glob while preserving the fallback behavior.

Verification Steps:

• Clear existing QMD collections (qmd collection remove ...).
• Restart the gateway with multiple agents targeting the same workspace.
• Verify that collections are successfully created without conflict warnings and strictly adhere to their intended patterns.

Compatibility / Risks

• Backward compatible? Yes. If --mask fails, it falls back to --glob.
• Migration needed? Users encountering the bug may need to clear their existing conflicting collections (qmd collection remove memory-root-<agent>) so they can be rebuilt correctly.

Changed files

• CHANGELOG.md (modified, +1/-0)
• extensions/memory-core/src/memory/qmd-manager.test.ts (modified, +13/-7)
• extensions/memory-core/src/memory/qmd-manager.ts (modified, +1/-1)