@kenz1117/dsh-engram 0.7.9 → 0.7.12

package/lib/index.js

@@ -42,7 +42,8 @@ const CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"historyBackfillMaxTotalTurns",
 	"historyBackfillIncludeSubagents",
 	"historyBackfillIncludeSeeded",
-	"historyBackfillIncludeNoCwd"
+	"historyBackfillIncludeNoCwd",
+	"jev"
 ]);
 const INGEST_MODES = /* @__PURE__ */ new Set([
 	"off",
@@ -77,7 +78,17 @@ const Config = z.object({
 	historyBackfillMaxTotalTurns: z.number().step(1).min(1).max(5e3),
 	historyBackfillIncludeSubagents: z.boolean(),
 	historyBackfillIncludeSeeded: z.boolean(),
-	historyBackfillIncludeNoCwd: z.boolean()
+	historyBackfillIncludeNoCwd: z.boolean(),
+	jev: z.object({
+		enabled: z.boolean(),
+		apiKey: z.string(),
+		baseUrl: z.string(),
+		model: z.string(),
+		timeoutMs: z.number().step(1).min(1e3).max(6e4),
+		deferMergeAbove: z.number().min(.5).max(1),
+		deferAcceptBelow: z.number().min(0).max(.5),
+		contradictMinProbability: z.number().min(.5).max(1)
+	})
 });
 /**
 * 显式 resolve 步骤：默认值只在唯一的此处落地，非法值 loud 失败。
@@ -106,6 +117,16 @@ function resolveConfig(config = {}) {
 	if (config.historyBackfillDays !== void 0 && (!Number.isInteger(config.historyBackfillDays) || config.historyBackfillDays < 0 || config.historyBackfillDays > 3650)) throw new Error("dsh-engram: historyBackfillDays must be an integer in [0, 3650] (0 = unlimited)");
 	if (config.historyBackfillMaxTurnsPerSession !== void 0 && (!Number.isInteger(config.historyBackfillMaxTurnsPerSession) || config.historyBackfillMaxTurnsPerSession < 1 || config.historyBackfillMaxTurnsPerSession > 500)) throw new Error("dsh-engram: historyBackfillMaxTurnsPerSession must be an integer in [1, 500]");
 	if (config.historyBackfillMaxTotalTurns !== void 0 && (!Number.isInteger(config.historyBackfillMaxTotalTurns) || config.historyBackfillMaxTotalTurns < 1 || config.historyBackfillMaxTotalTurns > 5e3)) throw new Error("dsh-engram: historyBackfillMaxTotalTurns must be an integer in [1, 5000]");
+	const jev = config.jev;
+	if (jev !== void 0) {
+		if (jev.enabled !== void 0 && typeof jev.enabled !== "boolean") throw new Error("dsh-engram: jev.enabled must be a boolean");
+		if (jev.enabled === true && (jev.apiKey === void 0 || jev.apiKey === "")) throw new Error("dsh-engram: jev.enabled=true requires jev.apiKey");
+		if (jev.timeoutMs !== void 0 && (!Number.isInteger(jev.timeoutMs) || jev.timeoutMs < 1e3 || jev.timeoutMs > 6e4)) throw new Error("dsh-engram: jev.timeoutMs must be an integer in [1000, 60000]");
+		if (jev.deferMergeAbove !== void 0 && (jev.deferMergeAbove < .5 || jev.deferMergeAbove > 1)) throw new Error("dsh-engram: jev.deferMergeAbove must be in [0.5, 1]");
+		if (jev.deferAcceptBelow !== void 0 && (jev.deferAcceptBelow < 0 || jev.deferAcceptBelow > .5)) throw new Error("dsh-engram: jev.deferAcceptBelow must be in [0, 0.5]");
+		if (jev.contradictMinProbability !== void 0 && (jev.contradictMinProbability < .5 || jev.contradictMinProbability > 1)) throw new Error("dsh-engram: jev.contradictMinProbability must be in [0.5, 1]");
+		if ((jev.deferAcceptBelow ?? .15) >= (jev.deferMergeAbove ?? .85)) throw new Error("dsh-engram: jev.deferAcceptBelow must be less than jev.deferMergeAbove");
+	}
 	const dbDir = config.dbDir ?? join(homedir(), ".dsh", "engram");
 	return {
 		dbDir,
@@ -138,6 +159,16 @@ function resolveConfig(config = {}) {
 			includeSubagents: config.historyBackfillIncludeSubagents ?? false,
 			includeSeeded: config.historyBackfillIncludeSeeded ?? false,
 			includeNoCwd: config.historyBackfillIncludeNoCwd ?? false
+		},
+		jev: {
+			enabled: config.jev?.enabled ?? false,
+			apiKey: config.jev?.apiKey,
+			baseUrl: config.jev?.baseUrl ?? "https://api.typesafe.ai",
+			model: config.jev?.model ?? "jev-latest",
+			timeoutMs: config.jev?.timeoutMs ?? 3e3,
+			deferMergeAbove: config.jev?.deferMergeAbove ?? .85,
+			deferAcceptBelow: config.jev?.deferAcceptBelow ?? .15,
+			contradictMinProbability: config.jev?.contradictMinProbability ?? .8
 		}
 	};
 }
@@ -147,6 +178,18 @@ function resolveConfig(config = {}) {
 function asMemoryId(raw) {
 	return raw;
 }
+/** 从任意字符串铸造品牌化实体 id（存储层入库前调用）。 */
+function asEntityId(raw) {
+	return raw;
+}
+/** 从任意字符串铸造品牌化事实 id（存储层入库前调用）。 */
+function asFactId(raw) {
+	return raw;
+}
+/** 归一化比较键：trim + 合并连续空白 + 小写（消解第一版只做精确归一匹配，不做相似合并）。 */
+function normalizeEntityName(raw) {
+	return raw.trim().replace(/\s+/g, " ").toLowerCase();
+}
 /** episode 情景时间线的时间邻近扩展缺省窗口：锚点 createdAt ± 60 分钟。 */
 const EPISODE_PROXIMITY_MS_DEFAULT = 36e5;
 /** dsh-engram 统一错误：加载/使用期的可诊断失败都抛此类型。 */
@@ -503,15 +546,75 @@ function omitRecallToolResults(events) {
 		};
 	});
 }
+//#endregion
+//#region src/jev/observe.ts
+/** 缓冲容量：足够回看一次摄取批次，同时封顶内存占用。 */
+const CAPACITY = 50;
+const buffer = [];
+/** 追加一条观测；超出容量丢弃最旧记录。 */
+function recordJevObservation(observation) {
+	buffer.push(observation);
+	if (buffer.length > CAPACITY) buffer.shift();
+}
+/** 按时间正序返回全部观测（最新在末尾）；返回副本，调用方改动不影响缓冲。 */
+function listJevObservations() {
+	return [...buffer];
+}
+/**
+* 模糊带的 Jev 三路裁决。
+* @returns 高置信同 → merge；高置信异 → accept；低置信、答案缺失或 judge 抛错 → undefined（保持 defer）。
+*/
+async function resolveBand(judge, neighbor, similarity, kind, content) {
+	const startedAt = Date.now();
+	try {
+		const p = (await judge.ask(`Memory A:\n${neighbor.content}\n\nMemory B:\n${content}`, [{
+			id: "same_memory",
+			instructions: `Are Memory A and Memory B the same fact, i.e. restatements of one identical statement (both are "${kind}" memories)? Answer true only for genuine restatements.`
+		}]))["same_memory"];
+		recordJevObservation({
+			at: startedAt,
+			site: "band",
+			question: "same_memory",
+			answered: p !== void 0,
+			probability: p,
+			elapsedMs: Date.now() - startedAt,
+			error: void 0,
+			verdict: p === void 0 ? "fallback" : p >= judge.deferMergeAbove ? "merge" : p <= judge.deferAcceptBelow ? "accept" : "defer"
+		});
+		if (p === void 0) return void 0;
+		if (p >= judge.deferMergeAbove) return {
+			disposition: "merge",
+			into: neighbor,
+			similarity
+		};
+		if (p <= judge.deferAcceptBelow) return { disposition: "accept" };
+		return;
+	} catch (error) {
+		recordJevObservation({
+			at: startedAt,
+			site: "band",
+			question: "same_memory",
+			answered: false,
+			probability: void 0,
+			elapsedMs: Date.now() - startedAt,
+			error: error instanceof Error ? error.message : String(error),
+			verdict: "fallback"
+		});
+		return;
+	}
+}
 /**
 * 判定一条新内容的处置。
 * 嵌入不可用 / 库内无向量条目 / 最近邻低于 DEFER_COSINE → accept；
-* 最近邻同 kind 且 ≥ MERGE_COSINE → merge；其余达到 DEFER_COSINE 的 → defer。
+* 最近邻同 kind 且 ≥ MERGE_COSINE → merge；
+* 其余达到 DEFER_COSINE 的进模糊带：注入 judge 时自动裁决（高置信同 → merge、
+* 高置信异 → accept、低置信或失败 → defer）；未注入 judge → defer（纯规则原行为）。
 * @param store - 目标分库
 * @param kind - 新内容的记忆种类（MERGE 要求同 kind，跨 kind 高度相似按 defer 处理）
 * @param embedding - 新内容的向量；undefined = 嵌入不可用，直接 accept
+* @param options - 可选 judge 注入；judge 与 content 齐备时模糊带走自动裁决
 */
