dsh-memoir

dsh-memoir

0.9.4：开发与验证 SDK 基线升级到官方 npm DSH 0.2.1-rc.5，保留 0.2.0-rc.1 / rc.2 与 0.2.1-alpha.1 / alpha.2 / rc.2 支持；#14 恢复 CLI 白名单经零差异审计扩展至 rc.3 / rc.4 / rc.5。0.9.3 的存储保护（#16）与模板字面量防护（#17）全部保留；升级并重新加载插件即可，无需删除快照或改写原始记忆；#14 的旧日志故障仍须单独恢复。

中文 · English · 更新日志 · Releases

DeepSeek Harness（DSH）的本地优先、跨会话项目记忆插件。 它把 Agent 已确认的工作结论、经验教训和后续行动持久化，在新会话中注入有界且缓存友好的 Hot Memory，并通过本地 BM25 排序召回长尾历史。

无需 embedding、向量数据库或云端记忆服务；npm 包零捆绑运行时依赖，DSH 与 Zod 4 peer 由宿主环境提供；Zod 用于验证宿主会话投影，不捆绑进插件。

[!WARNING] #14 旧日志恢复边界：0.8.1–0.9.0 写入的旧回执可能导致会话重新打开失败。 0.9.3 保留 0.9.1 起阻止新增异常回执的修复，但升级不自动重写旧日志；npm 包内置 dsh-memoir-repair 命令。旧会话仍打不开时，按恢复说明先只读检查、停机备份后再显式恢复；不要删除日志或降级数据格式。恢复前停止旧插件写入，仅关闭自动蒸馏不能阻止手动工具写入。 #17 的 prompt 输出防护不修复任意旧日志。恢复 CLI 的后端与格式支持须以恢复说明列出的已审计范围为准；仅升级 DSH 也不会修复已有异常日志。

[!IMPORTANT] 0.9.4 要求 DSH >=0.2.0-rc.1 <0.3.0-0 || >=0.2.1-alpha.1 <0.2.1，开发 SDK 基线为 0.2.1-rc.5；保留官方 0.2.0-rc.1 / rc.2 与 0.2.1-alpha.1 / alpha.2 / rc.2 兼容线，rc.3 / rc.4 / rc.5 的后端库与 rc.2 逐字节一致。版本范围不代表其中所有版本均已验证；0.2.2 预发布尚未通过门禁、不在放行范围（见更新摘要）。保留首屏导引、原生设置、四种 Agent 语言、独立蒸馏回合与冻结快照。DSH 0.1.7 兼容线为 0.8.2，但仍受 #14 影响；使用本版修复须先升级宿主，再安装 0.9.4。

dsh-memoir@0.7.1 修复重启和内存淘汰后旧会话快照丢失（#10），支持 DSH 0.1.5-rc.1 / rc.2。要求 >=0.1.5-rc.1 <0.1.6-0；请先核对宿主版本。旧 DSH 0.1.2 用户固定使用 0.6.2，0.1.1-rc.2 用户固定使用 0.5.6；这些旧版未包含本次修复。

npm install --global @deepseek-ai/dsh@0.2.1-rc.5
dsh plugin --profile web add dsh-memoir@0.9.4

升级后重新加载插件，或重启 dsh web。#17 防护会在后续 prompt 组装时生效；无需手工删除旧快照。记忆不会随插件升级或卸载自动删除。

0.9.4 更新摘要

• DSH rc.5 基线：开发与验证 SDK 统一固定到 0.2.1-rc.5。session-persistence-jsonl 的库代码在 rc.2 → rc.3 → rc.4 → rc.5 之间逐字节一致（2026-11-01 审计），全量回归在 rc.5 基线通过；宿主/peer 范围保持不变，0.2.2 稳定版发布时将自动被第一条款覆盖。

• 恢复 CLI 扩展至 rc.3 / rc.4 / rc.5：白名单从五个官方 SDK 版本扩展到八个，安全边界不变：先只读检查，全部宿主退出并独立备份后，再显式 --apply --host-stopped。

• 兼容基线一致性回归：新增测试防住三类脱节——JSONL devDependency 必须在恢复白名单内、engines/peer 范围必须放行编译基线、双语恢复文档必须列全白名单版本；恢复 CLI 帮助文本测试改为从脚本动态解析。

• CI SDK 兼容矩阵：新增 compat job，基线 rc.5 为硬门禁，0.2.2-alpha.2 为 advisory 预警；新增 scripts/compat-swap.mjs 基线切换脚本。

• 0.2.2 预发布预检（未放行）：0.2.2-alpha.2 要求 Node >=24.9.0（移除 Node 22），ProjectionDefinition 需要两个类型参数、PromptAssembly 拆分等属于公开契约变化；未通过门禁前不扩大 engine 范围。

