dsh-memory-beta

给 DeepSeek Harness（DSH）加一层长期记忆与带来源的知识库召回。

它解决什么问题

DSH 原生的检索是 glob / grep：精确匹配。你想不起来某个决定写在哪个文件、或者只记得"大概是关于存储选型的那段"，它就帮不上忙。而 web_search 查的是外网，不是你的资料。

同时，DSH 每次会话都是新的：你上一周说过的偏好、这个项目定下来的约定，下次对话它不知道。

这个插件补上这两件事：

能力	说明
kb_search	在你自己的工作区里做混合召回，返回带 路径:行号 引用的片段；证据不足时明确说"没找到"，而不是编
memory	跨会话的长期记忆，分用户级（跨所有项目）与项目级（仅本项目），存成你能直接打开改的 Markdown
记忆自动注入	每次请求都把长期记忆带进系统提示词，所以新会话开局就知道你是谁、这个项目的约定是什么

设计上刻意的三个选择

1. 记忆是人类可读的 Markdown，不是数据库。

<!-- dsh-memory:project v1 -->
# 项目长期记忆：my-project

- `决定.存储` 记忆载体用 Markdown + JSON，不用 SQLite：必须可人工审阅与 git 管理。 <!-- @2026-10-09 src=model -->
- `技术栈` 纯 ESM JavaScript，零运行时依赖。 <!-- @2026-10-09 src=model -->

<!-- user-notes -->
（这里是你自己的自留地，插件原样保留、不解析、不重排）

理由：记忆系统最怕的不是"存不下"，而是模型偷偷记错了还一路传下去。Markdown 让你用记事本就能纠正一条，不需要工具、不需要 SQL。它也天然进 git，团队可以共享项目级记忆。

2. 索引不是事实源。 原始文档始终在工作区里，索引只是它的可检索投影。删掉索引不丢任何信息，只是下次检索前要重建。索引里也没有你的原文副本之外的任何东西。

3. 零运行时依赖。 不引入 node:sqlite、不上原生模块、不下载模型。装完即用，这也是它能跨平台的原因。

长什么样

下面是一次真实调用的输出（示例工作区里放了两个 Markdown 文件，没有任何加工）。

问"部署成本怎么考虑"，它给出两条来自不同文件的证据，每条都能回到原文的 路径:行号：

检索：部署成本怎么考虑

结果：找到以下相关片段。回答时请标注引用的来源（形如 `路径:行号`）。

--- 片段 ---
[1] docs/选型记录.md:9-10
    章节：存储层选型记录 › 备选与被否决的方案
    【docs/选型记录.md › 存储层选型记录 › 备选与被否决的方案】
    我们否决了 Postgres（需要独立服务，单机部署成本过高），
    也否决了内存索引（重启后需要重建，冷启动不可接受）。

[2] docs/部署.md:5-6
    章节：部署说明 › 发布流程
    【docs/部署.md › 部署说明 › 发布流程】
    打 tag 后由 GitHub Actions 自动发布到 npm，使用 OIDC trusted publishing，
    不需要长期 token。

问一个资料里没有的问题时，它不会编，而是明确告诉你没找到，并约束模型不要用训练知识去补：

检索：缓存是怎么失效的

结果：工作区知识库里没有找到与查询相关的内容。

请直接告诉用户"在你给我的资料里没找到"，并说明你检索的是什么范围。
不要用你自己的训练知识把这个空缺补上——用户此刻要的是他资料的答案，不是通用知识。

这就是这个插件的重点：不是"总能给出答案"，而是"答案能回到原文，回不去就说明白"。

安装

插件通过 DSH 自带的插件管理器安装。装完如果没看到效果，先重启一次客户端——新版工具通常热生效，但提示词注入部分在部分场景需要重启。

桌面客户端（Electron）

桌面端读的是 desktop profile，而 dsh plugin 命令行按设计拒绝操作它。正确方式是在桌面客户端的会话里直接说：

把 dsh-memory-beta 装上

它会调用内置的 plugin_manager 工具，用客户端自带的 pnpm 在当前 profile 里装好并写入 dsh.profile.bundles。

Web（dsh web）

# 从 GitHub 安装
dsh plugin --profile web add github:Chang-An2002/dsh-memory-beta

# 从本地目录安装（开发时用，改动立即生效）
dsh plugin --profile web add link:D:\path\to\dsh-memory-beta

安装后重启 dsh web 并刷新浏览器。

手动安装（不依赖插件管理器）

在 profile 目录（~/.dsh/profiles/<profile>/）里：

