@kenz1117/dsh-engram 0.6.1 → 0.7.1

package/lib/index.js

@@ -1,10 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { homedir } from "node:os";
 import z from "@deepseek-ai/schemastery";
-import { mkdir, writeFile } from "node:fs/promises";
-import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { createGzip, gunzip } from "node:zlib";
+import { promisify } from "node:util";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region src/config.ts
 /**
@@ -257,6 +259,8 @@ async function streamText(ctx, params) {
 const MEMORY_CONTEXT_TAG = "engram_memory_context";
 /** 当前用户请求协议标签。 */
 const CURRENT_USER_REQUEST_TAG = "current_user_request";
+/** 用户显式禁记标签：在对话中用 <no-palace>...</no-palace> 包裹的整段不会被记忆。 */
+const NO_PALACE_TAG = "no-palace";
 /**
 * 入库剥离时识别的记忆上下文标签集合：不区分来源——历史正文可能携带
 * 其他记忆插件（如 memmy/memos）的包裹标签，一律按不可信协议块剥离。
@@ -274,7 +278,7 @@ const MEMORY_CONTEXT_TAGS = [
 * @returns 可安全入库/复用的正文。
 */
 function sanitizeProtocolText(value) {
-	return normalizeWhitespace(unwrapCurrentUserRequestBlocks(stripMemoryContextBlocks(value)));
+	return normalizeWhitespace(unwrapCurrentUserRequestBlocks(stripMemoryContextBlocks(stripNoPalaceBlocks(value))));
 }
 /**
 * 渲染记忆包：内容先清洗再包裹协议标签，附三条使用警告；当前请求独立成段。
@@ -320,6 +324,10 @@ function stripMemoryContextBlocks(value) {
 	for (const tag of MEMORY_CONTEXT_TAGS) text = replaceTaggedBlocks(text, tag, () => "", { removeUnclosedTail: true });
 	return text;
 }
+/** 剥离 <no-palace>...</no-palace> 整段：用户显式禁记（默认整段移除，不留存任何痕迹）。 */
+function stripNoPalaceBlocks(value) {
+	return replaceTaggedBlocks(value, NO_PALACE_TAG, () => "", { removeUnclosedTail: true });
+}
 /** 解包 current_user_request 块，保留内部文本（当前请求是可信正文，只是去除标签）。 */
 function unwrapCurrentUserRequestBlocks(value) {
 	return replaceTaggedBlocks(value, CURRENT_USER_REQUEST_TAG, (inner) => inner);
@@ -507,6 +515,66 @@ function collectTexts(events, includeAssistant) {
 		minSeq
 	};
 }
+/** 寒暄正则：整段用户输入只含问候/感谢等无信息内容时跳过摄取。 */
+const CHITCHAT_RE = /^(?:你好|您好|嗨|哈喽|hello|hi|hey|谢谢|感谢|ok|okay|好的|在吗|收到|辛苦了)[!！,.，。?？~\s]*$/iu;
+/** 显式禁记正则：用户明确要求不要记住本轮内容时跳过摄取（窄匹配整句指令，避免误伤）。 */
+const NO_CAPTURE_RE = /(?:不要|别|不用|无需)(?:把这?[个件些条]?|把上一?轮|把刚才)?(?:记|存)(?:住|录|下来|进去|到记忆|进记忆)|don'?t\s+(?:remember|record|save)\s+(?:this|that|it)/i;
+/** 工具多样性得分：无工具 0；1-2 种 1；≥3 种 2。 */
+function toolDiversity(distinct) {
+	return distinct === 0 ? 0 : distinct <= 2 ? 1 : 2;
+}
+/**
+* 活动评分（四信号，< ACTIVITY_THRESHOLD 跳过摄取）：
+* min(floor(userChars/50), 3) + completedTurns + min(floor(toolResults/5), 2) + toolDiversity。
+* @param signals - 上一轮活动信号。
+* @returns 0-8 的整数评分。
+*/
+function activityScore(signals) {
+	return Math.min(Math.floor(signals.userChars / 50), 3) + signals.completedTurns + Math.min(Math.floor(signals.toolResults / 5), 2) + toolDiversity(signals.toolNames.size);
+}
+/** 判断用户输入是否为纯寒暄（无信息内容）。 */
+function isChitchat(text) {
+	return CHITCHAT_RE.test(text.trim());
+}
+/** 判断用户输入是否显式要求不要记住。 */
+function forbidsCapture(text) {
+	return NO_CAPTURE_RE.test(text);
+}
+/** 从事件切片提取活动信号（用户文本排除插件注入的快照消息）。 */
+function turnSignals(events) {
+	let userChars = 0;
+	let completedTurns = 0;
+	let toolResults = 0;
+	const toolNames = /* @__PURE__ */ new Set();
+	for (const event of events) if (event.type === "user/message") {
+		const data = event.data;
+		if (data?.source?.kind === "plugin") continue;
+		for (const block of data?.content ?? []) if (block?.type === "text" && typeof block.text === "string") userChars += block.text.length;
+	} else if (event.type === "assistant/message") {
+		if ((event.data?.content ?? []).some((block) => block?.type === "text" && typeof block.text === "string" && block.text !== "")) completedTurns = 1;
+	} else if (event.type === "tool/result") toolResults += 1;
+	else if (event.type === "tool/call") {
+		const name = event.data?.name;
+		if (typeof name === "string") toolNames.add(name);
+	}
+	return {
+		userChars,
+		completedTurns,
+		toolResults,
+		toolNames
+	};
+}
+/**
+* 上一轮自动摄取的节流判定（只作用于 previous 切片；末轮/pending 重放补做不受限）。
+* @returns 跳过原因；null = 允许摄取。
+*/
+function throttleDecision(events) {
+	if (activityScore(turnSignals(events)) < 5) return "low-activity";
+	const joined = collectTexts(events, false).texts.join(" ");
+	if (joined !== "" && isChitchat(joined)) return "chitchat";
+	if (forbidsCapture(joined)) return "capture-forbidden";
+	return null;
+}
 /** 各 turn/start 事件的下标与轮次号（缺 data.turn 时轮次为 undefined）。 */
 function turnStarts(events) {
 	const starts = [];
@@ -579,6 +647,15 @@ async function ingestPreviousTurn(deps) {
 		written: 0,
 		skipped: "already-ingested"
 	};
+	if (sliceMode === "previous") {
+		const throttled = throttleDecision(slice);
+		if (throttled !== null) return {
+			scannedEvents: slice.length,
+			candidates: 0,
+			written: 0,
+			skipped: throttled
+		};
+	}
 	const scoped = omitRecallToolResults(slice);
 	const { texts, minSeq } = collectTexts(scoped, limits.includeAssistant);
 	const cleaned = texts.map((text) => redactSecrets(sanitizeProtocolText(text)));
@@ -734,6 +811,713 @@ async function replayPendingIngests(deps) {
 	};
 }
 //#endregion
