feat: add memory_reflection_resolve tool (follow-up to #447)

[jlin53882]

What

Add a memory_reflection_resolve tool that lets agents actively mark reflection items as resolved, completing the resolve → suppress pipeline for #447.

Why

Issue #447 introduced passive suppression (resolved items are excluded from recall). Without an active tool, resolvedAt can only be set programmatically. Agents need a way to explicitly resolve items when a problem is confirmed solved.

Design Questions (需要維護者確認)

1. Resolve Scope：連動 vs 獨立

Context：同一個問題（strictKey 相同）可能產生多筆 derived items（例如：Rerank 問題產生 6 筆 lessons）。

選項：

Option A — 預設連動，可關閉

memory_reflection_resolve({ id: "abc123" })
→ 順便 resolved 所有同 strictKey 的 items
memory_reflection_resolve({ id: "abc123", cascade: false })
→ 只有 abc123 這筆 resolved

Option B — 完全連動

memory_reflection_resolve({ query: "rerank" })
→ resolved 所有符合查詢且 strictKey 相同的多筆 items

Option C — 各自獨立（目前傾向）

memory_reflection_resolve({ id: "abc123" })
→ 只有 abc123 這筆 resolved
// agents 需重複呼叫多次來 resolved 同一個問題的多筆 items

建議 Option C：簡單明確，agents 可以自己迴圈處理多筆。cascade 語意容易造成預期外的大規模 resolved。

2. Query Mode：精準度

memory_reflection_resolve({ query: string }) 是 BM25 語意搜尋。精準度影響：

• 誤 resolved：resolve 了不該 resolved 的 items
• 漏 resolved：符合問題的 items 沒被搜到

建議：先做 dry-run 回報，agents 確認後才 actual resolved。

3. StrictKey 連動 (已 above)

見 Section 1。

Proposed API

memory_reflection_resolve({
  id?: string,          // 直接 resolved 單一 item（精準，無副作用）
  query?: string,       // BM25 搜尋 resolved 多筆
  note?: string,        // 選填的 resolved 理由
  cascade?: boolean,     // 選填，是否連動同 strictKey（default: false = 各自獨立）
  dryRun?: boolean,     // 選填，只回報受影響 items 不 actual resolved
})

Expected Behavior

• id + query 同時提供 → error
• id alone → 精準 resolved 單一 item
• query alone → BM25 搜尋 → resolved 所有符合結果（cascade=false 各自獨立）
• dryRun=true → 回報受影響 items 數量，不 actual resolved

Tasks

• Implement memory_reflection_resolve tool in reflection-item-store
• Add BM25 search capability (reuse existing bm25Search)
• Decision: strictKey cascade design (see Section 1 above)
• Tests for single-id resolve
• Tests for query-mode resolve
• Tests for cascade behavior
• Documentation

Related

• Closes #395 — Reflection Items Lack Resolution Mechanism #447 (PR feat: add resolvedAt + filterByResolved for reflection items (#447) #483)
• Blocks: [Feature Request / Enhancement] Reflection items lack resolution/invalidation mechanism after underlying problem is solved #395

[AliceLJY]

Good proposal, and well-structured design questions. My thoughts:

1. Resolve Scope: Option C (independent) is the right call

Agree with your reasoning. Cascade semantics are tricky — a strictKey match could span items the agent doesn't intend to resolve. Explicit per-item resolve is safer and more predictable. If agents need bulk resolve, they can loop.

2. Query Mode: dry-run first is essential

BM25 query-based resolve has real risk of false positives. The dryRun parameter is a must-have, not optional. I'd suggest making it the default for query mode (i.e., query without explicit dryRun: false always does a dry run).

3. API shape looks good

One suggestion: consider adding a resolvedBy field (auto-populated from the calling agent ID) for audit trail. This helps when debugging why something was resolved.

Overall, this is a clean follow-up to #447. Option C + mandatory dry-run for query mode + audit trail would be my recommended direction.