dsh-engramory-recall 0.6.2 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.8.0] — 2026-10-15
+
+### 新增
+
+- **零依赖 MCP 服务器（`mcp.js`）**：走 stdio 的只读 MCP 服务器，把同一份记忆库挂给任何支持
+  MCP 的宿主（Claude Code / Codex / Cursor…）。三个工具：`engramory_search`（同一个 BM25 内核）、
+  `engramory_read`（按文件名读原文，只认库根目录的 `.md`）、`engramory_status`（库位置 / 篇数 /
+  索引余量 / 指纹）；每篇笔记另外注册成 MCP 资源（`engramory://note/<文件名>`）。
+  只用 `node:` 内置模块、不 import 任何宿主包、**只读** —— 写入闸门与归档依赖宿主工具层的钩子，
+  别的宿主没有这套接口，硬做只会把 fail-closed 换成口头约定。
+  装了包就多一个命令：`engramory-recall-mcp`（库路径用 `--store` 或环境变量 `ENGRAMORY_STORE`）。
+- `npm run mcp:smoke`：拿脚本当 MCP 客户端，把服务器真的拉起来走一遍对话
+  （initialize → tools/list → status → search → resources/read → 越界读被拒），打印收发记录。
+
+### 测试
+
+- `test/mcp.test.mjs`：8 例，**全部起真进程**（协议版本协商、工具清单与 inputSchema、检索命中、
+  非法参数只回 isError 不炸进程、`../` 越界读一律拒、resources 往返、空库给「库在哪」的提示、
+  stdout 上只允许协议帧且日志只走 stderr，外加 `--version` / `--print-config` / 坏参数的退出码）。
+  合计 192 例全绿。
+
+## [0.7.0] — 2026-10-15
+
+### 变更
+
+- **长度归一常数 B 从教科书的 0.75 调到 0.4**（`bm25.js`）。三把尺子一致说 0.75 偏大：
+  LongMemEval-S 500 题 @1 87.8% → **88.4%**、@5 97.4% → **98.2%**、覆盖 91.5% → **92.5%**、
+  MRR 0.9155 → **0.9202**；自建合成卷子 hit@1 49.9% → **50.4%**、hit@4 66.6% → **67.5%**；
+  真库探针的中立对照 C top1 141/181 → **150/181**、recall@4 168/181 → **177/181**。
+  代价是偏袒短名的对照 A 掉了 2 分（45→43）。机制：长会话/长笔记里同一个词出现得更多，
+  `len/avgLen` 的惩罚就变成「谁长谁吃亏」，与相关性无关。扫过 0.2~0.9，0.3~0.5 是平台，取 0.4。
+- README 三张表与「长度归一」小节据此重算；`bench/expectations.json` 与
+  `bench/longmemeval-results.json` 一起重设（都写了原因）。
+
+### 新增（记在「被实测证伪的路」里）
+
+- **拿「结果要多样」当选桶护栏（MMR / 覆盖优先）**：在 LongMemEval-S 500 题上，MMR 各档
+  （λ 0.15 / 0.3 / 0.5）与基线逐位相同；覆盖优先 β=1.0 让 @1 掉 1.4pt。
+  顺带把「差一点」量化出来：948 个 gold 里 87.9% 已进 top-5，没进的里 40.0% 排在第 6~10 名、
+  39.1% 在第 11~25 名、16.5% 与问题零词重叠 —— 瓶颈是语义，不是重排。
+- **df 下限**（丢掉出现在超过一半文档里的词）：LongMemEval-S 上三档全不涨，@1 持平或更差。
+
 ## [0.6.2] — 2026-10-15
 
 ### 变更

package/README.md

@@ -10,6 +10,9 @@
 全部用 `node:` 内置模块实现：零第三方依赖、零网络、**默认零模型调用**、零常驻进程
 （只有你显式开启可选的语义增强时，才会走宿主的模型服务）。
 
+5. **别的宿主也能用**：`mcp.js` 是一个零依赖的 MCP（stdio）服务器，同一份记忆库可以挂给
+   Claude Code / Codex / Cursor 这类支持 MCP 的宿主 —— **只读**（检索与读笔记），写治理留在下面。
+
 ## 底线
 
 | 底线 | 本插件如何守 |
@@ -32,7 +35,7 @@
 | **三年后还能跑** | 不需要编译原生模块、不需要常驻服务 | 带 `better-sqlite3` 编译、rust 工具链、独立 daemon 的方案，会在某次系统升级后让你回来看这篇 README |
 
 四问都过了，才轮到比功能。功能这一层，本插件的取舍是**把不确定性变成可测量的东西**：
-新机制必须在库上跑出数字，跑不出来就不上（文末六条被证伪的路就是这么留下的）。
+新机制必须在库上跑出数字，跑不出来就不上（文末八条被证伪的路就是这么留下的）。
 
 ## 跟同类插件对照
 
@@ -71,13 +74,16 @@
 
 ### 短板
 
-- **公开基准只跑了一半**：LongMemEval-S 500 题跑出 RecallAny@5 97.4%（见下），但那只测英文词面
+- **公开基准只跑了一半**：LongMemEval-S 500 题跑出 RecallAny@5 98.2%（见下），但那只测英文词面
   检索；`thoth-mem` 公布的 470 题版本（RecallAny@5 432/470、Recall@5 84.8%、NDCG@10 0.8165）
   用的是别的 harness，两边数字不可相减。真正的「跨插件排名」仍然不存在。
 - **无语义检索**：没有 embedding、没有向量库。同义改写、隐含意图要靠手工同义表覆盖，
   没覆盖到的就是漏检。（可选的 `ctx.llm` 模块能做矛盾检测和摘要，但它**不参与检索排序**，
   所以排序本身仍然是纯词面的。）
