[Question] B-2 Neighbor Enrichment: Confirm direction before implementation

[jlin53882]

B-2 Option: Full Retrieval Neighbor Enrichment — Seeking Confirmation

References: Issue #445 (B-2 Proposal), PR #529 (CLOSED), Issue #513

---

Context

Following the closure of PR #529 (BM25 neighbor expansion for reflection slices), we submitted a B-2 proposal on Issue #445 outlining a different architecture for neighbor enrichment.

This issue is to confirm the B-2 direction before any implementation work begins.

---

B-2 Proposal Summary

Instead of enriching reflection slices at load time, B-2 proposes enriching recall results at retrieval time:

hybridRetrieval()
  → vectorSearch + bm25Search
  → RRF fusion → noise filter → rerank
  → applyRecencyBoost → applyImportanceBoost
  → applyMMRDiversity
  → [INSERT: enrich recalled results with their BM25 neighbors]
  → return top-K results

Key advantages over B-1:

• Works for ALL queries, including fresh sessions (query text is always available)
• Architecture is simpler and more intuitive
• Doesn't depend on derived reflection slices existing

---

Open Questions for B-2

1. BM25 vs Vector search: Should B-2 use bm25Search or vectorSearch to find neighbors? Each has different tradeoffs.

2. Insertion point: MMR diversity (after applyMMRDiversity) vs. before MMR. Does the order matter for diversity vs. relevance?

3. Gating mechanism: Should B-2 be gated behind a config flag, or always enabled?

4. Sharing code with B-1: B-1 and B-2 are different mechanisms. Should we share any code, or keep them fully separate?

---

Relationship to B-1

