dsh-prime-memory 0.18.2 → 0.18.5

package/dist/hooks/recall-ack.js

@@ -0,0 +1,79 @@
+/**
+ * §D 注入确认——日志回执协议(memorax-absorb Wave 3 / task_20-22)。
+ *
+ * 问题:`dedupe.mark` 原在 pre-step 返回注入的瞬间执行,但宿主是否真的把该
+ * 注入消息收进会话历史,此时并未确认(pre-step 被其他插件覆盖/步骤取消时,
+ * 模型根本没看到)——误标记会把这些记忆压制整个会话。
+ *
+ * 协议(两段式):
+ *  ① recall.ts 构造注入消息后只登记 pending(messageId → 记录 id 集),不标记;
+ *  ② capture.ts 在 `session/event` 观察到该 `user/message` 真正入日志时确认,
+ *     此时才 `dedupe.mark`(与 §D 红线一致:确认匹配在 source.kind 过滤之前——
+ *     注入消息的 source.kind 是 `plugin:memory`,放过滤后永远到不了匹配)。
+ *
+ * 超时降级(task_22):pending 超 5 分钟未确认 → 照旧标记 + 一次性提示。
+ * 防确认链路自身故障导致 dedupe 永不生效、记忆每轮重注的回归;正常确认时延
+ * <2s(同进程事件循环)。未确认且未超时的 pending 过期即弃(不标记)——
+ * 模型没看到的东西不应被抑制,允许下轮重注。
+ *
+ * 进程内 volatile,容量 64 条 LRU(注入速率低,正常情况秒级确认,积压即异常)。
+ */
+const PENDING_CAP = 64;
+export const PENDING_TIMEOUT_MS = 5 * 60_000;
+const pending = new Map();
+let marker;
+/** recall.ts 注册实际标记动作(dedupe.mark 绑定);重复注册以最后一次为准。 */
+export function setInjectionMarker(fn) {
+    marker = fn;
+}
+/** ① 登记待确认注入(超容量淘汰最旧——积压到 64 条说明确认链路已异常)。 */
+export function registerPendingInjection(agentId, messageId, recordIds, now = Date.now()) {
+    if (!messageId || recordIds.length === 0)
+        return;
+    pending.delete(messageId); // 同 id 重登记 = 刷新(置尾)
+    pending.set(messageId, { agentId, messageId, recordIds, at: now });
+    while (pending.size > PENDING_CAP) {
+        const oldest = pending.keys().next().value;
+        if (oldest === undefined)
+            break;
+        pending.delete(oldest);
+    }
+}
+/**
+ * ② 日志回执确认:该注入消息已真实进入会话历史。执行标记并移除 pending。
+ * @returns 是否命中一条 pending(未命中 = 与本插件注入无关的事件,静默)。
+ */
+export function confirmInjectionByMessageId(messageId) {
+    const entry = pending.get(messageId);
+    if (!entry)
+        return false;
+    pending.delete(messageId);
+    marker?.(entry.agentId, entry.recordIds);
+    return true;
+}
+/**
+ * 超时清扫:超时的 pending 照旧标记(降级保连续,防 dedupe 失效回归),并移除。
+ * 未超时的不动。@returns 本次降级标记的条数(recall 侧据此前瞻性提示一次)。
+ */
+export function expirePendingInjections(now = Date.now(), timeoutMs = PENDING_TIMEOUT_MS) {
+    if (pending.size === 0)
+        return 0;
+    let expired = 0;
+    for (const [key, entry] of pending) {
+        if (now - entry.at <= timeoutMs)
+            continue;
+        pending.delete(key);
+        marker?.(entry.agentId, entry.recordIds);
+        expired += 1;
+    }
+    return expired;
+}
+/** 诊断/测试:当前 pending 条数。 */
+export function pendingCount() {
+    return pending.size;
+}
+/** 测试隔离:清空 pending 与 marker(模块级状态,用例间互扰)。 */
+export function resetAckForTests() {
+    pending.clear();
+    marker = undefined;
+}

package/dist/hooks/recall.d.ts

@@ -22,6 +22,7 @@ import type { L1Store } from '../store/l1.js';
 import type { PersonaStore } from '../store/persona.js';
 import type { SceneStore } from '../store/scenes.js';
 import type { SessionModeStore } from '../store/session-modes.js';