pnpm add github:Chang-An2002/dsh-memory-beta

然后在该 profile 的 package.json 的 dsh.profile.bundles 数组里加上 "dsh-memory-beta"。

使用

五个工具

工具	什么时候用
kb_index	想让索引更新时手动跑一次。不是必须的前置步骤——kb_search 会自己检测过期并重建。增量更新，重复跑很便宜
kb_search	答案应该来自你自己的资料时。返回带引用的片段，或明确告诉你"没找到"
kb_stats	想知道"它到底索引了什么文件"、以及索引有没有过期时。只报告、不改动索引，所以回答依据可以原样核对
memory	记下稳定成立的事：action 取 read/write/forget，scope 取 user/project
memory_search	记忆条数变多后按内容检索

典型的一轮对话：

你：这个项目为什么不用 SQLite 存记忆？
（模型调用 kb_search）
模型：按 docs/DESIGN.md:132-150 的记录，有三个理由：可审阅、git 友好、零依赖……

如果资料里确实没有：

你：这个项目支持 PostgreSQL 吗？
模型：我在你的资料里没找到相关内容（检索范围：工作区已索引文档）。

注意最后这一句：插件会明确指示模型不要用训练知识把这个空缺补上。因为此刻你要的是你资料的答案，不是通用知识。

索引不会悄悄过期

改了文档却忘了重新索引，检索到的就是旧内容——而且它不会报错，是静默答错。这是知识库类工具最危险的失败模式。

所以每次 kb_search 之前会先做一次过期检测（实测：55 个文件的工作区约 0.5 ms，见下），发现变化就先重建索引再检索，并在结果里如实写明：

注意：工作区自上次索引后有变化（改动 1 个）——docs/deploy.md。
已自动重新索引后再回答。

检索：插件怎么安装
...

检测分两级，为的是既不漏也不误报：

1. 先比文件的修改时间（mtime）——绝大多数文件在这一步就排除了，不读内容；
2. 只有时间变了的文件才重新读盘算内容指纹。指纹一致就判定为没变。

第 2 步不能省。git checkout、切换分支、格式化保存、复制文件都会改 mtime 但内容没变；只看时间的话，这些操作全会被误报成"过期"，然后触发一次毫无必要的大规模重建。

如果不想让插件自动碰索引，把它关掉：config: { autoReindex: false }。此时检索仍会提醒你索引过期，但不会自己动手。

kb_stats 也做同样的检测，但不重建。 两个工具对"索引新不新鲜"必须给出一致结论——一个报"已索引 12 个文件"、另一个报"有 3 个文件变了"，用户就没法相信任何一个数字。但 kb_stats 的定位是"核对依据"的只读工具，偷偷改掉它正在报告的东西会让人没法信任这份报告，所以它只如实说明：

注意：工作区自上次索引后有变化（改动 1 个）——docs/deploy.md。
下面报告的是索引里的旧数据。

工作区：...

换句话说：过期检测两边一致，重新索引只发生在检索路径上。

配置

写在 profile 的 cordis.patch.yml 里：

- id: dsh-memory-beta
  name: dsh-memory-beta
  config:
    maxPassages: 6          # kb_search 默认返回的片段数
    injectMemory: true      # 是否把长期记忆注入系统提示词
    maxInjectedEntries: 40  # 注入的条数上限
    maxInjectedChars: 3000  # 注入的字符预算
    autoReindex: true       # 检索前发现索引过期时，是否自动重建（关掉则只提醒）

数据存在哪

全部在 $DSH_HOME（默认 ~/.dsh）之下，不放在插件目录里（插件目录可能被包管理器清理）：

~/.dsh/memory/
  user.longterm.md                                    用户级长期记忆（跨所有项目）
  projects/<工作区键>.longterm.md                      项目级长期记忆
  index/<工作区键>.json                                工作区检索索引（可随时删除重建）
  synonyms.json                                       同义说法表（可选，你自己维护）

<工作区键> 形如 my-project--f07f7b24：前面是路径摘要（方便你认出是哪个项目），后面是短哈希（保证唯一）。它会剥掉你的家目录前缀，所以键里不会出现你的用户名。

工作区索引只包含 DSH 配置里的当前工作区，不会扫到别处。

同义说法表（可选，但收益最大）

词面匹配最典型的失败不是"排得不好"，而是根本没有共同词：你问"这个课题实验设计怎么做"，文档里写的是"拟采取的研究方法"——两边一个字都不重合，检索必然为空。

解决办法是这个文件（默认不存在，需要你自己建）：

