dsh-memory-search

Name: JackZo400/dsh-memory-search
Author: JackZo400

English | 简体中文

给 DeepSeek Harness（dsh）用的长期记忆检索插件。

把一堆 markdown 笔记做成 Agent「想得起来」的记忆：两路召回（本地向量 + 关键词），每轮自动把相关的旧事带进上下文，Agent 也能自己 memory_search 去翻。

一个跑得久的 Agent，问题常常不是模型不够聪明，而是它不记得。这个插件不训练、不微调，只做一件事：把你自己写的笔记，变成随时查得到的记忆。

同类里更成熟的选择：csyangwen/dsh-memory-evolve、Aik358/dsh-auto-memory、FuRongJun-1999/dsh-memory 都比这份成熟，要装先看它们。我们这份留着的理由：它是我们自己线上记忆检索的抽出版——两路召回（本地向量 + 关键词）和密级过滤都是跑过的那套，自检自带语料、不用先接上你的数据，索引删了也能从 .md 重建。功能面比上面几个窄，选之前先比一比。

为什么需要它（用 markdown 当语料）

记忆存在磁盘上的 .md 里，数据库只是索引：

笔记你随时能打开改，改完索引自己跟上（按 mtime/size 增量重切，只动改过的那篇）
备份、diff、git 版本化都是现成的
索引删了随时重建 —— 笔记是唯一的真相来源

特性

混合召回：SQLite FTS5 关键词 + 本地 embedding 向量，RRF 融合 —— 「原话」和「意思」各管一半。中文按重叠 bigram 在应用层切词，不用编译任何 SQLite 扩展。
零 API 花费：向量模型跑在本地（node-llama-cpp，CPU 就行）。
不装模型也能用：modelPath 留空就只跑关键词那一路，一条依赖都不用多。
两个出口：memory_search 工具（Agent 主动查）+ 每轮自动召回（塞进系统提示，不进对话记录）。
可选密级：同一堆语料里，群聊只可能召回 public，私事只在主人会话里出现。
切块规范有闸：改切块规则不会偷偷把全库向量重算一遍，要你显式点头。

安装

dsh plugin --profile web add github:JackZo400/dsh-memory-search

装完按下面的「配置」改一遍，再重启对应 profile。

环境要求：Node ≥ 22.5（用的是内置 node:sqlite；实测 22.22 直接可用，会打一条 ExperimentalWarning，属正常）。想开向量检索才需要装 node-llama-cpp 并自己下一个 GGUF 模型 —— 它列在 optionalDependencies 里，装不上也不影响关键词检索。

配置

配置写在你的 profile patch 里（bundle patch 的 insert 段）：

- insert:
    - id: memory-search
      name: dsh-memory-search
      config:
        dbPath: .dsh-memory/index.db    # 索引库落哪；相对路径按 dsh 的工作目录算
        roots:                          # 语料根目录：递归收集里面的 .md
          - ./memory
        modelPath: ''                   # GGUF 嵌入模型；留空 = 只跑关键词
        recall:
          enabled: true                 # 每轮自动召回
          limit: 4                      # 最多带几条
          budgetChars: 1600             # 注入的字符预算
          order: 130                    # 在系统提示里的排序位
        embedding:
          enabled: true
          threads: 6                    # CPU 线程数
          contextSize: 1024             # 上下文窗口（开大更吃内存）
          batchSize: 256
          queryInstruction: ''          # 见下
        search:
          candidatePool: 40             # 每路召回各取多少候选
          rrfK: 10                      # RRF 平滑常数
        exclude: ['**/.index/**', '**/node_modules/**']
        syncIntervalMs: 300000          # 多久扫一次新写的笔记
        acceptSpecChange: false         # 换切块规则才设 true（会重算全部向量）

几个容易踩的点：