-async function decideWrite(store, kind, embedding) {
+async function decideWrite(store, kind, embedding, options = {}) {
 	if (embedding === void 0) return { disposition: "accept" };
 	const nearest = await store.nearestNeighbor(embedding);
 	if (nearest === void 0 || nearest.similarity < .88) return { disposition: "accept" };
@@ -520,6 +623,11 @@ async function decideWrite(store, kind, embedding) {
 		into: nearest.record,
 		similarity: nearest.similarity
 	};
+	const { judge, content } = options;
+	if (judge !== void 0 && content !== void 0) {
+		const verdict = await resolveBand(judge, nearest.record, nearest.similarity, kind, content);
+		if (verdict !== void 0) return verdict;
+	}
 	return {
 		disposition: "defer",
 		neighbor: nearest.record,
@@ -527,6 +635,51 @@ async function decideWrite(store, kind, embedding) {
 	};
 }
 /**
+* Jev 矛盾确认：对候选逐个问「真矛盾吗」，只保留概率达标的候选。
+* @param judge - Jev 判断器
+* @param incoming - 新写入内容原文
+* @param candidates - 矛盾候选（摄取链路的 defer 最近邻 / 工具链路的 findContradictions 结果）
+* @returns 达标候选数组；judge 抛错时返回 undefined，调用方按旧行为（全量建边）降级。
+*/
+async function confirmContradictions(judge, incoming, candidates) {
+	try {
+		return (await Promise.all(candidates.map(async (candidate) => {
+			const startedAt = Date.now();
+			try {
+				const p = (await judge.ask(`Memory A:\n${candidate.content}\n\nMemory B:\n${incoming}`, [{
+					id: "contradicts",
+					instructions: "Do Memory A and Memory B state facts that cannot both be true at the same time (a genuine contradiction)?"
+				}]))["contradicts"];
+				recordJevObservation({
+					at: startedAt,
+					site: "contradiction",
+					question: "contradicts",
+					answered: p !== void 0,
+					probability: p,
+					elapsedMs: Date.now() - startedAt,
+					error: void 0,
+					verdict: p === void 0 ? "fallback" : p >= judge.contradictMinProbability ? "confirm" : "reject"
+				});
+				return p !== void 0 && p >= judge.contradictMinProbability ? candidate : void 0;
+			} catch (error) {
+				recordJevObservation({
+					at: startedAt,
+					site: "contradiction",
+					question: "contradicts",
+					answered: false,
+					probability: void 0,
+					elapsedMs: Date.now() - startedAt,
+					error: error instanceof Error ? error.message : String(error),
+					verdict: "fallback"
+				});
+				throw error;
+			}
+		}))).filter((c) => c !== void 0);
+	} catch {
+		return;
+	}
+}
+/**
 * MERGE 落地：强化既有条目（accessCount+1 / confidence+0.05）并记 write-merge 审计行。
 * @returns 强化后的既有条目；目标在并发窗口内被物理清除时抛错（loud，调用方按写入失败处理）。
 */
@@ -579,11 +732,71 @@ function decodeTurnKey(detail) {
 }
 const INGEST_SYSTEM = [
 	"从对话记录中提取值得跨会话长期记住的用户信息（事实/偏好/决策/经历/做事方法）。",
-	"只输出一个 JSON 数组，每项形如 {\"content\": \"一句话完整表述\", \"kind\": \"fact|preference|decision|episode|skill\", \"scope\": \"project|user\", \"importance\": 0到1的小数}。",
+	"只输出一个 JSON 数组，每项形如 {\"content\": \"一句话完整表述\", \"kind\": \"fact|preference|decision|episode|skill\", \"scope\": \"project|user\", \"importance\": 0到1的小数, \"entities\": [{\"name\": \"实体名\", \"kind\": \"person|project|tool|concept|other\", \"aliases\": [\"别名\"]}], \"facts\": [{\"entity\": \"实体名\", \"content\": \"关于该实体的一句话事实\"}]}。",
+	"entities 是这条记忆里提到的具体对象（人名/项目名/工具名/概念名），没有就省略该字段；实体名要短（专名本身，不超过 20 字），aliases 列出该实体的其他叫法，没有就省略。",
+	"facts 列出这条记忆中关于具体实体的客观事实（状态/归属/关系/数据），entity 必须取该条 entities 里出现过的实体名，一条一个知识点，没有就省略该字段。",
 	"scope 决定这条记忆进哪座宫殿：只跟当前项目/仓库有关的（技术选型、项目约定、架构决策、该项目自身的事实）用 project；与具体项目无关、跨项目通用的（个人偏好、习惯、用户本人的经历、通用事实）用 user。拿不准用 project。",
 	"只提取明确、可复用的信息；寒暄、临时上下文、你自己的回答不要提取。没有值得记的就输出 []。",
 	"不要输出 JSON 以外的任何内容。"
 ].join("\n");
+/** 实体提及 kind 的合法值集合（模型输出边界校验用）。 */
+const ENTITY_KINDS = [
+	"person",
+	"project",
+	"tool",
+	"concept",
+	"other"
+];
+/** 单个实体名的长度上限（专名本身，防止把整句话当实体）。 */
+const ENTITY_NAME_MAX = 80;
+/** 单条事实陈述的长度上限（一句话）。 */
+const FACT_CONTENT_MAX = 500;
+/**
+* 解析模型输出的 entities 字段为合法提及列表。模型输出是不可信边界：
+* 非数组、元素缺 name、name 清洗后为空或超长的条目一律丢弃，kind 非法回退 other。
+*/
+function parseEntityMentions(raw) {
+	if (!Array.isArray(raw)) return [];
+	const mentions = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) continue;
+		const record = item;
+		if (typeof record.name !== "string") continue;
+		const name = record.name.trim();
+		if (name === "" || name.length > ENTITY_NAME_MAX) continue;
+		const kind = ENTITY_KINDS.includes(record.kind) ? record.kind : "other";
+		const aliases = Array.isArray(record.aliases) ? record.aliases.filter((a) => typeof a === "string" && a.trim() !== "" && a.trim().length <= ENTITY_NAME_MAX) : [];
+		mentions.push({
+			name,
+			kind,
+			...aliases.length === 0 ? {} : { aliases }
+		});
+	}
+	return mentions;
+}
+/**
+* 解析模型输出的 facts 字段为合法事实提及列表。模型输出是不可信边界：
+* 非数组、元素缺 entity/content、清洗后为空或超长的条目一律丢弃。
+* entity 与同批实体名的对应关系由写入路径按归一化名匹配（匹配不上整条丢弃）。
+*/
+function parseFactMentions(raw) {
+	if (!Array.isArray(raw)) return [];
+	const mentions = [];
+	for (const item of raw) {
+		if (typeof item !== "object" || item === null) continue;
+		const record = item;
+		if (typeof record.entity !== "string" || typeof record.content !== "string") continue;
+		const entity = record.entity.trim();
+		const content = record.content.trim();
+		if (entity === "" || entity.length > ENTITY_NAME_MAX) continue;
+		if (content === "" || content.length > FACT_CONTENT_MAX) continue;
+		mentions.push({
+			entity,
+			content
+		});
+	}
+	return mentions;
+}
 /**
 * 组装一次摄取的写入路由：会话有 cwd（可归属项目）时默认进项目宫殿且采纳模型的逐条判定，
 * 明显跨项目的个人偏好可被标成 user 落私人宫殿；无 cwd 的会话只能进私人宫殿，
@@ -855,14 +1068,38 @@ async function ingestPreviousTurn(deps) {
 		const scope = deps.perCandidateScope === true && modelScope !== void 0 ? modelScope : deps.writeScope ?? "user";
 		const target = deps.resolveStore === void 0 ? store : await deps.resolveStore(scope);
 		const importance = typeof candidate.importance === "number" && Number.isFinite(candidate.importance) ? Math.min(1, Math.max(0, candidate.importance)) : .5;
+		const linkEntities = async (nodeId) => {
+			const mentions = parseEntityMentions(candidate.entities);
+			if (mentions.length === 0) return;
+			try {
+				const entities = await target.resolveEntities(mentions);
+				await target.linkNodeEntities(nodeId, entities.map((entity) => entity.id));
+				const factInputs = [];
+				const byName = new Map(entities.map((entity) => [normalizeEntityName(entity.name), entity]));
+				for (const mention of parseFactMentions(candidate.facts)) {
+					const entity = byName.get(normalizeEntityName(mention.entity));
+					if (entity === void 0) continue;
+					factInputs.push({
+						entityId: entity.id,
+						content: mention.content,
+						sourceNodeId: nodeId
+					});
+				}
+				if (factInputs.length > 0) await target.writeFacts(factInputs);
+			} catch {}
+		};
 		if (writtenContents.includes(content)) {
 			dropped += 1;
 			continue;
 		}
 		const vector = embedder === void 0 ? void 0 : (await embedder.embed([content]))[0];
-		const decision = await decideWrite(target, kind, vector);
+		const decision = await decideWrite(target, kind, vector, deps.judge === void 0 ? {} : {
+			judge: deps.judge,
+			content
+		});
 		if (decision.disposition === "merge") {
 			await applyMerge(target, decision, content);
+			await linkEntities(decision.into.id);
 			writtenContents.push(content);
 			merged += 1;
 			continue;
@@ -880,9 +1117,11 @@ async function ingestPreviousTurn(deps) {
 			...deps.history === true ? { initialReviewAt: null } : {}
 		});
 		if (decision.disposition === "defer") {
-			await target.linkEdge(record.id, decision.neighbor.id, "contradicts");
+			const neighbors = deps.judge === void 0 ? [decision.neighbor] : await confirmContradictions(deps.judge, content, [decision.neighbor]) ?? [decision.neighbor];
+			for (const neighbor of neighbors) await target.linkEdge(record.id, neighbor.id, "contradicts");
 			deferred += 1;
 		}
+		await linkEntities(record.id);
 		writtenContents.push(content);
 		written += 1;
 	}
@@ -1022,6 +1261,7 @@ async function replayPendingIngests(deps) {
 			routeOverride: deps.routeOverride,
 			call: deps.call,
 			logRequest: deps.logRequest,
+			...deps.judge === void 0 ? {} : { judge: deps.judge },
 			signal: deps.signal
 		});
 		await store.clearAudit(INGEST_PENDING_OP, detail);
@@ -1280,6 +1520,7 @@ async function runHistoryBackfill(deps, defaults, overrides, onProgress, signal)
 					routeOverride,
 					call: deps.call,
 					logRequest: deps.logRequest,
+					...deps.judge === void 0 ? {} : { judge: deps.judge },
 					signal,
 					throttle: true,
 					history: true
@@ -1472,6 +1713,217 @@ function cosine$1(a, b) {
 	return denom === 0 ? 0 : dot / denom;
 }
 //#endregion
+//#region src/jev/client.ts
+/**
+* 调用 Jev /v1/systemone 端点并行回答 Noul 问题。
+* @param config - 已解析的 Jev 子配置（调用方先判 enabled）。
+* @param state - 待判断的状态文本（如两条记忆正文的对照）。
+* @param questions - Noul 问题列表；空列表直接返回空结果，不发请求。
+* @param signal - 外部取消信号；与配置超时信号合并监听，超时按配置 timeoutMs 兜底。
+* @returns 问题 id → Noul 概率（0-1，数字即信念）。
+* @throws 网络、非 2xx、响应缺 answers、答案缺失或非 0-1 数字时抛错。
+*/
+async function askNoul(config, state, questions, signal = new AbortController().signal) {
+	if (questions.length === 0) return {};
+	const response = await fetch(new URL("/v1/systemone", config.baseUrl), {
+		method: "POST",
+		headers: {
+			Authorization: `Bearer ${config.apiKey ?? ""}`,
+			"Content-Type": "application/json"
+		},
+		body: JSON.stringify({
+			model: config.model,
+			state,
+			questions: Object.fromEntries(questions.map((question) => [question.id, {
+				type: "noul",
+				instructions: question.instructions
+			}]))
+		}),
+		signal: AbortSignal.any([signal, AbortSignal.timeout(config.timeoutMs)])
+	});
+	if (!response.ok) throw new Error(`jev: HTTP ${response.status} from ${config.baseUrl}`);
+	const payload = await response.json();
+	if (payload.answers === void 0 || payload.answers === null) throw new Error("jev: response missing answers");
+	const result = {};
+	for (const question of questions) {
+		const noul = payload.answers[question.id]?.noul;
+		if (typeof noul !== "number" || !Number.isFinite(noul) || noul < 0 || noul > 1) throw new Error(`jev: answer "${question.id}" is not a noul probability`);
+		result[question.id] = noul;
+	}
+	return result;
+}
+/**
+* 从已解析配置构建可注入摄取与工具链路的判断器。
+* @param config - 已解析的 Jev 子配置（含三阈值）。
+* @returns MemoryJudge 实现；ask 不接收外部取消信号，仅受配置超时约束。
+*/
+function createMemoryJudge(config) {
+	return {
+		deferMergeAbove: config.deferMergeAbove,
+		deferAcceptBelow: config.deferAcceptBelow,
+		contradictMinProbability: config.contradictMinProbability,
+		ask: (state, questions) => askNoul(config, state, questions)
+	};
+}
+/**
+* 连接测试：向端点发一个最小 ping 问题，验证 baseUrl/model/apiKey 三者组合可用。
+* 不抛错——失败原因以 error 字段返回，供面板直接展示。
+* @param config - 待测试的生效配置（enabled 不参与判断；apiKey/baseUrl/model 用调用方给的值）。
+*/
+async function testJevConnection(config) {
+	const startedAt = Date.now();
+	try {
+		const answers = await askNoul(config, "Connectivity test: this state exists.", [{
+			id: "ping",
+			instructions: "This is a connectivity test. Return any probability between 0 and 1."
+		}]);
+		return {
+			ok: true,
+			elapsedMs: Date.now() - startedAt,
+			probability: answers["ping"],
+			error: void 0
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			elapsedMs: Date.now() - startedAt,
+			probability: void 0,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+//#endregion
+//#region src/jev/runtime.ts
+/**
+* Jev 连接配置的运行时覆盖：管理面板保存到 `<dbDir>/jev-config.json`（0600），
+* 字段级覆盖 cordis.yml 的 jev 子配置；装配免缓存——judge 构造是无状态闭包、
+* 覆盖文件是小读，每个装配点即时解析，面板保存后立即生效。
+* 覆盖文件损坏按空覆盖处理：不卡启动，面板重新保存即修复。
+* @module @kenz1117/dsh-engram/jev/runtime
+*/
+/** 覆盖文件路径（dbDir 已 0700，文件本身 0600 双保险）。 */
+function jevOverridePath(dbDir) {
+	return `${dbDir}/jev-config.json`;
+}
+/** 读覆盖文件：缺失/损坏/非法 JSON 都按空覆盖（面板重新保存即修复）。 */
+function loadJevOverride(dbDir) {
+	let raw;
+	try {
+		raw = readFileSync(jevOverridePath(dbDir), "utf8");
+	} catch {
+		return {};
+	}
+	try {
+		return collectOverride(JSON.parse(raw));
+	} catch {
+		return {};
+	}
+}
+/** 收敛未知 JSON 为覆盖对象：只认五个已知字段，类型不符的丢弃。 */
+function collectOverride(value) {
+	if (value === null || typeof value !== "object") return {};
+	const raw = value;
+	return {
+		...typeof raw["enabled"] === "boolean" ? { enabled: raw["enabled"] } : {},
+		...typeof raw["apiKey"] === "string" ? { apiKey: raw["apiKey"] } : {},
+		...typeof raw["baseUrl"] === "string" ? { baseUrl: raw["baseUrl"] } : {},
+		...typeof raw["model"] === "string" ? { model: raw["model"] } : {},
+		...typeof raw["timeoutMs"] === "number" && Number.isInteger(raw["timeoutMs"]) ? { timeoutMs: raw["timeoutMs"] } : {}
+	};
+}
+/** 全量保存覆盖文件（调用方先经 parseJevPatch 校验；内容为面板合并后的完整覆盖）。 */
+function saveJevOverride(dbDir, override) {
+	writeFileSync(jevOverridePath(dbDir), `${JSON.stringify(override, null, 2)}\n`, { mode: 384 });
+}
+/**
+* 面板 patch 解析：只认已知字段并逐个校验，出现非法值整体拒绝。
+* `apiKey: ''` 表示清除面板密钥覆盖（回落 yml）；缺席的字段保留 current。
+* @param current - 现有覆盖（合并底座）。
+* @param patch - POST body 原始对象。
+* @returns 合法时返回合并后的完整覆盖；非法时返回 `invalid:` 前缀的字段错误文案。
+*/
+function parseJevPatch(current, patch) {
+	const merged = { ...current };
+	if (patch["enabled"] !== void 0) {
+		if (typeof patch["enabled"] !== "boolean") return "invalid: jev.enabled 必须是布尔值";
+		merged.enabled = patch["enabled"];
+	}
+	if (patch["apiKey"] !== void 0) {
+		if (typeof patch["apiKey"] !== "string") return "invalid: jev.apiKey 必须是字符串";
+		const trimmed = patch["apiKey"].trim();
+		if (trimmed === "") delete merged.apiKey;
+		else merged.apiKey = trimmed;
+	}
+	if (patch["baseUrl"] !== void 0) {
+		if (typeof patch["baseUrl"] !== "string") return "invalid: jev.baseUrl 必须是字符串";
+		const value = patch["baseUrl"].trim();
+		try {
+			const url = new URL(value);
+			if (url.protocol !== "https:" && url.protocol !== "http:") return "invalid: jev.baseUrl 必须是 http(s) URL";
+		} catch {
+			return "invalid: jev.baseUrl 必须是 http(s) URL";
+		}
+		merged.baseUrl = value;
+	}
+	if (patch["model"] !== void 0) {
+		if (typeof patch["model"] !== "string" || patch["model"].trim() === "") return "invalid: jev.model 不能为空";
+		merged.model = patch["model"].trim();
+	}
+	if (patch["timeoutMs"] !== void 0) {
+		const value = patch["timeoutMs"];
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 1e3 || value > 6e4) return "invalid: jev.timeoutMs 必须是 1000-60000 的整数毫秒";
+		merged.timeoutMs = value;
+	}
+	return merged;
+}
+/**
+* 面板覆盖与 yml 基线的字段级合并；合并后 enabled=true 但无密钥时强制降级
+* enabled=false（与 Jev 不可用静默降级语义一致，不卡启动）。
+*/
+function effectiveJevConfig(base, override) {
+	const apiKey = override.apiKey ?? base.apiKey;
+	const enabled = (override.enabled ?? base.enabled) && apiKey !== void 0 && apiKey !== "";
+	return {
+		enabled,
+		apiKey: enabled ? apiKey : void 0,
+		baseUrl: override.baseUrl ?? base.baseUrl,
+		model: override.model ?? base.model,
+		timeoutMs: override.timeoutMs ?? base.timeoutMs,
+		deferMergeAbove: base.deferMergeAbove,
+		deferAcceptBelow: base.deferAcceptBelow,
+		contradictMinProbability: base.contradictMinProbability
+	};
+}
+/** 密钥掩码：长度 > 8 显示尾 4 位，其余全掩码。 */
+function maskApiKey(key) {
+	return key.length > 8 ? `****${key.slice(-4)}` : "******";
+}
+/** 组装面板视图：基于生效配置；掩码取合并后的密钥。 */
+function jevConfigView(base, override) {
+	const config = effectiveJevConfig(base, override);
+	return {
+		enabled: config.enabled,
+		apiKeySet: config.apiKey !== void 0 && config.apiKey !== "",
+		apiKeyMask: config.apiKey === void 0 || config.apiKey === "" ? null : maskApiKey(config.apiKey),
+		baseUrl: config.baseUrl,
+		model: config.model,
+		timeoutMs: config.timeoutMs,
+		deferMergeAbove: config.deferMergeAbove,
+		deferAcceptBelow: config.deferAcceptBelow,
+		contradictMinProbability: config.contradictMinProbability
+	};
+}
+/**
+* 统一装配函数：读面板覆盖、合并 yml 基线，enabled 时产出 judge，否则返回空对象。
+* 产出形状可直接条件展开进摄取/工具/末轮/回填四类依赖（`...resolveJevField(resolved.jev, dbDir)`）。
+* 免缓存：judge 构造是无状态闭包、覆盖文件是小读，每次调用即时解析，面板保存立即生效。
+*/
+function resolveJevField(base, dbDir) {
+	const config = effectiveJevConfig(base, loadJevOverride(dbDir));
+	if (!config.enabled || config.apiKey === void 0 || config.apiKey === "") return {};
+	return { judge: createMemoryJudge(config) };
+}
+//#endregion
 //#region src/mirror/markdown.ts
 /**
 * Markdown 镜像：把 SQLite 记忆库导出为可被 Obsidian / VS Code / git 直接漫游的
@@ -2267,6 +2719,62 @@ function registerEngramRoutes(ctx, deps) {
 					});
 					return;
 				}
+				if (req.method === "GET" && route === "entities") {
+					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
+					const kind = url.searchParams.get("kind");
+					const q = url.searchParams.get("q");
+					const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit") ?? 50) || 50));
+					const offset = Math.max(0, Number(url.searchParams.get("offset") ?? 0) || 0);
+					json(res, 200, {
+						scope,
+						...await (await storeFor(scope)).listEntities({
+							...kind !== null && kind !== "" && kind !== "all" ? { kind } : {},
+							...q !== null && q !== "" ? { q } : {},
+							limit,
+							offset
+						})
+					});
+					return;
+				}
+				if (req.method === "GET" && route === "entity") {
+					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
+					const id = url.searchParams.get("id");
+					if (id === null || id === "") {
+						json(res, 400, { error: "id required" });
+						return;
+					}
+					const limit = Math.min(100, Math.max(1, Number(url.searchParams.get("limit") ?? 20) || 20));
+					const detail = await (await storeFor(scope)).entityDetail(id, limit);
+					if (detail === void 0) {
+						json(res, 404, { error: `未找到实体 ${id}` });
+						return;
+					}
+					json(res, 200, detail);
+					return;
+				}
+				if (req.method === "GET" && route === "facts") {
+					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
+					const id = url.searchParams.get("entityId");
+					if (id === null || id === "") {
+						json(res, 400, { error: "entityId required" });
+						return;
+					}
+					const asOf = toNumber(url.searchParams.get("asOf"));
+					const includeInvalid = toBoolean(url.searchParams.get("includeInvalid")) ?? false;
+					const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit") ?? 50) || 50));
+					const offset = Math.max(0, Number(url.searchParams.get("offset") ?? 0) || 0);
+					json(res, 200, {
+						scope,
+						...await (await storeFor(scope)).factsOfEntity({
+							entityId: id,
+							...asOf === void 0 ? {} : { asOf },
+							...includeInvalid ? { includeInvalid: true } : {},
+							limit,
+							offset
+						})
+					});
+					return;
+				}
 				if (req.method === "GET" && route === "episode-timeline") {
 					const scope = scopeOf$1(url.searchParams.get("scope"), "user");
 					const since = toNumber(url.searchParams.get("since"));
@@ -2642,6 +3150,40 @@ function registerEngramRoutes(ctx, deps) {
 					});
 					return;
 				}
+				if (req.method === "GET" && route === "jev-config") {
+					json(res, 200, jevConfigView(deps.jev.base, loadJevOverride(deps.jev.dbDir)));
+					return;
+				}
+				if (req.method === "POST" && route === "jev-config") {
+					if (!guardWrite(req, res)) return;
+					const body = await readJsonBody(req);
+					const parsed = parseJevPatch(loadJevOverride(deps.jev.dbDir), body ?? {});
+					if (typeof parsed === "string") {
+						json(res, 400, { error: parsed });
+						return;
+					}
+					saveJevOverride(deps.jev.dbDir, parsed);
+					json(res, 200, {
+						ok: true,
+						view: jevConfigView(deps.jev.base, parsed)
+					});
+					return;
+				}
+				if (req.method === "POST" && route === "jev-test") {
+					if (!guardWrite(req, res)) return;
+					const body = await readJsonBody(req);
+					json(res, 200, await testJevConnection({
+						...effectiveJevConfig(deps.jev.base, loadJevOverride(deps.jev.dbDir)),
+						...typeof body?.baseUrl === "string" && body.baseUrl.trim() !== "" ? { baseUrl: body.baseUrl.trim() } : {},
+						...typeof body?.model === "string" && body.model.trim() !== "" ? { model: body.model.trim() } : {},
+						...typeof body?.apiKey === "string" && body.apiKey !== "" ? { apiKey: body.apiKey } : {}
+					}));
+					return;
+				}
+				if (req.method === "GET" && route === "jev-observations") {
+					json(res, 200, { items: [...listJevObservations()].reverse() });
+					return;
+				}
 				if (req.method === "POST" && route === "consolidate") {
 					if (!guardWrite(req, res)) return;
 					const body = await readJsonBody(req);
@@ -3104,7 +3646,7 @@ function placardImprovementHint(score) {
 * @module @kenz1117/dsh-engram/store/sqlite
 */
 /** 当前 schema 版本；结构性变更必须 +1。可空列与伴随表走增量迁移（见 openEngramStore 的迁移段）。 */
-const SCHEMA_VERSION = 9;
+const SCHEMA_VERSION = 11;
 /** 增量迁移表：key 为起始版本，value 为升到下一版本的 SQL（可多语句）。
 *  v2 → v3：nodes 补可空列 outcome（使用效果回报）。
 *  v3 → v4：新增 nodes_revisions 修订表（update 归档旧条目时的内容快照）。
@@ -3117,7 +3659,14 @@ const SCHEMA_VERSION = 9;
 *  v7 → v8：episode 情景时间线两个专用索引（kind+created_at 日期范围扫描、
 *   source_session_id+created_at 会话过滤）。列自 v1 就存在，纯索引迁移，零数据搬运。
 *  v8 → v9：会话摘要表 session_summaries（摄取期 LLM 生成的一句话会话摘要，
-*   组头展示用；与 nodes 无外键，会话 id 仅作逻辑关联）。 */
+*   组头展示用；与 nodes 无外键，会话 id 仅作逻辑关联）。
+*  v9 → v10：实体层两表——entities 实体词典（name/kind/aliases）与 node_entities
+*   记忆↔实体关联。实体随来源记忆所在 scope 分库；两表均无外键，删除记忆不级联
+*   （关联残留由查询侧 join status 过滤，见 listEntities 的 orphan 统计）。
+*  v10 → v11：facts 事实表——摄取/工具期抽取的一句话事实，挂在实体上（entity_id
+*   引用同库 entities.id，无外键）。valid_at/invalid_at 时间窗 + replaced_by 软失效
+*   链：新事实可声明取代旧事实（旧事实置 invalid_at 并回指 replaced_by），历史链
+*   保留可审计；asOf 查询按时间窗过滤（见 factsOfEntity）。 */
 const MIGRATIONS = {
 	"2": "ALTER TABLE nodes ADD COLUMN outcome TEXT",
 	"3": `CREATE TABLE IF NOT EXISTS nodes_revisions (
@@ -3144,7 +3693,21 @@ const MIGRATIONS = {
 	"7": `CREATE INDEX IF NOT EXISTS nodes_kind_created ON nodes (kind, created_at);
     CREATE INDEX IF NOT EXISTS nodes_session_created ON nodes (source_session_id, created_at);`,
 	"8": `CREATE TABLE IF NOT EXISTS session_summaries (
-    session_id TEXT PRIMARY KEY, summary TEXT NOT NULL, updated_at INTEGER NOT NULL);`
+    session_id TEXT PRIMARY KEY, summary TEXT NOT NULL, updated_at INTEGER NOT NULL);`,
+	"9": `CREATE TABLE IF NOT EXISTS entities (
+    id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL,
+    aliases_json TEXT NOT NULL DEFAULT '[]',
+    created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS node_entities (
+      node_id TEXT NOT NULL, entity_id TEXT NOT NULL,
+      PRIMARY KEY (node_id, entity_id));
+    CREATE INDEX IF NOT EXISTS entities_name ON entities (name);
+    CREATE INDEX IF NOT EXISTS node_entities_entity ON node_entities (entity_id);`,
+	"10": `CREATE TABLE IF NOT EXISTS facts (
+    id TEXT PRIMARY KEY, entity_id TEXT NOT NULL, content TEXT NOT NULL,
+    valid_at INTEGER NOT NULL, invalid_at INTEGER, replaced_by TEXT,
+    source_node_id TEXT, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+    CREATE INDEX IF NOT EXISTS facts_entity ON facts (entity_id);`
 };
 /** RRF 融合常数：score = Σ 1/(K + rank)。 */
 const RRF_K = 60;
@@ -3222,6 +3785,34 @@ function rowToRecord(row) {
 function blobToVec(blob) {
 	return new Float32Array(blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength));
 }
+function entityRowToRecord(row) {
+	let aliases = [];
+	try {
+		const parsed = JSON.parse(row.aliases_json);
+		if (Array.isArray(parsed)) aliases = parsed.filter((a) => typeof a === "string");
+	} catch {}
+	return {
+		id: asEntityId(row.id),
+		name: row.name,
+		kind: row.kind,
+		aliases,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+function factRowToRecord(row) {
+	return {
+		id: asFactId(row.id),
+		entityId: asEntityId(row.entity_id),
+		content: row.content,
+		validAt: row.valid_at,
+		invalidAt: row.invalid_at,
+		replacedBy: row.replaced_by === null ? null : asFactId(row.replaced_by),
+		sourceNodeId: row.source_node_id === null ? null : asMemoryId(row.source_node_id),
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
 function vecToBlob(vector) {
 	return new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength);
 }
@@ -3330,10 +3921,24 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
       source TEXT NOT NULL, at INTEGER NOT NULL, PRIMARY KEY (scope, version));
     CREATE TABLE IF NOT EXISTS session_summaries (
       session_id TEXT PRIMARY KEY, summary TEXT NOT NULL, updated_at INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS entities (
+      id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL,
+      aliases_json TEXT NOT NULL DEFAULT '[]',
+      created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS node_entities (
+      node_id TEXT NOT NULL, entity_id TEXT NOT NULL,
+      PRIMARY KEY (node_id, entity_id));
+    CREATE TABLE IF NOT EXISTS facts (
+      id TEXT PRIMARY KEY, entity_id TEXT NOT NULL, content TEXT NOT NULL,
+      valid_at INTEGER NOT NULL, invalid_at INTEGER, replaced_by TEXT,
+      source_node_id TEXT, created_at INTEGER NOT NULL, updated_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);
     CREATE INDEX IF NOT EXISTS nodes_kind_created ON nodes (kind, created_at);
     CREATE INDEX IF NOT EXISTS nodes_session_created ON nodes (source_session_id, created_at);
+    CREATE INDEX IF NOT EXISTS entities_name ON entities (name);
+    CREATE INDEX IF NOT EXISTS node_entities_entity ON node_entities (entity_id);
+    CREATE INDEX IF NOT EXISTS facts_entity ON facts (entity_id);
   `);
 	const versionRow = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
 	if (versionRow === void 0) {
@@ -3447,9 +4052,28 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 	const sqlProfileVersionsList = db.prepare("SELECT scope, version, content, source, at FROM profile_block_versions WHERE scope = ? ORDER BY version DESC LIMIT ?");
 	const sqlProfileVersionGet = db.prepare("SELECT scope, version, content, source, at FROM profile_block_versions WHERE scope = ? AND version = ?");
 	const sqlSessionSummaryUpsert = db.prepare(`INSERT INTO session_summaries (session_id, summary, updated_at) VALUES (?, ?, ?)
-    ON CONFLICT(session_id) DO UPDATE SET summary = excluded.summary, updated_at = excluded.updated_at`);
+    ON CONFLICT (session_id) DO UPDATE SET summary = excluded.summary, updated_at = excluded.updated_at`);
 	const sqlSessionSummaryGet = db.prepare("SELECT session_id, summary FROM session_summaries WHERE session_id = ?");
 	const sqlSessionSummaryMany = db.prepare("SELECT session_id, summary FROM session_summaries WHERE session_id IN (SELECT value FROM json_each(?))");
+	const sqlEntityAll = db.prepare("SELECT * FROM entities");
+	const sqlEntityGet = db.prepare("SELECT * FROM entities WHERE id = ?");
+	const sqlEntityInsert = db.prepare("INSERT INTO entities (id, name, kind, aliases_json, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)");
+	const sqlEntityTouch = db.prepare("UPDATE entities SET updated_at = ? WHERE id = ?");
+	const sqlNodeEntityInsert = db.prepare("INSERT OR IGNORE INTO node_entities (node_id, entity_id) VALUES (?, ?)");
+	const sqlEntityByNode = db.prepare(`SELECT e.* FROM node_entities ne JOIN entities e ON e.id = ne.entity_id
+    WHERE ne.node_id = ? ORDER BY e.name`);
+	const sqlEntityMemoryCounts = db.prepare(`SELECT ne.entity_id AS id, COUNT(*) AS n FROM node_entities ne
+    JOIN nodes n ON n.id = ne.node_id WHERE n.status = 'active' GROUP BY ne.entity_id`);
+	const sqlEntityMemories = db.prepare(`SELECT n.* FROM node_entities ne JOIN nodes n ON n.id = ne.node_id
+    WHERE ne.entity_id = ? AND n.status = 'active' ORDER BY n.created_at DESC LIMIT ?`);
+	const sqlPurgeEntities = db.prepare("DELETE FROM entities");
+	const sqlPurgeNodeEntities = db.prepare("DELETE FROM node_entities");
+	const sqlFactInsert = db.prepare(`INSERT INTO facts
+    (id, entity_id, content, valid_at, invalid_at, replaced_by, source_node_id, created_at, updated_at)
+    VALUES (?, ?, ?, ?, NULL, NULL, ?, ?, ?)`);
+	const sqlFactInvalidate = db.prepare("UPDATE facts SET invalid_at = ?, replaced_by = ?, updated_at = ? WHERE id = ?");
+	const sqlFactGet = db.prepare("SELECT * FROM facts WHERE id = ?");
+	const sqlPurgeFacts = db.prepare("DELETE FROM facts");
 	/** FTS 道：按 scope 集合检索（占位符动态生成，scope 集合由调用方去重）；rooms 非空时只查指定房间。 */
 	const ftsSearch = (match, scopes, rooms) => {
 		const placeholders = scopes.map(() => "?").join(",");
@@ -3648,12 +4272,17 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 				if (row === void 0) continue;
 				const viaEdge = viaEdgeOf.get(id);
 				const cueNeighbors = hits.length < 5 && row.slot_room !== null && row.slot_index !== null ? sqlSlotNeighbors.all(row.slot_room, row.slot_index - 1, row.slot_index + 1, id).map((neighbor) => asMemoryId(neighbor.id)) : [];
+				const entityRows = sqlEntityByNode.all(id);
 				hits.push({
 					record: rowToRecord(row),
 					score: info.score,
 					via: info.via,
 					...viaEdge === void 0 ? {} : { viaEdge },
-					...cueNeighbors.length === 0 ? {} : { cues: { neighbors: cueNeighbors } }
+					...cueNeighbors.length === 0 ? {} : { cues: { neighbors: cueNeighbors } },
+					...entityRows.length === 0 ? {} : { entities: entityRows.map((r) => ({
+						id: asEntityId(r.id),
+						name: r.name
+					})) }
 				});
 				sqlTouch.run(Date.now(), id);
 			}
@@ -4053,6 +4682,7 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 		async exportAll() {
 			const records = sqlAllNodes.all().map(rowToRecord);
 			const edgeRows = sqlAllEdges.all();
+			const entities = sqlEntityAll.all().map(entityRowToRecord);
 			return {
 				exportedAt: Date.now(),
 				records,
@@ -4061,7 +4691,8 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 					to: asMemoryId(edge.to_id),
 					type: edge.type,
 					createdAt: edge.created_at
-				}))
+				})),
+				entities
 			};
 		},
 		async decay(options) {
@@ -4119,6 +4750,134 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 			});
 			return rowToRecord(sqlGet.get(id));
 		},
