實戰範例 003：中型相關性搜索 (85-95% R@5)

背景

您的 Palace 已成長到中型規模（100-500 個 Drawers），您希望確保記憶檢索的**相關性（Precision）與召回率（Recall）**達到 OpenSpec 的指標：

特別是在中型關鍵詞查詢（例如「API 設計」），希望確保前 5 個結果中至少有 4 個是相關的。

問題

# 當前查詢「API 設計」
$ mempalace search --query "API 設計" --limit 10

Results: 15 (Precision: 0.73, Recall: 0.71)

前 10 個結果：
1. [observation] API 認證機制設計 ✅
2. [reference] RESTful API 最佳實踐 ✅
3. [observation] API 版本管理策略 ✅
4. [reference] API 網關架議設計 ✅
5. [observation] PostgreSQL JSONB 效能優化 ⚠️（與 API 不相關）
6. [reference] 安全設計 - 加密機制 ⚠️（與 API 不相關）
7. [observation] Redis 快取策略 ⚠️（與 API 不相關）
8. [reference] 微服務邊界決策 ⚠️（與 API 不相關）
9. [observation] 資料庫連線池設計 ⚠️（與 API 不相關）
10. [reference] 跨服務事務設計 ⚠️（與 API 不相關）

問題：前 5 個結果中只有 4 個相關（Precision 80%），未達 OpenSpec 目標（≥85%）。

解決方案：圖譜加權調整

MemPalace 的綜合分數是：

Score = (Match Score * 0.5) + (Graph Score * 0.3) + (Freshness Score * 0.2)

當圖譜加權不足（Graph Score 太低）時，不相關的記憶也可能浮現。我們可以透過：

1. 增加相關 Drawers 之間的 Links
2. 降低不相關 Drawers 之間的 Links
3. 設定較高的圖譜加權

第 1 步：檢視知識圖譜指標

$ mempalace graph --stats

Link Type Distribution:
  references_to: 15 (18%)
  relates_to: 60 (71%)
  extends_from: 10 (12%)

Avg Links per Drawer: 0.85 (Target: 3-7) ⚠️偏低
Highly Connected Drawers: 3 (7+ links)
Orphan Drawers: 28 (0 links) ⚠️偏高

問題已識別：

• 平均連結數太低（0.85）：大多數 Drawers 沒有足夠的關聯，導致圖譜加權效果不彰
• 孤立記憶偏高（28 個）：這些 Drawers 與其他記憶無連接，易於誤檢索

第 2 步：連結相關 Drawers

連結API 相關的 Drawers，使其與其他 API 記憶形成強關聯：

# 關聯 API 認證與 API 網關架議
mempalace link \
  --source "d:/Repo/api-gateway/architecture/drawer-001" \
  --target "d:/Repo/api-gateway/architecture/drawer-010" \
  --type "relates_to" \
  --reason "都涉及 API 設計（認證 vs 網關）"

# 關聯 API 版本管理與 RESTful 最佳實踐
mempalace link \
  --source "d:/Repo/api-gateway/architecture/drawer-005" \
  --target "d:/Repo/api-gateway/architecture/drawer-015" \
  --type "extends_from" \
  --reason "在 RESTful 最佳實踐上添加版本管理"

# 關聯微服務邊界與 API 網關（弱相關，降低權重）
mempalace link \
  --source "d:/Repo/api-gateway/architecture/drawer-020" \
  --target "d:/Repo/api-gateway/architecture/drawer-010" \
  --type "relates_to" \
  --reason "都涉及微服務設計（邊界 vs 網關）" \
  --weight 0.5

第 3 步：降低不相關 Drawers 的連結

若某些 Links 導致過度跨域關聯，可以降低其權重：

# 假設「PostgreSQL JSONB 效能優化」被錯誤地連結到多個 API Drawers
# 需要降低或移除這些連結

# 查看該 Drawer 的連結
mempalace list-links --drawer "d:/Repo/api-gateway/database/drawer-030"

Outgoing Links:
  [relates_to] → drawer-001 (API 認證機制設計)
    Reason: 都涉及效能優化（但仍弱相關）
    Weight: 1.0

  [relates_to] → drawer-005 (API 版本管理策略)
    Reason: 都涉及性能考量（但仍弱相關）
    Weight: 1.0

# 降低這些連結的權重
# (目前需要手動編輯 Drawer YAML，未來會有 `mempalace link --update` 指令)

編輯 drawer-030.md：

links:
  - type: "relates_to"
    target: "drawer-001"
    reason: "都涉及效能優化（但仍弱相關）"
    weight: 0.3  # 原本 1.0

  - type: "relates_to"
    target: "drawer-005"
    reason: "都涉及性能考量（但仍弱相關）"
    weight: 0.2  # 原本 1.0

第 4 步：重新查詢並測量指標

$ mempalace search --query "API 設計" --limit 10 --no-graph
# 禁用圖譜加權，測量純語義匹配

Results: 15 (Precision: 0.73, Recall: 0.71)

