dsh-prime-memory 0.16.2 → 0.16.4

package/dist/prompts/l1-extraction.js

@@ -5,7 +5,11 @@
  * prompt 内容直接决定蒸馏质量,是已发布行为的一部分,不属于可自由重写文本;
  * 代码结构与注释随实现重写。
  */
+import { CONTENT_IS_DATA_CLAUSE, DATA_DELIMITER_NOTE } from './boundary.js';
 export const EXTRACT_MEMORIES_SYSTEM_PROMPT = `你是专业的"情境切分与记忆提取专家"。
+
+${CONTENT_IS_DATA_CLAUSE}
+
 你的任务是分析用户的对话，判断情境切换，并从中提取结构化的核心记忆（仅限 persona, episodic, instruction 三类）。
 
 **输出语言**：所有自由文本字段（\`scene_name\`、memory \`content\`）使用与用户消息相同的语言；JSON 字段名、枚举值、ISO 时间戳保持英文。
@@ -93,6 +97,9 @@ metadata 字段说明：
 
 请严格按上述 JSON 数组格式输出，不要输出任何额外的 Markdown 代码块修饰符（如 \`\`\`json）或解释文本。`;
 export const EXTRACT_WORK_MEMORIES_SYSTEM_PROMPT = `你是专业的"工作情境切分与团队共享记忆提取专家"。
+
+${CONTENT_IS_DATA_CLAUSE}
+
 你的任务是分析多人工作消息，判断工作情境切换，并从中提取可在项目团队内共享的结构化工作记忆。
 
 本任务面向工作场合的团队协作场景。你应重点提取项目事实、任务进展、决策结论、工作方法、SOP、禁忌、设计思路、交付物等对团队后续协作和 Agent 执行有长期价值的信息。
@@ -298,6 +305,9 @@ metadata 字段说明：
 
 请严格按上述 JSON 数组格式输出，不要输出任何额外的 Markdown 代码块修饰符（如 \`\`\`json）或解释文本。`;
 export const EXTRACT_ALL_MEMORIES_SYSTEM_PROMPT = `你是专业的"情境切分与记忆提取专家"。
+
+${CONTENT_IS_DATA_CLAUSE}
+
 你的任务是分析用户的对话，判断情境切换，并从中提取结构化的核心记忆。对话可能同时包含个人生活与工作内容：个人内容提取为个人记忆（persona/episodic/instruction），工作内容提取为团队共享工作记忆（work_fact/work_task/work_method/work_artifact），互不排斥、**每条记忆显式输出 family 字段标注归族**。
 
 **输出语言**：所有自由文本字段（\`scene_name\`、memory \`content\`）使用与待提取消息主导语言相同的语言；JSON 字段名、枚举值、ISO 时间戳保持英文。
@@ -452,10 +462,12 @@ export function formatExtractionPrompt(params) {
 【上一个情境】：${previousSceneName}
 
 【背景对话】（仅供理解上下文推断关系/时间，严禁从中提取记忆）：
+${DATA_DELIMITER_NOTE}
 ${bgText}
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 【待提取的新消息】（务必结合 timestamp 推算时间，只从这里提取记忆！）：
+${DATA_DELIMITER_NOTE}
 ${newText}${wingText}`;
 }

package/dist/prompts/persona.js

@@ -4,8 +4,11 @@
  * 净室重写说明:本文件的 prompt 文案按重写规格(Phase 2 决策)逐字沿用——
  * prompt 内容直接决定蒸馏质量,是已发布行为的一部分,不属于可自由重写文本。
  */
+import { CONTENT_IS_DATA_CLAUSE, DATA_DELIMITER_NOTE } from './boundary.js';
 const PERSONA_SYSTEM_PROMPT = `# 🧬 Persona Architect - Incremental Evolution Protocol（内容输出模式）
 
+${CONTENT_IS_DATA_CLAUSE}
+
 **输出语言**：\`persona.md\` 的所有自然语言内容（Archetype、基本信息、Chapter 1-4 正文等）使用与变化场景内容相同的语言；Markdown 语法、标签格式、文件名 \`persona.md\` 保持英文。模板里 Chapter 标识保留作骨架，非中文输出时请改用目标语言的对照说明。
 
 请你结合已有的 persona.md 和新增/变化的 block 信息深度分析，然后**直接输出 persona.md 的完整最终内容**。
@@ -96,6 +99,8 @@ const PERSONA_SYSTEM_PROMPT = `# 🧬 Persona Architect - Incremental Evolution
 - ✅ 不要添加场景导航（工程会自动追加）`;
 const TEAM_MEMORY_SYSTEM_PROMPT = `# Team Operating Doctrine Architect（内容输出模式）
 
