dsh-memory-semantic

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

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

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

English

---

🧠 记忆是怎么运转的

┌─ 存 ──────────────────────────────────────────────────────────┐
│                                                               │
│   书架 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