Skip to content

Commit 4bed661

Browse files
committed
feat(provenance): 蒸馏归因补上 run 概念——窗口级与行级两层,历史链接不猜(#512)
#421 的溯源读出口回答的是「这条记忆蒸自哪几句原文」,回答不了一直被问的那件事: 同一段原文被重蒸过几次、哪一轮失败了。memory_provenance 的粒度是 (memory, 会话, seq 区间),区间是**输入**的坐标,不是**运行**的身份; distill_run_id / run_type / trigger_source 三个键此前全仓零命中——不是出口少透 一个字段,是库里根本没存。 归因拆成两层,因为它们回答的不是同一个问题: - 窗口级:memory_provenance.distill_run_id → 新表 distill_runs。一次蒸馏落一行 (status / error / session_id / seq_start / seq_end / memory_count / provider / model / audit_id),只由按窗口写入的 autoSummarize 路径填。 - 行级:新表 memory_mints(memory_id, run_id)。记「这条记忆出生自哪一轮巩固」, 由 dream / sleep 的 create 动作填。 行级为什么另开一张表:dream / sleep 铸造的 pattern 没有会话区间——session 与 seq 都不存在,把合成区间塞进 memory_provenance 就是编造坐标,而一个错的坐标比没有坐标 更坏(它看起来完全合法,会让「能追到」变成谎话)。 行级为什么只填 create:merge / conflict / update / supersede 动的是既有行, receipt_chain 早已按 (run_id, record_id) 记过;再造一份就是第二套账。 为什么不复用 llm_audit_logs.id 当 run id:llmAudit.retentionDays 到期裁剪会删掉 audit 行,归因会跟着悬空;而 memory_provenance 刻意活得比原文更久。所以 run 是 归因主体、audit 行只是它的开销读数,两边靠 distill_runs.audit_id 连——不靠时间戳 猜,先写 audit 拿 id、再落 run。 为什么不复用 dream_runs:那张表每一列都是巩固语义(snapshot_hash / input_count / decisions / outcome / receipt),「每行都能回放一次巩固」是它对消费方的契约。硬塞 run_type='autoSummarize' 会让这条契约失效。dream / sleep 的轮次仍只记在 dream_runs,不复制进 distill_runs。 历史行不猜:迁移只加列 / 加表,存量 distill_run_id 一律 NULL,反推一个「看起来能 追」的合成 id 是最坏的一种坏(读数正常、实际是编的),口径与 #534 的 raw_output 同源。面板遇到 NULL 显示「无运行归因(历史行)」而不是空白。 失败轮也记账:status 取 ok|degraded|noop|failed|aborted,模型侧流失败与解析失败都 留一行 failed,只有 dispose / 会话关闭才是 aborted。这两条出口原先根本不设状态, 于是失败轮一行 run 都不落——「跑过但失败了」与「压根没跑」在台账上长得一样。 不新增开关:这是记账,记账默认就该在;多一个键要多一份白名单 + schema + 旗标计数锁。 读出口:/memory/provenance 的窗口带 distill_run_id / run_type / trigger_source / run_status(读不到整组 null),答复级另带 mints[]。面板详情抽屉新增「蒸发归因」区块。 回归测试 +14(store 5 / summarize 4 / mint-source 4 / client 1),每条都做过变异自证。 其中 mint-source 的 sleep 用例首跑就抓到 phasePatterns 调 applyDecisions 时漏传 runId——正文注释写着「runId 让账本行能追到哪一轮」,而 sleep 这条真实铸造路径一直 没给,铸造出的 pattern 只能追到管道、追不到哪一轮,正是本条要补的口子。
1 parent 35a79c1 commit 4bed661

25 files changed

Lines changed: 1151 additions & 65 deletions

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3E63DD?style=flat-square" alt="license"></a>
1111
<a href="https://github.com/slow-stack/mneme/actions"><img src="https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml?style=flat-square&label=CI" alt="CI"></a>
1212
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-22%2B-3E63DD?style=flat-square&logo=nodedotjs&logoColor=white" alt="node"></a>
13-
<a href="https://github.com/slow-stack/mneme"><img src="https://img.shields.io/badge/tests-2577%20passed-3E63DD?style=flat-square" alt="tests"></a>
13+
<a href="https://github.com/slow-stack/mneme"><img src="https://img.shields.io/badge/tests-2625%20passed-3E63DD?style=flat-square" alt="tests"></a>
1414
<a href="https://codecov.io/gh/slow-stack/mneme"><img src="https://img.shields.io/codecov/c/github/slow-stack/mneme/main?style=flat-square" alt="coverage"></a>
1515
<a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome"></a>
1616
</p>
@@ -270,7 +270,7 @@ dsh-mneme-serve # 默认 ~/.dsh/memory + 127.0.0.1:8790
270270

271271
```bash
272272
cd dsh-mneme && npm install
273-
npm test # 2577 个测试
273+
npm test # 2625 个测试
274274
npm run stress # 三轴线压测
275275
npm run sync # src → lib 同步
276276
```
@@ -550,7 +550,7 @@ Community projects that wire mneme into more platforms — not part of this repo
550550

551551
```bash
552552
cd dsh-mneme && npm install
553-
npm test # 2577 tests
553+
npm test # 2625 tests
554554
npm run stress # three-axis stress test
555555
npm run sync # src → lib sync
556556
```

‎SECURITY.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -299,6 +299,7 @@ All plugin-side audit data is stored **locally** in the plugin database and neve
299299
| `recall_run` search logs | Local database | Every search is recorded with timestamp and query metadata |
300300
| AutoDream receipts | Local database + Markdown mirror | Cryptographically verifiable; persist until user deletes them |
301301
| `distill_records` raw window text (#399) | Local database | **Opt-in, off by default.** Only when `distillRecords.enabled: true`: the raw prompt/answer text of distilled windows is kept verbatim (no truncation), capped by `retentionDays` (default 90). Never includes private reasoning, plugin-injected content, tool arguments or tool output. Retention trims the text only — provenance links stay (they point at an empty range, shown as "source expired") |
302+
| `distill_runs` run ledger + `memory_mints` (#512) | Local database | Attribution metadata only — **no conversation text**. `distill_runs` records one row per distillation *round* (status, window range, memory count, provider/model, and `audit_id` joining the spend row); `memory_mints` records which run minted a given memory. Both live as long as the library does; unlike the raw text above they are not covered by `distillRecords.enabled` (they contain no transcript). Rows written before this change are left **NULL / absent on purpose**: guessing an attribution is worse than not having one |
302303
| Dependency scan reports | GitHub Security tab (code scanning / Dependabot) | Not stored on device |
303304

304305
Retention is user-controlled: audit records live only as long as the local database does. There is no remote logging and no telemetry.
@@ -539,7 +540,7 @@ Token 是**写**面上的锁,不是把整个 API 围起来的墙。
539540
- **真正的边界是回环 + 宿主监听器。** 宿主侧路由(`/api/dsh-mneme/*`)挂在 DSH 端口上,该端口绑 `127.0.0.1`,并由宿主挡掉 DNS rebinding 与跨站浏览器请求。这道围栏**不建立身份**:任何本地进程、以及任何跑在宿主同源页面里的脚本,都在这道围栏之内。
540541
- **鉴权是 opt-in 且 fail-open。** `apiToken` 默认为空;为空期间 `isAuthorized()` 对每个请求都返回 true——读和写都放行。配了 token 之后,它守的是写路由与敏感读,不守普通读。
541542
- **开放读(即使配了 token 也不需要)**:`GET /`、`/info`、`/version-check`、`/list`、`/recall-stats`、`/search`、`/semantic`、`/semantic/llm-audit`、`/semantic/llm-audit/stats`、`/semantic/graph/*`、`/entities`、`/memories/entities`、`/dream-status`、`/inject-status`、`/inject-preview`、`/pipeline`、`/candidates`、`/llm-providers`,以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands`、`/nudge`、`/receive`、`/receive/undo` 的 `GET`/`HEAD` 分支。把它们当作「本地任何东西都能读」。`/receive`、`/receive/undo` 明明是写路由也出现在这一串里,这不是笔误:`token-write` 下 `needsToken()` 对 `GET`/`HEAD` 免 token,所以这两条路径上真正「开放」的只有一个 `405`,压根没有可读分支。这一节照 policy 声明抄、不照意图写,`dsh-mneme/test/security-doc.test.js` 会拿真实装配出来的路由双向比对这两行。
542-
- **受门控的路由(配了 token 之后)**:全部写操作——`/create`、`/update`、`/delete`、`/import`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/conflicts/resolve`、`/profile/extract`(只收 POST:花一次宿主 LLM 产一段画像**草稿**,其它方法在产生任何副作用之前就 405)、`/receive`、`/receive/undo`(这两条写的是**本机自己的库**,所以归 `token-write`),以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands`、`/nudge` 的非 `GET` 分支——外加六条读:`/export`、`/external-api`、`/conflicts`、`/health`、`/share`(分享包是「用 POST 递出来的全库读取」,GET 一律 405,没有开放的读分支)、`/memory/provenance`(它回的是蒸馏窗口的**逐字会话原文**,`distillRecords.enabled` 打开才有;否则把它和上面那个开放的列表路由串起来,任何本地进程都能先枚举 id、再按 id 把那些原文捞回去——可达结果与 `/export`(一次拿全库)同量级,只是换了形状)。
543+
- **受门控的路由(配了 token 之后)**:全部写操作——`/create`、`/update`、`/delete`、`/import`、`/vector-config`、`/vector-reindex`、`/runtime/provision`、`/maintenance/reclaim`、`/test-model`、`/conflicts/resolve`、`/profile/extract`(只收 POST:花一次宿主 LLM 产一段画像**草稿**,其它方法在产生任何副作用之前就 405)、`/receive`、`/receive/undo`(这两条写的是**本机自己的库**,所以归 `token-write`),以及 `/profile`、`/rules`、`/persona`、`/mode`、`/features`、`/commands`、`/nudge` 的非 `GET` 分支——外加六条读:`/export`、`/external-api`、`/conflicts`、`/health`、`/share`(分享包是「用 POST 递出来的全库读取」,GET 一律 405,没有开放的读分支)、`/memory/provenance`(它回的是蒸馏窗口的**逐字会话原文**,并自 #512 起按窗口带出 `distill_run_id` / `run_type` / `trigger_source` / `run_status` 的运行归因;`distillRecords.enabled` 打开才有;否则把它和上面那个开放的列表路由串起来,任何本地进程都能先枚举 id、再按 id 把那些原文捞回去——可达结果与 `/export`(一次拿全库)同量级,只是换了形状)。
543544
- **独立数据面**(`127.0.0.1:8790`)是反过来的形状:除 `GET /health` 外每条路由都要自己的 Bearer token。因此把 `externalApiHost` 指向非回环地址,就等于把它变成一个「明文、只靠 token」的 HTTP 面——这是运营者的显式决定。
544545
- **推论**:如果你把插件暴露到回环之外(反代、绑非回环地址),请设 `apiToken`,**并**核对上面那串开放读是否也能被看到——它们不受 token 保护。
545546
- **这张表怎么保持为真**:每条路由在注册时自己声明 `policy`(`open` / `token` / `token-write`),`createRouteRegistrar` 在路由没声明或复用同一路径时直接抛错。新路由忘了归类会**启动失败**,而不是静默开门。上面两张清单还会被 `dsh-mneme/test/security-doc.test.js` 拿真实装配出来的路由做双向比对——加了路由却不更新这一节,CI 会红,而不是悄悄漂走。这张矩阵来自代码,不来自谁的记忆。
@@ -683,6 +684,7 @@ Token 是**写**面上的锁,不是把整个 API 围起来的墙。
683684
| `failure_memories` 审计日志 | 本地数据库 | 每次写入失败均记录,供取证分析 |
684685
| `recall_run` 搜索日志 | 本地数据库 | 每次搜索均记录时间戳和查询元数据 |
685686
| AutoDream receipts | 本地数据库 + Markdown 镜像 | 密码学可验证;保留至用户删除 |
687+
| `distill_runs` 运行台账 + `memory_mints` 铸造归因(#512) | 本地数据库 | 只有归因元数据,**不含任何会话正文**。`distill_runs` 一次蒸馏落一行(状态、窗口区间、记忆条数、provider/model,以及连到开销行的 `audit_id`);`memory_mints` 记「这条记忆出生自哪一轮」。两者随库存续,**不受** `distillRecords.enabled` 约束(里面没有转录文本)。改造之前写下的行**刻意留 NULL / 不补**:猜一个归因比没有归因更坏 |
686688
| `distill_records` 蒸馏窗口原文(#399) | 本地数据库 | **opt-in,默认关。** 仅当 `distillRecords.enabled: true` 时:被蒸馏窗口的用户提示与助手公开正文**逐字留存**(不截断),受 `retentionDays`(默认 90)约束。**绝不**包含私有推理链、插件注入的机器内容、工具入参与工具输出。到期裁剪只删原文,溯源链接保留(指向空区间,显示「来源已过期」) |
687689
| 依赖扫描报告 | GitHub Security 标签页(code scanning / Dependabot) | 不存储于设备 |
688690

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
## 🆕 新增
66

7+
- **蒸馏归因只到「会话区间」、到不了「哪一次蒸馏」:同一段原文被重蒸过几次、哪一轮失败了,库里一个字都没存(#512,提案与实测由 @modusensus 提供)**:#421 的溯源读出口(#509)能让「这条记忆蒸自哪几句原文」被查到,但它回答的一直是 `哪一段`,不是 `哪一轮`。`memory_provenance` 的粒度是 (memory, 会话, seq 区间),区间是**输入**的坐标,不是**运行**的身份;`distill_run_id` / `run_type` / `trigger_source` 三个键全仓零命中——不是出口少透一个字段,是库里根本没存。对照 `autoDream` 每轮一行 `dream_runs`、可审计可回放,`autoSummarize` 只在 `llm_audit_logs` 留一条计费痕迹且不与归因链接。于是「这个窗口为什么一直没有记忆」只能靠逐帧解压宿主日志去对,而审计行里的 token 数说明不了哪一步塌了。**归因拆成两层,因为它们回答的不是同一个问题**:① **窗口级** `memory_provenance.distill_run_id` → 新表 `distill_runs`(一次蒸馏落一行:`status` / `error` / `session_id` / `seq_start` / `seq_end` / `memory_count` / `provider` / `model` / `audit_id`),只由按窗口写入的 `autoSummarize` 路径填;② **行级** 新表 `memory_mints(memory_id, run_id)`,记「这条记忆出生自哪一轮巩固」,由 `dream` / `sleep` 的 create 动作填。**行级为什么另开一张表**:dream / sleep 铸造的 pattern 没有会话区间——session 与 seq 都不存在,把合成区间塞进 `memory_provenance` 就是编造坐标,而一个错的坐标比没有坐标更坏(它看起来完全合法,会让「能追到」变成谎话)。**行级为什么只填 create**:merge / conflict / update / supersede 动的是既有行,`receipt_chain` 早已按 (run_id, record_id) 记过;再造一份就是第二套账,两边迟早对不上。create 是那边唯一的洞——`buildOutcome` 刻意不给 create 派 disposition,`receipt_chain` 也就不产行。**为什么不复用 `llm_audit_logs.id` 当 run id**:`llmAudit.retentionDays` 到期裁剪会删掉 audit 行(`src/index.js` 启动即调 `deleteOldLlmAudits`),归因会跟着悬空;而 `memory_provenance` 刻意活得比原文更久(#399 的「来源已过期」正是这条设计的产物)。所以 run 是**归因主体**、audit 行只是它的**开销读数**,两边靠 `distill_runs.audit_id` 连,**不是靠时间戳猜**——先写 audit 拿 id、再落 run,顺序不能反。**为什么不复用 `dream_runs`**:那张表每一列都是巩固语义(`snapshot_hash` / `input_count` / `decisions` / `outcome` / `receipt`),「每行都能回放一次巩固」是它对消费方的契约;硬塞 `run_type='autoSummarize'` 会让这条契约失效,而一个字段两种含义是这套 schema 里最容易腐烂的设计。dream / sleep 的轮次仍只记在 `dream_runs`、**不复制**进 `distill_runs`——两张表各说一件事,比一张表说两件事好。**历史行不猜**:迁移只加列 / 加表,存量 `memory_provenance.distill_run_id` 一律 NULL;反推一个「看起来能追」的合成 id 是最坏的一种坏(读数正常、实际是编的),口径与 #534 的 `raw_output`「历史失败轮反推不出原文」同源。面板遇到 NULL 显示「无运行归因(历史行)」,不是空白——空白会被读成「这里本来就没有东西」。**失败轮也记账**:`status` 取 `ok | degraded | noop | failed | aborted`,模型侧流失败与解析失败都留一行 `failed`,只有 dispose / 会话关闭才是 `aborted`(这一轮被主动打断)。这两条出口原先根本不设状态,于是失败轮一行 run 都不落——「跑过但失败了」与「压根没跑」在台账上长得一模一样,正是本条要消灭的那种静默。**不新增开关**:这是记账,记账默认就该在(与 #521 的「只加观测、不动判定」同一条原则),多一个键就要多一份白名单 + schema + 旗标计数锁。**面板**:详情抽屉新增「蒸发归因」区块,同时渲染两层;拉不到时是「没有归因」而不是空白,历史行单独标「无运行归因」。**读出口**:`GET /api/dsh-mneme/memory/provenance?memoryId=` 的窗口按上表带上 `distill_run_id / run_type / trigger_source / run_status`(读不到整组 null),答复级另带 `mints[]`。**回归测试 +14**(`test/store.test.js` 5 条:老库补列补表且存量链接留 NULL、重开已升级的库幂等且不动已落盘的归因、同 id replay 覆写而不重复、`audit_id` 事后补注且补不存在的 run 返回 0、同一 (记忆, run) 只记一次且删记忆时显式清掉归因;`test/summarize.test.js` 4 条:一个窗口一行 run 且每条链接都指向它、run 与开销行靠 `audit_id` 而不是时间戳相连、`llmAudit` 关掉时 run 照落、失败轮仍留一行说它失败了;`test/mint-source.test.js` 4 条:create 记得住是哪一轮铸的它、不给 run id 时不编造记录、改动既有行不进 `memory_mints`、sleep 铸造的 pattern 指回真正那一轮;`test/client.test.js` 1 条:抽屉同时渲染两层归因)。变异自证:面板那条最初只断言 `includes("provenance.mints")`,被空态判断里的 `provenance.mints.length` 满足、改坏了仍绿——**断到 `.map(` 为止才咬得住**;另外 `test/mint-source.test.js` 的 sleep 用例首跑就抓到 `phasePatterns` 调 `applyDecisions` 时**漏传 `runId`**(正文注释写着「runId 让账本行能追到哪一轮」,而 sleep 这条真实铸造路径一直没给),漏了它铸造出的 pattern 只能追到 sleep 这条管道、追不到哪一轮——正是本条要补的口子。
8+
79
- **会话级无痕闸门:指定会话与子代理「不进不出」,其余会话照常(#539,实现由 @wuchichiumike 在 #540 贡献)**:AgentTeams / subagent 的一次性会话也会拿到 Mneme 注入并写进同一个库,而此前能关的只有全局——关插件或关 `autoSummarize` 会连带打死别的会话,#471 的 scopeState 又是 agent/workspace 级政策、且本来就不阻断保存。这一版加的是**逐会话**判定:命中会话不注入记忆 / 用户设置 / 工具指引,不接受其 `memory_*` 与 `set_scope_state` 调用(拒绝发生在任何副作用之前),不对它蒸馏,压缩抢救 / M.O. 记账 / 自动提议三条写路径同样早退。
810

911
三个键全部 **opt-in**:`sessionGateEnabled`(默认 `false`,总闸)、`sessionGateSubagents`(默认 `true`,总闸开启时自动命中子代理)、`sessionGateSessions`(默认 `[]`,手动 id 名单,两者 OR)。`sessionGateEnabled` / `sessionGateSubagents` 进 `settings.js` 白名单并可走 `/features`(重启生效),`sessionGateSessions` 是数组、只能写在 bundle 配置。

0 commit comments

Comments
 (0)