+import type { RecallUsageStore } from '../store/recall-usage.js';
 import type { MemoryLogger } from '../types.js';
 import { type OccupancyLedger } from '../util/context-occupancy.js';
 /**
@@ -41,6 +42,25 @@ export declare function isOwnRecallSource(src: {
 export declare function buildRecallQuery(messages: Array<{
     content: unknown;
 }>, tailMessages?: number, maxChars?: number): string;
+/**
+ * §E 压缩感知标记器(memorax-absorb / task_24-26):记录刚完成压缩的会话,
+ * pre-step 消费后做一次性增强召回。纯内存状态,CaptureBuffers 同款可单测导出。
+ *
+ * - `onCompactionEnd`:只认无 error 的 compaction/end(失败的压缩没有把内容逐出上下文);
+ * - `consume`:消费即清(一次性增强);容量上限淘汰最旧(积压即异常,回退路径兜底)。
+ */
+export declare class PostCompactionTracker {
+    private readonly cap;
+    private readonly map;
+    constructor(cap?: number);
+    /** @returns 是否真的置了标记(false = 非 compaction/end 或带 error)。 */
+    onCompactionEnd(sessionId: string, data?: {
+        error?: unknown;
+    }): boolean;
+    /** 消费该会话的增强标记(存在即清,返回是否存在)。 */
+    consume(sessionId: string): boolean;
+    get size(): number;
+}
 /** 单会话召回统计(悬浮卡信息区数据源;每轮 O(1) 记账,agent/disposed 清理)。
  *  口径声明:这是"注入统计"而非 bench 的离线 recall@k——运行时没有 ground truth,
  *  命中率 = hitTurns / injectedTurns。去重语义:全量压制轮计入 hitTurns
@@ -70,4 +90,6 @@ export declare function registerRecall(ctx: Context, cfg: MemoryConfig, stores:
     l1: L1Store;
     scenes: Record<'chat' | 'work', SceneStore>;
     persona: Record<'chat' | 'work', PersonaStore>;
-}, logger: MemoryLogger, live: LiveSettingsHandle, modes: SessionModeStore, dataDir: string): RecallHooks;
+}, logger: MemoryLogger, live: LiveSettingsHandle, modes: SessionModeStore, dataDir: string, 
+/** 召回使用统计(可选;未装配 = 零成本旁路):进 topN(注入)才算 used。 */
+usage?: RecallUsageStore): RecallHooks;

package/dist/hooks/recall.js

@@ -1,6 +1,9 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { createHash } from 'node:crypto';
+import { trace } from '../store/trace.js';
 import { RecallDedupeStore } from '../store/recall-dedupe.js';
 import { OccupancyStore } from '../store/occupancy.js';
+import { expirePendingInjections, registerPendingInjection, setInjectionMarker, } from './recall-ack.js';
 import { scopeFilterOf } from '../workspace.js';
 import { applyRecallBudget, raceRecallTimeout, RECALL_EMBED_CAP_MS } from '../util/recall-budget.js';
 import { clearProfileShare, emptyOccupancyLedger, estimateInjectedMessageTokens, estimateStableSectionTokens, recordProfileShare, recordRecallInjection, resetForCompaction, } from '../util/context-occupancy.js';
@@ -42,6 +45,43 @@ export function buildRecallQuery(messages, tailMessages = RECALL_QUERY_TAIL_MESS
         text = text.slice(-maxChars);
     return text;
 }
