前言¶
用 DSH 這類 harness 做智能體開發，常見困擾是會話之間什麼都沒留下：上一輪你告訴模型「本項目統一用 Vue3 <script setup>」，新開會話它就忘了。常見的補救是把記憶塞進向量庫、靠相似度檢索——代價是記憶本體變成一串不可讀的數字，過期信息藏在庫裏，觀測不到也修不了。
@max-null/dsh-memory 走的是另一條路：記憶全部是明文，檢索用確定性的 BM25，寫入要過人工確認閘門。下面介紹它的設計與用法。
這是什麼¶
@max-null/dsh-memory 是一個面向 DeepSeek Harness 的跨會話明文記憶插件，由 Max-Null 維護，MIT 許可證，當前版本 0.6.0。它屬於 @max-null/* 插件系列，與 SSID（思靈 · Seek Soul in Darkness）桌面體驗整合。
它遵循 DSH「一切皆插件」的理念：不修改 DSH 源碼，聲明 name / inject / apply，由 Loader 從 cordis.yml 加載。
核心設計：人是所有者¶
插件的設計原則可以概括爲三條：
- 人是所有者：模型只能寫入
suggested狀態的記憶，永遠不能自我提升；只有人工確認（setStatus）才能讓記憶生效。 - 可觀測先於精準：每條記憶是明文，
memory_list隨時可見，memory_forget隨時刪除，不存在「靜默暗礁」。 - 確定性且緩存安全：BM25 關鍵詞檢索是存儲的純函數，無 LLM 調用。
注意 approved 與 injected 是兩個獨立狀態：確認生效是一回事，是否每輪常駐注入是另一回事，由獨立開關決定。
提供的服務、工具與注入¶
- 服務
ctx.memory：remember/list/search/forget/setStatus - 工具：
memory_save、memory_list、memory_search、memory_confirm、memory_forget、memory_update - 注入：
tool:memory指引 section +memory:recall召回 context - 檢索：BM25 關鍵詞檢索，CJK 單字 + 2-gram 切分，
content與keywords字段分離加權
memory:recall 注入的是 global 與當前會話工作區裏 approved + injected 的記憶，逐條帶 [memory:<id>:<namespace>] 來源標記，以單行摘要進入 system prompt，並按注入預算截斷；超預算時按最近使用優先截斷，省略數在面板可見。memory_search 命中會更新 lastUsedAt 做冷熱追蹤。
兩層存儲¶
記憶按 namespace 分兩層物理存儲，各自落在獨立的明文 JSON：
| namespace | 默認位置 | 用途 |
|---|---|---|
global |
$DSH_HOME/storages/memory.json |
跨項目的個人偏好 |
project |
<cwd>/.dsh/storages/memory_project_<hash>.json |
跟隨倉庫的項目共識，隨 git 分享 |
幾個細節：
- 兩個根都可用 config 覆蓋（
globalRoot/projectRoot）。 memory_list/memory_search不帶namespace過濾時同時查兩層。- 舊版雙重前綴文件名在打開時自動遷移爲規範名。
明文 + 落在項目文件夾內，意味着 project 層記憶能隨 git 提交分享給所有協作者，團隊共識可以沉澱進倉庫。
安裝與啓用¶
1、安裝：
npm install @max-null/dsh-memory
2、在 cordis.yml 加一條。記憶的存儲後端由插件自己註冊，storage / system-prompt / tools 等由宿主以 peerDependencies 提供：
- id: memory
name: '@max-null/dsh-memory'
可選配置¶
在 cordis.yml 的 config 裏傳給插件，以下均可省略：
- id: memory
name: '@max-null/dsh-memory'
config:
injectionBudget: 1500 # 常駐注入預算（字符；null = 不限制）
summaryChars: 80 # 單條注入摘要截斷上限（字符）
semanticTopK: 5 # 語義側參與融合的 topK（僅配置 embeddings 時生效）
# embeddings: { embed(texts): Promise<number[][]>, similarity? }
缺省即純 BM25。語義融合是 0.5.2 引入的可插拔選項：配置 embeddings 後，memory_search 以 BM25 + 語義 RRF 融合，向量增量生成並持久化，嵌入調用失敗自動降級爲純 BM25。記憶本體仍是明文，向量只作爲檢索輔助字段（vector，明文可讀）。
典型使用流程¶
模型 memory_save → status: suggested（只是建議，未生效）
人 memory_confirm → status: approved（已審覈；是否常駐注入由獨立開關 injected 決定）
人（面板/開關） → injected: true（每輪注入，摘要化 + 預算截斷）
memory_search → 關鍵詞/語義召回任意狀態記憶（命中標記 lastUsedAt）
memory_forget → 隨時刪除
兩點說明：memory_search 不限狀態，任何狀態的記憶都能被召回，但只有 approved + injected 的記憶才進常駐注入；模型側從頭到尾只有「提議權」，生效與否始終由人決定。
提示詞模板庫（0.6.0）¶
0.6.0 新增提示詞模板庫，由四個工具管理：prompt_search / prompt_get / prompt_list / prompt_add。
md 文件是唯一事實源：
- global：
~/.dsh/prompt-library/*.md - 隨工作區分享：
<workspace>/.dsh/prompt-library/
模板存在即生效，source: agent 角標標識模型新增的模板；前端（記憶面板「模板」tab）與模型工具檢索的是同一份索引。提示詞模板永不注入 system prompt。
開發與驗證¶
如果你要參與開發或自行構建：
npm install
npm run typecheck # tsc 嚴格類型檢查
npm test # vitest 單測
npm run build # 產出 dist/
node scripts/verify-loader.mjs # 用 Loader 端到端驗證插件可加載
適用場景與注意¶
適合：
- 希望智能體跨會話記住個人偏好與項目共識的 DSH 用戶
- 團隊想把項目層共識隨 git 倉庫分享
- 在意記憶可審計、召回可解釋，不放心向量黑盒的場景
注意：
- 插件以當前 dsh 進程權限運行，可讀寫其存儲目錄。安裝任何第三方插件前，建議先檢查源碼與許可證（本插件爲 MIT）。
- 語義檢索需要在 config 中提供
embeddings實現，缺省爲純 BM25。 - 社區插件目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-memory 把「記憶」從黑盒拉回明文：模型提議、人確認、BM25 確定性召回、每條可查可刪。如果你在用 DSH 且苦於會話間失憶，可以按上面的步驟接入試試。
- 目錄頁：https://www.skillhub.cn/plugins/Max-Null/dsh-memory
- GitHub：https://github.com/Max-Null/dsh-memory