前 10 個結果：
1. [observation] API 認證機制設計 (Score: 0.894)
2. [reference] RESTful API 最佳實踐 (Score: 0.872)
3. [observation] API 版本管理策略 (Score: 0.861)
4. [reference] API 網關架議設計 (Score: 0.839)
5. [observation] PostgreSQL JSONB 效能優化 (Score: 0.785)  ← 依然出現
6. [reference] 安全設計 - 加密機制 (Score: 0.762)
7. [observation] Redis 快取策略 (Score: 0.751)
8. [reference] 微服務邊界決策 (Score: 0.733)
9. [observation] 資料庫連線池設計 (Score: 0.722)
10. [reference] 跨服務事務設計 (Score: 0.710)

現在啟用圖譜加權：

$ mempalace search --query "API 設計" --limit 10

Results: 15 (Precision: 0.82, Recall: 0.81)

前 10 個結果：
1. [observation] API 認證機制設計 (Score: 0.942)  ← 分數提升
2. [reference] RESTful API 最佳實踐 (Score: 0.925)  ← 分數提升
3. [observation] API 版本管理策略 (Score: 0.911)  ← 分數提升
4. [reference] API 網關架議設計 (Score: 0.895)  ← 分數提升
5. [reference] 微服務邊界決策 (Score: 0.842)  ← 因為有 Links 提升
6. [observation] PostgreSQL JSONB 效能優化 (Score: 0.785)  ← 分數不變
7. [reference] 安全設計 - 加密機制 (Score: 0.762)  ← 分數不變
8. [observation] Redis 快取策略 (Score: 0.751)  ← 分數不變
9. [observation] 資料庫連線池設計 (Score: 0.722)  ← 分數不變
10. [reference] 跨服務事務設計 (Score: 0.710)  ← 分數不變

Precision: 0.82 (+0.09 比 --no-graph)
Recall: 0.81 (+0.10 比 --no-graph)

改進：

• API 相關的 Drawers 分數提升約 0.05-0.06
• 前 5 個結果中，現在有5 個相關（Precision 100%）
• 前 10 個結果中，有8 個相關（Precision 80%）

第 5 步：連結更多 Drawers 以提升圖譜密度

為了進一步提升 Precision，您可以將更多的 API 相關 Drawers 互相連結：

# 連結 API 設計與 API 測試
mempalace link \
  --source "d:/Repo/api-gateway/architecture/drawer-001" \
  --target "d:/Repo/api-gateway/testing/drawer-045" \
  --type "relates_to" \
  --reason "都涉及 API 設計（設計 vs 測試）"

# 連結 API 測試與 API 認證（雙向連結）
mempalace link \
  --source "d:/Repo/api-gateway/testing/drawer-045" \
  --target "d:/Repo/api-gateway/architecture/drawer-001" \
  --type "relates_to" \
  --reason "都涉及 API 設計（測試 vs 認證）" \
  --bidirectional

現在查詢「API 設計」，前 5 個結果將包含更多的 API 相關 Drawers。

結果

透過圖譜加權調整，您的 Palace 檢索指標達到：

特別是在查詢「API 設計」：

• 前 5 個結果的 Precision：100% (5/5) ✅
• 前 10 個結果的 Precision：80% (8/10) ✅

為什麼圖譜加權有效？

MemPalace 的圖譜加權計算是：

def calculate_graph_score(drawer, query_results):
    # 獲取該 Drawer 的所有連結
    links = drawer.get_links()

    graph_score = 0

    for link in links:
        # 找出連結目標的匹配分數
        target_match_score = query_results.get(link.target, 0)

        # 若目標也匹配查詢，則提高本 Drawer 的分數
        if target_match_score > 0.7:
            # 連結類型權重
            link_type_weight = {
                "references_to": 1.0,
                "relates_to": 0.8,
                "extends_from": 0.6
            }[link.type]

            # 連結權重
            link_weight = link.weight

            # 圖譜加權得分
            graph_score += target_match_score * link_type_weight * link_weight

    return graph_score

這意味著：

• 若某個 Drawer 所連結的目標也匹配查詢，該 Drawer 會得到額外分數
• references_to 的權重最高，extends_from 的權重最低（因為擴展關聯較遠）
• 您可以透過降低弱不相關連結的權重，減少誤檢索

最佳實踐

✅ 連結高相關 Drawers：API 相關的 Drawers 形成簇
✅ 降低弱不相關連結：將權重降到 0.2-0.5
✅ 平衡圖譜密度：每個 Drawer 的 Links 數量 3-7 個為佳
✅ 定期測量指標：使用 Search 的 –no-graph 比較差異

❌ 避免過度連結：每個 Drawer 關聯 20+ 個其他 Drawers 會降低信噪比
❌ 避免孤立記憶：每月將孤立記憶與相關 Drawers 關聯
❌ 避免循環連結：A 關聯 B、B 關聯 A、A 復關聯 B 的冗餘結構

下一步

您可以：

1. 測試其他查詢：mempalace search --query "效能" --no-graph 並比較
2. 導出視覺化：mempalace graph --export --format mermaid 檢視連結密度
3. 定期測量指標：每月使用 --no-graph 比較圖譜加權效果

相關指令