+		async resolveEntities(mentions) {
+			if (mentions.length === 0) return [];
+			const at = Date.now();
+			const result = [];
+			withTransaction(() => {
+				const byKey = /* @__PURE__ */ new Map();
+				for (const row of sqlEntityAll.all()) {
+					const entity = entityRowToRecord(row);
+					byKey.set(normalizeEntityName(entity.name), entity);
+					for (const alias of entity.aliases) {
+						const aliasKey = normalizeEntityName(alias);
+						if (aliasKey !== "" && !byKey.has(aliasKey)) byKey.set(aliasKey, entity);
+					}
+				}
+				for (const mention of mentions) {
+					const name = mention.name.trim();
+					if (name === "") throw new EngramError("EMPTY_ENTITY_NAME", "实体名不能为空（清洗后的提及仍含空名）");
+					const key = normalizeEntityName(name);
+					const hit = byKey.get(key);
+					if (hit !== void 0) {
+						sqlEntityTouch.run(at, hit.id);
+						result.push(hit);
+						continue;
+					}
+					const aliases = [...new Set((mention.aliases ?? []).map((a) => a.trim()).filter((a) => a !== ""))];
+					const entity = {
+						id: asEntityId(randomUUID()),
+						name,
+						kind: mention.kind,
+						aliases,
+						createdAt: at,
+						updatedAt: at
+					};
+					sqlEntityInsert.run(entity.id, entity.name, entity.kind, JSON.stringify(aliases), at, at);
+					byKey.set(key, entity);
+					for (const alias of aliases) {
+						const aliasKey = normalizeEntityName(alias);
+						if (aliasKey !== "" && !byKey.has(aliasKey)) byKey.set(aliasKey, entity);
+					}
+					result.push(entity);
+				}
+			});
+			return result;
+		},
+		async linkNodeEntities(nodeId, entityIds) {
+			withTransaction(() => {
+				for (const entityId of entityIds) sqlNodeEntityInsert.run(String(nodeId), String(entityId));
+			});
+		},
+		async entitiesOfNodes(nodeIds) {
+			const map = /* @__PURE__ */ new Map();
+			for (const nodeId of nodeIds) {
+				const rows = sqlEntityByNode.all(String(nodeId));
+				if (rows.length > 0) map.set(nodeId, rows.map(entityRowToRecord));
+			}
+			return map;
+		},
+		async listEntities(filter) {
+			const conditions = [];
+			const params = [];
+			if (filter.kind !== void 0) {
+				conditions.push("kind = ?");
+				params.push(filter.kind);
+			}
+			if (filter.q !== void 0 && filter.q !== "") {
+				conditions.push("name LIKE ? ESCAPE '\\' OR aliases_json LIKE ? ESCAPE '\\'");
+				const pattern = `%${filter.q.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+				params.push(pattern, pattern);
+			}
+			const where = conditions.length === 0 ? "" : ` WHERE ${conditions.join(" AND ")}`;
+			const total = db.prepare(`SELECT COUNT(*) AS n FROM entities${where}`).get(...params).n;
+			const rows = db.prepare(`SELECT * FROM entities${where} ORDER BY updated_at DESC LIMIT ? OFFSET ?`).all(...params, filter.limit, filter.offset);
+			const counts = new Map(sqlEntityMemoryCounts.all().map((r) => [r.id, r.n]));
+			return {
+				items: rows.map((row) => ({
+					entity: entityRowToRecord(row),
+					memoryCount: counts.get(row.id) ?? 0
+				})),
+				total
+			};
+		},
+		async entityDetail(id, memoryLimit) {
+			const row = sqlEntityGet.get(String(id));
+			if (row === void 0) return void 0;
+			const memories = sqlEntityMemories.all(String(id), memoryLimit).map(rowToRecord);
+			return {
+				entity: entityRowToRecord(row),
+				memories
+			};
+		},
+		async writeFacts(inputs) {
+			const now = Date.now();
+			return inputs.map((input) => {
+				const id = asFactId(randomUUID());
+				const validAt = input.validAt ?? now;
+				withTransaction(() => {
+					if (input.replaces !== void 0 && sqlFactGet.get(String(input.replaces)) !== void 0) sqlFactInvalidate.run(now, id, now, String(input.replaces));
+					sqlFactInsert.run(id, String(input.entityId), input.content, validAt, input.sourceNodeId === void 0 ? null : String(input.sourceNodeId), now, now);
+				});
+				return {
+					id,
+					entityId: input.entityId,
+					content: input.content,
+					validAt,
+					invalidAt: null,
+					replacedBy: null,
+					sourceNodeId: input.sourceNodeId ?? null,
+					createdAt: now,
+					updatedAt: now
+				};
+			});
+		},
+		async factsOfEntity(filter) {
+			const conditions = ["entity_id = ?"];
+			const params = [String(filter.entityId)];
+			if (!filter.includeInvalid) {
+				if (filter.asOf !== void 0) {
+					conditions.push("valid_at <= ? AND (invalid_at IS NULL OR invalid_at > ?)");
+					params.push(filter.asOf, filter.asOf);
+				} else conditions.push("invalid_at IS NULL");
+			}
+			const where = ` WHERE ${conditions.join(" AND ")}`;
+			const total = db.prepare(`SELECT COUNT(*) AS n FROM facts${where}`).get(...params).n;
+			return {
+				items: db.prepare(`SELECT * FROM facts${where} ORDER BY valid_at DESC LIMIT ? OFFSET ?`).all(...params, filter.limit, filter.offset).map(factRowToRecord),
+				total
+			};
+		},
 		async audit(op, targetId, detail) {
 			sqlLog.run(Date.now(), op, targetId, detail);
 		},
@@ -4141,6 +4900,9 @@ async function openEngramStore(path, rankBoost = NO_BOOST, automation = DEFAULT_
 				sqlPurgeProfileBlocks.run();
 				sqlPurgeProfileVersions.run();
 				sqlPurgeSessionSummaries.run();
+				sqlPurgeNodeEntities.run();
+				sqlPurgeEntities.run();
+				sqlPurgeFacts.run();
 			});
 		},
 		async close() {
@@ -4519,7 +5281,7 @@ function assessEvidence(batch, request) {
 //#endregion
 //#region src/tools/create.ts
 /**
-* 19 个 engram_ 工具的定义与执行器。工具 schema 保持窄参数；
+* 20 个 engram_ 工具的定义与执行器。工具 schema 保持窄参数；
 * scope 决定读写哪个分库；嵌入缺失时检索结果显式标记降级。
 * @module @kenz1117/dsh-engram/tools/create
 */
@@ -4556,6 +5318,12 @@ function parseCountParam(raw, toolName, field, fallback, min, max) {
 	if (value < min || value > max) throw new Error(`${toolName}: ${field} 需在 ${String(min)}-${String(max)} 之间，收到 ${String(value)}`);
 	return value;
 }
+/** 事实链行渲染：序号 + 陈述 + id/生效日期；失效事实附失效日期与后继 id（全链视图用）。 */
+function renderFactLine(index, fact) {
+	const valid = new Date(fact.validAt).toISOString().slice(0, 10);
+	const state = fact.invalidAt === null ? "" : `（已失效 ${new Date(fact.invalidAt).toISOString().slice(0, 10)}，被 ${fact.replacedBy ?? "未知事实"} 取代）`;
+	return `${index + 1}. ${fact.content}（id=${fact.id}, 生效 ${valid}）${state}`;
+}
 /** 历史回填估算的模型可读文本（零成本，先看数再决定跑不跑）。 */
 function renderHistoryEstimate(estimate) {
 	if (estimate.unavailable !== void 0) return `历史回填不可用：${estimate.unavailable}`;
@@ -4672,7 +5440,7 @@ async function rewriteQueries(deps, exec, query) {
 	}
 }
 /**
-* 构造 19 个工具定义（engram_save/search/assess/timeline/episode_timeline/update/forget/report/review/review_queue/
+* 构造 20 个工具定义（engram_save/search/facts/assess/timeline/episode_timeline/update/forget/report/review/review_queue/
 * stats/export/distill/examine/neighbors/audit_forgotten/tour/ingest_history/profile_edit）。
 * @param baseDeps - 分库打开器、嵌入器、辅助 LLM、导出目录。
 * @returns 可直接 register 的工具定义数组（execute 已绑定会话 cwd 的项目宫殿路由）。
@@ -4718,7 +5486,10 @@ function createEngramTools(baseDeps) {
 	*/
 	async function writeWithDisposition(store, item) {
 		const { embedding } = item;
-		const decision = await decideWrite(store, item.kind, embedding);
+		const decision = await decideWrite(store, item.kind, embedding, deps.judge === void 0 ? {} : {
+			judge: deps.judge,
+			content: item.content
+		});
 		if (decision.disposition === "merge") return {
 			disposition: "merge",
 			record: await applyMerge(store, decision, item.content),
@@ -4737,13 +5508,14 @@ function createEngramTools(baseDeps) {
 		});
 		if (decision.disposition === "defer") {
 			const candidates = await store.findContradictions(embedding);
-			for (const candidate of candidates) await store.linkEdge(record.id, candidate.id, "contradicts");
+			const confirmed = deps.judge === void 0 ? candidates : await confirmContradictions(deps.judge, item.content, candidates) ?? candidates;
+			for (const candidate of confirmed) await store.linkEdge(record.id, candidate.id, "contradicts");
 			return {
 				disposition: "defer",
 				record,
 				relatedId: decision.neighbor.id,
 				similarity: decision.similarity,
-				candidates
+				candidates: confirmed
 			};
 		}
 		return {
@@ -4752,6 +5524,17 @@ function createEngramTools(baseDeps) {
 			candidates: []
 		};
 	}
+	/**
+	* 实体关联辅助：消解实体提及并挂到条目。merge 处置挂被并入的既有条目，
+	* accept/defer 挂新条目；失败静默（实体词典是增强数据，不阻塞记忆写入）。
+	*/
+	async function linkEntities(store, nodeId, mentions) {
+		if (mentions.length === 0) return;
+		try {
+			const entities = await store.resolveEntities(mentions);
+			await store.linkNodeEntities(nodeId, entities.map((entity) => entity.id));
+		} catch {}
+	}
 	/** 门牌参数收敛：非空字符串转 ImageryLabel（感官/情绪维度留空——AI 不需要人脑补丁），非法返回 undefined。 */
 	function placardOf(raw) {
 		if (typeof raw !== "string") return void 0;
@@ -4817,7 +5600,8 @@ function createEngramTools(baseDeps) {
 				index,
 				content,
 				kind: candidate.kind,
-				importance: typeof candidate.importance === "number" ? candidate.importance : void 0
+				importance: typeof candidate.importance === "number" ? candidate.importance : void 0,
+				entities: parseEntityMentions(candidate.entities)
 			});
 		}
 		const vectors = embedder === void 0 || prepared.length === 0 ? void 0 : await embedder.embed(prepared.map((item) => item.content.trim()));
@@ -4832,6 +5616,7 @@ function createEngramTools(baseDeps) {
 				sourceSessionId,
 				...embedding === void 0 ? {} : { embedding }
 			});
+			await linkEntities(store, outcome.disposition === "merge" && outcome.relatedId !== void 0 ? asMemoryId(outcome.relatedId) : outcome.record.id, item.entities);
 			saved.push({
 				id: outcome.record.id,
 				kind: outcome.record.kind,
@@ -4865,9 +5650,40 @@ function createEngramTools(baseDeps) {
 				enum: [...KINDS],
 				description: "记忆种类（单条模式必填）"
 			},
+			entities: {
+				type: "array",
+				description: "本条记忆提到的实体（可选，仅单条模式）：人名/项目名/工具名/概念名，用于按实体检索",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						name: {
+							type: "string",
+							required: true,
+							description: "实体名（专名本身，不超过 20 字）"
+						},
+						kind: {
+							type: "string",
+							enum: [
+								"person",
+								"project",
+								"tool",
+								"concept",
+								"other"
+							],
+							description: "实体种类，默认 other"
+						},
+						aliases: {
+							type: "array",
+							items: { type: "string" },
+							description: "该实体的其他叫法"
+						}
+					}
+				}
+			},
 			items: {
 				type: "array",
-				description: "批量保存条目数组，每项 {content, kind, importance?}；与 content/kind 二选一",
+				description: "批量保存条目数组，每项 {content, kind, importance?, entities?}；与 content/kind 二选一",
 				items: {
 					type: "object",
 					additionalProperties: false,
@@ -4886,6 +5702,37 @@ function createEngramTools(baseDeps) {
 						importance: {
 							type: "number",
 							description: "重要性 0-1"
+						},
+						entities: {
+							type: "array",
+							description: "该条提到的实体",
+							items: {
+								type: "object",
+								additionalProperties: false,
+								properties: {
+									name: {
+										type: "string",
+										required: true,
+										description: "实体名（专名本身，不超过 20 字）"
+									},
+									kind: {
+										type: "string",
+										enum: [
+											"person",
+											"project",
+											"tool",
+											"concept",
+											"other"
+										],
+										description: "实体种类，默认 other"
+									},
+									aliases: {
+										type: "array",
+										items: { type: "string" },
+										description: "该实体的其他叫法"
+									}
+								}
+							}
 						}
 					}
 				}
@@ -5013,6 +5860,7 @@ function createEngramTools(baseDeps) {
 			const embedder = await deps.embedder;
 			const embeddings = embedder === void 0 ? void 0 : await embedder.embed([content.trim()]);
 			const imagery = placardOf(input.placard);
+			const mentions = parseEntityMentions(input.entities);
 			const outcome = await writeWithDisposition(store, {
 				scope,
 				kind: input.kind,
@@ -5022,6 +5870,7 @@ function createEngramTools(baseDeps) {
 				...embeddings?.[0] === void 0 ? {} : { embedding: embeddings[0] },
 				...imagery === void 0 ? {} : { imagery }
 			});
+			if (mentions.length > 0) await linkEntities(store, outcome.disposition === "merge" && outcome.relatedId !== void 0 ? asMemoryId(outcome.relatedId) : outcome.record.id, mentions);
 			const { record, candidates } = outcome;
 			if (outcome.disposition === "merge") {
 				const sim = (outcome.similarity ?? 0).toFixed(2);
@@ -5083,6 +5932,10 @@ function createEngramTools(baseDeps) {
 			limit: {
 				type: "number",
 				description: "返回条数上限，默认 8"
+			},
+			asOf: {
+				type: "string",
+				description: "时点回看（可选，ISO 日期如 2026-03-01）：结果行附各记忆关联实体在该时点仍有效的事实快照，回答「当时」类问题时防止过时事实误导"
 			}
 		},
 		output: {
@@ -5110,6 +5963,7 @@ function createEngramTools(baseDeps) {
 			const scopes = scopesOf(input.scope);
 			const rooms = typeof input.room === "string" && input.room.trim() !== "" ? [input.room.trim()] : void 0;
 			const limit = input.limit ?? 8;
+			const asOfMs = parseTimeParam(typeof input.asOf === "string" ? input.asOf : void 0, "engram_search", "asOf");
 			const rewrite = await rewriteQueries(deps, exec, input.query);
 			const retrievals = await Promise.all(rewrite.queries.map(async (queryText) => {
 				const vector = await queryVectorOf(deps, queryText);
@@ -5127,15 +5981,49 @@ function createEngramTools(baseDeps) {
 				};
 			}));
 			const degraded = retrievals.some((retrieval) => retrieval.degraded);
-			const { kept, dropped } = fitWithinBudget(mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length))).map((hit, index) => {
+			const merged = mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length)));
+			const factNotes = /* @__PURE__ */ new Map();
+			if (asOfMs !== void 0) {
+				const scopeGroups = /* @__PURE__ */ new Map();
+				for (const hit of merged) {
+					const ids = scopeGroups.get(hit.record.scope);
+					if (ids === void 0) scopeGroups.set(hit.record.scope, [hit.record.id]);
+					else ids.push(hit.record.id);
+				}
+				for (const [scope, ids] of scopeGroups) {
+					const store = await deps.openStore(scope);
+					const entityMap = await store.entitiesOfNodes(ids);
+					const factLists = /* @__PURE__ */ new Map();
+					for (const entities of entityMap.values()) for (const entity of entities) {
+						if (factLists.has(entity.id)) continue;
+						factLists.set(entity.id, (await store.factsOfEntity({
+							entityId: entity.id,
+							asOf: asOfMs,
+							limit: 3,
+							offset: 0
+						})).items);
+					}
+					for (const [nodeId, entities] of entityMap) {
+						const contents = [];
+						for (const entity of entities) for (const fact of factLists.get(entity.id) ?? []) {
+							if (contents.length >= 4) break;
+							contents.push(fact.content);
+						}
+						if (contents.length > 0) factNotes.set(String(nodeId), contents);
+					}
+				}
+			}
+			const { kept, dropped } = fitWithinBudget(merged.map((hit, index) => {
 				const ref = evidenceRefOf(hit.record.scope, hit.record.id, hit.record.slot);
 				const edge = hit.viaEdge === void 0 ? "" : `（经 ${hit.viaEdge.type} 关联自 ${hit.viaEdge.from}）`;
 				const slot = hit.record.slot === void 0 ? "" : ` ${hit.record.slot.room}#${hit.record.slot.index}`;
 				const date = ` 刻于 ${new Date(hit.record.createdAt).toISOString().slice(0, 10)}`;
 				const cues = hit.cues === void 0 ? "" : ` 相邻桩位: ${hit.cues.neighbors.join(", ")}`;
+				const notes = factNotes.get(String(hit.record.id));
+				const facts = notes === void 0 ? "" : ` 时点事实: ${notes.join("；")}`;
 				return {
 					ref,
-					line: `${index + 1}. [${hit.record.scope}/${hit.record.kind}]${slot}${date} ${truncateItem(hit.record.content)}（id=${hit.record.id}, ref=${ref}）${edge}${cues}`
+					line: `${index + 1}. [${hit.record.scope}/${hit.record.kind}]${slot}${date} ${truncateItem(hit.record.content)}（id=${hit.record.id}, ref=${ref}）${edge}${cues}${facts}`
 				};
 			}), (entry) => entry.line.length, RECALL_TOTAL_CHARS);
 			const lines = kept.map((entry) => entry.line);