{
  "groups": [
    ["实验设计", "技术方案", "研究方法", "试验方案"],
    ["缓存", "快取", "cache"],
    ["部署", "上线", "发布"]
  ]
}

一个数组 = 一组"说的是同一件事"的说法。问法里出现组内任何一个，就把同组其它说法作为额外问法再检索一遍，结果按名次融合。

三件事值得说明：

• 只追加，不替换。 你原来的问法始终保留；扩展问法只是额外一路，融合时权重只有一半。所以表写错的最坏后果是"多了一路没用甚至略偏的结果"，而不是把原来的好结果挤掉。
• 改完立即生效，不需要重建索引（因为它是查询扩展，不是改索引）。
• 表坏了不影响检索：JSON 写错、格式不对，插件会退回"没有同义表"并在日志里说明原因，检索照常。

这份表是人手维护的，不自动学习。自动学出来的关联词一旦错了，检索会静默给出不相关的结果；手写的表结果确定、可审阅。

这个功能的优先级来自实测：在参考实现（ArkSeek）的对照实验里，加同义表让固定集过门槛从 7/15 提到 14/15，是所有尝试里单点收益最大的一项。细节见 MIGRATION.md 第 4 节。

隐私边界

这是你该知道清楚的几件事：

• 不上传任何东西。 没有网络请求，没有遥测，"记忆"全部是本机文件。
• 不索引的内容：node_modules、.git、dist/build/target 等构建目录、常见锁文件、超过 512 KB 的文件、二进制文件（含 NUL 字节或非 UTF-8）、符号链接（避免一个软链把工作区之外的文件悄悄纳入索引）。
• 不参与检索：工作区里的 .dsh-memory/ 目录（团队共享记忆用）本身不被索引，避免"记忆污染知识库"。
• 可审计：kb_stats 会列出所有被索引的文件；索引文件是纯 JSON，你可以直接打开看。
• 插件不会自己删你的记忆。删除只发生在你或模型显式调用 memory action=forget 时，且会回报删掉了什么。

已知限制

我宁可写清楚，也不想让你踩到才发现。

检索质量

• 目前只有 BM25 稀疏召回，没有语义召回。 这意味着：你问"怎么找出基因组之间的差异"，而文档标题写的是"变异检测流程"——两者没有共同词，召回不到。这是词面匹配的固有限制。
  • 缓解手段是同义说法表（见上面那节）：把这类"同一件事的不同说法"手写进去，就能救回一部分。实测在参考实现上这一项收益最大（7/15 → 14/15），但它需要你维护，不写就没有。
  • 代码和文档场景下这个限制没有听起来那么严重：标识符、路径、报错串都是精确 token，正是 BM25 的甜点区。
  • 架构上已经为语义召回留好位置：融合层从第一天就是多路 RRF，加入 embedding 是"多一路输入"，不需要重写编排。
• 没有精排（rerank）。 参考实现用的本地 cross-encoder 需要约 5 GB 常驻内存、单次精排 8–17 秒，与"装完即用"的定位冲突。
• 中文分词是字符二元组 + 停用词表，不是真正的中文分词器。这是为避免引入 jieba 之类的依赖而做的取舍，在多数技术文档上够用，但对长句和口语化表达不如专业分词。
• 单次检索的延迟随语料规模线性增长（内存 BM25，每次查询全量打分）。几千到几万片段是亚秒级；更大的语料需要换倒排索引。

记忆

• 记忆不会自动整理。 插件不会自己去重、合并、判断矛盾，也不会主动忘掉过时的条目。同一件事用不同 key 记两次就是两条。目前靠模型在写入前先读一次，以及你自己的判断。
• src=model / src=human 只是标记，还没影响行为。 我区分了来源，但还没有"模型推断的内容降权"之类的机制。
• 注入有预算：默认最多 40 条、3000 字符。超出时不会静默丢弃——装不下的条目会列出键名（"另有 3 条未展开：部署偏好、缓存策略…"），让模型知道存在什么、有没有必要用 memory_search 去取。有近期对话时，超预算的部分会按话题相关度择优展开。
• 模型可能记错东西。 这是本设计里最重要的一条：请把记忆文件当成"待审阅的笔记"而不是"事实"。定期的做法是打开 ~/.dsh/memory/user.longterm.md 看一眼，用 memory action=forget 或直接编辑文件纠正。

工程

