持久记忆管家 linx2568/dsh-memory-curator

dsh-memory-curator

为 DeepSeek Harness 提供经过整理的持久记忆：自动捕获决策、纠正、禁令和未完成的工作；渐进式披露召回；重复项合并；新旧冲突消解。全部数据都在本地——$DSH_HOME 下只有一个 JSON 存储，自身不联网，不需要账号，不需要 API key。模型调用复用 Harness 的 llm 服务，因此记忆沿用用户的 service provider、凭据和重试策略。

中文说明

安装

纯 Cordis bundle：无需构建步骤，无运行时依赖。

1. install it into the profile that runs your DSH
cd "${DSH_HOME:-$HOME/.dsh}/profiles/desktop" # your own profile directory
pnpm add link:/path/to/dsh-memory-curator

2. list it as a bundle in that profile's package.json, e.g.
"dsh": { "profile": { "bundles": [
"@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-memory-curator" ] } }

重启 DSH。宿主侧挂载捕获、召回、整理和六个 memory_ 工具；浏览器侧在左侧边栏添加 Memory 入口。包内自带 cordis.patch.yml——DSH 组装插件树时应用的补丁——因此插件行和默认配置都来自包本身。

DSH 的插件管理器（Settings → Plugins）接受同样的 link: 写法，并替你完成这两步；之后刷新页面即可，无需重新构建。

功能

| | 行为 | 实现方式 |
| A. 自动捕获 | 一轮对话结束时，把对话提炼成值得跨会话保留的持久条目：指定的技术参考、架构决策、明确纠正、禁令、未完成的工作。 | 在 session/event（turn/end）上挂一个即发即忘的监听器，把新消息发给一次有界的辅助 LLM 调用；校验通过的候选条目写入存储。记忆工作绝不会拖慢或弄挂一轮对话。 |
| B. 渐进式召回 | 每轮对话拿到一份有界的索引，每条一行：先放会改变行为的条目（决策、纠正、禁令、未完成的工作），再放最近的事实。全文只在需要时获取。 | 常驻目录注入系统提示词（第 0 层）。memory_search 返回带 id 的简短摘要（第 1 层）。memory_detail 返回完整条目（第 2 层），并记录这次读取，供排序和衰减流程使用。存储增长时，常驻提示词的开销保持平稳。 |
| C. 整理 | 重复的知识合并成一条；同一主题上更新的决策让过时的那条退役。 | 每次插入时以及定期运行一次确定性流程：同主题的决策类条目冲突，新的胜出，旧的作为历史保留，并带 supersededBy 指针。确定性流程无法裁决的相似主题对，交给模型辅助流程裁决，倾向 coexist，确保真正的记忆不会被错误退役。 |

记忆不记录的内容

插件刻意不与项目已有的产物重叠。下面任何一条测试命中，就什么都不记：

| 测试 | 这类信息该放哪 |
| 未来的会话能从仓库里拿到吗？架构、文件路径、构建与测试命令、依赖清单、目录结构、git 历史。 | 代码和 git 本身。 |
| 它是项目级指令吗——约定、「总是/绝不」规则？ | AGENTS.md / CLAUDE.md，每个队友、每个工具都能看到。记忆是本机私有的，团队其他人看不见。 |
| 它是任务状态吗——进度、下一步、已完成的计划？ | STATE.md、待办列表，或 issue 跟踪器。 |
| 它是在报告刚做完某件事吗？「发布了仓库」「重写了历史」「加了一节」。 | 产物本身就是记录。 |

为了让前两条可判定，而不是凭口味，每次蒸馏调用都带上仓库上下文：AGENTS.md / CLAUDE.md 存在时取其有界文本，再加上 README.md、STATE.md、TODO.md、CONTRIBUTING.md、ARCHITECTURE.md、CHANGELOG.md 和 docs/ 的名字。读取按 mtime 和大小缓存，所以安静的仓库每轮只花几次 stat 调用。

剩下的就是没有别处可放的部分：环境和工具链的坑、用户自己的偏好与纠正、以及仓库无从知道的、关于这台机器的事实。

