记忆库 HuaimaoCy/dsh-memory-vault

dsh-memory-vault

Summary

给 DSH 的知识与记忆库插件：把对话沉淀成记忆组，在对话记忆与知识库两种归属之间自由分配，在对话创建处选择知识应用把别处的记忆接进来，并可随时隐藏没用的记忆。模型侧提供 6 个工具与一段常驻记忆索引；人侧是侧边栏的磁贴看板，外观直接由外壳自己的组件与设计令牌构成。

核心概念

| 概念 | 含义 |
| 记忆组 | 记忆的一级容器。一组可以是「项目约定」「排错记录」这类主题，也可以是某个会话的专属容器。 |
| 记忆条目 | 一条具体记忆：标题、正文、类型、标签、可见性。 |
| 归属 | 每条记忆与每个记忆组都归属 conversation（对话记忆，属于产生它的会话）或 knowledge（知识库，跨会话复用）。 |
| 知识应用 | 某个会话「接上」了哪些记忆组。被应用的组的记忆会直接进入该会话的提示，这是跨对话同步记忆的通道。 |
| 隐藏 | 可逆下架。条目、标签、记忆组都保留，但默认不出现在检索、提示与看板里。 |

归属随时可改：模型用 memory_assign，你在看板上把磁贴拖到范围磁贴即可。条目与记忆组的归属可以不一致——把一条记忆从「知识库」提升为「对话记忆」时，它仍留在原记忆组里，并标记为「手动归属」，此后不再随记忆组整体移动。

安装

插件包自带 dsh.bundle 声明，两条安装路径都可用。

路径一：CLI（在 dsh 源码 checkout 根目录执行）
pnpm dsh plugin --profile web add ""

路径二：Web 侧边栏「插件」页 → 安装 → 填入上面的绝对目录路径

安装后 dsh 会把 dsh-memory-vault 追加进 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles。重启 dsh web 后生效（Host 代码是进程内模块，替换已装包不会热生效；客户端文件例外，见「开发」）。

卸载：

pnpm dsh plugin --profile web remove dsh-memory-vault

模型侧

工具

| 工具 | 用途 |
| memory_group | 列出 / 创建 / 修改 / 删除记忆组，整体切换一个组的归属，或用 bind / unbind 把本会话的总结写入绑定到某个组。 |
| memory_write | 写入一条或多条记忆，可一次指定归属。正文支持 Markdown 与 LaTeX。 |
| memory_recall | 关键词检索、按 id 读取、按记忆组 / 归属 / 标签列举；includeHidden 可连隐藏的一起看。 |
| memory_assign | 调整归属、改挂记忆组、设置优先级（0-100）、设置底层 prompt 标记，或把没用的记忆隐藏 / 恢复。 |
| memory_apply | 把知识接进当前会话（跨对话同步记忆）：list / set / reset；groups 按组应用，entries 按单条记忆应用。 |
| memory_curate | AI 整理归类：一次模型调用判断每条记忆是「可复用」还是「单次性」，并给出建议的记忆组；review 只给建议，apply 才落库。 |
| memory_summarize | 把本段对话固化为一记忆。给了 content 就存你写的正文；不给则插件调用模型对未总结的增量做一次总结。 |

常驻记忆索引

插件注册一个 system prompt 段落，列出当前有哪些记忆组、各自归属、组内条目数、优先级与自动总结开关，每组还列出优先级最高的几条记忆标题（见「知识优先级与知识索引」），标出本会话绑定的组，并列出本会话已应用的知识。索引按优先级排序、条数封顶——优先级是人为设定的，所以顺序只在有人调整时变化，写入新记忆不会打乱提示词前缀。

自动总结