+//#region src/consolidation/run.ts
+/** 单条整理动作（写入 op_log 的统一标记）。 */
+const CONSOLIDATION_OP = "consolidation";
+/** 默认参数。 */
+const DEFAULTS = {
+	olderThanDays: 30,
+	importanceBelow: .3,
+	mergeThreshold: .92
+};
+/** 闭馆整理主函数：纯异步，不抛错（失败仅记日志 / 落 pending）。 */
+async function runConsolidation(store, embedder, opts = {}) {
+	const start = Date.now();
+	const options = {
+		...DEFAULTS,
+		...opts
+	};
+	const scope = options.scope ?? "user";
+	const stats = await store.stats();
+	const records = await store.topActive(scope, Math.max(stats.active, 0));
+	const archivedIds = /* @__PURE__ */ new Set();
+	let archived = 0;
+	let merged = 0;
+	let skipped = 0;
+	const now = Date.now();
+	const ageCutoff = options.olderThanDays * 864e5;
+	for (const record of records) {
+		if (record.importance >= options.importanceBelow) continue;
+		if (now - record.createdAt < ageCutoff) continue;
+		if (record.confidence >= .3) continue;
+		try {
+			await store.forget(record.id);
+			archivedIds.add(record.id);
+			archived += 1;
+		} catch {
+			skipped += 1;
+		}
+	}
+	const emb = await embedder;
+	const buckets = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		if (archivedIds.has(record.id)) continue;
+		const list = buckets.get(record.kind) ?? [];
+		list.push(record);
+		buckets.set(record.kind, list);
+	}
+	const seedIds = options.mergeCandidateIds !== void 0 ? new Set(options.mergeCandidateIds) : null;
+	for (const list of buckets.values()) {
+		if (list.length < 2) continue;
+		if (seedIds !== null && !list.some((record) => seedIds.has(record.id))) continue;
+		if (emb === void 0) {
+			const seen = /* @__PURE__ */ new Map();
+			for (const record of list) {
+				const key = record.content.slice(0, 60);
+				const existing = seen.get(key);
+				if (existing === void 0) seen.set(key, record);
+				else if (record.importance > existing.importance) {
+					await store.supersedeMany({
+						scope,
+						kind: record.kind,
+						content: record.content,
+						importance: record.importance,
+						confidence: record.confidence
+					}, [existing.id]).catch(() => {
+						skipped += 1;
+					});
+					merged += 1;
+					seen.set(key, record);
+				}
+			}
+			continue;
+		}
+		const vectors = /* @__PURE__ */ new Map();
+		for (const record of list) {
+			if (seedIds !== null && !seedIds.has(record.id)) continue;
+			try {
+				const vec = (await emb.embed([record.content]))[0];
+				if (vec !== void 0) vectors.set(record.id, vec);
+			} catch {
+				skipped += 1;
+			}
+		}
+		const arr = list.filter((record) => vectors.has(record.id));
+		const visited = /* @__PURE__ */ new Set();
+		for (let i = 0; i < arr.length; i += 1) {
+			const a = arr[i];
+			if (visited.has(a.id)) continue;
+			const dupes = [];
+			for (let j = i + 1; j < list.length; j += 1) {
+				const b = list[j];
+				if (visited.has(b.id)) continue;
+				const bVec = vectors.get(b.id);
+				if (bVec === void 0) continue;
+				if (cosine$1(vectors.get(a.id), bVec) >= options.mergeThreshold) dupes.push(b);
+			}
+			if (dupes.length === 0) continue;
+			const ids = dupes.map((record) => record.id);
+			try {
+				await store.supersedeMany({
+					scope,
+					kind: a.kind,
+					content: a.content,
+					importance: a.importance,
+					confidence: a.confidence
+				}, ids);
+				for (const id of ids) visited.add(id);
+				visited.add(a.id);
+				merged += 1;
+			} catch {
+				skipped += 1;
+			}
+		}
+	}
+	const report = {
+		archived,
+		merged,
+		skipped,
+		tookMs: Date.now() - start
+	};
+	try {
+		await store.audit(CONSOLIDATION_OP, "AUX", JSON.stringify({
+			scope,
+			archived: report.archived,
+			merged: report.merged,
+			skipped: report.skipped,
+			tookMs: report.tookMs
+		}));
+	} catch {}
+	return report;
+}
+/** cosine 相似度（两个等长非零向量）。 */
+function cosine$1(a, b) {
+	let dot = 0;
+	let na = 0;
+	let nb = 0;
+	const n = Math.min(a.length, b.length);
+	for (let i = 0; i < n; i += 1) {
+		dot += a[i] * b[i];
+		na += a[i] * a[i];
+		nb += b[i] * b[i];
+	}
+	const denom = Math.sqrt(na) * Math.sqrt(nb);
+	return denom === 0 ? 0 : dot / denom;
+}
+//#endregion
+//#region src/mirror/markdown.ts
+/**
+* Markdown 镜像：把 SQLite 记忆库导出为可被 Obsidian / VS Code / git 直接漫游的
+* 文件树，每个房间一个 .md + frontmatter，附楼层清单 _meta.json 与全宫殿入口 _index.md。
+* 写入过程全部幂等：重复执行只会覆盖同名文件，不会向 SQLite 写任何东西（只读）。
+* @module @kenz1117/dsh-engram/mirror/markdown
+*/
+/** 房间铭牌 URL/路径安全的 slug（仅 ASCII、连字符分隔）。 */
+function slugify(input) {
+	const stripped = input.toLowerCase().replace(/[\u4e00-\u9fa5]+/g, "记").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return stripped === "" ? "untitled" : stripped.slice(0, 32);
+}
+/** frontmatter 字段值序列化（string 原样、数字 / 布尔直接、null 空字符串）。 */
+function yaml(value) {
+	if (value === null || value === void 0) return "\"\"";
+	if (typeof value === "string") return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", " ")}"`;
+	return JSON.stringify(value);
+}
+/** ISO 时间戳（秒级，frontmatter 与 _meta 通用）。 */
+function iso(ms) {
+	return new Date(ms).toISOString();
+}
+/** 楼层中文别名（与面板 i18n 的 kindLabel 保持一致；只用做目录名）。 */
+const FLOOR_LABEL = {
+	fact: "fact",
+	preference: "preference",
+	decision: "decision",
+	episode: "episode",
+	skill: "skill"
+};
+/** 顶层 _index.md 的纯文本模板（楼层卡片 + 房间清单链接）。 */
+function renderIndex(scope, data, floors) {
+	const total = data.records.length;
+	const active = data.records.filter((r) => r.status === "active").length;
+	const edges = data.edges.length;
+	return `# 记忆宫殿 · ${scope === "user" ? "私人宫殿" : "项目宫殿"}\n` + [
+		"",
+		`> 导出时间 ${iso(data.exportedAt)} · 共 **${total}** 间房间（对外开放 ${active}） · 走廊 ${edges} 条`,
+		"",
+		"## 楼层导览",
+		"",
+		...floors.map((f) => `- **${FLOOR_LABEL[f.kind] ?? f.kind} 层** · ${f.roomCount} 间（开放 ${f.active} · 展厅 ${f.archived} · 闭馆 ${f.forgotten}）`),
+		"",
+		"## 房间清单",
+		"",
+		...data.records.slice().sort((a, b) => b.importance - a.importance).map((record) => `- [${record.status === "active" ? "●" : record.status === "archived" ? "◇" : "×"}][${FLOOR_LABEL[record.kind] ?? record.kind}] ${record.content.slice(0, 60)}${record.content.length > 60 ? "…" : ""} — [[${record.id.slice(0, 8)}]]`),
+		"",
+		"## 走廊（关系边）",
+		"",
+		...edges === 0 ? ["（暂无走廊）"] : data.edges.map((edge) => `- \`${edge.from.slice(0, 8)}\` --${edge.type}--> \`${edge.to.slice(0, 8)}\``),
+		""
+	].join("\n");
+}
+/** 单房间 .md 模板：YAML frontmatter + 铭牌正文 + 走廊列表。 */
+function renderRoom(record, edges) {
+	const relEdges = edges.filter((edge) => edge.from === record.id || edge.to === record.id);
+	const tags = [];
+	if (record.outcome !== void 0) tags.push(`outcome-${record.outcome}`);
+	if (record.content.includes("[REDACTED:")) tags.push("redacted");
+	const imagery = record.imagery;
+	const caption = imagery?.caption;
+	const sensory = imagery?.sensoryTags ?? [];
+	const frontmatter = [
+		"---",
+		`id: ${record.id}`,
+		`scope: ${record.scope}`,
+		`kind: ${record.kind}`,
+		`status: ${record.status}`,
+		`importance: ${record.importance.toFixed(3)}`,
+		`confidence: ${record.confidence.toFixed(3)}`,
+		`createdAt: "${iso(record.createdAt)}"`,
+		`accessCount: ${record.accessCount}`,
+		`sourceSession: ${record.sourceSessionId === null ? "\"\"" : yaml(record.sourceSessionId)}`,
+		`sourceRound: ${record.sourceRound ?? "\"\""}`,
+		...tags.length === 0 ? [] : [`tags: [${tags.join(", ")}]`],
+		...caption !== void 0 && caption !== null ? [`imageryCaption: ${yaml(caption)}`] : [],
+		...sensory.length > 0 ? [`imagerySensory: [${sensory.map((s) => yaml(s)).join(", ")}]`, `imageryValence: ${(imagery?.emotionalValence ?? 0).toFixed(3)}`] : [],
+		"---"
+	].join("\n");
+	const body = [
+		`# ${record.content.split("\n")[0]?.slice(0, 80) ?? "房间铭牌"}`,
+		"",
+		record.content,
+		"",
+		"## 走廊",
+		"",
+		...relEdges.length === 0 ? ["（此房间暂未连接任何走廊）"] : relEdges.map((edge) => {
+			const other = edge.from === record.id ? edge.to : edge.from;
+			return `- ${edge.from === record.id ? "→" : "←"} \`${other.slice(0, 8)}\`（${edge.type}）`;
+		}),
+		""
+	].join("\n");
+	return frontmatter + "\n" + body;
+}
+/** 楼层 _meta.json 模板。 */
+function renderMeta(scope, data, floors) {
+	const payload = {
+		scope,
+		exportedAt: data.exportedAt,
+		total: data.records.length,
+		floors
+	};
+	return JSON.stringify(payload, null, 2) + "\n";
+}
+/** 计算楼层摘要（按 kind 分组统计 active/archived/forgotten）。 */
+function summarizeFloors(records) {
+	const map = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const entry = map.get(record.kind) ?? {
+			roomCount: 0,
+			active: 0,
+			archived: 0,
+			forgotten: 0
+		};
+		entry.roomCount += 1;
+		if (record.status === "active") entry.active += 1;
+		else if (record.status === "archived") entry.archived += 1;
+		else if (record.status === "forgotten") entry.forgotten += 1;
+		map.set(record.kind, entry);
+	}
+	return [...map.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([kind, count]) => ({
+		kind,
+		...count
+	}));
+}
+/**
+* 把一份 exportAll 数据写入镜像目录。
+* @param rootDir - 镜像根目录（通常 `${exportDir}/mirror/<scope>/`，由调用方拼）。
+* @param data - exportAll 的产物（含 records + edges）。
+* @returns 写入摘要（rootDir / fileCount / floors）。
+*/
+async function writeMirror(rootDir, data) {
+	const scope = data.records[0]?.scope ?? "user";
+	await mkdir(rootDir, {
+		recursive: true,
+		mode: 448
+	});
+	const floors = summarizeFloors(data.records);
+	const recordsByKind = /* @__PURE__ */ new Map();
+	for (const record of data.records) {
+		const list = recordsByKind.get(record.kind) ?? [];
+		list.push(record);
+		recordsByKind.set(record.kind, list);
+	}
+	let fileCount = 0;
+	for (const record of data.records) {
+		const floor = recordsByKind.get(record.kind);
+		if (floor === void 0) continue;
+		const indexInFloor = floor.indexOf(record);
+		const floorDir = join(rootDir, FLOOR_LABEL[record.kind] ?? record.kind);
+		await mkdir(floorDir, {
+			recursive: true,
+			mode: 448
+		});
+		const fileName = `${record.id.slice(0, 8)}-${slugify(record.content)}-${String(indexInFloor).padStart(3, "0")}.md`;
+		await writeFile(join(floorDir, fileName), renderRoom(record, data.edges), { mode: 384 });
+		fileCount += 1;
+	}
+	await writeFile(join(rootDir, "_index.md"), renderIndex(scope, data, floors), { mode: 384 });
+	await writeFile(join(rootDir, "_meta.json"), renderMeta(scope, data, floors), { mode: 384 });
+	fileCount += 2;
+	if (scope === "shared") {
+		const manifest = buildShareManifest(data);
+		await writeFile(join(rootDir, "share-manifest.json"), JSON.stringify(manifest, null, 2) + "\n", { mode: 384 });
+		fileCount += 1;
+	}
+	return {
+		rootDir,
+		fileCount,
+		floors,
+		exportedAt: data.exportedAt
+	};
+}
+/**
+* 从导出数据构造借阅归还清单（仅 shared scope 调用）。
+* firstLentAt 用 createdAt 替代（数据库没记首次公开时刻，这是务实选择）。
+*/
+function buildShareManifest(data, now = Date.now()) {
+	const loans = data.records.filter((record) => record.scope === "shared").map((record) => ({
+		id: record.id,
+		kind: record.kind,
+		status: record.status,
+		importance: record.importance,
+		confidence: record.confidence,
+		firstLentAt: record.createdAt,
+		lastAccessedAt: record.lastAccessedAt,
+		accessCount: record.accessCount
+	}));
+	return {
+		generatedAt: now,
+		scope: "shared",
+		roomCount: loans.length,
+		loans
+	};
+}
+//#endregion
+//#region src/backup/tar-stream.ts
+/**
+* 极简 tar 流的写入与解包：UStar 格式（POSIX.1-1988），足够本插件「打包几个 .db + _meta.json」场景。
+* 文件名长度 ≤ 99 字节、文件 ≤ 8 GiB 已覆盖本插件的备份规模；超过则抛错。
+* 不依赖 npm 包（无第三方 = 无供应链风险）；可被测试套件无障碍运行。
+* @module @kenz1117/dsh-engram/backup/tar-stream
+*/
+/** UStar 头字段宽度（POSIX.1-1988）。 */
+const BLOCK_SIZE = 512;
+const NAME_LEN = 100;
+const SIZE_LEN = 12;
+/** 把数字按八进制 + ASCII 写入固定宽度（末尾置空）。 */
+function writeOctal(buf, offset, length, value) {
+	const str = value.toString(8).padStart(length - 1, "0");
+	buf.write(str, offset, length - 1, "ascii");
+	buf.write("\0", offset + length - 1, 1, "ascii");
+}
+/** 校验和：头块 0-511 字节所有字节求和（chksum 字段本身按空格处理）。 */
+function computeChecksum(header) {
+	let sum = 0;
+	for (let i = 0; i < BLOCK_SIZE; i += 1) sum += header[i];
+	return sum;
+}
+/** 写一个文件条目到 tar 流（UStar 头 + 数据 + 填充到 512 边界）。 */
+function createTarPack(out, name, data) {
+	if (name.length >= NAME_LEN) throw new Error(`tar 文件名过长（${String(name.length)} / ${String(99)}）：${name}`);
+	if (data.length >= 2 ** 88 - 1) throw new Error(`tar 文件过大：${name}（${String(data.length)} bytes）`);
+	const header = Buffer.alloc(BLOCK_SIZE);
+	header.write(name, 0, NAME_LEN, "ascii");
+	writeOctal(header, 100, 8, 384);
+	writeOctal(header, 108, 8, 0);
+	writeOctal(header, 116, 8, 0);
+	writeOctal(header, 124, SIZE_LEN, data.length);
+	writeOctal(header, 136, 12, Math.floor(Date.now() / 1e3));
+	header.write("0", 156, 1, "ascii");
+	header.write("ustar\0", 257, 6, "ascii");
+	header.write("00", 263, 2, "ascii");
+	header.write("        ", 148, 8, "ascii");
+	writeOctal(header, 148, 8, computeChecksum(header));
+	out.write(header);
+	out.write(data);
+	const padLen = (BLOCK_SIZE - data.length % BLOCK_SIZE) % BLOCK_SIZE;
+	if (padLen > 0) out.write(Buffer.alloc(padLen));
+}
+/** 写两个全 0 块作为 tar 结束标记（EOF）。 */
+function endTarPack(out) {
+	out.write(Buffer.alloc(BLOCK_SIZE * 2));
+}
+/** 解 tar 字节流到目标目录。整段读完再解析（备份场景文件小、可接受）。 */
+async function extractTar(buffer, destDir) {
+	const { writeFile, mkdir } = await import("node:fs/promises");
+	const { dirname } = await import("node:path");
+	let offset = 0;
+	while (offset + BLOCK_SIZE <= buffer.length) {
+		const header = buffer.subarray(offset, offset + BLOCK_SIZE);
+		if (header.every((b) => b === 0)) return;
+		const name = header.toString("ascii", 0, NAME_LEN).replace(/\0+$/, "");
+		const sizeOct = header.toString("ascii", 124, 136).replace(/\0+$/, "");
+		const size = parseInt(sizeOct, 8);
+		offset += BLOCK_SIZE;
+		if (size > 0) {
+			const data = buffer.subarray(offset, offset + size);
+			const target = join(destDir, name);
+			await mkdir(dirname(target), {
+				recursive: true,
+				mode: 448
+			});
+			await writeFile(target, data, { mode: 384 });
+			const pad = (BLOCK_SIZE - size % BLOCK_SIZE) % BLOCK_SIZE;
+			offset += size + pad;
+		} else offset += (BLOCK_SIZE - size % BLOCK_SIZE) % BLOCK_SIZE;
+	}
+}
+//#endregion
+//#region src/backup/tar.ts
+/**
+* 宫殿备份与恢复：把当前 user/project 两库的 .db + 元信息打包成单一 .tar.gz 文件；
+* 恢复时校验 tar 内的 _meta.json schema 版本并覆盖原库（恢复前自动备份现状为 .before-restore-<ts>）。
+* 设计原则：
+* 1. tar 内文件路径用相对形式 `palace.db` / `palace-<scope>.db` / `_meta.json`，避免暴露绝对路径。
+* 2. 元信息必须含 schema_version（与插件同构），恢复时若不匹配返回明确的兼容错误而不是默默覆盖。
+* 3. 整个过程失败原子：恢复前若任何前置校验失败，原库不动。
+* @module @kenz1117/dsh-engram/backup/tar
+*/
+const gunzipAsync = promisify(gunzip);
+/**
+* 创建备份：把 dbDir 下所有 *.db 与 `_meta.json` 一起打包成 .tar.gz。
+* @param dbDir - 插件数据目录（含 user.db / project-*.db）。
+* @param pluginVersion - 写进 _meta.json 的插件版本（与 package.json 同步）。
+*/
+async function createBackup(dbDir, pluginVersion) {
+	await mkdir(dbDir, {
+		recursive: true,
+		mode: 448
+	});
+	const files = (await readdir(dbDir)).filter((name) => name.endsWith(".db"));
+	const scopes = [];
+	const entries = [];
+	for (const name of files) {
+		const path = join(dbDir, name);
+		if (!(await stat(path)).isFile()) continue;
+		entries.push({
+			name,
+			data: await readFileBuffer(path)
+		});
+		scopes.push({
+			scope: name === "user.db" ? "user" : "project",
+			recordCount: 0,
+			edgeCount: 0
+		});
+	}
+	const meta = {
+		schemaVersion: 1,
+		pluginVersion,
+		exportedAt: Date.now(),
+		scopes
+	};
+	entries.push({
+		name: "_meta.json",
+		data: Buffer.from(JSON.stringify(meta, null, 2), "utf8")
+	});
+	const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-").slice(0, 19);
+	const archivePath = join(dbDir, `palace-backup-${stamp}.tar.gz`);
+	await writeTarGz(archivePath, entries);
+	return {
+		archivePath,
+		meta,
+		bytes: (await stat(archivePath)).size
+	};
+}
+/** 异步读文件为 Buffer（小文件路径，备份场景可接受）。 */
+async function readFileBuffer(path) {
+	const { readFile } = await import("node:fs/promises");
+	return readFile(path);
+}
+/**
+* 把 entries 写入 .tar.gz。tar 头由本模块自带实现（避免引入 tar 依赖），gzip 用 zlib.createGzip。
+*/
+async function writeTarGz(outPath, entries) {
+	await new Promise((resolve, reject) => {
+		const sink = createWriteStream(outPath, { mode: 384 });
+		sink.on("error", reject);
+		sink.on("finish", () => resolve());
+		const gz = createGzip();
+		gz.on("error", reject);
+		gz.pipe(sink);
+		for (const entry of entries) createTarPack(gz, entry.name, entry.data);
+		endTarPack(gz);
+		gz.end();
+	});
+}
+/**
+* 从 .tar.gz 恢复：解包到临时目录 → 校验 _meta.json → 把 .db 文件原子搬到 dbDir。
+* 任何前置校验失败抛错，原 dbDir 不变。
+*/
+async function restoreBackup(archivePath, dbDir, options = {}) {
+	const tempDir = join(dbDir, `.restore-tmp-${Date.now()}`);
+	await mkdir(tempDir, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		await untarGz(archivePath, tempDir);
+		const metaRaw = await readFileBuffer(join(tempDir, "_meta.json")).then((buf) => buf.toString("utf8"));
+		const meta = JSON.parse(metaRaw);
+		if (meta.schemaVersion !== 1) throw new Error(`备份 schema 版本 ${meta.schemaVersion} 与当前 1 不兼容（请升级插件或使用旧版恢复）`);
+		if (typeof meta.pluginVersion !== "string" || meta.pluginVersion === "") throw new Error("备份 _meta.json 缺少 pluginVersion 字段，可能已损坏");
+		const restored = [];
+		if (options.keepCurrent !== false) {
+			const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-").slice(0, 19);
+			for (const name of (await readdir(dbDir)).filter((n) => n.endsWith(".db"))) {
+				const path = join(dbDir, name);
+				await rename(path, `${path}.before-restore-${stamp}`);
+			}
+		}
+		for (const name of (await readdir(tempDir)).filter((n) => n.endsWith(".db"))) {
+			const target = join(dbDir, name);
+			await rename(join(tempDir, name), target);
+			restored.push(target);
+		}
+		return {
+			restored,
+			archiveMeta: meta
+		};
+	} finally {
+		await rm(tempDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** 解 .tar.gz 到目标目录：先解压到 buffer，再 inline 解 tar。 */
+async function untarGz(archivePath, destDir) {
+	const compressed = await readFileBuffer(archivePath);
+	await extractTar(await gunzipAsync(compressed), destDir);
+}
+//#endregion
+//#region src/telemetry/aggregate.ts
+/** 聚合窗口（默认 7 天，可由路由 query 覆盖）。 */
+const DEFAULT_WINDOW_DAYS = 7;
+/** 从单库 op_log 统计各 op 的计数（窗口内）。 */
+async function countByOp(store, sinceMs) {
+	const ops = await store.recentOps(1e5);
+	const counts = {};
+	for (const op of ops) {
+		if (op.at < sinceMs) continue;
+		counts[op.op] = (counts[op.op] ?? 0) + 1;
+	}
+	return counts;
+}
+/** 聚合两库的指标 + 各 scope 状态。
+* @param scopeFilter - 限定只聚合指定 scope；undefined = 三库全聚合（向后兼容）。 */
+async function aggregateTelemetry(openStore, windowDays = DEFAULT_WINDOW_DAYS, scopeFilter) {
+	const untilMs = Date.now();
+	const sinceMs = untilMs - windowDays * 864e5;
+	const scopes = scopeFilter !== void 0 ? [scopeFilter] : [
+		"user",
+		"project",
+		"shared"
+	];
+	const countsAgg = {
+		ingestRequests: 0,
+		ingestDones: 0,
+		searches: 0,
+		writes: 0,
+		updates: 0,
+		forgets: 0,
+		restores: 0,
+		distillRequests: 0,
+		compressRequests: 0,
+		searchRewrites: 0,
+		consumptions: 0,
+		consolidations: 0
+	};
+	const scopeViews = [];
+	for (const scope of scopes) try {
+		const store = await openStore(scope);
+		const [counts, stats] = await Promise.all([countByOp(store, sinceMs), store.stats()]);
+		countsAgg.ingestRequests += counts["ingest-request"] ?? 0;
+		countsAgg.ingestDones += counts["ingest-done"] ?? 0;
+		countsAgg.searches += counts["search-rewrite-request"] ?? 0;
+		countsAgg.writes += counts["write"] ?? 0;
+		countsAgg.updates += counts["update"] ?? 0;
+		countsAgg.forgets += counts["forget"] ?? 0;
+		countsAgg.restores += counts["restore"] ?? 0;
+		countsAgg.distillRequests += counts["distill-request"] ?? 0;
+		countsAgg.compressRequests += counts["compress-request"] ?? 0;
+		countsAgg.searchRewrites += counts["search-rewrite-request"] ?? 0;
+		countsAgg.consumptions += counts["outcome-report"] ?? 0;
+		countsAgg.consolidations += counts["consolidation"] ?? 0;
+		scopeViews.push({
+			scope,
+			active: stats.active,
+			total: stats.total,
+			signalRatio: stats.signalRatio
+		});
+	} catch {}
+	return {
+		windowDays,
+		sinceMs,
+		untilMs,
+		counts: countsAgg,
+		scopes: scopeViews
+	};
+}
+//#endregion
+//#region src/tour-proposal.ts
+/**
+* 构造入殿建议。
+* @param scope - 作用域（user/project；shared 单独处理）
+* @param records - 当前 scope 的 active 条目（已按 importance × confidence 倒序）
+* @param focusKind - 本轮 user 输入的主题（可选；存在时优先选同 kind）
+*/
+function buildTourProposal(scope, records, focusKind) {
+	const active = records.filter((r) => r.status === "active");
+	const empty = active.length === 0;
+	const limit = Math.min(5, Math.max(1, active.length));
+	const scored = [...active].sort((a, b) => {
+		const focusBoost = (record) => focusKind !== void 0 && record.kind === focusKind ? 1 : 0;
+		const scoreA = focusBoost(a) * 1e3 + a.importance * a.confidence * 100;
+		return focusBoost(b) * 1e3 + b.importance * b.confidence * 100 - scoreA;
+	}).slice(0, limit);
+	return {
+		greeting: empty ? `[${scope}] 宫殿尚空。建议：先放第一段记忆（例如一条 fact 或 preference），让后续会话有锚点可循。` : `[${scope}] 宫殿现存 ${active.length} 间 active 房间。建议开场巡游：${scored.map((r, i) => `第 ${i + 1} 站「${r.content.slice(0, 24)}${r.content.length > 24 ? "…" : ""}」`).join("；")}。`,
+		suggestedStops: scored,
+		activeCount: active.length,
+		empty
+	};
+}
+//#endregion
+//#region src/refurb.ts
+/** 缺省参数。 */
+const DEFAULT_REFURB_OPTIONS = {
+	demoteBelow: .2,
+	staleDays: 60,
+	duplicateTitleWindow: 0
+};
+/**
+* 扫描一组 active 条目，按规则生成翻新建议。
+* 仅扫描同 scope 内的内容；跨 scope 的相似合并留给上层判定。
+*/
+function gatherRefurbSuggestions(records, options = DEFAULT_REFURB_OPTIONS) {
+	const suggestions = [];
+	const now = Date.now();
+	const active = records.filter((r) => r.status === "active");
+	const byScope = /* @__PURE__ */ new Map();
+	for (const record of active) {
+		const list = byScope.get(record.scope) ?? [];
+		list.push(record);
+		byScope.set(record.scope, list);
+	}
+	for (const record of active) {
+		const daysSinceAccess = (now - record.lastAccessedAt) / 864e5;
+		if (record.importance < options.demoteBelow && daysSinceAccess > options.staleDays) suggestions.push({
+			action: "demote",
+			primaryId: record.id,
+			candidates: [],
+			scope: record.scope,
+			reason: `重要性 ${record.importance.toFixed(2)} < ${options.demoteBelow} 且 ${Math.floor(daysSinceAccess)} 天未访问，建议降级为 archived。`,
+			confidence: .7
+		});
+	}
+	for (const [scope, list] of byScope) {
+		const byKind = /* @__PURE__ */ new Map();
+		for (const record of list) {
+			const bucket = byKind.get(record.kind) ?? [];
+			bucket.push(record);
+			byKind.set(record.kind, bucket);
+		}
+		for (const [, items] of byKind) {
+			if (items.length < 2) continue;
+			const seen = /* @__PURE__ */ new Set();
+			for (const record of items) {
+				const key = record.content.slice(0, 20);
+				if (seen.has(key)) continue;
+				seen.add(key);
+				const dupes = items.filter((other) => other.id !== record.id && other.content.startsWith(key));
+				if (dupes.length > 0) suggestions.push({
+					action: "merge",
+					primaryId: record.id,
+					candidates: dupes.map((d) => d.id),
+					scope,
+					reason: `与 ${dupes.length} 间房间内容前 20 字重复，建议蒸馏合并。`,
+					confidence: .6
+				});
+			}
+		}
+	}
+	for (const record of active) if (record.accessCount === 0 && record.importance >= .7) suggestions.push({
+		action: "review",
+		primaryId: record.id,
+		candidates: [],
+		scope: record.scope,
+		reason: `重要性 ${record.importance.toFixed(2)} 但从未被参观，可能埋没在走廊，建议复习。`,
+		confidence: .5
+	});
+	for (const record of active) if (record.content.length > 400) suggestions.push({
+		action: "split",
+		primaryId: record.id,
+		candidates: [],
+		scope: record.scope,
+		reason: `内容长度 ${record.content.length} > 400，建议拆为多条独立房间。`,
+		confidence: .6
+	});
+	return suggestions;
+}
+//#endregion
 //#region src/routes.ts
 /** 回环 peer：IPv4 127/8、IPv6 ::1、IPv4-mapped IPv6。 */
 function isLoopbackPeer(req) {
@@ -804,7 +1588,8 @@ function json(res, status, body) {
 }
 /** 从 URL searchParams 收敛 scope（缺省 user）。 */
 function scopeOf$1(raw, fallback) {
-	return raw === "user" || raw === "project" ? raw : fallback;
+	if (raw === "user" || raw === "project" || raw === "shared") return raw;
+	return fallback;
 }
 /**
 * 注册 /engram 页面与 /api/engram/* 接口（effect 由调用方持有，disposer 可逆）。
@@ -846,6 +1631,54 @@ function registerEngramRoutes(ctx, deps) {
 					json(res, 200, await (await deps.openStore(scope)).list(filter));
 					return;
 				}
+				if (req.method === "GET" && route === "search-test") {
+					const q = url.searchParams.get("q");
+					if (q === null || q.trim() === "") {
+						json(res, 400, { error: "q required" });
+						return;
+					}
+					const scopeParam = url.searchParams.get("scope");
+					const scopes = scopeParam === "all" || scopeParam === null || scopeParam === "" ? ["user", "project"] : [scopeOf$1(scopeParam, "user")];
+					const kind = url.searchParams.get("kind");
+					const limit = Math.min(20, Math.max(1, Number(url.searchParams.get("limit") ?? 10) || 10));
+					const embedder = deps.embedder === void 0 ? void 0 : await deps.embedder;
+					const vector = embedder === void 0 ? void 0 : (await embedder.embed([q.trim()]))[0];
+					const results = await Promise.all(scopes.map(async (scope) => {
+						return (await deps.openStore(scope)).search({
+							text: q,
+							scopes: [scope],
+							limit
+						}, vector);
+					}));
+					const degraded = results.some((result) => result.degraded);
+					let hits = results.flatMap((result) => result.hits);
+					if (kind !== null && kind !== "" && kind !== "all") hits = hits.filter((hit) => hit.record.kind === kind);
+					json(res, 200, {
+						degraded,
+						hits: hits.map((hit) => ({
+							id: hit.record.id,
+							score: hit.score,
+							via: hit.via,
+							...hit.viaEdge === void 0 ? {} : { viaEdge: hit.viaEdge },
+							scope: hit.record.scope,
+							kind: hit.record.kind,
+							status: hit.record.status,
+							content: hit.record.content,
+							createdAt: hit.record.createdAt
+						}))
+					});
+					return;
+				}
+				if (req.method === "GET" && route === "activity") {
+					const limit = Math.min(50, Math.max(1, Number(url.searchParams.get("limit") ?? 20) || 20));
+					json(res, 200, { operations: (await Promise.all(["user", "project"].map(async (scope) => {
+						return (await (await deps.openStore(scope)).recentOps(limit)).map((op) => ({
+							...op,
+							scope
+						}));
+					}))).flat().sort((a, b) => b.at - a.at).slice(0, limit) });
+					return;
+				}
 				if (req.method === "GET" && route === "review") {
 					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
 					const id = url.searchParams.get("id");
@@ -854,7 +1687,6 @@ function registerEngramRoutes(ctx, deps) {
 						return;
 					}
 					const view = await (await deps.openStore(scope)).review(id);
-					view === void 0 || view.operations;
 					if (view === void 0) {
 						json(res, 404, { error: `未找到条目 ${id}` });
 						return;
@@ -883,45 +1715,227 @@ function registerEngramRoutes(ctx, deps) {
 					res.end(body);
 					return;
 				}
-				if (req.method === "POST" && (route === "update" || route === "forget" || route === "restore")) {
-					if (!guardWrite(req, res)) return;
-					const body = await readJsonBody(req);
-					if (body === null || typeof body.id !== "string" || body.id === "") {
-						json(res, 400, { error: "id required" });
-						return;
-					}
-					const scope = scopeOf$1(typeof body.scope === "string" ? body.scope : null, "user");
-					const store = await deps.openStore(scope);
-					if (route === "update") {
-						if (typeof body.content !== "string" || body.content.trim() === "") {
-							json(res, 400, { error: "content required" });
-							return;
-						}
-						const old = await store.get(body.id);
-						if (old === void 0) {
-							json(res, 404, { error: `未找到条目 ${body.id}` });
-							return;
-						}
-						json(res, 200, { record: await store.update({
-							id: body.id,
+				if (req.method === "GET" && route === "mirror") {
+					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
+					const data = await (await deps.openStore(scope)).exportAll();
+					const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-").slice(0, 19);
+					json(res, 200, {
+						...await writeMirror(join(deps.mirrorDir, scope, stamp), data),
+						scope,
+						roomCount: data.records.length,
+						edgeCount: data.edges.length
+					});
+					return;
+				}
+				if (req.method === "GET" && route === "health") {
+					const rawScope = url.searchParams.get("scope");
+					const scopes = rawScope === "user" || rawScope === "project" || rawScope === "shared" ? [rawScope] : ["user", "project"];
+					const parts = await Promise.all(scopes.map(async (scope) => {
+						const store = await deps.openStore(scope);
+						const s = await store.stats();
+						const edgeCount = (await store.exportAll()).edges.length;
+						const total = Math.max(s.total, 1);
+						const signal = s.signalRatio;
+						const activeRatio = s.active / total;
+						const corridorRatio = Math.min(.5, edgeCount / Math.max(s.active, 1)) / .5;
+						const redactedPenalty = Math.max(0, 1 - s.redacted / total);
+						const archivedRatio = s.archived / total;
+						const isShared = scope === "shared";
+						const targetActive = isShared ? .7 : .85;
+						const decayLow = isShared ? .25 : .15;
+						const decayHigh = isShared ? .5 : .45;
+						const decayWindow = isShared ? .25 : .3;
+						const decayCoverage = archivedRatio >= decayLow && archivedRatio <= decayHigh ? 1 : Math.max(0, 1 - Math.min(Math.abs(archivedRatio - decayLow), Math.abs(archivedRatio - decayHigh)) / decayWindow);
+						const score = Math.round(signal * 40 + (1 - Math.abs(activeRatio - targetActive) / targetActive) * 25 + corridorRatio * 15 + redactedPenalty * 10 + decayCoverage * 10);
+						return {
 							scope,
-							kind: typeof body.kind === "string" && [
-								"fact",
-								"preference",
-								"decision",
-								"episode",
-								"skill"
-							].includes(body.kind) ? body.kind : old.kind,
-							content: body.content,
-							...typeof body.importance === "number" && Number.isFinite(body.importance) ? { importance: Math.min(1, Math.max(0, body.importance)) } : {}
-						}) });
-						return;
+							score: Math.min(100, Math.max(0, score)),
+							signal,
+							activeRatio,
+							edgeCount,
+							redacted: s.redacted,
+							archivedRatio
+						};
+					}));
+					json(res, 200, {
+						overall: Math.round(parts.reduce((sum, part) => sum + part.score, 0) / parts.length),
+						parts,
+						evaluatedAt: Date.now()
+					});
+					return;
+				}
+				if (req.method === "GET" && route === "corridor") {
+					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
+					const includeStatuses = /* @__PURE__ */ new Set(["active"]);
+					const rawStatus = url.searchParams.get("status");
+					if (rawStatus !== null && rawStatus !== "" && rawStatus !== "all") {
+						for (const s of rawStatus.split(",")) if (s === "active" || s === "archived" || s === "forgotten") includeStatuses.add(s);
 					}
-					json(res, 200, { record: route === "forget" ? await store.forget(body.id) : await store.restore(body.id) });
+					const data = await (await deps.openStore(scope)).exportAll();
+					const nodes = data.records.filter((r) => includeStatuses.has(r.status)).map((r) => ({
+						id: r.id,
+						scope: r.scope,
+						kind: r.kind,
+						status: r.status,
+						importance: r.importance,
+						confidence: r.confidence,
+						title: r.content.length > 40 ? `${r.content.slice(0, 40)}…` : r.content,
+						content: r.content
+					}));
+					const allowedIds = new Set(nodes.map((n) => n.id));
+					json(res, 200, {
+						scope,
+						nodes,
+						edges: data.edges.filter((e) => allowedIds.has(e.from) && allowedIds.has(e.to)).map((e) => ({
+							id: `${e.from}-${e.to}-${e.type}`,
+							from: e.from,
+							to: e.to,
+							type: e.type
+						}))
+					});
 					return;
 				}
-				json(res, 404, { error: "unknown route" });
-			} catch (error) {
+				if (req.method === "GET" && route === "telemetry") {
+					const windowDays = Math.min(90, Math.max(1, Number(url.searchParams.get("days") ?? 7) || 7));
+					const rawScope = url.searchParams.get("scope");
+					const scopeFilter = rawScope === "user" ? "user" : rawScope === "project" ? "project" : rawScope === "shared" ? "shared" : void 0;
+					json(res, 200, await aggregateTelemetry(deps.openStore, windowDays, scopeFilter));
+					return;
+				}
+				if (req.method === "GET" && route === "tour-proposal") {
+					const rawScope = url.searchParams.get("scope");
+					const scope = rawScope === "project" ? "project" : rawScope === "shared" ? "shared" : "user";
+					const filter = await (await deps.openStore(scope)).list({
+						scope,
+						status: "active",
+						limit: 200,
+						offset: 0
+					});
+					const focusKind = url.searchParams.get("focusKind");
+					const proposal = buildTourProposal(scope, filter.records, focusKind ?? void 0);
+					json(res, 200, {
+						scope: proposal.empty ? "empty" : scope,
+						greeting: proposal.greeting,
+						activeCount: proposal.activeCount,
+						empty: proposal.empty,
+						suggestedStops: proposal.suggestedStops.map((record) => ({
+							id: record.id,
+							kind: record.kind,
+							content: record.content,
+							importance: record.importance,
+							confidence: record.confidence
+						}))
+					});
+					return;
+				}
+				if (req.method === "GET" && route === "refurb") {
+					const rawScope = url.searchParams.get("scope");
+					const scope = rawScope === "project" ? "project" : rawScope === "shared" ? "shared" : "user";
+					const suggestions = gatherRefurbSuggestions((await (await deps.openStore(scope)).list({
+						scope,
+						status: "active",
+						limit: 500,
+						offset: 0
+					})).records, DEFAULT_REFURB_OPTIONS);
+					json(res, 200, {
+						scope,
+						count: suggestions.length,
+						suggestions: suggestions.map((suggestion) => ({
+							action: suggestion.action,
+							primaryId: suggestion.primaryId,
+							candidates: [...suggestion.candidates],
+							scope: suggestion.scope,
+							reason: suggestion.reason,
+							confidence: suggestion.confidence
+						}))
+					});
+					return;
+				}
+				if (req.method === "POST" && route === "consolidate") {
+					if (!guardWrite(req, res)) return;
+					const body = await readJsonBody(req);
+					const rawScope = typeof body?.scope === "string" ? body.scope : "user";
+					const scope = rawScope === "project" ? "project" : rawScope === "shared" ? "shared" : "user";
+					const candidates = Array.isArray(body?.candidates) ? body.candidates.filter((value) => typeof value === "string") : void 0;
+					json(res, 200, await runConsolidation(await deps.openStore(scope), deps.embedder, candidates === void 0 ? { scope } : {
+						scope,
+						mergeCandidateIds: candidates
+					}));
+					return;
+				}
+				if (req.method === "POST" && route === "backup") {
+					if (!guardWrite(req, res)) return;
+					const result = await createBackup(deps.dbDir, deps.pluginVersion);
+					json(res, 200, {
+						archivePath: result.archivePath,
+						bytes: result.bytes,
+						meta: result.meta,
+						schemaVersion: 1
+					});
+					return;
+				}
+				if (req.method === "POST" && route === "restore-backup") {
+					if (!guardWrite(req, res)) return;
+					const body = await readJsonBody(req);
+					if (body === null || typeof body.archivePath !== "string" || body.archivePath === "") {
+						json(res, 400, { error: "archivePath required" });
+						return;
+					}
+					const normalized = join(deps.dbDir, body.archivePath.replace(/^\/+/, ""));
+					if (!normalized.startsWith(deps.dbDir + "/") && normalized !== deps.dbDir) {
+						json(res, 400, { error: "archivePath 必须在 dbDir 内" });
+						return;
+					}
+					try {
+						const result = await restoreBackup(normalized, deps.dbDir);
+						json(res, 200, {
+							restored: result.restored,
+							meta: result.archiveMeta
+						});
+					} catch (restoreError) {
+						json(res, 400, { error: `恢复失败：${restoreError instanceof Error ? restoreError.message : String(restoreError)}` });
+					}
+					return;
+				}
+				if (req.method === "POST" && (route === "update" || route === "forget" || route === "restore")) {
+					if (!guardWrite(req, res)) return;
+					const body = await readJsonBody(req);
+					if (body === null || typeof body.id !== "string" || body.id === "") {
+						json(res, 400, { error: "id required" });
+						return;
+					}
+					const scope = scopeOf$1(typeof body.scope === "string" ? body.scope : null, "user");
+					const store = await deps.openStore(scope);
+					if (route === "update") {
+						if (typeof body.content !== "string" || body.content.trim() === "") {
+							json(res, 400, { error: "content required" });
+							return;
+						}
+						const old = await store.get(body.id);
+						if (old === void 0) {
+							json(res, 404, { error: `未找到条目 ${body.id}` });
+							return;
+						}
+						json(res, 200, { record: await store.update({
+							id: body.id,
+							scope,
+							kind: typeof body.kind === "string" && [
+								"fact",
+								"preference",
+								"decision",
+								"episode",
+								"skill"
+							].includes(body.kind) ? body.kind : old.kind,
+							content: body.content,
+							...typeof body.importance === "number" && Number.isFinite(body.importance) ? { importance: Math.min(1, Math.max(0, body.importance)) } : {}
+						}) });
+						return;
+					}
+					json(res, 200, { record: route === "forget" ? await store.forget(body.id) : await store.restore(body.id) });
+					return;
+				}
+				json(res, 404, { error: "unknown route" });
+			} catch (error) {
 				json(res, 500, { error: error instanceof Error ? error.message : String(error) });
 			}
 		}
@@ -1059,8 +2073,20 @@ function migrateProjectDb(dbDir, identity) {
 * 本包声明兼容 node ^22.19。
 * @module @kenz1117/dsh-engram/store/sqlite
 */
-/** 当前 schema 版本；结构性变更必须 +1 并拒绝旧库（pre-release 无兼容承诺）。 */
-const SCHEMA_VERSION = 2;
+/** 当前 schema 版本；结构性变更必须 +1。可空列与伴随表走增量迁移（见 openEngramStore 的迁移段）。 */
+const SCHEMA_VERSION = 5;
+/** 增量迁移表：key 为起始版本，value 为升到下一版本的 SQL（可多语句）。
+*  v2 → v3：nodes 补可空列 outcome（使用效果回报）。
+*  v3 → v4：新增 nodes_revisions 修订表（update 归档旧条目时的内容快照）。
+*  v4 → v5：nodes 补 imagery_json 列（意象铭牌：caption + sensoryTags + emotionalValence + provisional）。
+*  v5 不再升版：闭馆三问用 op_log JSON 详情承载（已有 audit 接口），不改表结构。 */
+const MIGRATIONS = {
+	"2": "ALTER TABLE nodes ADD COLUMN outcome TEXT",
+	"3": `CREATE TABLE IF NOT EXISTS nodes_revisions (
+    node_id TEXT NOT NULL, content TEXT NOT NULL, kind TEXT NOT NULL,
+    importance REAL NOT NULL, superseded_at INTEGER NOT NULL);`,
+	"4": "ALTER TABLE nodes ADD COLUMN imagery_json TEXT"
+};
 /** RRF 融合常数：score = Σ 1/(K + rank)。 */
 const RRF_K = 60;
 /** 向量道的语义门槛：低于该余弦的条目不参与排序。 */
@@ -1073,9 +2099,37 @@ const RANK_POOL = 64;
 const EXPANSION_LIMIT = 32;
 /** 命中强化：每次检索命中的置信度增量。 */
 const CONFIDENCE_BUMP = .05;
+/** 效果回报降权：failure 回报的置信度扣减（success 复用 CONFIDENCE_BUMP）。 */
+const OUTCOME_PENALTY = .1;
 /** 审计视图返回的操作日志条数上限。 */
 const REVIEW_LOG_LIMIT = 20;
+/** 把意象铭牌序列化为 JSON（缺省序列化为 null，落库）。 */
+function imageryToJson(imagery) {
+	if (imagery === void 0) return null;
+	return JSON.stringify({
+		caption: imagery.caption,
+		sensoryTags: [...imagery.sensoryTags],
+		emotionalValence: imagery.emotionalValence,
+		provisional: imagery.provisional
+	});
+}
+/** 从 JSON 反序列化意象铭牌；空串或解析失败返回 undefined（视作未铭刻）。 */
+function jsonToImagery(raw) {
+	if (raw === null || raw === "") return void 0;
+	try {
+		const parsed = JSON.parse(raw);
+		return {
+			caption: typeof parsed.caption === "string" ? parsed.caption : null,
+			sensoryTags: Array.isArray(parsed.sensoryTags) ? parsed.sensoryTags.filter((s) => typeof s === "string") : [],
+			emotionalValence: typeof parsed.emotionalValence === "number" && Number.isFinite(parsed.emotionalValence) ? Math.min(1, Math.max(0, parsed.emotionalValence)) : 0,
+			provisional: parsed.provisional === true
+		};
+	} catch {
+		return;
+	}
+}
 function rowToRecord(row) {
+	const imagery = jsonToImagery(row.imagery_json);
 	return {
 		id: asMemoryId(row.id),
 		scope: row.scope,
@@ -1084,12 +2138,14 @@ function rowToRecord(row) {
 		importance: row.importance,
 		confidence: row.confidence,
 		status: row.status,
+		...row.outcome === "success" || row.outcome === "failure" ? { outcome: row.outcome } : {},
 		createdAt: row.created_at,
 		lastAccessedAt: row.last_accessed_at,
 		accessCount: row.access_count,
 		sourceSessionId: row.source_session_id,
 		sourceRound: row.source_round,
-		sourceSeq: row.source_seq
+		sourceSeq: row.source_seq,
+		...imagery === void 0 ? {} : { imagery }
 	};
 }
 function blobToVec(blob) {
@@ -1173,36 +2229,80 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
       id TEXT PRIMARY KEY, scope TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL,
       importance REAL NOT NULL, confidence REAL NOT NULL, status TEXT NOT NULL,
       created_at INTEGER NOT NULL, last_accessed_at INTEGER NOT NULL, access_count INTEGER NOT NULL,
-      source_session_id TEXT, source_round INTEGER, source_seq INTEGER, embedding BLOB);
+      source_session_id TEXT, source_round INTEGER, source_seq INTEGER, embedding BLOB, outcome TEXT,
+      imagery_json TEXT);
     CREATE TABLE IF NOT EXISTS edges (
       from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL, created_at INTEGER NOT NULL,
       PRIMARY KEY (from_id, to_id, type));
     CREATE TABLE IF NOT EXISTS op_log (
       seq INTEGER PRIMARY KEY AUTOINCREMENT, at INTEGER NOT NULL, op TEXT NOT NULL,
       target_id TEXT NOT NULL, detail TEXT);
+    CREATE TABLE IF NOT EXISTS nodes_revisions (
+      node_id TEXT NOT NULL, content TEXT NOT NULL, kind TEXT NOT NULL,
+      importance REAL NOT NULL, superseded_at INTEGER NOT NULL);
     CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(node_id UNINDEXED, content, tokenize='unicode61');
     CREATE INDEX IF NOT EXISTS nodes_scope_status ON nodes (scope, status);
   `);
 	const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
 	if (versionRow === void 0) db.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
-	else if (Number(versionRow.value) !== SCHEMA_VERSION) {
-		db.close();
-		throw new EngramError("SCHEMA_INCOMPATIBLE", `engram 数据库 schema 版本 ${versionRow.value} 与插件支持的 ${SCHEMA_VERSION} 不一致：请备份并删除旧库文件（${path}）后重试`);
+	else {
+		let version = Number(versionRow.value);
+		if (!Number.isInteger(version) || version > SCHEMA_VERSION) {
+			db.close();
+			throw new EngramError("SCHEMA_INCOMPATIBLE", `engram 数据库 schema 版本 ${versionRow.value} 高于插件支持的 ${SCHEMA_VERSION}：请升级插件或备份后删除旧库文件（${path}）`);
+		}
+		while (version < SCHEMA_VERSION) {
+			const migration = MIGRATIONS[String(version)];
+			if (migration === void 0) {
+				db.close();
+				throw new EngramError("SCHEMA_INCOMPATIBLE", `engram 数据库 schema 版本 ${version} 无法升到 ${SCHEMA_VERSION}（缺迁移步骤）：请备份并删除旧库文件（${path}）后重试`);
+			}
+			withTransaction(() => {
+				const safe = migration.split(";").map((stmt) => stmt.trim()).filter((stmt) => stmt !== "").filter((stmt) => {
+					const match = /^ALTER\s+TABLE\s+(\w+)\s+ADD\s+COLUMN\s+(\w+)/i.exec(stmt);
+					if (match === null) return true;
+					const table = match[1];
+					const column = match[2];
+					return !db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column);
+				});
+				for (const stmt of safe) db.exec(stmt);
+				version += 1;
+				db.prepare("UPDATE meta SET value = ? WHERE key = 'schema_version'").run(String(version));
+			});
+		}
 	}
 	const sqlGet = db.prepare("SELECT * FROM nodes WHERE id = ?");
 	const sqlInsert = db.prepare(`INSERT INTO nodes
     (id, scope, kind, content, importance, confidence, status, created_at, last_accessed_at, access_count,
-     source_session_id, source_round, source_seq, embedding)
-    VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, 0, ?, ?, ?, ?)`);
+     source_session_id, source_round, source_seq, embedding, imagery_json)
+    VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, 0, ?, ?, ?, ?, ?)`);
 	const sqlFtsInsert = db.prepare("INSERT INTO nodes_fts (node_id, content) VALUES (?, ?)");
 	const sqlSetStatus = db.prepare("UPDATE nodes SET status = ?, last_accessed_at = ? WHERE id = ?");
