dsh-prime-memory 0.20.0-beta.9 → 0.20.2

package/dist/stats.js

@@ -26,9 +26,8 @@ import { resolveConflictPair, listConflictPairs } from './conflict-service.js';
 import { sourceAnchorLabels } from './pipeline/anchors.js';
 import { readSupersedeMarker } from './store/supersede.js';
 import { isSnapshotName } from './store/l1-snapshot.js';
-import { closeTodoRefSlot } from './hooks/long-task.js';
 import { WING_CATALOG, WING_FALLBACK } from './types.js';
-import { isTag } from './metadata-validators.js';
+import { isRoomSlug } from './metadata-validators.js';
 import { InProcMemoryBackend } from './store/memory-backend.js';
 import { isWingCorner } from './store/session-modes.js';
 import { startWingBackfill } from './wing-backfill.js';
@@ -52,8 +51,6 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/token-cost',
     'dsh-memory/session-mode-get',
     'dsh-memory/session-mode-set',
-    'dsh-memory/longtask-hint-get',
-    'dsh-memory/longtask-compress-tail',
     'dsh-memory/wing-overview',
     'dsh-memory/rooms-get',
     'dsh-memory/rooms-export',
@@ -160,51 +157,6 @@ function readJsonBody(req) {
         req.on('error', reject);
     });
 }
-/** 压缩后去抖 ruminate:上次触发时刻(模块级;跨轮询/按压共享)。 */
-let lastCompressRuminateAt = 0;
-const COMPRESS_RUMINATE_DEBOUNCE_MS = 10 * 60_000;
-/**
- * 尾部压缩闭环(T05):压缩入队成功后,冲刷+L2(带 repo 感知)+relabel+recluster
- * 消费一条龙由 ruminate 轻刷新接管——去抖 10 分钟,失败静默(压缩本身已成功,
- * 重算由下一次任何触发兜底)。
- */
-function debouncedCompressRuminate(ruminate, logger) {
-    const now = Date.now();
-    if (!ruminate || now - lastCompressRuminateAt < COMPRESS_RUMINATE_DEBOUNCE_MS)
-        return;
-    lastCompressRuminateAt = now;
-    void ruminate.start().catch((err) => logger.warn(`[memory] 压缩后反刍触发失败(压缩产物保留,重算由下次触发兜底): ${err instanceof Error ? err.message : String(err)}`));
-}
-/**
- * 尾部 turn 压缩:把 (水位线, maxCapturedTurn] 内最近的最近 N 轮强制蒸馏入记忆
- * (force 跳过阈值;L1 去重与水位线双重防重)。off 档会话保持完全隐身(不压缩)。
- * 无锚点老数据只在首次压缩(无水位线)时纳入——宁少收不重蒸。
- */
-export async function compressTailTurns(sessionId, turns, io) {
-    const toTurn = io.l0.maxCapturedTurn(sessionId);
-    if (toTurn === undefined)
-        return { enqueued: 0, fromTurn: null, toTurn: null };
-    const watermark = io.modes.getTailWatermark(sessionId) ?? 0;
-    const fromTurn = Math.max(watermark + 1, toTurn - turns + 1);
-    if (fromTurn > toTurn)
-        return { enqueued: 0, fromTurn, toTurn };
-    const mode = io.modes.get(sessionId);
-    if (mode === 'off')
-        return { enqueued: 0, fromTurn, toTurn };
-    const messages = await io.l0.recentBySession(sessionId, turns * 12 + 24);
-    const picked = messages.filter((m) => {
-        const t = m.anchor?.turn;
-        if (t === undefined)
-            return watermark === 0;
-        return t >= fromTurn && t <= toTurn;
-    });
-    if (picked.length === 0)
-        return { enqueued: 0, fromTurn, toTurn };
-    io.runner.enqueue(sessionId, picked, mode, { force: true });
-    io.modes.setTailWatermark(sessionId, toTurn);
-    io.logger.info(`[memory] 尾部压缩:turn ${fromTurn}..${toTurn} 已强制入队蒸馏(${picked.length} 条)`);
-    return { enqueued: picked.length, fromTurn, toTurn };
-}
 /**
  * 组装端点 deps。抽成函数是为了让"哪个控制器落入哪个字段"成为可测接缝:
  * 反刍端点读 deps.ruminate,若此处漏注入,端点会静默恒返 {supported:false}(面板整块不渲染)。
@@ -220,7 +172,6 @@ export function buildEndpointDeps(base, sources, controller) {
         embedManager: sources.embedManager,
         sessionInfo: sources.sessionInfo,
         ruminate: controller,
-        longTask: sources.longTask,
         roomRegistry: sources.roomRegistry,
     };
     return { ...base, ...injected };
@@ -228,8 +179,6 @@ export function buildEndpointDeps(base, sources, controller) {
 export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes, dataDir, rebuild, embedManager, sessionInfo, 
 /** 反刍控制器(存储降级时为 undefined):经 buildEndpointDeps 落入 deps.ruminate。 */
 ruminate, 