凭据是提示词不够用的唯一情形。lib/store.js 在所有路径都经过的唯一写入卡点上，对凭据形状的字符串做脱敏（sk-…、ghp_… / github_pat_…、AKIA…、xox…、JWT、PEM 私钥），所以自动捕获、工具调用和面板粘贴都覆盖到了。脱敏优于拒绝：泄露密钥周围的那句话通常才是值得留下的部分，所以条目保留下来，密钥位置换成 [redacted]。这些模式命名的是凭据形状，不是「任何看起来随机的东西」——commit id 或 sha256 摘要不受影响。

因为记忆是本机私有的，常驻召回指引里也会告诉智能体：把实际上是项目规则的条目提升到 AGENTS.md / CLAUDE.md，然后 memory_forget 掉它，这样两边不会漂移。

遗忘

从不读取的记忆在每次注入时仍然占用提示词字节，所以存储不是只增不减。三件事会让条目退役，且都不删除文本——退役的条目保留 id、文本和历史，只是不再被召回：

| 状态 | 含义 |
| superseded / merged | 同一主题上更新的陈述取代了它，或重复条目并入了它。带 supersededBy 指针。 |
| forgotten | 有人主动让它退役（memory_forget，或面板的 Forget）。 |
| decayed | 连续 decayAfterDays 没人读，且年龄超过 decayGraceDays。 |

衰减不会碰那两类价值不取决于读者数量的条目：决策性条目（包括 open 条目），因为还没人踩过的禁令照样有约束力；reference 条目也一样，因为这类条目本来就很少被查阅。「Read」指条目被读过时的 lastRecalledAt，没读过则按条目自身的年龄算。把 decayAfterDays 设为 0 可以关掉衰减。

衡量召回

插件记录的是记忆被用到的情况，而不只是存了什么：memory_detail 会标记它打开的条目（recallCount、lastRecalledAt），面板按条目显示这个计数，头部显示全库总数；索引排序时，刚读过的条目算作新鲜——被用过不会因为年龄受罚。

npm run audit:recall 读取 DSH 自己的会话日志（插件不记录召回事件），报告实际发生了什么：智能体调用了哪些记忆工具、完整打开了多少条目、索引有多少次不得不隐藏条目、眼下哪些条目被隐藏。它只读，并且逐帧解码会话日志，因为 DSH 每条记录写一个 zstd 帧。

对真实使用最初约 7 小时的运行结果：

tool calls memory_add=16 memory_detail=13 memory_forget=10 memory_stats=4
memory_search=0 memory_curate=0
readership 9 of 55 active entries ever opened in full
index 166 injections, 26% of them had to hide entries
eviction 13 of 52 visible entries hidden — 5 decisional, 6 of them read

这次测量推动了两项决定：索引现在分层（规则和决策在前，然后是最近的事实），因为纯按最新优先的索引会让新鲜的任务叙述挤掉真正被读过的平台知识，其中还包括一条生效中的禁令；页脚现在会点名 memory_search，而不只是统计被扣下了多少。

子代理拿到工具，但拿不到常驻索引。 DSH 在头部标记委派会话（origin: 'subagent'、delegationDepth），三个子代理会话里，每个都拿到了完整目录，三个加起来只调了一次记忆。它们仍可按需搜索。

第一次清理，作为实例

那次测量之后，按上面的准入测试手工修剪了存储（先做备份，修剪走面板自己的 /forget，因为运行中的 DSH 把存储放在内存里，会覆盖外部编辑）。56 个活跃条目中：

| 保留（19） | 退役（34） |
| 仓库无从知道的环境与工具陷阱：沙箱对管道子进程 stdio 的 spawn EPERM、MSYS-ssh 变通办法、监听器枚举被 CIM 挡住、哪些文档端点不可达、asar 布局、peerDependency 规则。 | 仓库或文档已经回答的一切：测试数量、许可证、提交结构、主题列表、仓库卫生文件；每份「已发布 / 已验证 / 已重写」的行动报告；以及已经处理完的任务状态。 |
索引从 39 行饱和内容、藏着 15 个条目，变成 19 行、一个都不藏，禁令和决策放在最上面——这正是分层想要的效果。

