跨会话记忆 ddtcorex/dsh-maestro-memory

dsh-maestro-memory

为 DeepSeek Harness（DSH）提供持久记忆和待办 —— 原地保留 ~/.dsh/memories。

给 AI 跨会话的持久记忆和待办 —— 你用得越多，它越懂你。

- 包名： @ddtcorex/dsh-maestro-memory（cordis.patch.yml id 为 maestro-memory）
- 版本： 见 package.json · 更新日志： CHANGELOG.md

环境要求

- Node.js ^22.19.0 || >=24.0.0，pnpm 11+（见 package.json 里的 packageManager）
- DSH 版本需落在 package.json 声明的 @deepseek-ai/dsh-client- peer 范围内

安装

pnpm install
pnpm run build # -> lib/
pnpm test # vitest run

DSH 配置档（运维）：

dsh plugin --profile web add link:<workspace-root>/packages/dsh-maestro-memory
production: dsh plugin --profile web add github:ddtcorex/dsh-maestro-memory#<tag-or-sha>

cordis.patch.yml 随包一起发布，里面有一条 connection 条目，声明了 webServer（DSH 0.2.x 需要它，rpc.handle 才能注册 channel）。不要在配置档里重复写。从 npm 安装时用 @ddtcorex/dsh-maestro-memory@<version> 锁定版本；每次对 link: 检出的代码执行 git pull 后，都要跑一遍 pnpm install && pnpm build。

- insert:
- id: maestro-memory
name: '@ddtcorex/dsh-maestro-memory'
config:
memoryDir: null # -> ~/.dsh/memories
snapshotOrder: 500
autoMemory: { enabled: false, userMessage: true, desensitize: true } # opt-in
writeGuard: { enabled: false, threshold: 2 } # per-turn write watchdog, opt-in

writeGuard 只在 apply() 时读取一次 —— 改它需要编辑配置档并重启宿主。threshold 统计连续多少轮有效人类对话没有写入 daily/project；任何小于 1 的值都按 1 处理。

工具

| 工具 | 用途 |
| memory | 五条轨道 memory/user/project/key/daily + 归档/展开。key 需经 memory_suggest 放行。 |
| maestro_todo | 跨会话持久待办存储（四条轨道 life/work/project/daily，带 id，智能视图最多 8 条）。命名上区别于 harness 自带的会话内任务列表 todo_write。 |
| memory_suggest | 受控提案写入 SUGGESTIONS.jsonl —— 需要人工批准。 |

memory 会清洗敏感片段（[Filtered:API key/password/token/ID/phone]，纯凭据 → content filtered）。

系统提示词快照

memory:snapshot（order 500）注入有界、确定性的上下文：

USER + MEMORY + KEY (branch-filtered) + Project Context (auto-recall top-4, 600 chars each, cap 1024) + Recent Daily (last 2 days, 512) + header + discipline note

上限：memory 2048 / user 4096 / key 6144 / recentDaily 512 / autoRecall 1024，外加各分区的条目预算 memory 8 / user 8 / key 12 / recentDaily 2 / autoRecall 4。

上限在两个维度上都是硬性的。最新条目始终保留 —— 当它带 summary 标签时，压缩为 head + [summary:…]。未打标签的条目若大于超过自身字节上限两倍的内容会被截断，并带上明确的 …[truncated] 标记，而不是整条保留：在这条规则之前，单条 2,293 字节的全局条目就占满了 2,048 字节的区段，把其他条目全都挤出了提示词。

成本上报。 renderSnapshotWithStats（memory:snapshot 背后的渲染器）会报告每个区段的字节数、条目数和被排除的条目数。宿主在内存中保留最近 50 次渲染结果，并通过 /dsh-maestro-memory-health 以 cost 返回：samples、last、medianTotalBytes、maxTotalBytes、medianBySection。条目正文从不保留——只保留字节数。

写入看门狗。 开启 writeGuard.enabled 后，宿主会统计连续多少个人类回合里发生了工作、却没有写入 daily/project 条目（agent/turn-stopping）。一个回合要计入，必须同时满足三件事：

1. 它由直接的人类提示词开启——目标续跑回合（source.kind === 'goal'）和注入的上下文（'plugin'，比如唤醒通知）不承担每回合的义务；
2. 它不是子代理会话；
3. 它至少派发了一次工具调用。只回答问题的回合属于对话，不是工作，因此不累积欠账——否则看门狗会逼着模型写凑数条目，而这正是纪律提示词明令禁止的。

