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 设置集成

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

兼容性

v0.9.2 保持 DSH 0.1.0-rc.6 的对等兼容范围，并已通过测试，且在本地与一致锁定的 0.1.0-rc.7 依赖图集成：

| 组件 | 支持的版本 |
| --- | --- |
| DSH 运行时对等范围 | @deepseek-ai/dsh@^0.1.0-rc.6（rc.6 和 rc.7） |
| 推荐/已测试的运行时 | 0.1.0-rc.7 |
| 净室开发测试依赖图 | DSH 客户端包 0.1.0-rc.7 |
| Node.js | 22.x |
| Python | 3.11.x |
| Git | PATH 上可用的本地可执行文件 |
| 操作系统 | macOS 是受支持/已测试的集成目标 |

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

安装

DSH 插件包（推荐）

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

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

本项目通过 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

两个工作区实现包保持私有；只有根 dsh-git-memory 包可发布。这样可以在保持内部宿主/UI 包名稳定的同时，避免使用已被占用的非作用域 dsh-memory npm 名称。
将这两个本地包安装到你的 DSH 配置文件中。安装程序默认使用
~/.dsh。如果你使用非默认的 DSH 或内存路径，请在安装、启动、验证和同步 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 条目：

/profiles/node_modules/dsh-memory
/profiles/node_modules/dsh-memory-ui

它还会将缺失的内存根目录初始化为私有的本地 Git 仓库。对于已存在的完整内存仓库，它会验证布局并恢复仅所有者权限；它不会删除或重写已学习的记忆、会话历史、凭据、其他插件或无关的 cordis.patch.yml 条目。在使用自定义内存根目录之前，请参阅安装详情。

安装后重启 DSH 主机。在 DSH 设置中，找到长期记忆并保持开关开启，以便为下一次模型调用启用回忆。

存储布局

默认情况下，主机使用：

/storages/memory

其中 DSH_HOME 默认为 ~/.dsh。操作员可以将
DSH_MEMORY_ROOT 设置为不同的本地绝对路径。它必须在安装程序、每次 DSH 主机启动、显式初始化运行以及可选的同步器运行时都存在；一次性的安装赋值不会配置未来的 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 历史并不是一种安全的擦除机制。

可选的空闲会话同步

可选同步器与设置 UI 是分开的：

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