所需权限

Read Only（仅可查看）就足以使用全部功能。

会话有四种权限模式——Read Only（仅可查看）、Workspace Write（工作区内修改）、Full access（完全权限）和 Auto review——它们约束的是智能体内置工具，不是插件宿主代码：

- 文件工具（read/write/edit/glob/grep）由 dsh-fs-sandbox 约束，也就是沙箱化的 ctx.fs 服务商。它自己的 README 写明：它「限制模型的文件写入和编辑」，这道围栏「是对可信代码中模型可控路径的策略检查，不是内核边界」。它作用在文件工具层内部，不是全局拦截 fs。
- Shell 工具（bash/pwsh）由 dsh-bash-sandbox/dsh-pwsh-sandbox 以子进程方式隔离。插件代码跑在宿主进程里，不在受隔离的子进程中。
- Auto review 审查原生工具调用，不约束插件宿主代码。

本插件直接用 node:fs 做自己的持久化（不走沙箱化的 ctx.fs 接缝），调用 llm 服务（不是文件或 shell 操作），并注册自己的工具（memory_search、memory_detail、memory_add、memory_curate、memory_forget、memory_stats），这些工具的 execute 作为宿主代码运行。以上路径都不经过文件或 shell 沙箱，所以会话权限模式约束不到它们。存储位于 $DSH_HOME/memory-curator/store.json（在工作区之外），在任何模式下写入都能成功——包括 Read Only。

审批策略（Read Only / Workspace Write 下为 ask，Full access 下为 never）只管升级请求（工具用更宽的沙箱模式重试）。本插件的工具不带 sandbox_permissions，从不升级，所以 ask 永远不会打断它们。

| 模式 | 捕获 | 召回 | 整理 | 自定义工具 | 结论 |
| Read Only（仅可查看） | ✅ | ✅ | ✅ | ✅ | 全部功能 |
| Workspace Write（工作区内修改） | ✅ | ✅ | ✅ | ✅ | 全部功能 |
| Full access（完全权限） | ✅ | ✅ | ✅ | ✅ | 全部功能 |
| Auto review | ✅ | ✅ | ✅ | ✅ | 全部功能（实验性宿主） |

配置

所有设置都是可选的；插件包补丁自带合理的默认值。

| 键 | 默认值 | 含义 |
| captureEnabled | true | 把已结束的轮次提炼成持久条目。 |
| recallEnabled | true | 每轮注入常驻目录。 |
| curateEnabled | true | 合并重复条目，淘汰被取代的条目。 |
| catalogMaxBytes | 2400 | 注入索引的字节预算。 |
| curateEveryTurns | 5 | 每 N 轮跑一次模型辅助的冲突处理。 |
| maxConcurrentDistills | 2 | 同时进行的提炼调用上限。 |
| distillTimeoutMs | 60000 | 每次提炼/裁决调用的截止时间。 |
| minTurnChars | 80 | 转录内容短于这个值，就不值得调用模型。 |
| dupThreshold | 0.82 | Jaccard 重叠度超过这个值，两条记录就算重复。 |
| storeFile | $DSH_HOME/memory-curator/store.json | 存储位置。 |

工具

| 工具 | 层级 | 用途 |
| memory_search | 1（摘要） | 按自由文本搜索活跃记忆，返回带 id 的简短摘要。 |
| memory_detail | 2（全文） | 按 id 或无歧义前缀读取一条记录的全文。 |
| memory_add | 写入 | 记录一条持久条目；重复条目会合并，同一主题的决策会取代旧条目。 |
| memory_curate | 写入 | 立即运行整理流程（合并 + 退役 + 裁决）。 |
| memory_forget | 写入 | 将一条记录从召回中退役（软删除，保留为历史）。 |
| memory_stats | 读取 | 计数器：活跃、被取代、已合并、已遗忘，按类型统计。 |