- 触发：在 turn/end 处检查会话的未总结增量。未总结消息数 ≥ autoSummaryTurns（默认 6）或字符数 ≥ autoSummaryChars（默认 4000）即触发，且只对绑定了自动总结的记忆组生效。
- 增量：每个会话在 sessions.summarized_seq 记录水位，总结只覆盖水位之后的新对话，并推进水位；重复触发不会重复总结。
- 执行方式：ctx.llm.stream() 一次性调用，provider/model 取该会话已路由的 session.requestHeader().config（可用配置覆盖）。这次调用不写入会话日志、不唤醒空闲 agent、不经过 agent loop。
- 失败处理：失败只记一条警告并放弃本轮，绝不阻塞对话；未总结的内容留到下次触发。总结被截断（max-tokens）时按失败处理，不会把残缺记录写成记忆。
- 手动：memory_summarize 随时可触发同一套流程；full=true 覆盖整个会话可见历史。

自动总结会真实消耗模型额度。想关掉，把 autoSummary 设为 false（仍可手动总结），或把 summarizer 设为 off。

知识：新建对话时选，开始后继续调

记忆选择出现在两个位置，覆盖对话的整个生命周期：

新建对话页（输入框上方）——外壳在空白会话页也会渲染 conversation.input.dock，而会话视图（页签）在空白会话时不渲染，所以这里单独提供一条记忆选择：一行记忆组胶囊，点亮即应用，右侧「恢复默认」清回部署默认。它会读取传入的会话快照，对话一旦开始就自动隐藏，把位置让给下面的页签。

对话开始后（顶部「知识」页签）——与对话、轨迹并列，注册为 conversation.view（order: 20，排在 chat 0 与 trajectory 10 之后）：

- 两个投放区：已应用 与 可应用。记忆组以磁贴呈现，拖动磁贴跨区即应用 / 移除；点击磁贴同样可以切换，所以触屏与键盘用户不会被拖拽挡住。
- 记忆组磁贴显示组名、归属、组内条数；拖进 已应用 即把整组接进本会话。
- 顶部按钮：恢复默认、全部关闭（明确不应用任何知识）、刷新。
- 下方列出实际注入的记忆原文——这就是模型当前能看到的内容，用外壳自己的 Markdown/KaTeX 渲染；达到注入上限时给出提示。

两处读写的是同一份会话状态，所以在新建页选好的组，对话开始后在页签里看到的完全一致。

三种状态彼此独立：应用某几组、明确不应用任何知识、恢复默认。默认（applyByDefault: true）新会话自动应用 applyDefaultGroups（默认 ["知识库"]）；知识库为空时不注入任何内容，所以默认不产生额外开销。注入有上限（applyMaxEntries / applyMaxChars）。

这就是跨对话同步记忆：会话 A 沉淀进知识库的结论，在会话 B 里直接可用。模型侧用 memory_apply 做同一件事。

知识优先级与知识索引

注入预算有限（默认 12 条 / 2400 字），所以"哪条记忆能进"必须由重要性决定，而不是由写入时间决定。

优先级 0-100，组和单条记忆共用一个刻度：

- 在提示索引里，组按优先级排序，组内记忆也按优先级排序——重要的排在前面。
- 在注入计划里，优先级高的先占预算；一条重要但较早的结论不会被后来的新记忆挤掉。
- 会话按条目应用的记忆永远排在最前，优先于任何推断出来的顺序。
- 设置方式：模型用 memory_assign priority=（单条）或 memory_group action=update priority=（整组）；面板里在记忆详情的「优先级」一行点选，或在「记忆组管理」里用 −/+ 按 10 步进。

知识索引是这段提示词里列出的内容：

知识库（2 组）：
- DSH 插件开发 [DSH, 插件开发] · P40 · 组内 16 条 — 为 DSH 开发插件的可复用知识
· [P90] 界面必须用外壳自己的基元与设计令牌
· [P70] Host 半要重启、浏览器半会热更
· …

除组名与条数外，每组还会列出优先级最高的几条记忆标题（indexEntryTitles，默认 5，设 0 关闭）。这样模型不必先检索就能判断某组值不值得读、值不值得接进本会话——索引从"目录"变成"菜单"，这正是提高记忆利用率的关键。

