Skip to content

Commit 20ea72e

Browse files
committed
feat(document): 升格吸收的 evidence 随之归档 + 归档侧第五指标(#275)
拍板 5 与第五指标的实现侧条目: 1. registerDocument 成功后,同一事务把被吸收的 evidence 行翻归档(只翻标志位,内容 与审计全留,可恢复):constraint/preference 永不自动归档;document 与 summary 两类不吸收(各有自己的生命周期,归档它们会让同一路径或同源总览多出一行); opt-out 走 keep_evidence_active 或 archiveEvidence:false。 2. 重注册同一份文档时,被它自己吸收过的已归档 id 仍算它的 evidence,不会被捏造判据 误报;别的文档引用这些 id 照旧拒绝。 3. recall-stats 新增 archive 块:归档净增速率(total/addedInWindow/perDay)与可压掉 行数(同 type 同 scope 的内容哈希精确重复);面板「记忆复用」卡与 STORAGE.md 同步。 已知近似写在 recall-stats.js 文件头与 STORAGE.md:归档时刻取 updated_at,精确口径要 archived_at 列,属第二批题材。
1 parent 795cc1e commit 20ea72e

12 files changed

Lines changed: 512 additions & 38 deletions

File tree

‎dsh-mneme/docs/STORAGE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,25 @@ VACUUM 是 O(库大小),且需要排他写锁:库越大越慢,期间的写
6565
- 窗口内(默认 7 天)的输入快照不动:近期 run 仍可能在离线回放里被用到。
6666
- `run_type='organize'` 的行任何窗口都不清:它们的 `input` 存的是 apply 的重放载荷(`src/organize.js` 直接读它重建候选索引),不是可重建的快照。置空会让那次 apply 静默空转并把报告锁死。
6767

68+
## 升格吸收的 evidence(#230 × #275)
69+
70+
`memory_register_document` 注册成功后,这份文档引用的 evidence 行会**在同一事务里**翻成归档(absorbed)。一次吸收 20 条,活跃面就少 20 行——而不是「21 行不是 1 行」。
71+
72+
- 只翻标志位:内容、`content_history`、审计行一条不删,随时可以还原;
73+
- `constraint` / `preference` 永不自动归档(#249 的逐字保真池),要归档得手动来;
74+
- 只吸收**原子条**:别的 `document` 行与 `summary` 行不碰——前者本体是磁盘上的文件(归档它会让同一路径下次注册留下第二行),后者是 dream 总览与叙述(按 source 身份去重、按注入档位常驻);
75+
- 想保留活跃面:工具带 `keep_evidence_active: true`(注册器参数是 `archiveEvidence: false`);
76+
- 重注册同一份文档(出新版)时,那些已归档的 evidence 行仍可为**它所属的那份文档**背书;换个文档拿归档 id 当证据,照旧按捏造拒绝。
77+
78+
## 第五指标:归档净增速率 + 可压掉行数
79+
80+
面板「记忆复用」卡与 `GET /api/dsh-mneme/recall-stats` 的返回里多了一个 `archive` 块(#275 拍板:与既有指标同位):
81+
82+
- `total` / `addedInWindow` / `perDay`:归档区现有行数、窗口内新进的、以及日均净增速率。归档时刻取行的 `updated_at`(`setArchived` 会刷它)——代理口径:再改一次已归档行就会被算进本窗口,精确口径要一个 `archived_at` 列(属第二批题材);
83+
- `compressible.rows` / `.groups`:**可压掉行数**——同 type、同 scope、内容归一化后逐字节相同的归档行里,每组留下的那一行之外的那些。判据用内容哈希(与写入准入同一把尺),**不**建在向量近重复上:回收动作本身就会清掉归档行的向量,指标不能指望自己的输入还在。
84+
85+
这是观察口,不是动作触发:真删仍属第二批(未立项)。
86+
6887
## 与 #254 的分界
6988

7089
本入口止体积、不止重复。归档区里同主题条目堆积是**出口**问题,归 #254 的写入准入与后续整理动作面;这里一条记忆都不碰(维护者拍板 4)。

‎dsh-mneme/lib/client.js‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -559,6 +559,7 @@ window.__ModuleLoader__.load({
559559
"memory.status.recallStats": "记忆复用",
560560
"memory.status.recallHint": "复用率 {rate} · 僵尸 {zombie}/{active}(豁免 {exempt})· 30 天回执 {runs} 次 · Top:{top}",
561561
"memory.status.recallInject": "注入 {runs} 轮 {count} 条,槽位填充 {fill}%",
562+
"memory.status.recallArchive": "归档 {total} 行({add}/天),精确重复可压掉 {compress} 行",
562563
"memory.status.viewAll": "查看全部",
563564
"memory.status.depositedCount": "沉淀的记忆({n})",
564565
"memory.status.archivedCount": "已归档的记忆({n})",
@@ -946,6 +947,7 @@ window.__ModuleLoader__.load({
946947
"memory.status.recallStats": "Recall reuse",
947948
"memory.status.recallHint": "reuse {rate} · zombie {zombie}/{active} (exempt {exempt}) · {runs} runs in 30d · top: {top}",
948949
"memory.status.recallInject": "injected {runs} turns · {count} items ({fill}% slots)",
950+
"memory.status.recallArchive": "archived {total} rows (+{add}/day) · {compress} exactly-duplicate rows compressible",
949951
"memory.status.viewAll": "View all",
950952
"memory.status.depositedCount": "Deposited memories ({n})",
951953
"memory.status.archivedCount": "Archived memories ({n})",
@@ -3613,7 +3615,7 @@ window.__ModuleLoader__.load({
36133615
// 口径不可信)或库为空时整卡不渲染,前端不感知;truncated(扫描超上限)
36143616
// 只影响 hint 里的回执计数,不挡渲染。
36153617
function RecallStatsCard({ t }) {
3616-
const [state, setState] = useState({ loading: true, off: false, rate: null, zombie: 0, active: 0, exempt: 0, runs: 0, top: "", inject: "" });
3618+
const [state, setState] = useState({ loading: true, off: false, rate: null, zombie: 0, active: 0, exempt: 0, runs: 0, top: "", inject: "", archive: "" });
36173619
useEffect(() => {
36183620
let cancelled = false;
36193621
apiFetch("/api/dsh-mneme/recall-stats?window=30")
@@ -3638,10 +3640,19 @@ window.__ModuleLoader__.load({
36383640
.replace("{count}", String(inj.injectedCount ?? 0))
36393641
.replace("{fill}", inj.slotFillRate == null ? "—" : String(Math.round(inj.slotFillRate * 100)))
36403642
: "";
3643+
// 第五指标(#275):归档净增速率 + 可压掉行数。与注入口径同款自门控
3644+
// ——归档区为空时整段省略,不往卡里塞一个恒 0 的数字。
3645+
const ar = d.archive || {};
3646+
const archive = (ar.total ?? 0) > 0
3647+
? t("memory.status.recallArchive")
3648+
.replace("{total}", String(ar.total ?? 0))
3649+
.replace("{add}", String(ar.perDay ?? 0))
3650+
.replace("{compress}", String(ar.compressible?.rows ?? 0))
3651+
: "";
36413652
setState({
36423653
loading: false, off: false, rate,
36433654
zombie: z.zombieCount ?? 0, active: z.activeCount ?? 0,
3644-
exempt: z.exemptCount ?? 0, runs: d.coverage?.runsScanned ?? 0, top, inject
3655+
exempt: z.exemptCount ?? 0, runs: d.coverage?.runsScanned ?? 0, top, inject, archive
36453656
});
36463657
})
36473658
.catch(() => { if (!cancelled) setState({ loading: false, off: true }); });
@@ -3660,7 +3671,7 @@ window.__ModuleLoader__.load({
36603671
.replace("{active}", String(state.active))
36613672
.replace("{exempt}", String(state.exempt))
36623673
.replace("{runs}", String(state.runs))
3663-
.replace("{top}", state.top || "—") + (state.inject ? " · " + state.inject : "")
3674+
.replace("{top}", state.top || "—") + (state.inject ? " · " + state.inject : "") + (state.archive ? " · " + state.archive : "")
36643675
});
36653676
}
36663677

‎dsh-mneme/lib/document.js‎

Lines changed: 61 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -60,20 +60,34 @@ export function isManagedDocumentPath(dir, path) {
6060
// id + 旧行 content_history 里的旧摘要(source=superseded)。
6161
const supersededByPointer = (id) => `\n\n[superseded by ${id}]`;
6262

63+
// 升格吸收不碰的类型(#275 拍板 5 的边界):吸收的对象是「原子条」,而下面这两种
64+
// 行各有自己的生命周期,被归档会各自留下第二行——
65+
// document:本体是磁盘上的文件。归档它等于替用户撤下外档;而且 supersede 探测
66+
// 只看活跃行(store.list 默认排除归档),同一 path 下次注册会在旧行还挂着
67+
// 「新版本」语义时再铸一行,指针注记与 content_history 记账也走不到。
68+
// summary:dream 总览与叙述按 source 身份去重、并按注入档位常驻。归档它会让下一
69+
// 次做梦把它当不存在(候选集同样只取活跃行),于是库里多出一行同源总览。
70+
// 口径是保守方向的:拿不准的行一律不吸收——少做一步没有代价,收错一步是内容事故。
71+
const ABSORB_EXEMPT_TYPES = new Set(["document", "summary"]);
72+
6373
/**
6474
* Build the document registrar. Injected deps are service.js closure members
6575
* (store / embedQuery / transaction / finalize) so this module stays free of
6676
* service-internal wiring; `finalize` is the single write epilogue (mirror
6777
* sync + notify + re-embed) so callers never duplicate it.
6878
*
69-
* @returns {(payload: object) => Promise<object>}
79+
* `pinnedTypes` 是注入的 #249 逐字保真池(service.js 的 PINNED_MEMORY_TYPES):
80+
* 这里不 import 它在 service.js 里,是因为 service.js 反向 import 本模块——
81+
* 方向反了会成环。
82+
*
83+
* @returns {(payload: object, opts?: object) => Promise<object>}
7084
* `{ action: "created"|"superseded", memory, superseded?, evidence_kept,
71-
* evidence_dropped, degraded }`
85+
* evidence_dropped, evidence_archived, degraded }`
7286
* @throws flag 关 / 路径非法或文件缺失 / title 或 summary 为空 / evidence 全部
7387
* 捏造 / 仅 vector 近重复(疑似重复外档,交 agent 裁决而不是静默二选一)。
7488
*/
75-
export function createDocumentRegistrar({ store, config, embedQuery, pushContentHistory, transaction, finalize }) {
76-
return async function registerDocument(payload, { hiddenEvidenceIds = [] } = {}) {
89+
export function createDocumentRegistrar({ store, config, embedQuery, pushContentHistory, transaction, finalize, pinnedTypes }) {
90+
return async function registerDocument(payload, { hiddenEvidenceIds = [], archiveEvidence = true } = {}) {
7791
// opt-in 总闸(#230 对齐 #228 形态):关 = 注册入口整体不存在,错误信息
7892
// 指回配置键,agent 能准确转告用户去开。
7993
if (config?.documentMemoryEnabled !== true) {
@@ -121,15 +135,14 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
121135
const hidden = new Set((Array.isArray(hiddenEvidenceIds) ? hiddenEvidenceIds : []).map((id) => String(id)));
122136
const kept = [];
123137
const dropped = [];
138+
// 存在但已归档的引用另记一份:它可能是被上一版文档升格吸收走的行(见下方
139+
// supersede 目标探测后的「认回」),不能一律按「不可用」处理。
140+
const archivedRefs = new Set();
124141
for (const id of wanted) {
125142
const row = hidden.has(id) ? null : store.getById(id);
143+
if (row?.archived) archivedRefs.add(id);
126144
(row && !row.archived ? kept : dropped).push(id);
127145
}
128-
if (wanted.length > 0 && kept.length === 0) {
129-
throw new Error(
130-
`registerDocument: all ${wanted.length} evidence ids are unknown, archived or out of scope — fabricated evidence is rejected`
131-
);
132-
}
133146

134147
const title = String(payload?.title ?? "").trim();
135148
if (!title) throw new Error("registerDocument: title is required");
@@ -162,6 +175,25 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
162175
.filter((m) => scopeMatches(m));
163176
const explicitTarget = scopeMatched.find((m) => samePath(m.doc_path, expanded))
164177
?? scopeMatched.find((m) => m.title.trim() === title);
178+
// 升格吸收过的引用认回(#275 拍板 5 的配套):evidence 行在文档注册成功后就翻了
179+
// archived,于是「同一份文档出新版、evidence 照旧」这一最常规的路径会整批落在
180+
// dropped——那会被下面的捏造判据误报成「证据都是编的」。口径:已归档行仍可为
181+
// **吸收它的那份文档**背书(loser.evidence 就是它吸收走的名单),不为别的文档
182+
// 背书;捏造与跨 scope 照旧拒绝。
183+
if (explicitTarget) {
184+
const own = new Set(explicitTarget.evidence ?? []);
185+
for (const id of archivedRefs) {
186+
if (!own.has(id)) continue;
187+
const at = dropped.indexOf(id);
188+
if (at >= 0) dropped.splice(at, 1);
189+
kept.push(id);
190+
}
191+
}
192+
if (wanted.length > 0 && kept.length === 0) {
193+
throw new Error(
194+
`registerDocument: all ${wanted.length} evidence ids are unknown, archived or out of scope — fabricated evidence is rejected`
195+
);
196+
}
165197
if (!explicitTarget) {
166198
// vector 档:embedder 不可用/向量缺失一律跳过——去重是增强不是写入依赖
167199
// (findSessionDuplicate 同原则)。probe 用 title+summary,与行向量
@@ -237,7 +269,25 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
237269
store.setArchived(loser.id, true);
238270
superseded = store.getById(loser.id);
239271
}
240-
return { created, superseded };
272+
// #275 拍板 5(#230 验收口径的补丁):升格吸收的 evidence 行随之退出活跃面——
273+
// 一次吸收 20 条,库里就是「21 行不是 1 行」。四条口径:①与本行同一事务(要么
274+
// 都成、要么都不成);②pinned(constraint / preference,即 #249 的逐字保真池)
275+
// 永不自动归档——升格不能绕过它;③自有生命周期的类型(document / summary,见
276+
// ABSORB_EXEMPT_TYPES)不吸收,吸收的是原子条;④只翻标志位、内容与审计全留
277+
// (可恢复),opt-out 走 archiveEvidence。
278+
// pinnedTypes 拿不到就不做这一步:宁可少做,也不能把保真池当普通行收走。
279+
let evidenceArchived = 0;
280+
if (archiveEvidence && pinnedTypes && typeof pinnedTypes.has === "function") {
281+
for (const id of kept) {
282+
// 事务内重读:期间被别的进程归档/遗忘的行不重复计数,也不误伤 pinned。
283+
const row = store.getById(id);
284+
if (!row || row.archived || row.forgotten) continue;
285+
if (pinnedTypes.has(row.type) || ABSORB_EXEMPT_TYPES.has(row.type)) continue;
286+
store.setArchived(id, true);
287+
evidenceArchived += 1;
288+
}
289+
}
290+
return { created, superseded, evidenceArchived };
241291
});
242292
finalize(result.superseded ? [result.created, result.superseded] : [result.created]);
243293
return {
@@ -246,6 +296,7 @@ export function createDocumentRegistrar({ store, config, embedQuery, pushContent
246296
...(result.superseded ? { superseded: result.superseded } : {}),
247297
evidence_kept: kept.length,
248298
evidence_dropped: dropped.length,
299+
evidence_archived: result.evidenceArchived,
249300
degraded: dropped.length > 0
250301
};
251302
};

‎dsh-mneme/lib/recall-stats.js‎

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
// 新内聚块从第一行就落在自己的文件里,service.js 保留 barrel 出口、调用方零改动。
66
// 纯读不写,绝不触发任何 write hook。
77

8+
import { scopeKeyOf } from "./scope.js";
9+
810
/**
911
* 口径(issue #217 评论 2026-09-18,锚 5bd2dab):
1012
* - Top-N:窗口内 recall_runs.candidates(最终返回集)按 id 计数,join
@@ -20,6 +22,17 @@
2022
* - coverage:recallRecordDefault 开启前的窗口算不到,earliestRunAt 为
2123
* null(窗口内无回执)或早于窗口起点时,前端标注可信度;扫描行数有
2224
* 上限,超出标 truncated(degraded 口径),不静默少算。
25+
* - archive(#275 拍板的第五指标,与上面几项同位):
26+
* · total = 归档区现有行数;addedInWindow / perDay = 窗口内进入归档区的行数
27+
* 与其日均(净增速率)。归档时刻只能取 updated_at(setArchived 翻标志位时刷
28+
* 它)——这是代理口径:对已归档行做一次 memory_update,或对同一行重复调
29+
* setArchived(…, true),都会被算成「本窗口新进归档」,perDay 因此偏高。精确
30+
* 口径要一个 archived_at 列(schema 变更,属第二批题材),本版不加;真正的
31+
* 「净」增本来也要跨快照比 total(物理删除落地后,差值才会由负向变化体现)。
32+
* · compressible = 可压掉行数:同 type、同 scope 三维且内容哈希完全相同的归档
33+
* 行里,多出来的那些(每组留一行)。用内容哈希而不是向量近重复,是因为回收
34+
* 动作本身会清掉归档行向量(clearArchivedEmbeddings)——指标不能建在它自己
35+
* 的输入会被回收掉的数据上;精确重复与 #254 的计量口径同一把尺。
2336
*
2437
* @param {object} store - createStore 产物(只调用 listRecallRunsSince / all)
2538
* @param {{ windowDays?: number, exemptDays?: number }} [options]
@@ -36,7 +49,8 @@ export function recallStats(store, options = {}) {
3649
const rawSlots = Number(options.maxInjectSlots ?? 5);
3750
const maxInjectSlots = Number.isInteger(rawSlots) && rawSlots >= 1 ? rawSlots : 5;
3851
const now = Date.now();
39-
const since = new Date(now - windowDays * 86400000).toISOString();
52+
const sinceMs = now - windowDays * 86400000;
53+
const since = new Date(sinceMs).toISOString();
4054

4155
const { rows: runs, total } = store.listRecallRunsSince(since);
4256
const hits = new Map(); // id -> { count, title, source }
@@ -67,8 +81,29 @@ export function recallStats(store, options = {}) {
6781
let activeCount = 0;
6882
let zombieCount = 0;
6983
let exemptCount = 0;
84+
// 第五指标(#275):归档区一侧单独累计,分组键与 #254 的去重候选集同构
85+
// (type + 哈希 + scope 三维)——可压掉的必须是「本来就会被判成同一件事」的行。
86+
let archivedTotal = 0;
87+
let archivedInWindow = 0;
88+
const hashGroups = new Map();
7089
for (const m of memories) {
71-
if (m.archived || m.forgotten) continue;
90+
if (m.archived) {
91+
archivedTotal += 1;
92+
const archivedMs = Date.parse(m.updated_at ?? "");
93+
if (Number.isFinite(archivedMs) && archivedMs >= sinceMs) archivedInWindow += 1;
94+
if (m.content_hash) {
95+
const key = [
96+
m.type ?? "",
97+
m.content_hash,
98+
scopeKeyOf(m.agent_scope) ?? "",
99+
scopeKeyOf(m.workspace_scope) ?? "",
100+
scopeKeyOf(m.sensitivity) ?? ""
101+
].join("\u0000");
102+
hashGroups.set(key, (hashGroups.get(key) ?? 0) + 1);
103+
}
104+
continue;
105+
}
106+
if (m.forgotten) continue;
72107
const createdMs = Date.parse(m.created_at ?? "");
73108
// created_at 解析不了时无法证明已过机会期 → 归入豁免,宁漏勿误伤
74109
if (!Number.isFinite(createdMs) || now - createdMs < EXEMPT_MS) {
@@ -98,6 +133,14 @@ export function recallStats(store, options = {}) {
98133
.sort((a, b) => b.count - a.count || a.id.localeCompare(b.id))
99134
.slice(0, 10);
100135

136+
let compressibleGroups = 0;
137+
let compressibleRows = 0;
138+
for (const n of hashGroups.values()) {
139+
if (n < 2) continue;
140+
compressibleGroups += 1;
141+
compressibleRows += n - 1;
142+
}
143+
101144
return {
102145
windowDays,
103146
generatedAt: new Date(now).toISOString(),
@@ -113,6 +156,13 @@ export function recallStats(store, options = {}) {
113156
slotFillRate: injectRuns > 0 ? injectedCount / (injectRuns * maxInjectSlots) : null
114157
},
115158
topRecalled,
159+
// #275 第五指标:归档净增速率 + 可压掉行数(口径见文件头)
160+
archive: {
161+
total: archivedTotal,
162+
addedInWindow: archivedInWindow,
163+
perDay: Math.round((archivedInWindow / windowDays) * 100) / 100,
164+
compressible: { rows: compressibleRows, groups: compressibleGroups }
165+
},
116166
zombie: {
117167
activeCount,
118168
zombieCount,

‎dsh-mneme/lib/service.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2181,6 +2181,9 @@ export function createService({ store, mirror, config, onWrite, logger, document
21812181
embedQuery,
21822182
pushContentHistory,
21832183
transaction,
2184+
// #275 拍板 5:升格吸收的 evidence 行随之归档,但 pinned 池(#249)永不自动归档
2185+
// ——注册器不 import 这个集合,方向反了会成环,所以在这里注入。
2186+
pinnedTypes: PINNED_MEMORY_TYPES,
21842187
finalize: (rows) => {
21852188
for (const row of rows) scheduleEmbed(row);
21862189
}

0 commit comments

Comments
 (0)