Skip to content

Commit c8a4af2

Browse files
committed
feat(stats): 记忆复用统计端点与面板卡(#217)
- recall-stats.js(新,纯函数模块):窗口内 recall_runs.candidates 只读 聚合——Top-N 召回(join memories 补 type/source,已删记忆 type=null)、 僵尸率(活跃且零曝光,豁免期 7 天 exemptCount 单独报数)、coverage (earliestRunAt 可信度标注 + 扫描上限 truncated 不静默少算);口径锚 issue #217 评论(candidates 只存最终返回集,「入池未中」语义 B 待留痕拍板) - store: listRecallRunsSince(窗口扫描 oldest-first,返回 rows + total, limit 参数供测试压 cap 路径;纯读) - api: GET /api/dsh-mneme/recall-stats?window=30d(1-365 天钳制,缺省 30; 失败走既有 500 JSON 惯例) - service: recallStats barrel 出口——service.js 过 2000 行参考线 (AGENTS.md 尺寸约定 #221),新内聚块独立成模块,api 层调用方零改动 - lib/client.js: 状态页「记忆复用」卡(自门控:接口失败/窗口内无回执/ 空库整卡不渲染)+ 双语文案 - AGENTS.md 模块地图补行;CHANGELOG 同步 - test: recall-stats.test.js 5 例(Top-N 计数与 join、幽灵行 type=null、 豁免期与归档/遗忘剔除、窗口过滤与 coverage、越界钳制与 truncated)
1 parent 5bd2dab commit c8a4af2

12 files changed

Lines changed: 474 additions & 1 deletion

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ dsh-mneme 是 DSH 宿主的记忆插件(蒸馏 / 注入 / 检索 / 巩固 / sc
2626
| 实体 | `src/entities/extractor.js`(存储侧在 store 三表) | 写入时 LLM 抽取实体/属性/关系 |
2727
| 检索辅助 | `src/search/{bm25,adaptive}.js`、`src/vector-index.js`、`src/embedding.js`、`src/local-embedder.js`、`src/reranker.js` | BM25 / 自适应阈值 / 向量索引 / 嵌入 / 重排 |
2828
| 热度 | `src/heat.js` | 纯函数遗忘曲线(opt-in) |
29+
| 复用统计 | `src/recall-stats.js` | recall_runs 只读聚合(#217,Top-N 召回 + 僵尸率) |
2930
| 冷启动 | `src/bootstrap.js` | 从仓库文件反向构建初始记忆(POST /bootstrap) |
3031
| 配置 | `src/config.js`(schema + lightMode)、`src/settings.js`(feature flags 白名单) | 一切行为开关的家 |
3132
| API 面 | `src/api.js`(宿主内 /api/dsh-mneme/*)、`src/api-standalone.js`(Bearer 数据面)、`bin/dsh-mneme-mcp.mjs`(MCP stdio) | 对外三张脸 |

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Changelog
22

3+
## [Unreleased]
4+
5+
## 🆕 新增
6+
7+
- **记忆复用统计端点与面板卡(issue #217)**:`GET /api/dsh-mneme/recall-stats?window=30d`(1-365 天钳制)只读聚合——Top-N 召回(按窗口内 recall_runs 候选计数,join memories 补 type/source,已删记忆 type=null)、僵尸记忆率(活跃且窗口内零曝光,豁免期 7 天单独报数)、覆盖度标注(earliestRunAt / 扫描超上限 truncated);纯读聚合独立成模块 `src/recall-stats.js`(service.js 过 2000 行参考线,barrel 出口调用方零改动);面板状态页新增「记忆复用」卡(自门控,窗口内无回执整卡不渲染)。注入命中率与「入池未中」零召回语义(B)待注入留痕口径拍板后接入。
8+
39
## [0.8.3] - 2026-09-17
410

511
## 🆕 新增

‎dsh-mneme/lib/api.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,28 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
243243
}
244244
});
245245

246+
// 记忆复用统计(#217,只读聚合):Top-N 召回 + 僵尸率 + 覆盖度标注。窗口
247+
// 参数钳制 1-365 天(缺省 30),聚合口径见 service.recallStats;注入命中
248+
// 率待注入留痕口径拍板后接入。失败走既有 500 JSON 惯例,前端整卡不渲染。
249+
register({
250+
kind: "exact",
251+
path: "/api/dsh-mneme/recall-stats",
252+
handler(req, res) {
253+
if (req.method !== "GET") {
254+
sendJson(res, 404, { error: "not-found" });
255+
return;
256+
}
257+
try {
258+
const url = new URL(req.url, "http://localhost");
259+
const raw = Number(url.searchParams.get("window"));
260+
const windowDays = Number.isInteger(raw) && raw >= 1 && raw <= 365 ? raw : 30;
261+
sendJson(res, 200, service.recallStats({ windowDays }));
262+
} catch {
263+
sendJson(res, 500, { error: "internal" });
264+
}
265+
}
266+
});
267+
246268
register({
247269
kind: "exact",
248270
path: "/api/dsh-mneme/search",

‎dsh-mneme/lib/client.js‎

Lines changed: 54 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -464,6 +464,8 @@ window.__ModuleLoader__.load({
464464
"memory.status.archivedMemories": "已归档的记忆",
465465
"memory.status.heatDistribution": "热度分布",
466466
"memory.status.heatHint": "热门(≥66%){hot} · 温热(33–66%){warm} · 冷却(<33%){cold},样本为最近 {sample} 条",
467+
"memory.status.recallStats": "记忆复用",
468+
"memory.status.recallHint": "复用率 {rate} · 僵尸 {zombie}/{active}(豁免 {exempt})· 30 天回执 {runs} 次 · Top:{top}",
467469
"memory.status.viewAll": "查看全部",
468470
"memory.status.depositedCount": "沉淀的记忆({n})",
469471
"memory.status.archivedCount": "已归档的记忆({n})",
@@ -817,6 +819,8 @@ window.__ModuleLoader__.load({
817819
"memory.status.archivedMemories": "Archived memories",
818820
"memory.status.heatDistribution": "Heat distribution",
819821
"memory.status.heatHint": "hot (≥66%) {hot} · warm (33–66%) {warm} · cooled (<33%) {cold}, sampled from the latest {sample}",
822+
"memory.status.recallStats": "Recall reuse",
823+
"memory.status.recallHint": "reuse {rate} · zombie {zombie}/{active} (exempt {exempt}) · {runs} runs in 30d · top: {top}",
820824
"memory.status.viewAll": "View all",
821825
"memory.status.depositedCount": "Deposited memories ({n})",
822826
"memory.status.archivedCount": "Archived memories ({n})",
@@ -3247,6 +3251,54 @@ window.__ModuleLoader__.load({
32473251
});
32483252
}
32493253

3254+
// 记忆复用卡(#217):只读聚合 /recall-stats(Top-N 召回 + 僵尸率 +
3255+
// 覆盖度)。自门控——接口失败、窗口内无任何回执(earliestRunAt=null,
3256+
// 口径不可信)或库为空时整卡不渲染,前端不感知;truncated(扫描超上限)
3257+
// 只影响 hint 里的回执计数,不挡渲染。
3258+
function RecallStatsCard({ t }) {
3259+
const [state, setState] = useState({ loading: true, off: false, rate: null, zombie: 0, active: 0, exempt: 0, runs: 0, top: "" });
3260+
useEffect(() => {
3261+
let cancelled = false;
3262+
apiFetch("/api/dsh-mneme/recall-stats?window=30")
3263+
.then((res) => { if (!res.ok) throw new Error("http"); return res.json(); })
3264+
.then((d) => {
3265+
if (cancelled) return;
3266+
const z = d.zombie || {};
3267+
const hasData = (d.coverage?.runsScanned ?? 0) > 0 || (z.activeCount ?? 0) > 0;
3268+
if (!hasData) {
3269+
setState({ loading: false, off: true });
3270+
return;
3271+
}
3272+
const rate = z.rate == null ? null : Math.round((1 - z.rate) * 100) + "%";
3273+
const top = (d.topRecalled || []).slice(0, 3)
3274+
.map((m) => (m.title || "").slice(0, 12))
3275+
.join(" · ");
3276+
setState({
3277+
loading: false, off: false, rate,
3278+
zombie: z.zombieCount ?? 0, active: z.activeCount ?? 0,
3279+
exempt: z.exemptCount ?? 0, runs: d.coverage?.runsScanned ?? 0, top
3280+
});
3281+
})
3282+
.catch(() => { if (!cancelled) setState({ loading: false, off: true }); });
3283+
return () => { cancelled = true; };
3284+
}, []);
3285+
if (state.off) return null;
3286+
return h(StatusCard, {
3287+
t,
3288+
title: t("memory.status.recallStats"),
3289+
loading: state.loading,
3290+
error: false,
3291+
num: state.rate ?? "—",
3292+
cap: t("memory.status.recallHint")
3293+
.replace("{rate}", state.rate ?? "—")
3294+
.replace("{zombie}", String(state.zombie))
3295+
.replace("{active}", String(state.active))
3296+
.replace("{exempt}", String(state.exempt))
3297+
.replace("{runs}", String(state.runs))
3298+
.replace("{top}", state.top || "—")
3299+
});
3300+
}
3301+
32503302
function StatusPanel({ t, onBrowse }) {
32513303
return h("div", { className: "mneme-status" },
32523304
h("div", { className: "mneme-statusgrid" },
@@ -3255,7 +3307,8 @@ window.__ModuleLoader__.load({
32553307
h(VectorStatusCard, { t }),
32563308
h(LlmStatusCard, { t }),
32573309
h(DreamStatusCards, { t }),
3258-
h(HeatStatusCard, { t })
3310+
h(HeatStatusCard, { t }),
3311+
h(RecallStatsCard, { t })
32593312
),
32603313
h(ConflictsQueue, { t }),
32613314
h(WorkbenchSection, { t, onBrowse })

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

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
// dsh-mneme/src/recall-stats.js
2+
// 记忆复用统计(#217):对 recall_runs + memories 做只读聚合,面板「记忆复用」
3+
// 卡与 GET /api/dsh-mneme/recall-stats 的数据源。
4+
// 独立成模块的原因:service.js 已过 2000 行参考线(AGENTS.md 尺寸约定,#221),
5+
// 新内聚块从第一行就落在自己的文件里,service.js 保留 barrel 出口、调用方零改动。
6+
// 纯读不写,绝不触发任何 write hook。
7+
8+
/**
9+
* 口径(issue #217 评论 2026-09-18,锚 5bd2dab):
10+
* - Top-N:窗口内 recall_runs.candidates(最终返回集)按 id 计数,join
11+
* memories 补 type/source;记忆已删的 type=null(标题/来源回退候选值)。
12+
* candidates 只存最终集,「入池未中」语义(B)现有表拿不到——v1 只报
13+
* 零曝光(A),B 待 recordRecall 记录形状扩展。
14+
* - 僵尸率:活跃(未归档未遗忘)且窗口内零候选出现;分母剔除写入不足
15+
* 豁免期的记忆(按当前时刻计,exemptCount 单独报数)。
16+
* - 注入命中率:注入侧无留痕,待 #217 mode='inject' 口径拍板后接入。
17+
* - coverage:recallRecordDefault 开启前的窗口算不到,earliestRunAt 为
18+
* null(窗口内无回执)或早于窗口起点时,前端标注可信度;扫描行数有
19+
* 上限,超出标 truncated(degraded 口径),不静默少算。
20+
*
21+
* @param {object} store - createStore 产物(只调用 listRecallRunsSince / all)
22+
* @param {{ windowDays?: number, exemptDays?: number }} [options]
23+
*/
24+
export function recallStats(store, options = {}) {
25+
const rawWindow = Number(options.windowDays ?? 30);
26+
const windowDays = Number.isInteger(rawWindow) && rawWindow >= 1 && rawWindow <= 365 ? rawWindow : 30;
27+
// 豁免期天数(issue #217 建议 7 天):option 化是给测试归零用 + 维护者
28+
// 调口径不留硬编码;越界值静默回默认(与 windowDays 同款宽容)。
29+
const rawExempt = Number(options.exemptDays ?? 7);
30+
const exemptDays = Number.isInteger(rawExempt) && rawExempt >= 0 && rawExempt <= 365 ? rawExempt : 7;
31+
const now = Date.now();
32+
const since = new Date(now - windowDays * 86400000).toISOString();
33+
34+
const { rows: runs, total } = store.listRecallRunsSince(since);
35+
const hits = new Map(); // id -> { count, title, source }
36+
for (const run of runs) {
37+
for (const cand of run.candidates ?? []) {
38+
if (!cand?.id) continue;
39+
const cur = hits.get(cand.id) ?? { count: 0, title: cand.title ?? null, source: cand.source ?? null };
40+
cur.count += 1;
41+
hits.set(cand.id, cur);
42+
}
43+
}
44+
45+
const memories = store.all();
46+
const memoryIndex = new Map(memories.map((m) => [m.id, m]));
47+
const EXEMPT_MS = exemptDays * 86400000;
48+
const byType = {};
49+
const bySource = {};
50+
let activeCount = 0;
51+
let zombieCount = 0;
52+
let exemptCount = 0;
53+
for (const m of memories) {
54+
if (m.archived || m.forgotten) continue;
55+
const createdMs = Date.parse(m.created_at ?? "");
56+
// created_at 解析不了时无法证明已过机会期 → 归入豁免,宁漏勿误伤
57+
if (!Number.isFinite(createdMs) || now - createdMs < EXEMPT_MS) {
58+
exemptCount += 1;
59+
continue;
60+
}
61+
activeCount += 1;
62+
const zombied = !hits.has(m.id);
63+
if (zombied) zombieCount += 1;
64+
const type = m.type ?? "unknown";
65+
const source = m.source ?? "unknown";
66+
if (!byType[type]) byType[type] = { active: 0, zombie: 0 };
67+
const t = byType[type];
68+
t.active += 1;
69+
if (zombied) t.zombie += 1;
70+
if (!bySource[source]) bySource[source] = { active: 0, zombie: 0 };
71+
const s = bySource[source];
72+
s.active += 1;
73+
if (zombied) s.zombie += 1;
74+
}
75+
76+
const topRecalled = [...hits.entries()]
77+
.map(([id, h]) => {
78+
const m = memoryIndex.get(id);
79+
return { id, title: m?.title ?? h.title, type: m?.type ?? null, source: m?.source ?? h.source, count: h.count };
80+
})
81+
.sort((a, b) => b.count - a.count || a.id.localeCompare(b.id))
82+
.slice(0, 10);
83+
84+
return {
85+
windowDays,
86+
generatedAt: new Date(now).toISOString(),
87+
coverage: {
88+
runsScanned: runs.length,
89+
runsTotal: total,
90+
truncated: total > runs.length,
91+
earliestRunAt: runs.length ? runs[0].created_at : null
92+
},
93+
topRecalled,
94+
zombie: {
95+
activeCount,
96+
zombieCount,
97+
exemptCount,
98+
rate: activeCount > 0 ? zombieCount / activeCount : null,
99+
byType,
100+
bySource
101+
}
102+
};
103+
}

‎dsh-mneme/lib/service.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { updatedAtBounds } from "./store.js";
44
import { normalizeExplicitScope, scopeKeyOf } from "./scope.js";
55
import { STR, langOf } from "./lang.js";
66
import { computeHeat } from "./heat.js";
7+
import { recallStats } from "./recall-stats.js";
78
import { evaluateMemoryQuality } from "./quality-filter.js";
89
import { applyDecisions } from "./dream/decisions.js";
910
import { createBM25Index } from "./search/bm25.js";
@@ -2011,6 +2012,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
20112012
setReranker(rn) { reranker = rn; },
20122013
setRecallRecorder(fn) { recallRecorder = fn; },
20132014
searchMemories,
2015+
// recallStats(#217)实现在 src/recall-stats.js:service.js 过 2000 行参考线,
2016+
// 新内聚块独立成模块(AGENTS.md 尺寸约定);这里只留 barrel 出口,调用方
2017+
// (api 层)零改动。纯读聚合,见模块注释的口径说明。
2018+
recallStats: (options) => recallStats(store, options),
20142019
embedQuery,
20152020
findSessionDuplicate,
20162021
evaluateRetrieval,

‎dsh-mneme/lib/store.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1566,6 +1566,23 @@ export function createStore(path) {
15661566
return rows.map(toRecallRun);
15671567
}
15681568

1569+
/**
1570+
* Window scan for the recall-stats aggregation (#217): every recall_runs row
1571+
* created at/after sinceIso, oldest first (rows[0].created_at = earliest
1572+
* coverage marker), plus the untruncated window total so the caller can flag
1573+
* a capped scan instead of silently undercounting. Read-only; `limit` exists
1574+
* so tests can exercise the cap path without a 50k-row fixture.
1575+
*/
1576+
function listRecallRunsSince(sinceIso, { limit = 50000 } = {}) {
1577+
const total = db.prepare(
1578+
"SELECT count(*) AS c FROM recall_runs WHERE created_at >= ?"
1579+
).get(sinceIso).c;
1580+
const rows = db.prepare(
1581+
"SELECT * FROM recall_runs WHERE created_at >= ? ORDER BY created_at ASC, id LIMIT ?"
1582+
).all(sinceIso, limit).map(toRecallRun);
1583+
return { rows, total };
1584+
}
1585+
15691586
// --- recall evaluation trail (方案 B: separate from the production audit) -
15701587

15711588
/**
@@ -2379,6 +2396,7 @@ export function createStore(path) {
23792396
saveRecallRun,
23802397
getRecallRun,
23812398
listRecallRuns,
2399+
listRecallRunsSince,
23822400
saveRecallEval,
23832401
getRecallEval,
23842402
listRecallEvals,

‎dsh-mneme/src/api.js‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,28 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
243243
}
244244
});
245245

246+
// 记忆复用统计(#217,只读聚合):Top-N 召回 + 僵尸率 + 覆盖度标注。窗口
247+
// 参数钳制 1-365 天(缺省 30),聚合口径见 service.recallStats;注入命中
248+
// 率待注入留痕口径拍板后接入。失败走既有 500 JSON 惯例,前端整卡不渲染。
249+
register({
250+
kind: "exact",
251+
path: "/api/dsh-mneme/recall-stats",
252+
handler(req, res) {
253+
if (req.method !== "GET") {
254+
sendJson(res, 404, { error: "not-found" });
255+
return;
256+
}
257+
try {
258+
const url = new URL(req.url, "http://localhost");
259+
const raw = Number(url.searchParams.get("window"));
260+
const windowDays = Number.isInteger(raw) && raw >= 1 && raw <= 365 ? raw : 30;
261+
sendJson(res, 200, service.recallStats({ windowDays }));
262+
} catch {
263+
sendJson(res, 500, { error: "internal" });
264+
}
265+
}
266+
});
267+
246268
register({
247269
kind: "exact",
248270
path: "/api/dsh-mneme/search",

0 commit comments

Comments
 (0)