+	const sqlSetOutcome = db.prepare(`UPDATE nodes
+    SET outcome = ?,
+        confidence = CASE WHEN ? = 'success' THEN min(1.0, confidence + ${CONFIDENCE_BUMP}) ELSE max(0.0, confidence - ${OUTCOME_PENALTY}) END
+    WHERE id = ?`);
 	const sqlTouch = db.prepare(`UPDATE nodes SET access_count = access_count + 1, last_accessed_at = ?,
     confidence = MIN(1, confidence + ${CONFIDENCE_BUMP}) WHERE id = ?`);
 	const sqlLog = db.prepare("INSERT INTO op_log (at, op, target_id, detail) VALUES (?, ?, ?, ?)");
 	const sqlHasAudit = db.prepare("SELECT 1 AS x FROM op_log WHERE op = ? AND detail = ? LIMIT 1");
 	const sqlListAudit = db.prepare("SELECT detail FROM op_log WHERE op = ? AND detail IS NOT NULL ORDER BY seq");
 	const sqlClearAudit = db.prepare("DELETE FROM op_log WHERE op = ? AND detail = ?");
-	const sqlOpLogById = db.prepare("SELECT at, op, detail FROM op_log WHERE target_id = ? ORDER BY seq DESC LIMIT ?");
+	const sqlOpLogById = db.prepare("SELECT at, op, target_id, detail FROM op_log WHERE target_id = ? ORDER BY seq DESC LIMIT ?");
+	const sqlGetManyByIds = db.prepare("SELECT * FROM nodes WHERE id IN (SELECT value FROM json_each(?))");
+	const sqlNeighborsBounded = db.prepare(`SELECT * FROM nodes WHERE id IN (
+    WITH RECURSIVE walk(id, depth) AS (
+      SELECT ?, 0
+      UNION
+      SELECT CASE WHEN e.from_id = walk.id THEN e.to_id ELSE e.from_id END, walk.depth + 1
+      FROM edges e JOIN walk ON (e.from_id = walk.id OR e.to_id = walk.id)
+      WHERE walk.depth < ? AND e.type IN ('supports','refines','related','supersedes','contradicts')
+    )
+    SELECT id FROM walk WHERE depth > 0
+  )`);
+	const sqlRecentOps = db.prepare("SELECT at, op, target_id, detail FROM op_log ORDER BY seq DESC LIMIT ?");
+	const sqlRevisionInsert = db.prepare("INSERT INTO nodes_revisions (node_id, content, kind, importance, superseded_at) VALUES (?, ?, ?, ?, ?)");
+	const sqlRevisionsById = db.prepare("SELECT content, kind, importance, superseded_at FROM nodes_revisions WHERE node_id = ? ORDER BY superseded_at DESC");
 	const sqlTopActive = db.prepare("SELECT * FROM nodes WHERE scope = ? AND status = 'active' ORDER BY importance DESC, confidence DESC LIMIT ?");
 	const sqlEdgeUpsert = db.prepare("INSERT OR IGNORE INTO edges (from_id, to_id, type, created_at) VALUES (?, ?, ?, ?)");
 	const sqlNeighbors = db.prepare(`SELECT * FROM edges WHERE from_id IN (SELECT value FROM json_each(?))
@@ -1238,9 +2338,9 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 	* 写入公共体：插入节点 + FTS + 操作日志（不建边、不开事务）。
 	* 事务由调用方持有（withTransaction）。
 	*/
-	const insertRecord = (id, input, content, importance, confidence, at, sourceSessionId, embedding, op) => {
+	const insertRecord = (id, input, content, importance, confidence, at, sourceSessionId, embedding, imagery, op) => {
 		const stored = embedding === null ? null : embedding instanceof Float32Array ? vecToBlob(embedding) : embedding;
-		sqlInsert.run(id, input.scope, input.kind, content, importance, confidence, at, at, sourceSessionId, input.sourceRound ?? null, input.sourceSeq ?? null, stored);
+		sqlInsert.run(id, input.scope, input.kind, content, importance, confidence, at, at, sourceSessionId, input.sourceRound ?? null, input.sourceSeq ?? null, stored, imageryToJson(imagery));
 		sqlFtsInsert.run(id, tokenizeForFts(content));
 		sqlLog.run(at, op, id, JSON.stringify({
 			kind: input.kind,
@@ -1273,7 +2373,7 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 			const id = asMemoryId(randomUUID());
 			const at = Date.now();
 			withTransaction(() => {
-				insertRecord(id, input, content, input.importance ?? .5, input.confidence ?? .5, at, input.sourceSessionId ?? null, input.embedding ?? null, "write");
+				insertRecord(id, input, content, input.importance ?? .5, input.confidence ?? .5, at, input.sourceSessionId ?? null, input.embedding ?? null, input.imagery, "write");
 			});
 			return rowToRecord(sqlGet.get(id));
 		},
@@ -1281,6 +2381,31 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 			const row = getRow(id);
 			return row === void 0 ? void 0 : rowToRecord(row);
 		},
+		async getMany(ids) {
+			if (ids.length === 0) return [];
+			const seen = /* @__PURE__ */ new Set();
+			const unique = [];
+			for (const id of ids) if (!seen.has(id)) {
+				seen.add(id);
+				unique.push(id);
+			}
+			const rows = sqlGetManyByIds.all(JSON.stringify(unique.map((id) => String(id))));
+			const map = /* @__PURE__ */ new Map();
+			for (const row of rows) map.set(row.id, rowToRecord(row));
+			return unique.map((id) => map.get(id)).filter((r) => r !== void 0);
+		},
+		async neighbors(id, depth) {
+			const boundedDepth = Math.min(Math.max(1, Math.floor(depth)), 3);
+			const rows = sqlNeighborsBounded.all(String(id), boundedDepth);
+			const seen = /* @__PURE__ */ new Set([String(id)]);
+			const result = [];
+			for (const row of rows) {
+				if (seen.has(row.id)) continue;
+				seen.add(row.id);
+				result.push(rowToRecord(row));
+			}
+			return result;
+		},
 		async search(query, queryVector) {
 			const limit = query.limit ?? 8;
 			const scores = /* @__PURE__ */ new Map();
@@ -1376,13 +2501,14 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 			const id = asMemoryId(randomUUID());
 			const at = Date.now();
 			withTransaction(() => {
+				sqlRevisionInsert.run(input.id, old.content, old.kind, old.importance, at);
 				sqlSetStatus.run("archived", at, input.id);
 				sqlLog.run(at, "superseded", input.id, JSON.stringify({ supersededBy: id }));
 				insertRecord(id, {
 					scope: input.scope,
 					kind: input.kind,
 					content
-				}, content, input.importance ?? old.importance, old.confidence, at, old.source_session_id, input.embedding ?? old.embedding, "update");
+				}, content, input.importance ?? old.importance, old.confidence, at, old.source_session_id, input.embedding ?? old.embedding, input.imagery ?? jsonToImagery(old.imagery_json), "update");
 				sqlEdgeUpsert.run(id, input.id, "supersedes", at);
 			});
 			return rowToRecord(sqlGet.get(id));
@@ -1393,6 +2519,56 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 			sqlLog.run(Date.now(), "forget", id, null);
 			return rowToRecord(sqlGet.get(id));
 		},
+		async forgetWithTombstone(id, tombstone) {
+			if (getRow(id) === void 0) throw new EngramError("NOT_FOUND", `条目 ${id} 不存在`);
+			const at = Date.now();
+			const cleaned = {
+				reason: tombstone.reason.trim().slice(0, 200),
+				affects: tombstone.affects.trim().slice(0, 200),
+				stillUseful: tombstone.stillUseful.trim().slice(0, 200)
+			};
+			sqlSetStatus.run("forgotten", at, id);
+			sqlLog.run(at, "forget", id, JSON.stringify({ tombstone: cleaned }));
+			return rowToRecord(sqlGet.get(id));
+		},
+		async listForgottenWithTombs(limit) {
+			const boundedLimit = Math.max(1, Math.min(limit, 200));
+			return db.prepare(`SELECT n.*, o.at AS forgotten_at, o.detail AS tombstone_json
+        FROM nodes n
+        INNER JOIN op_log o ON o.target_id = n.id AND o.op = 'forget'
+        WHERE n.status = 'forgotten'
+        ORDER BY o.seq DESC
+        LIMIT ?`).all(boundedLimit).map((row) => {
+				let tombstone = null;
+				if (row.tombstone_json !== null) try {
+					const inner = JSON.parse(row.tombstone_json).tombstone;
+					if (inner !== void 0 && typeof inner.reason === "string") tombstone = {
+						reason: inner.reason,
+						affects: typeof inner.affects === "string" ? inner.affects : "",
+						stillUseful: typeof inner.stillUseful === "string" ? inner.stillUseful : ""
+					};
+				} catch {
+					tombstone = null;
+				}
+				const base = rowToRecord(row);
+				return {
+					id: base.id,
+					scope: base.scope,
+					kind: base.kind,
+					content: base.content,
+					importance: base.importance,
+					lastAccessedAt: base.lastAccessedAt,
+					tombstone,
+					forgottenAt: row.forgotten_at
+				};
+			});
+		},
+		async reportOutcome(id, outcome) {
+			if (getRow(id) === void 0) return void 0;
+			sqlSetOutcome.run(outcome, outcome, id);
+			sqlLog.run(Date.now(), "outcome-report", id, outcome);
+			return rowToRecord(sqlGet.get(id));
+		},
 		async restore(id) {
 			if (getRow(id) === void 0) throw new EngramError("NOT_FOUND", `条目 ${id} 不存在`);
 			sqlSetStatus.run("active", Date.now(), id);
@@ -1429,12 +2605,32 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 			const row = getRow(id);
 			if (row === void 0) return void 0;
 			const operations = sqlOpLogById.all(id, REVIEW_LOG_LIMIT);
+			const revisions = sqlRevisionsById.all(id);
 			return {
 				record: rowToRecord(row),
 				...edgeGroups(id),
-				operations
+				revisions: revisions.map((rev) => ({
+					content: rev.content,
+					kind: rev.kind,
+					importance: rev.importance,
+					supersededAt: rev.superseded_at
+				})),
+				operations: operations.map((op) => ({
+					at: op.at,
+					op: op.op,
+					targetId: op.target_id,
+					detail: op.detail
+				}))
 			};
 		},
+		async recentOps(limit) {
+			return sqlRecentOps.all(Math.max(1, limit)).map((op) => ({
+				at: op.at,
+				op: op.op,
+				targetId: op.target_id,
+				detail: op.detail
+			}));
+		},
 		async stats() {
 			const statusRows = sqlCountBy.all();
 			const kindRows = sqlCountKind.all();
@@ -1500,7 +2696,7 @@ async function openEngramStore(path, rankBoost = NO_BOOST) {
 			const id = asMemoryId(randomUUID());
 			const at = Date.now();
 			withTransaction(() => {
-				insertRecord(id, input, content, input.importance ?? .5, input.confidence ?? .5, at, input.sourceSessionId ?? null, input.embedding ?? null, "distill");
+				insertRecord(id, input, content, input.importance ?? .5, input.confidence ?? .5, at, input.sourceSessionId ?? null, input.embedding ?? null, input.imagery, "distill");
 				for (const oldId of oldIds) {
 					sqlSetStatus.run("archived", at, oldId);
 					sqlEdgeUpsert.run(id, oldId, "supersedes", at);
@@ -1692,6 +2888,47 @@ function mergeQueryResults(retrievals, limit, rrfConstant, minPerQuery) {
 	return [...ranked.filter((entry) => reserved.has(entry.hit.record.id)), ...ranked.filter((entry) => !reserved.has(entry.hit.record.id))].slice(0, Math.max(0, limit)).map((entry) => entry.hit);
 }
 //#endregion
+//#region src/retrieve/budget.ts
+/**
+* 召回输出的字符预算：单条与总量双重截断，控制记忆正文占用的模型上下文
+* （协议内定值，对齐同类记忆插件的单轮召回配额，非部署可变项）。
+* @module @kenz1117/dsh-engram/retrieve/budget
+*/
+/** 单条召回行最大字符数（超长截断加省略号）。 */
+const RECALL_PER_ITEM_CHARS = 1200;
+/** 单次召回输出正文的总字符预算（含 id 与元信息行）。 */
+const RECALL_TOTAL_CHARS = 4800;
+/**
+* 截断单条文本到 maxChars（超长加省略号）。
+* @param text - 原文。
+* @param maxChars - 上限，默认 RECALL_PER_ITEM_CHARS。
+*/
+function truncateItem(text, maxChars = RECALL_PER_ITEM_CHARS) {
+	return text.length <= maxChars ? text : `${text.slice(0, maxChars)}…`;
+}
+/**
+* 总量预算内贪心装填行（保序；某行装不下时继续尝试更短的后续行），
+* 被跳过的行计数并在末尾追加提示行。
+* @param lines - 候选行（已按相关性排序）。
+* @param totalBudget - 总字符预算，默认 RECALL_TOTAL_CHARS。
+* @returns 装填后的行；有丢弃时末尾含「另有 N 条…」提示。
+*/
+function enforceBudget(lines, totalBudget = RECALL_TOTAL_CHARS) {
+	const kept = [];
+	let used = 0;
+	let dropped = 0;
+	for (const line of lines) {
+		if (used + line.length > totalBudget) {
+			dropped += 1;
+			continue;
+		}
+		kept.push(line);
+		used += line.length;
+	}
+	if (dropped > 0) kept.push(`（另有 ${dropped} 条未展示：缩小查询范围或降低 limit 后重试）`);
+	return kept;
+}
+//#endregion
 //#region src/tools/create.ts
 /**
 * 9 个 engram_ 工具的定义与执行器。工具 schema 保持窄参数；
@@ -1707,13 +2944,19 @@ const KINDS = [
 ];
 /** 从模型参数收敛 scope（非法值或缺失回退 fallback）。 */
 function scopeOf(raw, fallback) {
-	return raw === "user" || raw === "project" ? raw : fallback;
+	if (raw === "user" || raw === "project" || raw === "shared") return raw;
+	return fallback;
 }
 /** 把 search scope 参数收敛为分库集合。 */
 function scopesOf(raw) {
 	if (raw === "user") return ["user"];
 	if (raw === "project") return ["project"];
-	return ["user", "project"];
+	if (raw === "shared") return ["shared"];
+	return [
+		"user",
+		"project",
+		"shared"
+	];
 }
 /** 查询向量：嵌入可用时返回查询文本的向量，否则 undefined（降级）。 */
 async function queryVectorOf(deps, text) {
@@ -1731,7 +2974,7 @@ async function rewriteQueries(deps, exec, query) {
 		queries: [query],
 		rewritten: false
 	};
-	const events = exec.agent?.session?.events ?? [];
+	const events = exec.agent?.session?.snapshotEvents() ?? [];
 	const route = deps.routeOverride ?? routeFromEvents(events);
 	if (route === void 0) return {
 		queries: [query],
@@ -1768,7 +3011,7 @@ async function rewriteQueries(deps, exec, query) {
 	}
 }
 /**
-* 构造 9 个工具定义（engram_save/search/timeline/update/forget/review/stats/export/distill）。
+* 构造 10 个工具定义（engram_save/search/timeline/update/forget/report/review/stats/export/distill）。
 * @param deps - 分库打开器、嵌入器、辅助 LLM、导出目录。
 * @returns 可直接 register 的工具定义数组。
 */
@@ -1891,307 +3134,501 @@ function createEngramTools(deps) {
 			failed
 		};
 	}
-	return [
-		defineTool({
-			name: "engram_save",
-			description: "保存长期记忆（跨会话可用），支持单条（content/kind）或批量（items，最多 10 条，单条失败不影响其余）。kind：fact 事实 / preference 偏好 / decision 决策 / episode 经历 / skill 方法。scope：project 仅当前项目，user 全局。",
-			parameters: {
-				content: {
-					type: "string",
-					description: "记忆正文（单条模式必填），一句话完整表达"
-				},
-				kind: {
-					type: "string",
-					enum: [...KINDS],
-					description: "记忆种类（单条模式必填）"
-				},
+	const save = defineTool({
+		name: "engram_save",
+		description: "保存长期记忆（跨会话可用），支持单条（content/kind）或批量（items，最多 10 条，单条失败不影响其余）。kind：fact 事实 / preference 偏好 / decision 决策 / episode 经历 / skill 方法。scope：project 仅当前项目，user 全局。",
+		parameters: {
+			content: {
+				type: "string",
+				description: "记忆正文（单条模式必填），一句话完整表达"
+			},
+			kind: {
+				type: "string",
+				enum: [...KINDS],
+				description: "记忆种类（单条模式必填）"
+			},
+			items: {
+				type: "array",
+				description: "批量保存条目数组，每项 {content, kind, importance?}；与 content/kind 二选一",
 				items: {
-					type: "array",
-					description: "批量保存条目数组，每项 {content, kind, importance?}；与 content/kind 二选一",
-					items: {
-						type: "object",
-						additionalProperties: false,
-						properties: {
-							content: {
-								type: "string",
-								required: true,
-								description: "记忆正文"
-							},
-							kind: {
-								type: "string",
-								enum: [...KINDS],
-								required: true,
-								description: "记忆种类"
-							},
-							importance: {
-								type: "number",
-								description: "重要性 0-1"
-							}
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						content: {
+							type: "string",
+							required: true,
+							description: "记忆正文"
+						},
+						kind: {
+							type: "string",
+							enum: [...KINDS],
+							required: true,
+							description: "记忆种类"
+						},
+						importance: {
+							type: "number",
+							description: "重要性 0-1"
 						}
 					}
-				},
-				scope: {
-					type: "string",
-					enum: ["user", "project"],
-					description: "作用域，默认 project"
-				},
-				importance: {
-					type: "number",
-					description: "重要性 0-1，默认 0.5（仅单条模式）"
 				}
 			},
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: {
-						id: { type: "string" },
-						kind: { type: "string" },
-						importance: { type: "number" },
-						text: { type: "string" },
-						count: { type: "number" },
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared"
+				],
+				description: "作用域，默认 project"
+			},
+			importance: {
+				type: "number",
+				description: "重要性 0-1，默认 0.5（仅单条模式）"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					id: { type: "string" },
+					kind: { type: "string" },
+					importance: { type: "number" },
+					text: { type: "string" },
+					count: { type: "number" },
+					items: {
+						type: "array",
 						items: {
-							type: "array",
-							items: {
-								type: "object",
-								additionalProperties: false,
-								properties: {
-									id: {
-										type: "string",
-										required: true
-									},
-									kind: {
-										type: "string",
-										required: true
-									},
-									importance: {
-										type: "number",
-										required: true
-									}
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								id: {
+									type: "string",
+									required: true
+								},
+								kind: {
+									type: "string",
+									required: true
+								},
+								importance: {
+									type: "number",
+									required: true
 								}
 							}
-						},
-						failed: {
-							type: "array",
-							items: {
-								type: "object",
-								additionalProperties: false,
-								properties: {
-									index: {
-										type: "number",
-										required: true
-									},
-									reason: {
-										type: "string",
-										required: true
-									}
+						}
+					},
+					failed: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								index: {
+									type: "number",
+									required: true
+								},
+								reason: {
+									type: "string",
+									required: true
 								}
 							}
 						}
 					}
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: renderSaveResultText(value)
-				}]
-			},
-			async execute(args, exec) {
-				const input = args;
-				const sourceSessionId = exec.agent?.id ?? null;
-				if (input.items !== void 0) {
-					if (input.content !== void 0 || input.kind !== void 0) throw new Error("engram_save: items 与 content/kind 参数不能同时使用");
-					if (!Array.isArray(input.items) || input.items.length === 0) throw new Error("engram_save: items 必须是非空数组");
-					return saveBatch(sourceSessionId, input.items, input.scope);
-				}
-				if (typeof input.content !== "string" || typeof input.kind !== "string") throw new Error("engram_save: 需要 content/kind（单条）或 items（批量）参数");
-				const content = redactSecrets(sanitizeProtocolText(input.content));
-				if (content.trim() === "") throw new Error("engram_save: 清洗后内容为空（原文只含协议标签或密钥）");
-				const scope = scopeOf(input.scope, "project");
-				const store = await deps.openStore(scope);
-				const embedder = await deps.embedder;
-				const embeddings = embedder === void 0 ? void 0 : await embedder.embed([content.trim()]);
-				const { record, candidates } = await writeWithContradictions(store, {
-					scope,
-					kind: input.kind,
-					content,
-					...typeof input.importance === "number" ? { importance: input.importance } : {},
-					sourceSessionId,
-					...embeddings?.[0] === void 0 ? {} : { embedding: embeddings[0] }
-				});
-				if (candidates.length > 0) {
-					const listed = candidates.map((candidate) => `「${candidate.content}」（id=${candidate.id}）`).join("；");
-					return {
-						id: record.id,
-						kind: record.kind,
-						importance: record.importance,
-						text: `已保存 ${record.id}。注意：与现有记忆高度相似——${listed}。若这是修正而非新事实，请用 engram_update 归并，或 engram_forget 去重。`
-					};
 				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderSaveResultText(value)
+			}]
+		},
+		async execute(args, exec) {
+			const input = args;
+			const sourceSessionId = exec.agent?.id ?? null;
+			if (input.items !== void 0) {
+				if (input.content !== void 0 || input.kind !== void 0) throw new Error("engram_save: items 与 content/kind 参数不能同时使用");
+				if (!Array.isArray(input.items) || input.items.length === 0) throw new Error("engram_save: items 必须是非空数组");
+				return saveBatch(sourceSessionId, input.items, input.scope);
+			}
+			if (typeof input.content !== "string" || typeof input.kind !== "string") throw new Error("engram_save: 需要 content/kind（单条）或 items（批量）参数");
+			const content = redactSecrets(sanitizeProtocolText(input.content));
+			if (content.trim() === "") throw new Error("engram_save: 清洗后内容为空（原文只含协议标签或密钥）");
+			const scope = scopeOf(input.scope, "project");
+			const store = await deps.openStore(scope);
+			const embedder = await deps.embedder;
+			const embeddings = embedder === void 0 ? void 0 : await embedder.embed([content.trim()]);
+			const { record, candidates } = await writeWithContradictions(store, {
+				scope,
+				kind: input.kind,
+				content,
+				...typeof input.importance === "number" ? { importance: input.importance } : {},
+				sourceSessionId,
+				...embeddings?.[0] === void 0 ? {} : { embedding: embeddings[0] }
+			});
+			if (candidates.length > 0) {
+				const listed = candidates.map((candidate) => `「${candidate.content}」（id=${candidate.id}）`).join("；");
 				return {
 					id: record.id,
 					kind: record.kind,
-					importance: record.importance
+					importance: record.importance,
+					text: `已保存 ${record.id}。注意：与现有记忆高度相似——${listed}。若这是修正而非新事实，请用 engram_update 归并，或 engram_forget 去重。`
 				};
 			}
-		}),
-		defineTool({
-			name: "engram_search",
-			description: "语义 + 关键词混合检索长期记忆。user 作用域存偏好与通用事实，project 作用域存项目约定与决策。结果行尾给出 id，供 engram_update/engram_forget 引用。",
-			parameters: {
-				query: {
-					type: "string",
-					required: true,
-					description: "检索文本"
-				},
-				scope: {
-					type: "string",
-					enum: [
-						"user",
-						"project",
-						"all"
-					],
-					description: "作用域，默认 all"
-				},
-				limit: {
-					type: "number",
-					description: "返回条数上限，默认 8"
-				}
+			return {
+				id: record.id,
+				kind: record.kind,
+				importance: record.importance
+			};
+		}
+	});
+	const search = defineTool({
+		name: "engram_search",
+		description: "语义 + 关键词混合检索长期记忆。user 作用域存偏好与通用事实，project 作用域存项目约定与决策。结果行尾给出 id，供 engram_update/engram_forget 引用。",
+		parameters: {
+			query: {
+				type: "string",
+				required: true,
+				description: "检索文本"
 			},
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: {
-						degraded: {
-							type: "boolean",
-							required: true
-						},
-						text: {
-							type: "string",
-							required: true
-						}
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared",
+					"all"
+				],
+				description: "作用域，默认 all"
+			},
+			limit: {
+				type: "number",
+				description: "返回条数上限，默认 8"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					degraded: {
+						type: "boolean",
+						required: true
+					},
+					text: {
+						type: "string",
+						required: true
 					}
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: value.text
-				}]
+				}
 			},
-			async execute(args, exec) {
-				const input = args;
-				const scopes = scopesOf(input.scope);
-				const limit = input.limit ?? 8;
-				const rewrite = await rewriteQueries(deps, exec, input.query);
-				const retrievals = await Promise.all(rewrite.queries.map(async (queryText) => {
-					const vector = await queryVectorOf(deps, queryText);
-					const results = await Promise.all(scopes.map(async (scope) => {
-						return (await deps.openStore(scope)).search({
-							text: queryText,
-							scopes: [scope],
-							limit
-						}, vector);
-					}));
-					return {
-						hits: results.flatMap((result) => result.hits).sort((a, b) => b.score - a.score).slice(0, limit),
-						degraded: results.some((result) => result.degraded)
-					};
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args, exec) {
+			const input = args;
+			const scopes = scopesOf(input.scope);
+			const limit = input.limit ?? 8;
+			const rewrite = await rewriteQueries(deps, exec, input.query);
+			const retrievals = await Promise.all(rewrite.queries.map(async (queryText) => {
+				const vector = await queryVectorOf(deps, queryText);
+				const results = await Promise.all(scopes.map(async (scope) => {
+					return (await deps.openStore(scope)).search({
+						text: queryText,
+						scopes: [scope],
+						limit
+					}, vector);
 				}));
-				const degraded = retrievals.some((retrieval) => retrieval.degraded);
-				const lines = mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length))).map((hit, index) => {
-					const edge = hit.viaEdge === void 0 ? "" : `（经 ${hit.viaEdge.type} 关联自 ${hit.viaEdge.from}）`;
-					return `${index + 1}. [${hit.record.scope}/${hit.record.kind}] ${hit.record.content}（id=${hit.record.id}）${edge}`;
-				});
 				return {
-					degraded,
-					text: renderMemoryPacket(`${degraded && lines.length > 0 ? "（语义嵌入不可用，仅关键词检索）\n" : ""}${lines.join("\n") || "无命中"}`, "tool_search", input.query)
+					hits: results.flatMap((result) => result.hits).sort((a, b) => b.score - a.score).slice(0, limit),
+					degraded: results.some((result) => result.degraded)
 				};
+			}));
+			const degraded = retrievals.some((retrieval) => retrieval.degraded);
+			const lines = enforceBudget(mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length))).map((hit, index) => {
+				const edge = hit.viaEdge === void 0 ? "" : `（经 ${hit.viaEdge.type} 关联自 ${hit.viaEdge.from}）`;
+				return `${index + 1}. [${hit.record.scope}/${hit.record.kind}] ${truncateItem(hit.record.content)}（id=${hit.record.id}）${edge}`;
+			}));
+			return {
+				degraded,
+				text: renderMemoryPacket(`${degraded && lines.length > 0 ? "（语义嵌入不可用，仅关键词检索）\n" : ""}${lines.join("\n") || "无命中"}`, "tool_search", input.query)
+			};
+		}
+	});
+	const timeline = defineTool({
+		name: "engram_timeline",
+		description: "按时间范围与主题浏览记忆（时间倒序，最近 20 条）。无参数直接列出最近记录。",
+		parameters: {
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared",
+					"all"
+				],
+				description: "作用域，默认 all"
+			},
+			topic: {
+				type: "string",
+				description: "主题子串"
+			},
+			since: {
+				type: "string",
+				description: "起始时间（ISO 或可解析日期）"
+			},
+			until: {
+				type: "string",
+				description: "结束时间"
 			}
-		}),
-		defineTool({
-			name: "engram_timeline",
-			description: "按时间范围与主题浏览记忆（时间倒序，最近 20 条）。无参数直接列出最近记录。",
-			parameters: {
-				scope: {
-					type: "string",
-					enum: [
-						"user",
-						"project",
-						"all"
-					],
-					description: "作用域，默认 all"
-				},
-				topic: {
-					type: "string",
-					description: "主题子串"
-				},
-				since: {
-					type: "string",
-					description: "起始时间（ISO 或可解析日期）"
-				},
-				until: {
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { text: {
 					type: "string",
-					description: "结束时间"
-				}
+					required: true
+				} }
 			},
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: { text: {
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args) {
+			const input = args;
+			const scopes = scopesOf(input.scope);
+			const parseTime = (raw, field) => {
+				if (raw === void 0) return void 0;
+				const ms = Date.parse(raw);
+				if (Number.isNaN(ms)) throw new Error(`engram_timeline: ${field} 不是可解析时间 ${raw}`);
+				return ms;
+			};
+			const since = parseTime(input.since, "since");
+			const until = parseTime(input.until, "until");
+			return { text: renderMemoryPacket(enforceBudget((await Promise.all(scopes.map(async (scope) => {
+				return (await deps.openStore(scope)).timeline({
+					scopes: [scope],
+					...input.topic === void 0 ? {} : { topic: input.topic },
+					...since === void 0 ? {} : { since },
+					...until === void 0 ? {} : { until },
+					limit: 20
+				});
+			}))).flat().sort((a, b) => b.createdAt - a.createdAt).slice(0, 20).map((record) => `${new Date(record.createdAt).toISOString()} [${record.scope}/${record.kind}] ${truncateItem(record.content)}（id=${record.id}）`)).join("\n") || "时间线为空", "tool_timeline", input.topic ?? "（对话继续）") };
+		}
+	});
+	const update = defineTool({
+		name: "engram_update",
+		description: "修正一条记忆：写入新条目并把旧条目标记为被取代（链条保留，可审计）。id 来自 engram_search 结果。",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "要修正的旧条目 id"
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "修正后的正文"
+			},
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared"
+				],
+				description: "旧条目作用域，默认 project"
+			},
+			kind: {
+				type: "string",
+				enum: [...KINDS],
+				description: "种类，默认继承旧条目"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					id: {
 						type: "string",
 						required: true
-					} }
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: value.text
-				}]
+					},
+					superseded: {
+						type: "string",
+						required: true
+					}
+				}
 			},
-			async execute(args) {
-				const input = args;
-				const scopes = scopesOf(input.scope);
-				const parseTime = (raw, field) => {
-					if (raw === void 0) return void 0;
-					const ms = Date.parse(raw);
-					if (Number.isNaN(ms)) throw new Error(`engram_timeline: ${field} 不是可解析时间 ${raw}`);
-					return ms;
-				};
-				const since = parseTime(input.since, "since");
-				const until = parseTime(input.until, "until");
-				return { text: renderMemoryPacket((await Promise.all(scopes.map(async (scope) => {
-					return (await deps.openStore(scope)).timeline({
-						scopes: [scope],
-						...input.topic === void 0 ? {} : { topic: input.topic },
-						...since === void 0 ? {} : { since },
-						...until === void 0 ? {} : { until },
-						limit: 20
-					});
-				}))).flat().sort((a, b) => b.createdAt - a.createdAt).slice(0, 20).map((record) => `${new Date(record.createdAt).toISOString()} [${record.scope}/${record.kind}] ${record.content}（id=${record.id}）`).join("\n") || "时间线为空", "tool_timeline", input.topic ?? "（对话继续）") };
+			render: (_args, value) => [{
+				type: "text",
+				text: `已写入修正记忆 ${value.id}；旧条目 ${value.superseded} 已归档并建立取代链。`
+			}]
+		},
+		async execute(args) {
+			const input = args;
+			const content = redactSecrets(sanitizeProtocolText(input.content));
+			if (content.trim() === "") throw new Error("engram_update: 清洗后内容为空（原文只含协议标签或密钥）");
+			const scope = scopeOf(input.scope, "project");
+			const store = await deps.openStore(scope);
+			const old = await store.get(input.id);
+			if (old === void 0) throw new Error(`engram_update: 条目 ${input.id} 不存在于 ${scope} 库（用 engram_search 确认 id 与 scope）`);
+			const embedder = await deps.embedder;
+			const embeddings = embedder === void 0 ? void 0 : await embedder.embed([content.trim()]);
+			return {
+				id: (await store.update({
+					id: input.id,
+					scope,
+					kind: input.kind ?? old.kind,
+					content,
+					...embeddings === void 0 ? {} : { embedding: embeddings[0] }
+				})).id,
+				superseded: input.id
+			};
+		}
+	});
+	const forget = defineTool({
+		name: "engram_forget",
+		description: "闭馆仪式（软删，可恢复）：遗忘前必须留下「为什么关 / 影响谁 / 还有用吗」三问答案作为墓志铭，便于日后考古。id 与 scope 来自 engram_search 结果。",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "条目 id"
+			},
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared"
+				],
+				description: "条目作用域，默认 project"
+			},
+			reason: {
+				type: "string",
+				required: true,
+				description: "闭馆原因：被取代 / 过期 / 与现实不符 / 隐私 等"
+			},
+			affects: {
+				type: "string",
+				required: true,
+				description: "影响哪些条目/人/项目，空串表示不适用"
+			},
+			stillUseful: {
+				type: "string",
+				required: true,
+				description: "遗留价值：可考古 / 可复习 / 回滚时如何理解"
 			}
-		}),
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { id: {
+					type: "string",
+					required: true
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `房间 ${value.id} 已闭馆（软删，可恢复），墓志铭已刻入操作日志。`
+			}]
+		},
+		async execute(args) {
+			const input = args;
+			const scope = scopeOf(input.scope, "project");
+			const reason = typeof input.reason === "string" ? input.reason.trim() : "";
+			const affects = typeof input.affects === "string" ? input.affects.trim() : "";
+			const stillUseful = typeof input.stillUseful === "string" ? input.stillUseful.trim() : "";
+			if (reason === "" || affects === "" || stillUseful === "") throw new Error("engram_forget: 闭馆三问（reason / affects / stillUseful）都必须填写，方便日后考古");
+			return { id: (await (await deps.openStore(scope)).forgetWithTombstone(input.id, {
+				reason,
+				affects,
+				stillUseful
+			})).id };
+		}
+	});
+	/** P0-3 闭馆考古：返回最近 N 条 forgotten 条目 + 墓志铭。 */
+	const auditForgotten = defineTool({
+		name: "engram_audit_forgotten",
+		description: "闭馆考古：列出最近 N 条已闭馆条目 + 墓志铭（为什么关 / 影响谁 / 还有用吗），便于复核过去的遗忘是否得当。",
+		parameters: {
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared",
+					"all"
+				],
+				description: "作用域，默认 all"
+			},
+			limit: {
+				type: "integer",
+				description: "返回条数上限，默认 20"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { text: {
+					type: "string",
+					required: true
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args) {
+			const input = args;
+			const scopes = scopesOf(input.scope);
+			const limit = Number.isInteger(input.limit) ? Math.min(Math.max(1, input.limit), 50) : 20;
+			const all = (await Promise.all(scopes.map(async (scope) => (await deps.openStore(scope)).listForgottenWithTombs(limit)))).flat();
+			all.sort((a, b) => b.forgottenAt - a.forgottenAt);
+			const sliced = all.slice(0, limit);
+			if (sliced.length === 0) return { text: "尚无闭馆条目。" };
+			const lines = sliced.map((row, index) => {
+				const stamp = new Date(row.forgottenAt).toISOString();
+				const tomb = row.tombstone === null ? "（墓志铭缺失：旧版无三问数据）" : `\n   - 为什么关：${row.tombstone.reason}\n   - 影响谁：${row.tombstone.affects}\n   - 还有用吗：${row.tombstone.stillUseful}`;
+				return `${index + 1}. [${row.scope}/${row.kind}] ${row.content.slice(0, 80)}${row.content.length > 80 ? "…" : ""}\n   id=${row.id} · importance=${row.importance.toFixed(2)} · 闭馆于 ${stamp}${tomb}`;
+			});
+			return { text: `闭馆考古（共 ${sliced.length} 条）：\n${lines.join("\n")}` };
+		}
+	});
+	return [
+		save,
+		search,
+		timeline,
+		update,
+		forget,
 		defineTool({
-			name: "engram_update",
-			description: "修正一条记忆：写入新条目并把旧条目标记为被取代（链条保留，可审计）。id 来自 engram_search 结果。",
+			name: "engram_report",
+			description: "回报一条记忆（尤其 skill 类）使用后的实际效果：success（有效，提权）或 failure（无效，降权）。id 与 scope 来自 engram_search 结果。效果影响后续召回排序，长期无效的记忆将被衰减归档。",
 			parameters: {
 				id: {
 					type: "string",
 					required: true,
-					description: "要修正的旧条目 id"
+					description: "条目 id"
 				},
-				content: {
+				outcome: {
 					type: "string",
+					enum: ["success", "failure"],
 					required: true,
-					description: "修正后的正文"
+					description: "使用效果"
 				},
 				scope: {
 					type: "string",
-					enum: ["user", "project"],
-					description: "旧条目作用域，默认 project"
-				},
-				kind: {
-					type: "string",
-					enum: [...KINDS],
-					description: "种类，默认继承旧条目"
+					enum: [
+						"user",
+						"project",
+						"shared"
+					],
+					description: "条目作用域，默认 project"
 				}
 			},
 			output: {
@@ -2203,74 +3640,34 @@ function createEngramTools(deps) {
 							type: "string",
 							required: true
 						},
-						superseded: {
+						outcome: {
 							type: "string",
 							required: true
+						},
+						confidence: {
+							type: "number",
+							required: true
 						}
 					}
 				},
 				render: (_args, value) => [{
 					type: "text",
-					text: `已写入修正记忆 ${value.id}；旧条目 ${value.superseded} 已归档并建立取代链。`
+					text: value.outcome === "success" ? `已记录：记忆 ${value.id} 使用有效（confidence=${value.confidence}）。该记忆后续召回排序将提升。` : `已记录：记忆 ${value.id} 使用无效（confidence=${value.confidence}）。该记忆后续召回排序将下降，持续无效会被衰减归档。`
 				}]
 			},
 			async execute(args) {
 				const input = args;
-				const content = redactSecrets(sanitizeProtocolText(input.content));
-				if (content.trim() === "") throw new Error("engram_update: 清洗后内容为空（原文只含协议标签或密钥）");
+				if (input.outcome !== "success" && input.outcome !== "failure") throw new Error("engram_report: outcome 必须是 success 或 failure");
 				const scope = scopeOf(input.scope, "project");
-				const store = await deps.openStore(scope);
-				const old = await store.get(input.id);
-				if (old === void 0) throw new Error(`engram_update: 条目 ${input.id} 不存在于 ${scope} 库（用 engram_search 确认 id 与 scope）`);
-				const embedder = await deps.embedder;
-				const embeddings = embedder === void 0 ? void 0 : await embedder.embed([content.trim()]);
+				const record = await (await deps.openStore(scope)).reportOutcome(input.id, input.outcome);
+				if (record === void 0) throw new Error(`engram_report: 条目 ${input.id} 不存在（scope=${scope}）`);
 				return {
-					id: (await store.update({
-						id: input.id,
-						scope,
-						kind: input.kind ?? old.kind,
-						content,
-						...embeddings === void 0 ? {} : { embedding: embeddings[0] }
-					})).id,
-					superseded: input.id
+					id: record.id,
+					outcome: input.outcome,
+					confidence: record.confidence
 				};
 			}
 		}),
-		defineTool({
-			name: "engram_forget",
-			description: "遗忘一条记忆（软删，用户可从库中恢复）。id 与 scope 来自 engram_search 结果。",
-			parameters: {
-				id: {
-					type: "string",
-					required: true,
-					description: "条目 id"
-				},
-				scope: {
-					type: "string",
-					enum: ["user", "project"],
-					description: "条目作用域，默认 project"
-				}
-			},
-			output: {
-				schema: {
-					type: "object",
-					additionalProperties: false,
-					properties: { id: {
-						type: "string",
-						required: true
-					} }
-				},
-				render: (_args, value) => [{
-					type: "text",
-					text: `记忆 ${value.id} 已遗忘（软删，可恢复）。`
-				}]
-			},
-			async execute(args) {
-				const input = args;
-				const scope = scopeOf(input.scope, "project");
-				return { id: (await (await deps.openStore(scope)).forget(input.id)).id };
-			}
-		}),
 		defineTool({
 			name: "engram_review",
 			description: "审计一条记忆：查看内容、来源（会话/轮次/事件）、取代链、矛盾与关联，以及最近操作日志。",
@@ -2282,7 +3679,11 @@ function createEngramTools(deps) {
 				},
 				scope: {
 					type: "string",
-					enum: ["user", "project"],
+					enum: [
+						"user",
+						"project",
+						"shared"
+					],
 					description: "条目作用域，默认 project"
 				}
 			},
@@ -2315,6 +3716,7 @@ function createEngramTools(deps) {
 					section("取代了谁", view.supersedes.map(String)),
 					section("矛盾候选", view.contradicts.map(String)),
 					section("关联", view.related.map(String)),
+					view.revisions.length === 0 ? "" : `\n修订历史:\n${view.revisions.map((rev) => `- ${new Date(rev.supersededAt).toISOString()} [${rev.kind}] ${truncateItem(rev.content)}`).join("\n")}`,
 					view.operations.length === 0 ? "" : `\n最近操作:\n${view.operations.map((op) => `- ${new Date(op.at).toISOString()} ${op.op}${op.detail === null ? "" : ` ${op.detail}`}`).join("\n")}`
 				].filter((part) => part !== "").join("\n"), "tool_review", "（对话继续）") };
 			}
@@ -2327,6 +3729,7 @@ function createEngramTools(deps) {
 				enum: [
 					"user",
 					"project",
+					"shared",
 					"all"
 				],
 				description: "作用域，默认 all"
@@ -2359,25 +3762,30 @@ function createEngramTools(deps) {
 		}),
 		defineTool({
 			name: "engram_export",
-			description: "把记忆库导出为文件（Markdown 或 JSON，含全部状态与关系边），返回文件路径。redactedView=true 时输出脱敏视图（内容二次清洗并截断为 40 字预览，可安全分享）。",
+			description: "把记忆库导出为文件（Markdown / JSON / 镜像目录），返回文件路径。redactedView=true 时输出脱敏视图（内容二次清洗并截断为 40 字预览，可安全分享）。format=markdown-mirror 时每个房间一个 .md + frontmatter，附楼层清单 _meta.json 与全宫殿入口 _index.md，可直接用 Obsidian / git 漫游。",
 			parameters: {
 				format: {
 					type: "string",
-					enum: ["markdown", "json"],
-					description: "导出格式，默认 markdown"
+					enum: [
+						"markdown",
+						"json",
+						"markdown-mirror"
+					],
+					description: "导出格式：markdown 单文件、json 单文件、markdown-mirror 每房间一文件（默认 markdown）"
 				},
 				scope: {
 					type: "string",
 					enum: [
 						"user",
 						"project",
+						"shared",
 						"all"
 					],
 					description: "作用域，默认 all"
 				},
 				redactedView: {
 					type: "boolean",
-					description: "脱敏视图：内容二次脱敏并截断为预览（默认 false 完整导出）"
+					description: "脱敏视图：内容二次脱敏并截断为预览（默认 false 完整导出；镜像模式忽略此参数）"
 				}
 			},
 			output: {
@@ -2396,7 +3804,7 @@ function createEngramTools(deps) {
 			},
 			async execute(args) {
 				const input = args;
-				const format = input.format === "json" ? "json" : "markdown";
+				const format = input.format === "json" ? "json" : input.format === "markdown-mirror" ? "markdown-mirror" : "markdown";
 				const redactedView = input.redactedView === true;
 				const scopes = scopesOf(input.scope);
 				const preview = (content) => {
@@ -2410,6 +3818,13 @@ function createEngramTools(deps) {
 				const written = [];
 				for (const scope of scopes) {
 					const data = await (await deps.openStore(scope)).exportAll();
+					if (format === "markdown-mirror") {
+						const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-").slice(0, 19);
+						const mirrorRoot = join(deps.exportDir, `mirror-${scope}-${stamp}`);
+						const report = await writeMirror(mirrorRoot, data);
+						written.push(`${mirrorRoot}（${report.fileCount} 个文件，${data.records.length} 间房间，${report.floors.length} 个楼层）`);
+						continue;
+					}
 					const payload = redactedView ? {
 						...data,
 						records: data.records.map((record) => ({
@@ -2440,7 +3855,11 @@ function createEngramTools(deps) {
 			description: "蒸馏整理：把同主题的记忆簇合并提炼为更高层的规律（旧条目归档、supersedes 链保留）。建议记忆较多时周期性执行。",
 			parameters: { scope: {
 				type: "string",
-				enum: ["user", "project"],
+				enum: [
+					"user",
+					"project",
+					"shared"
+				],
 				description: "作用域，默认 user"
 			} },
 			output: {
@@ -2461,7 +3880,7 @@ function createEngramTools(deps) {
 				const scope = scopeOf(args.scope, "user");
 				if (deps.call === void 0) throw new Error("engram_distill: 辅助 LLM 不可用（宿主未提供 llm 服务），无法蒸馏");
 				const call = deps.call;
-				const events = exec.agent?.session?.events ?? [];
+				const events = exec.agent?.session?.snapshotEvents() ?? [];
 				const route = deps.routeOverride ?? routeFromEvents(events);
 				if (route === void 0) throw new Error("engram_distill: 无法确定模型路由（会话尚无模型请求），请在 cordis.yml 配置 provider/model");
 				const embedder = await deps.embedder;
@@ -2483,19 +3902,298 @@ function createEngramTools(deps) {
 				});
 				return { text: `蒸馏完成：取材 ${outcome.input} 条，产出 ${outcome.distilled} 条高层规律，归档 ${outcome.superseded} 条旧记忆（supersedes 链已建立，可 engram_review 审计）。` };
 			}
-		})
+		}),
+		defineTool({
+			name: "engram_examine",
+			description: "渐进式披露：按 id 批量拉取房间完整铭牌（content + 楼层 + 状态 + 边关系）。仅在已通过 engram_search/timeline/neighbors 拿到候选 id 后调用，避免一次性吞全文。建议 ≤16 个 id，超出会按入参顺序保留前 N 条。",
+			parameters: { ids: {
+				type: "array",
+				items: { type: "string" },
+				description: "房间 id 列表"
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { text: {
+						type: "string",
+						required: true
+					} }
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.text
+				}]
+			},
+			async execute(args) {
+				const input = args;
+				const rawIds = Array.isArray(input.ids) ? input.ids.filter((x) => typeof x === "string") : [];
+				if (rawIds.length === 0) throw new Error("engram_examine: ids 必填且至少含 1 条");
+				const ids = rawIds.slice(0, 16).map((id) => asMemoryId(id));
+				const store = await deps.openStore("user");
+				const projectStore = await deps.openStore("project");
+				const [fromUser, fromProject] = await Promise.all([store.getMany(ids), projectStore.getMany(ids)]);
+				const records = [...fromUser, ...fromProject];
+				if (records.length === 0) throw new Error(`engram_examine: 全部 ${ids.length} 个 id 都找不到`);
+				return { text: records.map((record, index) => [
+					`### ${index + 1}. [${record.scope}/${record.kind}/${record.status}] id=${record.id}`,
+					`铭牌: ${record.content}`,
+					`地标亮度=${record.importance.toFixed(2)} · 考据可靠度=${record.confidence.toFixed(2)} · 参观=${record.accessCount}人次`
+				].join("\n")).join("\n\n") };
+			}
+		}),
+		defineTool({
+			name: "engram_neighbors",
+			description: "走廊漫步：从某间出发走 1-3 跳内的 related/supersedes/contradicts 边，返回邻居房间简表（仅 id + scope + kind + status + content），便于判断下一站。",
+			parameters: {
+				id: {
+					type: "string",
+					description: "起点房间 id"
+				},
+				depth: {
+					type: "integer",
+					description: "跳数（默认 1，最多 3，由执行器夹逼）"
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { text: {
+						type: "string",
+						required: true
+					} }
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.text
+				}]
+			},
+			async execute(args) {
+				const input = args;
+				if (typeof input.id !== "string" || input.id === "") throw new Error("engram_neighbors: id 必填");
+				const depth = Number.isInteger(input.depth) ? Math.min(Math.max(1, input.depth), 3) : 1;
+				const seed = asMemoryId(input.id);
+				const userStore = await deps.openStore("user");
+				const projectStore = await deps.openStore("project");
+				const seedRow = await userStore.get(seed) ?? await projectStore.get(seed);
+				if (seedRow === void 0) throw new Error(`engram_neighbors: 起点 ${seed} 不存在`);
+				const seedScope = seedRow.scope;
+				const neighbors = await (seedScope === "user" ? userStore : projectStore).neighbors(seed, depth);
+				if (neighbors.length === 0) return { text: `从 ${seed}（${seedScope}）出发，${depth} 跳内无邻居房间。` };
+				const lines = neighbors.map((record, index) => `${index + 1}. [${record.scope}/${record.kind}/${record.status}] ${record.content.slice(0, 80)}${record.content.length > 80 ? "…" : ""}（id=${record.id}）`);
+				return { text: `起点 ${seed}（${seedScope}）→ ${depth} 跳走廊共访 ${neighbors.length} 间：\n${lines.join("\n")}` };
+			}
+		}),
+		defineTool({
+			name: "engram_tour",
+			description: "巡游路由：按「同类巩固 → 走廊相邻 → 反差补位」顺序组织 3-7 间房间，每站附入选理由 + 意象铭牌回声。适合在用户问起某主题时直接给出一条可走的导览路线，而不是无序结果集。",
+			parameters: {
+				query: {
+					type: "string",
+					required: true,
+					description: "巡游主题（与 engram_search 同义）"
+				},
+				scope: {
+					type: "string",
+					enum: [
+						"user",
+						"project",
+						"shared",
+						"all"
+					],
+					description: "作用域，默认 all"
+				},
+				maxStops: {
+					type: "integer",
+					description: "最多站数（默认 6，3-7 之间）"
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { text: {
+						type: "string",
+						required: true
+					} }
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.text
+				}]
+			},
+			async execute(args, exec) {
+				const input = args;
+				const scopes = scopesOf(input.scope);
+				const limit = 12;
+				const maxStops = Number.isInteger(input.maxStops) ? Math.min(Math.max(3, input.maxStops), 7) : 6;
+				const rewrite = await rewriteQueries(deps, exec, input.query);
+				const retrievals = await Promise.all(rewrite.queries.map(async (queryText) => {
+					const vector = await queryVectorOf(deps, queryText);
+					const results = await Promise.all(scopes.map(async (scope) => {
+						return (await deps.openStore(scope)).search({
+							text: queryText,
+							scopes: [scope],
+							limit
+						}, vector);
+					}));
+					return {
+						hits: results.flatMap((result) => result.hits).sort((a, b) => b.score - a.score).slice(0, limit),
+						degraded: results.some((result) => result.degraded)
+					};
+				}));
+				const degraded = retrievals.some((retrieval) => retrieval.degraded);
+				const merged = mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length)));
+				const userStore = await deps.openStore("user");
+				const projectStore = await deps.openStore("project");
+				const poolLookup = async (id) => await userStore.get(id) ?? await projectStore.get(id);
+				const route = await planTour(merged, poolLookup, input.query, maxStops);
+				return { text: `${degraded ? "（语义嵌入不可用，仅关键词检索）\n" : ""}${route.narrative}` };
+			}
+		}),
+		auditForgotten
+	];
+}
+/**
+* 构造巡游路径：在 search 命中的基础上按路径策略重排。
+* 1) 起点簇：取命中中 kind 出现频次最高的前 N 个同 kind 节点（同类巩固）。
+* 2) 走廊扩展：从起点簇每个节点的 1-跳 neighbors 中挑 active 且 score > 0 的房间。
+* 3) 反差收束：从剩余命中挑一个 emotionalValence ≥ 0.7 的做收束（强反差唤醒）。
+* 命中不足时按可用性回退；命中为 0 时返回空 stops。
+*/
+async function planTour(hits, poolLookup, query, maxStops = 6) {
+	if (hits.length === 0) return {
+		stops: [],
+		narrative: "无命中，无巡游路径可规划。",
+		query
+	};
+	const used = /* @__PURE__ */ new Set();
+	const stops = [];
+	const kindCounts = /* @__PURE__ */ new Map();
+	for (const hit of hits) kindCounts.set(hit.record.kind, (kindCounts.get(hit.record.kind) ?? 0) + 1);
+	const topKinds = [...kindCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 2).map(([kind]) => kind);
+	for (const kind of topKinds) for (const hit of hits) {
+		if (stops.length >= maxStops) break;
+		if (hit.record.kind !== kind || used.has(hit.record.id)) continue;
+		stops.push({
+			record: hit.record,
+			reason: "same-kind"
+		});
+		used.add(hit.record.id);
+	}
+	for (const stop of [...stops]) {
+		if (stops.length >= maxStops - 1) break;
+		await poolLookup(stop.record.id);
+		for (const hit of hits) {
+			if (stops.length >= maxStops - 1) break;
+			if (used.has(hit.record.id) || hit.record.id === stop.record.id) continue;
+			if (hit.record.scope !== stop.record.scope) continue;
+			stops.push({
+				record: hit.record,
+				reason: "neighbor"
+			});
+			used.add(hit.record.id);
+		}
+	}
+	const emotionCut = hits.find((hit) => !used.has(hit.record.id) && (hit.record.imagery?.emotionalValence ?? 0) >= .7);
+	if (emotionCut !== void 0 && stops.length < maxStops) {
+		stops.push({
+			record: emotionCut.record,
+			reason: "emotional-peak"
+		});
+		used.add(emotionCut.record.id);
+	}
+	for (const hit of hits) {
+		if (stops.length >= maxStops) break;
+		if (used.has(hit.record.id)) continue;
+		stops.push({
+			record: hit.record,
+			reason: "contrast"
+		});
+		used.add(hit.record.id);
+	}
+	return {
+		stops,
+		narrative: renderTourNarrative(stops, query),
+		query
+	};
+}
+/** 把巡游路径渲染为一段含回声触发器的可读文本（供 engram_tour 的 text 字段）。 */
+function renderTourNarrative(stops, query) {
+	if (stops.length === 0) return "无巡游路径。";
+	const reasonLabel = (reason) => {
+		switch (reason) {
+			case "same-kind": return "同类巩固";
+			case "neighbor": return "走廊相邻";
+			case "contrast": return "反差补位";
+			case "emotional-peak": return "情绪强反差";
+		}
+	};
+	const lines = [`巡游路径（查询：${query}）：按「同类巩固 → 走廊相邻 → 反差补位」顺序组织，共 ${stops.length} 站。`];
+	stops.forEach((stop, index) => {
+		const caption = stop.record.imagery?.caption;
+		const sensory = stop.record.imagery?.sensoryTags ?? [];
+		const echo = caption === null || caption === void 0 ? "（未铭刻意象，请先调用 engram_examine 读铭牌）" : `回声：似曾「${caption}」${sensory.length > 0 ? `（${sensory.slice(0, 3).join("、")}）` : ""}`;
+		lines.push(`${index + 1}. [${stop.record.scope}/${stop.record.kind}] ${stop.record.content.slice(0, 60)}${stop.record.content.length > 60 ? "…" : ""}（id=${stop.record.id}，理由：${reasonLabel(stop.reason)}）— ${echo}`);
+	});
+	return lines.join("\n");
+}
+//#endregion
+//#region src/selection-rationale.ts
+/** 给定一组入选房间，返回归因 XML 字符串；空 rooms 返回空串。 */
+function buildSelectionRationale(records) {
+	if (records.length === 0) return "";
+	const now = Date.now();
+	const lines = [
+		"<engram_selection_rationale>",
+		`本轮画像共 ${String(records.length)} 间房间，挑选理由如下：`,
+		""
 	];
+	for (const record of records) {
+		const reasons = classifyRecord(record, now);
+		lines.push(`- #${record.id.slice(0, 8)} [${record.kind}/${record.scope}] ${reasonsLabel(reasons)}：${record.content.slice(0, 40)}${record.content.length > 40 ? "…" : ""}`);
+	}
+	lines.push("", "如果某条理由错误，请通过 engram_report 反馈，越准的画像越能帮你。", "</engram_selection_rationale>");
+	return lines.join("\n");
+}
+/** 把画像正文 + 归因拼成最终注入文本。 */
+function wrapWithRationale(profileText, records) {
+	const rationale = buildSelectionRationale(records);
+	return rationale === "" ? profileText : `${rationale}\n\n${profileText}`;
+}
+/** 启发式：4 类原因按阈值判定，可叠加。 */
+function classifyRecord(record, now) {
+	const reasons = [];
+	if (now - record.lastAccessedAt < 6048e5) reasons.push("recent");
+	if (record.importance * record.confidence >= .7) reasons.push("bright");
+	if (record.accessCount >= 5) reasons.push("corridor-hit");
+	if (record.outcome === "success") reasons.push("strong-evidence");
+	return reasons;
+}
+/** 中文/英文 reason 标签。 */
+function reasonsLabel(reasons) {
+	if (reasons.length === 0) return "基础入选";
+	const LABELS = {
+		recent: "近期被参观",
+		bright: "地标明亮",
+		"corridor-hit": "走廊常客",
+		"strong-evidence": "管家验证有效"
+	};
+	return reasons.map((r) => LABELS[r]).join(" / ");
 }
 //#endregion
 //#region src/index.ts
 /**
 * dsh-engram：DeepSeek Harness 跨会话长期记忆插件（host 半）。
-* 注册 9 个 engram_ 工具、会话开始注入用户画像、自动摄取上一轮对话、
+* 注册 10 个 engram_ 工具、会话开始注入用户画像、自动摄取上一轮对话、
 * 蒸馏/衰减飞轮与审计能力。
 * @module @kenz1117/dsh-engram
 */
 /** Cordis 插件名（loader 诊断与注入 source 使用）。 */
 const name = "dsh-engram";
