dsh-prime-memory 0.18.4 → 0.18.5

package/dist/contract.d.ts

@@ -507,10 +507,91 @@ export interface WingOverviewResponse {
  * 降级/无 tags 时 `rooms` 为空数组(面板显示"暂无"),不报错。
  */
 export interface RoomsGetResponse {
-    /** Room 列表(按记录数降序,同数按名升序)。 */
+    /** Room 列表(按记录数降序,同数按名升序;注册表条目 count=0 并带 source/label)。
+     *  条目可选字段 source/label 由端点层合并注册表后附带(客户端可选读,零断裂)。 */
     rooms: RoomCount[];
     /** Room 总数(= rooms.length,冗余只为前端少写一次 .length)。 */
     total: number;
+    /** 孤儿记忆数:没有任何 Room(tags 为空/缺失)的记录条数(与 rooms 同口径含已退场)。 */
+    orphanCount: number;
+    /** 注册表条目(全量含 retired;分类管理面板用;未装配 = undefined)。 */
+    registry?: Array<{
+        slug: string;
+        label?: string;
+        description?: string;
+        source: 'pre-registered' | 'grown';
+        aliases?: string[];
+        status: 'active' | 'retired';
+    }>;
+}
+/** dsh-memory/room-register(预注册 Room;高权限:面板 memoryMutate 开启才生效)。 */
+export interface RoomRegisterRequest {
+    slug: string;
+    label?: string;
+    description?: string;
+    /** 收编自生长 slug 时传 grown(缺省 pre-registered;已存在条目忽略此字段)。 */
+    source?: 'pre-registered' | 'grown';
+}
+export interface RoomRegisterResponse {
+    slug: string;
+    created: boolean;
+    /** 幂等补全时的提示(如「已存在,只补全缺失字段」)。 */
+    notice?: string;
+}
+/** dsh-memory/rooms-export(分类数据导出,CSV 直出)。 */
+export interface RoomsExportRequest {
+    /** rooms = 词表+计数;orphans = 无 Room 绑定的记录清单;records = 按 Room 的记录清单(tag 必传)。 */
+    kind: 'rooms' | 'orphans' | 'records';
+    /** 各 kind 通用上限(1..10000,默认 2000)。 */
+    limit?: number;
+    /** kind=records 的目标 Room slug。 */
+    tag?: string;
+}
+export interface RoomsExportResponse {
+    kind: 'rooms' | 'orphans' | 'records';
+    /** CSV 文本(首行表头;
+   行尾;RFC 4180 转义)。 */
+    csv: string;
+    /** 数据行数(不含表头)。 */
+    total: number;
+    /** truncated = 达到 limit 上限,结果可能不完整。 */
+    truncated: boolean;
+}
+/** dsh-memory/room-admin(Room 破坏性面管理;高权限:面板 memoryMutate 开启才生效)。 */
+export interface RoomAdminRequest {
+    /** merge/rename:from→to(mergeRoom/renameRoom 编排:预览→实跑+自动备份+入队场景重算);retire:slug 退役/恢复;update:改写 label/description。 */
+    action: 'merge' | 'rename' | 'retire' | 'update';
+    /** update 的显示名(可中文;非空才改写)。 */
+    label?: string;
+    /** update 的归类说明(喂标注器;非空才改写)。 */
+    description?: string;
+    /** merge/rename 的源 Room slug。 */
+    from?: string;
+    /** merge/rename 的目标 Room slug。 */
+    to?: string;
+    /** retire 的目标 Room slug。 */
+    slug?: string;
+    /** retire:true=恢复 active;缺省/false=退役。 */
+    active?: boolean;
+    /** retire:同时把该 room 下全部**活跃**记录退场(软删,可在「已退场」区恢复)。 */
+    withRecords?: boolean;
+    /** merge/rename:缺省 true 只返预览;实跑需显式 false。 */
+    dryRun?: boolean;
+}
+export interface RoomAdminResponse {
+    notice: string;
+    /** merge/rename 本次是否 dryRun(预览)。 */
+    dryRun?: boolean;
+    /** merge/rename 影响的记录条数(实跑 = 已改写条数)。 */
+    affected?: number;
+    /** 预览样例(受影响记录 id 的前几条)。 */
+    preview?: string[];
+    /** true = 超过单次上限,需续跑。 */
+    hasMore?: boolean;
+    /** 实跑时改写前备份文件名(rooms-merge-backups/)。 */
+    backupFile?: string;
+    /** retire withRecords 实际退场的记录条数(软删,可恢复)。 */
+    retiredRecords?: number;
 }
 /** dsh-memory/wing-backfill(一键回填,后台任务;端点立即返回,进度以 wing-overview 轮询)。 */
 export interface WingBackfillResponse {
@@ -650,6 +731,11 @@ export interface ListRecordsRequest {
      * Room 由 tags 派生(自生长),故这里传的是**具体 tag 名**而非枚举 id。
      */
     tag?: string;
+    /**
+     * 孤儿记忆筛选:true = 只列**没有任何 Room(tags 为空/缺失)**的记录。
+     * 与 `tag` 互斥;同传时 `tag` 优先(客户端保证不同传)。
+     */
+    untagged?: boolean;
     /**
      * 退场(软删)筛查:三态。省略 = 全部(活跃+已退场混排,靠 `UiRecord.retired`
      * 徽标区分);`false` = 仅活跃;`true` = 仅已退场。
@@ -686,6 +772,15 @@ export interface UiRecord {
     sourceAnchors: string[];
     /** 检索相关度(列表路径无 score → null)。 */
     score: number | null;
+    /** 老化权重:读路径衰减系数 max(0.5, 0.5^(Δ天/半衰期))(Δ=updatedAt;半衰期 0=关 → null)。 */
+    agingWeight?: number | null;
+    /** 召回使用统计:**进 topN(被注入)才算 used**;参与尝试未进 = 仅 attempts。缺省 = 未装配。 */
+    usage?: {
+        attempts: number;
+        used: number;
+        lastAttemptAt: number | null;
+        lastUsedAt: number | null;
+    } | null;
     /**
      * 是否已退场(软删)。`true` 时该记录在活动列表里仍以「已退场」态呈现(置灰 + 徽标),
      * 可被 `records-restore` 找回——这正是设计要的「不静默消失、可恢复」,而非真删。
@@ -704,6 +799,13 @@ export interface ListRecordsResponse {
     truncated: boolean;
     /** 场景筛选下拉选项(仅 offset===0 时附带)。 */
     scenes?: string[];
+    /** 召回使用汇总(老化权重效果口径:进 topN 才算 used)。未装配 = undefined。 */
+    usageSummary?: {
+        tracked: number;
+        attempted: number;
+        used: number;
+        rate: number;
+    } | null;
     /**
      * Wing 词表(R8 单一事实源:服务端随 list-records 下发,client 不再手抄;仅 offset===0 时附带)。
      * 含 8 角 + `general`(跨域兜底,存量大 reserved 值仍可筛)。缺省(旧服务端)时 client
@@ -1201,6 +1303,9 @@ export interface DshMemoryRequestMap {
     'dsh-memory/session-mode-set': SessionModeSetRequest;
     'dsh-memory/wing-overview': Record<string, never>;
     'dsh-memory/rooms-get': Record<string, never>;
+    'dsh-memory/rooms-export': RoomsExportRequest;
+    'dsh-memory/room-register': RoomRegisterRequest;
+    'dsh-memory/room-admin': RoomAdminRequest;
     'dsh-memory/wing-backfill': Record<string, never>;
     'dsh-memory/session-stats': SessionStatsRequest;
     'dsh-memory/settings-get': Record<string, never>;
@@ -1246,6 +1351,9 @@ export interface DshMemoryResponseMap {
     'dsh-memory/session-mode-set': SessionModeSetResponse;
     'dsh-memory/wing-overview': WingOverviewResponse;
     'dsh-memory/rooms-get': RoomsGetResponse;
+    'dsh-memory/rooms-export': RoomsExportResponse;
+    'dsh-memory/room-register': RoomRegisterResponse;
+    'dsh-memory/room-admin': RoomAdminResponse;
     'dsh-memory/wing-backfill': WingBackfillResponse;
     'dsh-memory/session-stats': SessionStatsResponse;
     'dsh-memory/settings-get': SettingsGetResponse;

package/dist/hooks/capture.js

@@ -164,7 +164,9 @@ export function registerCapture(ctx, cfg, runner, l0, logger, live, modes) {
     // 补收 (L0 水位线, 末尾] 内 bracket 完整的尾轮(≤2 轮)——崩溃轮在缓冲丢失后
     // 仍可从持久化层找回(persistence 会给孤儿轮补 interrupted 闭合,探针② 实证 98 处)。
     // fail-open 纪律:任何异常只 warn,不阻塞会话启动;幂等 = 水位线 + 逐 turn 存在性检查。
-    ctx.on('agent/session-start', (payload) => {
+    // 0.1.7-rc.2 起 agent/session-start 并入 agent/created(serial:监听器需 async,
+    // 同 main 线 0.19.0 的 0.2.0 适配)。仍监听旧事件名的实现在 rc.2 宿主上永不触发。
+    ctx.on('agent/created', async (payload) => {
         try {
             if (payload.source !== 'resume')
                 return;
@@ -178,7 +180,9 @@ export function registerCapture(ctx, cfg, runner, l0, logger, live, modes) {
             const mode = modes.get(sid);
             if (mode === 'off')
                 return; // off 档对记忆系统完全隐身,对齐现行为
-            let events = session?.events;
+            // 0.1.7-rc.2 起 Session 弃用同步全量 .events,改 snapshotEvents()(同 main 线
+            // 0.19.0 的 0.2.0 适配);探针式读取,旧宿主形状走下方降级链。
+            let events = typeof session?.snapshotEvents === 'function' ? session.snapshotEvents() : undefined;
             if (!events || events.length === 0) {
                 // task_8 降级链:events 不可得(宿主版本偏差)时依次试
                 // ctx.sessionQuery.readSession / ctx.sessionPersistence.readFrom(守卫探针式)

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';
 /**
@@ -89,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

@@ -112,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);
     /** 记忆占用流水(账本迁移写穿;重启后历史会话账目由此复生)。 */
@@ -218,7 +220,8 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
     // 上下文压缩/清空 → 已注入内容从模型上下文丢失,重置该会话的去重压制
     // (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);
@@ -378,6 +381,7 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                         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 });
@@ -389,6 +393,7 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                         injectedIds: [], suppressedCount: scoped.length - fresh.length,
                         durationMs: Date.now() - searchStart, outcome: 'suppressed',
                     });
