MoonlitDropOfBlood/dsh-memory-manager

DeepSeek Harness 记忆管理插件

_中文

---

为 DeepSeek Harness（DSH） Web UI 打造的持久化记忆插件，移植自 ZCode 的项目记忆（Memory）：按项目（工作区）保存结构化记忆，并在设置里提供完整的记忆管理页面。

记忆以 ZCode 同款 Markdown 格式落盘（<DSH_HOME>/memories/projects/<project>/memory/*.md，含 MEMORY.md 索引与 memory_summary.md 摘要），并支持一键从 ZCode 记忆目录导入，把 ZCode 里积累的用户偏好 / 反馈 / 技术参考直接搬进 DSH。

功能

功能	说明
🧠 ZCode 记忆移植	沿用 ZCode 的记忆文件格式（YAML frontmatter + 正文）、类型体系（user / feedback / reference / project / other）与按项目分目录的存储布局
⚙️ 设置中的记忆管理	设置面板新增 记忆管理 页（侧栏带 brain 图标）：搜索、项目/类型筛选、按项目分组、新建 / 编辑 / 删除 / 查看正文
🗑️ 回收站（软删除）	删除不再永久销毁：记忆移入项目回收站并留下「遗忘原因」墓志铭，随时可恢复；只有「彻底删除」才移除文件
🧬 记忆生命周期	置顶（永不被条数上限挤掉）、取代链（memory_correct 写新条目并把旧条目标为「已被取代」，旧文件保留可审计且不再注入）、覆盖快照（.history/ 保留最近 5 版）
🏷️ 来源与时效标注	注入的索引行带来源（人工 / AI / 导入）与日期，AI 自己写下的旧结论会被明示为低证据强度；超过类型相关期（user 10 年 / feedback 3 年 / project·reference 180 天）的条目标「可能过时」
🔍 相似记忆提示	新建记忆时按「名称字符相似 + TF-IDF 语义余弦 + 释义改写」三层信号检测近乎重复的旧条目（阈值用真实库 2485 对校准，不误报同前缀不同主题），提示改用 memory_correct
🛡️ 并发安全	写入走跨进程目录锁 + 原子 rename：两个会话同时改同一条记忆时，后写者收到「已被其他会话修改」冲突而不是互相覆盖；崩溃也不会留下半截文件
🔄 自动加载到对话	每次模型调用自动把「当前项目 + 全局」的记忆索引按相关度（置顶 > 类型 > 使用次数 > 新旧）排序注入，省上下文；也可切换为附带正文截断的旧模式
🤖 Agent 记忆工具	注册 memory_save / memory_get / memory_list / memory_forget / memory_correct / memory_review 六个工具：读取全文、跨项目搜索、自我纠错（取代链）、软遗忘、定期体检
📥 从 ZCode 导入	一键扫描 ~/.zcode/cli/memories（memory/ + topics/），按项目 + 名称去重，不覆盖已有记忆
🌐 全局 + 项目记忆	global 项目存放跨项目记忆；项目 key 取自工作区路径名，自动清洗为安全片段
📄 自动索引	每次变更自动重写 MEMORY.md 索引与 memory_summary.md 摘要（含「已被取代」标记）
🌗 主题适配	全部使用 DSH 设计 token（按钮为官方 DSH Button 组件），明暗主题自动跟随

安装

标准安装（推荐）

本插件是标准 DSH bundle：package.json 声明 dsh.bundle.patch，包内自带 cordis.patch.yml，用官方 dsh plugin 命令安装：

# 本地开发：pnpm 软链到本仓库，改代码即生效（无需重新复制）
dsh plugin --profile web add /path/to/dsh-memory-manager

# 正式发布：从 GitHub Release tarball 安装
dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-memory-manager/releases/download/v1.5.0/dsh-memory-manager-1.5.0.tgz

重启 DSH 后，打开 设置 → 记忆管理 即可使用。

dsh plugin add 把插件装成 profile 的 npm 依赖并追加到 dsh.profile.bundles，启动时 DSH 自动应用包内的 cordis.patch.yml 挂载插件。卸载：dsh plugin --profile web remove dsh-memory-manager。

宿主兼容性

支持 DSH 0.1.0-rc.7 ~ 0.2.x（engines.dsh: ^0.1.0-rc.7 || ^0.2.0-rc.1，已在本机 0.2.0-rc.1 与 0.2.2-rc.1 宿主端到端验证）。DSH 0.2.0 起宿主会在启动时按 peerDependencies 的 @deepseek-ai/dsh* 声明做兼容预检，范围不满足的 bundle 会被静默跳过——如果升级宿主后插件消失，先确认版本声明覆盖了新宿主，再跑 npm run e2e（对真实安装验证闸门、Host 激活、CRUD、TypertRegistry 与 client bundle）。

DSH 0.2.2 起设置壳把导航图标改为从 settings.section.icon 槽按行 id 取（settings.section 本身仍只投影 id/order/label），本插件已原生注册侧栏 brain 图标；0.2.1 及更早的宿主没有该槽，继续走 CSS 兜底路径，两条路径互斥、不会同时渲染。

使用

1. 打开 设置，侧栏出现 记忆管理 页。
2. 列表按项目分组、最新优先；顶部可搜索（名称/描述）、按项目和类型筛选；卡片展示类型徽章与更新时间。
3. 自动加载记忆到对话上下文：默认开启。每次模型调用，DSH 会把当前会话工作区项目的记忆 + 全局记忆的索引（名称 + 描述 + 来源 + 日期，不含正文）按相关度排序注入给智能体，agent 对某条感兴趣时自行用 memory_get 工具读取全文——比全量注入省一个量级的上下文。需要旧行为（每条附带 400 字正文截断）可在记忆管理页打开「注入记忆正文」。
4. Agent 回写记忆：agent 在对话中发现值得长期保留的用户偏好、纠正/反馈、项目约定时，会自己调用 memory_save 写入记忆（origin: agent），之后每轮索引自动带上它。也可在记忆管理页看到、编辑或删除这些记忆。
5. 并发与冲突：如果你在设置页编辑一条记忆的同时另一个会话也改了它，保存会提示「记忆已被其他会话修改，请刷新后重试」，不会悄悄覆盖。
6. 纠错与遗忘：旧结论被推翻时 agent 会用 memory_correct 写新条目并取代旧条目（旧条目留在磁盘标记「已被取代」、不再注入）；确定无用则 memory_forget 移入回收站。memory_review 可列出过时 / 长得一样 / 已被取代的条目，相当于记忆体检。
7. 新建记忆：填写名称（建议短横线 slug，可含中文）、类型、项目（global = 全局，或某个项目名，可参考工作区建议）、描述与 Markdown 正文；可勾选「置顶」让它永远排在索引最前。
8. 编辑 / 查看 / 删除：每行右侧操作；编辑会自动留旧版本快照；删除只会移入回收站（可在侧栏「回收站 (n)」里恢复或彻底删除）。
9. 从 ZCode 导入：一键导入 ~/.zcode/cli/memories 下各项目的记忆，同名自动跳过，结束后展示每个项目的导入/跳过统计。

工作原理

DSH Web UI
  └─ client.js (window.__ModuleLoader__.load bundle)
       └─ settings.section 注册「记忆管理」页
            ├─ settings.section.icon 注册侧栏 brain 图标（DSH >= 0.2.2 原生槽；旧宿主走 CSS 兜底）
            └─ ctx.remote.memoryManager.{list|get|create|update|delete|forget|restore|purge|importZCode|getConfig|setConfig}
                 └─ index.js (MemoryService, TypertRemoteService)
                      ├─ systemPrompt.section（order 90）→ 每次模型调用注入「记忆索引」段落
                      │    └─ context.agent.session.header.cwd → 项目 key → 项目 + 全局记忆索引
                      │       （置顶 > 类型权重 > 使用次数 > 新旧；带来源/日期/可能过时标记）
                      ├─ ctx.tools.register → memory_save / memory_get / memory_list /
                      │                       memory_forget / memory_correct / memory_review
                      │    └─ systemPrompt.section（order 100）→ 工具使用指引
                      └─ memory-core.mjs（node:fs 直接读写）
                           ├─ <DSH_HOME>/memories/projects/<p>/memory/<name>.md
                           ├─ <DSH_HOME>/memories/projects/<p>/.archive/      （回收站，优雅遗忘）
                           ├─ <DSH_HOME>/memories/projects/<p>/.history/      （覆盖快照，保留最近 5 版）
                           ├─ <DSH_HOME>/memories/projects/<p>/MEMORY.md
                           ├─ <DSH_HOME>/memories/projects/<p>/memory_summary.md
                           └─ <DSH_HOME>/memories/config.json（autoLoad / injectBody 开关）

记忆存储走 node:fs 直接落在 <DSH_HOME>/memories/（与 DSH 核心写 ~/.dsh 的方式一致），无需 shell 沙箱。

目录结构

dsh-memory-manager/
├── index.js            # Host 半：MemoryService（Remote 服务）
├── client.js           # Client 半：设置「记忆管理」页 UI bundle
├── typert.host.js      # Typert Host manifest（Remote 方法描述）
├── memory-core.mjs     # 共享记忆核心（frontmatter / 存储 / 索引 / ZCode 导入），零依赖
├── cordis.patch.yml    # dsh bundle patch（挂载行）
├── scripts/self-test.mjs # 独立核心自测（无需 DSH 进程）
├── .github/workflows/  # GitHub Actions 发布
├── AGENTS.md           # 面向 AI agent 的开发指南（含踩坑）
└── LICENSE             # MIT

开发

npm run check           # 全文件语法检查
npm test                # 独立核心自测（CRUD / 索引 / ZCode 导入 / 遗忘·取代链·相似度 / 注入排序）
npm run e2e             # 对真实 DSH 安装跑端到端（启动闸门 / Host 激活 / Remote / 工具 / client bundle）
dsh plugin --profile web add /path/to/dsh-memory-manager   # 安装/重装到本机 DSH profile

详见 AGENTS.md——记录了 DSH 正式插件（Host/Client/Typert 三件套）的完整机制和踩坑。

License

本项目遵循 MIT License。

本项目是基于 DeepSeek Harness 构建的社区插件，并非 DeepSeek 官方产品。记忆格式移植自 ZCode 的项目记忆设计。