• 存储保护（#16）：遇到未来 store 格式、读取错误或损坏文件备份失败时，报错并拒绝继续加载或覆盖（fail closed）。只有成功保留损坏原文件后才允许建立空库；Windows 临时占用导致的 rename 失败采用有界重试，耗尽后仍报错。

• Hot Memory 预算（#16）：候选超出剩余硬预算时跳过并继续寻找较小条目；首条过大时按渲染后的完整块缩短正文，必要时缩短标题。连最小块也放不下则跳过，长标题不能突破 hotMemoryMaxTokens。

• 模板字面量（#17）：通过官方 PromptSection 的 interpolate: false 关闭记忆 section 的变量插值，使 {{...}} 等字面量按原文进入 system prompt，避免被求值或导致组装失败。新记忆、进程内旧快照与磁盘恢复的旧快照均按原文输出；花括号、原始记忆 JSON、PROJECT_MEMORY.md 与磁盘快照保持原样。感谢 mikemikimike 在 PR #18 中的报告、输出边界分析及旧快照方案对问题定位的帮助。

• 0.9.3 的 rc.2 适配与修复全部保留：#16 存储保护、Hot Memory 预算边界与 #17 模板字面量防护见 CHANGELOG.md；项目记忆仍绑定会话原始项目，切换执行目录不转移归属。恢复 CLI 支持的八个官方 SDK 版本和安全边界见恢复说明；运行时兼容不等于任意历史日志均可恢复。

为什么选择 dsh-memoir

适合需要“新 Agent 接手时继续理解项目”的个人或本地开发工作流。它不是原始聊天记录备份、多人云同步服务或向量语义知识库。

界面预览

0.9.0 组件界面预览，使用演示数据。 顶部常驻插件身份、GitHub、文档与记忆设置入口，无需滚过长列表。

工作原理

有效工作回合
    │  自动蒸馏提醒
    ▼
memoir_record / memoir_update
    │
    ├── ~/.dsh/dsh-memoir.json       完整结构化历史（SSOT）
    ├── <项目>/PROJECT_MEMORY.md      可读、可提交的投影
    └── Retrieval Index              倒排索引 + BM25 + 查询缓存
              │
              ├── Hot Memory Selector ──> 有界 system-prompt 注入
              └── memoir_read / Web ────> 按需召回长尾历史

完整历史与 Hot Memory 是两层数据：

• Full Memory 保留全部记录，用于 GUI、人工审阅、Markdown 投影和排序检索。
• Hot Memory 只选择预算内的 actions、lessons 与 recent state；不会把整个 PROJECT_MEMORY.md 塞进 prompt。
• Session Snapshot 按会话持久化冻结注入基线，重启恢复与内存淘汰后继续复用原文。0.9.3 通过关闭记忆 section 的变量插值保护旧基线，注入文本与已存快照均保持原样。新写入立即可被工具和 GUI 读取，但自动注入从下一个新会话开始更新；恢复失败会显式报告降级。

快照恢复与清理（0.7.1）

0.9.3 升级提示： #17 防护同时覆盖进程内缓存和磁盘恢复的旧快照，升级并重新加载插件即可，无需按下面的磁盘清理步骤删除它们。记忆 section 关闭变量插值后，含模板字面量的旧基线仍按原文输出，花括号与冻结前缀保持不变；这不等于修复 #14 的异常回执或其它旧日志故障。

• 默认目录：$DSH_HOME/dsh-memoir.json.snapshots/；自定义 storePath 时为 <storePath>.snapshots/。记录按数据源/设置文件的哈希、语言和会话哈希分开保存；按需读取，不在启动时加载全部文件。
• sessionSnapshotMax 只限制内存 LRU。磁盘记录无自动 TTL，不随缩容、卸载或清理内存删除；备份记忆时请一起备份该目录。需要回收磁盘时先停止相关 DSH 进程并备份，再人工删除确定不再恢复的记录。删除后再次访问会建立新基线。
• 语言切换使用独立快照空间；切回原语言会复用其旧基线。预算修改仅影响新基线；fork/新 session id 不借用父会话快照。
• 升级前已丢失快照的旧会话，首次使用新版只能按当前记忆建立一次新基线；不从历史 system prompt 猜测截取原文。读取损坏、权限或锁失败时保留原文件，回退到进程内冻结；诊断页和日志会提示重启稳定性降级。
• 单条文本上限 256 KiB，记录上限 2 MiB；超限走同样的可诊断降级。POSIX 新目录/记录使用 0700/0600，Windows 权限仍由目录 ACL 管理。记录含记忆文本，应视为用户数据。
• 本修复消除可恢复快照的重复重建，不能保证提供商仍保留 KV cache 或保证命中率。

Agent 工具与记忆生命周期

Read the full README on GitHub →