+                    usage?.recordAttempt(fresh.map((h) => h.id), []);
                     return decision;
                 }
                 st.lastHits = lines.length;
@@ -421,6 +426,8 @@ export function registerRecall(ctx, cfg, stores, logger, live, modes, dataDir) {
                     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);
@@ -568,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.js

@@ -36,6 +36,8 @@ 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';
@@ -158,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,不影响双路。
@@ -350,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);
@@ -378,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/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);
         }

package/dist/room-review.d.ts

@@ -0,0 +1,196 @@
+/**
+ * 孤儿记忆的 Room 候选预标记 + agent 逐个复查(长尾治理)。
+ *
+ * 背景:Room 由 metadata.tags 自生长,但 tags 只在反刍 relabel 段随 wing 补打
+ * 顺带产出(每轮 ≤40 条、且只覆盖本轮补 wing 的记录)——「有 wing 无 tags」与
+ * 「预算用尽被 deferred」的记录成为无 Room 绑定的孤儿,且标注器不参考现有
+ * Room 词表,产出碎片化新 slug(81 个 Room 大多 1 条的成因)。
+ *
+ * 两段式:
+ *  1. **预标记(annotateOrphanCandidates)**:抽取活跃孤儿,LLM 对照**现有 Room
+ *     词表**产出候选(优先挂靠现有 Room,≤2 个新 slug 兜底),写
+ *     `metadata.roomCandidates` + `roomReview:'pending'`——不动 tags、不进
+ *     Room、不进召回,只是"待确认的建议"。
+ *  2. **逐个复查(memory_room_review 工具)**:agent 取下一条待复查记录
+ *     (带候选 + 现有 Room 词表),确认后 confirm 写入 tags(进 Room,高权限
+ *     门控),或 skip 跳过。确认/跳过都是显式动作,预标记本身零行为面。
+ *
+ * 存储即 metadata 保留键(与 relabel 写 tags 同款 patchMetadata 合并纪律,
+ * 写前重读):`roomCandidates` / `roomReview:'pending'|'confirmed'|'skipped'`。
+ * 两键不在 rooms 聚合(rooms 只读 $.tags)、不在快照哈希投影关注的治理列——
+ * 与既有 metadata 键同层,无 schema 变更。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from './config.js';
+import type { MemoryLogger, MemoryRecord } from './types.js';
+export declare const ROOM_CANDIDATES_KEY = "roomCandidates";
+export declare const ROOM_REVIEW_KEY = "roomReview";
+export type RoomReviewState = 'pending' | 'confirmed' | 'skipped';
+/** 复查与候选操作对 L1 的最小依赖面(便于测试注入)。 */
+export interface RoomReviewStore {
+    list(opts: {
+        untagged?: boolean;
+        retired?: boolean;
+        limit: number;
+        offset: number;
+    }): {
+        items: MemoryRecord[];
+        total: number;
+    };
+    getByIds(ids: readonly string[]): MemoryRecord[];
+    patchMetadata(id: string, metadata: Record<string, unknown>): boolean;
+    listRooms(): Array<{
+        room: string;
+        count: number;
+    }>;
+    /** 确认写 tags 后失效 Room 计数缓存(30s TTL)。 */
+    invalidateRooms(): void;
+}
+/** merge/rename 的 store 面(RoomReviewStore + 游标重写与备份;L1Store 已实现)。 */
+export interface RoomMergeStore extends RoomReviewStore {
+    listByTagAll(tag: string, cap?: number): MemoryRecord[];
+    backupTagRecords(tag: string): {
+        file: string;
+        count: number;
+    };
+    rewriteTag(from: string, to: string, cap?: number): {
+        rewritten: number;
+        scanned: number;
+        families: string[];
+        scenes: string[];
+        hasMore: boolean;
+    };
+}
+/** Room 注册表最小面(merge 收尾;RoomRegistryStore 已满足)。 */
+export interface RoomRegistryMerge {
+    markMerged(fromSlug: string, toSlug: string): Promise<boolean>;
+    renameSlug(oldSlug: string, newSlug: string): Promise<boolean>;
+    /** rename 收尾恢复先前状态用(active 条目改名后不掉出标注词表)。 */
+    bySlug?(slug: string): {
+        status: 'active' | 'retired';
+    } | undefined;
+    setStatus?(slug: string, status: 'active' | 'retired'): Promise<boolean>;
+}
+export interface RoomCandidate {
+    id: string;
+    rooms: string[];
+}
+/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isTag 校验;目录内优先,≤3)。 */
+export declare function parseRoomCandidateItems(parsed: ReadonlyArray<{
+    id: string;
+    rooms: readonly string[];
+}>, ids: ReadonlyArray<string>, roomCatalog: ReadonlyArray<{
+    room: string;
+    count: number;
+}>): RoomCandidate[];
+/** 候选标注系统 prompt:喂现有 Room 词表(带计数),优先挂靠、少量新建兜底。 */
+export declare function roomCandidateSystemPrompt(roomCatalog: ReadonlyArray<{
+    room: string;
+    count: number;
+}>): string;
+/** 候选标注器:一批孤儿记录 → 候选 Room(优先现有词表;失败返回空,调用方零改动)。 */
+export declare function roomCandidateChunk(ctx: Context, cfg: MemoryConfig, logger: MemoryLogger, chunk: MemoryRecord[], roomCatalog: ReadonlyArray<{
+    room: string;
+    count: number;
+}>): Promise<Array<{
+    id: string;
+    rooms: string[];
+}>>;
+export interface OrphanAnnotateIO {
+    l1: RoomReviewStore;
+    logger: MemoryLogger;
+    /** Room 注册表(可选:未装配 = 词表只用自生长聚合,无注册条目)。 */
+    registry?: {
+        listActive(): Array<{
+            slug: string;
+            label?: string;
+            description?: string;
+        }>;
+    };
+}
+/**
+ * 预标记消费器:活跃孤儿(≤limit 条)批量产候选并写 pending。
+ * 写前重读合并(与 relabel 同纪律);失败单条跳过、原记录零改动。
+ */
+export interface OrphanAnnotateOverrides {
+    /** 测试注入口:替换 LLM 候选标注器(默认走真实 callLLM 路径);第二参为合并词表。 */
+    chunkAnnotator?: (chunk: MemoryRecord[], catalog: ReadonlyArray<{
+        room: string;
+        count: number;
+        label?: string;
+        description?: string;
+    }>) => Promise<Array<{
+        id: string;
+        rooms: string[];
+    }>>;
+}
+export declare function annotateOrphanCandidates(ctx: Context, cfg: MemoryConfig, io: OrphanAnnotateIO, limit?: number, overrides?: OrphanAnnotateOverrides): Promise<{
+    selected: number;
+    candidates: number;
+    written: number;
+}>;
+export interface MergeRoomResult {
+    dryRun: boolean;
+    /** 影响条数(dryRun=预览数;实跑=实际重写数)。 */
+    affected: number;
+    preview: string[];
+    applied: number;
+    hasMore: boolean;
+    backupFile?: string;
+    /** 实跑时回传:受影响的族与场景(调用方入队 recluster 'room-merge')。 */
+    families?: string[];
+    scenes?: string[];
+}
+/**
+ * Room merge/rename 编排(破坏性动作,分类管理 beta.5):
+ *  - dryRun(缺省 true):只统计 affected + 前 6 条预览,**零写入**;
+ *  - 实跑:执行前备份(matching rows → rooms-merge-backups/)→ 游标重写
+ *    (写前重读-合并-写回,其余 metadata 键保全)→ 注册表 markMerged/renameSlug
+ *    → 返回受影响 (family, scene) 供调用方入队 recluster('room-merge');
+ *  - 单飞:并发 merge 直接抛错;与 relabel/ruminate 的时间错开由调用方保证。
+ * 抛错语义:非法参数/注册表冲突直接抛(调用方转 notice)。
+ */
+export declare function mergeRoom(io: {
+    l1: RoomMergeStore;
+    registry: RoomRegistryMerge;
+    logger: MemoryLogger;
+}, from: string, to: string, opts?: {
+    dryRun?: boolean;
+    cap?: number;
+}): Promise<MergeRoomResult>;
+/** rename = merge 1:1 + 注册表改名(冲突时抛错提示走 merge)。
+ *  归类语义:改名**不是退役**——merge 编排的 markMerged 会把旧条目置 retired,
+ *  这里在改名后恢复其先前状态(active 条目改名后仍 active,不掉出标注词表)。 */
+export declare function renameRoom(io: {
+    l1: RoomMergeStore;
+    registry: RoomRegistryMerge;
+    logger: MemoryLogger;
+}, from: string, to: string, opts?: {
+    dryRun?: boolean;
+    cap?: number;
+}): Promise<MergeRoomResult>;
+/** 下一条待复查(供 agent 逐个过):记录摘要 + 候选 + 现有 Room 词表 + 剩余数。 */
+export declare function nextReview(l1: RoomReviewStore): {
+    id: string;
+    content: string;
+    type: string;
+    sceneName: string;
+    candidates: string[];
+    roomCatalog: Array<{
+        room: string;
+        count: number;
+    }>;
+    remaining: number;
+} | null;
+/** 待复查剩余数(面板/工具兜底信息)。 */
+export declare function pendingReviewCount(l1: RoomReviewStore): number;
+/**
+ * 确认复查结果:候选(或 agent 改写的)写入 metadata.tags(**进 Room**),
+ * 清候选、标 confirmed。**高权限门控由调用方执行**(与 memory_delete 同款)。
+ * 返回写入的 tags;id 不存在/状态非法返回 null。
+ */
+export declare function confirmReview(l1: RoomReviewStore, id: string, rooms: readonly string[]): {
+    tags: string[];
+} | null;
+/** 跳过:标 skipped(不再进 pending 队列)。已 confirmed 的记录不受 skip 影响(挂了 Room 的不算长尾)。 */
+export declare function skipReview(l1: RoomReviewStore, id: string): boolean;