Git 本地记忆 seriousz158/dsh-memory

dsh-memory

dsh-memory 是 DeepSeek Harness (DSH) 的本地长期记忆插件，用 Git 做后端。

它新增一项持久化设置、一套安全的设置页工作流用来清空记忆，还有一个可选的空闲会话同步器。只有当 memory.enabled 为 true 时，宿主插件才会注入记忆指引；UI 插件让你查看仓库状态、切换这项设置，并通过刻意的两步确认清空已学习的记忆。

它能做什么

- 把持久记忆存进本地 Git 仓库，而不是这个源码仓库，也不是托管服务。
- 立即注册 memory 设置命名空间，所以 memory.enabled 对下一次模型调用就生效，不用重启 DSH。
- 在 DSH 设置里显示一行长期记忆，带仓库状态，以及需要双重确认的 Delete memory 操作。
- 清空 summary.md、handbook/、rollouts/ 和 archive/ 之前保留一个 Git 恢复点：干净的仓库复用现有 HEAD，脏的目标路径会拿到一个专门的检查点提交；下一次提交记录清空后的状态。
- 拒绝不安全的仓库布局、符号链接逃逸、非仓库根目录，以及清空操作期间的路径竞争。
- 可以通过可选的无头同步器，只处理空闲的本地会话日志。同步器默认使用 workspace-write，绝不静默安装 DSH，只转发白名单内的环境变量。

能力

这份 README 描述稳定的面向用户行为。逐版本的实现细节有意不放在这一页；历史变更见 CHANGELOG.md 和 GitHub releases。

本地 Git 后端记忆

- 记忆留在本地 Git 仓库里。没有托管记忆服务，也没有云端向量数据库。
- Markdown 记录支持 front matter、带命名空间的 id、来源信息、过期投影、确定性冲突处理，以及旧版兼容。
- summary.md 是简短的导航快照；详细知识放在 handbook/、rollouts/ 和 archive/。

安全同步与恢复

- 可选的空闲会话同步在每次运行私有的工作区里跑。模型只能编辑隔离的副本；宿主负责校验并写入实时的 Git 仓库。
- 宿主提供 dry-run/preview/apply 流程、操作锁、健康检查、有界批次、重试退避、重复 id 诊断，以及只含元数据的日志。
- 恢复/应用提交、回滚、备份导出/导入，以及旧版迁移，让变更可审计、可回退。迁移通过 CLI/宿主 API 提供，不在设置 UI 里。

读取路径

- 启用后，模型可以拿到一份有界且明确不可信的 summary.md 快照（最大 12 KiB）。
- memory.search() 和 memory.context() 提供本地、有界的检索带来源引用和基于使用情况的确定性排序。检索是混合式的：一个派生的 SQLite 索引（FTS5 trigram + CJK 二元组/词项，存放在 .sync/search-index.sqlite，权限受限）与词法评分、精确子串优先融合，当索引缺失、过期或损坏时，会透明地回退到纯扫描。
- 读取使用情况作为私有元数据存放在 .sync/usage.json；转录、提示词、凭据和记忆内容不会写入日志。

DSH 设置集成

设置界面提供记忆开关、仓库状态、最近同步状态、预览操作、回滚，以及需要明确确认的清除操作。它不暴露文件系统根目录，也不直接执行 Git。

兼容性

v0.10.0 面向 DSH 桌面应用 0.2.x，并保留 0.1.x Web 运行时的 peer 范围：

| 组件 | 支持的版本 |
| DSH 桌面应用 | 0.2.0-rc.2（peer 范围 >=0.2.0-rc.2 <0.3.0） |
| DSH Web 运行时 peer 范围 | ^0.1.0-rc.6 \|\| 0.1.5-rc.1 \|\| 0.1.7-rc.1 |
| 净室开发测试依赖图 | DSH 客户端包 0.1.0-rc.7 |
| Node.js | 22.x |
| Python | 3.11.x |
| Git | PATH 上可用的本地可执行文件 |
| 操作系统 | macOS 是受支持/已测试的集成目标 |

本包使用 DSH 的 Cordis 加载器接口。rc.7 依赖图是可复现的开发和集成基线，因为注册表的 rc.6 传递 peer 依赖图无法用普通的 npm ci 安装；这不改变宿主/UI 包声明的 rc.6 运行时 peer 范围。DSH rc.8 及之后的版本在通过本仓库的测试套件之前均未经验证。

安装

DSH 插件包（推荐）

仓库根目录同时也是一个名为 dsh-git-memory 的公开 DSH 包。它包含宿主插件、设置页客户端包，以及对应的 dsh.bundle 补丁，因此一次安装即可激活两部分：

GitHub 源码安装（在 npm 发布之前或没有 npm 发布时也可用）
dsh plugin --profile web add github:seriousz158/dsh-memory

DSH 桌面应用 0.2.x：使用应用自带的 CLI 和 desktop 配置档
"/Applications/DeepSeek Harness.app/Contents/Resources/runtime/cli/bin/dsh" \
plugin --profile desktop add github:seriousz158/dsh-memory

桌面配置档规则（仅限聚合包、默认记忆根目录）见 docs/installation.md。

本项目通过 GitHub 源码安装和 GitHub Releases 分发，未发布到 npm。

安装后重启选定的 DSH 配置档。包中不包含任何记忆数据、会话日志、凭据或本地 .dsh 目录。

源码检出（开发 / 本地集成）

克隆仓库并安装可复现的开发/运行时依赖：

