Relistencode/dsh-recall

dsh-recall

🌏 English · 中文

对话历史回忆插件 —— 给 DeepSeek Harness 的 agent 一座"记忆迷宫"

Version
License
Node
Platform
Offline

AI 再也不会"忘记"你说的话了。

[DeepSeek Harness (DSH) 原生插件:给 agent 一座记忆迷宫——为你们的每一段对话筑起走廊与房间。它记得你们之间发生过的一切:一个决定、一条设定、一次讨论、一句随口提的需求。你问"我们上次说到哪了",它走进迷宫,把当时的对话原样带回,再像聊天一样自然融进回答——你甚至察觉不到它"想了一下"。

对话历史回忆 · 三层检索(字面 / 模糊 / 语义)· 完全本地离线 · 压缩免疫

- 运行中,只在角落里安静地亮起一束扫动的光:

回忆中

- 完成时,不留痕迹:

回忆完成

适合谁使用

- 长会话的重度用户——一场对话跨数天、几百轮,翻不到头
- 写作者 / RP / 酒馆玩家——设定、伏笔、人物关系散落在几个月前的对话里
- 代码与文档维护者——当时拍板的理由、踩过的坑,压缩后只剩一句摘要
- 任何说过"我们上次不是聊过吗"的人——它把原话找回来,而不是让你重讲一遍

反过来:如果你的会话都很短、随时能翻,你大概用不上它——它专为"历史太长、记忆被压缩"的场景而生。

快速开始

dsh plugin --profile web add dsh-recall@0.2.2

一条命令即可:包自带组合补丁(bundle 层),插件与它所需的全文搜索会自动接线。重启 dsh web 即可。没有额外步骤:模型随包预置(完整版约 37MB),首次搜索自动建立索引,随后在后台安静完成语义预热(几分钟,对你的使用无感知)。

也可以在 dsh-extension-hub 的插件管理页 「附加功能」 区块里一键安装/停用/卸载本插件。

从源码安装（git 克隆）：

dsh plugin --profile web add git+https://github.com/Relistencode/dsh-recall.git

仓库已跟踪模型文件（models/model_merged.onnx）与内置推理运行时：git 安装完全离线可用，无构建步骤、无需 allowBuilds 配置。可选依赖 dsh-recall-models 仍会尝试从 npm 拉取；拉取失败时自动改用仓库内模型——两种情形语义层都可用。所有路径经 $DSH_HOME（默认 ~/.dsh）解析，harness 主目录在哪个位置安装效果完全一致。

可选配置

- id: recall
name: dsh-recall
config:
semantic: false   # 关闭语义层(只保留字面 + 模糊,包体更小)
warmup: gentle    # 慢速预热,降低后台 CPU 占用(仅预热期间占用,后续使用 0 占用)

它不是什么

- ❌ 不是上下文工程 —— 不把全部历史硬塞进模型窗口
- ❌ 不是提示词工程 —— 不靠 prompt 让模型"装作记得"
- ❌ 不是 memory 文档系统 —— 不需要手动维护 MEMORY.md / 备忘录
- ✅ 是真正的回忆能力:按需检索对话原始记录——包括已被压缩掉的历史(压缩只是摘要,原文永远可搜)

能力概览

| 能力 | 实现 |
|---|---|
| 三层混合检索 | 字面 / 模糊 / 语义自动合并,覆盖率门控(≥90%)+ 静默降级链 |
| 渐进披露 | 默认轻量粗召回(标题 + 片段 + 事件,约 100–800 tokens);需要时 detail 下钻原文——命中窗口 / 精确原文 / 分页翻阅 |
| 事件聚合 | 同一主题的多次提及合并为事件([startSeq..endSeq],文本块间隔 ≤5)——一次拿到完整片段集,而非零散碎片;事件全文仍是一次 detail 下钻之遥 |
| 自动调用 | agent 自主在需要时回忆(压缩后、缺细节时主动调用),无需用户开口;用户也可主动要求 |
| 压缩锚点 | 监听 compaction/summary,压缩后自动注入一次轻量锚点(摘要 + 关键原文片段,3 轮过期) |
| 作用域控制 | 默认仅当前会话;workspace / all 只在用户明确要求时使用 |
| 压缩免疫 | 索引覆盖全量历史,含 shadowed(压缩遮蔽)事件 |
| 增量索引 | live 会话走 ctx.sessions,持久化走 sessionPersistence,append-only 增量 |
| 后台预热 | worker 线程嵌入(~10 条/秒),host 事件循环零阻塞 |
| 无感知 UI | 「回忆中…」光波 → 「回忆完成」一行,结果不进 UI、由 agent 自然呈现 |
| 完全本地离线 | 零 npm 运行时依赖;无外部模型 API;断网也能用 |

架构

- 回合生命周期(顶部):一次回忆是一条直线——用户提问、agent 调用 recall 工具、三层检索、命中按会话聚合成事件、agent 按需拿到轻量粗召回或下钻窗口。
- 检索层:三条独立的检索通道(字面 / 模糊 / 语义),在覆盖率门控下合并(见三层混合检索)。
- 索引与数据:全部走官方服务(ctx.sessions / ctx.sessionPersistence / ctx.sessionQuery)读取——不解析 .zstd、不碰私有格式。插件自有的 recall-index.db(SQLite)存放模糊索引、向量与 trigram FTS。
- 治理与作用域:作用域红线(默认当前会话)、覆盖率门控、降级链、token 预算都在这一层。
- 自动层:监听 compaction/summary,把每次压缩变成一条轻量锚点——历史被折叠后 agent 依然有方向感。

核心机制

三层混合检索

| 层 | 技术 | 解决 |
|---|---|---|
| 字面 | 官方 FTS5 全文索引 | 精确命中原词 |
| 模糊 | 自建 trigram + 字符二元组索引(零依赖) | 记不清原话、只记得片段、换字漏字 |
| 语义 | 本地 bge-small-zh 模型(int8,24MB 预置) | 换词、意译、"大概意思"也能想起来 |

- 模糊层是主路径(它已覆盖字面层的能力且容错更强);官方 FTS5 是兜底;语义层只在覆盖率 ≥90% 时才参与混合——否则保持沉默,绝不让排序变差。
- 任一层失败都静默降级到下一层——语义 → 模糊 → 字面,永不报错。recall 永远有答案。
- 推理在 worker 线程运行(WASM 放主线程会阻塞 host 事件循环;实测 ~9.6 条/秒零阻塞)。
- 全部本地运行、完全离线——无外部模型 API、无网络。

渐进披露

回忆分两阶段,第二阶段只在 agent 真正需要时触发:

| 阶段 | agent 拿到什么 | 成本 |
|---|---|---|
| 1 — 粗召回(默认) | 会话标题 + 片段 + 同主题事件,分组排序 | 最多 10 个会话约 100–800 tokens |
| 2 — detail 下钻 | 会话命中列表 / 精确原文窗口(readEvent)/ 分页翻阅 | 约 300 tokens/会话(如 ±3 事件窗口) |

实机实测:粗召回比旧版全量上下文窗口省 ~80% token(10 会话命中:2500–3000 → ~600,聚合前)。事件聚合保持同样的纪律——只带片段,事件全文一次下钻之遥——粗召回单次仍在 ~800 tokens 以内。无关内容从不进上下文——而需要时,原文永远一次下钻之遥。

压缩锚点

压缩是记忆最容易丢失的地方——harness 生成摘要,原文被遮蔽。dsh-recall 监听 compaction/summary,立即为被压缩会话注入一条轻量锚点:

- 内容:LLM 摘要 + 最多 3 条关键原文片段(优先用户消息,再取最长文本块)。
- 过期:3 轮组装后自动消失——它是路标,不是拐杖。
- 逃生口:精确原文随时 detail 下钻,永远可还原。
- 实机端到端验证:真实 /compact 后,锚点在下一轮组装中注入,内容正确,3 轮后自动过期。

作用域与隐私

- 默认作用域是仅当前会话——跨会话(workspace)、跨项目(all)只在用户明确要求时使用。
- 呈现层无感知:一声安静的「回忆中…」光波、一行「回忆完成」,别无其他。结果不进 UI——由 agent 自然呈现。
- 数据留在本机:无外部 API、无遥测、无网络。

实测数据

token 收益（v0.2.1 实机）

| 指标 | 结果 |
|---|---|
| 粗召回成本(默认) | 每次调用约 100–800 tokens |
| 旧版全量上下文窗口(10 会话) | 约 2500–3000 tokens——多花 3–4 倍 |
| detail ±3 窗口 | 约 300 tokens/会话 |
| 压缩锚点 | 实机验证:真实 /compact → 锚点下一轮注入,内容正确,3 轮自动过期 |
| 语义预热 | worker 线程 ~10 条/秒,host 事件循环零阻塞 |

检索质量（黄金评测集）

合成 4 会话语料(32 条文档)+ 23 条人工标注查询(精确 / 模糊错字 / 意译 / 跨会话),内存运行、真实模型——复现:node eval/run-golden.mjs:

| 变体 | recall@5 | MRR | nDCG@10 |
|---|---|---|---|
| 仅字面(模拟官方 FTS5) | 0.196 | 0.217 | 0.201 |
| 仅模糊 | 0.587 | 0.652 | 0.579 |
| 仅语义 | 0.533 | 0.609 | 0.529 |
| 混合(生产路径) | 0.696 | 0.761 | 0.687 |

- 混合融合胜过任何单层(比最佳单层 recall@5 高 +19%)——三层各有贡献,没有装饰层。
- 字面层单独最弱(仅精确匹配;unicode61 分词对中文不分词)——印证其兜底定位。
- 模糊层是主路径(胜过语义单层);语义层在意译、换词查询上补召回。
- 覆盖率门控验证:半预热时门控正确回退为仅模糊(0.587 = 纯模糊);强行使用半热语义层在小语料上有小幅增益(0.674)——0.90 门控是为真实长会话保留的保守安全默认,未针对本集调参。
- 已知漏检(已声明的边界):低于语义阈值且无字面重合的完全换词(如"打码" 找 "脱敏")、抽象概念查询(如"方案")。

更新记录

更新记录（点击展开）

npm 首个发布版本为 0.1.0；以下 0.0.x 为开发里程碑。

- 2026-08 — 结果聚合：同一主题的多次提及合并为完整事件（[startSeq..endSeq]，文本块间隔 ≤5；阈值基于真实索引实测——p50 同主题间隔 3、61% ≤5）。粗召回每会话最多返回 3 个事件，token 纪律不变（只带片段；事件全文仍是一次 detail 下钻之遥）。v2 路线图全部完成。
- 2026-08 — 检索质量评测：黄金集（4 会话 / 32 文档 / 23 条人工标注查询）实测生产混合路径 recall@5 0.696 / MRR 0.761 / nDCG@10 0.687——比最佳单层高 +19%。消融确认模糊层为主路径、字面层为兜底；覆盖率门控实机验证（半预热正确回退为仅模糊）。复现：node eval/run-golden.mjs。
- 2026-08 — v0.2.1 实机实测：粗召回约 100–600 tokens，旧版全量上下文窗口 10 会话命中约 2500–3000 tokens（省 ~80%）；detail ±3 原文窗口约 300 tokens/会话。压缩锚点端到端验证：真实 /compact 后，LLM 摘要 + 3 条关键原文片段在下一轮组装中自动注入，3 轮后自动过期。
- 2026-08 — v0.2.1：修复——detail 原文窗口正确提取 assistant/message 的文本块（块数组）并按块类型过滤，助手回复的精确原文在下钻结果中完整可见（实机验证中发现）。
- 2026-08 — v0.2.0：渐进披露 + 手动/自动双模式——recall 默认轻量粗召回（标题+片段，token 大降），新增 detail 参数下钻原文（会话命中列表 / 精确原文窗口 / 分页翻阅）；description 重写：agent 自主调用（压缩后、缺细节时主动回忆，无需用户开口），scope 红线与无感知呈现保留；压缩锚点——压缩后自动注入一次轻量锚点（LLM 摘要 + 关键原文片段，3 轮过期），细节随时可下钻。
- 2026-08 — v0.1.0：正式发布——一条命令安装（dsh.bundle.patch 自动接线插件行并启用全文搜索）；23.9MB 语义模型拆为可选包 dsh-recall-models（--omit=optional 即轻量版）；双语 README + 多语言 UI。
- 2026-08 — v0.0.6：语义层——本地 bge-small-zh（int8，随包预置，完全离线）跑在 worker 线程；字面/模糊/语义三层混合检索，覆盖率 ≥90% 门控 + 静默降级；后台预热（~10 条/秒，host 事件循环零阻塞）。
- 2026-08 — v0.0.4：模糊检索——自建 trigram + 字符二元组索引（零 npm 依赖）：只记得片段、记不清原话、换字漏字也能找到。
- 2026-08 — v0.0.2：recall 工具——官方 FTS5 全文检索全部历史会话（含压缩掉的历史），按会话聚合 + 上下文窗口；作用域控制（默认仅当前会话）；无感知 UI（回忆中… / 回忆完成）。

Roadmap

v1 · 完成 — 三层混合检索:官方 FTS5 字面 / 自建 trigram+bigram 模糊 / 本地 bge embedding 语义;覆盖率门控、后台预热、静默降级链。

v2 · 检索控制
- [x] 两阶段召回(browse/detail 下钻):默认轻量粗召回(标题 + 摘要,约 100–800 tokens),agent 选定会话后按需精读完整上下文——无用信息不进上下文
- [x] 压缩锚点:监听 compaction/summary,压缩后自动注入一次轻量锚点(摘要 + 关键原文片段),原文随时可下钻还原
- [x] 自动调用:agent 自主在需要时调用(压缩后、缺细节时),无需用户开口;用户也可主动要求
- [x] 结果聚合:同一主题的多次提及合并为完整"事件"——文本块间隔 ≤5 的连续命中归并为 [startSeq..endSeq] 事件(阈值基于真实索引实测:p50 同主题间隔 3,61% ≤5);事件全文仍是一次 detail 下钻之遥

v3 · 记忆组织
- 主题聚类:embedding 相似度聚类,按话题归拢呈现
- 记忆沉淀:跨会话提炼设定/决策条目,沉淀为长期记忆
- 远期:评估主题化 / 分层压缩机制——只评估,不改 DSH 核心

已知边界

- 短查询(≤4 字)的语义补位较弱(bge 短文本余弦区分度有限),由模糊层 LIKE 兜底
- 语义排序对完全无字面重合的查询不完全可靠——模糊层始终是主路径,agent 最终判断
- 模型为 int8 量化,语义质量为"够用"级别;可换 fp32 模型(约 4 倍体积)追求极致

开发与测试

node .smoke-recall.mjs      # 单元 + 集成(mock,无需模型)—— 90+ 断言
node .smoke-semantic.mjs    # 真模型集成(需 models/ 就位)

覆盖:tokenizer 对拍(与 transformers.js 逐 token 一致)、索引增量、作用域、混合排序、降级、预热、事件聚合。

模块

| 文件 | 职责 |
|---|---|
| lib/index.js | 工具注册、作用域解析、混合排序、会话与事件聚合、预热调度 |
| lib/fuzzy-index.js | 自建 SQLite 索引(trigram FTS + bigram + 向量表),零 npm 依赖 |
| lib/tokenizer.js | BERT WordPiece 分词器(纯 JS,与官方实现逐 token 对拍一致) |
| lib/semantic.js | Embedder:worker 线程、批量嵌入、懒加载 |
| lib/embed-worker.js | worker 内 WASM 推理 + mask-aware mean pooling + L2 归一 |
| lib/vendor/ | vendored onnxruntime-web(入口 0.8MB + wasm 12MB)+ tokenizer.json |
| models/ | 合并单文件 int8 模型(23MB,发布时拆为 optional 包) |
| lib/client.js | 极简 ToolView(「回忆中…」/「回忆完成」,zh/en 随用户语言) |

发布结构

- dsh-recall —— 主包(代码 + vendor 运行时 + tokenizer)
- dsh-recall-models —— optional 依赖(23MB 模型),npm 默认安装;--omit=optional 即轻量版,缺失自动降级

参考与致谢

- 官方:@deepseek-ai/dsh-session-query(-sqlite)、dsh-tools、dsh-session-persistence
- 模型:BAAI/bge-small-zh-v1.5 (MIT) · onnx-community int8 导出 · onnxruntime-web (MIT)
- 生态参考:dsh-plugin-recall(一期同构的官方 FTS 检索工具)、dsh-mneme(本地语义记忆,混合召回降级链思路)

License

MIT