前言¶
如果你给 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