roots 不配就是空索引，日志会提醒你。
modelPath 留空时插件只建关键词索引，embedding.enabled 开着也白开（不会报错）。
queryInstruction：默认值是给 Qwen3-Embedding 用的指令前缀（它 instruction-aware，检索质量吃这个前缀）。换别的嵌入模型（bge-m3、nomic 之类）建议在配置里显式清空，不然前缀会污染语义。
换嵌入模型要删掉索引库重建 —— 向量维度不同，旧向量没法复用（代码会检测到维度不匹配，直接放弃语义那一路，不会给你算出垃圾结果）。

配置（语料怎么放）

没有固定结构，递归收 .md，两个建议：

一条一事（一个 bullet 一件事、段落之间空行）。切块是按「空行 / 列表项 / 标题」这些边界走的 —— 相邻的两件事被塞进同一块，检索精度会掉。
事实文件别混进大量流水账。语料里「日记里我正在讨论这件事」的段落会字面上更像查询，把真正的事实挤出前排。插件给 public.md / personal.md / secret.md 这类文件加了 1.5 倍来源权重、给 carryover/ 目录降了权，但语料结构还是你自己最清楚。

配置（密级，可选）

判据是文件名（放在哪个目录下都行）：

文件名	密级	谁能召回
`public.md`	`public`	所有会话
`personal.md`	`personal`	只有 owner 会话
`secret.md`	`secret`	只有 owner 会话
其它任何文件	`personal`（保守）	只有 owner 会话

「谁是 owner」由可选的通道映射决定 —— 一个 JSON，把会话 key 映射到 session id：

{ "c2c:1A2B3C": { "sessionId": "8f0c…" }, "group:123456": { "sessionId": "ab12…" } }

配上 sessionMap 之后：group:/grp: 开头的 key 判成 group（只给 public）、在 ownerIds 里的判成 owner（全给）、其余判成 guest（只给 public）。 判不出通道时不召回（fail closed）—— 宁可少给，不可漏私事。

不配 sessionMap 就不做任何过滤，所有会话都当 owner —— 单人使用（不接群）的时候，这才是你想要的默认。

工作原理

markdown 语料 ──scan──▶ 切块（按条目边界）──▶ SQLite
                                              ├── chunks（正文 + 向量 BLOB）
                                              └── chunks_fts（bigram token）
查询 ──┬── FTS5 MATCH ──▶ bm25 排名 ─┐
       └── embed ──────▶ 余弦排名 ──┴── RRF 融合 ──▶ 按来源加权 ──▶ 密级过滤 ──▶ top-k

RRF 融合：不比较两路的分数（bm25 和余弦根本不是一个量纲），只比名次。
切块：按空行 / 列表项 / markdown 标题切，条目超长才按长度硬切；保留起始行号，方便回原文。
增量：每个文件记 mtime + size，只重切变过的；删掉的文件从索引里忘掉。
切块规范闸：切块规则变了（CHUNK_SIG），默认只记账不重切 —— 要重切得设 acceptSpecChange: true（那一下会把全部向量重算）。
两个出口：memory_search 工具返回原文片段 + 出处（不是摘要）；自动召回挂在 system-prompt/assemble 上，往系统提示里加一段 memory-search， 不写进对话记录，所以不会污染上下文历史。

测试

node test/selftest.mjs         # 切块 / 分词 / 索引 / 检索（临时语料，无外部依赖）
node test/plugin-selftest.mjs  # 插件契约：工具注册、系统提示段、服务暴露、密级
node test/spec-guard.mjs       # 切块规范闸：改了规则不许偷偷重切
npm test                       # 上面三个一起

test/recall-eval.mjs 是评测脚手架，不是自检 —— 它对着你自己的索引库跑一批「问句 → 期望命中的片段/文件」的题，报告 top-1 / top-3 / top-5 命中率：

node test/recall-eval.mjs --db .dsh-memory/index.db --corpus ./memory

题目要按你自己的语料改（文件头部有示例）。这是这个插件最该动的地方 —— 召回质量跟语料结构强相关，我给的默认权重只在一类语料上验证过。

已知局限

