dsh-prime-memory 0.16.2 → 0.16.4

package/dist/stats.js

@@ -18,14 +18,16 @@ import { EFFORT_CHOICES, resolveDataDir } from './config.js';
 import { effectiveCfg } from './pipeline/runner.js';
 import { emptyRecallStats } from './hooks/recall.js';
 import { buildRouteChain, decideSendableEffort, LAYER_DEFAULT_BUDGETS, layerChainOrNull, resolveModelContextWindow, resolveModelEfforts, resolveModelRoute } from './llm.js';
+import { mergeRoom, renameRoom } from './room-review.js';
 import { projectDistillChain, validateDistillChain } from './settings.js';
 import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/receipts.js';
+import { getTraceStore } from './store/trace.js';
 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 { 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';
@@ -34,7 +36,7 @@ import { snapshotTokenCost } from './token-cost.js';
 const require = createRequire(import.meta.url);
 export const PLUGIN_VERSION = require('../package.json').version;
 /**
- * 端点全集运行时清单(36 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * 端点全集运行时清单(与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
  * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
  * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端
@@ -51,6 +53,9 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/session-mode-set',
     'dsh-memory/wing-overview',
     'dsh-memory/rooms-get',
+    'dsh-memory/rooms-export',
+    'dsh-memory/room-register',
+    'dsh-memory/room-admin',
     'dsh-memory/wing-backfill',
     'dsh-memory/session-stats',
     'dsh-memory/settings-get',
@@ -66,6 +71,7 @@ export const MEMORY_ENDPOINTS = [
     'dsh-memory/scenes',
     'dsh-memory/persona',
     'dsh-memory/log-tail',
+    'dsh-memory/trace-tail',
     'dsh-memory/rebuild-status',
     'dsh-memory/rebuild-start',
     'dsh-memory/rebuild-cancel',
@@ -166,12 +172,15 @@ export function buildEndpointDeps(base, sources, controller) {
         embedManager: sources.embedManager,
         sessionInfo: sources.sessionInfo,
         ruminate: controller,
+        roomRegistry: sources.roomRegistry,
     };
     return { ...base, ...injected };
 }
 export function registerMemoryRpc(ctx, cfg, stores, logger, status, live, modes, dataDir, rebuild, embedManager, sessionInfo, 
 /** 反刍控制器(存储降级时为 undefined):经 buildEndpointDeps 落入 deps.ruminate。 */
-ruminate) {
+ruminate, 
+/** Room 分类管理依赖(注册表;缺省 = rooms-get 不带 registry、rooms-export 恒 404 语义)。 */
+roomRegistry) {
     /** 当前是否持有一段有效注册(dispose 完成后清空,允许服务重上线时重注册)。 */
     let holding = false;
     /** 当前 handle 绑定的 connection 实例(internal/service 第二参;用于识别实例替换)。 */
@@ -189,7 +198,7 @@ ruminate) {
             // 端点处理器:HTTP 层与旧 connection.rpc 的 handler 共用同一分发。
             const rpcHandler = async (endpoint, payload) => {
                 try {
-                    const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, { status, live, modes, dataDir, rebuild, embedManager, sessionInfo }, ruminate));
+                    const value = await handleEndpoint(endpoint, payload, buildEndpointDeps({ ctx, cfg, stores, logger }, { status, live, modes, dataDir, rebuild, embedManager, sessionInfo, roomRegistry }, ruminate));
                     return { ok: true, value };
                 }
                 catch (err) {
@@ -337,7 +346,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 } = 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);
@@ -454,10 +463,223 @@ export async function handleEndpoint(endpoint, payload, deps) {
         // ── Room 分类计数(标签自生长分类;展开 metadata.tags 聚合,零 schema) ──
         case 'dsh-memory/rooms-get': {
             const rooms = stores.l1.listRooms();
-            const v = { rooms, total: rooms.length };
+            // 端点层合并注册表(Agent A 设计):注册表 active 条目 count=0 补齐并带
+            // 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: e.source, label: e.label });
+                }
+                else {
+                    merged[idx] = { ...merged[idx], source: e.source, label: e.label ?? merged[idx].label };
+                }
+            }
+            const v = {
+                rooms: merged,
+                total: merged.length,
+                orphanCount: stores.l1.untaggedL1Count(),
+                registry: roomRegistry?.list().map((e) => ({
+                    slug: e.slug,
+                    label: e.label,
+                    description: e.description,
+                    source: e.source,
+                    aliases: e.aliases,
+                    status: e.status,
+                })),
+            };
+            return v;
+        }
+        case 'dsh-memory/room-register': {
+            if (!roomRegistry)
+                throw new Error('Room 注册表未装配(需要插件重载以初始化)。');
+            if (!live?.get().memoryMutate)
+                throw new Error('记忆写删未开放:请在记忆库面板开启「高权限模式」后,模型才能预注册 Room。');
+            const p = (payload ?? {});
+            const slug = String(p.slug ?? '').trim();
+            if (!slug)
+                throw new Error('slug 不能为空');
+            const r = await roomRegistry.register({
+                slug,
+                label: typeof p.label === 'string' ? p.label : undefined,
+                description: typeof p.description === 'string' ? p.description : undefined,
+                source: p.source === 'grown' ? 'grown' : undefined,
+            });
+            const v = {
+                slug: r.entry.slug,
+                created: r.created,
+                notice: r.created ? '已预注册。' : '已存在(只补全了缺失的 label/description)。',
+            };
+            return v;
+        }
+        // ── Room 破坏性面管理(merge/rename/retire;与 memory_room_admin 工具同编排) ──
+        case 'dsh-memory/room-admin': {
+            if (!roomRegistry)
+                throw new Error('Room 注册表未装配(需要插件重载以初始化)。');
+            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 不动,仅词表不再推荐)。${retiredRecords > 0 ? `已连同退场 ${retiredRecords} 条记录(软删,可在「已退场」区恢复)。` : ''}`
+                        : `未找到注册条目或状态无变化:${slug}。${retiredRecords > 0 ? `已退场 ${retiredRecords} 条记录(软删,可恢复)。` : ''}`,
+                };
+                return v;
+            }
+            if (p.action === 'merge' || p.action === 'rename') {
+                const from = String(p.from ?? '').trim();
+                const to = String(p.to ?? '').trim();
+                if (!from || !to)
+                    throw new Error('merge/rename 需要 from 与 to 两个 slug');
+                const dryRun = p.dryRun !== false;
+                const r = await (p.action === 'merge' ? mergeRoom : renameRoom)({ l1: stores.l1, registry: roomRegistry, logger: deps.logger }, from, to, { dryRun });
+                if (r.dryRun) {
+                    const v = {
+                        notice: `[dryRun 预览] ${from} → ${to}:影响 ${r.affected} 条${r.hasMore ? '(超过单次上限,需续跑)' : ''}。` +
+                            `样例:${r.preview.join(', ') || '无'}。确认无误后以 dryRun=false 执行(执行前自动备份,完成后自动入队场景重算)。`,
+                        dryRun: true,
+                        affected: r.affected,
+                        preview: r.preview,
+                        hasMore: r.hasMore,
+                    };
+                    return v;
+                }
+                const v = {
+                    notice: `${p.action === 'merge' ? '合并' : '改名'}完成:${from} → ${to},重写 ${r.applied} 条` +
+                        `(备份:${r.backupFile ?? '无'})。`,
+                    dryRun: false,
+                    affected: r.applied,
+                    backupFile: r.backupFile,
+                };
+                return v;
+            }
+            throw new Error(`非法 action:${String(p.action)}(允许 merge/rename/retire)`);
+        }
+        case 'dsh-memory/rooms-export': {
+            const p = (payload ?? {});
+            const kind = p.kind === 'orphans' ? 'orphans' : p.kind === 'rooms' ? 'rooms' : p.kind === 'records' ? 'records' : '';
+            if (!kind)
+                throw new Error(`非法 kind: ${String(p.kind)}(允许 rooms/orphans/records)`);
+            const limit = Math.min(Math.max(Number(p.limit) || 2000, 1), 10_000);
+            const esc = (v) => {
+                const t = String(v ?? '');
+                return /[,\r\n"]/.test(t) ? '"' + t.replace(/"/g, '""') + '"' : t;
+            };
+            if (kind === 'rooms') {
+                const registry = roomRegistry?.list() ?? [];
+                const counts = new Map(stores.l1.listRooms().map((r) => [r.room, r.count]));
+                const lines = ['slug,count,source,label,description,status,aliases'];
+                let n = 0;
+                const seen = new Set();
+                for (const e of registry) {
+                    lines.push([e.slug, String(counts.get(e.slug) ?? 0), e.source, e.label ?? '', e.description ?? '', e.status, (e.aliases ?? []).join('|')].map(esc).join(','));
+                    seen.add(e.slug);
+                    n++;
+                }
+                for (const r of stores.l1.listRooms()) {
+                    if (seen.has(r.room))
+                        continue;
+                    lines.push([r.room, String(r.count), 'grown', '', '', 'active', ''].map(esc).join(','));
+                    n++;
+                }
+                const v = { kind, csv: lines.join('\r\n'), total: n, truncated: false };
+                return v;
+            }
+            if (kind === 'records') {
+                const tag = String(p.tag ?? '').trim();
+                if (!tag)
+                    throw new Error('kind=records 需要 tag(目标 Room slug)');
+                const header = 'id,type,scene_name,updated_at,tags,content';
+                const lines = [header];
+                let n = 0;
+                let truncated2 = false;
+                for (let offset = 0; offset < limit; offset += 200) {
+                    const page = stores.l1.list({ tag, retired: undefined, limit: 200, offset });
+                    for (const r of page.items) {
+                        if (n >= limit) {
+                            truncated2 = true;
+                            break;
+                        }
+                        const meta = (r.metadata ?? {});
+                        const tags = Array.isArray(meta.tags) ? meta.tags.join('|') : '';
+                        lines.push([r.id, r.type, r.scene_name, new Date(r.updatedAt).toISOString(), tags, r.content].map(esc).join(','));
+                        n++;
+                    }
+                    if (truncated2 || page.items.length < 200)
+                        break;
+                }
+                const v = { kind, csv: lines.join('\r\n'), total: n, truncated: truncated2 };
+                return v;
+            }
+            // orphans:无 Room 绑定的活跃记录清单(id/type/scene/updated/content/候选/状态)
+            const header = 'id,type,scene_name,updated_at,content,room_candidates,room_review';
+            const lines = [header];
+            let n = 0;
+            let truncated = false;
+            for (let offset = 0; offset < limit; offset += 200) {
+                const page = stores.l1.list({ untagged: true, retired: false, limit: 200, offset });
+                for (const r of page.items) {
+                    if (n >= limit) {
+                        truncated = true;
+                        break;
+                    }
+                    const meta = (r.metadata ?? {});
+                    lines.push([r.id, r.type, r.scene_name, new Date(r.updatedAt).toISOString(), r.content,
+                        Array.isArray(meta.roomCandidates) ? meta.roomCandidates.join('|') : '',
+                        String(meta.roomReview ?? '')].map(esc).join(','));
+                    n++;
+                }
+                if (truncated || page.items.length < 200)
+                    break;
+            }
+            const v = { kind, csv: lines.join('\r\n'), total: n, truncated };
             return v;
         }
-        // ── 一键回填(task_15):后台任务,单飞;端点立即返回,进度看 wing-overview ──
         case 'dsh-memory/wing-backfill': {
             const r = startWingBackfill({
                 ctx: deps.ctx,
@@ -751,8 +973,10 @@ 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(角数);
             // wing 单值保留兼容,归一后与 halls 合并
             const wingSel = Array.from(new Set([
@@ -793,29 +1017,46 @@ export async function handleEndpoint(endpoint, payload, deps) {
                             if (!Array.isArray(tags) || !tags.some((t) => t === tagSel))
                                 return false;
                         }
+                        if (untaggedSel) {
+                            // 孤儿:tags 缺失/非数组/全部空串均算无 Room
+                            const tags = m?.tags;
+                            const hasRoom = Array.isArray(tags) && tags.some((t) => typeof t === 'string' && t !== '');
+                            if (hasRoom)
+                                return false;
+                        }
                         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;
             }
             // 退场筛查仅浏览路径透传;检索路径不接——FTS/向量里本就没有已退场行,
             // 接了只会让「仅退场+关键词」永远空结果,不如如实不筛。
-            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, retired: retiredSel, limit, offset });
+            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;
         }
@@ -1152,6 +1393,13 @@ export async function handleEndpoint(endpoint, payload, deps) {
             const p = (payload ?? {});
             return { lines: readLogTail(join(dataDir, 'memory.log'), Math.min(Math.max(Number(p.lines) || 200, 1), 1000)) };
         }
+        case 'dsh-memory/trace-tail': {
+            // §F 追踪尾读:未初始化(trace.enabled=false)回空集;坏行已在 store 侧跳过
+            const p = (payload ?? {});
+            const store = getTraceStore();
+            const events = store ? await store.tail(Math.min(Math.max(Number(p.lines) || 100, 1), 500), p.kind) : [];
+            return { events };
+        }
         case 'dsh-memory/rebuild-status': {
             if (!rebuild) {
                 const v = { supported: false, running: false, phase: 'idle' };
@@ -1415,7 +1663,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 {
@@ -1441,6 +1696,8 @@ export function hitToUiRecord(r) {
         // 但必须给出可见差异。
         retired,
         retiredReason: retired ? (mark?.reason ?? 'unknown') : null,
+        agingWeight: extra?.agingWeight ?? null,
+        usage: extra?.usage ?? null,
     };
 }
 /**

package/dist/store/l0.d.ts

@@ -19,6 +19,10 @@ export declare class L0Store {
     countBySession(sessionId: string): Promise<number>;
     /** 该会话最近 n 条消息(时间升序;蒸馏背景参考用,按会话现查——ADR-0003)。 */
     recentBySession(sessionId: string, limit: number): Promise<ConversationMessage[]>;
+    /** §A 水位线:该会话 L0 已落盘的最大 turn(空会话 undefined;委托 MemoryDb)。 */
+    maxCapturedTurn(sessionId: string): number | undefined;
+    /** §A 幂等检查:该 (session, turn) 是否已有任意 L0 行(委托 MemoryDb)。 */
+    hasAnyL0Message(sessionId: string, turn: number): boolean;
     /** 检索:FTS + 向量 hybrid(RRF 融合),返回按相关性排序的消息。 */
     search(query: string, limit: number): Promise<L0MessageRecord[]>;
     /** 活切换嵌入源:同步换底层服务(嵌入源三态切换用)。 */

package/dist/store/l0.js

@@ -128,6 +128,14 @@ export class L0Store {
     async recentBySession(sessionId, limit) {
         return this.db.recentL0BySession(sessionId, limit);
     }
+    /** §A 水位线:该会话 L0 已落盘的最大 turn(空会话 undefined;委托 MemoryDb)。 */
+    maxCapturedTurn(sessionId) {
+        return this.db.maxCapturedTurn(sessionId);
+    }
+    /** §A 幂等检查:该 (session, turn) 是否已有任意 L0 行(委托 MemoryDb)。 */
+    hasAnyL0Message(sessionId, turn) {
+        return this.db.hasAnyL0Message(sessionId, turn);
+    }
     /** 检索:FTS + 向量 hybrid(RRF 融合),返回按相关性排序的消息。 */
     async search(query, limit) {
         const caps = this.db.getCapabilities();

package/dist/store/l1.d.ts

@@ -61,6 +61,8 @@ export declare class L1Store {
     private readonly decayHalfLifeDays;
     /** §D 第 3 路(图谱回链);缺省 = 不接,恰为 2 路。 */
     private readonly graphLaneProvider?;
+    /** 孤儿记忆计数(没有任何 Room 的记录;rooms-get 面板「无绑定」chip 用)。 */
+    untaggedL1Count(): number;
     /** Room 计数缓存(见 `listRooms()`:tags 仅随反刍变化,不必每次敲库)。 */
     private roomCache;
     constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger, 
@@ -68,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;
@@ -88,6 +92,34 @@ export declare class L1Store {
      * 返回 false 表示 id 不存在或写入失败——调用方须记账,不许静默。
      */
     patchMetadata(id: string, metadata: Record<string, unknown>): boolean;
+    /**
+     * 收集某 Room 的全部匹配记录(含已退场行,口径与 Room 计数一致)。
+     * 内部分页拉取,上限 cap 防跑飞;返回记录数组供备份与干跑预览。
+     */
+    listByTagAll(tag: string, cap?: number): MemoryRecord[];
+    /**
+     * 备份某 Room 的匹配记录到 `<dataDir>/rooms-merge-backups/<ts>-<tag>.json`
+     * (执行前快照;破坏性重写前的唯一回滚物料)。返回备份文件路径与条数。
+     */
+    backupTagRecords(tag: string): {
+        file: string;
+        count: number;
+    };
+    /**
+     * 游标重写:把 metadata.tags 里的 `from` 全部替换为 `to`(**含已退场行**,
+     * 口径与 Room 计数一致)。写前重读-合并-写回(relabel 同款):只动 tags,
+     * roomCandidates/roomReview/hall/cogHall/sourceAnchors 等其余键原样保全。
+     *
+     * 单次上限 cap(500)可续跑:再次调用同一 from 即继续处理剩余行。
+     * 返回重写条数 + 受影响的 (family, scene) 集(供 recluster 'room-merge' 入队)。
+     */
+    rewriteTag(from: string, to: string, cap?: number): {
+        rewritten: number;
+        scanned: number;
+        families: string[];
+        scenes: string[];
+        hasMore: boolean;
+    };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
     /**
@@ -291,6 +323,8 @@ export declare class L1Store {
         halls?: readonly string[];
         /** Room 过滤(metadata.tags 含该 slug)。 */
         tag?: string;
+        /** 孤儿记忆筛选(true = 只列没有 Room 的记录;与 tag 互斥,tag 优先)。 */
+        untagged?: boolean;
         workspaceId?: string;
         /** 退场筛查:三态(`undefined` 全部 / `false` 仅活跃 / `true` 仅已退场)。 */
         retired?: boolean;

package/dist/store/l1.js

@@ -6,7 +6,7 @@
  *
  * 去重/合并的更新记录走 upsert(新 record id + 版本递增),不再全量重写文件。
  */
-import { existsSync, promises as fs } from 'node:fs';
+import { existsSync, mkdirSync, promises as fs, writeFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { familyForType, isScopeVisible } from '../types.js';
 import { graphHitRecordIds } from '../graph/search.js';
@@ -34,6 +34,10 @@ export class L1Store {
     decayHalfLifeDays;
     /** §D 第 3 路(图谱回链);缺省 = 不接,恰为 2 路。 */
     graphLaneProvider;
+    /** 孤儿记忆计数(没有任何 Room 的记录;rooms-get 面板「无绑定」chip 用)。 */
+    untaggedL1Count() {
+        return this.db.untaggedL1Count();
+    }
     /** Room 计数缓存(见 `listRooms()`:tags 仅随反刍变化,不必每次敲库)。 */
     roomCache = null;
     constructor(dataDir, db, embed = new NoopEmbeddingService(), strategy = 'hybrid', logger, 
@@ -52,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();
@@ -113,6 +121,65 @@ export class L1Store {
     patchMetadata(id, metadata) {
         return this.db.patchL1Metadata(id, metadata);
     }
+    // ── Room merge/rename 的游标重写(分类管理 beta.5;破坏性面)──────────────
+    /**
+     * 收集某 Room 的全部匹配记录(含已退场行,口径与 Room 计数一致)。
+     * 内部分页拉取,上限 cap 防跑飞;返回记录数组供备份与干跑预览。
+     */
+    listByTagAll(tag, cap = 500) {
+        const out = [];
+        for (let offset = 0; offset < cap; offset += 200) {
+            const page = this.list({ tag, retired: undefined, limit: Math.min(200, cap - out.length), offset });
+            out.push(...page.items);
+            if (page.items.length < 200 || out.length >= cap)
+                break;
+        }
+        return out;
+    }
+    /**
+     * 备份某 Room 的匹配记录到 `<dataDir>/rooms-merge-backups/<ts>-<tag>.json`
+     * (执行前快照;破坏性重写前的唯一回滚物料)。返回备份文件路径与条数。
+     */
+    backupTagRecords(tag) {
+        const records = this.listByTagAll(tag, 2000);
+        const backupDir = path.join(this.dataDir, 'rooms-merge-backups');
+        if (!existsSync(backupDir))
+            mkdirSync(backupDir, { recursive: true });
+        const file = path.join(backupDir, `${Date.now()}-${tag.replace(/[^a-z0-9-]/gi, '_')}.json`);
+        writeFileSync(file, JSON.stringify({ tag, exportedAt: new Date().toISOString(), records }, null, 2), 'utf8');
+        return { file, count: records.length };
+    }
+    /**
+     * 游标重写:把 metadata.tags 里的 `from` 全部替换为 `to`(**含已退场行**,
+     * 口径与 Room 计数一致)。写前重读-合并-写回(relabel 同款):只动 tags,
+     * roomCandidates/roomReview/hall/cogHall/sourceAnchors 等其余键原样保全。
+     *
+     * 单次上限 cap(500)可续跑:再次调用同一 from 即继续处理剩余行。
+     * 返回重写条数 + 受影响的 (family, scene) 集(供 recluster 'room-merge' 入队)。
+     */
+    rewriteTag(from, to, cap = 500) {
+        const rows = this.listByTagAll(from, cap + 1);
+        const hasMore = rows.length > cap;
+        const batch = rows.slice(0, cap);
+        let rewritten = 0;
+        const families = new Set();
+        const scenes = new Set();
+        for (const r of batch) {
+            const meta = { ...(r.metadata ?? {}) };
+            const tags = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
+            if (!tags.includes(from))
+                continue; // 命中是 json_each 判等,数组缺失即无可改
+            const next = tags.map((t) => (t === from ? to : t));
+            meta.tags = [...new Set(next)];
+            if (this.patchMetadata(r.id, meta)) {
+                rewritten++;
+                families.add(r.family ?? 'chat');
+                if (r.scene_name)
+                    scenes.add(r.scene_name);
+            }
+        }
+        return { rewritten, scanned: batch.length, families: [...families], scenes: [...scenes], hasMore };
+    }
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids) {
         return this.db.getL1ByIds(ids);

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;
+}