dsh-memoir

dsh plugin --profile web add dsh-memoir

dsh-memoir

让新的 Agent 会话继续理解你的项目。 dsh-memoir 是 DeepSeek Harness（DSH）的本地优先项目记忆插件：保存已确认的工作结论、经验教训和后续行动，以有界 Hot Memory 注入新会话，并用 BM25 按需召回完整历史。

无需 embedding、向量数据库或云端记忆服务；npm 包不捆绑运行时依赖，DSH 与 Zod 4 peer 由宿主提供。适合个人和本地开发工作流，不是原始聊天备份或多人云同步服务。




中文 · [English](./README.en.md) · [更新日志](./CHANGELOG.md) · Releases

快速安装

当前版本 0.9.5（2026-11-06），适配 DSH 0.2.2-rc.1 / Node.js >=24.9.0。本版不迁移记忆、设置或快照；升级前请备份 DSH_HOME。旧日志故障须按后文单独恢复。

Web： 安装或更新 CLI，再添加到 web profile：

npm install --global @deepseek-ai/dsh@0.2.2-rc.1
dsh plugin --profile web add dsh-memoir@0.9.5

Desktop： 先核对桌面应用内置的 DSH 宿主版本；更新全局 CLI 不会替代桌面内置宿主。在桌面的原生「插件」管理界面添加 npm 包 dsh-memoir@0.9.5，或用指向同一 DSH_HOME 的 CLI 添加到 desktop profile：

dsh plugin --profile desktop add dsh-memoir@0.9.5

Web 与 Desktop 的插件安装、启用分别管理。使用同一 DSH_HOME 和相同数据路径时共享记忆与设置文件；不同 DSH_HOME、不同机器不会自动同步。安装或升级后重新加载插件，必要时重启对应的 dsh web 或桌面应用；只刷新页面不足以重新加载宿主插件。界面缺失时先核对 profile 和宿主版本。

界面预览

以下是 0.9.0 历史界面预览，不是 0.9.5 的新截图。组件预览使用演示数据；插件信息、文档和记忆设置入口常驻顶部。

<details>

<summary>更多界面与历史截图（均保留原版本）</summary>

原生插件详情页直接复用记忆设置。第一张为 DSH 0.2.0-rc.1 的实际宿主界面；第二张为英文 GUI 中选择德语 Agent 文案的组件预览。

历史截图来源：0.9.0 离线公告（演示数据） · 0.7.1 快照诊断 · 0.7.0 原生设置 · 0.6.2 蒸馏诊断。

更早来源：0.6.1 全局项目分组 · 0.6.1 设置导航 · 0.6.1 滚动布局 · 0.6.0 原生视图 · 0.5.6 记忆治理预览 · 0.5.6 设置卡 · 0.5.6 侧栏预览。链接版本为发布来源，文件名保留原组件版本。

</details>

如何使用、能力与边界

1. 打开项目会话中的「记忆」，或从右侧栏打开记忆面板；也可在原生插件详情页或设置页进入记忆设置。侧栏不会自动打开或替换其它面板；缺少侧栏服务时其它入口仍可用。

2. 完成工作后，让 Agent「记录本次结论、教训和下一步」，或等待符合条件的自动蒸馏提醒。也可在面板手工新增、编辑、置顶、归档、恢复或替代。

3. 在「记忆浏览」中搜索项目或全局历史，在 Hot Memory 中查看新会话的注入候选，在「诊断」中检查索引、查询缓存、快照和写入结果。

工作原理