+${CONTENT_IS_DATA_CLAUSE}
+
 **输出语言**：\`persona.md\` 的所有自然语言内容使用与变化场景内容相同的语言；Markdown 语法、标签格式、文件名 \`persona.md\` 保持英文。
 
 请你结合已有的 \`persona.md\` 和新增/变化的 L2 场景块，生成或更新一份高度精炼的团队工作原则文档。
@@ -229,6 +234,7 @@ ${triggerSection}
 - **变化场景**: ${changedSceneCount} 个（自上次更新后）
 
 ---
+${DATA_DELIMITER_NOTE}
 ${changedScenesContent}
 
 ${existingPersonaSection}

package/dist/prompts/scene.js

@@ -4,9 +4,12 @@
  * 净室重写说明:本文件的 prompt 文案按重写规格(Phase 2 决策)逐字沿用——
  * prompt 内容直接决定蒸馏质量,是已发布行为的一部分,不属于可自由重写文本。
  */
+import { CONTENT_IS_DATA_CLAUSE, DATA_DELIMITER_NOTE } from './boundary.js';
 function buildSceneSystemPrompt(maxScenes) {
     return `# Memory Consolidation Architect（场景整合 · 操作输出模式）
 
+${CONTENT_IS_DATA_CLAUSE}
+
 **输出语言**：\`.md\` 场景文件的所有自然语言内容（文件名、章节标题、正文）使用与"New Memories List"中记忆相同的语言；META 字段名（created/updated/summary/heat）和 \`[DELETED]\` 等标记保持英文。模板中给出的中文章节标题（\`## 用户核心特征\` 等）作为结构骨架——非中文输出时请用目标语言的等价表达替换。
 
 ## 角色定义 (Role Definition)
@@ -168,6 +171,8 @@ reason: 具体原因描述
 function buildWorkSceneSystemPrompt(maxScenes) {
     return `# Team Work Method Memory Consolidation Architect（场景整合 · 操作输出模式）
 
+${CONTENT_IS_DATA_CLAUSE}
+
 **输出语言**：\`.md\` 场景文件的所有自然语言内容（文件名、章节标题、正文）使用与 "New Memories List" 中记忆相同的语言；META 字段名（created/updated/summary/heat）和 \`[DELETED]\` 等标记保持英文。模板中的中文章节标题仅作为结构骨架，非中文输出时请用目标语言的等价表达替换。
 
 ## 角色定义 (Role Definition)
@@ -379,7 +384,7 @@ function getSceneSystemPrompt(maxScenes, family) {
 export function buildScenePrompt(params) {
     const { memoriesJson, sceneSummaries, sceneContents, currentTimestamp, existingSceneFiles, maxScenes, family, } = params;
     const contentsSection = sceneContents
-        ? `### 2.5 相关场景完整内容（仅供参考，write 时必须整体重写，不要只改局部）\n${sceneContents}\n`
+        ? `### 2.5 相关场景完整内容（仅供参考，write 时必须整体重写，不要只改局部）\n${DATA_DELIMITER_NOTE}\n${sceneContents}\n`
         : '';
     const fileListSection = existingSceneFiles.length > 0
         ? `### 📁 已有场景文件清单（仅以下文件可 write/delete）\n${existingSceneFiles.map((f) => `- \`${f}\``).join('\n')}\n`
@@ -387,6 +392,7 @@ export function buildScenePrompt(params) {
     const userPrompt = `**输出语言**：场景文件内容使用下方 New Memories List 中记忆的主导语言。
 
 ### 1️⃣ New Memories List
+${DATA_DELIMITER_NOTE}
 ${memoriesJson}
 
 ### 2️⃣ Existing Scene Blocks Summary

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;

package/dist/room-review.js