切块规则是启发式的（空行/列表/标题），对「一大段长文」的笔记不友好。
来源权重是硬编码的三条，按文件名/目录匹配。语料结构差异大的话，得改 src/recall.js。
向量检索是全量扫描（几百到几千块是毫秒级，上万块就该上专门的向量库了）。
中文分词只做 bigram，没有词表 —— 专有名词查得准，语法层面的理解不做。
嵌入模型只在 Qwen3-Embedding-0.6B 上验证过，换模型请留意 queryInstruction 和维度。

License

English

→ Full English README: README.en.md

dsh-memory-search

English | 简体中文

给 DeepSeek Harness（dsh）用的长期记忆检索插件。

一个跑得久的 Agent，问题常常不是模型不够聪明，而是它不记得。这个插件不训练、不微调，只做一件事：把你自己写的笔记，变成随时查得到的记忆。

同类里更成熟的选择：csyangwen/dsh-memory-evolve、Aik358/dsh-auto-memory、FuRongJun-1999/dsh-memory 都比这份成熟，要装先看它们。我们这份留着的理由：它是我们自己线上记忆检索的抽出版——两路召回（本地向量 + 关键词）和密级过滤都是跑过的那套，自检自带语料、不用先接上你的数据，索引删了也能从 .md 重建。功能面比上面几个窄，选之前先比一比。

为什么需要它（用 markdown 当语料）

记忆存在磁盘上的 .md 里，数据库只是索引：

笔记你随时能打开改，改完索引自己跟上（按 mtime/size 增量重切，只动改过的那篇）
备份、diff、git 版本化都是现成的
索引删了随时重建 —— 笔记是唯一的真相来源

特性

混合召回：SQLite FTS5 关键词 + 本地 embedding 向量，RRF 融合 —— 「原话」和「意思」各管一半。中文按重叠 bigram 在应用层切词，不用编译任何 SQLite 扩展。
零 API 花费：向量模型跑在本地（node-llama-cpp，CPU 就行）。
不装模型也能用：modelPath 留空就只跑关键词那一路，一条依赖都不用多。
两个出口：memory_search 工具（Agent 主动查）+ 每轮自动召回（塞进系统提示，不进对话记录）。
可选密级：同一堆语料里，群聊只可能召回 public，私事只在主人会话里出现。
切块规范有闸：改切块规则不会偷偷把全库向量重算一遍，要你显式点头。

安装

dsh plugin --profile web add github:JackZo400/dsh-memory-search

装完按下面的「配置」改一遍，再重启对应 profile。

配置

配置写在你的 profile patch 里（bundle patch 的 insert 段）：

- insert:
    - id: memory-search
      name: dsh-memory-search
      config:
        dbPath: .dsh-memory/index.db    # 索引库落哪；相对路径按 dsh 的工作目录算
        roots:                          # 语料根目录：递归收集里面的 .md
          - ./memory
        modelPath: ''                   # GGUF 嵌入模型；留空 = 只跑关键词
        recall:
          enabled: true                 # 每轮自动召回
          limit: 4                      # 最多带几条
          budgetChars: 1600             # 注入的字符预算
          order: 130                    # 在系统提示里的排序位
        embedding:
          enabled: true
          threads: 6                    # CPU 线程数
          contextSize: 1024             # 上下文窗口（开大更吃内存）
          batchSize: 256
          queryInstruction: ''          # 见下
        search:
          candidatePool: 40             # 每路召回各取多少候选
          rrfK: 10                      # RRF 平滑常数
        exclude: ['**/.index/**', '**/node_modules/**']
        syncIntervalMs: 300000          # 多久扫一次新写的笔记
        acceptSpecChange: false         # 换切块规则才设 true（会重算全部向量）

几个容易踩的点：

roots 不配就是空索引，日志会提醒你。
modelPath 留空时插件只建关键词索引，embedding.enabled 开着也白开（不会报错）。
queryInstruction：默认值是给 Qwen3-Embedding 用的指令前缀（它 instruction-aware，检索质量吃这个前缀）。换别的嵌入模型（bge-m3、nomic 之类）建议在配置里显式清空，不然前缀会污染语义。
换嵌入模型要删掉索引库重建 —— 向量维度不同，旧向量没法复用（代码会检测到维度不匹配，直接放弃语义那一路，不会给你算出垃圾结果）。