工具 schema 是以 object 为根的 JSON Schema。 ctx.tools.register() 会把工具的 parameters 原样转发给模型服务商——它不做任何编译——所以裸的属性映射
（{ text: { type: 'string', required: true } }）到达时没有根 type，服务商会拒绝
整个请求：

Invalid schema for function 'memory_add': schema must be a JSON Schema of type: "object",
got type: "null". (INVALID_REQUEST)

因此 lib/harness.js 里的 toolDefinition 会把编写用的简写编译成 { type: 'object', properties, required? }，规则与 Harness 自带的 defineTool 相同；如果结果不是以 object 为根，assertParameters 会直接让注册失败。
安装 @deepseek-ai/dsh-tools 后，test/tools.test.js 会用 Harness 真实的编译器交叉校验每个 spec，所以两者不会出现偏差。

管理面板（侧边栏）

浏览器端部分（lib/client.js）会在 DSH 左侧边栏加一个 Memory 按钮。
点击后打开中央面板，通过插件自己的同源 HTTP 路由与宿主通信：

| 面板操作 | 路由 | 效果 |
| 列表 + 过滤 | GET /api/memory-curator/entries | 所有条目（每个作用域和状态），最新的在前。 |
| 搜索 | GET /api/memory-curator/search?q= | 在活跃条目上做服务端关键词搜索。 |
| 展开一行 | GET /api/memory-curator/detail?id= | 全文、id、作用域、后继条目。 |
| 添加记忆 | POST /api/memory-curator/add | 记录一条条目（默认使用 global 作用域）。 |
| 遗忘 | POST /api/memory-curator/forget | 将一条条目从召回中退役。 |
| 整理 | POST /api/memory-curator/curate | 立即运行确定性的合并 + 退役流程。 |

面板通过真实的 --dsw-alias- token 继承外壳主题，无需构建步骤——它就是普通的 React.createElement，通过 window.__ModuleLoader__ 加载。路由由 lib/panel-api.js 挂载到组合的 webServer 服务上，挂载位置在嵌套的 ctx.inject fiber 内，所以没有 web 服务器的组合只会失去面板，捕获和召回不受影响。
为什么用 HTTP，而不是 ctx.remote.memoryCurator？ 浏览器端如果声明对某个 Remote 命名空间的硬依赖（inject: ['remote.<ns>']），而该命名空间始终不出现，这个条目就会一直停在 pending 状态；DSH web shell 会把处于 pending 状态的客户端条目报告为启动失败 —— web boot: 1 entry did not activate —— 整个应用因此无法启动。同源路由没有这种耦合：后端缺失时，面板只会显示一个普通的、可恢复的错误。已知可用的 dsh-our-free-model bundle 也采用同样的模式。

条目类型

decision · correction · prohibition · reference · open · fact

decision、correction 和 prohibition 属于决策类：在同一作用域、同一主题下，较新的条目会取代较旧的条目。其余类型按主题归并，但不淘汰旧条目。

存储与作用域

- 单个 JSON 文档，原子写入（临时文件 + rename），权限 0600。存储损坏时，文件会被隔离到 store.json.corrupt-<ts>，而不是让配置档崩溃。
- 条目按工作区划分作用域（取会话 cwd 的 SHA-1 前缀）；global 作用域对所有工作区可见。召回时能看到当前作用域加上 global。
- 硬性上限：5000 个条目（先丢弃已淘汰的历史），每条文本 1200 字符，每个主题 200 条，12 个标签。

架构

