EchoHeim/DSH-Memory

dsh-memory · DSH 项目记忆插件 (v6)

给 DSH（DeepSeek Harness）装上「像 WorkBuddy 一样的记忆」：会话内容自动沉淀成 markdown，
下一次会话自动带回来。常驻安装，dsh plugin add 一条命令搞定，随 DSH 启动自动加载。

默认与 WorkBuddy 共用同一份记忆文件 —— DSH 记的东西 WorkBuddy 打开就能读到，反之亦然；
项目里没有 .workbuddy/ 就把 .workbuddy/memory/ 建出来再共用（不探测磁盘，只按配置）。
想两边各用各的，把 memoryHome 设成 dsh。

功能总览

| 能力 | 说明 |
| --- | --- |
| 两层记忆 | 项目记忆（主，落在项目根磁盘上）+ 全局库（辅，~/.dsh/dsh-memory.json，跨项目、带版本历史与回滚） |
| 与 WorkBuddy 共用 | 默认共用 /.workbuddy/memory/；长期记忆只写 MEMORY.md 里我们那一小块，别人的内容一个字节不动 |
| 自动沉淀 | 监听 session/event，把真人输入与助手回复按 YYYY-MM-DD.md 存下来，内容指纹去重 |
| 自动召回 | 每轮把「长期记忆 + 最近 N 天 + WorkBuddy 写的」渲染进系统提示，带字符上限 |
| 运行时 skill | 注册 project-memory，告诉模型什么场景该调哪个工具 |
| 9 个模型工具 | 全局 5（save / search / recall_core / forget / admin）+ 项目 4（context / note / promote / sync） |
| 对账自愈 | WorkBuddy 整文件重写抹掉我们的小节后，memory_sync export 能补回来，且不覆盖它新写的内容 |
| 用户级记忆 | 可读写 ~/.workbuddy/MEMORY.md 的受控小节（默认只读） |
| 密钥打码 | 落盘前对 sk- / ghp_ / AKIA / JWT / 私钥 / password= 打码 |
| 写入保护 | 拒写盘符根与 skipRoots；单日文件 512KB 封顶；长期记忆 200 条封顶 |
| 零配置 | 装完即用；.gitignore 只对我们自己造出来的目录动手 |

安装

dsh plugin --profile web add git+https://github.com/EchoHeim/DSH-Memory.git

- --profile web 换成你的 profile 名（web / tui / headless… 各自独立安装）。
- 装完重启 DSH：dsh plugin 会把包名写进 profile 的 dsh.profile.bundles，下次启动即加载。
- 更新：重复上面的 add，或 dsh plugin --profile web update dsh-memory，然后重启。
- 卸载：dsh plugin --profile web remove dsh-memory（已生成的项目记忆与全局库不受影响）。
- ⚠️ 本地 file: 安装不会因 update 刷新：pnpm 对 file: 目录依赖做的是硬链接拷贝，
改了源码后要 remove + add 一次；git 安装没这个问题（commit 变了就是新版本）。

装好后在任意会话里调 memory_admin {action:"storage"} 自检：会返回当前项目记忆存在哪、是否与 WorkBuddy 共用。

记忆放在哪：memoryHome

两态，就这两个取值：

| 取值 | 行为 |
| --- | --- |
| auto（默认） | 与 WorkBuddy 共用 /.workbuddy/memory/。项目里没有这个目录就创建出来再用 —— 不探测磁盘，判断只看这一个配置项 |
| dsh | 分开：只写 /.DSH__memory/，两个工具各记各的；要搬运靠 memory_sync |

shared / workbuddy / wb 是历史别名，都等同 auto；local / separate / split / isolated 等同 dsh。

判定是纯配置判断、不碰磁盘 —— 所以一次会话里绝不会中途换地方，也就不会把记忆劈成两半。

共用模式（默认）长什么样

/
├── .workbuddy/memory/                  ← 与 WorkBuddy 共用（同一个物理文件）
│   ├── MEMORY.md                       ← 长期记忆；我们只写「DSH 记忆」小节
│   └── 2026-09-23.md                   ← 记忆条目（note/promote），WorkBuddy 当场可读
└── .DSH__memory/                       ← 本地账本（sharedLedger: true，默认开）
├── MEMORY.md                       ← 长期记忆的正本备份：WorkBuddy 整文件重写时兜底
└── 2026-09-23.md                   ← 会话流水（逐条对话）只写这里，不灌 WorkBuddy 日志

.workbuddy/memory/MEMORY.md 里我们的那一块长这样，边界之外一个字都不动：

项目记忆

- WorkBuddy 自己写的条目，原样保留

DSH 记忆（dsh-memory 维护）