索引末尾还会写明可执行的下一步：需要正文用 memory_recall、接整组用 memory_apply groups=[...]、只接一条用 memory_apply entries=[...]、调整优先级用 memory_assign priority=。

面板侧：磁贴在优先级大于 0 时显示 P90 徽标；「知识」页签里每条被注入的记忆会标明是本会话指定的还是随组注入的，让"为什么它在提示里"一目了然。

底层 prompt、知识数量与 AI 整理归类

底层 prompt：不占配额的那一层

有的记忆是长期有效的基础约定（"所有编码任务必须用 git 留痕"），既不该受"这个会话应用了哪些组"影响，也不该挤占会话的知识配额。把它们标为底层 prompt：

- 写入时就标：memory_write 的 base: true；面板里在记忆详情的「底层 prompt」一行点一下。
- 已存在的记忆：memory_assign 的 base: true/false，可批量。
- 每次对话都会注入，与本次应用了哪些组无关；在提示词里单独成段（### 底层 prompt（N 条 · 不占用本会话的知识配额））。
- 不占知识数量：底层条数由 baseMaxEntries（默认 4）与 baseMaxChars（默认 1200）单独封顶。

可自定义的知识数量

「可用知识数量」决定一个会话最多注入多少条已应用的知识（默认 12）。它现在存在库里，而不是只写在 profile：

- 面板「知识」页签里有 − / + 直接调，改完立即生效，不需要重启。
- 配置里的 applyMaxEntries / applyMaxChars 仍是部署默认值，面板改的是覆盖值；调回默认即恢复。
- 底层 prompt 不计入这个数字——两条预算是分开的。

AI 整理归类

知识库存久了会混进两类东西：值得长期保留的结论，和只对某一次任务成立的细节。插件无法从文本本身分辨，所以提供一次模型调用做判断：

memory_curate action=review # 只看建议，不写入 memory_curate action=apply # 按建议归类

- 判断标准写在提示词里：可复用＝结论、事实、约定、偏好、可复用的步骤或排错结论；单次性＝进度、临时决定、一次性排查、已被后续结论取代的旧状态。不确定时倾向单次性（宁可少收录）。
- 每条给出 verdict、一句话 reason、以及建议的记忆组名（同一批里语义相同的会得到相同名称，便于归并成组）。
- apply 时：可复用的提升到知识库并归入建议的记忆组（组不存在就建）；单次性的改回对话记忆。加 applyPriority: true 可同时把可复用记忆的优先级提到至少 60。
- 整批落库在一个事务内完成，不会出现"整理了一半"的状态。
- 面板「知识」页签里也有「AI 整理（预览）」与「按建议归类」两个按钮；「知识记忆库」看板顶部也有一个「AI 整理」按钮，整理整个知识库，结果就地展开成一张卡片（多少条可复用、多少条单次性、各自理由与建议组），确认后点「按建议归类」才落库。
- 面板调用不需要配置 provider：面板本身不在任何会话里，Host 会记住最近一次 turn 实际使用的 provider/model 并用它发起调用；只有从未有过任何会话时才提示"没有可用的 provider/model"。

这是一次真实的模型调用，会消耗额度；一次最多 50 条，默认 20。

Web 面板

侧边栏出现「知识记忆库」入口。知识库与对话记忆合成为同一块磁贴看板，归属只作为筛选条件存在。

面板直接使用外壳自己的组件与设计令牌（--dsw-）：按钮、胶囊、标签、开关、复选框、输入框、图标都来自 @deepseek-ai/dsh-client-ui-primitives，字体、间距、圆角、明暗主题随之自动一致。

一级：磁贴看板

- 顶行：搜索框、＋ 新建记忆、刷新。
- 筛选行：全部 / 知识库 / 对话记忆 范围磁贴、所有在用标签（带条数）、显示隐藏 开关、分组方式（按记忆组 / 按标签 / 不分组）。
- 每块磁贴：标题（最多两行）、正文纯文本摘要（三行）、标签、记忆组、更新时间；搜索词高亮。被隐藏的磁贴变淡并带「已隐藏」标签，并就地提供「恢复」。
- 看板按所选方式分组，分组可折叠；「记忆组管理」收在默认折叠区（切换自动总结、整体切换归属、删除、新建）。
- 拖拽即操作：把磁贴拖到 知识库 / 对话记忆 磁贴改归属，拖到任意标签磁贴即打上该标签；记忆组卡片同样可拖到范围磁贴整体改归属。

