语义记忆检索 Jackbessaliuz/dsh-memory-semantic

dsh-memory-semantic

给 meow-memory 记忆系统加一层语义检索：让「记过的」变成「想得起来的」。

一个 DeepSeek Harness（DSH）插件。它只读记忆库，在本机建向量索引，给 AI 补上三件事：语义检索、记忆图谱、对话原文召回。

📌 图谱来源：本项目的轮次记忆数据模型、召回算法与 surface-takeover range 语义移植自 graph-memory（MIT License，© 2026 adoresever）。详见文末 Credits。

🧠 记忆是怎么运转的

┌─ 存 ──────────────────────────────────────────────────────────┐ │ │ │ 书架 A：知识层（meow-memory） 书架 B：原文层（本插件） │ │ ────────────────────────── ───────────────────────── │ │ 书 = AI 写的读书笔记 书 = 原始对话本身 │ │ （soul/user/rules/fact/ （一字不差的问答） │ │ lesson/topic/project） ＋ 每轮一句摘要当书脊 │ │ 谁写 = AI 主动写 谁写 = 聊完一轮自己长一条 │ │ 管理员 = dream（整理/合并/归档） 管理员 = 无（只增不改） │ │ 定位 = "我知道什么" 定位 = "当初具体怎么说的" │ │ │ └───────────────────────────────────────────────────────────────┘ │ ┌─ 找 ──────────────────────────┴───────────────────────────────┐ │ 查书架 A：memory_search （关键词） │ │ memory_semantic （向量＋关键词融合，换说法也找得到）│ │ memory_graph （关系网：谁重要、谁和谁一类） │ │ 查书架 B：recall_turns （翻回当时的原话） │ └───────────────────────────────────────────────────────────────┘ │ ┌─ 递（主动送到眼前）───────────┴───────────────────────────────┐ │ ① 首轮长期记忆注入：会话开头把 soul / user / 全局规则递过来 │ │ ② 动作触发：你一改配置、动数据，相关红线与教训自动附上 │ │ ③ 跨会话接力：新会话说"继续"，上一个会话的尾巴接进来 │ │ ④ 召回注入：每轮按你的问题，从书架 B 找原文递过来 │ └───────────────────────────────────────────────────────────────┘

一句话：meow-memory 管「存」，本插件管「找」和「递」。

一句话：它是什么

meow-memory 负责「记住」，dsh-memory-semantic 负责「想起来」。

打个比方：meow-memory 是书架——把你说过的话、做过的事、定过的规矩，分门别类放进格子。
dsh-memory-semantic 是图书管理员——它不往书架上放任何东西，但你说「我上次提的那个关于时区的事」，它能把那本书抽出来递给你，哪怕那本书的标题里根本没有「时区」两个字。

两个插件怎么配合

| 你能看到的现象 | 谁在干活 |
| AI 记住你说过的话，换个会话还记得 | meow-memory（写入、分层、整理） |
| AI 换个说法也找得到那条记忆 | dsh-memory-semantic（语义检索） |
| AI 知道哪些记忆是重点、哪些是一类 | dsh-memory-semantic（记忆图谱） |
| 长对话被折叠后，还能翻回原话 | dsh-memory-semantic（对话原文召回） |

装一个能用，装两个才好用。 只装 meow-memory：记忆在，但你换个说法它就找不到。
只装本插件：它没有东西可找（记忆库是空的）。

组合式 vs 只用其中一个：有实测数据

⚠️ 口径：本机 1283 轮真实对话库 ＋ 64 条人工改写查询（换词／同义、刻意避开原文里的独特词）—— 这是最接近「你换个说法问」的场景。

| 路线 | Recall@1 | Recall@3 | Recall@5 | 彻底找不到 |
| 只用关键词（BM25） | 46.9% | 59.4% | 64.1% | 23/64 |
| 只用语义（向量） | 32.8% | 42.2% | 48.4% | 33/64 |
| 两者融合（本项目） | 54.7% | 62.5% | 68.8% | 20/64 |

怎么读：

- 单用语义的绝对成绩低于单用关键词（32.8% vs 46.9%）—— 语义不是「更强的检索」，它是另一种视角：换词、同义、只记大意时它接得住；而专有名词与精确术语仍是关键词不可替代的强项。
- 融合同时超过两者（54.7%）—— 这才是它存在的理由。它不是「两边取平均」，而是哪边强就用哪边。
- 「彻底找不到」从 23 条降到 20 条：融合最大的收益不是「排得更准」，而是少漏——对「给 AI 提供上下文」这个用途，漏掉的代价远大于排第二（排第二多读一条就捞到了，漏掉则完全断片）。

