前言¶
如果你給 DeepSeek Harness（DSH）裏的 agent 做過跨會話記憶，多半會遇到兩種做法的麻煩：自己寫一個 JSON 文件目錄讓 agent 讀寫，召回靠全文搜索，久了就分不清哪些記憶還值得用、哪些已經過期；或者引入外部向量庫，多了一套要維護的依賴。本文介紹的 @wilshi/dsh-memory-engine（社區目錄收錄名 wilshi/dsh-memory-engine）試圖把這件事收進插件裏：DSH 插件的本地記憶引擎，帶神經網絡可視化，讓 agent 保存、召回和管理跨會話記憶，也能把已有的記憶文件導進來。
先說清楚它是什麼：它是 dsh-memory-engine 0.7.5 的分叉（MIT 許可證，原作者 dsh-memory-engine contributors），包名改爲 @wilshi/dsh-memory-engine，版本 0.8.0，維護者 WilShi，分類爲「記憶」。GitHub 倉庫 WilShi/dsh-memory-engine 當前星標爲 0（數據來自社區目錄頁）。
下面按定位、能力、安裝、用法、注意五個部分介紹，事實以倉庫 README 與 npm registry 爲準。
定位：0.8.0 分叉改了什麼，沒改什麼¶
0.8.0 與上游 0.7.5 的關係很明確：只改圖譜可視層與關聯邊算法，具體是深空星雲背景、語義星座佈局（TF-IDF kNN 關聯邊）、標籤避讓、圖例篩選、可摺疊複習清單、hover/脈衝動效。數據格式、工具、HTTP 路由與上游 0.7.5 完全兼容，因此從上游版本升級不需要遷移命令。
依賴方面保持克制：Node ≥22，dependencies 爲空（零新增依賴）；peerDependencies 是 @deepseek-ai/dsh-tools >=0.1.0-rc.8 <0.3.0 且標記爲 optional。倉庫聲明的實測可用範圍是 @deepseek-ai/dsh-tools 0.1.0-rc.8 ~ 0.2.2-alpha.2（插件只用其中的 defineTool，這幾個版本簽名一致）。
一句話定位：在 DSH 宿主內提供帶可視化的本地記憶庫，agent 通過七個工具寫入和召回，人在圖譜或管理頁裏查看和整理。
核心功能¶
記憶庫與 agent 工具¶
- 提供七個 agent 工具，負責保存、召回、導入、複習、生成圖譜等操作；安裝後 agent 可以直接調用。
- 記憶條目帶有分類（知識、印象、對話、事件、日記）、重要度（heat）、相關人（who）等字段，並按艾賓浩斯式衰減計算留存；這是 package.json 關鍵詞裏
spaced-repetition/ebbinghaus對應的行爲。 - 管理頁支持列表、搜索（正文或標題，250ms 防抖）、編輯、刪除、導出和清空；編輯只允許改
text（1～2000 字符且非全空白）、kind（1～20 字符）、heat（1/2/3 整數）、who（0～40 字符），不會改動 id、時間、強化次數。 - 寫操作有備份：管理寫操作統一先調用
MemoryStore.backup()，再以臨時文件加 rename 原子落盤，memories.json.bak-<毫秒時間戳>保留最新五份；配置寫入前也會生成config.json.bak-<時間戳>，同毫秒加序號，保留最近五份。備份失敗不寫入。
圖譜可視化¶
- 圖譜通過宿主同源路由提供，由 React 直接繪製 Canvas（不再是 iframe），支持拖拽旋轉、滾輪縮放（0.3～4.5）、點擊節點查看詳情；離開頁面或切換 tab 停止動畫。
- 界面入口是會話頭部的「記憶圖譜」按鈕，點擊後全屏顯示，頂部有圖譜 / 記憶 / 設置三個 tab。
- 空庫時默認彈出中央引導卡片（三步說明、提示詞、數據目錄），之後可點右上角的問號隨時回看；Esc 按「引導卡片 → 詳情卡片 → 整個圖譜浮層」的順序逐層關閉。
- 可以配置中心角色卡作爲圖譜裏的虛擬中心（見下節配置），不寫入記憶庫，也不參與評分、關聯、複習、列表或導出。
自動記憶與自動導入（默認關閉）¶
- 自動記憶默認關閉，需在圖譜頭部或設置頁手動打開；開啓後每輪對話會額外調用一次模型，可能產生費用，首次開啓會提示成本；關閉即取消排隊抽取並阻止遲到結果寫庫。
- 自動導入默認只收聊天會話的用戶消息，支持來源白名單、工作指令過濾、流程話過濾、規則分類、錯誤原因、一次性重掃和賬本清理；要凍結所有自動入庫，需同時關閉自動記憶和自動導入。
- 實際回調簽名爲
(session, event)；llm和sessionQuery通過ctx.get()按需獲取，缺少前者只停用自動抽取，缺少後者只跳過會話來源。
離線圖譜¶
/memory-engine/ 整頁 HTML 保留給 CLI 與瀏覽器直接訪問，獨立打開仍可交互。應用內界面與離線 HTML 共用同一份繪製源碼（lib/render/canvas.js 導出 createRenderer(canvas, data, options)）。
安裝與啓用¶
倉庫 README 未給出統一的一行安裝命令，安裝走 npm registry 與 DSH 插件機制：包名爲 @wilshi/dsh-memory-engine，registry 地址爲 https://registry.npmjs.org/@wilshi/dsh-memory-engine，目錄頁 https://www.skillhub.cn/plugins/WilShi/dsh-memory-engine 給出了面向 DSH 的安裝入口。安裝前請先看下節「適用場景與注意」。
啓用後的步驟是：完全退出 DSH 再打開，進入任意會話，頭部第一行會出現記憶圖譜按鈕。插件對宿主版本做了兜底，版本不合適時不會出現「裝上了卻什麼都沒有」：
| 宿主情況 | 插件行爲 |
|---|---|
有 ctx.effect |
正常註冊，隨插件卸載一起清理 |
沒有 ctx.effect |
直接註冊工具，功能不減少，日誌留一條提示 |
解析不到 @deepseek-ai/dsh-tools |
用內置直通 defineTool，工具照常可用 |
| 沒有 header.actions 插槽 | 圖譜按鈕退到 views.actions（在「更多視圖」菜單裏） |
| 完全沒有 slots 服務 | 跳過按鈕，記憶工具不受影響 |
插件版本 0.7.0 起的 GUI 還要求宿主提供 webServer.register({ kind, path, handler })，服務端聲明 inject = ['tools', 'webServer']，生命週期結束時註銷路由。
配置：按鈕開關¶
在 {DSH_HOME}/memory-engine/config.json（默認 ~/.dsh/memory-engine/config.json）的現有對象中合併以下字段，然後完全退出 DSH 再打開：
{
"hideButton": false,
"showGuideOnEmpty": true
}
hideButton: true 隱藏會話頭部的入口按鈕，七個記憶工具照常可用；showGuideOnEmpty: false 讓空庫不自動彈出引導，仍可點問號查看。未配置時分別默認 false、true，只有明確的布爾值才改變默認行爲；現有 bridgeRoot、diaryDir 等字段請保留。配置請求失敗、返回無效內容或超過 5 秒時，客戶端記錄警告並按默認顯示按鈕。
配置：中心角色卡¶
在現有 config.json 對象裏合併以下字段（路徑使用你自己的角色卡）：
{
"personaFile": "C:/path/to/role.md",
"personaTitle": "小夏",
"spinSpeed": 0.35
}
也可用 personaText 直接配置正文，最多 4000 個 Unicode 字符；非空 personaText 優先於文件。標題默認「角色卡」，速度範圍 0.05～1.5，默認 0.35（正常幀率下約 90 秒一圈）。角色卡固定在原點，印象、知識、事件位於內層球殼，日記、對話和其他類別在外層，舊記憶更靠外。
配置項也可以通過 HTTP 接口改，但只開放白名單字段：autoMemory.enabled、autoImport.enabled、autoMemory.maxPerTurn（1～5 整數）、autoMemory.dailyCap（0～500 整數）、spinSpeed（0.05～1.5 數字）、showGuideOnEmpty、hideButton；任何未知字段或類型錯誤會整次返回 400，不改任何字段。
典型用法¶
讓 agent 生成離線圖譜¶
agent 調用 memory_map() 即可生成可雙擊、離線打開的單文件 HTML：
memory_map()
memory_map(title="我的機器人的記憶", open=true)
memory_map(out="D:\\memory-map.html")
默認輸出 {DSH_HOME}/memory-engine/starmap.html；未設置 DSH_HOME 時爲 ~/.dsh/memory-engine/starmap.html。open 默認 false，顯式 true 才啓動系統默認瀏覽器。
命令行生成圖譜¶
也可以直接運行插件自帶的腳本，生成並打開離線圖譜：
node <插件目錄>/scripts/render-map.mjs --open
該腳本同時註冊爲 dsh-memory-map 命令（見 package.json 的 bin 字段）。
同源 HTTP 接口¶
下面是應用內界面和離線 HTML 共用的接口（均在 /memory-engine 路徑下）：
| 方法 | 路徑 | 返回內容 |
|---|---|---|
| GET | /memory-engine/ |
整頁 HTML 圖譜，瀏覽器可直接訪問 |
| GET | /memory-engine/api/map |
{ nodes, links, review, stats, generatedAt, core, spinSpeed } |
| GET | /memory-engine/api/stats |
記憶總數、分類、衰減狀態及存儲位置 |
| GET | /memory-engine/api/onboard |
{ empty, prompt, steps, dataDir } |
| GET | /memory-engine/api/config |
公開配置（含 autoImport、lastError 等，不返回 raw 與模型配置） |
| PUT | /memory-engine/api/config |
合併白名單字段，返回公開配置和 backup 文件名 |
| GET | /memory-engine/api/list?q=&kind=&sort=&limit=&offset= |
{ total, allTotal, limit, offset, items } |
| GET | /memory-engine/api/item/:id |
完整條目、留存和連接數；不存在返回 404 |
| PUT | /memory-engine/api/item/:id |
僅更新傳入的 text/kind/heat/who |
| DELETE | /memory-engine/api/item/:id |
刪除一條，返回 { deleted, backup } |
| GET | /memory-engine/api/export |
{ total, items }，條目原樣導出 |
| POST | /memory-engine/api/clear |
請求 { confirm: "DELETE" }，返回 { removed, backup } |
JSON 成功返回 { "ok": true, "data": ... }，失敗返回 { "ok": false, "error": "說明" }。接口僅接受本機 Host，拒絕路徑穿越，不允許的方法返回 405；PUT 和 POST 只接收 JSON 對象，大小限制在 1MB。
適用場景與注意¶
適合：單機使用 DSH、希望 agent 有跨會話記憶、又不想引入外部向量庫或數據庫的人；想把已有的記憶文件導入統一管理的人；想要一個能在瀏覽器裏直接查看記憶關係的圖譜界面的人。不適合需要跨設備同步、需要同義詞語義檢索、或需要加密存儲的場景。
注意幾點：
- 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。許可證爲 MIT（繼承自上游 dsh-memory-engine，作者 dsh-memory-engine contributors；本分叉貢獻者爲 WilShi）。本倉庫是第三方分叉，社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。
- 檢索是字面匹配，不理解同義詞：查「自行車」不能自動匹配只寫「單車」的記憶。
- 數據保存爲明文 JSON，沒有加密；單機使用，沒有跨設備同步。
- 自動記憶開啓後會產生額外模型調用費用，實際金額取決於模型和計費方案；只支持 DSH 宿主，Node 需 ≥22。
- 官方說明當前版本爲 0.8.0，README 正文裏「當前版本：0.7.5」是上游原文未隨分叉更新的說法，以包名與 package.json 爲準。
結尾¶
這個插件的價值在於把「跨會話記憶 + 可視化 + 管理界面」收斂成一個零新增依賴的本地插件，分叉版本 0.8.0 只動可視層和關聯邊算法，向上兼容上游的數據格式與接口，升級風險可控。如果你已經在用上游 dsh-memory-engine，換到這個分叉只是換一張圖譜；如果你還沒做記憶管理，它比自建目錄多了一個能看見記憶關係的入口。
- 社區目錄頁：https://www.skillhub.cn/plugins/WilShi/dsh-memory-engine
- GitHub：https://github.com/WilShi/dsh-memory-engine
