深鲸记忆 · dsh-memory-doctor
跨会话记忆的管家：用量体检、重复合并、备份恢复、记忆包迁移。本地明文、零依赖、不上传任何数据。
它解决什么
现在大多数记忆插件都在解决「记住」。但用久了真正的问题变成：
- 记忆越写越满（运行时记忆有硬上限），到点就被动归档
- 同一条记了两遍、内容差不多但措辞不同
- 「临时/进度」类内容混进长期记忆，占着预算
- 换电脑、团队协作时，记忆带不走
本插件补的就是这三件事，不改你现有的记忆文件格式（~/.mnemon/runtime/ 下的 MEMORY.md / USER.md），
所以它可以和现有记忆插件共存。
它自己就是热记忆（不是配件）
每轮对话都会把 MEMORY.md（项目/环境记忆）和 USER.md（用户画像）注入 system prompt，
并附带「记忆维护协议」——所以 Agent 真的会记住，而且知道什么时候该写、写去哪、别重复写。
- 注入预算默认 6000 字符，超了截断并提示归档（不会把上下文吃光）
- 记忆是明文 Markdown（
~/.mnemon/runtime/），你自己随时能看、能改、能带走 - Agent 用自带的写文件工具维护记忆，不需要额外工具调用
与别的记忆插件共存 / 替换
本插件默认会自动让位：如果检测到 profile 里装着其他记忆插件， 就不做每轮注入（只提供体检 / 瘦身 / 记忆包），避免两份记忆打架。
- 共存（推荐先这样）：保留对方的注入，本插件只当「记忆管家」——体检、归档、导出；
- 替换：在插件面板停用（不必卸载）对方，重启后本插件自动接管注入（判断只看已启用的 bundles）；
- 强制开关：
MEMORY_DOCTOR_INJECT=0关、=1开（优先级最高），或写~/.mnemon/doctor.json：{ "inject": true }/{ "inject": false }。
记忆文件是同一份（
~/.mnemon/runtime/MEMORY.md、USER.md），所以替换时内容不用迁移。
功能
| 功能 | 说明 |
|---|---|
| 写记忆工具 | Agent 可调用 memory 工具：read / append / replace / remove / search / stats / compact；写入经宿主进程、绕开文件沙箱，自动去重、写前备份、到 80% 自动压缩、超上限拒绝 |
| 会话回复存入记忆 | 每条助手回复旁的大脑按钮：预览后一键存入 MEMORY.md / USER.md（自动去重、写前备份、超上限提示） |
| 概览 | 系统状态卡片（记忆引擎 / 运行时记忆 / 归档 / 记忆包）、存储域（根路径+三个子存储）、记忆来源与共存状态、用量（实时曲线 + 历次体检快照，两种口径分开标注）、最近写入 |
| 体检（分级） | 用量百分比、条目数、重复/近重复、低信息量、临时/阶段性条目；只有真需要动作的（超上限、完全重复）才在面板顶部弹黄条，其余只进体检列表，每条可「忽略」（0.5.8） |
| 自动压缩（四层） | 到 80% 自动跑四层管线：L1 无损折叠 → L2 超大条目落盘 → L3 按优先级驱逐 → L4 到摘要线才 LLM 摘要；每层都可恢复、有谱系记录，见下面「压缩」一节 |
| 忽略 | 误报的条目点「忽略」后不再出现在建议里；设置页可一键全部恢复 |
| 瘦身 | 按勾选归档到 archived/（先备份、只移动、不删除，可回滚） |
| 文档（只读） | 浏览 ~/.mnemon/documents/ 里的项目文档（只读，不修改） |
| 对比上次 | 与上一次体检对比：新增 / 移除的记忆条目 |
| 记忆包 | 一键导出 ~/.mnemon/记忆包-日期-xxxx/（含 manifest.json、文档、git 版本），可换机/团队共享/留档 |
压缩（0.5.11 起：四层管线）
MEMORY.md 是整份每轮注入 + 硬上限 10KB，所以它一定会满。旧版是「到 80% 就归档临时条目 + 把长条压成首句」的一刀切；
0.5.11 改成四层依次尝试，每一层都能单独恢复，单层失败只降级、不阻断：
| 层 | 什么时候做 | 做什么 | 怎么恢复 |
|---|---|---|---|
| L1 无损折叠 | 有连续重复行（同一行 ≥3 次）且真能省字节 | 折叠成一行标记 ⟦dsh-fold-N-<行指纹>⟧（带指纹，多条记录不串），不丢信息 |
逆变换.json 的 L1 记录 + 还原折叠() 逐字节还原；层快照 1-折叠.md |
| L2 落盘 | 单条内容 > 4000 字节 | 全文存 落盘/条目-N.md，上下文里留头 480B + 尾 160B + 路径 + SHA256 |
直接读落盘文件；校验压缩() 用 SHA256 校验完整性 |
| L3 软压力 | 70% 只提醒（不改内容）；80% 起驱逐 | 按优先级：临时/进度类 → 可重放指针（已落盘/已归档）→ 超长条目首句化（至少留 3 条） | 被驱逐的进 归档条目.md；整份原文在存档根目录 |
| L4 LLM 摘要 | 前三层压完仍 ≥90%，且调用方注入了摘要器 | 摘要正文上限 = 上限的 15%（预算预留同样 15%），永远保留最新 1 条原文 | 摘要前全量写 摘要前-MEMORY.md；不注入摘要器就跳过（默认不调 LLM） |
每次触发的存档目录 ~/.mnemon/runtime/archived/自动压缩-<时间>/：
MEMORY.md 压缩前全量（整体回滚用）
memories.json 压缩前记忆库
归档条目.md L3 驱逐出去的条目
落盘/条目-N.md L2 落盘全文（带 SHA256）
层快照/0-原始.md … 4-摘要.md 每层跑完的样子
逆变换.json L1 折叠记录 / L2 SHA256 / L3 归档 / L4 摘要
谱系.json 四层各自的状态（ok / noop / 跳过 / 降级）、原因、省下字节
- 入口：
自动压缩({ 文件, 摘要器?, 摘要阈值? })，写记忆/改记忆前自动触发；也可memory action=compact手动跑 - 整体回滚：
恢复压缩({ 存档文件名, 确认: true })（会先把当前内容另存.恢复压缩前.bak） - 存档完整性：
校验压缩({ 存档文件名 })→ 逐项检查全量存档 / 逆变换 / 落盘 SHA256 / 层快照 - 谱系列表：
压缩谱系()；同时追加一行到archived/压缩谱系.jsonl（最多保留 200 行） - L4 默认不跑：插件自己不发 LLM 请求；只有宿主/调用方传入
摘要器才执行，否则该层记「跳过（未注入摘要器）」并降级 - 任何时候都不删除内容：只做「折叠 / 落盘 / 归档 / 摘要」，原文都能从
archived/取回
安装
dsh plugin --profile web add dsh-memory-doctor
- 面板安装需要本机有
pnpm（DSH 的安装器依赖它） - 没有 pnpm 也行：下载仓库 → 把整个文件夹放进
dsh-home/plugins/→ 重启 DeepWhale Desktop - 装好后侧栏出现「记忆体检」图标；命令
/memory可用
测试
bash tests/run.sh # 106 项：拆条目/体检/瘦身/记忆包/注入/四层压缩/实时曲线（离线，不调 LLM）
使用
- 面板：侧栏「深鲸记忆」图标（大脑图标）→ 概览 / 运行时记忆 / 记忆包 / 归档 / 设置 五个页签
- 命令：
/memory→ 一句话看健康度
白屏防护（2026-10-27 起硬性要求）
宿主 web 启动时，任何一个客户端插件激活失败都会让整页显示 "Failed to load plugins"（白屏）。 本插件三层保证自己永远不会触发这件事：
- 客户层加载整体 try/catch：加载期异常 → 降级为空插件（不注册任何槽位），界面照常；
- 错误边界：面板与「存入记忆」按钮都用 React ErrorBoundary 包住，渲染期异常只在那一块显示一句提示；
- apply() 绝不抛错：槽位服务缺失、某个槽位注册失败都只记日志跳过。
发布前自动闸门：npm run preflight（scripts/preflight-client.mjs）模拟宿主加载/激活/渲染，
不通过就发不出去（prepublishOnly 自动执行）；同类闸门也用于其它深鲸插件。
安全
- 只读写
~/.mnemon/；不做删除（归档 + 备份） - 不联网、不上传；无遥测
未知边界
- 目前瘦身只处理
MEMORY.md（USER.md是人格画像，建议人工编辑） - 记忆包导入为追加合并，不与现有条目冲突时才加
更新记录
- 0.5.18：面板文案与呈现收口 —— 删掉「两种口径不能对比」这类自解释的免责声明，改由区块标题与分隔线表达；迷你折线换成「占用条 + 较上次变化 + 区间」（没有写入时才不会像条死线）；头部状态不再永远写「运行正常」（有问题时显示待处理条数）；「去体检」按钮与实际跳转对齐为「去处理」；版本兜底不再硬编 0.3.0。测试 106 项。
- 0.5.17：合并两条线并修一个口径问题 —— 面板「用量」卡把两种口径拆开标注：「实时（每 2 秒 stat 文件字节，滚动最近 3 分钟）」与「历次体检（每次体检记一个点，最近 N 次）」，并注明二者不能逐点对比；同时带上 0.5.13~0.5.15 的实时曲线、趋势图取值修正，以及 0.5.11 的四层压缩管线。测试 106 项。
- 0.5.11
：自动压缩升级为四层管线（L1 无损折叠 / L2 落盘 / L3 软压力 / L4 摘要），每层可逆、有谱系与层快照，单层失败降级不阻断；新增
压缩谱系/校验压缩/恢复压缩；70% 起软压力提醒；测试 75 → 101 项。 - 0.5.4：写入改为以宿主运行时记忆的
memories.json为源（md 只是投影）——之前直接改 md，宿主重启会用 memories.json 把改动覆盖回去（USER.md 99% 反复出现就是这个原因）；现在追加/替换/归档/瘦身/恢复都会同步库并重新投影。 - 0.5.0：补上「会话回复存入记忆」——每条助手回复旁的大脑按钮（和宿主记忆系统的位置/交互对齐），预览后存入工作记忆或用户画像；新增
/api/message、/api/save-message；55 项测试。 - 0.4.0：新增
memory工具（Agent 写记忆不再依赖文件沙箱）；文档页只读浏览；概览新增「与上次体检对比」；注入判断只看已启用的 bundles（停用但不卸载也会自动接管）；51 项测试。 - 0.3.0：面板升级为「仪表盘」结构：系统状态 + 存储域 + 记忆来源 + 用量趋势（历史快照）；运行时记忆改双栏（列表 + 条目详情侧栏）；新增「设置」页（注入开关、路径复制、导出诊断报告、版本与仓库入口）；服务端新增
/api/config、/api/report、诊断与历史快照。 - 0.2.0：面板重做（对齐宿主「记忆系统」的信息架构：状态卡片 + 页签 + 分组 + 搜索筛选 + 批量归档）；新增归档列表与一键恢复；侧栏改名「深鲸记忆」、图标改大脑；服务端补
/api/archive、/api/restore。 - 0.1.3：注入开关改为「自动让位 + doctor.json + 环境变量」三级，和别的记忆插件共存不再重复注入；补 28 项回归测试；清理仓库。
- 0.1.2：
MEMORY_DOCTOR_INJECT开关 + 热记忆注入。 - 0.1.0：热记忆注入 + 体检 / 瘦身 / 记忆包。