配置（语料怎么放）

没有固定结构，递归收 .md，两个建议：

一条一事（一个 bullet 一件事、段落之间空行）。切块是按「空行 / 列表项 / 标题」这些边界走的 —— 相邻的两件事被塞进同一块，检索精度会掉。
事实文件别混进大量流水账。语料里「日记里我正在讨论这件事」的段落会字面上更像查询，把真正的事实挤出前排。插件给 public.md / personal.md / secret.md 这类文件加了 1.5 倍来源权重、给 carryover/ 目录降了权，但语料结构还是你自己最清楚。

配置（密级，可选）

判据是文件名（放在哪个目录下都行）：

文件名	密级	谁能召回
`public.md`	`public`	所有会话
`personal.md`	`personal`	只有 owner 会话
`secret.md`	`secret`	只有 owner 会话
其它任何文件	`personal`（保守）	只有 owner 会话

「谁是 owner」由可选的通道映射决定 —— 一个 JSON，把会话 key 映射到 session id：

{ "c2c:1A2B3C": { "sessionId": "8f0c…" }, "group:123456": { "sessionId": "ab12…" } }

不配 sessionMap 就不做任何过滤，所有会话都当 owner —— 单人使用（不接群）的时候，这才是你想要的默认。

工作原理

markdown 语料 ──scan──▶ 切块（按条目边界）──▶ SQLite
                                              ├── chunks（正文 + 向量 BLOB）
                                              └── chunks_fts（bigram token）
查询 ──┬── FTS5 MATCH ──▶ bm25 排名 ─┐
       └── embed ──────▶ 余弦排名 ──┴── RRF 融合 ──▶ 按来源加权 ──▶ 密级过滤 ──▶ top-k

RRF 融合：不比较两路的分数（bm25 和余弦根本不是一个量纲），只比名次。
切块：按空行 / 列表项 / markdown 标题切，条目超长才按长度硬切；保留起始行号，方便回原文。
增量：每个文件记 mtime + size，只重切变过的；删掉的文件从索引里忘掉。
切块规范闸：切块规则变了（CHUNK_SIG），默认只记账不重切 —— 要重切得设 acceptSpecChange: true（那一下会把全部向量重算）。
两个出口：memory_search 工具返回原文片段 + 出处（不是摘要）；自动召回挂在 system-prompt/assemble 上，往系统提示里加一段 memory-search， 不写进对话记录，所以不会污染上下文历史。

测试

node test/selftest.mjs         # 切块 / 分词 / 索引 / 检索（临时语料，无外部依赖）
node test/plugin-selftest.mjs  # 插件契约：工具注册、系统提示段、服务暴露、密级
node test/spec-guard.mjs       # 切块规范闸：改了规则不许偷偷重切
npm test                       # 上面三个一起

node test/recall-eval.mjs --db .dsh-memory/index.db --corpus ./memory

已知局限

切块规则是启发式的（空行/列表/标题），对「一大段长文」的笔记不友好。
来源权重是硬编码的三条，按文件名/目录匹配。语料结构差异大的话，得改 src/recall.js。
向量检索是全量扫描（几百到几千块是毫秒级，上万块就该上专门的向量库了）。
中文分词只做 bigram，没有词表 —— 专有名词查得准，语法层面的理解不做。
嵌入模型只在 Qwen3-Embedding-0.6B 上验证过，换模型请留意 queryInstruction 和维度。

License

English

→ Full English README: README.en.md

JackZo400/dsh-memory-search

dsh-memory-search

为什么需要它（用 markdown 当语料）

特性

安装

配置

配置（语料怎么放）

配置（密级，可选）

工作原理

测试

已知局限

License

English

Community comments

JackZo400/dsh-memory-search

dsh-memory-search

为什么需要它（用 markdown 当语料）

特性

安装

配置

配置（语料怎么放）

配置（密级，可选）

工作原理

测试

已知局限

License

English

Community comments