lib/index.js — Cordis Service (TypertRemoteService) + Config; delegates to mount() lib/mount.js — mount(): capture wiring, recall injection, tool registration, panel API lib/tools.js — the six tool specs: authoring parameter map + handlers (single source of truth) lib/panel-api.js — /api/memory-curator/* HTTP surface for the sidebar panel lib/client.js — browser half: sidebar entry + management panel (React, same-origin fetch) lib/harness.js — Harness glue with zero install-time deps (plain ctx.tools/ctx.llm contracts, plus the parameter-spec → object-rooted JSON Schema compiler) lib/store.js — MemoryStore: insert/fold/conflict/curate/search/forget + atomic persistence lib/extract.js — distillTurn (A) and resolveConflict (C, model-assisted) lib/parse.js — pure prompts, JSON extraction, entry validation, transcript rendering lib/recall.js — catalog/digest/detail rendering with byte budgets

没有构建步骤。宿主端把 @deepseek-ai/cordis 和 @deepseek-ai/schemastery 声明为 peer 依赖（由 Harness 运行时提供）；浏览器端只需要 react（由客户端模块加载器提供）。

@deepseek-ai/dsh-tools 是仅用于开发的依赖，供 npm test 使用：schema 契约测试会用 Harness 真实的 parameterSchemaSpecToJsonSchema / assertSupportedJsonSchema 来比对本插件的编译器和 schema。该依赖缺失时，这些测试会自动跳过，所以即使在一个没有安装开发依赖的干净检出里，插件依然能运行、测试依然能跑。

在沙箱化的 DSH shell 里，直接运行 npm test 会报 spawn EPERM：Node 的测试运行器会为每个测试文件启动一个子进程，并通过管道捕获它的输出，而沙箱不允许这样做。npm run test:in-process 改为在单个进程里运行同一套测试。

中文说明

为 DeepSeek Harness 提供策展式持久记忆。

- A. 自动记录：每轮对话结束后，把值得跨会话保留的信息蒸馏为持久条目，包括指定的技术参考、架构决定、明确纠错、禁止事项、未完成状态。后台监听 turn/end，fire-and-forget，绝不拖慢或拖垮对话。
- B. 自动召回：每轮注入一行一条的有界索引；memory_search 返回短摘要与 id；memory_detail 按需读取全文。常驻提示成本随库增长保持平坦。
- C. 自动整理：重复知识按 Jaccard 相似度合并；同主题的新旧决策冲突时新者胜出，旧者标记 superseded 并保留 supersededBy 指针；确定性规则无法裁决的相似主题对，交给一次有界模型调用裁决，偏向 coexist，以免误退真记忆。
- D. 管理面板：DSH 左侧边栏新增 Memory 入口按钮，点击打开中央面板，通过插件自己的同源 HTTP 路由 /api/memory-curator/* 列出、筛选、新增、遗忘、整理全部记忆条目。无需构建步骤，纯 React.createElement。

为什么用 HTTP 而不是 ctx.remote.memoryCurator？ 浏览器半若把 Remote 命名空间声明为硬依赖（inject: ['remote.<ns>']），而该命名空间始终不出现，该条目会一直 pending；DSH 网页外壳把 pending 的客户端条目判定为启动失败（web boot: 1 entry did not activate），导致整个应用无法启动。同源路由没有这种耦合：后端缺失时面板只显示一个可恢复的错误。此做法与已知可用的 dsh-our-free-model 插件一致。

- 同源护栏：这些路由注册在 DSH 的 web server 上，而插件前缀在该 server 的鉴权闸门之前分发——同一端口上 DSH 自带的 /api/client-modules 无凭据返回 401，本插件的路由却返回 200（已在 127.0.0.1:19387 实测）。因此处理器自己校验浏览器给出的跨站标记：Sec-Fetch-Site 不是 same-origin/none，或 Origin 的主机与本次请求的 Host 不一致，一律 403。会带这两个头的是浏览器；两者都没有的请求来自本地进程（脚本、curl、测试），不具浏览器的环境权限，照常放行，所以命令行调用不受影响。

- 与仓库文档的边界：不记录仓库已经拥有的东西。四条判据命中任意一条即不记：①未来会话能从仓库得到吗（架构、文件路径、构建/测试命令、依赖清单、目录结构、git 历史）；②它是项目级指令吗（约定与「永远/绝不」类规则属于 AGENTS.md/CLAUDE.md，而记忆是本机私有，团队其他人看不到）；③它是任务状态吗（进度、下一步、已作废的计划属于 STATE.md/待办/issue）；④它是「刚刚做完了什么」的动作报告吗（产物本身就是记录）。为了让前两条可判定而不是凭感觉，每次蒸馏都会带上仓库上下文：AGENTS.md/CLAUDE.md 的正文（有界 2000 字符）加上 README.md、STATE.md、TODO.md、CONTRIBUTING.md、ARCHITECTURE.md、CHANGELOG.md、docs/ 的存在清单；读取按 mtime+size 缓存，仓库没变时每轮只花几次 stat。剩下才是记忆的正当范围：环境与工具的坑、用户自己的偏好与纠正、以及仓库不可能知道的本机事实。另外，因为记忆是本机私有的，常驻召回指引会要求代理把「本质上是项目规则」的条目升级进 AGENTS.md/CLAUDE.md，然后 memory_forget 掉，避免两处漂移。

- 召回可测，且防止「劣币驱逐良币」：注入的索引分两层——会改变行为的条目（decision/correction/prohibition/open）优先，其后才是最新的事实；同层排序中「刚被读过」的条目视同刚写入（lastRecalledAt），所以有用不会被年龄惩罚。memory_detail 每次打开条目计一次 recallCount，面板按条显示、表头显示总量。实测（约 7 小时真实使用）发现：纯新近度排序会让刚捕获的任务叙事把被真正读过的平台知识挤出索引（含一条 prohibition），而全部 15 条决策类合计只占 983 字节——这直接促成了索引分层与脚注改写。npm run audit:recall 读取 DSH 自己的会话日志（插件不记录召回事件）输出上述指标，只读，且必须逐帧解码 zstd（DSH 每条记录一个帧）。子代理不注入常驻索引，但保留工具可按需检索：实测三个子代理会话各自拿到完整索引，合计仅调用过一次记忆工具。

工具 schema 必须是以 object 为根的 JSON Schema

ctx.tools.register() 会把工具的 parameters 原样交给模型服务商，不做任何编译。因此若直接传属性映射（{ text: { type: 'string', required: true } }），根节点没有 type，服务商会直接拒绝整个请求：

Invalid schema for function 'memory_add': schema must be a JSON Schema of type: "object",
got type: "null". (INVALID_REQUEST)

失败的是整轮请求而非单个工具——同一次请求里的所有工具全部不可用。lib/harness.js 的 toolDefinition 现在会按照 Harness 自身 defineTool 的规则，把简写编译成 { type: 'object', properties, required? }；assertParameters 会在注册时就拦下不合规的 schema。test/tools.test.js 在装有 @deepseek-ai/dsh-tools 时直接调用 Harness 的真实编译器逐项比对，避免两边规则漂移。

运行完整功能所需的最低权限

仅可查看（Read Only）模式下即可运行全部功能。

四种会话权限模式（仅可查看 / 工作区内修改 / 完全权限 / Auto review）约束的是智能体的内置工具，而非插件宿主代码：

- 文件工具（read/write/edit）由 dsh-fs-sandbox（沙箱化的 ctx.fs 提供方）围栏，其 README 明确写道：它限制的是「模型对文件的写入与编辑」，围栏「是在可信代码中检查模型控制路径的策略，而非内核边界」——即在文件工具层内检查，并非全局 fs 拦截。
- Shell 工具（bash/pwsh）以子进程方式由 dsh-bash-sandbox/dsh-pwsh-sandbox 隔离；插件代码运行在宿主进程，不在受限子进程内。
- Auto review 审查原生工具调用，不围栏插件宿主代码。

本插件用 node:fs 直接持久化（不经沙箱化的 ctx.fs），通过 llm 服务调用模型（非文件/Shell 操作），并注册自己的工具（其 execute 为宿主代码）。这些路径都不经过文件或 Shell 沙箱，因此会话权限模式不约束它们。存储位于 $DSH_HOME/memory-curator/store.json（工作区之外），在任何模式下写入均成功——包括仅可查看。

审批策略（仅可查看/工作区内修改下为 ask，完全权限下为 never）只管升权请求（工具以更宽沙箱模式重试）。本插件工具不带 sandbox_permissions、从不升权，故 ask 永远不会打断它。

License

MIT