@@ -5144,10 +6032,284 @@ function createEngramTools(baseDeps) {
 			const batch = sessionId === void 0 || kept.length === 0 ? void 0 : evidenceBatches.register(sessionId, kept.map((entry) => entry.ref));
 			const prefix = degraded && lines.length > 0 ? "（语义嵌入不可用，仅关键词检索）\n" : "";
 			const roomNote = rooms === void 0 ? "" : `（房间路由：${rooms.join("、")}）\n`;
+			const asOfNote = asOfMs === void 0 ? "" : `（时点回看：行尾「时点事实」为关联实体在 ${new Date(asOfMs).toISOString().slice(0, 10)} 仍有效的事实快照）\n`;
 			const batchNote = batch === void 0 ? "" : `\n批次 ${batch.batchId}（${String(batch.refs.size)} 条可引用证据）：作答前用 engram_assess 判定证据是否充分，evidenceRefs 只能引用上面的 ref。`;
 			return {
 				degraded,
-				text: renderMemoryPacket(`${prefix}${roomNote}${lines.join("\n") || "无命中"}${batchNote}`, "tool_search", input.query)
+				text: renderMemoryPacket(`${prefix}${roomNote}${asOfNote}${lines.join("\n") || "无命中"}${batchNote}`, "tool_search", input.query)
+			};
+		}
+	});
+	const factsTool = defineTool({
+		name: "engram_facts",
+		description: "实体事实链：查询某实体的时序事实（asOf 时点回看 / includeInvalid 全链展开），或写入与修正事实（facts 数组）。事实是关于具体实体的一条客观陈述（状态/归属/关系/数据）。修正过时事实时传 replaces=旧事实 id：旧事实软失效、新事实接棒，历史链保留——不要反复保存互相矛盾的事实，用取代链表达演变。",
+		parameters: {
+			scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"shared"
+				],
+				description: "作用域，默认 project"
+			},
+			entityId: {
+				type: "string",
+				description: "查询模式：实体 id（engram_search/engram_entities 输出中获取；与 entity 二选一，优先）"
+			},
+			entity: {
+				type: "string",
+				description: "查询模式：实体名（按名称与别名精确匹配；未命中不新建，返回近似候选）"
+			},
+			asOf: {
+				type: "string",
+				description: "时点回看（ISO 日期或毫秒时间戳）：只看该时点仍有效的事实"
+			},
+			includeInvalid: {
+				type: "boolean",
+				description: "true 展开全链（含已失效事实，查看事实演变历史）"
+			},
+			limit: {
+				type: "number",
+				description: "返回条数上限，默认 20"
+			},
+			offset: {
+				type: "number",
+				description: "分页偏移，默认 0"
+			},
+			facts: {
+				type: "array",
+				description: "写入模式：事实数组（与查询参数二选一），每项 {entity 或 entityId, content, replaces?}",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						entity: {
+							type: "string",
+							description: "实体名（与 entityId 二选一；实体不存在时新建）"
+						},
+						entityId: {
+							type: "string",
+							description: "实体 id（优先于 entity）"
+						},
+						content: {
+							type: "string",
+							required: true,
+							description: "事实陈述（一句话，不超过 500 字符）"
+						},
+						replaces: {
+							type: "string",
+							description: "被取代的旧事实 id（旧事实软失效；id 不存在时按无取代写入）"
+						}
+					}
+				}
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					total: { type: "number" },
+					count: { type: "number" },
+					items: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								id: {
+									type: "string",
+									required: true
+								},
+								entityId: {
+									type: "string",
+									required: true
+								},
+								replaced: { type: "string" }
+							}
+						}
+					},
+					failed: {
+						type: "array",
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								index: {
+									type: "number",
+									required: true
+								},
+								reason: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					},
+					text: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args) {
+			const input = args;
+			const scope = scopeOf(input.scope, "project");
+			const store = await deps.openStore(scope);
+			const asOfMs = parseTimeParam(typeof input.asOf === "string" ? input.asOf : void 0, "engram_facts", "asOf");
+			if (input.facts !== void 0) {
+				if (input.entityId !== void 0 || input.entity !== void 0 || input.asOf !== void 0 || input.includeInvalid !== void 0) throw new Error("engram_facts: facts（写入）与 entityId/entity/asOf/includeInvalid（查询）参数不能同时使用");
+				if (!Array.isArray(input.facts) || input.facts.length === 0) throw new Error("engram_facts: facts 必须是非空数组");
+				if (input.facts.length > MAX_SAVE_BATCH) throw new Error(`engram_facts: 单次最多写入 ${MAX_SAVE_BATCH} 条事实`);
+				const failed = [];
+				const prepared = [];
+				for (const [index, raw] of input.facts.entries()) {
+					if (raw === null || typeof raw !== "object") {
+						failed.push({
+							index,
+							reason: "条目必须是对象"
+						});
+						continue;
+					}
+					const candidate = raw;
+					if (typeof candidate.content !== "string" || candidate.content.trim() === "") {
+						failed.push({
+							index,
+							reason: "content 缺失或为空"
+						});
+						continue;
+					}
+					const content = redactSecrets(sanitizeProtocolText(candidate.content));
+					if (content.trim() === "") {
+						failed.push({
+							index,
+							reason: "清洗后内容为空（只含协议标签或密钥）"
+						});
+						continue;
+					}
+					try {
+						let entityId;
+						if (typeof candidate.entityId === "string" && candidate.entityId.trim() !== "") entityId = asEntityId(candidate.entityId.trim());
+						else if (typeof candidate.entity === "string" && candidate.entity.trim() !== "") {
+							const resolvedEntity = (await store.resolveEntities([{
+								name: candidate.entity.trim(),
+								kind: "other"
+							}]))[0];
+							if (resolvedEntity === void 0) {
+								failed.push({
+									index,
+									reason: "实体消解未返回结果"
+								});
+								continue;
+							}
+							entityId = resolvedEntity.id;
+						} else {
+							failed.push({
+								index,
+								reason: "需要 entity 或 entityId"
+							});
+							continue;
+						}
+						prepared.push({
+							index,
+							input: {
+								entityId,
+								content,
+								...typeof candidate.replaces === "string" && candidate.replaces.trim() !== "" ? { replaces: asFactId(candidate.replaces.trim()) } : {}
+							}
+						});
+					} catch (error) {
+						failed.push({
+							index,
+							reason: error instanceof Error ? error.message : String(error)
+						});
+					}
+				}
+				const records = prepared.length === 0 ? [] : await store.writeFacts(prepared.map((entry) => entry.input));
+				const items = [];
+				for (const [position, record] of records.entries()) {
+					const entry = prepared[position];
+					if (entry === void 0) continue;
+					items.push({
+						id: record.id,
+						entityId: record.entityId,
+						...entry.input.replaces === void 0 ? {} : { replaced: entry.input.replaces }
+					});
+				}
+				const parts = [`已写入 ${String(records.length)} 条事实`];
+				const replacedCount = prepared.filter((entry) => entry.input.replaces !== void 0).length;
+				if (replacedCount > 0) parts.push(`其中 ${String(replacedCount)} 条声明取代旧事实（旧事实已软失效，历史链保留；id 不存在时按无取代写入）`);
+				for (const item of items) parts.push(`${item.id} → 实体 ${item.entityId}${item.replaced === void 0 ? "" : `（取代 ${item.replaced}）`}`);
+				if (failed.length > 0) parts.push(`${String(failed.length)} 条失败：${failed.map((entry) => `#${String(entry.index + 1)} ${entry.reason}`).join("；")}`);
+				return {
+					count: records.length,
+					items,
+					...failed.length > 0 ? { failed } : {},
+					text: parts.join("；")
+				};
+			}
+			const hasEntityId = typeof input.entityId === "string" && input.entityId.trim() !== "";
+			const hasEntityName = typeof input.entity === "string" && input.entity.trim() !== "";
+			if (!hasEntityId && !hasEntityName) throw new Error("engram_facts: 需要 entityId/entity（查询）或 facts（写入）参数");
+			const limit = parseCountParam(typeof input.limit === "number" ? input.limit : void 0, "engram_facts", "limit", 20, 1, 100);
+			const offset = parseCountParam(typeof input.offset === "number" ? input.offset : void 0, "engram_facts", "offset", 0, 0, 1e5);
+			const includeInvalid = input.includeInvalid === true;
+			let entityId;
+			let entityName;
+			if (hasEntityId) {
+				entityId = asEntityId(input.entityId.trim());
+				const detail = await store.entityDetail(entityId, 0);
+				if (detail === void 0) throw new Error(`engram_facts: 实体 ${input.entityId} 不存在`);
+				entityName = detail.entity.name;
+			} else {
+				const name = input.entity.trim();
+				const { items: candidates } = await store.listEntities({
+					q: name,
+					limit: 10,
+					offset: 0
+				});
+				const normalized = normalizeEntityName(name);
+				const matches = candidates.filter((item) => normalizeEntityName(item.entity.name) === normalized || item.entity.aliases.some((alias) => normalizeEntityName(alias) === normalized));
+				if (matches.length === 0) {
+					const near = candidates.map((item) => `${item.entity.name}（id=${item.entity.id}）`).join("；");
+					return {
+						total: 0,
+						text: `未找到实体「${name}」（按名称与别名精确匹配，不自动新建）。${near === "" ? "词典中没有近似名称。" : `近似候选：${near}。可用 entityId 精确查询。`}`
+					};
+				}
+				if (matches.length > 1) {
+					const listed = matches.map((item) => `${item.entity.name}（id=${item.entity.id}）`).join("；");
+					return {
+						total: 0,
+						text: `名称「${name}」匹配到 ${String(matches.length)} 个实体：${listed}。请用 entityId 指定。`
+					};
+				}
+				const match = matches[0];
+				if (match === void 0) return {
+					total: 0,
+					text: `未找到实体「${name}」。`
+				};
+				entityId = match.entity.id;
+				entityName = match.entity.name;
+			}
+			const { items: facts, total } = await store.factsOfEntity({
+				entityId,
+				...asOfMs === void 0 ? {} : { asOf: asOfMs },
+				...includeInvalid ? { includeInvalid: true } : {},
+				limit,
+				offset
+			});
+			const header = `实体「${entityName}」的事实（共 ${String(total)} 条${asOfMs === void 0 ? "" : `，时点 ${new Date(asOfMs).toISOString().slice(0, 10)}`}${includeInvalid ? "，全链含已失效" : ""}）`;
+			const lines = facts.map((fact, index) => renderFactLine(index, fact));
+			return {
+				total,
+				text: renderMemoryPacket(`${header}\n${lines.length === 0 ? "没有符合条件的事实。" : lines.join("\n")}`, "tool_facts", hasEntityName ? input.entity : entityId)
 			};
 		}
 	});
