前言¶

如果你给 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 再打开，进入任意会话，头部第一行会出现记忆图谱按钮。插件对宿主版本做了兜底，版本不合适时不会出现「装上了却什么都没有」：

插件版本 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 路径下）：

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