DeepSeek Harness（DSH）採用插件化架構。在智能體開發中，長期記憶往往導致上下文膨脹和 token 消耗。dsh-engram 從 symbolic-index 和 pi-esr 概念中汲取靈感，爲 DSH 提供了一個極簡的長期記憶系統，核心目標是節省 token。
核心功能¶
零 LLM 自動捕獲¶
插件通過純模式匹配捕獲有意義的事件，不調用 LLM 進行熱路徑處理。
* 事件類型：支持 git milestones（帶有 -m 提交信息的里程碑）、關鍵文件編輯、重複錯誤。
* 敏感信息脫敏：所有寫入前會經過確定性脫敏處理，API keys、JWT、Bearer tokens、私鑰等被替換爲 <REDACTED:...> 標記。
* 排除項：靜默提交（git push / git stash）被有意排除，不記錄在案。
* 測試失敗：通過純模式（npm test、node --test、vitest/pytest/jest 的失敗行）識別測試失敗，作爲 tags:["error","test"] 的條目捕獲。
符號索引與漸進披露¶
- 索引結構：在提示詞組裝時注入緊湊的
[ENGRAM]塊（默認預算 700 個字符，約 175 tokens，每行一條記憶）。 - 會話凍結：該塊在會話開始時生成並凍結，保持請求前綴字節穩定，以支持 KV-cache 重用。
- 下鑽工具：使用
engram_recall或engram_detail進行下鑽，而非直接將原始命中結果傾倒到上下文中。 - 召回算法：進程內 BM25 召回（TF·IDF + 標籤/短語加權 + 時間衰減因子）。包含實體鄰居表（
esr_link格式）。 - 重複失敗喚醒：當新失敗與舊錯誤高度相似時，基於最近期和命中爬升（
promoteHits）喚醒舊的錯誤條目，避免失敗記錄堆疊。 - Fallback 機制：本地無命中時，回退到 DSH 自身的跨會話全文索引（
ctx.sessionQuery）；若仍爲空且包含 CJK 字符，則掃描最新的會話日誌（zstd 解壓，LRU 緩存）。
會話開始自動召回¶
- 默認開啓：
autoRecallOnStart默認開啓。 - 機制：在會話第一條用戶消息上運行一次確定性 BM25 召回。
- 注入形式：將前 ≤
autoRecallLimit個命中注入爲[RECALL]塊（默認 700 字符預算）。 - 行爲：純讀操作（不增加命中次數），排除已被覆蓋的舊條目。
記憶間語義管理¶
- 關係定義：
engram_store支持可選的supersedes（覆蓋）和contradicts（矛盾）參數。 - 覆蓋處理：被覆蓋的條目（“陳舊真相”）被降級到召回列表尾部，並排除在
[ENGRAM]塊之外，但依然可通過engram_detail檢索。 - 矛盾處理：被矛盾的條目保留排名，但標記爲
· contradicted by <id>。 - 自動覆蓋：
autoSupersede配置（默認關閉）可自動將“改用 / no longer / switched…”類的更新標記爲覆蓋舊條目。
失敗→修復閉環¶
- 命令標籤：錯誤記憶攜帶
cmd:標籤簽名。 - 自動修復：當該命令後續執行成功時，插件自動沉積一條
procedure記憶（fixed: <cmd> — N earlier failing runs now succeed），並將舊錯誤條目標記爲resolved，召回時優先展示修復方案。
ESR 輕量級證據閉環協議¶
- 命令集：
esr_task/esr_close/esr_link。 - 生命週期：任務經歷
draft → active → stable生命週期。stable狀態要求真實證據（artifact/evaluation/memory_ref）。 - 證據驗證：
verifyArtifact（默認開啓）檢查非 URL artifact 是否存在於工作區（session cwd）。若不存在，任務保持 ACTIVE 狀態並附帶原因。force:true可跳過磁盤檢查。 - 依賴管理：
esr_dep將依賴邊寫入任務的deps（阻塞邏輯）和共享鏈接表，使依賴關係成爲圖中的可見邊。
會話結束待辦自動下沉¶
- 默認開啓：
autoSinkTodosOnEnd默認開啓。 - 下沉機制：會話結束時，若計劃仍有待辦事項，它們被自動下沉爲 ESR
draft任務（名稱爲待辦文本，描述標記「源自會話計劃」）。 - 狀態：下沉爲
draft而非active，避免產生證據義務。需通過顯式esr_claim/esr_task才能激活。
技術細節¶
- 依賴環境：Node.js >= 22.19.0；DSH >= 0.1.2-alpha.2 < 0.2.0-0。
- 存儲位置：數據存儲於
ctx.storageDomain。 - 運行模式：以當前 DSH 進程權限運行。
典型用法¶
插件提供以下工具和接口用於操作記憶與任務：
// 記憶操作
engram_store(supersedes: string, contradicts: string)
engram_recall()
engram_detail()
// ESR 任務操作
esr_task(entity: string)
esr_close(taskId: string)
esr_link(taskId: string, targetId: string)
esr_dep(taskId: string, depId: string)
esr_status()
esr_claim(taskId: string)
// HTTP 接口
GET /api/dsh-engram/goals
GET /api/dsh-engram/triggerstats
適用場景與注意¶
- 適用場景：需要爲 DeepSeek Harness 智能體引入長期記憶，但希望嚴格控制上下文 token 消耗，同時需要結構化任務管理和證據閉環能力的開發者。
- 注意：插件以當前 DSH 進程權限運行，請確保安裝前檢查源碼與許可證（MIT）。