另一组数据（同一库，只换索引文本）：我们曾把语义索引建在抽取摘要上，语义路线 Recall@1 只有 6.3% （彻底找不到 57/64）—— 因为摘要是第三人称的「本轮纪要」，和用户第一人称的提问不在同一个语义空间。
改回原文后升到 32.8%。

结论：索引文本比融合策略重要得多。喂进去的原料不对，后面怎么调排序都是在抢救。

还有一组（历史数据，口径不同）：把原文截成 60 字再建索引，融合路线 Recall@1 变化 ≈0% ——说明「变短」本身不致命，致命的是「换人称、换视角」。

另一组对照（同库、原文片段查询）：拿原文的具体片段去查时，三者分别是 关键词 98.2% / 语义 100% / 融合 100%——这个场景没有区分度（都对），但也说明融合没有牺牲关键词的强项。

为什么不做成「直接装现成的图谱插件」？

有人会问：已经有做类似事情的开源项目（比如 graph-memory），为什么不直接装它？

因为直接装会让你的记忆分裂成两套：

| | 直接装 graph-memory | 本插件（移植设计） |
| 记忆存在哪 | 它自建一套 gm_ 库（TASK/SKILL/EVENT ＋ 轮次） | 同一份 meow-memory 记忆库之上 |
| 与 meow-memory 的关系 | 并行、互不读写 | 只读复用，整理／索引／图谱全认 |
| 语义检索靠什么 | 需要外部 API key（没 key 就降级成纯关键词） | 本机 Ollama，零成本、数据不出门 |
| 能不能自己改 | 是 npm 包，改行为就得 fork、背更新债 | 自己的源码，改一行是一行 |
| 上游大改怎么办 | 只能被动跟（它 1.5.8→1.6 把概念图整个换掉了） | 只移植设计，能力长在自己的插件上 |

一句话：那会让 AI 同时拥有两个互不相认的记忆库。
而对一个「想要被长久记住」的 AI 来说，记忆必须唯一、可带走、跨模型连续——所以本项目的做法是移植设计（算法与数据模型），把能力长在同一份记忆上。
这也正是要在 Credits 里郑重署名上游的原因。

顺带说清楚一件事：市场上还有 dsh-engram（记忆宫殿式跨会话记忆）、dsh-memoria（向量+图后端）这类方案，它们和本项目不冲突，也不必二选一——那些是「完整的记忆系统」（自己存、自己管、自己整理），本项目是「读层」（在既有的存之上做检索、图谱与原文召回）。
记忆本来就可以分成「存」和「读」两半：你已经有 meow-memory 在管「存」，本插件就补「读」。

它解决什么问题

关键词检索有三个绕不过去的坎：

1. 换个说法就找不到。 记忆里写的是「thresholdRatio 调低」，你搜「上下文太满」——字面对不上，命中为零。
2. 不知道哪条最重要。 记忆多了以后，「哪些是枢纽、哪些是细枝末节」靠人肉翻不动。
3. 摘要之后细节就没了。 长对话被压缩成摘要，等到真需要原话时已经翻不回去。

本插件在同一份记忆库上补这三件事，且不改变原系统。

功能

三个工具

| 工具 | 作用 |
| memory_semantic | 语义检索记忆：本地向量 + BM25，RRF 融合后返回最相关条目 |
| memory_graph | 记忆图谱：全局重要性（加权 PageRank）、知识域（社区）、相似邻居 |
| recall_turns | 对话原文检索：按问题找回更早对话里的逐字问答 |

几条自动接线

- 跨会话接力：新会话开场说「继续」时，自动把上一个会话的尾巴接进来——不必手打上下文。
- 动作触发注入：命中特定动作（如改配置、动数据）时，自动检索相关红线与教训并附加到下一次请求。
- 召回注入：每轮按你的问题，从对话原文里找出相关片段，插在当前提问之前（标注为历史参考）。
- 注入去重：同一条记忆在一次会话里只注入一次，避免反复灌水。
- 上下文组装：按体积上限把召回的原文插在当前提问之前，不打断对话流。

设置页

安装后会在 DSH 设置里多出一页「语义记忆」，可以看到：向量引擎是否可用、索引条数、轮次库规模、图谱规模、当前生效的检索与图谱参数，以及宿主压缩档位的建议值。