+/**
+ * §E 压缩感知标记器(memorax-absorb / task_24-26):记录刚完成压缩的会话,
+ * pre-step 消费后做一次性增强召回。纯内存状态,CaptureBuffers 同款可单测导出。
+ *
+ * - `onCompactionEnd`:只认无 error 的 compaction/end(失败的压缩没有把内容逐出上下文);
+ * - `consume`:消费即清(一次性增强);容量上限淘汰最旧(积压即异常,回退路径兜底)。
+ */
+export class PostCompactionTracker {
+    cap;
+    map = new Map();
+    constructor(cap = 64) {
+        this.cap = cap;
+    }
+    /** @returns 是否真的置了标记(false = 非 compaction/end 或带 error)。 */
+    onCompactionEnd(sessionId, data) {
+        if (!sessionId || data?.error)
+            return false;
+        this.map.delete(sessionId); // 置尾刷新
+        this.map.set(sessionId, true);
+        while (this.map.size > this.cap) {
+            const oldest = this.map.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.map.delete(oldest);
+        }
+        return true;
+    }
+    /** 消费该会话的增强标记(存在即清,返回是否存在)。 */
+    consume(sessionId) {
+        if (!this.map.delete(sessionId))
+            return false;
+        return true;
+    }
+    get size() {
+        return this.map.size;
+    }
+}
 const MEMORY_TOOLS_GUIDE = `<memory-tools-guide>
 ## 记忆工具调用指南
 
@@ -72,7 +112,9 @@ export function emptyRecallStats(now = Date.now()) {
         updatedAt: now,
     };
 }
-export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
+export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir, 
+/** 召回使用统计(可选;未装配 = 零成本旁路):进 topN(注入)才算 used。 */
+usage) {
     /** 召回去重存储(同会话已注入的记忆不再重复注入;写穿持久化,重启不丢)。 */
     const dedupe = new RecallDedupeStore(dataDir, logger);
     /** 记忆占用流水(账本迁移写穿;重启后历史会话账目由此复生)。 */
@@ -160,10 +202,26 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
         recallStats.delete(payload.agent.id);
         occupancyByAgent.delete(payload.agent.id);
     });
+    // §D:绑定实际标记动作 + 超时清扫挂到 pre-step 入口(见注入点注释)。
+    setInjectionMarker((agentId, recordIds) => dedupe.mark(agentId, recordIds));
+    let ackDegradeWarned = false;
+    // §E 压缩感知(memorax-absorb):宿主 `compaction/end`(无 error)→ 该会话下一轮
+    // 做一次"定向增强召回"——跳过去重压制、画像立即重注入、占用账本归零;消费即清。
+    // 会话级回退路径保留(下方 session-start source='compact' 全量重置),两者幂等。
+    // 宿主无压缩计数器(compactionId 为 per-transaction UUID),故不做 generation 对账。
+    const postCompaction = new PostCompactionTracker();
+    ctx.on('session/event', (session, event) => {
+        if (event.type !== 'compaction/end')
+            return;
+        if (postCompaction.onCompactionEnd(String(session.id ?? session))) {
+            logger.info(`[memory] compaction/end:下一轮将做一次增强召回(session=${String(session.id ?? session)})`);
+        }
+    });
     // 上下文压缩/清空 → 已注入内容从模型上下文丢失,重置该会话的去重压制
     // (resume/startup 不重置:历史仍在,已注入的记忆模型还持有)。
     // 占用账本同步全量归零(宁低勿高;轮级粒度近似)。
-    ctx.on('agent/session-start', (payload) => {
+    // 0.1.7-rc.2 起并入 agent/created(serial:监听器需 async)。
+    ctx.on('agent/created', async (payload) => {
         if (payload.source === 'compact' || payload.source === 'clear') {
             dedupe.reset(payload.agent.id);
             const led = ledgerFor(payload.agent.id);
@@ -205,6 +263,13 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
     // prepend 注册 + 先 next() 再改写:不劫持其他监听器(dsh-time-context 官方范式)。
     if (cfg.recall.enabled) {
         ctx.on('agent/pre-step', async (payload, next) => {
+            // §D 超时清扫:超时未确认的注入照旧标记(降级保连续,防 dedupe 失效回归);
+            // 正常确认在秒级完成,这里只是兜底。一次性提示。
+            const expiredAcks = expirePendingInjections();
+            if (expiredAcks > 0 && !ackDegradeWarned) {
+                ackDegradeWarned = true;
+                logger.warn(`[memory] 注入确认:${expiredAcks} 条 pending 超时未回执,已降级为照常标记(一次性提示)`);
+            }
             const decision = await next();
             if (decision.kind === 'reject' || payload.signal.aborted)
                 return decision;
@@ -220,6 +285,17 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                 const hasNewUserMessage = decision.messages.some((m) => m.source?.kind === 'user');
                 if (!hasNewUserMessage)
                     return decision;
+                // §E 消费增强标记:压缩后下一轮跳过去重压制(预算/档位/门控照常),
+                // 画像 TTL 失效立即重注入,占用账本归零。消费即清(一次性)。
+                const sessionKey = String(payload.agent.session?.id ?? payload.agent.id);
+                const boosted = postCompaction.consume(sessionKey);
+                if (boosted) {
+                    invalidateProfile();
+                    const led = ledgerFor(payload.agent.id);
+                    resetForCompaction(led);
+                    occupancyStore.save(payload.agent.id, led);
+                    logger.info(`[memory] 压缩后增强召回:本轮跳过去重压制 + 画像重注入(session=${sessionKey})`);
+                }
                 const query = buildRecallQuery(payload.messages);
                 // 空查询是退化轮(无用户文本),重置命中信号但不计入统计
                 if (!query) {
@@ -227,6 +303,10 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     degenerate.lastHits = 0;
                     return decision;
                 }
+                // §F 追踪字段:metadata-only 默认(chars+sha256 前 16),captureContent 才存原文
+                const queryChars = query.length;
+                const querySha = createHash('sha256').update(query).digest('hex').slice(0, 16);
+                const queryText = cfg.trace?.captureContent === true ? query.slice(0, 200) : undefined;
                 const st = statFor(payload.agent.id);
                 st.injectedTurns++;
                 st.lastHits = 0;
@@ -245,6 +325,11 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                 if (hits === undefined) {
                     st.timeouts++;
                     logger.warn('[memory] 召回超时,跳过本轮注入(不阻塞对话)');
+                    trace({
+                        kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                        hitIds: [], hitScores: [], injectedIds: [], suppressedCount: 0,
+                        durationMs: Date.now() - searchStart, outcome: 'timeout',
+                    });
                     return decision;
                 }
                 st.lastDurationMs = Date.now() - searchStart;
@@ -275,7 +360,8 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                 }
                 // 召回去重:同会话已注入过的记录不再重复注入(模型上下文已持有,省 token)。
                 // 纯过滤——剩几条注几条,全量压制(0 条新鲜命中)是正确状态而非未命中。
-                const seen = dedupe.seen(payload.agent.id);
+                // §E:压缩后增强轮跳过压制(压缩把已注入内容逐出了模型上下文)。
+                const seen = boosted ? new Set() : dedupe.seen(payload.agent.id);
                 const fresh = scoped.filter((h) => !seen.has(h.id));
                 const suppressed = scoped.length - fresh.length;
                 st.suppressedRecalls += suppressed;
@@ -287,13 +373,29 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     st.hitTurns++;
                     st.totalHits += fresh.length;
                 }
-                if (fresh.length === 0)
+                if (fresh.length === 0) {
+                    // §F 追踪:全量压制轮——零注入是正确状态,如实记录
+                    trace({
+                        kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                        hitIds: scoped.map((h) => h.id), hitScores: scoped.map((h) => Number(h.score.toFixed(4))),
+                        injectedIds: [], suppressedCount: scoped.length - fresh.length,
+                        durationMs: Date.now() - searchStart, outcome: 'suppressed',
+                    });
+                    usage?.recordAttempt(scoped.map((h) => h.id), []);
                     return decision;
+                }
                 const lines = applyRecallBudget(fresh.map((h) => `- [${h.scene_name ? `${h.type}|${h.scene_name}` : h.type}] ${h.content}`), { maxCharsPerMemory: cfg.recall.maxCharsPerMemory, maxTotalRecallChars: cfg.recall.maxTotalRecallChars });
-                if (lines.length === 0)
+                if (lines.length === 0) {
+                    // §F 追踪:预算清零轮(截断后无完整行)
+                    trace({
+                        kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                        hitIds: fresh.map((h) => h.id), hitScores: fresh.map((h) => Number(h.score.toFixed(4))),
+                        injectedIds: [], suppressedCount: scoped.length - fresh.length,
+                        durationMs: Date.now() - searchStart, outcome: 'suppressed',
+                    });
+                    usage?.recordAttempt(fresh.map((h) => h.id), []);
                     return decision;
-                // 预算截断只丢尾部(前缀保留):实际注入 = fresh 的前 lines.length 条——只标记模型真实看到的
-                dedupe.mark(payload.agent.id, fresh.slice(0, lines.length).map((h) => h.id));
+                }
                 st.lastHits = lines.length;
                 const text = [
                     '<relevant-memories>',
@@ -312,6 +414,20 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     // v3 旧行(kind:'plugin'+plugin 字段)由宿主 v3→v4 迁移升格,读侧双形状兼容。
                     source: { kind: 'plugin:memory', form: 'recall' },
                 });
+                // §D 注入确认(memorax-absorb):宿主接受 enter 后,注入消息以原样
+                // `user/message` 进入会话日志(message.id 稳定保留)——capture 侧观察到
+                // 该 id 才真正 dedupe.mark(recall-ack 两段式)。这里只登记 pending,
+                // 未确认不标记:被覆盖/取消的注入不该压制这些记忆(下轮可重注)。
+                registerPendingInjection(payload.agent.id, injection.id, fresh.slice(0, lines.length).map((h) => h.id));
+                // §F 追踪:注入轮
+                trace({
+                    kind: 'recall_turn', ts: Date.now(), sessionId: sessionKey, queryChars, querySha, queryText,
+                    hitIds: scoped.map((h) => h.id), hitScores: scoped.map((h) => Number(h.score.toFixed(4))),
+                    injectedIds: fresh.slice(0, lines.length).map((h) => h.id), suppressedCount: scoped.length - fresh.length,
+                    durationMs: Date.now() - searchStart, outcome: 'injected',
+                });
+                // 使用统计:候选=scoped(尝试),进 topN(注入)=used
+                usage?.recordAttempt(scoped.map((h) => h.id), fresh.slice(0, lines.length).map((h) => h.id));
                 // 入账在成功构造注入消息之后、返回 enter 之前——任何前置抛错路径账目零扰动
                 const led = ledgerFor(payload.agent.id);
                 recordRecallInjection(led, text.length);
@@ -459,7 +575,7 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
         for (const agent of agents.list())
             registerForAgent(agent);
     }
-    ctx.on('agent/created', (payload) => {
+    ctx.on('agent/created', async (payload) => {
         registerForAgent(payload.agent);
     });
     ctx.effect(() => () => {

package/dist/index.d.ts

@@ -23,10 +23,21 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
         enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         stripCodeBlocks: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         maxMessageChars: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        redactSecrets: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         stripCodeBlocks: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         maxMessageChars: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        redactSecrets: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+    }>>, "plain">;
+    trace: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+        enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+        retentionDays: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        captureContent: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+        retentionDays: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        captureContent: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
     }>>, "plain">;
     extract: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
         enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
@@ -502,10 +513,21 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
         enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         stripCodeBlocks: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         maxMessageChars: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        redactSecrets: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         stripCodeBlocks: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
         maxMessageChars: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        redactSecrets: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+    }>>, "plain">;
+    trace: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+        enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+        retentionDays: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        captureContent: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
+        retentionDays: import("@deepseek-ai/schemastery").default<number, number, "defined">;
+        captureContent: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;
     }>>, "plain">;
     extract: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
         enabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "defined">;

package/dist/index.js

@@ -36,12 +36,15 @@ import { SlotStore } from './store/slots.js';
 import { registerMemoryTools } from './tools/index.js';
 import { registerSlotTools } from './tools/slots.js';
 import { registerSlotRecall } from './hooks/slot-recall.js';
+import { RoomRegistryStore } from './store/rooms-registry.js';
+import { RecallUsageStore } from './store/recall-usage.js';
 import { registerSlotsProjection } from './projection/slots.js';
 import { errDetail, withFileLog } from './util/filelog.js';
 import { buildRouteChain, resolveModelRoute, invalidateEffortCache } from './llm.js';
 import { effectiveCfg } from './pipeline/runner.js';
 import { pendingPathFor } from './store/pending.js';
 import { initTokenCost, resetTokenCost } from './token-cost.js';
+import { initTraceStore } from './store/trace.js';
 export const name = 'dsh-memory-plugin';
 /**
  * 硬依赖:蒸馏要用 llm,工具注册要用 tools,召回注入要用 systemPrompt。
@@ -137,6 +140,9 @@ export async function apply(ctx, config) {
     const embed = initial.svc;
     const db = new MemoryDb(path.join(dataDir, 'memory.db'), initial.dims, logger);
     initTokenCost(db, config.tokenCost.retentionDays);
+    // §F 追踪(trace.enabled=false 时保持未初始化,埋点零副作用)
+    if (config.trace?.enabled)
+        initTraceStore(dataDir, { retentionDays: config.trace.retentionDays });
     // 插件卸载时关闭连接(WAL 落盘),注册一次即可
     ctx.effect(() => () => db.close());
     let dbInit = { needsReindex: false };
@@ -154,6 +160,7 @@ export async function apply(ctx, config) {
         }
     }
     const stores = {
+        usage: undefined, // 装配于下方(依赖 dataDir 就绪)
         l0: new L0Store(dataDir, db, embed, logger),
         l1: new L1Store(dataDir, db, embed, config.recall.strategy, logger, config.recall.decayHalfLifeDays, 
         // §D 第 3 路:图谱回链。图谱不可用时 searchNodes 自带 no-op,不影响双路。
@@ -346,16 +353,23 @@ export async function apply(ctx, config) {
         backend = await createMemoryBackend({ dbPath: path.join(dataDir, 'memory.db'), dimensions: initial.dims, logger }, backend);
     }
     stores.backend = backend;
+    // Room 注册表(分类管理 beta.4;损坏降级为纯自生长目录)
+    const roomRegistry = new RoomRegistryStore(dataDir, logger);
+    await roomRegistry.init();
     const ruminate = storageOk && !db.isDegraded() && ruminateFile
-        ? new RuminateController(ctx, config, runner, stores, logger, live, ruminateFile)
+        ? new RuminateController(ctx, config, runner, stores, logger, live, ruminateFile, roomRegistry)
         : undefined;
     let flushL0;
     if (storageOk) {
         flushL0 = registerCapture(ctx, config, runner, stores.l0, logger, live, modes);
     }
-    const recall = registerRecall(ctx, config, stores, logger, live, modes, dataDir);
+    // 召回使用统计(进 topN 才算 used;热路径只碰内存,去抖落盘)
+    const recallUsage = new RecallUsageStore(dataDir, logger);
+    await recallUsage.init();
+    stores.usage = recallUsage;
+    const recall = registerRecall(ctx, config, stores, logger, live, modes, dataDir, recallUsage);
     runner.setAfterRun(recall.invalidateProfile);
-    registerMemoryTools(ctx, config, stores, logger, modes, live, ruminate);
+    registerMemoryTools(ctx, config, stores, logger, modes, live, ruminate, storageOk ? roomRegistry : undefined);
     // 激活槽位(active slot):工具面 + 常驻注入 + 服务端投影(均走 ctx.effect,可撤销)
     registerSlotTools(ctx, config, stores.slots, logger, modes, live, stores.l1);
     const slotRecall = registerSlotRecall(ctx, config, stores.slots, logger, live);
@@ -374,7 +388,7 @@ export async function apply(ctx, config) {
         runnerView: (sid, mode) => runner.sessionView(sid, mode),
         l0Count: (sid) => stores.l0.countBySession(sid),
         capabilities: () => db.getCapabilities(),
-    }, ruminate);
+    }, ruminate, storageOk ? roomRegistry : undefined);
     // bench 控制服务(config.benchControl 门控,默认关):仅基准/调试部署注册,
     // 供同进程的 bench-runner lifecycle 赛道触发 rebuild / 设置会话档位
     // (宿主侧 RPC 无 call(),见 bench-control.ts)

package/dist/metadata-validators.d.ts

@@ -10,6 +10,11 @@
  * 已是 string 的变量收窄成 `never`(该分支内无法再 `.slice`,已在 wing-backfill 踩过)。
  */
 export declare function isWingId(v: unknown): boolean;
+/**
+ * 两级 Room slug(`major` 或 `major/minor`,各段满足 isTag;至多一个 slash)。
+ * Room 注册表/归类写回的 tags 域;与 rooms-registry.ts 同一事实源(就近定义避免依赖环)。
+ */
+export declare function isRoomSlug(v: unknown): boolean;
 /** 同为布尔谓词(理由见 isWingId 注释)。 */
 export declare function isTag(v: unknown): boolean;
 /**

package/dist/metadata-validators.js

@@ -31,6 +31,16 @@ export function isWingId(v) {
 }
 /** 标签(Room 的构成单元)校验:小写字母数字连字符,1-32 字符。 */
 const TAG_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/**
+ * 两级 Room slug(`major` 或 `major/minor`,各段满足 isTag;至多一个 slash)。
+ * Room 注册表/归类写回的 tags 域;与 rooms-registry.ts 同一事实源(就近定义避免依赖环)。
+ */
+export function isRoomSlug(v) {
+    if (typeof v !== 'string')
+        return false;
+    const parts = v.split('/');
+    return parts.length <= 2 && parts.every((p) => TAG_RE.test(p));
+}
 /** 同为布尔谓词(理由见 isWingId 注释)。 */
 export function isTag(v) {
     return typeof v === 'string' && TAG_RE.test(v);
@@ -47,7 +57,7 @@ export function normTags(v, max = 3) {
         if (typeof raw !== 'string')
             continue;
         const t = raw.trim().toLowerCase();
-        if (!isTag(t) || out.includes(t))
+        if (!(isTag(t) || isRoomSlug(t)) || out.includes(t))
             continue;
         out.push(t);
         if (out.length >= max)

package/dist/pipeline/l1.d.ts

@@ -8,6 +8,10 @@ export interface ExtractionResult {
     skipped: boolean;
     sceneName: string;
     newRecords: MemoryRecord[];
+    /** §F 追踪捎带:与本轮 l1_receipts 同源的 runId(可交叉审计);早退分支缺省。 */
+    runId?: string;
+    /** §F 追踪捎带:六值决策词表聚合;早退分支缺省。 */
+    byKind?: Record<string, number>;
 }
 /** 分族 checkpoint 桶(活引用,改动由调用方 save 落盘)。 */
 export type FamilyStates = Record<MemoryFamily, MemoryState>;

package/dist/pipeline/l1.js

@@ -262,13 +262,20 @@ anchorMap) {
     // runId 提到块外:§C 冻结对要沿用同一批次 id,使「这一轮判了什么」与
     // 「这一轮冻结了哪一对」在记忆库侧可交叉审计(findings.md §3 / §9)。
     const runId = newRunId();
+    let byKind;
     {
         const items = extracted.map((m, i) => ({
             recordId: m.record_id,
             candidateIds: (matches[i]?.candidates ?? []).map((c) => c.id),
             action: byRecord.get(m.record_id)?.action,
         }));
-        persistReceiptsSafely((rows) => store.recordReceipts(rows), buildReceipts(runId, new Date().toISOString(), items), logger);
+        const rows = buildReceipts(runId, new Date().toISOString(), items);
+        persistReceiptsSafely((rows) => store.recordReceipts(rows), rows, logger);
+        // §F 追踪捎带:六值决策词表聚合(与凭证同源,runner 侧并入 distill_run 事件)
+        byKind = rows.reduce((acc, r) => {
+            acc[r.kind] = (acc[r.kind] ?? 0) + 1;
+            return acc;
+        }, {});
     }
     // ── Step 3: 应用决策(官方语义:新记录追加进事实源,被替换目标只从检索库删除) ──
     // 只按需取决策涉及的记录(候选 + 目标 id 并集),避免每轮全表扫描
@@ -521,7 +528,7 @@ anchorMap) {
     }
     markExtracted(states, mode, lastScene);
     logger.info(`[memory] L1 抽取完成(mode=${mode}):消息 ${pending.length} 条,抽取 ${extracted.length} 条,去重后新增 ${added.length} 条(取代退场 ${supersededBy.size} 条,chat=${addedByFamily.chat}/work=${addedByFamily.work}),累计 chat=${states.chat.totalExtracted}/work=${states.work.totalExtracted}`);
-    return { stored: added.length, skipped: false, sceneName: lastScene, newRecords: added };
+    return { stored: added.length, skipped: false, sceneName: lastScene, newRecords: added, runId, byKind };
 }
 /** auto 档取最近活跃的族 checkpoint(情境链/计数锚点)。 */
 function activeState(states) {

package/dist/pipeline/reconcile.js

@@ -1,4 +1,5 @@
 import { callLLM, parseJson } from '../llm.js';
+import { CONTENT_IS_DATA_CLAUSE, DATA_DELIMITER_NOTE } from '../prompts/boundary.js';
 /** 三态判定。顺序即优先级(报告与面板按此排序)。 */
 export const RECONCILE_STATES = ['contradicted', 'supported', 'unverifiable'];
 const DEFAULT_MAX_RECORDS = 50;
@@ -46,6 +47,8 @@ export function buildReconcilePrompt(memory, events, maxEvidenceChars) {
     const system = [
         '你是一个记忆核对员。给你一条「记忆」和它在会话里的「原文证据」,判断这条记忆是否与原文相符。',
         '',
+        CONTENT_IS_DATA_CLAUSE,
+        '',
         '只输出一个 JSON 对象,不要解释、不要 Markdown 代码块:',
         '{"state": "supported|contradicted|unverifiable", "reason": "一句话理由", "quote": "支撑你判断的原文片段"}',
         '',
@@ -57,6 +60,7 @@ export function buildReconcilePrompt(memory, events, maxEvidenceChars) {
         '- 拿不准就选 unverifiable。**不要猜。**',
     ].join('\n');
     const user = [
+        DATA_DELIMITER_NOTE,
         `记忆:${memory.text}`,
         '',
         '原文证据:',

package/dist/pipeline/ruminate.d.ts

@@ -66,6 +66,8 @@ export declare class RuminateController {
     private sessions;
     private totalL1;
     private pendingFile;
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    private readonly roomRegistry;
     /** 记忆后端:未注入时包 l1(进程内,行为与改造前等价)。 */
     private backend;
     constructor(ctx: Context, cfg: MemoryConfig, runner: Pick<MemoryRunner, 'enqueue' | 'states'>, stores: {
@@ -75,7 +77,15 @@ export declare class RuminateController {
         scenes: Record<MemoryFamily, SceneStore>;
         persona: Record<MemoryFamily, PersonaStore>;
         state: StateStore;
-    }, logger: MemoryLogger, live: LiveSettingsHandle, pendingFile: string);
+    }, logger: MemoryLogger, live: LiveSettingsHandle, pendingFile: string, 
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    roomRegistry?: {
+        listActive(): Array<{
+            slug: string;
+            label?: string;
+            description?: string;
+        }>;
+    });
     /** 状态快照 */
     getStatus(): RuminateStatus;
     /**

package/dist/pipeline/ruminate.js

@@ -3,6 +3,7 @@ import { groupPendingBySession, loadPending, } from '../store/pending.js';
 import { errDetail } from '../util/filelog.js';
 import { runSceneConsolidation } from './l2.js';
 import { relabelPass } from './relabel.js';
+import { annotateOrphanCandidates } from '../room-review.js';
 import { runPersona } from './l3.js';
 const IDLE_STATUS = {
     running: false,
@@ -44,11 +45,15 @@ export class RuminateController {
     sessions = [];
     totalL1 = 0;
     pendingFile;
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    roomRegistry;
     /** 记忆后端:未注入时包 l1(进程内,行为与改造前等价)。 */
     backend() {
         return this.stores.backend ?? new InProcMemoryBackend(this.stores.l1);
     }
-    constructor(ctx, cfg, runner, stores, logger, live, pendingFile) {
+    constructor(ctx, cfg, runner, stores, logger, live, pendingFile, 
+    /** Room 注册表(可选;孤儿候选预标记的合并词表来源)。 */
+    roomRegistry) {
         this.ctx = ctx;
         this.cfg = cfg;
         this.runner = runner;
@@ -56,6 +61,7 @@ export class RuminateController {
         this.logger = logger;
         this.live = live;
         this.pendingFile = pendingFile;
+        this.roomRegistry = roomRegistry;
     }
     /** 状态快照 */
     getStatus() {
@@ -222,6 +228,17 @@ export class RuminateController {
                 // 重标定失败不拖垮反刍整体(蒸馏/L2/L3 产物保留)
                 this.logger.warn(`[memory] 反刍重标定失败(不影响本次产物): ${errDetail(err)}`);
             }
+            // 孤儿候选预标记(长尾治理):无 Room 的活跃孤儿对照现有 Room 词表产出
+            // 候选(roomReview='pending'),由 agent 用 memory_room_review 逐个复查;
+            // 每轮至多 40 条,吞错不拖垮反刍。
+            try {
+                const r = await annotateOrphanCandidates(this.ctx, this.cfg, { l1: this.stores.l1, logger: this.logger, registry: this.roomRegistry }, 40);
+                if (r.written > 0)
+                    this.status.detail = `孤儿候选预标记 ${r.written} 条(待 agent 复查,工具 memory_room_review)`;
+            }
+            catch (err) {
+                this.logger.warn(`[memory] 孤儿候选预标记失败(忽略): ${errDetail(err)}`);
+            }
             this.status.phase = 'done';
             this.finish(null);
         }