前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，「記住用戶偏好、項目約定、運維規則」往往靠會話內上下文或手寫 system prompt。上下文會隨輪次被擠掉；prompt 越寫越長，又和每次請求一起計費。社區裏也有把記憶文件整段塞進 prompt 的做法，但缺少硬上限時，規則被靜默截斷、沒人察覺的情況並不少見——README 裏引用的 Hermes 部署曾出現 MEMORY 超 cap 約 68%、USER 超 cap 約 100% 仍無告警的例子。
@ruqinhu/dsh-memory 是維護者 ruqinhu 發佈的 DSH 插件（社區目錄分類：記憶），用兩份 § 分隔的 Markdown 文檔、可配置的字符上限，以及搜索、按 id 讀取和帶證據的維護流程，把「記憶即 prompt 上下文」這件事做成可預期、可拒絕超限寫入的機制。下面介紹它是什麼、能做什麼、如何安裝與日常使用。
這是什麼¶
一句話：面向 DeepSeek Harness 的持久化 agent 記憶插件——整文件注入（在預算內）、關鍵詞搜索、以及有界的維護與冷條目採樣。
- 維護者：ruqinhu
- 倉庫：https://github.com/ruqinhu/dsh-memory
- 社區目錄：https://www.skillhub.cn/plugins/ruqinhu/dsh-memory
- 許可證：MIT（見倉庫 LICENSE）
- 當前 package 版本（資料來源 package.json）：0.3.2
- peer 對齊的 DSH 版本：0.2.1-rc.5；運行時 Node 22+，無 native 模塊
默認在 ~/.dsh/memory 下維護 MEMORY.md（ durable 規則，默認 cap 2200 字符）和 USER.md（用戶畫像與長期偏好，默認 cap 1375 字符）。超限寫入會被拒絕，而不是靜默截斷。
核心機制與功能¶
兩份文檔與硬 cap¶
| 文檔 | 默認 cap | 內容 |
|---|---|---|
MEMORY.md |
2200 字符 | durable 規則 |
USER.md |
1375 字符 | 用戶畫像與長期偏好 |
記憶隨每次請求作爲 prompt 上下文注入，因此 cap 是設計約束，不是可選優化。
注入策略¶
兩份文檔合計 ≤ 6000 字符時，整份 inline 注入；超過則改爲 id + 首行索引，需要時再 memory_get(id) 拉全文（多一次工具調用，但避免擠佔工作上下文）。
條目 id 與搜索¶
- 條目 id 由
(target, text)哈希得到，10 位十六進制，前綴m-/u-；改文案會換 id（有意爲之，避免 positional id 在壓縮後 silently 指錯條目）。 memory_search做關鍵詞匹配；中文用 bigram，ASCII 按 ≥2 字符詞切分。memory_recall（需enableRecall）在 1500 字符預算內按分數注入，放不下的條目跳過，不截斷半條規則。
使用證據與維護¶
側車文件 .entry-index.json 記錄 hits、firstSeenAt、lastHitAt。inline 注入的條目不計數，因此統計是下界。memory_maintenance 會備份、輪轉、報告用量，並列出「冷」條目樣本：未使用達 staleAfterDays（默認 45 天）、且條目年齡大於 staleMinAgeDays（默認 14 天），最多 12 條、按體積優先——是樣本，不是全量清單。
若環境中存在 skill registry，插件會註冊 memory-curation skill（enableSkill 默認 true）；無 registry 時跳過註冊，插件仍可加載。
工具一覽¶
| 工具 | 用途 |
|---|---|
memory_read |
讀整份文檔及用量、條目數 |
memory_get |
按 id 讀單條條目全文 |
memory_search |
關鍵詞搜索，返回帶分數的 id |
memory_recall |
搜索並渲染可直接用的塊（需開啓 recall） |
memory_write |
替換整份文檔（超限拒絕） |
memory_append |
追加一條（超限拒絕） |
memory_replace |
精確子串替換，壓縮時的基本操作 |
memory_maintenance |
備份、輪轉、用量報告、冷條目列表 |
README 建議：每週用定時任務調用 memory_maintenance，再用 memory_replace 合併或刪除條目，直到用量回到 cap 以內。
已知邊界（資料原文）¶
- 自動 recall 默認關閉；僅在注入切到索引模式後纔有典型收益。
- 跨設備無共享與鎖；跨文檔重複條目不檢測。
- cap 單位是字符而非 token，換語言環境需重新評估。
安裝與啓用¶
插件以當前 DSH 進程權限讀寫 memoryDir，安裝前請自行審閱源碼與 MIT 許可證。
官方安裝命令（來自 README）：
dsh plugin add @ruqinhu/dsh-memory
常用配置項（默認值見 README）：
| 鍵 | 默認 | 含義 |
|---|---|---|
memoryCap |
2200 |
MEMORY.md cap |
userCap |
1375 |
USER.md cap |
enableInjection |
true |
作爲動態 prompt 上下文注入 |
backupKeep |
12 |
保留的備份目錄數 |
memoryDir |
~/.dsh/memory |
文檔與備份位置 |
enableRecall |
false |
註冊 memory_recall |
enableAutoRecall |
false |
每輪自動 recall |
recallBudgetChars |
1500 |
單次 recall 字符上限 |
staleAfterDays |
45 |
多久未用視爲 cold |
staleMinAgeDays |
14 |
更年輕的條目不列入 unused |
enableSkill |
true |
有 registry 時註冊 memory-curation |
運行時依賴 @deepseek-ai/schemastery；@deepseek-ai/dsh-skill 爲可選 peer，缺失時無 skill，不影響插件本體。
典型用法¶
1、安裝並確認 enableInjection 爲 true 後，智能體每輪會在預算內看到記憶內容或索引。
2、需要查某條規則時，先搜索再按 id 讀取。README 實測示例：memory_search("網關") 得到 id（如 m-efa7252010），再 memory_get 返回完整條目（示例中爲 95 字符），側車 hits 會增加。
3、寫入或追加前留意 cap；若被拒絕，用 memory_maintenance 看用量與 cold 樣本，用 memory_replace 做壓縮，而不是指望截斷。
4、可選：開啓 enableRecall 註冊 memory_recall；索引模式下再考慮 enableAutoRecall（默認關）。
適用場景與注意¶
適合：需要在 DSH 里長期保存少量高價值規則與用戶偏好、且希望超限寫入失敗而非靜默丟內容的開發者或運維型 agent 部署。
注意：
- 插件與 DSH 同進程權限，記憶目錄含備份，部署環境需自行隔離與備份策略。
- recall 失敗會被吞掉，不會拖垮整輪對話；側車損壞會在下次 sync 時當空重建。
- 社區目錄 skillhub.cn 爲獨立生態站點，與 DeepSeek / 幻方無官方從屬關係；星標等頁面元數據以目錄爲準（資料抓取時爲 0）。
結尾¶
@ruqinhu/dsh-memory 把長期記憶收成兩份有 cap 的文檔、可導航的 content-derived id，以及拒絕超限寫入和帶採樣的維護路徑，適合在 DSH「一切皆插件」的架構裏替代無上限的整文件堆 prompt。