-/** 长任务端点依赖(cfg.longTask.enabled 门控;缺省 = 端点恒 disabled)。 */
-longTaskDeps, 
 /** Room 分类管理依赖(注册表;缺省 = rooms-get 不带 registry、rooms-export 恒 404 语义)。 */
 roomRegistry) {
     /** 当前是否持有一段有效注册(dispose 完成后清空,允许服务重上线时重注册)。 */
@@ -250,9 +199,9 @@ roomRegistry) {
             const rpcHandler = async (endpoint, payload) => {
                 try {
                     const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, 
-                    // longTask/roomRegistry 必须随 sources 下发——漏带 = 面板侧 room-*/longtask-*
-                    // 全部"未装配"(工具面直传不受影响;2026-10-02 beta.8 实测回归)
-                    { status, live, modes, dataDir, rebuild, embedManager, sessionInfo, longTask: longTaskDeps, roomRegistry }, ruminate));
+                    // roomRegistry 必须随 sources 下发——漏带 = 面板侧 room-* 恒"未装配"
+                    // (工具面直传不受影响;2026-10-02 beta.9 实测回归)
+                    { status, live, modes, dataDir, rebuild, embedManager, sessionInfo, roomRegistry }, ruminate));
                     return { ok: true, value };
                 }
                 catch (err) {
@@ -400,7 +349,7 @@ function sanitizeSettings(s) {
 }
 /** 端点分发表(导出供测试直调:可精确注入 rebuild/ruminate 等可选控制器,验证 deps 接线)。 */
 export async function handleEndpoint(endpoint, payload, deps) {
-    const { cfg, stores, status, live, modes, dataDir, rebuild, ruminate, embedManager, sessionInfo, longTask: longTaskDeps, roomRegistry } = deps;
+    const { cfg, stores, status, live, modes, dataDir, rebuild, ruminate, embedManager, sessionInfo, roomRegistry } = deps;
     switch (endpoint) {
         case 'dsh-memory/stats':
             return buildStats(cfg, stores, status);
@@ -434,7 +383,6 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 halls: locked,
                 hallIncludeUnlabeled: bounds.includeUnlabeled,
                 hallIncludeGeneral: bounds.includeGeneral,
-                longTask: modes.getLongTask(sessionId),
             };
             return v;
         }
@@ -444,9 +392,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const p = (payload ?? {});
             const sessionId = expectSessionId(p.sessionId);
             const allowed = ['auto', 'chat', 'work', 'off'];
-            // mode 可选(带 longTask 的轻量切换);二者都不传 = 无操作拒绝(防旧客户端漏字段静默)。
-            if (p.mode === undefined && p.longTask === undefined) {
-                throw new Error('session-mode-set 需要 mode 或 longTask 之一');
+            if (p.mode === undefined) {
+                throw new Error('session-mode-set 需要 mode');
             }
             if (p.mode !== undefined && (typeof p.mode !== 'string' || !allowed.includes(p.mode))) {
                 throw new Error(`非法档位: ${String(p.mode)}(允许 ${allowed.join('/')})`);
@@ -468,17 +415,6 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     throw new Error(`非法 Wing 锁定: ${String(bad)}(允许 ${WING_CATALOG.map((h) => h.id).join('/')}/null)`);
                 }
             }
-            // 长任务开关可选同车:布尔 = 切换;缺省 = 不动。关闭时撤下 todo 参考槽位
-            // (todo 参考只在长任务模式可用;撤下失败不影响开关本身,log 即可)。
-            if (p.longTask !== undefined) {
-                if (typeof p.longTask !== 'boolean') {
-                    throw new Error(`非法长任务开关: ${String(p.longTask)}(允许 true/false)`);
-                }
-                modes.setLongTask(sessionId, p.longTask);
-                if (!p.longTask && longTaskDeps?.slots) {
-                    closeTodoRefSlot({ cfg, modes, slots: longTaskDeps.slots, contextUsage: longTaskDeps.contextUsage, todoRef: longTaskDeps.todoRef, logger: deps.logger }).catch((err) => deps.logger.warn(`[memory] todo 参考槽位撤下失败: ${err instanceof Error ? err.message : String(err)}`));
-                }
-            }
             if (p.mode !== undefined)
                 modes.set(sessionId, p.mode);
             if (typeof p.recall === 'boolean') {
@@ -518,129 +454,6 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 halls: locked,
                 hallIncludeUnlabeled: bounds.includeUnlabeled,
                 hallIncludeGeneral: bounds.includeGeneral,
-                longTask: modes.getLongTask(sessionId),
-            };
-            return v;
-        }
-        case 'dsh-memory/longtask-hint-get': {
-            if (!modes)
-                throw new Error('档位存储未初始化');
-            const p = (payload ?? {});
-            const sessionId = expectSessionId(p.sessionId);
-            const enabled = cfg.longTask.enabled;
-            const longTask = modes.getLongTask(sessionId);
-            let contextPct = null;
-            if (enabled && longTask) {
-                // 分母:主对话模型官方窗口(3s race 封顶,同 session-stats 口径)
-                let window = null;
-                try {
-                    const sel = deps.ctx.get('agentDefaultModel')?.currentSelection?.();
-                    if (sel?.provider && sel?.model) {
-                        window = await Promise.race([
-                            resolveModelContextWindow(deps.ctx, sel.provider, sel.model),
-                            new Promise((resolve) => setTimeout(() => resolve(null), 3_000)),
-                        ]);
-                    }
-                }
-                catch {
-                    /* 可选服务缺失 = 分母未知 */
-                }
-                contextPct = longTaskDeps
-                    ? longTaskDeps.contextUsage.percentOfWindow(sessionId, window ?? undefined)
-                    : null;
-            }
-            const drift = enabled ? longTaskDeps?.todoRef.latest(sessionId)?.drift ?? null : null;
-            const todoCount = enabled ? longTaskDeps?.todoRef.latest(sessionId)?.items.length ?? 0 : 0;
-            const reasons = [];
-            if (!longTask) {
-                if (contextPct !== null && contextPct >= cfg.longTask.contextThresholdPct) {
-                    reasons.push('context-threshold');
-                }
-                if (drift !== null && drift >= cfg.longTask.driftThreshold) {
-                    reasons.push('todo-drift');
-                }
-            }
-            const watermark = modes.getTailWatermark(sessionId);
-            let pendingTailTurns = null;
-            if (enabled && longTask && longTaskDeps) {
-                const captured = stores.l0.maxCapturedTurn(sessionId);
-                pendingTailTurns = captured === undefined ? 0 : Math.max(0, captured - (watermark ?? 0));
-            }
-            // 自动尾部压缩(长任务开启 + 显式 opt-in + 跨阈值):水位线只前进,
-            // 轮询重复触发天然幂等;失败只 warn,不打断建议状态返回。
-            if (enabled &&
-                longTask &&
-                longTaskDeps &&
-                cfg.longTask.autoCompress &&
-                pendingTailTurns !== null &&
-                pendingTailTurns > 0 &&
-                contextPct !== null &&
-                contextPct >= cfg.longTask.contextThresholdPct) {
-                try {
-                    const ar = await compressTailTurns(sessionId, cfg.longTask.tailTurns, {
-                        modes,
-                        l0: stores.l0,
-                        runner: longTaskDeps.runner,
-                        logger: deps.logger,
-                    });
-                    if (ar.enqueued > 0)
-                        debouncedCompressRuminate(ruminate, deps.logger);
-                }
-                catch (err) {
-                    deps.logger.warn(`[memory] 自动尾部压缩失败: ${err instanceof Error ? err.message : String(err)}`);
-                }
-                const captured = stores.l0.maxCapturedTurn(sessionId);
-                pendingTailTurns = captured === undefined ? 0 : Math.max(0, captured - (modes.getTailWatermark(sessionId) ?? 0));
-            }
-            const v = {
-                sessionId,
-                enabled,
-                longTask,
-                contextPct,
-                contextThresholdPct: cfg.longTask.contextThresholdPct,
-                drift,
-                driftThreshold: cfg.longTask.driftThreshold,
-                todoCount,
-                suggest: reasons.length > 0,
-                reasons,
-                tailTurns: cfg.longTask.tailTurns,
-                lastTailCompressedTurn: watermark ?? null,
-                pendingTailTurns,
-            };
-            return v;
-        }
-        case 'dsh-memory/longtask-compress-tail': {
-            if (!modes)
-                throw new Error('档位存储未初始化');
-            const p = (payload ?? {});
-            const sessionId = expectSessionId(p.sessionId);
-            const longTask = modes.getLongTask(sessionId);
-            const turns = p.turns === undefined
-                ? cfg.longTask.tailTurns
-                : Math.max(1, Math.min(50, Math.round(p.turns)));
-            let enqueued = 0;
-            let fromTurn = null;
-            let toTurn = null;
-            if (longTask && longTaskDeps) {
-                // 只在长任务模式可用(部署开关在 compressTailTurns 内再守一道)
-                const r = await compressTailTurns(sessionId, turns, {
-                    modes,
-                    l0: stores.l0,
-                    runner: longTaskDeps.runner,
-                    logger: deps.logger,
-                });
-                enqueued = r.enqueued;
-                fromTurn = r.fromTurn;
-                toTurn = r.toTurn;
-                if (enqueued > 0)
-                    debouncedCompressRuminate(ruminate, deps.logger);
-            }
-            const v = {
-                sessionId,
-                enqueued,
-                fromTurn,
-                toTurn,
-                longTask,
             };
             return v;
         }
