justhalfbit/dsh-plugin-memory

dsh-plugin-memory

DeepSeek Harness (DSH) 的跨会话记忆插件：
对话模型在工作中边干边记，把值得长期记住的信息（事实 / 决策 / 教训 / 偏好）持久化为
纯 Markdown 文件，并在同一项目的新会话中自动注入。机制对齐 Claude Code 官方 auto memory，
并在索引同步与结构护栏上更进一步。

特性

- 🧠 两层记忆：主记忆文件（自动注入，预算内截断）+ 专题文件（渐进式披露：只注入一行索引，正文按需加载）
- ✍️ 模型边干边记：所有写入都是可见的工具调用，三档积极度可调（保守 / 平衡 / 积极）
- 🤫 可选后台蒸馏（默认关）：每轮对话完成后静默提取记忆，零工具卡片、零对话痕迹，适合无人值守长任务
- 📁 按项目隔离：以会话工作目录为粒度，目录名为可读的全路径编码 + 防碰撞哈希
- 📝 纯 Markdown 存储：人可读、可手编、可 git 管理；无法解析的行在任何改写中原样保留
- ⚙️ 设置面板：浏览器卡片 + settings.yaml 双入口，全部配置热生效
- 🔒 护栏完备：内容哈希去重、每类条目上限、修剪顺序（手动条目最后淘汰）、注入预算、KV cache 友好的 digest 防重

安装

前置：已安装 DSH 且 pnpm 在 PATH 上。

从 GitHub 安装（本插件零构建步骤，无需 allowBuilds 配置）
dsh plugin --profile web add github:justhalfbit/dsh-plugin-memory

重启 dsh web 生效

web 是 dsh web（浏览器界面）对应的 profile 名；用其他 profile（如 tui）时把 web 换成对应名字即可。
dsh plugin add 会自动把包写入 profile 依赖并追加到 dsh.profile.bundles，无需手工编辑。

卸载：dsh plugin --profile web remove dsh-plugin-memory，重启生效；记忆数据保留在 ~/.dsh/memory，可手动删除。

本地开发安装：克隆本仓库后 pnpm install，再 dsh plugin --profile web add link:/绝对路径/dsh-plugin-memory。

兼容性：需要 DSH 0.1.2 及以上（已在 0.1.2-rc.1 与 0.1.5-rc.2 上端到端验证）。宿主端通过 Session.snapshotEvents() 读取会话日志（0.1.2 起取代了 events 访问器），因此不再支持 0.1.1-rc.x；rc 阶段上游 API 可能变动，客户端模块表差异已在插件内做双版本回退。

界面支持

| 运行形态 | 记忆核心（注入 / 蒸馏 / 工具 / 存储） | 设置卡片 |
|---|---|---|
| dsh web（浏览器 GUI） | ✅ | ✅ |
| tui / headless | ✅ 全部可用 | ❌ 改用 settings.yaml（同样热生效） |

host 半与界面无关；client 半（设置卡片）声明 platform: "web"，仅在浏览器界面加载。

工作方式

存储

~/.dsh/memory/projects//
├── memories.md      # 主记忆文件：四个小节（Facts/Decisions/Lessons/Preferences）
└── topics/.md      # 专题文件：自由格式深度笔记（调试手册、API 约定……）

memories.md 长这样——id 由内容哈希派生（天然去重），尾注记录日期与来源
（auto 蒸馏 / manual 手动，修剪时 auto 先淘汰）：

Project Memory

Facts
- [f-32e32a1b] host 进程日志直接输出到启动 dsh web 的终端，无 --log-file 选项

Decisions
- [d-8c4c11ee] 记忆存储选纯 Markdown 而非 SQLite，为了可 git 管理

Lessons
Preferences

专题上限：每项目 24 个文件、单文件 64K 字符。读取与单次写入的上限同为 64K，
所以插件接受过的专题永远能被完整读出、也能被一次 replace 整体重写；触顶时用
memory_delete_topic 腾位置。

记忆写入（主机制，对齐 Claude Code）