-- **只支持 DSH 一个宿主**：`claude-mem` 覆盖 7 个宿主，`thoth-mem` 覆盖 4 个。
+- **只有 DSH 里是「全功能」**：0.8.0 起带一个零依赖的 MCP 服务器（见下），任何支持 MCP
+  的宿主都能检索与读笔记；但写入闸门、归档、体检、沉淀提醒、面板这些**只在家用版（DSH 插件）
+  里有** —— 别的宿主拿到的是只读视图。`claude-mem` 覆盖 7 个宿主、`thoth-mem` 覆盖 4 个，
+  我们覆盖「1 个全功能 + N 个只读」。
 - **没有多端或团队同步**：basic-memory 有云同步，本插件没有。
 - **写入闸门可以被绕过**：`guard` 只拦 `write` / `edit` 工具调用，`bash` 重定向它看不见；
   `@jipika/dsh-memory` 的 guard 挂在更底层的 `tools/pre-execute`，覆盖更广。
@@ -95,7 +101,7 @@ CI 里再跑一遍 `npm run bench:check` 跟 `bench/expectations.json` 对账。
 
 | 引擎 | 总 hit@1 | 总 hit@4 | verbatim | colloquial | keyword |
 |---|---|---|---|---|---|
-| **本插件** | **49.9%** | 66.6% | 98.2% | 33.9% | 15.2% |
+| **本插件** | **50.4%** | 67.5% | 98.7% | 34.8% | 15.6% |
 | 教科书 BM25（同分词口径） | 43.2% | 46.9% | 100% | 17.9% | 17.9% |
 | 教科书 BM25（中文逐字切分） | 47.2% | 53.4% | 100% | 20.1% | 28.1% |
 | 瞎猜（地板线） | 0.6% | 2.6% | 0.4% | 0.9% | 0.4% |
@@ -106,15 +112,15 @@ CI 里再跑一遍 `npm run bench:check` 跟 `bench/expectations.json` 对账。
 
 | 改动 | 总 hit@1 | 相对本插件 |
 |---|---|---|
-| 本插件 | 49.9% | — |
-| 去掉同义表 | 46.7% | -3.1pt |
-| 去掉笔记别名（不再声明 `aliases`） | 56.5% | **+6.7pt** |
-| 去掉字段加权（`TITLE_EXTRA` 24 → 0） | 49.6% | -0.3pt |
-| 同义键碎片不降权（回到改动前） | 49.1% | -0.7pt |
-| 桥权重与同义表一致（都算 0.5） | 50.4% | +0.6pt |
+| 本插件 | 50.4% | — |
+| 去掉同义表 | 46.4% | -4.0pt |
+| 去掉笔记别名（不再声明 `aliases`） | 56.1% | **+5.7pt** |
+| 去掉字段加权（`TITLE_EXTRA` 24 → 0） | 49.1% | -1.3pt |
+| 同义键碎片不降权（回到改动前） | 49.0% | -1.4pt |
+| 桥权重与同义表一致（都算 0.5） | 51.4% | +1.0pt |
 
 「去掉笔记别名」是 **+6.7pt**，在总分上反而更好看 —— 这个语料里别名是把双刃剑：
-它帮自己（写了别名的 37 篇 hit@1 89.2%，没写的 187 篇 23.0%），
+它帮自己（写了别名的 37 篇 hit@1 94.6%，没写的 187 篇 23.0%），
 也把同域别的笔记的口语查询抢过来（语料里同域的别名共用同一个口语域词，而别名是程序按比例随机发的）。
 真库里别名是人手写的、更克制，所以别拿这一行下结论 —— 判断别名只看探针的别名组（5/5）。
 
@@ -125,21 +131,34 @@ CI 里再跑一遍 `npm run bench:check` 跟 `bench/expectations.json` 对账。
 而 `代理`、`部署` 既是同义键、也是笔记正文里的原词，剔掉等于把真证据扔了。
 所以改成**降权不剔除**（`BRIDGED_FRAGMENT_WEIGHT = 0.5`，桥到的技术词算 `BRIDGE_WEIGHT = 1`）。
 降权只针对键的**碎片**（单字、相邻双字），键本身照旧算满权重 —— 这一条是量出来的：
-一开始连键本身一起降权，`verbatim` 对照组从 100% 掉到 95.1%，放开键本身后回到 98.2%，
+一开始连键本身一起降权，`verbatim` 对照组从 100% 掉到 95.1%，放开键本身后回到 98.7%，
 而桥组一点没退。道理很直白：查询里原样出现的那个词是实打实的证据，降权的理由只是
 它拆出来的碎片在别的笔记里到处都是。
 
-代价是与「桥权重打回 0.5」相比总分少 0.6 个点（50.4% → 49.9%）。接受它的理由：
+代价是与「桥权重打回 0.5」相比总分少 1.0 个点（51.4% → 50.4%）。接受它的理由：
 合成语料里绝大多数查询本来就有字面落点，总分被它们主导；桥是唯一在字面完全无交集时
 还能工作的机制 —— 同一批桥查询，桥权重打回 0.5 只有 25.0%，碎片不降权 43.8%。
 （历史值：修「碎片压桥」之前，那一版语料上这组查询只有 27.3%。）
 
-「去掉字段加权」那一行要单独说：它现在是 -0.3pt（拿掉略微更差），**在一次引擎改动之前它是 +4pt**
+「去掉字段加权」那一行要单独说：它现在是 -1.3pt（拿掉略微更差），**在一次引擎改动之前它是 +4pt**
 （拿掉明显更好），而**真实库的中立对照一直说拿掉更差**（见下）。当时的冲突定位到机制上：
 合成语料的标题是从正文模板派生的、与正文近乎重复，抬高标题权重只是放大域词噪声；
 真实库的标题是人手提炼的。现在前两把尺子都偏向「留着字段加权」，但理由仍是上面这条 ——
 不是冲突消失了，是那把合成尺子的标题变真实了一点。两者不一致时以对照 C 为准。
 