@@ -658,16 +471,17 @@ export async function handleEndpoint(endpoint, payload, deps) {
         case 'dsh-memory/rooms-get': {
             const rooms = stores.l1.listRooms();
             // 端点层合并注册表(Agent A 设计):注册表 active 条目 count=0 补齐并带
-            // source/label;自生长条目标 source='grown'。不动 listRooms() 的缓存语义。
+            // source/label(source 用条目真实来源——收编 grown ≠ 预注册,⭐角标靠它区分);
+            // 自生长条目标 source='grown'。不动 listRooms() 的缓存语义。
             const merged = rooms.map((r) => ({ ...r, source: 'grown' }));
             const registry = roomRegistry?.listActive() ?? [];
             for (const e of registry) {
                 const idx = merged.findIndex((r) => r.room === e.slug);
                 if (idx === -1) {
-                    merged.push({ room: e.slug, count: 0, source: 'pre-registered', label: e.label });
+                    merged.push({ room: e.slug, count: 0, source: e.source, label: e.label });
                 }
                 else {
-                    merged[idx] = { ...merged[idx], source: 'pre-registered', label: e.label ?? merged[idx].label };
+                    merged[idx] = { ...merged[idx], source: e.source, label: e.label ?? merged[idx].label };
                 }
             }
             const v = {
@@ -714,18 +528,53 @@ export async function handleEndpoint(endpoint, payload, deps) {
             if (!live?.get().memoryMutate)
                 throw new Error('记忆写删未开放:请在记忆库面板开启「高权限模式」后,才能执行 Room 管理。');
             const p = (payload ?? {});
+            if (p.action === 'update') {
+                const slug = String(p.slug ?? '').trim();
+                if (!slug)
+                    throw new Error('update 需要 slug');
+                const changed = await roomRegistry.update(slug, {
+                    label: typeof p.label === 'string' ? p.label : undefined,
+                    description: typeof p.description === 'string' ? p.description : undefined,
+                });
+                const v = {
+                    notice: changed
+                        ? `已更新:${slug}(显示名/归类说明,标注器下次即用新词)`
+                        : `无变化:${slug} 未找到或未提供任何非空字段`,
+                };
+                return v;
+            }
             if (p.action === 'retire') {
                 const slug = String(p.slug ?? '').trim();
                 if (!slug)
                     throw new Error('retire 需要 slug');
                 const active = p.active === true;
+                // 自生长未注册 slug 退场:自动补一条 grown 注册条目再置 retired——
+                // 否则词表无物可变,面板按钮无法切换为「恢复」(用户实测反馈)
+                if (!active && p.withRecords === true && !roomRegistry.bySlug(slug)) {
+                    await roomRegistry.register({ slug, source: 'grown' });
+                }
                 const changed = await roomRegistry.setStatus(slug, active ? 'active' : 'retired');
+                // 带记录退场(软删,可恢复):该 room 下全部**活跃**记录分批 retire(每批 ≤200,与 records-delete 同原语)
+                let retiredRecords = 0;
+                if (p.withRecords === true && !active) {
+                    for (let offset = 0;; offset += 200) {
+                        const page = stores.l1.list({ tag: slug, retired: false, limit: 200, offset });
+                        if (page.items.length === 0)
+                            break;
+                        const n = stores.l1.retire(page.items.map((r) => r.id), { at: new Date().toISOString(), reason: 'manual' });
+                        retiredRecords += n;
+                        if (page.items.length < 200)
+                            break;
+                    }
+                    deps.logger.info(`[memory] Room 退役带记录:${slug},退场 ${retiredRecords} 条(软删,可恢复)`);
+                }
                 const v = {
+                    retiredRecords: retiredRecords > 0 ? retiredRecords : undefined,
                     notice: changed
                         ? active
                             ? `已恢复:${slug}`
-                            : `已退役:${slug}(存量记录的 tags 不动,仅词表不再推荐)。`
-                        : `未找到注册条目或状态无变化:${slug}(自生长 Room 无需退役,会随 tags 自然消失)。`,
+                            : `已退役:${slug}(存量记录的 tags 不动,仅词表不再推荐)。${retiredRecords > 0 ? `已连同退场 ${retiredRecords} 条记录(软删,可在「已退场」区恢复)。` : ''}`
+                        : `未找到注册条目或状态无变化:${slug}。${retiredRecords > 0 ? `已退场 ${retiredRecords} 条记录(软删,可恢复)。` : ''}`,
                 };
                 return v;
             }
@@ -1139,8 +988,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const retiredSel = typeof p.retired === 'boolean' ? p.retired : undefined;
             // Room 过滤:tag 是**自生长**的 slug(无枚举),只做形状与长度校验(SQL 侧参数化)
             const tagSel = typeof p.tag === 'string' ? p.tag.trim().slice(0, 64) : '';
-            if (tagSel && !isTag(tagSel))
-                throw new Error('tag 非法(需小写字母数字连字符,1-32 字符)');
+            if (tagSel && !isRoomSlug(tagSel))
+                throw new Error('tag 非法(两级制:major 或 major/minor,各段小写字母数字连字符)');
             // 孤儿记忆筛选(与 tag 互斥,tag 优先):只认显式布尔,其余视为缺省。
             const untaggedSel = p.untagged === true && !tagSel;
             // R13 多值归一: halls 数组只留非空字符串(≤40 字符),去重,上限 8(角数);
@@ -1193,13 +1042,19 @@ export async function handleEndpoint(endpoint, payload, deps) {
                         return true;
                     });
                 }
+                const pageIds = filtered.slice(offset, offset + limit).map((h) => h.id);
+                const updatedById = new Map(stores.l1.getByIds(pageIds).map((r) => [r.id, r.updatedAt]));
                 const resp = {
-                    items: filtered.slice(offset, offset + limit).map((h) => hitToUiRecord({ ...h, metadata: metaById?.get(h.id) })),
+                    items: filtered.slice(offset, offset + limit).map((h) => hitToUiRecord({ ...h, metadata: metaById?.get(h.id) }, {
+                        agingWeight: agingWeightOf(updatedById.get(h.id), stores.l1.decayHalfLife),
+                        usage: stores.usage?.get(h.id) ?? null,
+                    })),
                     hasMore: filtered.length > offset + limit,
                     total: null,
                     truncated: wanted > SEARCH_CAP,
                     scenes: offset === 0 ? stores.l1.distinctScenes() : undefined,
                     wingCatalog,
+                    usageSummary: stores.usage?.summary() ?? null,
                 };
                 return resp;
             }
@@ -1207,12 +1062,16 @@ export async function handleEndpoint(endpoint, payload, deps) {
             // 接了只会让「仅退场+关键词」永远空结果,不如如实不筛。
             const { items, total } = stores.l1.list({ type: p.type || undefined, scene: p.scene || undefined, hall: p.hall || undefined, halls: wingSel.length > 0 ? wingSel : undefined, tag: tagSel || undefined, untagged: untaggedSel || undefined, retired: retiredSel, limit, offset });
             const resp = {
-                items: items.map(hitToUiRecord),
+                items: items.map((r) => hitToUiRecord(r, {
+                    agingWeight: agingWeightOf(r.updatedAt, stores.l1.decayHalfLife),
+                    usage: stores.usage?.get(r.id) ?? null,
+                })),
                 hasMore: offset + items.length < total,
                 total,
                 truncated: false,
                 scenes: offset === 0 ? stores.l1.distinctScenes() : undefined,
                 wingCatalog,
+                usageSummary: stores.usage?.summary() ?? null,
             };
             return resp;
         }
@@ -1819,7 +1678,14 @@ export async function handleEndpoint(endpoint, payload, deps) {
     }
 }
 /** 浏览器卡片字段(比 MemoryRecord 精简,去掉大 metadata;Hall 从 metadata 提取)。 */