二级：记忆详情（点击任意磁贴进入，Esc 或「返回」退出）

- 预览 / 源码 切换：预览用外壳自己的 Markdown 渲染器排版正文（见下），源码显示原始文本。
- 标签编辑：AI自动总结 / 人工输入 跟随来源、不可移除；其余标签可增删，回车即添加。
- 属性表：归属、记忆组、类型、来源、可见性、创建与更新时间、ID。
- 操作：编辑（改标题、类型、正文）、保存、移入另一归属、移动到其他记忆组、隐藏 / 恢复、删除。

＋ 新建记忆 复用同一套详情界面：选记忆组与归属、用 Markdown 写正文、加标签，保存即以「人工输入」写入。

面板与模型走同一套 Host 侧操作表，所以两边看到的永远是一份数据。

Markdown 与 LaTeX

记忆正文的渲染直接调用外壳自己的 MarkdownText（@deepseek-ai/dsh-client-ui-primitives）：GFM 解析、表格、任务列表、脚注、引用式链接、代码高亮，以及经 KaTeX 排版的 TeX 数学。它和助手消息用的是同一套渲染器与同一套样式，所以排版、字号、深浅色表现完全一致。

- 行内公式写 $...$，独立公式写 $$...$$。
- 不需要插件侧的任何 Markdown/数学依赖：渲染器随外壳一起加载，插件只是调用它。
- 磁贴预览用外壳的 extractMarkdownPlainText 取纯文本（每块磁贴都排版公式会很慢），完整渲染在详情页。

标签

- 两个系统标签由来源自动产生，不能手工指定：AI自动总结（阈值自动总结或 memory_summarize 生成）与 人工输入（模型 memory_write 或你在面板新建）。它们和普通标签一样可检索、可筛选。
- 普通标签由你或模型自由添加。面板里点标签即筛选（可多选，同时满足），工具侧用 memory_recall 的 tag 参数。

隐藏无用记忆

- 入口：详情页的 隐藏 按钮，或模型用 memory_assign 的 hidden 参数。
- 效果：该记忆从检索、提示索引、知识应用注入里全部消失，也不计入标签清单与分组计数。
- 恢复：打开筛选行的 显示隐藏，变淡的磁贴上点「恢复」，或详情页点「恢复」。
- 隐藏与删除的区别：隐藏保留全部内容与标签，随时可逆；删除不可逆。

配置

写进 ~/.dsh/profiles/web/cordis.patch.yml（覆盖插件自带的那一层）：

- id: memory-vault
name: 'dsh-memory-vault'
config:
databasePath: null # 默认 $DSH_HOME/memory-vault/vault.sqlite conversationGroupName: '对话记忆' knowledgeGroupName: '知识库' autoSummary: true # 是否启用阈值自动总结 autoSummaryTurns: 6 # 未总结消息数阈值 autoSummaryChars: 4000 # 未总结字符数阈值 summarizer: 'llm' # 'llm' 调用模型；'off' 只保留手动总结 summarizerProvider: null # 覆盖 provider（默认跟随会话路由） summarizerModel: null # 覆盖 model summarizerMaxTokens: 1600 summarizerTimeoutMs: 120000 injectIndex: true # 是否注入记忆索引段落 injectMaxGroups: 24 # 索引里最多列出的记忆组数 indexEntryTitles: 5 # 每组在索引里列出几条记忆标题；0 关闭 baseMaxEntries: 4 # 底层 prompt 最多注入几条（不占知识数量） baseMaxChars: 1200 # 底层 prompt 的字符预算 transcriptRetention: 400 # 每会话保留的已总结对话行数 searchLimit: 20 # memory_recall 默认返回上限 maxEntryChars: 20000 # 单条记忆正文上限 applyByDefault: true # 新会话是否自动应用默认记忆组
applyDefaultGroups: ['知识库'] # 自动应用哪些组
applyMaxEntries: 12 # 最多把几条记忆注入会话提示 applyMaxChars: 2400 # 注入记忆的字符预算

