前言¶
DeepSeek Harness (DSH) 的核心哲學是「一切皆插件」。在開發基於 DSH 的智能體時，跨會話的持久化記憶是一個常見痛點。傳統的向量檢索方案通常依賴外部數據庫，或者需要額外的模型調用，這增加了系統的複雜度和延遲。
dsh-long-term-memory 插件旨在解決這個問題。它爲 DSH 提供了分層的、確定性的長期記憶能力。它使用 JSONL 文件存儲數據，採用 CJK 感知的 BM25 算法進行確定性召回，並在每次請求組裝前自動注入記憶摘要。該插件不依賴向量庫、不需要額外的模型調用、也不需要自建 SQLite 或外部服務器，完全基於 DSH 已有的接縫進行組合。
核心功能¶
本插件提供以下核心能力：
- 三庫分層存儲：將記憶分爲三個作用域，各佔一個 JSONL 文件。
user：用戶畫像（姓名、角色、偏好）。global：跨項目的事實與決策。workspace：項目專屬的記憶。
- 確定性召回：使用 BM25 算法檢索。中文按漢字 bigram 匹配，日文韓文同理，英文按單詞匹配。結果可解釋、可重放。
- 自動注入與校準：每次組裝請求前，通過
systemPrompt.context()注入記憶摘要。注入塊被<long_term_memory>標籤包裹，明確聲明來源與不確定性，指引模型判斷相關性並忽略無關內容。 - 安全機制：
- 威脅掃描：對寫入內容和注入快照進行輕量模式檢測，命中則拒絕寫入或替換爲佔位符。
- 寫入護欄：採用寫臨時文件 + rename 的原子方式，配合跨進程文件鎖，防止數據損壞。
- 糾正迴路：提供
memory_correct工具，用於更正舊事實，將舊記錄標記爲superseded，並在後續召回與注入中自動排除。
安裝與啓用¶
在插件目錄下執行以下命令：
cd dsh-long-term-memory
dsh plugin --profile web add .
安裝完成後需要重啓 dsh web。
⚠️ 注意：
dsh plugin add命令曾破壞過link:的相對路徑（導致相關插件被移出 bundles）。本插件已使用絕對路徑link:/Users/...固化。請勿再對新插件依賴相對路徑。
使用方式¶
插件提供兩類使用入口：模型工具和斜槓命令。
模型工具¶
模型可以通過註冊的工具讀寫記憶：
memory_write(content, scope?, tags?)：寫入一條記憶。scope可選user/global/workspace，默認workspace。memory_recall(query, scope?, limit?)：BM25 檢索，返回帶分數的命中記錄。memory_list(scope?, limit?)：按更新時間列出近期記憶。memory_get(id)：查看單條記憶。memory_forget(id, scope?)：按 ID 刪除記憶。memory_correct(claim, truth, evidence?)：記錄更正事實。
斜槓命令¶
用戶可以直接在輸入框使用斜槓命令（不經模型）：
/memory list [user|global|workspace|all]：列出近期記憶。/memory search <query>：BM25 檢索。/memory get <id>：查看單條記憶。/memory forget <id>：刪除單條記憶。/memory export [|markdown]：導出記憶 bundle。
配置說明¶
通過覆蓋 cordis.patch.yml 或 settings.yaml 來控制行爲。以下是關鍵配置項：
- 注入策略 (
injectContext)：recent（默認）：每輪注入每庫最近的幾條記憶。full：注入全部記憶（受字符預算限制）。off：關閉自動注入。
- 標籤過濾 (
injectTags)：在recent模式下，只注入帶有指定標籤（如decision,constraint）的記憶，過濾瑣碎條目。 - 寫入審批 (
requireApprovalForWrite)：可選開啓，在寫入前通過 DSH 的審批接縫進行人工確認。 - 威脅掃描 (
scanThreatsOnWrite)：默認開啓，對寫入內容進行輕量威脅模式檢測。 - 字符預算 (
charLimit)：每個作用域的字符上限，超限時先自動壓縮再拒絕。
技術細節與注意事項¶
- 同步注入：DSH 的 prompt 組裝器同步調用相關函數。如果注入渲染走異步路徑（返回 Promise），會導致崩潰。插件已將注入渲染全部改爲同步路徑（首個 assembly 前異步預熱 store）。
- 零外部依賴：插件內部實現了 BM25 分詞器和 JSONL 讀寫邏輯，不依賴外部向量庫。
- 威脅掃描保守：掃描模式刻意收窄（僅檢測指令覆蓋/系統提示泄露/角色劫持/標記注入），避免誤傷正常筆記。注入快照使用佔位符而非直接刪除原文，保留供用戶處理。
- 存儲路徑：
user:$DSH_HOME/dsh-memory/user.jsonlglobal:$DSH_HOME/dsh-memory/global.jsonlworkspace:<workspaceRoot>/.dsh/memory.jsonl
適用場景¶
適合需要在 DSH 智能體中實現跨會話記憶、用戶偏好管理、歷史決策追溯以及需要嚴格數據安全控制的場景。
- 記憶沉澱：模型在對話中通過
memory_write將關鍵信息沉澱下來。 - 確定性召回：當模型需要查詢歷史約束或事實時，使用
memory_recall獲取高相關性結果。 - 知識庫管理：通過
/memory list和標籤過濾，整理項目文檔或用戶畫像。