其中 Ollama 自动拉起开关可以在设置页直接切换，即时生效（写入插件自己的 ~/.dsh/dsh-memory-semantic.runtime.json，不触碰任何宿主配置）。

它是怎么工作的（想深入了解再看）

书架 B（轮次记忆）是怎么长出来的

每聊完一轮，插件会在后台做四件事，全程不影响前台对话：

1. 登记：把这一轮写进「待抽取队列」（落库）。
2. 抽取：调用模型，把这一轮压成一句摘要 + 结果状态 + 若干组「主体—关系—客体」三元组。
3. 入库：写进 <工作区>/.dsh-semantic/turns.db，并算一份向量。
4. 标记：更新队列状态与「这个会话完成了第几轮」的水位。

为什么要队列和水位：早期版本把这两样放在内存里，宿主一重启就清空——实测因此单会话丢过 20 轮。现在它们都落库了，重启后会自动把没抽完的轮次从会话日志里捡回来续抽。
配套还有三重保护：

- 可重试的错误（429、5xx）→ 指数退避重试，连失三次转「隔离」，不再自动花钱；
- 需要改配置的错误（401/403/404）→ 暂停 10 分钟再试（因为再试也没用）；
- 400/422 不暂停 → 它可能只是一个坏 prompt 引起的，不能让它禁用后续不相关的调用。

检索是怎么融合的

三条路线各出一张榜单，按名次融合（RRF）：

| 路线 | 强项 | 弱项 |
| 词法（BM25） | 专有名词、精确术语、原文片段 | 换个说法就找不到 |
| 语义（向量） | 换词、同义、只记大意 | 短查询抓不准；不懂专有名词 |
| 词项图（PageRank） | 谁连接多、谁是一类 | 不参与主序，只做补充 |

门控：词法路线「够多且够自信」时（前两名分差够大）才让它主导；否则交给加权融合，让语义补位。
这个判据是实测定的——早期的判据只看「找到几条」，而关键词几乎总能凑够，等于永远不让语义上场。

索引文本的选择（一条来之不易的教训）

向量索引必须建在用户原文上，不能建在抽取摘要上。摘要读起来更「干净」，但它是第三人称的转述，与用户第一人称的提问不在同一个语义空间——实测语义路线 Recall@1 从 32.8% 掉到 6.3%。

配套使用须知（重要）

本插件是 meow-memory 的卫星，不是替代品。装之前请先确认这几件事。

① 它必须和 meow-memory 一起用

本插件不含任何记忆写入能力——记忆的产生、分层、整理（dream）全部由 meow-memory 负责。
单独装它，记忆库里没有东西可检索，等于空转。

② 它只读，绝不写入

| | meow-memory | dsh-memory-semantic |
| 角色 | 基座：记忆的写入、分层、整理 | 增强层：只读检索与召回 |
| 数据库 | <工作区>/.dsh-meow/memory.db | 自己的 <工作区>/.dsh-semantic/ |
| 本插件对它的影响 | —— | 绝不写入、绝不修改 |

两条硬规矩：

- 本插件始终以只读方式打开记忆库：不建表、不写行、不改 schema。
- 卸载本插件后，meow-memory 的一切功能与数据原样不受影响。

③ 首次使用会自动建索引

第一次调用 memory_semantic 时，插件会把现有记忆全量嵌入一遍建立向量索引（几百条的库通常几十秒内完成）。
之后新增的记忆会增量补嵌，不需要你操心。

④ Ollama 是可选依赖

- 装了：走「向量 + BM25」融合检索，召回质量更好。
- 没装 / 没开：自动降级为纯 BM25，功能不中断，只是语义泛化弱一些。

插件不会因为你没装 Ollama 而报错或阻塞；autoStart: true 时它会在后台尝试把 Ollama 拉起来（不阻塞本次对话）。

⑤ 数据都在你自己的工作区

向量索引、图谱、轮次库都写在 <工作区>/.dsh-semantic/ 下，删除该目录即可让本插件「从零开始」，不影响 meow-memory 的任何数据。

⑥ 它会多花多少 token（实测，量不大）

先说结论：meow-memory 自己的开销不会因为装了这个插件而增加——本插件只读它的库，不改它的行为。真正的增量只有下面两笔：

| 开销 | 发生在哪 | 实测（150 轮真实样本的中位长度轮次） |
| 每轮一次抽取 | 后台独立调用，不进你的对话上下文 | 输入 ≈ 2,600 tokens ＋ 输出 ≈ 240 tokens |
| 召回注入 | 插在当前提问之前，算进本轮上下文 | 最多 ≈ 1,100 tokens（k=3、上限 1200 字） |

