dsh-memory-plugin

一个独立的 DSH 记忆 / 规则持久插件（profile bundle）：与宿主项目解耦，任何工作区
都能用。它由 AnimeTrack 项目里的动态 Cordis 插件演化而来，早期以
@animetrack/memory-plugin 的名义存在，v1.4.0 起独立命名为 dsh-memory-plugin
（存储路径同批迁移，旧数据自动兼容，见下文）。

它定义在磁盘上、作为 profile bundle 随启动加载，因此重启后不会消失，
不需要任何恢复步骤。

它做什么

• 每轮注入：只注入记忆索引（类型 + 一行摘要 + id + 标签）和启用中的规则；记忆正文
  不再整段塞进提示词，由模型按需 memory_get。索引有固定字符预算（2400 字符 / 40 条），
  装不下的条目会在提示里明说「用 memory_search 找」，不会静默丢弃；
• 模型工具：memory_view / memory_search / memory_get / memory_add / memory_remove /
  memory_rollback / rule_add / rule_remove / memory_debug；
• 记忆类型与标签：user（关于用户）/ feedback（纠正与偏好）/ project（决策、约束、
  坑）/ reference（去哪找东西）；每条可带 tags 与 createdAt / updatedAt；
• 两个界面入口（都能读能改）：
• 标题栏图标：conversation.session.header.utilities，与「在应用中打开」「下载会话日志」
  同排的 28×28 圆形图标（照搬官方按钮规则），点开后浮层锚在图标正下方；
• 设置页：settings.section 里的一页「记忆与规则」。
• 数据文件：/.dsh-memory/memory-store.json（v1.3.x 及更早写在
  .animetrack/memory-store.json，格式完全一致，仍可读）。

索引式注入与检索（v1.5.0，对标 Claude auto memory）

v1.4 及更早把最近 25 条记忆全文注入系统提示，条目一多就挤占上下文，老条目还会被
slice(-25) 静默切掉。v1.5.0 改成 Claude Code auto memory 的两层结构：

• 索引常驻：每轮只注入一行一条的索引，例如
  - [feedback] 回答用中文，不要用敬语 #风格 #语言 (m7)；
• 正文按需：模型用 memory_get(["m7"]) 读全文，用 memory_search("构建") 按关键词、
  标签或类型找回索引里没列出的条目；
• 预算固定：索引 2400 字符 / 最多 40 条，规则 1200 字符 / 最多 25 条。超出时提示里
  直接写「还有 N 条未展示，用 memory_search」，不静默丢弃；
• 去重：memory_add 对「忽略大小写与空白后完全相同」的正文直接拒绝，返回已有条目的 id。

类型与标签都可选：面板的添加框有类型下拉和标签输入，模型工具也有 type / tags 参数。
旧版数据（没有这些字段）载入时自动补成 project + 空标签，下一次写入自然升级，不需要迁移脚本。

检索是本地打分（拉丁词 + 中文 bigram + 标签/类型命中），不引入 embedding、向量库或
任何运行时依赖。它不追求语义召回，只保证几十到几百条规模下「关键词找得回来」。

轮末提炼、草稿审批与版本链（v1.6.0）

v1.6.0 补上「写入」这一环。自动提炼默认关闭，在面板「记忆」页勾选后生效：

1. 监听 session/event 的 turn/start / user/message / assistant/message / turn/end，
   在轮末异步蒸馏，不阻塞轮次收尾（刻意不监听 serial 的 agent/turn-stopping）；
2. 只处理达到 minChars（默认 800）的轮次；同一工作区默认 5 分钟冷却，避免每轮都调模型；
3. 用当前会话的 provider / model 发一次辅助请求，要求返回 JSON 数组；本地再过滤重复条目、
   失效的 supersedes 目标；
4. 结果一律先落草稿队列（面板「待审 N」），批准后才写入 active 记忆。草稿不注入、
   不参与检索，批准前对模型完全不可见；
5. 如果新事实推翻旧事实，带 supersedes: "m3"：
   - 新条 active，supersedes 指向旧条；
   - 旧条转 archived，supersededBy 指向新条，正文保留；
   - 面板上归档条显示「回滚」，memory_rollback 工具也能撤销一步。

默认参数：minChars: 800、cooldownMs: 300000、maxDraftsPerTurn: 3；面板里目前只暴露
自动提炼开关，其余参数可改 memory-store.json 的 settings。自动提炼会产生额外模型调用，
默认关闭是成本考虑。