- [project·5] 构建命令用 pnpm build（2026-09-23）

- 幂等：重组后再解析再重组，结果一字不差（有回归用例守着）。
- topic 覆盖：同 topic 的新条目替换旧行，不是追加。
- 自愈：WorkBuddy 若整文件重写把这一块抹掉，本地账本还在，memory_sync {direction:"export"}
会把条目补回去，而且不影响它新写的内容。

分开模式（memoryHome: 'dsh'）

/
├── .DSH__memory/          ← 正本（首次写入时自动把自身加进 .gitignore）
│   ├── 2026-09-23.md
│   └── MEMORY.md
└── .workbuddy/memory/     ← 只读 + 可选镜像（mirrorWorkbuddy: true 时；始终不动它的 MEMORY.md）

当日文件的块格式（HTML 注释是去重指纹，Markdown 预览里不可见）：

DSH 记忆 · 2026-09-23

19:15:59 · 用户
帮我把构建命令记下来

19:20:03 · 记忆 [project·5]
HMI 从 DGUS 迁到 Qt；通道扩展到 20 路（4 块 ARM 板 × 5 通道）

长期记忆行格式：- [类别·重要度] 内容（日期）

两种模式下「谁写哪里」

| 内容 | 共用模式（auto，默认） | 分开模式（dsh） |
| --- | --- | --- |
| 长期记忆 | .workbuddy/memory/MEMORY.md 的受控小节 (+ 本地账本备份) | .DSH__memory/MEMORY.md |
| 记忆条目 note/promote | .workbuddy/memory/.md | .DSH__memory/.md（+ mirrorWorkbuddy 时镜像一份） |
| 会话流水 capture | .DSH__memory/.md（账本） | .DSH__memory/.md |
| mirrorScope: 'all' | 流水也进共享日文件（全共享） | 流水额外镜像一份到 .workbuddy |
| 读取 | 共享面 + 本地账本合并，按指纹去重 | 自己的目录 + 读 .workbuddy/memory |
| memory_sync export | 把本地账本里缺的条目补回 WorkBuddy 的文件（自愈） | 往 .workbuddy/memory 搬运 |

为什么把流水留在本地：WorkBuddy 的当日文件定位是「工作日志」，逐条对话灌进去会把语义稀释掉。
想全共享就把 mirrorScope 改成 all。

用户级记忆（~/.workbuddy/MEMORY.md）

WorkBuddy 的跨项目用户记忆也是同一个物理文件，本插件分三档：

| userMemory | 行为 |
| --- | --- |
| read（默认） | 只读，内容附带在 memory_search / memory_recall_core 的结果里 |
| write | 额外把全局库的条目投影进它的「DSH 记忆」小节 |
| off | 完全不碰 |

默认只读 —— 那是跨所有项目的文件，写它比写项目内的要谨慎。

9 个模型工具

全局库（跨项目，~/.dsh/dsh-memory.json）：

| 工具 | 用途 |
| --- | --- |
| memory_save | 写/合并/按 id 更新全局记忆（同 topic 覆盖，原内容进 history） |
| memory_search | 同时检索全局库、项目记忆、用户级 WorkBuddy 记忆 |
| memory_recall_core | 取核心记忆（identity/project 或重要度 ≥ N）+ 用户级 WorkBuddy 记忆 |
| memory_forget | 删除（批量需 confirm:true） |
| memory_admin | action: list / stats / history / rollback / store_path / storage / export / import |

项目记忆：

| 工具 | 用途 |
| --- | --- |
| memory_context | 读项目记忆全景（长期 + 最近 N 天 + WorkBuddy 自己写的），正文会标出当前正本路径 |
| memory_note | 写一条项目记忆；重要度 ≥4 或 promote:true 自动进长期记忆；同 topic 覆盖 |
| memory_promote | 把内容（或 fromRecent:N）提升为项目长期记忆 |
| memory_sync | 与 WorkBuddy 对账：direction: import / export / both，支持 dryRun |

自动化（不需要模型操心）

| 行为 | 触发方式 | 说明 |
| --- | --- | --- |
| 会话沉淀 | 监听 session/event | 只记真人输入（source.kind === 'user'）与助手文本；跳过插件注入、工具结果、被中断的回复；轮次结束落盘 |
| 上下文注入 | 注册 systemPrompt section | 每轮装配时按该 agent 的 session.header.cwd 动态渲染记忆摘要，带字符上限 |
| 记忆 skill | ctx.skills.register | 注册 project-memory skill，说明「什么场景调哪个工具」 |
| 项目根定位 | findProjectRoot | 从会话 cwd 向上找带 .DSH__memory/.workbuddy/.git 的目录，最长 8 层；主目录是上界 |

