前言¶

DeepSeek Harness (DSH) 生態強調插件化。在開發智能體時，對話上下文通常僅限於當前會話，新會話開啓後 Agent 需要重新“學習”背景信息。dsh-hindsight-memory 插件將 Hindsight 集成到 DSH 的管線中，提供管線級長期記憶。它通過 DSH 的鉤子機制，在模型調用前後自動完成記憶的注入與留存，且不暴露任何 agent 工具。

核心功能¶

• 管線級長期記憶：將記憶能力嵌入 DSH 的 agent pre-step 和 post-step 流程。
• 自動注入與留存：模型調用前自動召回，對話結束後自動留存。
• 故障隔離：recall 失敗不影響本步注入；retain 失敗僅記錄日誌，不中斷聊天。
• 配置分層：支持設置界面編輯與配置分層（默認值、組合層、用戶層）。

安裝¶

使用官方命令安裝插件，或指定本地路徑。

dsh plugin --profile web add dsh-hindsight-memory

安裝完成後，重啓 DSH Web。在宿主日誌中應能看到插件激活信息：

hindsight-memory: active (api=… bank=… enabled=true)

配置¶

重啓後，DSH 設置側邊欄會出現獨立的 設置 → Hindsight 記憶插件 分節。主要控件包括：

• 啓用開關：控制注入與留存功能的開啓/關閉。
• API URL：Hindsight API 地址。
• API KEY：Bearer Token，留空則不認證。
• BANK ID：記憶庫名，多端指向同一 bank 可共享記憶。
• Recall Budget：召回策略，可選 low / mid / high 三檔。

配置分層遵循 DSH 語義：schema 默認值 ← 組合層配置 ← 用戶層覆蓋。所有字段保存後下一輪即可生效，無需重啓。

配置示例（可省略）：

- insert:
    - id: hindsight-memory
      name: dsh-hindsight-memory
      config:
        apiUrl: http://127.0.0.1:28888
        apiKey: ""
        bankId: dsh
        autoRecall: true
        autoRetain: true
        recallBudget: low
        recallTypes: [observation]
        maxQueryChars: 800
        recallTimeoutMs: 8000
        maxMemories: 8
        maxBlockChars: 4000
        retainContext: conversation between the DSH agent and the user
        retainTags: [source:dsh]
        includeSubagents: true
        retainEveryNTurns: 1
        verbose: false

工作原理¶

插件通過兩個核心鉤子實現功能：

1. Auto-Recall (agent/pre-step)：
   在每輪對話的第一個 LLM 調用（step 1）前觸發。系統取最新用戶消息（≤800 字符）作爲 query 調用 Hindsight 的 recall 接口，並將相關記憶追加到步驟批次中。後續 step 不再重複召回。對齊 Hermes 的語義，寒暄確認（如“好的/嗯/ok/謝謝/繼續”）和斜槓命令會被跳過。

2. Auto-Retain (session/event)：
   每次 append 都會投遞一次事件。系統按 turn/start → user/message / assistant/message → turn/end 的順序累積 User 和 Assistant 的文本。在 turn/end 時異步將內容存入 Hindsight。被播種的歷史事件不會重新發布，因此不會重複留存舊輪次。

使用驗證¶

1. 新開一個會話，告訴 agent 一個事實（例如：“我的服務器叫 atlas”），然後正常聊完一輪。
2. 打開 Hindsight UI（部署機的 29999 端口），進入 bank dsh。此時應能看到剛剛留存的 User: … / Assistant: … 記憶。
3. 再開一個全新的會話，直接問“我的服務器叫什麼”。Agent 的回答應直接帶上答案，且全程沒有調用任何工具。

注意事項¶

• 運行時要求：DeepSeek Harness 版本需爲 0.2.0-rc.1。
• 依賴檢查：插件在 package.json 中將相關包聲明爲 peer，profile 兼容性閘門會在不匹配的 DSH 上直接拒載，而非運行期靜默失靈。
• 消息過濾：只有 source.kind === "user" 的消息被當作“人類輸入”；Harness 注入的上下文（時間上下文、技能目錄等）既不作爲召回 query，也不進入留存正文。
• 子 Agent：子 agent / fork 會話默認參與記憶流轉，可通過 includeSubagents 關閉。
• 卸載：如需移除，使用 dsh plugin --profile web remove dsh-hindsight-memory。