注入的提示（默认保守档措辞）指示对话模型在学到持久且非显而易见的东西时主动调用
memory_save：用户纠错、带理由的决策、来之不易的教训、明确的用户偏好、稳定的项目事实。拿不准就不存；
保守档还额外提示"多数轮次什么都不记，同一轮的近重复合并成一条"；
删除条目要求当前对话给出具体反证才能 memory_forget——同项目的多个会话共享同一份文件，
不能凭"看着不顺眼"就删掉别的会话记下的东西；
任务收尾产出成体系知识时用 memory_write_topic 整理成专题。积极度由 proactivity 设置控制，
只改提示措辞，机制与护栏不变。

注入

agent/pre-step waterfall 把记忆以  拼入步骤消息：主文件条目全量
（默认 64000 字符预算，按需分摊、超出才截断保最新），专题文件每个一行索引（名称 + 大小 + 日期 + 首行摘要），
正文由模型在相关时调 memory_read 按需加载。预算管的是整个提示——固定的指令开头先扣除，
剩下的额度由条目与专题索引分摊，不会各自另算。按渲染体 SHA-1 防重——与模型当前仍可见的最近一条
本插件提醒（session.surface.nodes 上的最后一条）比较：文件不变则整个会话只注入一次（KV cache 友好）；
可见面是唯一依据，不维护进程内状态，因此重启、恢复、fork 都天然接续；步骤失败未落盘的提醒不在可见面上，
自动重注入；compaction 把旧提醒压缩掉（摘要不保留原文）后，下一轮也会补注入一份，长会话不会丢记忆。

空库也注入（约 0.9–1K 字符，不含任何条目块）。写记忆的行为指令只存在于这段提示里，
而自动蒸馏默认关闭，所以"空库不注入"是自封闭的：没有指令 → 不调 memory_save → 库仍为空 →
仍不注入。空库版只带当前积极度档位的写入/专题两条规则，并明确要求不要为了填满而乱记；
首条记忆一落地就自动切换回完整提示。

注入只发生在每轮的第一步：记忆由对话模型自己维护，若轮内重渲染，则它每调一次
memory_save 就会再收到一份完整提示（N 次保存 ≈ O(N²) 上下文），而那只是在告诉写入者它刚写了什么。
轮内的改动顺延到下一轮第一步注入。

自动蒸馏（opt-in，默认关）

开启 autoDistill 后，每轮 turn/end 追加一层完全静默的两阶段蒸馏：零成本预检
（跳过子代理会话、无用户消息的轮次、新增文本不足、冷却期内、重复窗口、进行中的蒸馏）
通过后，后台用一次 ctx.llm.stream() 直调提取严格 JSON 条目——不走工具管线、不产生卡片。
模型选择回退链与 compaction 一致：设置指定 → 会话最近请求路由 → agent 配置。

模型工具

| 工具 | 作用 |
|---|---|
| memory_save | 存一条（category + content），内容哈希去重，返回 id |
| memory_search | 关键词检索（大小写不敏感分词匹配 + 短语加权） |
| memory_list | 列出全部条目与专题清单，含文件路径 |
| memory_forget | 按 id 删除错误/过时条目 |
| memory_read | 按需读取专题文件全文 |
| memory_write_topic | 创建/追加/重写专题文件（append / replace） |
| memory_delete_topic | 删除整个专题文件（专题数触顶时腾位置） |

设置项

设置入口：「设置 → 插件 → 插件配置 → 跨会话记忆」卡片，或 ~/.dsh/settings.yaml 的 memory: 节。全部热生效。