配置在插件加载时校验，写错会让该行加载失败并指出具体字段，不会静默降级。

数据与存储

- SQLite（node:sqlite，与 DSH 自带的 SQLite 存储后端同一引擎），无需原生编译、无第三方运行时依赖。
- 表：groups、entries（含 hidden）、applications（会话 × 记忆组）、sessions（绑定、总结水位、应用是否显式选择）、summaries、meta。旧库在打开时自动补齐新增列与系统标签。
- 数据在 workspace 之外（默认 $DSH_HOME/memory-vault/），不污染被描述的项目目录。
- 检索用大小写不敏感的字段加权子串匹配（标题 6 / 标签 3 / 正文 2），而不是 FTS5：记忆多为中英混排的短文本，SQLite 自带分词器对两种语言都不合用，加权子串扫描对两者都精确，个人记忆库的规模完全吃得下。

卸载与清理

pnpm dsh plugin --profile web remove dsh-memory-vault
Remove-Item -Recurse "$env:USERPROFILE\.dsh\memory-vault" # 记忆数据（可选）

已知限制

- Host 代码改动需要重启 dsh web：插件不在 profile 目录内，不被 HMR 监视。客户端文件 client.js 例外——HMR 按产物轮询，改完刷新页面即可。只热更新了 client.js 时，面板会自行从 source 推导系统标签并自建标签清单；持久化的系统标签、隐藏与服务端标签筛选要等下一次重启。
- 知识应用会让提示变长：应用的组越多，每次请求的上下文越大；注入有上限（applyMaxEntries / applyMaxChars），超出的部分需要模型自己检索。
- 不做向量检索：没有 embedding，检索是关键词子串匹配。语义相近但用词不同的记忆不会被召回。
- 自动总结按会话触发：多个会话各自独立触发，没有全局配额；长会话高频触发时成本随轮次线性增长，建议按需调大阈值。
- 没有冲突消解与遗忘策略：新记忆不会覆盖或合并旧记忆，隐藏与删除都需要显式操作。
- 只观察插件加载之后发生的对话：安装前的历史不在 transcript 里，full=true 也只看会话当前可见历史。
- 面板外观依赖外壳的设计令牌：宿主主题缺某个令牌时该处样式回退为默认值，不会报错。

开发

独立冒烟测试：用模拟 ctx 驱动工具、优先级、知识索引、底层 prompt、可调配额、AI 整理归类、按条目应用、隐藏、水位总结、面板路由与请求边界，并真实渲染知识页、看板与新建对话记忆条（151 项检查） cd
node tests/smoke.mjs

dsh-memory-vault/
├── index.js Host 侧插件：装配存储、工具、提示词段落、面板路由、会话观察 ├── client.js 浏览器半：侧边栏入口、磁贴看板与详情页、知识应用控件 ├── cordis.patch.yml bundle 层：插入插件行与默认配置 ├── src/ │ ├── config.js 配置默认值与 Standard Schema 校验 │ ├── store.js SQLite 架构、迁移、全部读写操作 │ ├── tools.js 6 个模型工具的定义与结果渲染 │ ├── prompt.js 记忆索引与已应用知识段落 │ ├── summarize.js 一次性模型调用与总结提示词 │ └── http.js 面板与知识应用控件使用的同源 HTTP 路由 └── tests/smoke.mjs 冒烟测试

插件对外只依赖 ctx（Cordis 上下文），不 import 任何 @deepseek-ai/ 运行时模块；浏览器半只从模块表基线里取 react 与 @deepseek-ai/dsh-client-ui-primitives。