B-1 (PR #529) enriches derived reflection slices at load time. B-2 enriches recall results at retrieval time. They are complementary but not dependent.

Questions:

• Should we merge B-1 first, then build B-2 on top?
• Or should we focus only on B-2 and close B-1 as superseded?

---

Proposed Next Steps

1. Maintainer confirms B-2 direction
2. Maintainer answers the 4 open questions above
3. Contributor submits implementation PR for B-2

We will not implement until we have confirmed direction from the maintainer team.

[AliceLJY]

感谢 @jlin53882 在开始实现前确认方向，这是很好的工作习惯。

关于 B-2 方向

B-2（retrieval-time neighbor enrichment）的整体方向是合理的，相比 B-1（load-time reflection slice enrichment）有明确的优势：

1. 适用范围更广：不依赖 derived reflection slices 是否存在，fresh session 也能受益
2. 架构更简单：在 retrieval pipeline 的一个明确位置插入，不需要修改 reflection store 的写入逻辑

对 4 个 Open Questions 的建议

Q1: BM25 vs Vector search for neighbors

建议 BM25。理由：

• 主检索已经包含了 vector search，neighbor enrichment 的目标是补充语义相似但词汇相关的上下文
• BM25 能找到与 recall 结果词汇重叠的相邻记忆，与 vector search 形成互补
• 如果 neighbor 也用 vector search，容易和主检索结果高度重叠，enrichment 价值下降

Q2: Insertion point — before or after MMR

建议 在 MMR 之后插入。理由：

• MMR 负责多样性保障，应该先让 top-K 通过 MMR 去重
• Neighbor enrichment 是对 top-K 结果的补充（附加上下文），而非额外候选
• 如果在 MMR 之前插入，neighbor 可能影响 MMR 的多样性计算

Q3: Gating mechanism

建议 config flag 控制，默认 disabled。理由：

• B-2 是新行为，需要用户 opt-in，避免改变现有检索行为
• 可以在后续版本验证稳定后改为默认 enabled
• 例如：retrieval.neighborEnrichment.enabled: true

Q4: 是否与 B-1 共享代码

建议 保持独立。B-1 和 B-2 的触发时机、数据流、作用对象完全不同：

• B-1 作用于 reflection slices（write path）
• B-2 作用于 recall results（read path）

硬共享代码容易造成耦合。如果有共用的 BM25 查询逻辑，可以抽取为 utility function，但 enrichment 逻辑本身应该独立。

关于 B-1 的处理

PR #529 已关闭。建议：

• 先聚焦 B-2，B-1 暂不重开
• 如果后续有场景需要 write-time enrichment（例如 reflection 质量提升），再单独评估 B-1

Next Steps

1. 基于以上方向，可以开始 B-2 的 implementation PR
2. 建议 PR 中包含一个简单的 benchmark（对比 enrichment 前后的 recall 质量），方便 review 评估效果
3. config flag + 默认 disabled，降低合入风险

期待你的 PR。

[jlin53882]

B-2 方向確認收到，追加 3 個實作缺口 + 2 個流程問題

@rwmjhb @AliceLJY 謝謝 Q1-Q4 的詳細答案，B-2 的實作方向現在非常清晰。基於這些確認，我們整理出 5 個在實作前需要先確定的點：

---

Q5：MMR 去重是否會消滅 neighbors？【🔴 阻塞】

B-2 的插入點在 applyMMRDiversity 之後，但 MMR 的核心功能就是「對相似的 items 去重」。如果某個 neighbor 與 MMR 選中的 result 相似度過高，MMR 已經在去重階段把它刪掉了。

執行流程：

applyMMRDiversity(top-K)
  → 相似 items 被刪除，某些潛在 neighbors 也消失
  → B-2 在 MMR 這時才插入，只對「還活著的」items 找 neighbors
  → 被 MMR 刪掉的 neighbors 永遠找不到

問題：neighbor enrichment 是在 MMR 去重前還是後執行？如果在 MMR 之後，是否有補救機制找回被 MMR 預先刪掉的潛在 neighbors？還是 MMR 的 threshold 設定讓這個問題在實務上不存在？

---

Q6：vectorOnlyRetrieval() 路徑的 B-2 如何實作？【🔴 阻塞】

B-2 流程圖是基於 hybridRetrieval()：

• ✅ hybrid path 有 bm25Search() → 可直接對 recall results 做 neighbor lookup
• ❌ vectorOnlyRetrieval() 沒有 BM25 search 階段 → 如何找 neighbors？

問題：B-2 是否只實作在 hybrid path？vector-only path 是否需要不同的 neighbor 實作方式（例如用 vector search 做 neighbor lookup）？還是 vector-only path 暫時不實作 B-2，只做 hybrid path？

---

Q7：Neighbor search 的 scope boundary 如何決定？

所有流程圖都假設 neighbor 在「同一個 scope 內」找，但沒有定義邊界：

• 以 recall result 的 scope 為準？每個 result 各自在自己的 scope 內找 neighbor
• 以 query 本身的 scope 為準？所有 neighbors 都用 query 的 scope filter
• 跨 scope 的 recall results：neighbor search 的 scope filter 用哪一個？

---

Q8：B-2 的 Phase 4 依賴關係被跳過，觸發條件是否重新定義？【🟡 需確認】

依據 Issue #445 的設計文件，B-2（全域 Retrieval 鄰居擴展）原為 Phase 4：

觸發條件：Phase 1（B-1 reflection neighbor enrichment）運行 1 個月無異常

但目前的方向是「先聚焦 B-2，B-1 暫不重開」。這意味著：

• B-2 的觸發條件從「B-1 穩定 1 個月」變成了「直接實作」
• 缺少了 Phase 1 的實證基礎

問題：B-2 的觸發條件是否需要重新定義（例如改為「上線後觀察 X 週」）？還是這個 Phase 4 依賴關係已被放棄？

---

Q9：BM25 neighbor lookup 的輸入範圍？Neighbors 如何附加？【🟡 需確認】

維護者確認「用 BM25 找 neighbors」，但細節未定義：

• Input scope：對所有 recall results 找 neighbors？還是只對 MMR 過濾後的 top-K？
• Neighbors 的數量：每個 result 找固定 topK=2 嗎？
• 附加方式：
  • A. 作為附屬上下文（enriched.text = original.text + "\n\nNeighbors: ..."）
  • B. 作為額外候選列表（results = [...topK, ...neighbors]）
  • C. 其他？
• Output 結構：最終 return 的 items 是否包含 neighbors？還是 neighbors 只作為 injection context 不出現在 return 中？

---

建議的 Next Steps

1. 確認 Q5-Q9（本次回覆）
2. 開啟 B-2 實作 issue（包含 neighbor scope、input range、附加方式等設計決策）
3. Implementation PR + benchmark（enrichment 前後 recall quality 對比）
4. Review → Merge

確定這 5 個點之後就可以開始實作，謝謝！