记忆库落在哪个工作区（v1.3.0 起）

记忆库是按会话工作区分文件的：/.dsh-memory/memory-store.json。
目标根按这个顺序解析，并且在载入时锁定：

1. 显式会话（面板通过 ?sessionId= 带来的那个）；
2. 当前 initiator 会话（模型工具调用就在这条异步链里）；
3. 最近一次由主会话确定的根（pinnedRoot，给没有会话上下文的设置页用）；
4. 配置根（sandboxPolicy.workspaceRoot，通常是 profile 目录）。

每个根各自持有一份内存状态，互不覆盖；写入只落在本次状态所属的那个根。

> v1.2.0 及更早的实现有三个相关缺陷，v1.3.0 全部修掉，见文末「修掉的 bug」。

旧路径兼容（v1.4.0）

新路径不存在、而旧路径 /.animetrack/memory-store.json 存在时，插件会
回退读旧文件（memory_view / 面板上会标注「读自旧路径」），内容照常可用；
旧文件不会被改写或删除，下一次落盘统一写新路径 —— 也就是一次天然的迁移。
memory_debug 会同时列出 storePath / legacyStorePath / usingLegacy。

结构

dsh-memory-plugin/
package.json        bundle 清单：dsh.bundle.patch + dsh.client(./client 导出)
cordis.patch.yml    一行加载行：name: 'dsh-memory-plugin'
lib/host.js         Host 半部（ESM）：索引注入 + 9 个工具 + 轮末提炼 + 同源 HTTP 路由
lib/client.js       Client 半部（经典脚本）：__ModuleLoader__.load 注册上面两个 slot
test/host-harness.mjs   Host 半部桩测试（真实 fs + 假 ctx，不需要 DSH）
LICENSE / .gitignore    发布用（MIT；忽略 node_modules 与 *.tgz）
docs/legacy/            旧「动态 Cordis 插件」实现归档（不参与打包，仅历史参考）

一个 dual-face 包只用一行：包的 "." 导出是 Host 半部，"./client" 导出是浏览器半部。

安装

这是个标准 npm 包 + DSH bundle，三种装法（plugin_manager install_bundle 都受理）：

1) 从 GitHub 装（发布形态）

plugin_manager install_bundle
target: github:AieXile/dsh-memory-plugin#v1.6.0
# 也可以写完整地址：git+https://github.com/AieXile/dsh-memory-plugin.git#v1.6.0

DSH 先 git ls-remote 探一次仓库（默认 5s 超时，禁用凭据助手与交互提示），
再由 pnpm 拉取，并按本包 files 列表打包安装。#v1.6.0 是 tag，也能写分支或 commit。
这是「GitHub 发布」的标准形态：仓库本身就是包，不需要 extra 构建产物。

2) 从 npm 装（发布后）

plugin_manager install_bundle
target: dsh-memory-plugin@1.6.0

包名不带 scope，publishConfig.access = public 也已声明，推 npm 时不需要额外占坑。

3) 从本地目录装（开发用，当前 profile 就是这样）

plugin_manager install_bundle
target: F:\Projects\dsh-memory-plugin

本地路径会写成 link:<绝对路径>（junction），改完源码重启 DSH 即生效；
GitHub / npm 装的是快照副本，之后改源码不再影响已装的那份。

> install_bundle 自己完成 pnpm 安装与 bundle 选择 —— 不要手工改 profile 的
> package.json / cordis.patch.yml，也不要手工跑 pnpm。
> 该操作要求会话为 danger-full-access，或审批策略为 ask 并由你批准。

从 v1.3.x 升级（包名与条目 id 都变了）

profile 里登记的 bundle 名与 Cordis 条目 id 都已更换，所以要重新装一次：

1. plugin_manager remove_bundle → 移除 @animetrack/memory-plugin（只解除 profile 的
   链接，记忆库文件不动）；
2. plugin_manager install_bundle → 装 dsh-memory-plugin；
3. 重启 DSH（原因见下文「改了代码怎么生效」：旧实例注册的路由/工具在那个进程里
   不会释放）；
4. 若 profile 的 cordis.patch.yml 里还留着 id: animetrack-memory-rules 的旧条目，
   删掉它（新版条目叫 dsh-memory-rules）。

工具名（memory_* / rule_*）、数据格式与工作区解析规则都没有变，
记忆与规则不需要搬运。

从 v1.5.0 升级（数据兼容）