git clone https://github.com/seriousz158/dsh-memory.git
cd dsh-memory
使用本次 v0.8.4 集成测试所用的固定运行时。
npm install --global @deepseek-ai/dsh@0.1.0-rc.7
dsh --version
npm ci --ignore-scripts

两个 workspace 实现包保持私有，只有根目录的 dsh-git-memory bundle 可以发布。这样内部 host/UI 包名保持稳定，同时避开已被占用的无 scope 的 dsh-memory npm 名称。

把这两个本地包安装到你的 DSH 配置档。安装器默认使用 ~/.dsh。如果你用了非默认的 DSH 或 memory 路径，请在安装、启动、校验、同步 DSH 的环境里保持同一组值：

./integrations/dsh/install.sh

Example for a non-default DSH home and memory repository:
export DSH_HOME="$HOME/.config/dsh"
export DSH_MEMORY_ROOT="$HOME/Documents/dsh-memory-data"
./integrations/dsh/install.sh
Start DSH from this configured environment as well.

安装器只创建这些 DSH 配置档链接和两个必需的 Cordis 条目：

<DSH_HOME>/profiles/node_modules/dsh-memory
<DSH_HOME>/profiles/node_modules/dsh-memory-ui

它还会把缺失的 memory root 初始化为私有本地 Git 仓库。如果 memory 仓库已经完整存在，它会校验目录结构并恢复仅属主可访问的权限；它不会删除或改写已学习的记忆、会话历史、凭据、其他插件，或无关的 cordis.patch.yml 条目。使用自定义 memory root 之前，请先看安装细节。

安装完成后重启 DSH host。在 DSH Settings 里找到 长期记忆，保持开关打开，下一次模型调用即可启用回忆。

存储布局

默认情况下，host 使用：

<DSH_HOME>/storages/memory

DSH_HOME 默认为 ~/.dsh。运维人员可以把 DSH_MEMORY_ROOT 设为其他本地绝对路径。安装器、每次启动 DSH host、显式运行 initializer、以及可选的 synchronizer 运行时，它都必须存在；一次性安装时赋值不会配置后续的 LaunchAgent 任务。Web UI 无法提交或修改文件系统路径。

初始化后的仓库包含：

summary.md short, stable navigation and preferences
handbook/ reusable knowledge
rollouts/ per-session extraction results
archive/ superseded entries
scripts/ transcript filter helper
.last-sync optional synchronizer watermark

设置与 API

唯一持久化的设置是：

memory:
enabled: true

本地 UI 只与固定的 memory 远程服务通信：

memory.getSettings()
memory.setEnabled({ enabled: boolean })
memory.status()
memory.legacyRecords()
memory.migrateLegacy({ dryRun: boolean })
memory.clear({ confirmation: "DELETE_MEMORY" })

status() 返回 empty、dataFileCount、targetDirty、recoverable 等元数据；它从不返回记忆正文。完整的请求/响应契约和稳定错误码见 docs/api.md。

安全清空记忆

设置 UI 有意要求两次确认：
1. 点击 删除记忆，查看受影响的路径，然后点击 继续。
2. 原样输入 删除记忆，然后点击最终确认。

清除操作用于日常可恢复的重置，并不保证彻底抹除隐私。在改动任何目标记忆路径之前，它会先保留一个恢复点：对于干净的仓库，恢复点就是现有的清除前 HEAD；而对于有未提交改动的目标路径，则会记录在一个专门的检查点提交里。随后，清除提交直接创建在这个恢复点之上。该操作会保留 .git、README.md、辅助脚本、目录结构和 .last-sync，这样后续会话仍能重新学习，无需重新处理历史日志。

在本地记忆仓库里使用 Git 历史来恢复检查点。如果有隐私敏感的删除要求，请移除相关本地备份，并遵循你所在组织的保留策略；仅靠 Git 历史并不是安全的抹除机制。

可选的空闲会话同步

可选的同步器独立于设置界面：

./integrations/dsh/dsh-memory-sync

当 memory.enabled 为 false 时它会跳过工作，也会跳过活跃会话。它需要用户自行安装的 dsh 可执行文件（或显式指定的 DSH_BIN），而不是调用 npx --yes。它默认使用 workspace-write；更宽的权限绝不会成为仓库默认值。LaunchAgent 模板显式设置了默认的 DSH 和记忆路径；如果你的安装是自定义的，加载前请先修改这两处赋值。

在转录内容送达记忆提取模型之前，会话过滤器会抹掉常见凭据格式和主目录前缀。这是纵深防御，并不承诺能检测出所有密钥格式。启用无人值守同步前，请先阅读隐私与恢复。

开发

运行完整的本地测试套件：

npm ci --ignore-scripts
npm test

测试使用临时 Git 仓库和合成夹具。它们不得要求 DSH 账号、启动 Chrome、加载 LaunchAgent、读取当前用户的记忆/会话文件夹，或发起付费模型请求。

在提交 issue 或 pull request 之前，请运行：

npm test
zsh tools/secret-scan.sh

参见 CONTRIBUTING.md、SECURITY.md 和发布检查清单。

隐私承诺

本仓库只包含代码、测试、模板和示例。它绝不能包含任何真实的 DSH 记忆、会话日志、凭据文件、浏览器配置档或用户特定的 DSH 配置。如果你认为敏感数据已被提交，请视其为已泄露，轮换受影响的凭据，并遵循 SECURITY.md。

许可证

MIT © 2026 seriousz158。