有效工作回合 -> 自动蒸馏提醒（独立收尾回合）
                         |
                         v
              memoir_record / memoir_update
                         |
                         v
              JSON 记忆库（单一事实源）
                +--> PROJECT_MEMORY.md（可读投影）
                +--> BM25 索引 + 查询 LRU --> memoir_read / GUI 搜索
                `--> Hot Memory Selector --> 会话冻结快照 --> system prompt

提醒须满足 AND 门控，是否落盘以工具实际保存结果为准；手动写入不需要先有提醒。BM25 召回与 Hot Memory 选择分别读取结构化记忆，选择器不依赖 BM25 搜索结果。

工具与记忆治理

工具 · 用途

memoir_record · 写入 work / lessons / actions / note；写前返回相似或冲突候选

memoir_update · 保留 id 和创建时间，修改正文、分类、重要度、标签与生命周期

memoir_read · 在 project（默认）/ global / all 范围召回：有查询时按相关度检索，无查询时按项目取近期记录；支持 compact / full 输出

重要度为 1–5，默认 3 是中性优先级；置顶另有 Hot Memory 权重。默认召回 active，归档和被替代的历史仍可检查、恢复，不会自动删除。相似提示不等于判定真伪，必须显式选择 update、保留旧历史的 supersede 或允许并存的 force-record，不会自动合并或删除。

项目记忆绑定会话原始项目，切换执行目录不改变归属。Agent 写入保留可信 session/turn 来源，来源不足时可降级为仅 session；面板可复制标识并尽力打开原会话，不承诺自动定位到具体回合。GUI 手工记录不能伪造可信来源。

自动蒸馏与语言

自动蒸馏是可观察、可取消的模型收尾提醒，不是静默抓取聊天或无成本后台任务。默认 1 / 0 / 1：每个有效工作回合、无额外冷却、至少一次工具调用；autoDistillEvery、autoDistillCooldownMin、autoDistillMinTools 三个频率条件按 AND 判定、按 Agent 隔离。idle、aborted、subagent 和已成功保存记忆的回合不触发，冷却只在提醒成功后更新。

提醒排入独立收尾回合，来源仍指向原工作回合；不占用原任务答复的回合边界，不计入工作回合频率，也不递归触发蒸馏，可能增加显示的回合数。只有成功保存的 memoir_record / memoir_update 才抑制本回合提醒；失败或待确认相似候选不算保存。关闭 autoDistill 不会关闭手动写入工具。

诊断区分提醒提交、实际保存、失败、取消和回执降级；保存后宿主仍可能取消结果，计数可重叠。提醒与后续保存的关联不证明因果或内容正确，GUI 手工写入不计入 Agent 工具计数。旧版已折叠的答案历史不会被升级改写，须展开过程或使用 normal 模式查看；修复历史见[更新日志](./CHANGELOG.md)。

language 可选 zh / en / de / ru，控制工具描述、参数说明、蒸馏提示、工具结果、校验错误及 Hot Memory / Markdown 标题；工具名、参数名与枚举不变。它与中英 GUI 语言独立，不自动猜测语言或翻译记忆正文。修改即时影响后续提示，无需重启；切换本身不重写 JSON/Markdown，后续写入才使用当前语言的投影标题。

Hot Memory 与会话快照

• 有界注入：完整历史保留在本地，只有预算内的 actions、lessons 与 recent state 自动进入 system prompt，不会整份注入 Markdown。
• 冻结前缀：新写入立即可被工具和 GUI 读取，自动注入从下一新会话更新；预算变更不重写既有快照。语言各有独立快照空间，切回原语言复用旧基线；fork/新 session id 不借用父快照。
• 硬预算处理：超出剩余预算的候选会被跳过，继续寻找较小条目；首条过大时按完整渲染块缩短正文，必要时缩短标题。最小块仍放不下就跳过，长标题不能突破硬上限。
• 字面量与缓存边界：{{...}} 等模板字面量对新记忆、内存旧快照及磁盘恢复快照均按原文输出，无需删除快照或改写原始记忆。冻结前缀有助缓存，但不保证提供商 KV cache、命中率或账单节省。

本地召回与缓存

• 分词：中文 2/3-gram、Unicode 字母/组合标记/数字及代码/路径标识符；NFC 归一化不修改原始正文，保留德语变音字符与俄语西里尔字母。
• BM25 排序：保留真实词频，标题 BM25 分数 2.5× 加权，另有精确短语、分类与时

…(truncated)