按每天 100 轮估算，抽取约 26 万输入 + 2.4 万输出 tokens/天（长回复的轮次会比中位值高，实测样本最长一轮正文 3,752 字）。这个量级下，给抽取配一个便宜档模型就够——插件默认已经把抽取档位固定成温和档（low），不沿用你会话自己的档位。

两条都能单独关，互不影响：

- 不想要自动抽取：turns.live.enabled: false → 只留三个工具，需要时你自己喊；
- 不想要自动注入：turns.recallShadow.inject: false → 不再自动递料，但已入库的轮次照样能检索。

安装

方式一：命令行安装（CLI / 网页端 profile）

dsh plugin --profile <profile-name> add github:Jackbessaliuz/dsh-memory-semantic

dsh plugin 会把参数透传给 profile 里的 pnpm，所以 add / remove / update 都能用。
⚠️ 桌面端（Electron）的 desktop profile 由应用独占，命令行不能操作它——桌面端请在应用内的插件管理界面安装。

本包声明了 dsh.bundle.patch，安装器/reconcile 会自动把它加入当前 profile 的 bundles，重启 DSH 后生效（host 侧插件不会热重载）。

方式二：本地开发（link）

在 profile 目录里
npm i link:<本仓库路径>

然后在 profile 的 cordis.patch.yml 里手工 insert 一条 dsh-memory-semantic。

注意：同一条目不要既走 bundles 又手工 insert，会报重复 entry id。

装不上？先看这里

① 提示 allowBuilds / 安装期构建被拦

pnpm 10+ 默认阻止安装期脚本。本插件自己没有编译步骤（纯 JS，装上就能跑），但同一次安装里如果带着别的包——最常见的是记忆本体 meow-memory（它带 prepare）——pnpm 就会打印一个键并要求你允许它构建。

处理：按 pnpm 输出的提示，把那个键原样加进当前 profile 的 pnpm-workspace.yaml（pnpm 会给出确切的键名与写法），然后重跑安装命令。

② 官方桌面端（DSH Desktop）装不上

桌面端的 desktop profile 由应用独占，命令行不能操作它——请在应用内的「设置 → 插件」里安装（或让 AI 助手通过插件管理界面装）。

③ 装完没效果？

- 本插件必须和 meow-memory 一起用：它没有写入能力，记忆库里没东西时，可检索的内容自然是空的；
- 第一次调用会全量建索引（几百条通常几十秒），之后是增量补嵌，不用管；
- 语义检索这条路需要 Ollama + bge-m3；没装会自动降级成纯关键词检索——能用，但「换个说法」就不好找了。

④ 给 AI 助手的一页速查

如果用户把本仓库丢给你、让你帮忙装，照这五步走：

1. 先查记忆本体：宿主里有没有 meow-memory？没有就先装它（本插件只读它，缺了等于空转）。
2. 安装：dsh plugin --profile <profile> add github:Jackbessaliuz/dsh-memory-semantic
3. 必须重启 DSH：host 侧插件不热重载，不重启不会生效。
4. 验证挂载：dsh --profile <profile> --dump-config，其中 dsh-memory-semantic 的 - id: 行应恰好出现 1 次（0 次＝没挂上，2 次以上＝重复挂载）。
5. 报错留档：把原始报错原样保留再排查；allowBuilds 类按 ① 处理。官方桌面端没有 --dump-config，改用应用内的插件管理界面看状态。

两个高频误判：「装了但没效果」多半是没重启；「检索变笨了」多半是 Ollama 没开（此时自动降级为纯关键词，是设计行为，不是坏了）。

配置

所有可调参数都集中在 profile patch 的 config: 段，无需改代码：