| 字段 | 默认 | 说明 |
|---|---|---|
| enabled | true | 总开关（关闭后不注入不蒸馏，工具仍可查询） |
| proactivity | 'conservative' | 记忆积极度：conservative / balanced / eager |
| autoDistill | false | opt-in：额外开启每轮完成后的后台静默蒸馏 |
| memoryDir | '' | 记忆根目录，空 = /memory |
| injectBudgetChars | 64000 | 整个注入提示的字符预算（含 ~1K 固定指令开头）；上限而非下限，小记忆只花实际长度。约占 1M token 窗口的 1.6%，满载 200 条时可显示约 150 条 |
| distillMinChars | 2500 | 触发蒸馏的最小新增字符（不足则累积到下轮） |
| cooldownTurns | 3 | 同会话两次蒸馏的最小间隔轮数（与上一项相乘决定蒸馏频率） |
| distillProvider / distillModel | '' | 蒸馏模型；留空跟随当前对话 |
| maxEntriesPerCategory | 50 | 每类条目上限，超出先淘汰最旧的 auto 条目；淘汰会连同被删条目的正文一起在 memory_save / memory_forget 的结果里报出，不静默（调低本上限会让各类立刻超限，随后第一次写入或删除就会清理超额部分，并全部报出） |
| topicIndexInInject | true | 注入摘要末尾是否附专题索引（正文始终按需加载） |

设计

为什么挂 host 平面而不是 agent preset？DSH 的设置命名空间每进程只能注册一次
（preset 插件每会话实例化一份，第二个会话必然撞车），且记忆天然跨会话、需要进程级单例的
写队列。host 平面的根上下文监听器能收到所有会话的事件，工具全局注册，按 session.header.cwd
归属项目——单例服务多会话，能力无损。

与 Claude Code auto memory 的对照：

| 环节 | Claude Code | 本插件 |
|---|---|---|
| 写入者 | 主对话 agent 自己（可见工具调用） | ✅ 相同（proactivity 三档可调） |
| 加载 | MEMORY.md 前 200 行 | 主文件预算内全量（默认 64000 字符） |
| 专题文件 | 不自动加载，按需 Read | ✅ 相同（memory_read） |
| 索引 | agent 手工维护于 MEMORY.md，会失同步 | 注入时扫目录动态生成，永不失同步 |
| 结构 | 自由格式，无界增长 | 四类条目 + 内容哈希去重 + 上限修剪 |
| 后台蒸馏 | 无 | 额外提供，opt-in |

可靠性设计：每文件写队列串行化 + 跨进程锁目录（陈旧锁 5s 可偷取，偷前二次确认）+
临时文件原子改名（失败自动清理）；目录解析单飞（single-flight）防迁移竞态；
注入去重以可见面（surface）为准；蒸馏水位线在尝试开始时推进（失败窗口不重试，成本可控）。

安全：专题名白名单校验（构造上杜绝路径穿越）；注入内容大小写不敏感转义闭合标签；
蒸馏提示词明令禁止存储密钥/凭据/个人数据；子代理会话不注入不蒸馏。

静默的执行者权限更小：后台蒸馏不产生工具卡片、用户当场看不见，且只读到一个纯文本窗口
（没有工具调用与结果）——所以它可以新增、可以整理自己写的 auto 条目，但不允许删除或改写
经由可见工具调用写下的 manual 条目*（update 是先删后加，破坏性完全相同，因此一并禁止；
被拦的 op 直接丢弃，不会降级成 add 而留下自相矛盾的一对）。这条是在 applyOps 里强制的，
不是提示词请求——提示层只是建议，我们在跨会话删除那件事上已经验证过这一点。

已知限制

- 跨进程并发写同一项目为"最后写胜"的弱保证（进程内严格串行）；
- 记忆按项目共享，不按会话隔离：同一项目的任何会话都能改写、删除其它会话记下的条目。
注入的提示已要求删除必须有当前对话的具体反证，但这是提示层约束，不是强制机制；
- 也没有墓碑——A 删掉的条目，持有旧上下文的 B 可能重新存回来；
- 自动蒸馏只能新增条目、以及改写/删除它自己写的 auto 条目；manual 条目对它只读，
纠正手动条目必须走可见的 memory_forget；
- 蒸馏失败的窗口不重试（有意的成本控制）。插件自身不给蒸馏调用设超时，靠 adapter 的
流空闲超时兜底（pi-ai 默认 5 分钟），所以卡住的蒸馏会自愈，不会永久停摆；
- 蒸馏只看得到 user/assistant 文本，看不到工具调用与结果；
- 记忆文件是插件自有用户数据，host 侧直写，不经 agent 文件沙箱。

开发

pnpm install
pnpm test   # node --test test/

License

MIT