采集与注入都走缓存 + 指纹去重，重复内容不会重复落盘；写入后立即失效缓存，下一轮就能看到。

和 WorkBuddy 自带记忆会冲突吗

共用模式下是同一份文件，所以不存在「冲突」，只存在「边界」：

| | WorkBuddy 自带记忆 | dsh-memory |
| --- | --- | --- |
| 项目级数据 | /.workbuddy/memory/ | 同一个目录（共用）或 .DSH__memory/（分开） |
| 写入方式 | 它自己按 markdown 自由写 | 只走工具：长期记忆写受控小节，日文件追加带指纹的块 |
| 跨项目/用户画像 | 服务端云 profile（自动注入，本插件碰不到） | ~/.dsh/dsh-memory.json（本地文件，带版本历史） |
| 冲突面 | —— | ① 同一处的 topic 覆盖（只在我们自己的行上）② 对方整文件重写会把我们的块抹掉 → memory_sync export 自愈 |

- 绝不删改别人的内容：受控小节的边界之外一个字节都不动，追加 + 指纹去重。
- 绝不写云画像缓存：~/.workbuddy/memory/_memory.md 是服务端画像的本地缓存，写它会被覆盖 —— 只读。
- 唯一的「覆盖」：发生在我们自己 MEMORY.md 里同 topic 的条目上。
- 想彻底不沾：memoryHome: 'dsh' + 保持 mirrorWorkbuddy: false（默认），
只用「读 + 按需 memory_sync import」——这时 .workbuddy/ 一个字节都不会被改。

配置

改 profile 里的补丁文件即可（安装后也可直接改包内 cordis.patch.yml 后重启），键与默认值：

| 键 | 默认 | 说明 |
| --- | --- | --- |
| memoryHome | auto | auto（共用，没有就创建）/ dsh（分开），见上文；shared / wb 等是历史别名 |
| sharedLedger | true | 共用模式下在 .DSH__memory 留本地正本（长期记忆兜底 + 会话流水账本） |
| userMemory | read | 用户级 ~/.workbuddy/MEMORY.md：off / read / write |
| userFilePath | 无 | 覆盖 ~/.workbuddy/MEMORY.md 的位置（测试/多用户） |
| capture | auto | off = 关闭自动沉淀（工具仍可用） |
| captureAssistant | true | 是否连助手回复一起沉淀 |
| injectPolicy | true | 注入时是否附「记忆使用说明」 |
| injectDays | 2 | 注入上下文回看天数 |
| injectMaxChars | 4000 | 注入上下文字符上限 |
| sectionOrder | 650 | systemPrompt section 排序值 |
| mirrorWorkbuddy | false | 只对 dsh 模式有意义：是否额外把记忆条目镜像进 .workbuddy/memory；auto 模式下忽略 |
| mirrorScope | notes | notes 只写记忆条目；all 连会话流水一起写（共用模式下 = 流水也共享） |
| readWorkbuddy | true | 读取 .workbuddy/memory |
| autoGitignore | true | 把我们自己创建出来的目录写进 .gitignore；原本就在的不碰 |
| redact | true | 落盘前打码密钥 |
| globalFile | ~/.dsh/dsh-memory.json | 全局库路径（可指向云同步目录实现跨设备共用） |
| projectRoot | 无 | 拿不到会话 cwd 时的兜底项目根 |
| homeDir | os.homedir() | 向上查找项目根的边界 + 用户级 WorkBuddy 记忆的位置 |
| markers | [.DSH__memory, .workbuddy, .git] | 判定项目根的标记目录名 |
| skipRoots | [] | 这些根目录下拒绝写入 |

配置校验：拼错会在启动时报错，不再静默兜底

配置由插件导出的 Config schema（@deepseek-ai/schemastery）在加载期校验 —— 官方《插件配置》页的硬性要求。

$ dsh --profile web        # 假设把 memoryHome 写成了 'shard'
error: dsh-memory: $.memoryHome expected "auto" | "dsh" but got "shard"

取值拼错、类型写错（例如 injectDays: '两天'）都会让插件直接加载失败并报出字段路径，
不会再悄悄退回默认值 —— 以前那样排查「我明明设了 dsh，怎么还在写 WorkBuddy 的文件」极难定位。

两个配套事实：

- auto / dsh 之外的合法取值只剩历史别名（shared / workbuddy / wb / local / separate / split / isolated），
它们照常识别；真正拼错的字符串才会被拒。
- patch 行是整值替换而非深合并：在自己 profile 的 cordis.patch.yml 里覆盖这行的 config 时，
要把想保留的键一并重述，只写改动的那一个会丢掉其余键。

安全与边界（请读完再用）