@@ -0,0 +1,281 @@
+import { isTag } from './metadata-validators.js';
+import { callLLM, parseJsonLogged } from './llm.js';
+export const ROOM_CANDIDATES_KEY = 'roomCandidates';
+export const ROOM_REVIEW_KEY = 'roomReview';
+/** 解析标注器输出的逐条候选(容错:id 配对失败丢弃;isTag 校验;目录内优先,≤3)。 */
+export function parseRoomCandidateItems(parsed, ids, roomCatalog) {
+    const idSet = new Set(ids);
+    const catalogSet = new Set(roomCatalog.map((r) => r.room));
+    const byId = new Map();
+    for (const item of parsed) {
+        if (!idSet.has(item.id))
+            continue;
+        const cleaned = [];
+        for (const r of item.rooms) {
+            const slug = typeof r === 'string' ? r.trim().toLowerCase() : '';
+            if (!slug || !isTag(slug))
+                continue;
+            if (!cleaned.includes(slug))
+                cleaned.push(slug);
+        }
+        // 目录内优先排前,其余兜底;截断到 3
+        cleaned.sort((a, b) => Number(catalogSet.has(b)) - Number(catalogSet.has(a)));
+        byId.set(item.id, cleaned.slice(0, 3));
+    }
+    return [...byId.entries()].map(([id, rooms]) => ({ id, rooms }));
+}
+/** 候选标注系统 prompt:喂现有 Room 词表(带计数),优先挂靠、少量新建兜底。 */
+export function roomCandidateSystemPrompt(roomCatalog) {
+    const catalog = roomCatalog.length > 0
+        ? roomCatalog
+            .slice(0, 40)
+            .map((r) => `- ${r.room}(现有 ${r.count} 条)`)
+            .join('\n')
+        : '(暂无现有 Room)';
+    return ('你是记忆库的 Room 归类器。给你若干条记忆(带 id)与现有 Room 词表(带计数),' +
+        '为每条记忆选出它最可能归属的 1-3 个 Room slug。规则:\n' +
+        '1. **优先从现有 Room 词表里选**(保持分类收敛,避免碎片化);\n' +
+        '2. 词表确实没有合适主题时,才提议最多 2 个新 slug(小写字母/数字/连字符);\n' +
+        '3. 完全无法判断时返回空数组(宁缺毋滥,不硬猜)。\n' +
+        `现有 Room 词表:\n${catalog}\n\n` +
+        '输出 JSON 数组:[{"id":"<原id>","rooms":["slug1","slug2"]}]。只输出 JSON,不要多余文字。');
+}
+/** 候选标注器:一批孤儿记录 → 候选 Room(优先现有词表;失败返回空,调用方零改动)。 */
+export async function roomCandidateChunk(ctx, cfg, logger, chunk, roomCatalog) {
+    const list = chunk.map((r, i) => `${i + 1}. id=${r.id}\n${r.content.slice(0, 300)}`).join('\n\n');
+    try {
+        const raw = await callLLM(ctx, cfg, {
+            system: roomCandidateSystemPrompt(roomCatalog),
+            user: `记忆列表:\n${list}`,
+            maxTokens: 4096,
+            layer: 'l1-extract',
+            logger,
+        });
+        const parsed = parseJsonLogged(raw, 'Room 候选标注', logger);
+        if (!Array.isArray(parsed))
+            return [];
+        const shape = parsed
+            .map((item) => ({
+            id: typeof item?.id === 'string' ? item.id : '',
+            rooms: Array.isArray(item?.rooms) ? item.rooms : [],
+        }))
+            .filter((x) => x.id !== '');
+        return parseRoomCandidateItems(shape, chunk.map((r) => r.id), roomCatalog);
+    }
+    catch (err) {
+        logger.warn(`[memory] Room 候选标注块失败(跳过 ${chunk.length} 条,原记录未改): ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/** 活跃孤儿的选择器:untagged + 未退场,跳过已 skipped 的。 */
+function selectPendingOrphans(l1, limit) {
+    const out = [];
+    const seen = new Set();
+    for (let offset = 0; offset < 2000; offset += 200) {
+        const page = l1.list({ untagged: true, retired: false, limit: 200, offset });
+        for (const r of page.items) {
+            if (seen.has(r.id))
+                continue;
+            seen.add(r.id);
+            if (r.metadata?.[ROOM_REVIEW_KEY] === 'skipped')
+                continue;
+            out.push(r);
+            if (out.length >= limit)
+                return out;
+        }
+        if (page.items.length < 200)
+            break;
+    }
+    return out;
+}
+export async function annotateOrphanCandidates(ctx, cfg, io, limit = 40, overrides = {}) {
+    const selected = selectPendingOrphans(io.l1, limit);
+    if (selected.length === 0)
+        return { selected: 0, candidates: 0, written: 0 };
+    // 合并词表:注册表条目排前(附 description,对 LLM 归类价值最高),封顶 120;
+    // 无注册表 = 纯自生长聚合(计数降序)。整批共享一张词表(一次 LLM 调用)。
+    const grown = io.l1.listRooms();
+    const regActive = io.registry?.listActive() ?? [];
+    const regSet = new Set(regActive.map((e) => e.slug));
+    const merged = [
+        ...regActive.map((e) => ({ room: e.slug, count: 0, label: e.label, description: e.description })),
+        ...grown.filter((r) => !regSet.has(r.room)).map((r) => ({ room: r.room, count: r.count })),
+    ].slice(0, 120);
+    const rows = overrides.chunkAnnotator !== undefined
+        ? await overrides.chunkAnnotator(selected, merged)
+        : await roomCandidateChunk(ctx, cfg, io.logger, selected, merged);
+    let written = 0;
+    for (const { id, rooms: candidates } of rows) {
+        if (candidates.length === 0)
+            continue;
+        const fresh = io.l1.getByIds([id])[0];
+        if (!fresh)
+            continue;
+        const meta = { ...(fresh.metadata ?? {}) };
+        meta[ROOM_CANDIDATES_KEY] = candidates;
+        meta[ROOM_REVIEW_KEY] = 'pending';
+        if (io.l1.patchMetadata(id, meta))
+            written++;
+    }
+    io.logger.info(`[memory] 孤儿候选预标记:选中 ${selected.length},产候选 ${rows.length},写 pending ${written} 条(待 agent 复查)`);
+    return { selected: selected.length, candidates: rows.length, written };
+}
+/** 待复查队列:pending 且有候选的活跃孤儿,按更新时间升序(最旧的先复查)。 */
+function pendingQueue(l1) {
+    const out = [];
+    const seen = new Set();
+    for (let offset = 0; offset < 2000; offset += 200) {
+        const page = l1.list({ untagged: true, retired: false, limit: 200, offset });
+        for (const r of page.items) {
+            if (seen.has(r.id))
+                continue;
+            seen.add(r.id);
+            const meta = (r.metadata ?? {});
+            if (meta[ROOM_REVIEW_KEY] === 'pending' && Array.isArray(meta[ROOM_CANDIDATES_KEY]))
+                out.push(r);
+        }
+        if (page.items.length < 200)
+            break;
+    }
+    return out.sort((a, b) => a.updatedAt - b.updatedAt);
+}
+/** merge 单飞哨兵(模块级;与 ruminate/wing-backfill 的时间错开由调用方保证)。 */
+let roomMergeRunning = false;
+/**
+ * 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 async function mergeRoom(io, from, to, opts = {}) {
+    const dryRun = opts.dryRun !== false;
+    const cap = Math.min(Math.max(opts.cap ?? 500, 1), 2000);
+    if (from === to)
+        throw new Error('from 与 to 相同');
+    if (!from.trim())
+        throw new Error('from 不能为空');
+    if (roomMergeRunning)
+        throw new Error('Room merge 已在进行中(单飞)');
+    const previewRows = io.l1.listByTagAll(from, 7);
+    const affected = io.l1.listByTagAll(from, cap + 1).length;
+    const preview = previewRows.slice(0, 6).map((r) => r.id);
+    if (dryRun)
+        return { dryRun: true, affected, preview, applied: 0, hasMore: affected > cap };
+    if (roomMergeRunning)
+        throw new Error('Room merge 已在进行中(单飞)');
+    roomMergeRunning = true;
+    try {
+        const backup = io.l1.backupTagRecords(from);
+        io.logger.info(`[memory] Room merge 备份:${from} → ${to},${backup.count} 条 → ${backup.file}`);
+        let applied = 0;
+        const hasMore = false; // 循环到收敛,单次调用内 hasMore 恒 false(重写返回值沿用结果形状)
+        const families = new Set();
+        const scenes = new Set();
+        // 游标重写:上限 cap/次,hasMore 时继续(总量受 cap×轮次约束,单飞内收敛)
+        for (;;) {
+            const r = io.l1.rewriteTag(from, to, cap);
+            applied += r.rewritten;
+            for (const f of r.families)
+                families.add(f);
+            for (const sc of r.scenes)
+                scenes.add(sc);
+            if (!r.hasMore || r.rewritten === 0)
+                break;
+        }
+        await io.registry.markMerged(from, to);
+        io.l1.invalidateRooms();
+        io.logger.info(`[memory] Room merge 完成:${from} → ${to},重写 ${applied} 条;受影响场景 ${scenes.size} 个`);
+        return {
+            dryRun: false,
+            affected,
+            preview,
+            applied,
+            hasMore,
+            backupFile: backup.file,
+            ...(families.size > 0 || scenes.size > 0 ? { families: [...families], scenes: [...scenes] } : {}),
+        };
+    }
+    finally {
+        roomMergeRunning = false;
+    }
+}
+/** rename = merge 1:1 + 注册表改名(冲突时抛错提示走 merge)。
+ *  归类语义:改名**不是退役**——merge 编排的 markMerged 会把旧条目置 retired,
+ *  这里在改名后恢复其先前状态(active 条目改名后仍 active,不掉出标注词表)。 */
+export async function renameRoom(io, from, to, opts = {}) {
+    const priorStatus = io.registry.bySlug?.(from)?.status ?? 'active';
+    const r = await mergeRoom(io, from, to, opts);
+    if (!r.dryRun && r.applied > 0) {
+        await io.registry.renameSlug(from, to);
+        if (priorStatus === 'active')
+            await io.registry.setStatus?.(to, 'active');
+    }
+    return r;
+}
+/** 下一条待复查(供 agent 逐个过):记录摘要 + 候选 + 现有 Room 词表 + 剩余数。 */
+export function nextReview(l1) {
+    const queue = pendingQueue(l1);
+    if (queue.length === 0)
+        return null;
+    const r = queue[0];
+    const meta = (r.metadata ?? {});
+    return {
+        id: r.id,
+        content: r.content.slice(0, 600),
+        type: r.type,
+        sceneName: r.scene_name,
+        candidates: meta[ROOM_CANDIDATES_KEY] ?? [],
+        roomCatalog: l1.listRooms().slice(0, 40),
+        remaining: queue.length,
+    };
+}
+/** 待复查剩余数(面板/工具兜底信息)。 */
+export function pendingReviewCount(l1) {
+    return pendingQueue(l1).length;
+}
+/**
+ * 确认复查结果:候选(或 agent 改写的)写入 metadata.tags(**进 Room**),
+ * 清候选、标 confirmed。**高权限门控由调用方执行**(与 memory_delete 同款)。
+ * 返回写入的 tags;id 不存在/状态非法返回 null。
+ */
+export function confirmReview(l1, id, rooms) {
+    const found = l1.getByIds([id])[0];
+    if (!found)
+        return null;
+    const meta = { ...(found.metadata ?? {}) };
+    // 已确认/已跳过的不允许重复确认(防止 agent 循环空转)
+    if (meta[ROOM_REVIEW_KEY] === 'confirmed')
+        return null;
+    const cleaned = [];
+    for (const r of rooms) {
+        if (typeof r !== 'string')
+            continue;
+        const slug = r.trim().toLowerCase();
+        if (!slug || !isTag(slug) || cleaned.includes(slug))
+            continue;
+        cleaned.push(slug);
+    }
+    if (cleaned.length === 0)
+        return null;
+    meta.tags = cleaned;
+    delete meta[ROOM_CANDIDATES_KEY];
+    meta[ROOM_REVIEW_KEY] = 'confirmed';
+    if (!l1.patchMetadata(id, meta))
+        return null;
+    l1.invalidateRooms();
+    return { tags: cleaned };
+}
+/** 跳过:标 skipped(不再进 pending 队列)。已 confirmed 的记录不受 skip 影响(挂了 Room 的不算长尾)。 */
+export function skipReview(l1, id) {
+    const found = l1.getByIds([id])[0];
+    if (!found)
+        return false;
+    const meta = { ...(found.metadata ?? {}) };
+    if (meta[ROOM_REVIEW_KEY] === 'confirmed')
+        return false;
+    meta[ROOM_REVIEW_KEY] = 'skipped';
+    return l1.patchMetadata(id, meta);
+}

package/dist/stats.d.ts

@@ -3,6 +3,8 @@ import { type MemoryConfig } from './config.js';
 import { type RecallSessionStats } from './hooks/recall.js';
 import type { RebuildController } from './pipeline/rebuild.js';
 import type { RuminateController } from './pipeline/ruminate.js';
+import type { RoomRegistryStore } from './store/rooms-registry.js';
+import type { RecallUsageStore } from './store/recall-usage.js';
 import { type LiveSettingsHandle } from './settings.js';
 import type { GraphStore } from './store/graph-store.js';
 import type { L0Store } from './store/l0.js';
@@ -23,7 +25,7 @@ export interface MemoryStatusSource {
     pending(): number;
 }
 /**
- * 端点全集运行时清单(36 个,与 tests/contract-keys.test.ts 的 ENDPOINTS 及
+ * 端点全集运行时清单(与 tests/contract-keys.test.ts 的 ENDPOINTS 及
  * contract.ts 类型映射表三方对齐,漂移由键集 diff 测试暴露)。
  * 注意:本清单同时是 HTTP 前缀路由 `/dsh-memory/rpc/<短名>` 的**放行白名单**
  * (见下方 SHORT_ENDPOINTS),漏一条 = 该端点在面板里静默消失(404 被客户端
@@ -77,6 +79,9 @@ interface MemoryRpcSources {
     rebuild?: RebuildController;
     embedManager?: EmbeddingManager;
     sessionInfo?: SessionInfoSource;
+    /** 长任务端点依赖(未装配 = 端点恒 disabled,面板不挂载)。 */
+    /** Room 注册表(未装配 = rooms-get 不带 registry,rooms-export 不可用)。 */
+    roomRegistry?: RoomRegistryStore;
 }
 /** 端点 deps 的注入面(ctx/cfg/stores/logger 由调用方绑定,其余由此处决定)。 */
 export type EndpointDepsInput = Omit<EndpointDeps, 'ctx' | 'cfg' | 'stores' | 'logger'>;
@@ -92,19 +97,25 @@ export declare function registerMemoryRpc(ctx: Context, cfg: MemoryConfig, store
     scenes: Record<MemoryFamily, SceneStore>;
     persona: Record<MemoryFamily, PersonaStore>;
     state: StateStore;
+    /** 召回使用统计(可选)。 */
+    usage?: RecallUsageStore;
     /** 记忆后端(后台边界);未装配时回退为包 l1 的进程内实现。 */
     backend?: MemoryBackend;
     /** 图谱存储(可选:未装配时图谱端点返空,不报错)。 */
     graph?: GraphStore;
 }, logger: MemoryLogger, status?: MemoryStatusSource, live?: LiveSettingsHandle, modes?: SessionModeStore, dataDir?: string, rebuild?: RebuildController, embedManager?: EmbeddingManager, sessionInfo?: SessionInfoSource, 
 /** 反刍控制器(存储降级时为 undefined):经 buildEndpointDeps 落入 deps.ruminate。 */
-ruminate?: RuminateController): void;
+ruminate?: RuminateController, 
+/** Room 分类管理依赖(注册表;缺省 = rooms-get 不带 registry、rooms-export 恒 404 语义)。 */
+roomRegistry?: RoomRegistryStore): void;
 export interface EndpointDeps {
     ctx: Context;
     cfg: MemoryConfig;
     stores: {
         l0: L0Store;
         l1: L1Store;
+        /** 召回使用统计(可选:未装配 = 列表不带 usage/usageSummary)。 */
+        usage?: RecallUsageStore;
         scenes: Record<MemoryFamily, SceneStore>;
         persona: Record<MemoryFamily, PersonaStore>;
         state: StateStore;
@@ -121,10 +132,15 @@ export interface EndpointDeps {
     ruminate?: RuminateController;
     embedManager?: EmbeddingManager;
     sessionInfo?: SessionInfoSource;
+    /** 长任务端点依赖(未装配 = 端点恒 disabled,面板不挂载)。 */
+    /** Room 注册表(未装配 = rooms-get 不带 registry,rooms-export 不可用)。 */
+    roomRegistry?: RoomRegistryStore;
 }
 /** 端点分发表(导出供测试直调:可精确注入 rebuild/ruminate 等可选控制器,验证 deps 接线)。 */
 export declare function handleEndpoint(endpoint: string, payload: unknown, deps: EndpointDeps): Promise<unknown>;
 /** 浏览器卡片字段(比 MemoryRecord 精简,去掉大 metadata;Hall 从 metadata 提取)。 */
+/** 老化权重(与读路径 applyDecayWeight 同式):max(0.5, 0.5^(Δ天/半衰期));半衰期 ≤0 = 关 → null。 */
+export declare function agingWeightOf(updatedAtMs: number | undefined, halfLifeDays: number, now?: number): number | null;
 export declare function hitToUiRecord(r: {
     id: string;
     content: string;
@@ -141,4 +157,12 @@ export declare function hitToUiRecord(r: {
     family?: string;
     /** 退场判据:`valid_to` 闭合即已退场(软删)。由 `listL1`/`getByIds` 透传。 */
     validTo?: number;
+}, extra?: {
+    agingWeight?: number | null;
+    usage?: {
+        attempts: number;
+        used: number;
+        lastAttemptAt: number | null;
+        lastUsedAt: number | null;
+    } | null;
 }): UiRecord;