v1.6.0 只新增字段、草稿与工具，不需要迁移脚本（从 v1.4.0 直接升也适用）：

1. 重装当前版本（本地 link 与 GitHub tag 都行）；
2. 重启 DSH（Host 半部改了）；
3. 旧记忆载入时自动补 type / tags / status: "active" / 版本链字段与空时间戳；
4. 新增 drafts / settings 两个顶层字段，默认 autoCapture: false，不会主动调模型；
5. 新增 memory_rollback 工具，面板多一个「待审」页签与自动提炼开关。

发布 / 更新流程

本仓库自身就是包（F:\Projects\dsh-memory-plugin），开发、提交、发版都在这里：

cd F:\Projects\dsh-memory-plugin
git remote add origin https://github.com/AieXile/dsh-memory-plugin.git   # 首次
# 改代码 → 同步提升 package.json 的 version 与 README 的版本说明
git add -A
git commit -m "feat: ..."
git tag v1.6.0
git push origin main --tags

npm 侧（可选）：pnpm pack 先看打包内容，再 pnpm publish。

依赖与兼容

• 零依赖、零 peer：不 import 任何 @deepseek-ai/*。官方兼容性门禁只检查包声明的
  peers，而 profile 里并没有装官方包 —— 声明 peer 会让 pnpm 去 registry 拉整套官方依赖，
  得不偿失。所以本包不参与 DSH 版本门禁，能否运行取决于所用服务是否还在：
  fs / systemPrompt / tools / webServer（必需），sandboxPolicy / agents（可选读取）。
• 无需构建：Host 半部是 ESM 源码；Client 半部是页面直接加载的经典脚本。
• 已在 DSH 0.1.7-rc.2 + pnpm 11.7（Windows）实测。

生效与验证

改了代码怎么生效：必须重启 DSH

实测结论（2026-09-28）：

原因：ctx.webServer.register 的路由不随 Cordis fiber 释放，于是新实例注册同一路径时抛
webserver: duplicate exact route "/dsh-memory/memory-store"（现场写进崩溃日志）；
ctx.tools.register 则按名字保留先注册的那份定义。两者叠加的结果是：旧代码继续服务，
新代码只在提示词段落上生效 —— 看上去「没改对」，其实是没换上去。

所以：改 Host 半部后请重启 DSH。Client 半部（lib/client.js）是经典脚本，刷新页面即可。

验证清单

• 验证 Host：cordis_inspect_query → host / Config / listConfigs，
  entry = include:dsh-memory-rules；status: inactive 表示没激活。
• 验证工具：新会话的模型工具表里应出现 memory_view / memory_search / memory_get 等；
  调用应返回 store 里的内容。用 memory_debug 可以看到「已知根 / 各根的条目数 / 新旧路径 /
  预热事件 / 注入统计（memories N/M, rules N/M, chars）/ 上次落盘错误」。
• 验证注入：新会话的系统提示里应出现 Memory index (N of M; …)，一行一条，带 [类型]、
  摘要和 (m1) 这样的 id；正文不应整段出现。用 memory_get(["m1"]) 应能取回全文。
• 验证路由：GET /dsh-memory/memory-store?sessionId=<会话id> 应返回
  { ok, value, root, storePath, usingLegacy, error, preview }，root 就是该会话的工作区，
  preview 是注入预算的实时统计。
• 验证界面：会话标题栏右侧多出一个圆形图标（与「在应用中打开」同排），
  点开显示「规则 N / 记忆 N / 待审 N」，添加框带类型下拉与标签输入，底部一行
  「下次注入：记忆 X/Y 条 · 规则 A/B 条 · ~C 字符」和存储位置；
  设置页里也多出「记忆与规则」一页。
• 验证提炼：在面板「记忆」页勾选「轮末自动提炼为草稿」，完成一轮 ≥800 字符的对话后，
  「待审」页签应出现草稿；草稿不应出现在注入索引里；点「批准」后进入记忆库，
  若带 supersedes，被替换的条目应显示「归档」并可「回滚」。

不改 DSH 的自测

node test/host-harness.mjs

用真实文件系统 + 假 ctx 直接驱动 lib/host.js 的 apply()，覆盖：工具/段落/路由注册、
无会话时不误读配置根、按会话切根读写、切根不互相覆盖、路由 ?sessionId= 精确命中、
预热事件、坏 JSON 时拒绝写入并保持文件原样、旧路径回退读取与「读旧写新」迁移，
v1.5.0 的类型/标签落盘、索引摘要注入、注入预算与截断提示、按关键词/标签/类型检索、
按 id 取全文、重复记忆拒绝，以及 v1.6.0 的轮末提炼（假 LLM）、草稿不入注入/检索、
批准入队、supersedes 归档与回滚、设置开关。66 项断言，全部通过为退出码 0。

> 本机 profile 里本插件以 link: 安装，改完 Host 半部要重启 DSH 才会载入 v1.6.0；
> 重启后按上面的验证清单看索引行、memory_search / memory_get、待审页签是否出现。

卸载 / 回退

plugin_manager remove_bundle，或从 dsh.profile.bundles 移除该条目。
数据文件不会被删除（已实测：remove_bundle 只解除 profile 的 link，插件目录与 store 都原样保留）。

注意：移除会让提示词注入立刻消失，但本进程内已经注册的路由与工具不会随之释放
（原因见上文），要彻底清干净还是得重启 DSH。

界面与读写通道

两个界面入口都能查看、添加、删除、启用/停用规则与记忆。

读写走的是一条自建同源 HTTP 路由：

GET  /dsh-memory/memory-store?sessionId=<会话id>
-> { ok, value: { memories, rules, drafts, settings }, root, storePath,
usingLegacy, error,
preview: { memoryTotal, memoryShown, ruleTotal, ruleShown, chars } }
POST /dsh-memory/memory-store?sessionId=<会话id>   { action, ...args }
action ∈ state | memoryAdd | memoryRemove | memoryRollback
| draftApprove | draftReject | settings
| ruleAdd | ruleRemove | ruleToggle
memoryAdd 额外接受 type（user/feedback/project/reference）、tags（字符串数组）
与 supersedes（要替换的 active 记忆 id）

sessionId 可以省略：标题栏浮层会带上它（slot 的标准 props 里有），设置页没有会话上下文，
Host 就回退到 pinnedRoot。响应里的 root / storePath 是本次读写的实际位置，界面会显示出来。

为什么用它：常规 Client 插件没有动态插件沙箱私有的 host.call 通道，
而生成的 Remote codec 需要部署的构建工具。Host 半部用 ctx.webServer.register()
自己开一条路由（inject 里已声明 webServer），页面端同源 fetch 即可 ——
不需要任何生成物。这条路由只监听 127.0.0.1，沿用页面自身的会话。

限制

• 浮层位置：锚在图标正下方（.dmp-pop{position:absolute;top:calc(100% + 6px);right:0}），
  所以它随图标移动，不再固定在右上角。
• 路由路径 /dsh-memory/memory-store 是硬编码的；若与别的插件冲突，
  ctx.webServer.register 会抛错（路由是组合级契约），现场写入崩溃日志。
  该注册不随 fiber 释放，所以重新装载本插件（而非重启进程）会稳定复现这条冲突。
• 取数失败时不会静默留空：标题栏图标出现红点，浮层与设置页显示错误条目。
• 记忆库按工作区分文件：换工作区就是另一本记忆库（设计如此，注入也只注入本工作区的）。
• 首次往一个全新工作区写入时，需要 .dsh-memory 目录能被创建；
  否则落盘失败会在工具返回里明说（不会静默丢数据）。
• 旧路径 .animetrack/memory-store.json 只读不写，迁移后它会作为历史文件留在原地；
  确认不再需要时可以手动删除。
• 检索是本地关键词打分，不是语义检索：中文按 bigram、英文按词，同义词/改写查询可能
  搜不到；用 tags 能明显提高命中率。需要全量时 memory_view 仍然列出所有条目。
• 索引有预算：只列出最近 40 条 / 2400 字符；更老的条目不在提示词里，只能靠
  memory_search 找回。这是「固定上下文成本」的代价，也是 v1.5.0 的刻意取舍。
• 自动提炼默认关闭：开启后每个达到 minChars 的轮次可能多一次模型调用；只取直接用户
  消息与助手文本（工具结果不进提示），超长对话截断到 6000 字符。提炼失败只写 lastError，
  不影响主流程。
• 草稿只能由面板批准：没有模型侧的批准工具，避免模型自批自写；supersedes 只回滚一步，
  更长的版本链需要逐次回滚。

视觉（对齐桌面端）

• 标题栏图标完全照搬官方按钮规则：28×28、border-radius:999px、display:grid、
  color:var(--dsw-alias-label-tertiary)、hover 用 --dsw-alias-interactive-bg-hover。
• 浮层与设置页取自应用自带的 Cordis 面板（dsh-client-ui-cordis/lib/client.js）：
  --dsw-specific-menu、--dsw-elevation-prominent、--dsw-menu-backdrop-filter、
  --dsw-alias-border-l4、--dsw-alias-button-ghost-active-fill、--dsw-font-xs-13；
  12px 圆角、.5px 描边、z-index:30，浮层宽 320px。

排查：Host fiber failed

若 plugin_manager list_plugins 里该行为 fiberPhase: "failed"，插件会把现场写入：

<包目录>/.memory-plugin-crash.log         （首选；已 gitignore，随包走）
<系统临时目录>/memory-plugin-crash.log     （退路，%TEMP%）

该文件只为定位问题，排查完可直接删除。

版本变更

v1.6.0：轮末提炼 + 草稿审批 + supersedes 版本链

设计对标 Claude Code auto memory 的「写前可审查」：模型只负责提出候选，人批准后才生效；
同时借鉴 dreaming 的「保留历史、可回滚」，但把整理范围限制在 supersedes 一步，不自动重写旧条。

v1.5.0：索引式注入 + 检索（对标 Claude Code auto memory）

设计直接对标 Claude Code auto memory：MEMORY.md 索引常驻、主题文件按需读、类型沿用
user / feedback / project / reference、写入前先查重（见
Claude Code memory 文档）。
本插件用「JSON 主库 + 按 id 取正文」代替 Claude 的「索引文件 + 主题文件」，保持零依赖与
单文件存储。

v1.4.0：独立命名 + 存储路径迁移

升级到 v1.4.0 需要重装 bundle 并重启 DSH，见上文「从 v1.3.x 升级」。

转换时修掉的三个 bug

旧动态插件里存在、并在转换时修正：

1. 注入用的是 ctx.systemPrompt.context()。它注册的是 runtime context（作为 user 角色的
   来源快照进入模型历史），不是系统提示词。已改为 ctx.systemPrompt.section()。
2. store 只在工具调用时懒加载，而 section 的 text() 是同步的，导致首轮注入为空。
   已改为 session/created / agent/created 预热 + 每次操作前 ensureLoaded()。

转换过程中还踩到并修掉一个 Cordis 契约问题：

3. ctx.tools 必须先声明注入。动态插件沙箱里 ctx.tools 是直接可用的，
   但常规插件会抛 cannot get property "tools" without inject。
   inject 必须列出真正用到的服务：['fs', 'systemPrompt', 'tools', 'webServer']。
   （反过来说，用不到的服务不要写进 inject；sandboxPolicy / agents 是可选读取，
   走 ctx.get 即可。）

v1.3.0 修掉的根目录 bug（影响数据安全）

v1.2.0 在 DSH 启动时就激活，而那一刻还没有任何会话：

1. sandboxPolicy.resolve() 返回的是「无会话回退根」（profile 目录），于是插件读的是
   \.animetrack\memory-store.json（通常不存在），
   内存状态为空；而 loaded 只置一次，之后再也不会读 —— 工作区里已有的记忆和规则
   全部看不见（表现为 memory_view 显示 (none)，面板空白）。
2. 写入时 persist() 重新解析了一次根，解析到会话工作区，于是用内存里的空状态
   覆盖工作区里那份有数据的 store —— 一次 memory_add 或面板上点一下「添加」就会
   丢掉全部既有条目。这是数据丢失级的缺陷。
3. 面板走 HTTP 路由，浏览器请求里没有 initiator，同样解析不到工作区。

修法：目标根按「显式会话 → 当前 initiator → 最近一次主会话根 → 配置根」解析，
每个根一份独立状态、懒载入一次，写入只落在本次状态所属的那个根；
另外载入失败（文件损坏等）时拒绝写入并明说原因，绝不用空状态覆盖现场。

> 复现过这个坑：2026-09-28 修复时工作区 store 里有 3 条记忆 + 3 条规则，
> 而运行中的插件视图是空的 —— 任何一次写入都会清空它们。

与旧动态插件的关系

旧动态插件的两份源码与恢复步骤（dynamic-plugin.host.js / dynamic-plugin.client.js /
dynamic-plugin-restore.md）归档在 docs/legacy/，仅作历史参考、不参与打包；
lib/ 下这份 bundle 才是权威实现。

许可

MIT © 2026 Aelius —— 见 LICENSE。