+**长度归一的强度 B 是量出来的，不是抄的。** 教科书默认 0.75 我们抄了很久，三把尺子都说它偏大：
+
+| 尺子 | B=0.75 | B=0.4 |
+|---|---|---|
+| 这份合成卷子 | hit@1 49.9% · hit@4 66.6% | hit@1 50.4% · hit@4 67.5% |
+| LongMemEval-S 500 题 | @1 87.8% · @5 97.4% · 覆盖 91.5% | @1 88.4% · @5 98.2% · 覆盖 92.5% |
+| 真库对照 C（中立那把） | top1 141/181 · recall@4 168/181 | top1 150/181 · recall@4 177/181 |
+
+机制：同一个词在长会话、长笔记里出现得更多，`len/avgLen` 这个惩罚就变成「谁长谁吃亏」，
+与相关性无关。代价在对照 A 上看得见（top1 45→43），但 A 拿文件名当查询、结构性偏袒短名，
+按一直以来的规矩以对照 C 为准。扫过的值是 0.2 / 0.3 / 0.4 / 0.5 / 0.6 / 0.75 / 0.9，
+0.3~0.5 是一片平台，取中间偏下的 0.4。
+
 ### 桥组：32 条，65.6%
 
 | 组 | 条数 | hit@1 | 说明 |
@@ -172,12 +191,12 @@ CI 里再跑一遍 `npm run bench:check` 跟 `bench/expectations.json` 对账。
 | 组 | 条数 | 测什么 | 最近一次 |
 |---|---|---|---|
 | 口径 | 21 | 真实场景的中文口语问法 | recall@4 21/21 |
-| 桥探针 | 10 | 全局同义表（大白话问英文/术语密集的笔记） | recall@4 9/10 |
+| 桥探针 | 10 | 全局同义表（大白话问英文/术语密集的笔记） | recall@4 10/10 |
 | 别名探针 | 5 | 笔记自己的 `aliases:`（关键词在全局桥里一个都没有） | recall@4 5/5 |
-| 死桥自检 | 519 值 | 同义桥的每个值是否真的存在于语料（不存在等于白写） | 121 个死值（均为通用词） |
-| 对照 A | 189 | 文件名当查询的底线（对标题权重有偏袒） | top1 36/189 · recall@4 96/189 |
-| 对照 B | 164 | 笔记中文标题当查询的底线（同样偏袒） | top1 159/164 · recall@4 163/164 |
-| 对照 C | 176 | 正文独有词当查询（该词在任何标题里都没有） | top1 140/176 · recall@4 164/176 |
+| 死桥自检 | 519 值 | 同义桥的每个值是否真的存在于语料（不存在等于白写） | 118 个死值（均为通用词） |
+| 对照 A | 194 | 文件名当查询的底线（对标题权重有偏袒） | top1 43/194 · recall@4 96/194 |
+| 对照 B | 169 | 笔记中文标题当查询的底线（同样偏袒） | top1 164/169 · recall@4 168/169 |
+| 对照 C | 181 | 正文独有词当查询（该词在任何标题里都没有） | top1 150/181 · recall@4 177/181 |
 
 对照 A 和 B 都拿标题当查询，所以它们对「标题里的词多计几遍」这类参数是**结构性偏袒**的：
 抬高标题权重几乎必然让这两组变好。它们既不该当目标函数，也不能用来证明「抬高标题权重是安全的」。
@@ -218,33 +237,35 @@ haystack，题目分六类。
 
 | 指标 | 全部 500 题 | 教科书 BM25（同分词口径） |
 | --- | --- | --- |
-| RecallAny@1 | **87.8%** | 86.2% |
-| RecallAny@5 | **97.4%** | 97.0% |
-| Recall@5（gold 覆盖率） | **91.5%** | 90.7% |
-| MRR@5 | **0.9155** | 0.9056 |
-| RecallAny@10 | **98.4%** | 98.2% |
+| RecallAny@1 | **88.4%** | 86.2% |
+| RecallAny@5 | **98.2%** | 97.0% |
+| Recall@5（gold 覆盖率） | **92.5%** | 90.7% |
+| MRR@5 | **0.9202** | 0.9056 |
+| RecallAny@10 | **98.8%** | 98.2% |
 
 | 题型 | 题数 | RecallAny@1 | RecallAny@5 | Recall@5 | MRR@5 |
 | --- | --- | --- | --- | --- | --- |
-| knowledge-update | 78 | 97.4% | 100.0% | 98.7% | 0.987 |
-| multi-session | 133 | 88.0% | 97.0% | 85.3% | 0.919 |
+| knowledge-update | 78 | 98.7% | 100.0% | 99.4% | 0.994 |
+| multi-session | 133 | 88.0% | 98.5% | 86.0% | 0.920 |
 | single-session-assistant | 56 | 100.0% | 100.0% | 100.0% | 1.000 |
-| single-session-preference | 30 | 40.0% | 86.7% | 86.7% | 0.583 |
+| single-session-preference | 30 | 46.7% | 90.0% | 90.0% | 0.627 |
 | single-session-user | 70 | 92.9% | 100.0% | 100.0% | 0.950 |
-| temporal-reasoning | 133 | 85.0% | 96.2% | 86.6% | 0.892 |
+| temporal-reasoning | 133 | 85.0% | 97.0% | 88.5% | 0.894 |
 
 三句必须说在前面的实话：
 