• 团队共享记忆尚未实现。 设计上计划在工作区放 .dsh-memory/project.md 供提交进 git，插件发现即读取且不自动写入（把"可提交"与"只该自己看"从物理上分开）。目前这部分还没做，记忆只存在 ~/.dsh 下。
• 索引过期是"检索时检测"，不是"文件一变就重建"。 没有文件监听：变化要等到下一次 kb_search 才会被发现（并自动重建）。所以单次检索的结果按检索那一刻的工作区算，这点是准的；但如果你在两次检索之间改了文档却没有再检索，插件不会主动知道。检测策略见上面「索引不会悄悄过期」。
• 自动重建会改写索引文件。它不动你的文档，索引本身也只是可重建的派生物；但索引默认放在 ~/.dsh 下，一般不在同步盘里，所以通常不会带来额外同步流量。
• 索引在内存里全量驻留。语料很大时（十万级片段）启动与内存开销会明显上升。
• 跨平台：单元测试在 CI 里同时跑 ubuntu 与 windows（Node 20 / 24 两档）， 所以测试本身不是 Windows 专属。但插件在真实 DSH 实例里只在 Windows 验证过， Linux / macOS 上的实际行为未实测。
• kb_search 一次只处理一个查询。 复合问题（"A 和 B 分别是什么关系"）目前靠模型自己拆成多次调用，插件内置的查询分解与多跳编排没有移植——参考实现那部分逻辑（query_planner.py、wiki_router.py）深度耦合于某个特定机器人的领域（Wiki 路由、群聊身份），直接搬过来只会带来负担。这是有意的删减，不是遗漏。

什么时候它可能反而更糟

这个插件的目标是"装上之后净收益为正，哪怕很小"。所以这一节列的是它可能在哪些地方让你更难受，以及对应的限制措施。 如果你在下面列的场景里，可以关掉对应功能，而不是忍着。

1. 首次检索会构建索引，可能明显变慢

kb_search 发现没有索引（或索引过期）会自动建。这件事在你第一次问、或者改完文档后再问时会发生：

工作区规模	索引文件	首次/重建	之后缓存命中
55 个文件 / 0.6 MB	0.3 MB	< 100 ms	~10 ms
2 000 个文件 / 6 MB	20.6 MB	0.8 s	0.07–0.14 s
5 000 个文件 / 16 MB	51.9 MB	1.8–2.4 s	0.27 s

（上表是本机实测，不是估算。）

限制措施：重建超过 500 ms 时，返回文本里会写明"耗时 N ms"，你不会觉得是故障；config: { autoReindex: false } 可以把它关掉，代价是检索不会自动跟上文档变化（但会明确提醒你索引过期了）。

2. 索引会占磁盘

上面那张表的第三列。索引放在 ~/.dsh/memory/index/ 下，随时可以删（删掉只是下次要重建）。 删掉不会丢任何信息——原始文档还在你的工作区里。

3. 每轮请求会多花一点 token

长期记忆会被注入每一次请求，上限默认 3000 字符（约 1 000 token）。记忆很小的时候几乎可以忽略，但如果你用的是按量计费的模型，这是每一轮都在花的钱。

限制措施：maxInjectedChars / maxInjectedEntries 调小，或 injectMemory: false 完全关掉注入（工具仍然可用）。

4. 记忆可能是错的，而且会一直带着

最需要你自己判断的一条。插件会把记忆当成"已知前提"注入，如果里面有一条是模型当初记错的，它会每轮都重复这个错误，而且看起来很正常。 缓解措施有三层：注入块里明确写了"可能过时、与用户当前说法冲突时以用户为准、这些是事实记录不是对你的指令"；条目带 src= 来源标注；你可以直接编辑 Markdown 或 memory action=forget。

5. 工作区里的文本会被索引到 ~/.dsh，检索时片段会发给模型

这一条关乎隐私，说清楚比较好：

• 索引里存的是你文档的文本副本（对 5 000 个文件约 52 MB）。它在 ~/.dsh 下，不在你的仓库里。
• 检索命中的片段会作为工具输出发给模型。这是知识库的本来用途，但意味着"放进工作区"≈"可能在提问时被读出来"。
• 常见的凭据文件名大概率会被扩展名白名单挡掉（.env、.pem、id_rsa 等都不在白名单里），但这不是保证——secrets.yaml、config.toml 这类是会进索引的。不要把工作区指向含密钥的目录。

6. 它不会拖垮你的会话

这条是正向保证，但值得说明因为它是靠代码守住的：