- 共用模式下你写的是 WorkBuddy 的文件：受控小节之外不动，但请知道这一层关系。
项目里 .workbuddy/ 本就被 git 跟踪时，DSH 写的记忆会随它进版本库 —— 不想这样就设 memoryHome: 'dsh'。
- 自动加 .gitignore：只对我们自己造出来的目录负责 —— 我们建的 .DSH__memory/ 一定排除；
共用模式下连 .workbuddy/ 都是我们建的话，也一并排除。原本就在的 .workbuddy/ 一个字都不碰
（那是 WorkBuddy 的地盘，可能本来就被跟踪）。ensure 的返回值里有 createdWorkbuddy，
可以据此判断这个 .workbuddy/ 到底是谁建的。
- 密钥打码：写入前对 sk- / ghp_ / AKIA / JWT / 私钥 / password=xxx 做打码。仍然建议别把口令喂给模型。
- 拒写保护：盘符根、skipRoots 里的目录一律不写；单个日文件超过 512KB 停止追加；长期记忆超 200 条丢弃最旧。
- 写入冲突：受控小节用「读-改-写 + mtime 校验 + 重试」，被插队就整体重来，不做局部拼接。
- 沙箱：插件用 node:fs 直接读写（与全局库一致），不走 ctx.fs 沙箱策略 —— 它会往项目根写文件，请在有意识的前提下使用。
- 不需要审批：工具定义里没有权限位，宿主默认放行（除非部署侧挂了 hook 要求审批）。
- peer 依赖：@deepseek-ai/dsh-tools 写 >=0.1.5-rc.1 =3.0.0 <4.0.0-0。两者都标 optional: true ——
运行期由 profile 的 module fallback 提供，声明只为消 pnpm 的 missing peer 警告。

开发与测试

npm test              # 全局库 12 项 + 项目记忆/宿主集成 26 项
npm run test:store    # 只跑全局库引擎
npm run test:workspace

测试会优先加载本机 DSH 里真实的 @deepseek-ai/dsh-tools 与 @deepseek-ai/schemastery（在 ~/.dsh/profiles/node_modules 找），
所以参数 DSL、defineTool 约束、Config 校验、宿主补丁算法都是真跑；换到没装 DSH 的机器则退落到
test/stub-*.mjs —— stub 的校验语义按真实包实测行为复刻（枚举不匹配就抛错），免得「非法配置要响亮失败」
这条在没装 DSH 的机器上变成假绿。
smoke-workspace.js 里的「模拟 cordis 宿主」会替代触发 session/event、调用工具的 execute，端到端验证采集/注入/对账。

宿主契约（针对 DSH 0.1.5-rc.2 实测确认）：session/event（含 user/message / assistant/message / turn/end）、
agent.session.header.cwd、ctx.systemPrompt.section({name, order, text})、ctx.skills.register({name, description, content, source})、
ctx.tools.register(defineTool(...))、模块导出的 Config（schemastery）由宿主在加载期校验；
systemPrompt / skills 走可选注入，缺失时插件照常工作。

从 v5 升级

- 默认行为变了：v5 恒定用 .DSH__memory/；v6 默认 memoryHome: 'auto' ——
无条件与 WorkBuddy 共用同一份文件，项目里没有 .workbuddy/ 也会创建出来再用。
想保持 v5 行为，把补丁里的 memoryHome 设为 dsh。
- shared 改名为 auto（0.7.0）：两个取值的正名现在是 auto / dsh；shared / workbuddy / wb
继续作为历史别名可用，老配置不用动，只是别再往新配置里写。
- 配置开始被校验（0.7.0）：非法取值在插件加载时报错，不再静默兜底；同时新增
@deepseek-ai/schemastery 的 peer 依赖（见上文「配置校验」）。
- 旧数据不会丢：共用模式下读取会合并 .DSH__memory/（账本）与 .workbuddy/memory/，按指纹去重。
- 全局库数据结构与 v4/v5 完全一致（~/.dsh/dsh-memory.json，version 2），无需迁移。
- memory_admin 新增 action: 'storage'，用来查看当前项目记忆存在哪、是否共用。

文件结构

lib/core.js        全局 JSON 库引擎（版本历史 / TTL / 衰减 / 迁移 / 导入导出）
lib/workspace.js   项目记忆引擎（存储位置解析 + 受控小节读写 + 日文件 + 对账 + 上下文渲染）
lib/index.js       cordis 插件入口：Config schema + 9 个工具 + 会话采集 + systemPrompt 注入 + skill 注册
test/              测试用的模块解析 shim，以及 dsh-tools / schemastery 的兜底 stub
legacy/            v3 动态版（含浏览器面板），与本版数据格式互通

License: MIT