-1. **这 1.6 个点的来源要说清楚。** 本插件比教科书 BM25 高 1.6pt @1，差的那部分**全部**来自一处通用改动：
-   查询侧丢掉英文虚词（`what / is / the / of / did / how…`）。是我们自己的机制（同义表、别名、
-   字段加权、中文分词）在这份数据上没被激活 —— LongMemEval 是英文的，session 没有标题、
-   没有别名、没有中文口语，它们在这里没事可做。所以这张表证明的是「英文词面检索不输、且
-   基础卫生做到位」，**不是**「本插件的独门设计更好」。机制值多少，回上面两把尺子看。
+1. **这 2.2 个点的来源要说清楚。** 本插件比教科书 BM25 高 2.2pt @1，差的那部分**全部**来自两处通用改动：
+   查询侧丢掉英文虚词（`what / is / the / of / did / how…`），以及把长度归一常数从教科书的 0.75
+   调到 0.4。两处都与中文无关 —— 是我们自己的机制（同义表、别名、字段加权、中文分词）在这份数据上
+   没被激活：LongMemEval 是英文的，session 没有标题、没有别名、没有中文口语，它们在这里没事可做。
+   B 的取值不是在这份数据上单独挑的（挑法见上：三把尺子一致，真库中立对照 +9/+9）。所以这张表
+   证明的是「英文词面检索不输、且基础卫生做到位」，**不是**「本插件的独门设计更好」。机制值多少，
+   回上面两把尺子看。
 2. **别拿它跟别家数字直接相减。** thoth-mem 公布过 LongMemEval-S 470 题、RecallAny@5 91.9%。
    我们用的是 cleaned 版 500 题 + 自己的 harness，题集版本、命中口径、读不读日期都未必一样，
    相减没有意义。能担保的是：harness 与逐题结果都在仓库里（`bench/longmemeval.mjs`、
    `bench/longmemeval-results.json`），可以逐题核。
-3. **最差的是偏好题**（40.0%@1）：「我喜欢什么」这类问题本身没什么词面抓手。这是零模型路线的
+3. **最差的是偏好题**（46.7%@1）：「我喜欢什么」这类问题本身没什么词面抓手。这是零模型路线的
    边界 —— 偏好类想做得更好，要么开可选的 `llm.js`，要么就老老实实把偏好写进标题。
 
 复算：
@@ -484,6 +505,9 @@ aliases: 梯子, 翻墙, 科学上网, 节点, 代理
 | 自动合并 | 只出报告，不自动改文件 | 已实现（只报告） |
 | 语义冲突检测 | 走宿主 `ctx.llm`，**默认关闭** | 已实现（`semanticConflicts`） |
 | 自动摘要 | 走宿主 `ctx.llm`，**默认关闭** | 已实现（`semanticSummary`） |
+| 跨宿主分发 | 零依赖 stdio MCP 服务器，只读 | 已实现（`mcp.js`） |
+| 跨会话覆盖 | 「结果要多样」的选桶护栏（MMR / 覆盖优先） | 量过了，**被证伪**（见「被实测证伪的路」），收益改在长度归一 `B` 上拿到 |
+| 可选语义检索 | 可插拔 seam（向量/API 都行），默认关闭 | 计划中 |
 
 后两条默认关闭，是为了让「零模型调用」这条基线保持可复现。开启是用户的显式选择，
 而不是装完就生效：一个会自己调模型改写你笔记的插件不该默认打开。走 `ctx.llm`
@@ -565,19 +589,56 @@ dsh plugin --profile <profile> remove dsh-engramory-recall
 指向已删的路径），添或删任何插件都会一起失败，而且报错说的是那个无关的包。
 排查时看 `.plugin-manager/logs/operation-*/pnpm.log`，别盯被操作的那个包。
 
+## 别的宿主：MCP 服务器（只读）
+
+`mcp.js` 是一个零依赖的 MCP（Model Context Protocol）stdio 服务器。它只做三件事，
+全部只读、全部本机、零模型调用：
+
+| 工具 | 作用 |
+|---|---|
+| `engramory_search` | 同一个 BM25 内核（中文分词、177 条同义桥、别名、字段加权） |
+| `engramory_read` | 按文件名读一篇笔记的原文（只认库里根目录的 `.md`，路径一律拒） |
+| `engramory_status` | 库在哪、多少篇、索引几行几字节、指纹 —— 先确认读的是不是你以为的那个库 |
+
+另外把每篇笔记也注册成 MCP 资源（`engramory://note/<文件名>`），客户端可以直接列出来读。
+
+```jsonc
+// Claude Code / Claude Desktop / Cursor 之类的 mcpServers 配置
+{
+  "mcpServers": {
+    "engramory": {
+      "command": "node",
+      "args": ["/path/to/node_modules/dsh-engramory-recall/mcp.js", "--store", "~/memory/engramory"]
+    }
+  }
+}
+```
+
+```bash
+# 装了这个包就有了一个可直接调用的命令
+engramory-recall-mcp --store ~/memory/engramory      # 库路径也可以用环境变量 ENGRAMORY_STORE
+npm run mcp:smoke                                    # 自证：拉起来走一遍完整对话，打印收发记录
+```
+
+**为什么它是只读的**：写入闸门、归档、体检这些能力依赖宿主工具层的钩子（`tools/pre-execute`），
+别的宿主没有这套接口；硬做一个「谁都能写」的版本，等于把 fail-closed 的闸门换成一句口头约定。
+所以跨宿主给的是**看**的能力，治理留在家用版里。它也不 import 任何宿主包 ——
+在别的宿主里最坏是「没被用上」，不会「装上就崩」。
+
 ## 测试与自检
 
 ```bash
-npm test        # 分词 / BM25 / 切桶 / 门控 / 闸门 / 索引闸门 / 技能注册 / 体检 / 审计 / 沉淀提醒 / 归档 / 打包 / 路由 / 公开基准 harness
+npm test        # 分词 / BM25 / 切桶 / 门控 / 闸门 / 索引闸门 / 技能注册 / 体检 / 审计 / 沉淀提醒 / 归档 / 打包 / 路由 / 公开基准 harness / MCP 服务器
 npm run check   # 接线自检：配置键认不认、库路径对不对、装的是哪一份、包清单漏没漏文件
 npm run probe   # 召回质量探针：3 组 query + 三道对照，跑在真实记忆库上
 npm run probe -- --save   # 把这次结果存成基线，之后每次跑自动比对
 npm run bench:check       # 合成基准 + 和 bench/expectations.json 对账（CI 跑的就是它）
+npm run mcp:smoke         # 拿脚本当 MCP 客户端，把服务器拉起来走一遍真实对话
 node bench/longmemeval.mjs --data bench/.tmp/longmemeval_s_cleaned.json   # 公开基准（数据要自己下，264MB）
 ```
 
 CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄悄漂走」的：任何一项