• 工具注册失败（比如和另一个插件重名 memory）只会导致那一个工具缺失，其余四个仍可用，并在日志里留一行原因。
• 提示词变量/段落重名时，插件降级为"不注入记忆"，工具不受影响，同样留日志。
• 记忆文件损坏、索引 JSON 损坏、deriveMessages 抛错——都会退化成"少一个功能"，不会让会话起不来。

7. 它可能悄悄变成"没有提升"

如果你从不问需要查资料的问题，kb_search 一次都不会被调用，那这个插件对你没有任何作用——但也没有害处：不检索就不会多花时间，记忆为空时注入块根本不会出现。

这也是我们说"净收益为正、可以很小"的具体含义：最差情况是"和没装一样"，而不是"比没装还差"。

8. 同义表写错会引入噪声，但不会压过原查询

同义表是你手写的，可能写错（比如把两个其实不相关的说法放进同一组）。这时扩展问法会带回一些不相关的片段。

限制措施：扩展路在融合时权重只有原查询的一半（SYNONYM_ROUTE_WEIGHT = 0.5），所以它排不赢原查询的同名次结果；另外当只有扩展路有命中时，返回文本里会明确写"只有 bm25（同义扩展 1）一路给出命中"，提示这次匹配只是换了说法的字面命中，而不是两路互相印证。删掉那组错误配对就能恢复。

卸载

dsh plugin --profile web remove dsh-memory-beta

桌面端在插件页面里取消选择，或让 DSH 自己卸载。

记忆文件不会被自动删除——它们是你的数据。要一并清理：

rm -rf ~/.dsh/memory

开发

git clone https://github.com/Chang-An2002/dsh-memory-beta
cd dsh-memory-beta
npm test                    # 187 项，零依赖，不需要 npm install
node scripts/check-pack.mjs # 校验 npm 打包内容（白名单少写一项时不会报错，只会少文件）

测试按层组织，每层可独立运行：

文件	覆盖
test/retrieval.test.js	分词、BM25、RRF 融合
test/chunking.test.js	结构感知切分、标题路径、行号
test/memory.test.js	路径与工作区键、记忆文件读写、与人工编辑共存
test/evidence.test.js	充分性判定、预算裁剪、来源标注
test/index.test.js	文件发现、增量索引、过期检测、检索编排、引用可核对
test/plugin.test.js	工具注册、宿主契约（Config schema / 参数编译 / 段落 order）、自动重索引、记忆注入、失败隔离
test/synonyms.test.js	同义表的解析容错、扩展边界、缓存失效、融合权重

CI 在 ubuntu 与 windows 上跑 Node 20 / 24 两档（.github/workflows/test.yml）。

npm test 故意不带路径（node --test，不是 node --test test/）。 Node 20 会把目录参数当"要扫描的目录"，Node 24 则把它当"要加载的模块入口"， 于是 node --test test/ 在 Node 24 上报 Cannot find module .../test。 不带参数时两版都用默认发现规则（**/*.test.js），行为一致。 这个差异是 CI 抓到的——本地只在 Node 24 上逐文件跑，发现不了。

单元测试用的是假桩宿主，它测不出"宿主怎么读我们的导出"这类契约问题。改动 Config、inject、output、parameters、提示词段落或变量名时，务必也启动一次真实 DSH 验证——这个插件曾经在 62 项自检全绿的情况下一次都没能激活。 具体步骤、预期输出与判据见 VERIFICATION.md，配套脚本在 scripts/real-kernel/。CI 里的四个组合只证明测试跨平台，不替代真机验证。

架构与移植依据见 DESIGN.md，逐模块的移植对照见 MIGRATION.md，版本变更见 CHANGELOG.md。

这个插件的来路

它的检索与记忆设计来自另一个项目 ArkSeek（Python，QQ 机器人，四层记忆 + 混合召回 + 可靠性兜底），那个项目在真实语料和真实群聊上迭代过多轮。这里移植的是它的设计判断，不是代码：运行时用零依赖 JavaScript 重写，因为参考实现依赖约 6.6 GB 的模型、需要 8 GB 内存、单次精排 8–17 秒——一个"装完即用"的插件不该有这种前置条件。

哪些判断被继承、哪些被有意砍掉、依据是什么，都记在 DESIGN.md 里。

逐模块的对应关系（哪个文件对应 ArkSeek 的哪个模块、转移了什么、改了什么、为什么砍， 以及 ArkSeek 侧的具体出处与实测数字）单独记在 MIGRATION.md。 那份文档也记录了一处我们自己的更正：早先被当成"最有效杠杆"的章节标题路径， 核对原始实验数据后发现单独使用时反而让固定集变差。

许可

MIT