一旦缺口达到 threshold，快照就会在纪律提示词之前紧挨着多出一个 # ⚠️ Memory Write Backlog 区段，并一直保留到某次写入成功为止。
只有真正记录下内容的写入才算数——去重后未新增的写入不算。告警文本是静态的（只含阈值，从不含实时计数），所以一个未闭合的缺口最多产生两次尾部快照：出现，然后消失。

子代理会话（session.header.origin === 'subagent'）改用克制的按成果节奏，而不是每回合义务，并且永远看不到积压告警。共享记忆上下文（MEMORY / USER / KEY / Project Context）仍会为它们注入。

渲染出的快照会把两个及以上的连续花括号折叠成一个：DSH 会插值每个提示词上下文，遇到名字格式错误或未注册的 {{name}} 分组就会让整个回合失败，所以自由形式的记忆文本永远不会以模板语法到达那里。

UI 与 RPC

一个 conversation.view 插槽（maestro-memory，顺序 40），标签页为 Memory / Queue / Todo / Skills / Health。Health 显示 coverage、daily last 7d、longest 以及 5 维评分 S/R/J/C/Safety（综合分 min0.4+mean0.6）。

Memory 标签页以只读方式列出每条轨道，并带一个手动添加编辑器：选一条轨道，输入条目，按 Add。它会以 action: 'add' 发送 memory.mutate，因此不需要模型往返；草稿按轨道分别保存，条目为空或 key/project 没有 cwd 时按钮保持禁用。模型侧的 key 门禁在宿主上按 exec.agent 作用域生效，所以它依然有效——你在这里写 key，等同于批准一条排队中的建议。
RPC：/dsh-maestro-memory + 回环 /dsh-maestro-memory-health + /dsh-maestro-memory-propose。

/dsh-maestro-memory 上的维护端点（两者都是先预览：dryRun 默认为 true，真正写入需要 confirm: true）：

| 端点 | 作用 |
| memory.repair | 拆分缺少 § 分隔符而粘连在一起的条目，删除完全重复的条目，并把结尾的 [summary:…] 移到规范的头部位置，覆盖每个存储文件。报告 files / changed / split / deduped / relocated。 |
| memory.maintenance | 规划（并可选执行）memory/user/key/project 中最旧条目的归档，超出 DEFAULT_ARCHIVE_POLICY（保留字节数 + 最长时限）的部分。超量条目移到对应轨道的 -archive.md；它们永远不会被丢弃。 |

归档与双机同步。 sync/ 把 MEMORY.md、KEY.md 和 KEY-archive.md 按并集合并——它从不丢弃任何版本，而项目/全局条目不带 [id:…]，所以一台机器上的删除和「另一台机器还没看到它」无法区分。归档前值得了解几个后果：

- 只在 ONE 台机器上归档并不稳定：下一次并集合并会把归档的条目拉回活动文件，因为对端仍然把它们放在那里。要在每台机器上归档（同一策略），这样两边一致，并集就是空操作；或者归档时关闭同步。
- MEMORY-archive.md 不在合并集合里（只有 KEY-archive.md 在），所以项目轨道的归档留在本地。这对活动文件是安全的，但也意味着两台机器的归档文件可以合理地不同。
- 归档不改变提示词显示的内容：# Project Key Memory 上限为 6,144 B，# Project Context 上限为最新的 4 条，两者都远低于归档策略的保留预算。已在活动存储上验证：渲染在运行前后逐字节一致。

启动时运行一次修复，由 <root>/.maestro-memory/（maestroMetaDir）下的标志文件控制：delimiter-repaired-v3 覆盖每个存储文件，并把运行报告写入该标志。（v1 是仅针对 KEY 的一遍，一直是静默空操作——它被用错误的 cwd 调用——v2 覆盖了存储，但没有拆分游离的分隔符；带版本的标志让已有机器恰好一次地采用新的修复规则。）

维护

维护通过上文 UI & RPC 中描述的 memory.repair 和 memory.maintenance RPC 端点运行（先预览，confirm: true 才写入）。没有独立的维护脚本；scripts/ 只存放构建辅助工具。