-跟期望值的偏差超过 2 个百分点就红，桥组与 verbatim 组要求满分（它们掉下来就是我们改坏了）。
+跟期望值的偏差超过 2 个百分点就红；桥组容差 3pt、verbatim 组 1pt（它们掉下来多半是我们改坏了）。
 分数低不红 —— 绝对值会随语料演化，卡死绝对值只会逼人去改尺子；漂了才红，因为那说明
 要么是回归、要么是刻意改动而没人说清楚。
 
@@ -626,10 +687,12 @@ CI 跑 `npm test` 和 `npm run bench:check` 两件事。后者是防「数字悄
 | DSH-SEP | 每步 ~1250 字符 guidance + ≤4200 字符快照 | 同上 | 抽取走 `api.deepseek.com` |
 | **本插件** | **0** | **≤480 字符，且只有指针** | **无** |
 
-## 六条被实测证伪的路
+## 八条被实测证伪的路
 
 | 尝试 | 结果 |
 |---|---|
+| 拿「结果要多样」当选桶护栏：MMR / 覆盖优先 | 在 LongMemEval-S 500 题上，MMR（对 tf 集合算 Jaccard，λ 取 0.15 / 0.3 / 0.5）与基线**逐位相同**（87.8% @1）：不同 session 之间几乎不重叠，惩罚项无处发力。覆盖优先 β=1.0 让 @1 从 87.8% 掉到 86.4%，换来的 @5 只有 +0.2pt。机制：我们要解决的是「这个词的重心在别处」，不是「两条结果太像」。跨会话类题目（multi-session 133 题）真正的瓶颈是 gold session 里根本没有问题里的名词 —— 948 个 gold 里 16.5% 与问题零词重叠，19.1% 排在第 6~10 名、39.1% 在第 11~25 名，属于「差一点」，需要的是语义不是重排 |
+| df 下限（把出现在超过一半文档里的词直接扔掉） | LongMemEval-S 上扫描 keep6 / keep12 / 0.7 三档：@1 与基线持平或更差（80.5% vs 81.5%），@5 一点不涨。英文虚词已经由查询侧停用词处理掉，索引侧再删一遍只会顺手动掉 `len` |
 | 伪相关反馈查询扩展（拿 top-1 的高频词再搜一遍，RM3 那一路） | 在 LongMemEval-S 500 题上前 120 题实测：RecallAny@1 从 89.2% 掉到 **48.3%**。机制：扩出来的词全是 top-1 自己的词汇，等于把「已经赢了的文档」又投了一遍票，稍有偏差的第一次命中会被自己的回声推到第一。Recall@5 只涨 0.4pt，@1 腰斩 —— 这种改动在只看 top-5 的评测里会被误认为「有效」 |
 | 提高分数门槛 / IDF 门槛过滤误召回 | 正例最低分 4.59、反例最高分 5.54，区间重叠切不开；IDF 门槛会把 recall 从 28/28 打到 13/28 |
 | freshness 时间衰减（学灵枢 / dsh-mneme） | 六档半衰期扫描：recall 恒为 28/28、top-1 只有一档 +1（噪声级）。库里「旧」的那批恰好是基础事实，衰减就是误伤 |

package/bm25.js

@@ -14,7 +14,22 @@
  */
 
 const K1 = 1.2;