- id: dsh-memory-semantic
name: 'dsh-memory-semantic'
config:
ollama:
url: http://127.0.0.1:11434
model: bge-m3
autoStart: false # true = 探测不到就后台拉起 Ollama executablePath: '' # 绿色版/自定义安装可显式指定 probeTimeoutMs: 800 warmupWaitMs: 0 # 0 = 点火不等人，本轮直接走 BM25 embedBatch: 32 retrieval: rrfK: 60 # RRF 融合常数 rrfPool: 10 # 每路候选池 outputChars: 220 # 单条记忆返回的最大字符数 queryInstruction: '为这个句子生成表示以用于检索相关文章：'
graph:
topK: 8
edgeThreshold: 0.62 # 余弦阈值：越高社区越碎 damping: 0.85 prIterations: 50 lpMaxIter: 50 turns: live: # 轮次记忆自动写入（默认开启） enabled: true maxTokens: 4000 concurrency: 2 priorTurns: 3 # 抽取时带上前面几轮做上下文 vector: true # 是否为每一轮算向量 recallShadow: # 召回注入（默认关闭） inject: true k: 3 maxChars: 1200 minQueryChars: 6 guard: # 防复读退化折叠（thinking-guard 并入，1.1.0） enabled: true dryRun: false # 调判据时先设 true 观察一天 minChars: 400 # 思考块短于这个长度不看 minRepeats: 25 # 同一单元至少重复这么多次 minShare: 0.20 # 重复部分至少占尾窗句数的 20% maxUnit: 30 # 算作「重复单元」的最大字符数（英文环境建议调大） tailChars: 4000 # 只看思考块尾部这么长 foldToolSteps: true # 带工具调用的步也折叠（含工具结果一起换成说明） rotationGuard: true # v2 判据：短句轮换 / 英文碎片

任何非法值都会安静地退回默认值——配置写错不会让插件加载失败。

更新日志

1.1.0（2026-10-18）

性能
- 词法召回从「每轮全量重建 BM25」迁移到 SQLite FTS5（中文按 bigram 入索引，与内存 BM25 同一套分词）。实测 1391 轮时每轮固定开销 440ms → 6~17ms，且不再随规模线性增长。
- 升级后自动迁移：首次打开库时建 FTS 索引并回填存量轮次（1424 行约 0.7s，一次性），之后随轮次增量同步，无需手动重建。

防复读退化（thinking-guard 并入）
- 新增 guard 配置段：退化的 reasoning 块会被从模型可见历史里折叠（日志原文不删、人看的 transcript 不受影响）。判据与独立版 thinking-guard 一致（235 会话校准，中文逐字复读 + 英文短句轮换两把尺子）。
- 建议首次开启时 guard.dryRun: true 观察一天再真折叠。

Ollama 自动拉起
- autoStart 现在在插件启动时就探测/点火，不再只在调用 memory_semantic 工具时触发；并每 5 分钟低频守护，Ollama 中途退出会被重新拉起。
- 设置页文案同步：开着 autoStart 但 Ollama 未运行时显示「启动时自动拉起」，不再直接判「降级」。

图谱
- memory_graph rebuild 改为后台任务，构图分块让出事件循环（此前 820 节点 1.4s、3000 节点 13s 全程阻塞宿主）。
- 设置页新增「重建图谱」按钮（异步、带状态、未建图时也可用）与过期提示（>7 天）。

修复
- 轮次 id 改为按 (sessionId, userSeq) 派生，与表上的 UNIQUE(session_id, user_seq) 对齐——消除已实证的 UNIQUE constraint failed（同一轮被算出两个 answerSeq 时）。
- 写库序列（轮次 + 三元组 + 队列状态 + 水位）包进一个事务，失败回滚并记 failed 走退避——不再出现「半写的轮次 + 队列永久 pending」。
- 合同层空白串改用 trim() 判断（与存储层同口径），避免「合同通过 → 计费 → 存储抛错」。
- recoverLimit / guardCooldownMs 两个旋钮补进归一化（此前用户写了配置不生效）。
- embedTexts 加超时（8s）：Ollama 半死时不再永久卡住宿主串行链。
- 融合权重接上 ROUTE_WEIGHTS（此前是死常量，线上一直等权）；routes 标签统一语义（此前 gated 分支下 vector/graph 补位会被误标为 bm25）；图谱路线只保留分数前 20%，不再用长尾稀释 RRF。

数据与隐私

- 全部数据都在本机：向量索引、图谱、轮次库都写在你自己的工作区 .dsh-semantic/ 下。
- embedding 请求只发给本机 Ollama（默认 127.0.0.1:11434）。
- 记忆库只读，本插件不会改动 meow-memory 的任何数据。
- 内置脱敏闸门：写入轮次库之前会过滤 GitHub token / API key / 私钥等敏感串——而且是在两处拦：一处挡「落库」，一处挡「明文被送给模型 API」。

Credits

本项目的轮次记忆数据模型、召回算法与 surface-takeover range 语义移植自
graph-memory（MIT License，© 2026 adoresever）。
骨架设计参考了它，实现按 DSH 的插件接口重写；在此致谢。

License

MIT