@@ -5715,6 +6877,7 @@ function createEngramTools(baseDeps) {
 	return [
 		save,
 		search,
+		factsTool,
 		assess,
 		timeline,
 		episodeTimeline,
@@ -6673,6 +7836,7 @@ async function preStep(ctx, openStore, openStoreForProjectCwd, resolved, embedde
 				embedder,
 				mode,
 				routeOverride: resolved.routeOverride,
+				...resolveJevField(resolved.jev, resolved.dbDir),
 				call: (params) => streamText(ctx, {
 					...params,
 					sessionId: agent.session.id
@@ -6693,6 +7857,7 @@ async function preStep(ctx, openStore, openStoreForProjectCwd, resolved, embedde
 			embedder,
 			mode,
 			routeOverride: resolved.routeOverride,
+			...resolveJevField(resolved.jev, resolved.dbDir),
 			call: (params) => streamText(ctx, {
 				...params,
 				sessionId: agent.session.id
@@ -7017,7 +8182,8 @@ function apply(ctx, config = {}) {
 			...callParams,
 			sessionId: ""
 		}),
-		logRequest: logIngestRequest
+		logRequest: logIngestRequest,
+		...resolveJevField(resolved.jev, resolved.dbDir)
 	});
 	/** 回填任务（进程内单例；面板轮询它的进度，工具同步等待自己的那一次运行）。 */
 	let backfillJob;
@@ -7124,6 +8290,7 @@ function apply(ctx, config = {}) {
 			sessionId: callParams.sessionId ?? ""
 		}),
 		routeOverride: resolved.routeOverride,
+		...resolveJevField(resolved.jev, resolved.dbDir),
 		queryRewrite: resolved.queryRewrite,
 		exportDir: `${resolved.dbDir}/exports`,
 		historyBackfill: {
@@ -7140,6 +8307,10 @@ function apply(ctx, config = {}) {
 			dbDir: resolved.dbDir,
 			pluginVersion: VERSION,
 			embedder,
+			jev: {
+				base: resolved.jev,
+				dbDir: resolved.dbDir
+			},
 			history: {
 				estimate: historyApi.estimate,
 				start: historyApi.start,
@@ -7171,6 +8342,7 @@ function apply(ctx, config = {}) {
 			embedder,
 			mode,
 			routeOverride: resolved.routeOverride,
+			...resolveJevField(resolved.jev, resolved.dbDir),
 			call: (params) => streamText(ctx, {
 				...params,
 				sessionId: session.id