-const B = 0.75;
+/**
+ * 长度归一的强度。0.75 是教科书默认值（也是我们最初抄的值），三把尺子都说它偏大：
+ *
+ * | 尺子 | B=0.75 | B=0.4 |
+ * | --- | --- | --- |
+ * | LongMemEval-S 500 题 | @1 87.8% · @5 97.4% · 覆盖 91.5% · MRR 0.9140 | @1 88.4% · @5 98.2% · 覆盖 92.5% · MRR 0.9196 |
+ * | 合成基准 704 查询 | @1 49.9% · @4 66.6% · verbatim 98.2% | @1 50.4% · @4 67.5% · verbatim 98.7% |
+ * | 真库对照 C（中立那把） | top1 141/181 · @4 168/181 | top1 150/181 · @4 177/181 |
+ *
+ * 机制：同一个词在长会话/长笔记里出现得更多，长度归一按 `len/avgLen` 把整篇压下去；
+ * 当库里绝大多数是长文档时，这个惩罚就变成「谁长谁吃亏」，与相关性无关。
+ * 代价在对照 A 上能看到（top1 45→43），但 A 拿文件名当查询、结构性偏袒短名，
+ * 所以按一直以来的规矩：以对照 C 为准，A/B 只当「别掉分」的底线。
+ * 扫过的值：0.2 / 0.3 / 0.4 / 0.5 / 0.6 / 0.75 / 0.9 —— 0.3~0.5 是一片平台，取中间偏下的 0.4。
+ */
+const B = 0.4;
 
 /**
  * 同义扩展项的权重：字典里搭出来的桥，命中也不该完全压过查询里的原词。

package/mcp.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+/**
+ * 零依赖的 MCP（Model Context Protocol）服务器，走 stdio。
+ *
+ * 为什么有这个东西：检索内核（`bm25.js` + `store.js`）本来就不依赖 DSH ——
+ * 记忆库就是一堆 markdown，索引就是词频。别的宿主（Claude Code、Codex、Cursor…）
+ * 只要支持 MCP，就应该能用同一份库。插件不该被绑死在一个宿主上。
+ *
+ * 四条自我约束（改掉任何一条就等于换了个东西）：
+ * 1. 只用 `node:` 内置模块：零依赖、零子进程、零网络、零模型调用；
+ * 2. **只读**：没有任何写库的接口 —— 闸门、归档、体检那套留在 DSH 那一侧的家用版本里；
+ * 3. 不 import 任何宿主包（`@deepseek-ai/*`）。所以它在别的宿主里最坏是「没被装上」，
+ *    不会因为版本对不上而「装上就崩」；
+ * 4. **stdout 只允许出现协议帧**：日志一律走 stderr，否则客户端解析到一半就崩。
+ *
+ * 用法：`node mcp.js [--store <路径>]`，或者看 README 里各宿主的配置片段。
+ */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline';
+import { pathToFileURL } from 'node:url';
+
+import { buildIndex, search } from './bm25.js';
+import { countLines, DEFAULT_MAX_INDEX_BYTES, DEFAULT_MAX_INDEX_LINES, measureIndex } from './index-guard.js';
+import { corpusFingerprint, readDocs } from './store.js';
+
+export const SERVER_NAME = 'dsh-engramory-recall';
+/** 声明支持的 MCP 协议版本。客户端报的版本在名单里就照它回，否则回我们最新的。 */
+export const PROTOCOL_VERSION = '2025-06-18';
+export const SUPPORTED_PROTOCOL_VERSIONS = new Set([PROTOCOL_VERSION, '2025-03-26', '2024-11-05']);
+export const DEFAULT_STORE = '~/memory/engramory';
+/** 单个工具结果的字符上限：MCP 客户端会把结果塞进上下文，给个天花板。 */
+export const MAX_OUTPUT_CHARS = 40000;
+export const MAX_LIMIT = 20;
+export const DEFAULT_LIMIT = 5;
+
+const pkg = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
+  } catch {
+    return {};
+  }
+})();
+export const SERVER_VERSION = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+
+/** 工具执行失败：message 会原样出现在 isError 的文本里，所以写人话。 */
+export class McpError extends Error {}
+
+export const TOOLS = [
+  {
+    name: 'engramory_search',
+    description:
+      '在本地 Engramory 记忆库里检索相关笔记（BM25 词面检索，含中文分词、同义桥与别名，本机执行、零模型调用）。返回文件名、分数与命中词。',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', description: '查询文本，中英文都行；口语说法会被同义表桥到技术词。' },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: MAX_LIMIT,
+          description: `返回几条，默认 ${DEFAULT_LIMIT}。`,
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'engramory_read',
+    description: '按文件名读出一篇笔记的完整 markdown 原文（只读库根目录下的 .md，不接受路径）。',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { file: { type: 'string', description: '库里的文件名，例如 reference-publish-plugin-to-npm.md' } },
+      required: ['file'],
+    },
+  },
+  {
+    name: 'engramory_status',
+    description: '汇报记忆库的位置、笔记数、索引用量与上限，用来确认客户端读的是不是你以为的那个库。',
+    inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+  },
+];
+
+export const RESOURCE_TEMPLATE = {
+  uriTemplate: 'engramory://note/{file}',
+  name: '一篇笔记',
+  description: '把 {file} 换成 <store> 下的文件名。',
+  mimeType: 'text/markdown',
+};
+
+export function expandHome(value) {
+  const text = String(value ?? '').trim();
+  if (!text) return '';
+  if (text === '~') return homedir();
+  return text.startsWith('~/') ? join(homedir(), text.slice(2)) : text;
+}
+
+/** 库路径：命令行 > 环境变量 ENGRAMORY_STORE > 默认 `~/memory/engramory`。 */
+export function resolveStorePath(raw) {
+  const expanded = expandHome(raw);
+  return expanded ? resolve(expanded) : resolve(expandHome(DEFAULT_STORE));
+}
+
+export function createSession(options = {}) {
+  const raw = options.store ?? process.env.ENGRAMORY_STORE ?? DEFAULT_STORE;
+  return { store: resolveStorePath(raw), storeRaw: String(raw ?? '').trim() || DEFAULT_STORE, index: null, fingerprint: '' };
+}
+
+/** 索引按语料指纹缓存：库被改过就重建，没改过就复用（readDocs 自己也有 mtime 缓存）。 */
+function indexFor(session) {
+  const docs = readDocs(session.store);
+  const fingerprint = corpusFingerprint(docs);
+  if (!session.index || session.fingerprint !== fingerprint) {
+    session.index = buildIndex(docs);
+    session.fingerprint = fingerprint;
+  }
+  return session.index;
+}
+
+/** 库里唯一的笔记（长笔记在索引里会切成多桶，这里按 id 折回一篇）。 */
+function notesOf(session) {
+  const notes = new Map();
+  for (const doc of readDocs(session.store)) {
+    const existing = notes.get(doc.id);
+    if (!existing) notes.set(doc.id, { file: doc.id, title: doc.title || doc.id, description: doc.description || '' });
+    else if (!existing.description && doc.description) existing.description = doc.description;
+  }
+  return [...notes.values()];
+}
+
+function safeNotePath(session, file) {
+  const name = String(file ?? '').trim();
+  if (!name) throw new McpError('需要 file 参数：库里的 markdown 文件名。');
+  if (name !== basename(name) || name.startsWith('.') || !name.endsWith('.md')) {
+    throw new McpError(`不是库里的笔记文件名：${name}。只接受 <store> 下直接的 .md 文件名，不接受路径。`);
+  }
+  const full = join(session.store, name);
+  if (!resolve(full).startsWith(session.store + sep)) throw new McpError(`拒绝越界路径：${name}`);
+  return full;
+}
+
+function readNote(session, file) {
+  const name = String(file ?? '').trim() || basename(safeNotePath(session, file));
+  const full = safeNotePath(session, name);
+  let text;
+  try {
+    text = readFileSync(full, 'utf8');
+  } catch {
+    throw new McpError(`读不到这篇笔记：${name}。用 engramory_status 看库的位置，或 engramory_search 找回文件名。`);
+  }
+  if (text.length > MAX_OUTPUT_CHARS) {
+    return `${text.slice(0, MAX_OUTPUT_CHARS)}\n\n…（笔记超过 ${MAX_OUTPUT_CHARS} 字符，这里截断了；完整原文在 ${name}）`;
+  }
+  return text;
+}
+
+function toolSearch(session, args) {
+  const query = String(args?.query ?? '').trim();
+  if (!query) throw new McpError('需要非空的 query。');
+  const raw = Number(args?.limit);
+  const limit = Number.isFinite(raw) ? Math.min(MAX_LIMIT, Math.max(1, Math.trunc(raw))) : DEFAULT_LIMIT;
+  const docs = readDocs(session.store);
+  if (!docs.length) {
+    throw new McpError(`库是空的或不存在：${session.store}。用 --store <路径> 或环境变量 ENGRAMORY_STORE 指定。`);
+  }
+  const hits = search(indexFor(session), query, limit);
+  const header = `库：${session.store}（${notesOf(session).length} 篇）· 查询：${query}`;
+  if (!hits.length) return `${header}\n没有命中。换个词，或先用 engramory_status 确认库对不对。`;
+  const lines = hits.map((hit, i) => {
+    const snippet = String(hit.snippet || '').replace(/\s+/g, ' ').trim();
+    const matched = Array.isArray(hit.matched) && hit.matched.length ? hit.matched.join('、') : '—';
+    return [`${i + 1}. ${hit.id} · ${Number(hit.score).toFixed(2)}`, `   ${snippet}`, `   命中：${matched}`].join('\n');
+  });
+  return [header, ...lines].join('\n');
+}
+
+function toolStatus(session) {
+  const notes = notesOf(session);
+  let indexText = '';
+  try {
+    indexText = readFileSync(join(session.store, 'MEMORY.md'), 'utf8');
+  } catch {
+    /* 索引缺失不是错误：没有索引也能按正文召回，只是宿主不会自动打开它。 */
+  }
+  // measureIndex 返回的是「超限时的人话描述 / 没超时 null」，行数与字节数得自己数。
+  const over = measureIndex(indexText, DEFAULT_MAX_INDEX_LINES, DEFAULT_MAX_INDEX_BYTES);
+  const indexLine = indexText
+    ? `索引：${countLines(indexText)} 行 / ${Buffer.byteLength(indexText)} 字节（上限 ${DEFAULT_MAX_INDEX_LINES} 行 / ${DEFAULT_MAX_INDEX_BYTES} 字节${over ? `，已超限：${over}` : ''}）`
+    : '索引：没有 MEMORY.md（召回仍可用，但宿主没有索引可读）';
+  return [
+    `库：${session.store}`,
+    `笔记：${notes.length} 篇`,
+    indexLine,
+    `指纹：${corpusFingerprint(readDocs(session.store)).slice(0, 12) || '（空库）'}`,
+    `服务器：${SERVER_NAME} ${SERVER_VERSION} · 只读 · 零模型调用`,
+  ].join('\n');
+}
+
+const HANDLERS = {
+  engramory_search: toolSearch,
+  engramory_read: (session, args) => readNote(session, args?.file),
+  engramory_status: toolStatus,
+};
+
+export async function callTool(session, params) {
+  const name = String(params?.name ?? '');
+  const handler = HANDLERS[name];
+  if (!handler) {
+    return { content: [{ type: 'text', text: `没有这个工具：${name}。可用：${Object.keys(HANDLERS).join(' / ')}` }], isError: true };
+  }
+  try {
+    return { content: [{ type: 'text', text: String(handler(session, params?.arguments ?? {})) }], isError: false };
+  } catch (error) {
+    const text = error instanceof McpError ? error.message : `工具 ${name} 出错：${error?.message ?? error}`;
+    return { content: [{ type: 'text', text }], isError: true };
+  }
+}
+
+export function listResources(session) {
+  return {
+    resources: notesOf(session).map((note) => ({
+      uri: `engramory://note/${note.file}`,
+      name: note.file,
+      title: note.title,
+      description: note.description || undefined,
+      mimeType: 'text/markdown',
+    })),
+  };
+}
+
+export function readResource(session, params) {
+  const uri = String(params?.uri ?? '');
+  const prefix = 'engramory://note/';
+  if (!uri.startsWith(prefix)) throw new McpError(`只认得 ${prefix}<文件名> 这种 URI，收到的是：${uri}`);
+  const file = decodeURIComponent(uri.slice(prefix.length));
+  return { contents: [{ uri, mimeType: 'text/markdown', text: readNote(session, file) }] };
+}
+
+function initializeResult(params) {
+  const asked = String(params?.protocolVersion ?? '');
+  return {
+    protocolVersion: SUPPORTED_PROTOCOL_VERSIONS.has(asked) ? asked : PROTOCOL_VERSION,
+    capabilities: { tools: { listChanged: false }, resources: { listChanged: false, subscribe: false } },
+    serverInfo: { name: SERVER_NAME, version: SERVER_VERSION, title: 'Engramory 记忆召回（本地 markdown，只读）' },
+    instructions:
+      '这是本机 markdown 记忆库的只读检索。先用 engramory_search 找相关笔记，再用 engramory_read 打开需要的那些；' +
+      '不要假设库里有什么，也不要通过它写任何东西。',
+  };
+}
+
+const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+const fail = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/** 处理一条 JSON-RPC 消息；通知返回 null（协议规定通知不回包）。 */
+export async function handleMessage(session, message) {
+  if (!message || typeof message !== 'object' || Array.isArray(message)) {
+    return fail(null, -32600, 'Invalid Request：只接受单条 JSON-RPC 2.0 对象（不支持批量）。');
+  }
+  const { id, method } = message;
+  const notification = id === undefined || id === null;
+  if (typeof method !== 'string') {
+    return notification ? null : fail(id, -32600, 'Invalid Request：method 必须是字符串。');
+  }
+  if (method.startsWith('notifications/')) return null;
+  try {
+    switch (method) {
+      case 'initialize':
+        return ok(id, initializeResult(message.params));
+      case 'ping':
+        return ok(id, {});
+      case 'tools/list':
+        return ok(id, { tools: TOOLS });
+      case 'tools/call':
+        return ok(id, await callTool(session, message.params));
+      case 'resources/list':
+        return ok(id, listResources(session));
+      case 'resources/templates/list':
+        return ok(id, { resourceTemplates: [RESOURCE_TEMPLATE] });
+      case 'resources/read':
+        return ok(id, readResource(session, message.params));
+      case 'prompts/list':
+        return ok(id, { prompts: [] });
+      default:
+        if (notification) return null;
+        return fail(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (error) {
+    const text = error instanceof McpError ? error.message : `内部错误：${error?.message ?? error}`;
+    return notification ? null : fail(id, -32603, text);
+  }
+}
+
+/** stdio 主循环：一行一条消息，stdout 只写协议帧。 */
+export async function serveStdio(session, options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  const pending = [];
+  rl.on('line', (line) => {
+    const text = line.trim();
+    if (!text) return;
+    let message;
+    try {
+      message = JSON.parse(text);
+    } catch {
+      output.write(`${JSON.stringify(fail(null, -32700, 'Parse error：这一行不是合法 JSON。'))}\n`);
+      return;
+    }
+    // 逐条串行处理：保证响应顺序与请求顺序一致（工具调用本身很快，不值得为并发引入状态问题）。
+    const task = (pending.at(-1) ?? Promise.resolve())
+      .then(() => handleMessage(session, message))
+      .then((response) => {
+        if (response) output.write(`${JSON.stringify(response)}\n`);
+      })
+      .catch((error) => {
+        output.write(`${JSON.stringify(fail(message?.id ?? null, -32603, String(error?.message ?? error)))}\n`);
+      });
+    pending.push(task);
+    if (pending.length > 64) pending.shift();
+  });
+  await new Promise((done) => rl.on('close', done));
+  await Promise.all(pending);
+}
+
+export const USAGE = `用法：node mcp.js [--store <路径>] [--print-config] [--version] [--help]
+
+零依赖、只读的 MCP stdio 服务器：把 Engramory markdown 记忆库暴露成
+engramory_search / engramory_read / engramory_status 三个工具。
+库路径优先级：--store > 环境变量 ENGRAMORY_STORE > ${DEFAULT_STORE}
+日志一律写 stderr；stdout 只有 JSON-RPC 帧。`;
+
+export function parseArgs(argv) {
+  const args = { store: '', help: false, version: false, printConfig: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--store') args.store = argv[++i] ?? '';
+    else if (arg.startsWith('--store=')) args.store = arg.slice('--store='.length);
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--version' || arg === '-v') args.version = true;
+    else if (arg === '--print-config') args.printConfig = true;
+    else if (arg.trim()) args.error = `听不懂的参数：${arg}`;
+  }
+  return args;
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.error) {
+    process.stderr.write(`${args.error}\n\n${USAGE}\n`);
+    return 2;
+  }
+  if (args.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  if (args.version) {
+    process.stdout.write(`${SERVER_VERSION}\n`);
+    return 0;
+  }
+  const session = createSession({ store: args.store || undefined });
+  if (args.printConfig) {
+    process.stdout.write(`${JSON.stringify({ name: SERVER_NAME, version: SERVER_VERSION, store: session.store })}\n`);
+    return 0;
+  }
+  process.stderr.write(`[${SERVER_NAME}] 库：${session.store} · 只读 · 日志只走 stderr\n`);
+  await serveStdio(session);
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (error) => {
+      process.stderr.write(`[${SERVER_NAME}] 退出：${error?.stack ?? error}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "Local BM25 auto-recall, fail-closed write guard, static doctor and a memory panel for the Engramory markdown store — no network, no model, no daemon.",
   "keywords": [
     "dsh",
@@ -37,7 +37,8 @@
     "./index-guard": "./index-guard.js",
     "./skill": "./skill.js",
     "./llm": "./llm.js",
-    "./index": "./index.js"
+    "./index": "./index.js",
+    "./mcp": "./mcp.js"
   },
   "files": [
     "index.js",
@@ -51,6 +52,7 @@
     "index-guard.js",
     "skill.js",
     "llm.js",
+    "mcp.js",
     "CHANGELOG.md",
     "cordis.patch.yml",
     "README.md"
@@ -73,6 +75,10 @@
     "check": "node scripts/check-recall-wiring.mjs",
     "probe": "node scripts/recall-probe.mjs",
     "bench": "node bench/run.mjs",
-    "bench:check": "node bench/run.mjs --check"
+    "bench:check": "node bench/run.mjs --check",
+    "mcp:smoke": "node scripts/mcp-smoke.mjs"
+  },
+  "bin": {
+    "engramory-recall-mcp": "./mcp.js"
   }
 }