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

dsh-maestro-memory

DeepSeek Harness (DSH) 的持久化记忆与待办事项——就地保留 ~/.dsh/memories。

为 AI 提供跨会话的持久化记忆与待办事项——你用得越多，它就越懂你。

- 包： @ddtcorex/dsh-maestro-memory（cordis.patch.yml id 为 maestro-memory）
- 版本： 2.0.0 · 变更日志： CHANGELOG.md

环境要求

- Node.js 22+、pnpm 11+
- DSH deepseek-harness master

安装

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

DSH 配置（运维）：

dsh plugin --profile web add link:/packages/dsh-maestro-memory
production: dsh plugin --profile web add github:ddtcorex/dsh-maestro-memory#

cordis.patch.yml 随包一起发布——请勿在配置中重复添加。

- 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。

上限在两个维度上都是硬性的。最新条目始终保留——当它带有摘要标签时，
会被压缩为 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 / Review / Todos / 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:…]，因此一台机器上的
删除*与“另一台机器尚未看到它”无法区分。
在归档之前值得了解的一些后果：

- 仅在一台机器上归档并不稳定：下一次并集合并会把已归档的条目
拉回活动文件，因为对端仍然在那里保留着它们。在每台机器上归档
（使用相同策略），这样双方达成一致，并集合并即为无操作；或者在禁用同步的情况下归档。
- MEMORY-archive.md 不在合并集合中（只有 KEY-archive.md 在），因此项目轨道
的归档保持本地。这对活动文件来说是安全的，但意味着两台机器的归档文件
可以合理地存在差异。
- 归档不会改变提示所显示的内容：# Project Key Memory 上限为 6,144 B，
而 # Project Context 上限为最新的 4 个条目，两者都远低于归档策略的保留
预算。已在活动存储上验证：运行前后的渲染逐字节完全相同。

一次修复过程在启动时运行一次，由
/.maestro-memory/（maestroMetaDir）下的一个标志文件控制：delimiter-repaired-v3 覆盖
每个存储文件，并将其运行报告写入该标志。（v1 是一次仅针对 KEY 的过程，
它一直是一个静默的无操作——它被以一个错误的 cwd 调用——而 v2 覆盖了
存储，但没有进行杂散分隔符拆分；带版本的标志正是让
现有机器恰好一次地采用新修复规则的原因。）

维护

node scripts/maestro-memory-remediate.mjs --apply --threshold-days 14
node scripts/enforce-rules.mjs --check-memory --threshold 90

切换

1. 备份：node scripts/migrate.mjs --root ~/.dsh/memories --apply
2. 验证：node scripts/migrate.mjs --root ~/.dsh/memories --verify（必须为 ok=true）
3. 切换配置文件：移除 dsh-memory-evolve，以 link: 或固定 SHA 添加 dsh-maestro-memory。
4. 在用户批准的时间窗口重启 dsh web，然后实时读取每个轨道。

回滚：rollback(root, runId) 从 backups// 恢复逐字节相同的文件。

迁移 CLI

node scripts/migrate.mjs --root  [--inspect|--dry-run|--verify|--apply]

默认只读；只有 --apply 会写入 manifest.json + backups//files/ + schema.json。

验证
执行 --apply/--verify 后：ok=true、mismatches=[]、manifest.json 字节完全一致。演练套件 tests/m4-rehearsal.spec.ts 覆盖夹具 link: 配置文件 → 备份 → 验证 → 回滚。