ewoooc/docs/adr/ADR-007-ai-learning-dual-write.md

ADR-007：AI 學習雙寫規範（DB + KM 同步寫入）

• Status: Accepted
• Date: 2026-04-18
• Decision Maker: 統帥
• Author: Claude

Context

在 EwoooC 三 Agent 分工架構中（ADR-001），所有 AI 產出（洞察、競品分析、對話、PPT 內容）最終需要沉澱。 若只寫入一個 sink，會導致：

• 只寫 DB：RAG 無法語意搜尋過去的洞察
• 只寫 KM（vector）：精確 period/sku 查詢無法命中

歷史教訓（2026-04-18）：

• 舊版 openclaw_learning_service.py 有 store_insight() API，但只寫入 DB，未向量化
• 導致 PPT 每次重新呼叫 AI 生成，歷史簡報失真（內容不一致）

Decision

所有 AI 產出必須雙寫 DB + KM（pgvector），且為同一事務（atomic）。

AI 產出（洞察/分析/對話）
     │
     ▼
NemoTron: tool call store_insight()
     │
     ├─→ PostgreSQL ai_insights（結構化欄位 + metadata）
     │          ↓ async
     └─→ Hermes: embed → pgvector embedding 欄位更新同一行

What 必須雙寫：

產出類型	DB 表	embedding 欄位
PPT 洞察	ai_insights	embedding vector(1024)
競品分析	ai_insights	embedding vector(1024)
用戶對話記錄	conversations	embedding vector(1024)
週報 meta-analysis	ai_insights	embedding vector(1024)

What 不需雙寫（不需語意搜尋）：

• Telegram 告警派發記錄（只做審計）
• 原始爬蟲資料（price_records, competitor_prices）
• 用戶操作 log（audit_logs）

Consequences

Positive

• RAG 永遠能找到歷史洞察，PPT 內容跨時一致
• cache-aside 精確命中（同 period+type → 0.3s 回）+ 語意 fallback（近似查詢）

Negative / Trade-offs

• 每次寫入有兩個 I/O（DB + embedding），延遲增加約 100-200ms
• Hermes 主機 OOM 時 embedding 會失敗（需 retry queue）

Implementation Notes

# 雙寫入口點（atomic）
async def store_insight_with_embedding(insight: InsightModel):
    # Step 1: 寫 DB（同步）
    insight_id = db.execute(INSERT INTO ai_insights ...)

    # Step 2: 排隊 embedding（異步，不阻塞主流）
    embedding_queue.put({"id": insight_id, "text": insight.text})

# Hermes worker（獨立進程）
def embedding_worker():
    while True:
        item = embedding_queue.get()
        vec = embed_text(item["text"])  # 呼叫 Ollama bge-m3
        db.execute(UPDATE ai_insights SET embedding = :vec WHERE id = :id)

Related ADRs

• ADR-001：三 Agent 分工（NemoTron 負責寫入觸發，Hermes 負責 embedding）
• ADR-002：pgvector（KM 儲存層）
• ADR-003：本地 embedding（embedding 引擎）
• ADR-005：時間衰減（品質分數策略）