-export function hitToUiRecord(r) {
+/** 老化权重(与读路径 applyDecayWeight 同式):max(0.5, 0.5^(Δ天/半衰期));半衰期 ≤0 = 关 → null。 */
+export function agingWeightOf(updatedAtMs, halfLifeDays, now = Date.now()) {
+    if (!(halfLifeDays > 0))
+        return null;
+    const ageDays = Math.max(0, (now - (updatedAtMs ?? 0)) / 86_400_000);
+    return Math.max(0.5, Math.pow(0.5, ageDays / halfLifeDays));
+}
+export function hitToUiRecord(r, extra) {
     const retired = r.validTo !== undefined;
     const mark = retired ? readSupersedeMarker(r.metadata) : undefined;
     return {
@@ -1845,6 +1711,8 @@ export function hitToUiRecord(r) {
         // 但必须给出可见差异。
         retired,
         retiredReason: retired ? (mark?.reason ?? 'unknown') : null,
+        agingWeight: extra?.agingWeight ?? null,
+        usage: extra?.usage ?? null,
     };
 }
 /**

package/dist/store/l1.d.ts

@@ -70,6 +70,8 @@ export declare class L1Store {
     decayHalfLifeDays?: number, 
     /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
     graphLane?: GraphLaneProvider);
+    /** 读路径时效半衰期(天;0=关)。老化权重展示与召回衰减同一事实源。 */
+    get decayHalfLife(): number;
     init(): Promise<void>;
     /** 旧版单文件 records.jsonl 一次性导入检索库,成功后改名 .imported。 */
     private importLegacy;

package/dist/store/l1.js

@@ -56,6 +56,10 @@ export class L1Store {
         this.decayHalfLifeDays = decayHalfLifeDays ?? 30;
         this.graphLaneProvider = graphLane;
     }
+    /** 读路径时效半衰期(天;0=关)。老化权重展示与召回衰减同一事实源。 */
+    get decayHalfLife() {
+        return this.decayHalfLifeDays;
+    }
     async init() {
         await ensureDir(this.recordsDir);
         await this.importLegacy();

package/dist/store/recall-usage.d.ts

@@ -0,0 +1,43 @@
+import type { MemoryLogger } from '../types.js';
+export declare const RECALL_USAGE_FILE_VERSION: 1;
+export interface RecallUsageEntry {
+    attempts: number;
+    used: number;
+    lastAttemptAt: number | null;
+    lastUsedAt: number | null;
+}
+export interface RecallUsageSummary {
+    /** 有统计的记忆条数。 */
+    tracked: number;
+    /** 尝试总次数(Σ attempts)。 */
+    attempted: number;
+    /** 使用总次数(Σ used)。 */
+    used: number;
+    /** 使用率(百分比整数;attempted=0 时 0)。 */
+    rate: number;
+}
+export declare class RecallUsageStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeTimer;
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    private ensureLoaded;
+    /** 一轮召回:候选集 attempts++/lastAttemptAt=now;used 子集额外 used++/lastUsedAt=now
+     *  (used 不在候选内 = 防御路径,同样算一次尝试——用了就是被尝试过)。 */
+    recordAttempt(candidateIds: readonly string[], usedIds: readonly string[]): void;
+    get(id: string): RecallUsageEntry | undefined;
+    summary(): RecallUsageSummary;
+    /** 立即落盘(去抖窗口内的兜底;测试/停机用)。 */
+    flush(): Promise<void>;
+    /** 同步等待在途写(测试用;无在途写时立即返回)。 */
+    flushSync(): void;
+    private prune;
+    private schedulePersist;
+    private persist;
+}

package/dist/store/recall-usage.js

@@ -0,0 +1,149 @@
+/**
+ * 召回使用统计 sidecar(老化权重效果统计的数据面)。
+ *
+ * 口径(用户裁定):**进 topN(被注入上下文)才算被使用**;参与尝试未进 = 只有
+ * attempts。每轮召回 recordAttempt(候选集, 注入集)——内存即时、去抖原子持久化
+ * (召回是热路径,统计只碰内存 Map)。
+ *
+ * 存储:`recall-usage.json` slots 式 sidecar,与 rooms-registry/session-modes 同族
+ * 纪律:缺失 = 合法空表;损坏/不可读 → 只读降级(内存态照常,停止回写),绝不阻塞
+ * 召回读路径(R2 红线)。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const RECALL_USAGE_FILE_VERSION = 1;
+/** 条目上限(防已退场/被取代记忆的 id 无限累积):超限按 lastAttemptAt 淘汰最旧。 */
+const MAX_ENTRIES = 50_000;
+/** 去抖持久化间隔(召回热路径;窗口内断电最多丢最近统计,不影响记忆本体)。 */
+const PERSIST_DEBOUNCE_MS = 5_000;
+export class RecallUsageStore {
+    logger;
+    file;
+    entries = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeTimer;
+    writeChain = Promise.resolve();
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'recall-usage.json');
+    }
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 召回使用统计只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        const raw = read.value.entries ?? {};
+        for (const [id, e] of Object.entries(raw)) {
+            if (!e || typeof e.attempts !== 'number')
+                continue;
+            this.entries.set(id, {
+                attempts: e.attempts,
+                used: typeof e.used === 'number' ? e.used : 0,
+                lastAttemptAt: typeof e.lastAttemptAt === 'number' ? e.lastAttemptAt : null,
+                lastUsedAt: typeof e.lastUsedAt === 'number' ? e.lastUsedAt : null,
+            });
+        }
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('召回使用统计未初始化(先 await init())');
+    }
+    /** 一轮召回:候选集 attempts++/lastAttemptAt=now;used 子集额外 used++/lastUsedAt=now
+     *  (used 不在候选内 = 防御路径,同样算一次尝试——用了就是被尝试过)。 */
+    recordAttempt(candidateIds, usedIds) {
+        this.ensureLoaded();
+        if (candidateIds.length === 0 && usedIds.length === 0)
+            return;
+        const now = Date.now();
+        const cand = new Set(candidateIds);
+        for (const id of cand) {
+            const e = this.entries.get(id) ?? { attempts: 0, used: 0, lastAttemptAt: null, lastUsedAt: null };
+            e.attempts += 1;
+            e.lastAttemptAt = now;
+            this.entries.set(id, e);
+        }
+        for (const id of usedIds) {
+            const e = this.entries.get(id) ?? { attempts: 0, used: 0, lastAttemptAt: null, lastUsedAt: null };
+            e.used += 1;
+            if (!cand.has(id)) {
+                e.attempts += 1;
+                e.lastAttemptAt = now;
+            }
+            e.lastUsedAt = now;
+            this.entries.set(id, e);
+        }
+        this.prune();
+        this.schedulePersist();
+    }
+    get(id) {
+        this.ensureLoaded();
+        const e = this.entries.get(id);
+        return e ? { ...e } : undefined;
+    }
+    summary() {
+        this.ensureLoaded();
+        let attempted = 0;
+        let used = 0;
+        for (const e of this.entries.values()) {
+            attempted += e.attempts;
+            used += e.used;
+        }
+        return { tracked: this.entries.size, attempted, used, rate: attempted > 0 ? Math.round((used / attempted) * 100) : 0 };
+    }
+    /** 立即落盘(去抖窗口内的兜底;测试/停机用)。 */
+    flush() {
+        if (this.writeTimer) {
+            clearTimeout(this.writeTimer);
+            this.writeTimer = undefined;
+        }
+        return this.persist();
+    }
+    /** 同步等待在途写(测试用;无在途写时立即返回)。 */
+    flushSync() {
+        void this.flush();
+    }
+    prune() {
+        if (this.entries.size <= MAX_ENTRIES)
+            return;
+        const byOldest = [...this.entries.entries()].sort((a, b) => (a[1].lastAttemptAt ?? 0) - (b[1].lastAttemptAt ?? 0));
+        for (const [id] of byOldest.slice(0, this.entries.size - MAX_ENTRIES))
+            this.entries.delete(id);
+    }
+    schedulePersist() {
+        if (this.degraded || this.writeTimer)
+            return;
+        this.writeTimer = setTimeout(() => {
+            this.writeTimer = undefined;
+            void this.persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.writeTimer.unref?.(); // 不为统计写hold进程(停机即丢窗口内统计,可接受)
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(async () => {
+            try {
+                await ensureDir(path.dirname(this.file));
+                const data = { version: RECALL_USAGE_FILE_VERSION, entries: Object.fromEntries(this.entries) };
+                await atomicWriteText(this.file, JSON.stringify(data));
+            }
+            catch (err) {
+                this.degraded = err instanceof Error ? err.message : String(err);
+                if (!this.degradedLogged) {
+                    this.degradedLogged = true;
+                    this.logger?.warn(`[memory] 召回使用统计写入失败,只读降级: ${this.degraded}`);
+                }
+            }
+        });
+        await this.writeChain;
+    }
+}