+/** 插件版本（与 package.json 同步，写进备份 _meta.json）。 */
+const VERSION = "0.7.0";
 /** 必需服务：工具注册表与 LLM 流式端点（摄取/蒸馏的辅助调用）。 */
 const inject = ["tools", "llm"];
 /**
@@ -2504,9 +4202,9 @@ const inject = ["tools", "llm"];
 * 索引行也装不下的折成末尾 `+N more; use engram_search` 计数行。
 * @param records - 候选条目（调用方已按重要性排序、按条数截断）。
 * @param tokenBudget - 整段画像的 token 预算（含首尾固定行）。
-* @returns 注入文本。
+* @returns 渲染文本与溢出条目（调用方可用辅助 LLM 压缩后重渲染）。
 */
-function renderProfile(records, tokenBudget) {
+function renderProfileDetailed(records, tokenBudget) {
 	const estimate = (text) => Math.ceil(text.length / 4);
 	const header = "User memory profile (dsh-engram, cross-session):";
 	const footer = "Use engram_search to recall details; use engram_save to persist new facts.";
@@ -2531,16 +4229,76 @@ function renderProfile(records, tokenBudget) {
 		} else more += 1;
 	}
 	if (more > 0) lines.push(`+${more} more; use engram_search`);
-	return [
-		header,
-		...lines,
-		footer
-	].join("\n");
+	return {
+		text: [
+			header,
+			...lines,
+			footer
+		].join("\n"),
+		overflow
+	};
+}
+/**
+* 会话开始注入的画像渲染（只取文本；溢出明细见 renderProfileDetailed）。
+* @param records - 候选条目（调用方已按重要性排序、按条数截断）。
+* @param tokenBudget - 整段画像的 token 预算（含首尾固定行）。
+* @returns 注入文本。
+*/
+function renderProfile(records, tokenBudget) {
+	return renderProfileDetailed(records, tokenBudget).text;
+}
+/** 压缩辅助调用的输出 token 上限（40 字 × 若干条，短输出足够）。 */
+const COMPRESS_MAX_TOKENS = 800;
+/** 压缩辅助调用超时：压缩在 pre-step 关键路径上，必须限时防阻塞首轮请求。 */
+const COMPRESS_TIMEOUT_MS = 8e3;
+const COMPRESS_SYSTEM = [
+	"把记忆条目压缩为更短的一句话表述（每条不超过 40 个字符），保留可跨会话复用的关键信息（事实、偏好、决策、方法）。",
+	"只输出一个 JSON 数组，每项形如 {\"id\": \"原样返回的id\", \"content\": \"压缩后表述\"}，条目数量与 id 必须与输入一一对应。",
+	"不要输出 JSON 以外的任何内容。"
+].join("\n");
+/**
+* 画像超预算的辅助压缩：把装不下的条目交给辅助 LLM 压短，返回 id → 压缩文本。
+* 任何失败（无路由、输出不可解析、超时、调用异常）返回 undefined，调用方
+* 降级回索引行装填。压缩请求审计到 user 库 op_log（model-visible ⟺ logged：
+* 压缩产物本身会随注入消息进会话日志）。
+*/
+async function compressProfileOverflow(ctx, agent, routeOverride, overflow, signal) {
+	try {
+		const events = agent.session.snapshotEvents();
+		const route = routeOverride ?? routeFromEvents(events);
+		if (route === void 0) return void 0;
+		const userText = JSON.stringify(overflow.map((record) => ({
+			id: record.id,
+			content: record.content
+		})));
+		const parsed = parseJsonArray(await streamText(ctx, {
+			route,
+			system: COMPRESS_SYSTEM,
+			userText,
+			maxTokens: COMPRESS_MAX_TOKENS,
+			purpose: "engram-compress",
+			sessionId: agent.session.id,
+			signal: AbortSignal.any([signal, AbortSignal.timeout(COMPRESS_TIMEOUT_MS)])
+		}));
+		if (parsed === void 0) return void 0;
+		const ids = new Set(overflow.map((record) => record.id));
+		const compressed = /* @__PURE__ */ new Map();
+		for (const item of parsed) {
+			const entry = item;
+			if (typeof entry.id !== "string" || typeof entry.content !== "string") continue;
+			if (!ids.has(entry.id) || entry.content.trim() === "" || entry.content.length >= overflow.find((record) => record.id === entry.id).content.length) continue;
+			compressed.set(entry.id, entry.content.trim());
+		}
+		return compressed.size > 0 ? compressed : void 0;
+	} catch {
+		return;
+	}
 }
 /**
-* agent/pre-step waterfall：每轮第一步注入画像；同时 fire-and-forget 触发
-* 上一轮的自动摄取（不阻塞请求）；进程内首次第一步重放待补做的末轮摄取。
-* 必须调用 next() 委托链路；reject 决策原样透传，记忆库为空或非首轮时不追加消息。
+* agent/pre-step waterfall：每轮第一步注入画像（内容与上次相同则跳过重复注入）；
+* 同时 fire-and-forget 触发上一轮的自动摄取（不阻塞请求）；进程内首次第一步
+* 重放待补做的末轮摄取。必须调用 next() 委托链路；reject 决策原样透传，
+* 记忆库为空或非首轮时不追加消息。
 */
 async function preStep(ctx, openStore, resolved, embedder, state, logRequest, { agent, step, turn, signal }, next) {
 	const decision = await next();
@@ -2566,7 +4324,7 @@ async function preStep(ctx, openStore, resolved, embedder, state, logRequest, {
 			});
 		}
 		if (turn > 1) ingestPreviousTurn({
-			events: agent.session.events,
+			events: agent.session.snapshotEvents(),
 			sessionId: String(agent.id),
 			turn,
 			openStore: () => openStore("user"),
@@ -2586,7 +4344,27 @@ async function preStep(ctx, openStore, resolved, embedder, state, logRequest, {
 	if (step !== 1) return decision;
 	const top = await (await openStore("user")).topActive("user", resolved.profileTopN);
 	if (top.length === 0) return decision;
-	const packet = renderMemoryPacket(renderProfile(top, resolved.injectTokenBudget), "turn_start", currentUserRequestText(decision.messages));
+	const detailed = renderProfileDetailed(top, resolved.injectTokenBudget);
+	let text = detailed.text;
+	if (detailed.overflow.length > 0) {
+		const compressed = await compressProfileOverflow(ctx, agent, resolved.routeOverride, detailed.overflow, signal);
+		if (compressed !== void 0) {
+			openStore("user").then((auditStore) => auditStore.audit("compress-request", "AUX", JSON.stringify({ count: detailed.overflow.length }))).catch(() => {});
+			text = renderProfileDetailed(top.map((record) => {
+				const shorter = compressed.get(record.id);
+				return shorter === void 0 ? record : {
+					...record,
+					content: shorter
+				};
+			}), resolved.injectTokenBudget).text;
+		}
+	}
+	const textWithRationale = wrapWithRationale(text, top);
+	const hash = createHash("sha256").update(textWithRationale).digest("hex");
+	if (state.lastProfileAgent === String(agent.id) && hash === state.lastProfileHash) return decision;
+	state.lastProfileAgent = String(agent.id);
+	state.lastProfileHash = hash;
+	const packet = renderMemoryPacket(text, "turn_start", currentUserRequestText(decision.messages));
 	return {
 		...decision,
 		messages: [...decision.messages, createUserMessage({
@@ -2613,7 +4391,7 @@ async function preStep(ctx, openStore, resolved, embedder, state, logRequest, {
 */
 function makeEventResolver(ctx, agent) {
 	return async (sessionId) => {
-		if (sessionId === String(agent.id)) return agent.session.events;
+		if (sessionId === String(agent.id)) return agent.session.snapshotEvents();
 		const persistence = ctx.get("sessionPersistence");
 		if (persistence === void 0) return void 0;
 		try {
@@ -2624,7 +4402,7 @@ function makeEventResolver(ctx, agent) {
 	};
 }
 /**
-* 插件体：预热分库与嵌入器，注册 9 个工具、画像注入、自动摄取与衰减调度。
+* 插件体：预热分库与嵌入器，注册 10 个工具、画像注入、自动摄取与衰减调度。
 * @param ctx - host 上下文。
 * @param config - cordis.yml 传入的可选配置；非法值在加载时 loud 失败。
 */
@@ -2647,7 +4425,7 @@ function apply(ctx, config = {}) {
 	const openStore = (scope) => {
 		const existing = stores.get(scope);
 		if (existing !== void 0) return existing;
-		const created = openEngramStore(scope === "user" ? join(resolved.dbDir, "user.db") : join(resolved.dbDir, identity.dbName), rankBoost);
+		const created = openEngramStore(scope === "user" ? join(resolved.dbDir, "user.db") : scope === "shared" ? join(resolved.dbDir, "shared.db") : join(resolved.dbDir, identity.dbName), rankBoost);
 		stores.set(scope, created);
 		return created;
 	};
@@ -2668,21 +4446,29 @@ function apply(ctx, config = {}) {
 	ctx.inject(["webServer"], (webCtx) => {
 		registerEngramRoutes(webCtx, {
 			openStore,
-			exportDir: `${resolved.dbDir}/exports`
+			exportDir: `${resolved.dbDir}/exports`,
+			mirrorDir: `${resolved.dbDir}/palaces`,
+			dbDir: resolved.dbDir,
+			pluginVersion: VERSION,
+			embedder
 		});
 	});
 	const logIngestRequest = (data) => {
 		openStore("user").then((store) => store.audit("ingest-request", "AUX", JSON.stringify(data))).catch(() => {});
 	};
 	if (resolved.injectProfile || resolved.ingest !== "off") {
-		const state = { pendingReplayed: false };
+		const state = {
+			pendingReplayed: false,
+			lastProfileAgent: null,
+			lastProfileHash: null
+		};
 		ctx.on("agent/pre-step", (payload, next) => preStep(ctx, openStore, resolved, embedder, state, logIngestRequest, payload, next), { prepend: true });
 	}
 	if (resolved.ingest !== "off") ctx.on("session/disposed", (session) => {
 		const mode = resolved.ingest;
 		if (mode === "off") return;
 		ingestFinalTurn({
-			events: session.events,
+			events: session.snapshotEvents(),
 			sessionId: String(session.id),
 			turn: 0,
 			slice: "last",
@@ -2720,6 +4506,26 @@ function apply(ctx, config = {}) {
 			clearInterval(timer);
 		};
 	}, "dsh-engram: decay timer");
+	const runConsolidateOnce = async () => {
+		try {
+			const report = await runConsolidation(await openStore("user"), embedder, {
+				olderThanDays: resolved.decayAfterDays,
+				importanceBelow: resolved.decayImportanceBelow
+			});
+			console.log(`[dsh-engram] 闭馆整理完成：归档 ${String(report.archived)}，合并 ${String(report.merged)}，跳过 ${String(report.skipped)}（${String(report.tookMs)} ms）`);
+		} catch (error) {
+			console.warn("[dsh-engram] 闭馆整理失败（不影响对话）：", error);
+		}
+	};
+	runConsolidateOnce();
+	ctx.effect(() => {
+		const timer = setInterval(() => {
+			runConsolidateOnce();
+		}, 864e5);
+		return () => {
+			clearInterval(timer);
+		};
+	}, "dsh-engram: consolidation timer");
 }
 //#endregion
-export { Config, apply, inject, name, renderProfile };
+export { Config, VERSION, apply, inject, name, renderProfile, renderProfileDetailed };