@kenz1117/dsh-engram 0.2.0

package/lib/index.mjs

@@ -0,0 +1,1577 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { BlockAssembler, createUserMessage } from "@deepseek-ai/dsh-llm";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { randomUUID } from "node:crypto";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/config.ts
+/**
+* 插件 Config：所有部署可变项集中于此，禁止在实现里内嵌默认值。
+* @module @kenz1117/dsh-engram/config
+*/
+/** 合法配置键集合（未知键 loud 失败）。 */
+const CONFIG_KEYS = /* @__PURE__ */ new Set([
+	"dbDir",
+	"injectProfile",
+	"profileTopN",
+	"modelCacheDir",
+	"hfEndpoint",
+	"ingest",
+	"provider",
+	"model",
+	"decayAfterDays",
+	"decayImportanceBelow"
+]);
+const INGEST_MODES = /* @__PURE__ */ new Set([
+	"off",
+	"light",
+	"eager"
+]);
+/** Schemastery 校验面（cordis.yml 读取时校验）。 */
+const Config = z.object({
+	dbDir: z.string(),
+	injectProfile: z.boolean(),
+	profileTopN: z.number().step(1).min(1).max(64),
+	modelCacheDir: z.string(),
+	hfEndpoint: z.string(),
+	ingest: z.string(),
+	provider: z.string(),
+	model: z.string(),
+	decayAfterDays: z.number().step(1).min(1).max(3650),
+	decayImportanceBelow: z.number().min(0).max(1)
+});
+/**
+* 显式 resolve 步骤：默认值只在唯一的此处落地，非法值 loud 失败。
+* @param config - cordis.yml 传入的未校验配置。
+* @returns 完整解析配置。
+* @throws 未知键、ingest 档位非法、provider/model 只给其一、decay 参数越界时抛错。
+*/
+function resolveConfig(config = {}) {
+	for (const key of Object.keys(config)) if (!CONFIG_KEYS.has(key)) throw new Error(`dsh-engram: unknown config key "${key}"`);
+	if (config.ingest !== void 0 && !INGEST_MODES.has(config.ingest)) throw new Error(`dsh-engram: ingest must be one of off|light|eager, got "${String(config.ingest)}"`);
+	if (config.profileTopN !== void 0 && (!Number.isInteger(config.profileTopN) || config.profileTopN < 1 || config.profileTopN > 64)) throw new Error("dsh-engram: profileTopN must be an integer in [1, 64]");
+	const hasProvider = config.provider !== void 0;
+	const hasModel = config.model !== void 0;
+	if (hasProvider !== hasModel) throw new Error("dsh-engram: provider and model must be supplied together");
+	if (config.decayAfterDays !== void 0 && (!Number.isInteger(config.decayAfterDays) || config.decayAfterDays < 1 || config.decayAfterDays > 3650)) throw new Error("dsh-engram: decayAfterDays must be an integer in [1, 3650]");
+	if (config.decayImportanceBelow !== void 0 && (config.decayImportanceBelow < 0 || config.decayImportanceBelow > 1)) throw new Error("dsh-engram: decayImportanceBelow must be in [0, 1]");
+	const dbDir = config.dbDir ?? join(homedir(), ".dsh", "engram");
+	return {
+		dbDir,
+		injectProfile: config.injectProfile ?? true,
+		profileTopN: config.profileTopN ?? 8,
+		modelCacheDir: config.modelCacheDir ?? join(dbDir, "models"),
+		hfEndpoint: config.hfEndpoint,
+		ingest: config.ingest ?? "off",
+		routeOverride: hasProvider && hasModel ? {
+			provider: config.provider,
+			model: config.model
+		} : void 0,
+		decayAfterDays: config.decayAfterDays ?? 30,
+		decayImportanceBelow: config.decayImportanceBelow ?? .3
+	};
+}
+//#endregion
+//#region src/types.ts
+/** 从任意字符串铸造品牌化 id（存储层入库前调用）。 */
+function asMemoryId(raw) {
+	return raw;
+}
+/** dsh-engram 统一错误：加载/使用期的可诊断失败都抛此类型。 */
+var EngramError = class extends Error {
+	/** 机器可读原因码，如 EMBEDDER_DOWNLOAD_FAILED / SCHEMA_INCOMPATIBLE。 */
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "EngramError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/embedder/local.ts
+/**
+* transformers.js 本地嵌入实现：Xenova/bge-small-zh-v1.5，量化权重（q8），离线推理。
+* 模型首次使用需联网下载到 cacheDir；之后完全离线，数据不出机。
+* @module @kenz1117/dsh-engram/embedder/local
+*/
+/** 模型标识（bge 中文小模型，512 维输出）。 */
+const ENGRAM_MODEL_ID = "Xenova/bge-small-zh-v1.5";
+/** 进程内单例：重复调用 createLocalEmbedder 共享同一模型实例，避免重复加载权重。 */
+let cached;
+/**
+* 创建本地嵌入器。
+* @param cacheDir - 模型缓存目录；不存在会自动创建（0o700）。
+* @param remoteHost - 模型下载端点；默认 huggingface.co，网络受限环境可配镜像（如 https://hf-mirror.com）。
+* @returns 就绪的 EngramEmbedder。
+* @throws EngramError(code=EMBEDDER_DOWNLOAD_FAILED) 模型下载/加载失败（调用方据此降级）。
+*/
+async function createLocalEmbedder(cacheDir, remoteHost) {
+	if (cached?.dir === cacheDir) return cached.embedder;
+	await mkdir(cacheDir, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		const { pipeline, env } = await import("@huggingface/transformers");
+		env.cacheDir = cacheDir;
+		if (remoteHost !== void 0 && remoteHost !== "") env.remoteHost = remoteHost;
+		const extractor = await pipeline("feature-extraction", ENGRAM_MODEL_ID, { dtype: "q8" });
+		const embedder = {
+			model: ENGRAM_MODEL_ID,
+			async embed(texts) {
+				if (texts.length === 0) return [];
+				return (await extractor([...texts], {
+					pooling: "mean",
+					normalize: true
+				})).tolist().map((list) => new Float32Array(list));
+			},
+			close: async () => {
+				if (cached?.embedder === embedder) cached = void 0;
+			}
+		};
+		cached = {
+			dir: cacheDir,
+			embedder
+		};
+		return embedder;
+	} catch (error) {
+		throw new EngramError("EMBEDDER_DOWNLOAD_FAILED", "嵌入模型下载/加载失败；检索已降级为纯关键词模式，可检查网络后重试", { cause: error });
+	}
+}
+//#endregion
+//#region src/llm/client.ts
+/**
+* 辅助 LLM 调用客户端：封装 ctx.llm.stream + BlockAssembler，路由从会话日志解析。
+* 遵守 model-visible ⟺ logged：每次辅助调用的完整请求由调用方 append 到会话日志。
+* @module @kenz1117/dsh-engram/llm/client
+*/
+/** 从会话事件流解析最近一条模型路由（request/header → header.config）。 */
+function routeFromEvents(events) {
+	for (let i = events.length - 1; i >= 0; i--) {
+		const event = events[i];
+		if (event?.type !== "request/header") continue;
+		const config = event.data?.header?.config;
+		if (typeof config?.provider === "string" && typeof config?.model === "string" && config.provider !== "" && config.model !== "") return {
+			provider: config.provider,
+			model: config.model
+		};
+	}
+}
+/** 从模型输出提取 JSON 数组：剥 Markdown 代码栅栏后解析；无有效数组返回 undefined。 */
+function parseJsonArray(text) {
+	const candidate = (/```(?:json)?\s*([\s\S]*?)```/.exec(text)?.[1] ?? text).trim();
+	const start = candidate.indexOf("[");
+	const end = candidate.lastIndexOf("]");
+	if (start < 0 || end <= start) return void 0;
+	try {
+		const parsed = JSON.parse(candidate.slice(start, end + 1));
+		return Array.isArray(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+/** 终止原因转错误（session-title-llm 同款语义）。 */
+function finishError(finish) {
+	switch (finish.kind) {
+		case "stop": return;
+		case "error":
+		case "aborted": {
+			const error = new Error(finish.failure.message);
+			error.code = finish.failure.code;
+			return error;
+		}
+		case "max-tokens": return /* @__PURE__ */ new Error("dsh-engram: 辅助调用输出达到 maxTokens 上限");
+		case "tool-calls": return /* @__PURE__ */ new Error("dsh-engram: 辅助调用意外请求工具");
+		default: return /* @__PURE__ */ new Error(`dsh-engram: 不支持的终止原因 "${String(finish.kind)}"`);
+	}
+}
+/**
+* 一次辅助 LLM 调用：流式收集文本输出。
+* @param ctx - 提供 llm 服务的上下文。
+* @param params.route - 模型路由（来自日志解析或显式配置）。
+* @param params.system - 系统指令。
+* @param params.userText - 用户侧 JSON 框定输入。
+* @param params.sessionId - 归属会话 id 字符串（调用方来自 agent.session.id，内部转 branded）。
+* @param params.maxTokens - 输出上限。
+* @param params.purpose - 用途标记（宿主 purpose 枚举未开放第三方注册，运行时经 cast 传入，
+*   token-meter 归因由 sessionId/provider/model 承载）。
+* @param params.signal - 取消信号。
+* @returns 模型输出全文。
+*/
+async function streamText(ctx, params) {
+	const messages = [{
+		role: "user",
+		content: [{
+			type: "text",
+			text: params.userText
+		}],
+		source: {
+			kind: "plugin",
+			plugin: "dsh-engram"
+		}
+	}];
+	const options = {
+		provider: params.route.provider,
+		model: params.route.model,
+		messages,
+		system: params.system,
+		maxTokens: params.maxTokens,
+		sessionId: params.sessionId,
+		purpose: params.purpose,
+		signal: params.signal
+	};
+	const assembler = new BlockAssembler();
+	for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk);
+	const terminalError = finishError(assembler.finish);
+	if (terminalError !== void 0) throw terminalError;
+	const text = assembler.blocks().filter((block) => block.type === "text").map((block) => block.text).join("");
+	if (text.trim() === "") throw new EngramError("LLM_EMPTY_OUTPUT", "辅助调用返回空输出");
+	return text;
+}
+//#endregion
+//#region src/ingest/hook.ts
+/** 档位参数（协议内常量，非部署 tunables）。 */
+const MODE_LIMITS = {
+	light: {
+		maxCandidates: 2,
+		confidence: .3,
+		includeAssistant: false
+	},
+	eager: {
+		maxCandidates: 5,
+		confidence: .4,
+		includeAssistant: true
+	}
+};
+/** 摄取输出 token 上限（提取 JSON 数组，短输出足够）。 */
+const INGEST_MAX_TOKENS = 600;
+const INGEST_SYSTEM = [
+	"从对话记录中提取值得跨会话长期记住的用户信息（事实/偏好/决策/经历/做事方法）。",
+	"只输出一个 JSON 数组，每项形如 {\"content\": \"一句话完整表述\", \"kind\": \"fact|preference|decision|episode|skill\", \"importance\": 0到1的小数}。",
+	"只提取明确、可复用的信息；寒暄、临时上下文、你自己的回答不要提取。没有值得记的就输出 []。",
+	"不要输出 JSON 以外的任何内容。"
+].join("\n");
+/** 从事件里按类型收集文本块，跳过插件注入的 user 快照（它们不是用户说的话）。 */
+function collectTexts(events, includeAssistant) {
+	const texts = [];
+	let minSeq = null;
+	for (const event of events) if (event.type === "user/message") {
+		const data = event.data;
+		if (data?.source?.kind === "plugin") continue;
+		const segments = (data?.content ?? []).filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text);
+		if (segments.length > 0) {
+			texts.push(...segments);
+			if (event.seq !== void 0 && (minSeq === null || event.seq < minSeq)) minSeq = event.seq;
+		}
+	} else if (includeAssistant && event.type === "assistant/message") {
+		const segments = (event.data?.content ?? []).filter((block) => block?.type === "text" && typeof block.text === "string").map((block) => block.text);
+		if (segments.length > 0) texts.push(...segments);
+	}
+	return {
+		texts,
+		minSeq
+	};
+}
+/** 上一轮事件切片：最后一个 turn/start 之前的那一轮（含其中的全部事件）。 */
+function previousTurnSlice(events) {
+	const starts = [];
+	for (let i = 0; i < events.length; i++) if (events[i]?.type === "turn/start") starts.push(i);
+	if (starts.length < 2) return [];
+	const previousStart = starts[starts.length - 2];
+	const currentStart = starts[starts.length - 1];
+	return events.slice(previousStart, currentStart);
+}
+/**
+* 执行一次上一轮摄取。
+* @returns 结果摘要；异常由调用方捕获计数（不重试）。
+*/
+async function ingestPreviousTurn(deps) {
+	const limits = MODE_LIMITS[deps.mode];
+	const slice = previousTurnSlice(deps.events);
+	if (slice.length === 0) return {
+		scannedEvents: 0,
+		candidates: 0,
+		written: 0,
+		skipped: "no-previous-turn"
+	};
+	const { texts, minSeq } = collectTexts(slice, limits.includeAssistant);
+	if (texts.length === 0) return {
+		scannedEvents: slice.length,
+		candidates: 0,
+		written: 0,
+		skipped: "no-user-content"
+	};
+	const route = deps.routeOverride ?? routeFromEvents(deps.events);
+	if (route === void 0) return {
+		scannedEvents: slice.length,
+		candidates: 0,
+		written: 0,
+		skipped: "no-route-in-log"
+	};
+	const userText = `从下面这轮对话（JSON 数组）提取值得长期记住的信息：\n${JSON.stringify(texts)}`;
+	deps.logRequest({
+		route,
+		round: Math.max(0, deps.turn - 1),
+		userText,
+		maxTokens: INGEST_MAX_TOKENS,
+		mode: deps.mode
+	});
+	const parsed = parseJsonArray(await deps.call({
+		route,
+		system: INGEST_SYSTEM,
+		userText,
+		maxTokens: INGEST_MAX_TOKENS,
+		purpose: "engram-ingest",
+		signal: deps.signal
+	}));
+	if (parsed === void 0) return {
+		scannedEvents: slice.length,
+		candidates: 0,
+		written: 0,
+		skipped: "unparseable-output"
+	};
+	const store = await deps.openStore();
+	const embedder = await deps.embedder;
+	const writtenContents = [];
+	let written = 0;
+	for (const item of parsed.slice(0, limits.maxCandidates)) {
+		const candidate = item;
+		if (typeof candidate.content !== "string" || candidate.content.trim() === "") continue;
+		const content = candidate.content.trim();
+		const kind = typeof candidate.kind === "string" && [
+			"fact",
+			"preference",
+			"decision",
+			"episode",
+			"skill"
+		].includes(candidate.kind) ? candidate.kind : "fact";
+		const importance = typeof candidate.importance === "number" && Number.isFinite(candidate.importance) ? Math.min(1, Math.max(0, candidate.importance)) : .5;
+		if (embedder !== void 0) {
+			const vector = (await embedder.embed([content]))[0];
+			if (vector !== void 0 && (await store.findContradictions(vector, 1)).length > 0) continue;
+		}
+		if (writtenContents.includes(content)) continue;
+		await store.write({
+			scope: "user",
+			kind,
+			content,
+			importance,
+			confidence: limits.confidence,
+			sourceSessionId: deps.sessionId,
+			sourceRound: Math.max(0, deps.turn - 1),
+			...minSeq === null ? {} : { sourceSeq: minSeq },
+			...embedder === void 0 ? {} : { embedding: (await embedder.embed([content]))[0] }
+		});
+		writtenContents.push(content);
+		written += 1;
+	}
+	return {
+		scannedEvents: slice.length,
+		candidates: parsed.length,
+		written,
+		skipped: null
+	};
+}
+//#endregion
+//#region src/store/sqlite.ts
+/**
+* EngramStore 的 node:sqlite 实现：节点表 + 边表 + FTS5（unicode61 + 中文 2-gram 预切词）
+* + 操作日志，单调 SCHEMA_VERSION，打开时校验、不兼容拒绝加载（不写兼容 shim）。
+* 事务用手工 BEGIN/COMMIT——DatabaseSync.prototype.transaction 仅新引擎可用，
+* 本包声明兼容 node ^22.19。
+* @module @kenz1117/dsh-engram/store/sqlite
+*/
+/** 当前 schema 版本；结构性变更必须 +1 并拒绝旧库（pre-release 无兼容承诺）。 */
+const SCHEMA_VERSION = 2;
+/** RRF 融合常数：score = Σ 1/(K + rank)。 */
+const RRF_K = 60;
+/** 向量道的语义门槛：低于该余弦的条目不参与排序。 */
+const MIN_COSINE = .2;
+/** 矛盾候选门槛：近邻余弦达到该值即报告（由模型/用户裁决）。 */
+const CONTRADICTION_COSINE = .88;
+/** 每道参与融合的候选上限。 */
+const RANK_POOL = 64;
+/** 一跳扩展引入的邻居上限。 */
+const EXPANSION_LIMIT = 32;
+/** 命中强化：每次检索命中的置信度增量。 */
+const CONFIDENCE_BUMP = .05;
+/** 审计视图返回的操作日志条数上限。 */
+const REVIEW_LOG_LIMIT = 20;
+function rowToRecord(row) {
+	return {
+		id: asMemoryId(row.id),
+		scope: row.scope,
+		kind: row.kind,
+		content: row.content,
+		importance: row.importance,
+		confidence: row.confidence,
+		status: row.status,
+		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
+	};
+}
+function blobToVec(blob) {
+	return new Float32Array(blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength));
+}
+function vecToBlob(vector) {
+	return new Uint8Array(vector.buffer, vector.byteOffset, vector.byteLength);
+}
+/** 余弦相似度；任一向量零范数时返回 0。 */
+function cosine(a, b) {
+	let dot = 0;
+	let na = 0;
+	let nb = 0;
+	const len = Math.min(a.length, b.length);
+	for (let i = 0; i < len; i++) {
+		dot += a[i] * b[i];
+		na += a[i] * a[i];
+		nb += b[i] * b[i];
+	}
+	if (na === 0 || nb === 0) return 0;
+	return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+* 中文 2-gram + 西文词元切词：unicode61 把连续汉字当作单个 token，无法支撑短语检索，
+* 因此入库与查询前都把中文按两字窗口切开、西文按词保留，用空格分隔交给 FTS5。
+*/
+function tokenizeForFts(text) {
+	const tokens = [];
+	for (const segment of text.split(/([a-zA-Z0-9_]+)/)) {
+		if (segment === "") continue;
+		if (/^[a-zA-Z0-9_]+$/.test(segment)) {
+			tokens.push(segment.toLowerCase());
+			continue;
+		}
+		const cjk = segment.replace(/\s+/gu, "");
+		if (cjk.length === 1) tokens.push(cjk);
+		else for (let i = 0; i + 2 <= cjk.length; i++) tokens.push(cjk.slice(i, i + 2));
+	}
+	return tokens.join(" ");
+}
+/** 把切词结果转成 FTS5 MATCH 表达式（每个词元双引号包裹，OR 连接）；无有效词元返回 undefined。 */
+function ftsMatchExpression(text) {
+	const tokens = tokenizeForFts(text).split(" ").filter((token) => token !== "");
+	if (tokens.length === 0) return void 0;
+	return tokens.map((token) => `"${token.replaceAll("\"", "\"\"")}"`).join(" OR ");
+}
+/**
+* 打开（必要时创建）一个 scope 分库。
+* @param path - SQLite 文件路径；目录不存在会自动创建（0o700）。
+* @returns 就绪的 EngramStore。
+* @throws EngramError(code=SCHEMA_INCOMPATIBLE) 当库的 schema 版本高于当前实现。
+*/
+async function openEngramStore(path) {
+	await mkdir(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	const { DatabaseSync } = await import("node:sqlite");
+	const db = new DatabaseSync(path);
+	/** 手工事务：BEGIN/COMMIT/ROLLBACK（兼容 ^22.19 引擎范围）。 */
+	const withTransaction = (fn) => {
+		db.exec("BEGIN");
+		try {
+			fn();
+			db.exec("COMMIT");
+		} catch (error) {
+			db.exec("ROLLBACK");
+			throw error;
+		}
+	};
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS nodes (
+      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);
+    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 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}）后重试`);
+	}
+	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, ?, ?, ?, ?)`);
+	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 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 sqlOpLogById = db.prepare("SELECT at, op, detail FROM op_log WHERE target_id = ? ORDER BY seq DESC LIMIT ?");
+	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(?))
+    AND type IN ('supports','refines','related') LIMIT ?`);
+	const sqlEdgesTouching = db.prepare("SELECT from_id, to_id, type FROM edges WHERE from_id = ? OR to_id = ?");
+	const sqlCountBy = db.prepare("SELECT status, COUNT(*) AS n FROM nodes GROUP BY status");
+	const sqlCountKind = db.prepare("SELECT kind, COUNT(*) AS n FROM nodes GROUP BY kind");
+	const sqlCountEdges = db.prepare("SELECT COUNT(*) AS n FROM edges");
+	const sqlCountOpLog = db.prepare("SELECT COUNT(*) AS n FROM op_log");
+	const sqlAllNodes = db.prepare("SELECT * FROM nodes ORDER BY created_at");
+	const sqlAllEdges = db.prepare("SELECT * FROM edges");
+	const sqlDecay = db.prepare(`UPDATE nodes SET status = 'archived'
+    WHERE status = 'active' AND importance < ? AND last_accessed_at < ?`);
+	const sqlPurgeNodes = db.prepare("DELETE FROM nodes");
+	const sqlPurgeEdges = db.prepare("DELETE FROM edges");
+	const sqlPurgeFts = db.prepare("DELETE FROM nodes_fts");
+	const sqlPurgeLog = db.prepare("DELETE FROM op_log");
+	/** FTS 道：按 scope 集合检索（占位符动态生成，scope 集合由调用方去重）。 */
+	const ftsSearch = (match, scopes) => {
+		const placeholders = scopes.map(() => "?").join(",");
+		return db.prepare(`SELECT n.* FROM nodes_fts f JOIN nodes n ON n.id = f.node_id
+      WHERE nodes_fts MATCH ? AND n.status = 'active' AND n.scope IN (${placeholders})
+      ORDER BY bm25(nodes_fts) LIMIT ${RANK_POOL}`).all(match, ...scopes);
+	};
+	/** 向量候选池：active 且带向量的条目，按 scope 集合过滤（占位符动态生成）。 */
+	const vectorPool = (scopes) => {
+		const placeholders = scopes.map(() => "?").join(",");
+		return db.prepare(`SELECT * FROM nodes WHERE status = 'active' AND embedding IS NOT NULL AND scope IN (${placeholders})`).all(...scopes);
+	};
+	const getRow = (id) => sqlGet.get(id);
+	/**
+	* 写入公共体：插入节点 + FTS + 操作日志（不建边、不开事务）。
+	* 事务由调用方持有（withTransaction）。
+	*/
+	const insertRecord = (id, input, content, importance, confidence, at, sourceSessionId, embedding, 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);
+		sqlFtsInsert.run(id, tokenizeForFts(content));
+		sqlLog.run(at, op, id, JSON.stringify({
+			kind: input.kind,
+			scope: input.scope
+		}));
+	};
+	/** 邻居收集：该 id 触及的全部边按类型分组（supersedes 分方向）。 */
+	const edgeGroups = (id) => {
+		const rows = sqlEdgesTouching.all(id, id);
+		const supersededBy = [];
+		const supersedes = [];
+		const contradicts = [];
+		const related = [];
+		for (const edge of rows) if (edge.type === "supersedes") {
+			if (edge.to_id === id) supersededBy.push(edge.from_id);
+			else supersedes.push(edge.to_id);
+		} else if (edge.type === "contradicts") contradicts.push(edge.from_id === id ? edge.to_id : edge.from_id);
+		else if (edge.type === "related" || edge.type === "supports" || edge.type === "refines") related.push(edge.from_id === id ? edge.to_id : edge.from_id);
+		return {
+			supersededBy: supersededBy.map(asMemoryId),
+			supersedes: supersedes.map(asMemoryId),
+			contradicts: contradicts.map(asMemoryId),
+			related: related.map(asMemoryId)
+		};
+	};
+	return {
+		async write(input) {
+			const content = input.content.trim();
+			if (content === "") throw new EngramError("EMPTY_CONTENT", "content 不能为空");
+			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");
+			});
+			return rowToRecord(sqlGet.get(id));
+		},
+		async get(id) {
+			const row = getRow(id);
+			return row === void 0 ? void 0 : rowToRecord(row);
+		},
+		async search(query, queryVector) {
+			const limit = query.limit ?? 8;
+			const scores = /* @__PURE__ */ new Map();
+			const match = ftsMatchExpression(query.text);
+			if (match !== void 0) ftsSearch(match, query.scopes).forEach((row, index) => {
+				scores.set(row.id, {
+					score: 1 / (RRF_K + index + 1),
+					via: "fts"
+				});
+			});
+			let degraded = true;
+			if (queryVector !== void 0) {
+				degraded = false;
+				vectorPool(query.scopes).map((row) => ({
+					row,
+					sim: cosine(queryVector, blobToVec(row.embedding))
+				})).filter((entry) => entry.sim >= MIN_COSINE).sort((a, b) => b.sim - a.sim).slice(0, RANK_POOL).forEach((entry, index) => {
+					const add = 1 / (RRF_K + index + 1);
+					const existing = scores.get(entry.row.id);
+					if (existing === void 0) scores.set(entry.row.id, {
+						score: add,
+						via: "vec"
+					});
+					else scores.set(entry.row.id, {
+						score: existing.score + add,
+						via: "both"
+					});
+				});
+			}
+			const topIds = [...scores.entries()].sort((a, b) => b[1].score - a[1].score).slice(0, limit).map(([id]) => id);
+			const viaEdgeOf = /* @__PURE__ */ new Map();
+			if (topIds.length > 0) {
+				const edges = sqlNeighbors.all(JSON.stringify(topIds), EXPANSION_LIMIT);
+				for (const edge of edges) {
+					if (scores.has(edge.to) || !topIds.includes(edge.from)) continue;
+					const row = getRow(edge.to);
+					if (row === void 0 || row.status !== "active" || !query.scopes.includes(row.scope)) continue;
+					const baseScore = scores.get(edge.from)?.score;
+					if (baseScore === void 0) continue;
+					scores.set(edge.to, {
+						score: baseScore * .5,
+						via: "fts"
+					});
+					viaEdgeOf.set(edge.to, {
+						from: asMemoryId(edge.from),
+						type: edge.type
+					});
+				}
+			}
+			const finalRows = [...scores.entries()].sort((a, b) => b[1].score - a[1].score).slice(0, limit);
+			const hits = [];
+			for (const [id, info] of finalRows) {
+				const row = getRow(id);
+				if (row === void 0) continue;
+				const viaEdge = viaEdgeOf.get(id);
+				hits.push({
+					record: rowToRecord(row),
+					score: info.score,
+					via: info.via,
+					...viaEdge === void 0 ? {} : { viaEdge }
+				});
+				sqlTouch.run(Date.now(), id);
+			}
+			return {
+				hits,
+				degraded
+			};
+		},
+		async timeline(query) {
+			const limit = query.limit ?? 20;
+			const placeholders = query.scopes.map(() => "?").join(",");
+			return db.prepare(`SELECT * FROM nodes WHERE status = 'active' AND scope IN (${placeholders})
+        AND (? IS NULL OR created_at >= ?) AND (? IS NULL OR created_at <= ?)
+        AND (? IS NULL OR instr(content, ?) > 0)
+        ORDER BY created_at DESC LIMIT ?`).all(...query.scopes, query.since ?? null, query.since ?? null, query.until ?? null, query.until ?? null, query.topic ?? null, query.topic ?? null, limit).map(rowToRecord);
+		},
+		async update(input) {
+			const old = getRow(input.id);
+			if (old === void 0) throw new EngramError("NOT_FOUND", `条目 ${input.id} 不存在`);
+			const content = input.content.trim();
+			if (content === "") throw new EngramError("EMPTY_CONTENT", "content 不能为空");
+			const id = asMemoryId(randomUUID());
+			const at = Date.now();
+			withTransaction(() => {
+				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");
+				sqlEdgeUpsert.run(id, input.id, "supersedes", at);
+			});
+			return rowToRecord(sqlGet.get(id));
+		},
+		async forget(id) {
+			if (getRow(id) === void 0) throw new EngramError("NOT_FOUND", `条目 ${id} 不存在`);
+			sqlSetStatus.run("forgotten", Date.now(), id);
+			sqlLog.run(Date.now(), "forget", id, null);
+			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);
+			sqlLog.run(Date.now(), "restore", id, null);
+			return rowToRecord(sqlGet.get(id));
+		},
+		async topActive(scope, n) {
+			return sqlTopActive.all(scope, n).map(rowToRecord);
+		},
+		async review(id) {
+			const row = getRow(id);
+			if (row === void 0) return void 0;
+			const operations = sqlOpLogById.all(id, REVIEW_LOG_LIMIT);
+			return {
+				record: rowToRecord(row),
+				...edgeGroups(id),
+				operations
+			};
+		},
+		async stats() {
+			const statusRows = sqlCountBy.all();
+			const kindRows = sqlCountKind.all();
+			const edgeCount = sqlCountEdges.get().n;
+			const opCount = sqlCountOpLog.get().n;
+			const byStatus = {
+				active: 0,
+				archived: 0,
+				forgotten: 0
+			};
+			for (const row of statusRows) byStatus[row.status] = row.n;
+			const byKind = {};
+			for (const row of kindRows) byKind[row.kind] = row.n;
+			const active = byStatus["active"] ?? 0;
+			const archived = byStatus["archived"] ?? 0;
+			const forgotten = byStatus["forgotten"] ?? 0;
+			const total = active + archived + forgotten;
+			return {
+				total,
+				active,
+				archived,
+				forgotten,
+				byKind,
+				edges: edgeCount,
+				opLogCount: opCount,
+				signalRatio: total === 0 ? 0 : active / total
+			};
+		},
+		async exportAll() {
+			const records = sqlAllNodes.all().map(rowToRecord);
+			const edgeRows = sqlAllEdges.all();
+			return {
+				exportedAt: Date.now(),
+				records,
+				edges: edgeRows.map((edge) => ({
+					from: asMemoryId(edge.from_id),
+					to: asMemoryId(edge.to_id),
+					type: edge.type,
+					createdAt: edge.created_at
+				}))
+			};
+		},
+		async decay(options) {
+			const cutoff = Date.now() - options.olderThanDays * 864e5;
+			const result = sqlDecay.run(options.importanceBelow, cutoff);
+			const changed = Number(result.changes);
+			if (changed > 0) sqlLog.run(Date.now(), "decay", "BATCH", JSON.stringify({ archived: changed }));
+			return changed;
+		},
+		async findContradictions(embedding, limit = 3) {
+			return db.prepare("SELECT * FROM nodes WHERE status = 'active' AND embedding IS NOT NULL AND scope IN ('user','project')").all().map((row) => ({
+				row,
+				sim: cosine(embedding, blobToVec(row.embedding))
+			})).filter((entry) => entry.sim >= CONTRADICTION_COSINE).sort((a, b) => b.sim - a.sim).slice(0, limit).map((entry) => rowToRecord(entry.row));
+		},
+		async linkEdge(from, to, type) {
+			sqlEdgeUpsert.run(from, to, type, Date.now());
+		},
+		async supersedeMany(input, oldIds) {
+			const content = input.content.trim();
+			if (content === "") throw new EngramError("EMPTY_CONTENT", "content 不能为空");
+			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");
+				for (const oldId of oldIds) {
+					sqlSetStatus.run("archived", at, oldId);
+					sqlEdgeUpsert.run(id, oldId, "supersedes", at);
+				}
+			});
+			return rowToRecord(sqlGet.get(id));
+		},
+		async audit(op, targetId, detail) {
+			sqlLog.run(Date.now(), op, targetId, detail);
+		},
+		async purge() {
+			withTransaction(() => {
+				sqlPurgeNodes.run();
+				sqlPurgeEdges.run();
+				sqlPurgeFts.run();
+				sqlPurgeLog.run();
+			});
+		},
+		async close() {
+			db.close();
+		}
+	};
+}
+//#endregion
+//#region src/flywheel/distill.ts
+/**
+* 知识飞轮的蒸馏步骤：把同主题的记忆簇由辅助 LLM 合并提炼为更高层的
+* skill/fact，被合并条目归档并逐条建立 supersedes 链，新条目继承簇内
+* 置信度均值。由 `engram_distill` 工具显式触发。
+* @module @kenz1117/dsh-engram/flywheel/distill
+*/
+/** 蒸馏输入条数上限（协议内常量：单次辅助调用的可控上下文）。 */
+const DISTILL_MAX_INPUT = 30;
+/** 蒸馏输出 token 上限。 */
+const DISTILL_MAX_TOKENS = 900;
+const DISTILL_SYSTEM = [
+	"下面是一组用户的长期记忆条目。把表达同一主题或可归纳为一条规律的若干条，合并提炼为更高层的一条。",
+	"只输出一个 JSON 数组，每项形如 {\"content\": \"提炼后的一句话规律\", \"kind\": \"skill或fact\", \"importance\": 0到1, \"supersedes\": [\"被合并条目的id\", ...]}。",
+	"supersedes 必须从输入给出的 id 中选取且每组至少 1 个；无法归并的条目不要输出。没有可归并的就输出 []。",
+	"不要输出 JSON 以外的任何内容。"
+].join("\n");
+/**
+* 执行一次蒸馏。
+* @returns 结果摘要；LLM/解析失败抛错（工具层报给模型），单组写入失败中断本次。
+*/
+async function distillMemories(deps) {
+	const rows = await deps.store.topActive(deps.scope, DISTILL_MAX_INPUT);
+	if (rows.length < 2) return {
+		input: rows.length,
+		distilled: 0,
+		superseded: 0
+	};
+	const userText = `记忆条目：\n${rows.map((record) => `[${record.id}] (${record.kind}, importance ${record.importance.toFixed(2)}) ${record.content}`).join("\n")}`;
+	deps.logRequest({
+		route: deps.route,
+		scope: deps.scope,
+		userText,
+		maxTokens: DISTILL_MAX_TOKENS
+	});
+	const parsed = parseJsonArray(await deps.call({
+		route: deps.route,
+		system: DISTILL_SYSTEM,
+		userText,
+		maxTokens: DISTILL_MAX_TOKENS,
+		purpose: "engram-distill",
+		signal: deps.signal
+	}));
+	if (parsed === void 0 || parsed.length === 0) return {
+		input: rows.length,
+		distilled: 0,
+		superseded: 0
+	};
+	const validIds = new Set(rows.map((record) => String(record.id)));
+	const byId = new Map(rows.map((record) => [String(record.id), record]));
+	let distilled = 0;
+	let superseded = 0;
+	for (const item of parsed) {
+		const candidate = item;
+		if (typeof candidate.content !== "string" || candidate.content.trim() === "") continue;
+		if (!Array.isArray(candidate.supersedes) || candidate.supersedes.length === 0) continue;
+		const oldIds = [];
+		for (const rawId of candidate.supersedes) {
+			if (typeof rawId !== "string" || !validIds.has(rawId)) continue;
+			const row = await deps.store.get(asMemoryId(rawId));
+			if (row !== void 0 && row.status === "active") oldIds.push(asMemoryId(rawId));
+		}
+		if (oldIds.length === 0) continue;
+		const kind = candidate.kind === "skill" || candidate.kind === "fact" ? candidate.kind : "skill";
+		const importance = typeof candidate.importance === "number" && Number.isFinite(candidate.importance) ? Math.min(1, Math.max(0, candidate.importance)) : .7;
+		const confidences = oldIds.map((oldId) => byId.get(String(oldId))?.confidence ?? .5).filter((value) => value > 0);
+		const confidence = confidences.length === 0 ? .5 : confidences.reduce((sum, value) => sum + value, 0) / confidences.length;
+		let embedding;
+		if (deps.embedder !== void 0) {
+			const vectors = [];
+			for (const oldId of oldIds) {
+				const vector = (await deps.embedder.embed([byId.get(String(oldId))?.content ?? ""]))[0];
+				if (vector !== void 0) vectors.push(vector);
+			}
+			if (vectors.length > 0) {
+				const average = new Float32Array(vectors[0].length);
+				for (const vector of vectors) for (let i = 0; i < vector.length; i++) average[i] = (average[i] ?? 0) + vector[i] / vectors.length;
+				embedding = average;
+			}
+		}
+		await deps.store.supersedeMany({
+			scope: deps.scope,
+			kind,
+			content: candidate.content.trim(),
+			importance,
+			confidence,
+			...embedding === void 0 ? {} : { embedding }
+		}, oldIds);
+		distilled += 1;
+		superseded += oldIds.length;
+	}
+	return {
+		input: rows.length,
+		distilled,
+		superseded
+	};
+}
+//#endregion
+//#region src/tools/create.ts
+/**
+* 9 个 engram_ 工具的定义与执行器。工具 schema 保持窄参数；
+* scope 决定读写哪个分库；嵌入缺失时检索结果显式标记降级。
+* @module @kenz1117/dsh-engram/tools/create
+*/
+const KINDS = [
+	"fact",
+	"preference",
+	"decision",
+	"episode",
+	"skill"
+];
+/** 从模型参数收敛 scope（非法值或缺失回退 fallback）。 */
+function scopeOf(raw, fallback) {
+	return raw === "user" || raw === "project" ? raw : fallback;
+}
+/** 把 search scope 参数收敛为分库集合。 */
+function scopesOf(raw) {
+	if (raw === "user") return ["user"];
+	if (raw === "project") return ["project"];
+	return ["user", "project"];
+}
+/** 查询向量：嵌入可用时返回查询文本的向量，否则 undefined（降级）。 */
+async function queryVectorOf(deps, text) {
+	const embedder = await deps.embedder;
+	if (embedder === void 0 || text.trim() === "") return void 0;
+	return (await embedder.embed([text.trim()]))[0];
+}
+/**
+* 构造 9 个工具定义（engram_save/search/timeline/update/forget/review/stats/export/distill）。
+* @param deps - 分库打开器、嵌入器、辅助 LLM、导出目录。
+* @returns 可直接 register 的工具定义数组。
+*/
+function createEngramTools(deps) {
+	return [
+		defineTool({
+			name: "engram_save",
+			description: "保存一条长期记忆（跨会话可用）。kind：fact 事实 / preference 偏好 / decision 决策 / episode 经历 / skill 方法。scope：project 仅当前项目，user 全局。",
+			parameters: {
+				content: {
+					type: "string",
+					required: true,
+					description: "记忆正文，一句话完整表达"
+				},
+				kind: {
+					type: "string",
+					enum: [...KINDS],
+					required: true,
+					description: "记忆种类"
+				},
+				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",
+							required: true
+						},
+						kind: {
+							type: "string",
+							required: true
+						},
+						importance: {
+							type: "number",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `已保存记忆 ${value.id}（kind=${value.kind}, importance=${value.importance}）。后续会话可用 engram_search 召回。`
+				}]
+			},
+			async execute(args, exec) {
+				const input = args;
+				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([input.content.trim()]);
+				const record = await store.write({
+					scope,
+					kind: input.kind,
+					content: input.content,
+					...input.importance === void 0 ? {} : { importance: input.importance },
+					sourceSessionId: exec.agent?.id ?? null,
+					...embeddings === void 0 ? {} : { embedding: embeddings[0] }
+				});
+				if (embeddings?.[0] !== void 0) {
+					const candidates = await store.findContradictions(embeddings[0]);
+					for (const candidate of candidates) await store.linkEdge(record.id, candidate.id, "contradicts");
+					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 去重。`
+						};
+					}
+				}
+				return {
+					id: record.id,
+					kind: record.kind,
+					importance: record.importance
+				};
+			}
+		}),
+		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"
+				}
+			},
+			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) {
+				const input = args;
+				const scopes = scopesOf(input.scope);
+				const limit = input.limit ?? 8;
+				const vector = await queryVectorOf(deps, input.query);
+				const results = await Promise.all(scopes.map(async (scope) => {
+					return (await deps.openStore(scope)).search({
+						text: input.query,
+						scopes: [scope],
+						limit
+					}, vector);
+				}));
+				const merged = results.flatMap((result) => result.hits).sort((a, b) => b.score - a.score).slice(0, limit);
+				const degraded = results.some((result) => result.degraded);
+				const lines = merged.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: `${degraded && lines.length > 0 ? "（语义嵌入不可用，仅关键词检索）\n" : ""}${lines.join("\n") || "无命中"}`
+				};
+			}
+		}),
+		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: {
+					type: "string",
+					description: "结束时间"
+				}
+			},
+			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 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: (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") || "时间线为空" };
+			}
+		}),
+		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"],
+					description: "旧条目作用域，默认 project"
+				},
+				kind: {
+					type: "string",
+					enum: [...KINDS],
+					description: "种类，默认继承旧条目"
+				}
+			},
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						id: {
+							type: "string",
+							required: true
+						},
+						superseded: {
+							type: "string",
+							required: true
+						}
+					}
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: `已写入修正记忆 ${value.id}；旧条目 ${value.superseded} 已归档并建立取代链。`
+				}]
+			},
+			async execute(args) {
+				const input = args;
+				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([input.content.trim()]);
+				return {
+					id: (await store.update({
+						id: input.id,
+						scope,
+						kind: input.kind ?? old.kind,
+						content: input.content,
+						...embeddings === void 0 ? {} : { embedding: embeddings[0] }
+					})).id,
+					superseded: input.id
+				};
+			}
+		}),
+		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: "审计一条记忆：查看内容、来源（会话/轮次/事件）、取代链、矛盾与关联，以及最近操作日志。",
+			parameters: {
+				id: {
+					type: "string",
+					required: true,
+					description: "条目 id"
+				},
+				scope: {
+					type: "string",
+					enum: ["user", "project"],
+					description: "条目作用域，默认 project"
+				}
+			},
+			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 view = await (await deps.openStore(scopeOf(input.scope, "project"))).review(input.id);
+				if (view === void 0) return { text: `未找到条目 ${input.id}（用 engram_search 确认 id 与 scope）` };
+				const record = view.record;
+				const source = record.sourceSessionId === null ? "显式保存（无会话来源）" : `会话 ${record.sourceSessionId}` + (record.sourceRound === null ? "" : ` 第 ${record.sourceRound} 轮`) + (record.sourceSeq === null ? "" : `，事件 seq ${record.sourceSeq}`);
+				const section = (title, ids) => ids.length === 0 ? "" : `\n${title}: ${ids.join(", ")}`;
+				return { text: [
+					`内容: ${record.content}`,
+					`属性: kind=${record.kind}, scope=${record.scope}, status=${record.status}, importance=${record.importance}, confidence=${record.confidence}, 访问 ${record.accessCount} 次`,
+					`来源: ${source}`,
+					section("被谁取代", view.supersededBy.map(String)),
+					section("取代了谁", view.supersedes.map(String)),
+					section("矛盾候选", view.contradicts.map(String)),
+					section("关联", view.related.map(String)),
+					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") };
+			}
+		}),
+		defineTool({
+			name: "engram_stats",
+			description: "记忆库统计：各状态与种类数量、关系边数、信噪比、操作日志量。scope=all 时合并两库。",
+			parameters: { scope: {
+				type: "string",
+				enum: [
+					"user",
+					"project",
+					"all"
+				],
+				description: "作用域，默认 all"
+			} },
+			output: {
+				schema: {
+					type: "object",
+					additionalProperties: false,
+					properties: { text: {
+						type: "string",
+						required: true
+					} }
+				},
+				render: (_args, value) => [{
+					type: "text",
+					text: value.text
+				}]
+			},
+			async execute(args) {
+				const scopes = scopesOf(args.scope);
+				return { text: (await Promise.all(scopes.map(async (scope) => ({
+					scope,
+					stats: await (await deps.openStore(scope)).stats()
+				})))).map(({ scope, stats }) => [
+					`[${scope}] 总数 ${stats.total}（active ${stats.active} / archived ${stats.archived} / forgotten ${stats.forgotten}）`,
+					`种类分布: ${Object.entries(stats.byKind).map(([kind, count]) => `${kind}=${count}`).join(", ") || "空"}`,
+					`关系边 ${stats.edges} 条 · 信噪比 ${(stats.signalRatio * 100).toFixed(1)}% · 操作日志 ${stats.opLogCount} 条`
+				].join("\n")).join("\n\n") };
+			}
+		}),
+		defineTool({
+			name: "engram_export",
+			description: "把记忆库导出为文件（Markdown 或 JSON，含全部状态与关系边），返回文件路径。数据可携带。",
+			parameters: {
+				format: {
+					type: "string",
+					enum: ["markdown", "json"],
+					description: "导出格式，默认 markdown"
+				},
+				scope: {
+					type: "string",
+					enum: [
+						"user",
+						"project",
+						"all"
+					],
+					description: "作用域，默认 all"
+				}
+			},
+			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 format = input.format === "json" ? "json" : "markdown";
+				const scopes = scopesOf(input.scope);
+				await mkdir(deps.exportDir, {
+					recursive: true,
+					mode: 448
+				});
+				const written = [];
+				for (const scope of scopes) {
+					const data = await (await deps.openStore(scope)).exportAll();
+					const stamp = (/* @__PURE__ */ new Date()).toISOString().replaceAll(":", "-");
+					const path = join(deps.exportDir, `engram-${scope}-${stamp}.${format === "json" ? "json" : "md"}`);
+					const body = format === "json" ? JSON.stringify(data, null, 2) : [
+						`# dsh-engram 导出（${scope}）`,
+						"",
+						...data.records.map((record) => `- [${record.status}/${record.kind}] ${record.content}（id=${record.id}，importance ${record.importance}）`),
+						"",
+						"## 关系边",
+						...data.edges.map((edge) => `- ${edge.from} --${edge.type}--> ${edge.to}`),
+						""
+					].join("\n");
+					await writeFile(path, body, { mode: 384 });
+					written.push(`${path}（${data.records.length} 条记忆，${data.edges.length} 条边）`);
+				}
+				return { text: `已导出:\n${written.join("\n")}` };
+			}
+		}),
+		defineTool({
+			name: "engram_distill",
+			description: "蒸馏整理：把同主题的记忆簇合并提炼为更高层的规律（旧条目归档、supersedes 链保留）。建议记忆较多时周期性执行。",
+			parameters: { scope: {
+				type: "string",
+				enum: ["user", "project"],
+				description: "作用域，默认 user"
+			} },
+			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 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 route = deps.routeOverride ?? routeFromEvents(events);
+				if (route === void 0) throw new Error("engram_distill: 无法确定模型路由（会话尚无模型请求），请在 cordis.yml 配置 provider/model");
+				const embedder = await deps.embedder;
+				const outcome = await distillMemories({
+					store: await deps.openStore(scope),
+					embedder,
+					scope,
+					call: (params) => call({
+						...params,
+						sessionId: exec.agent === void 0 ? void 0 : String(exec.agent.session.id)
+					}),
+					logRequest: (data) => {
+						(async () => {
+							await (await deps.openStore(scope)).audit("distill-request", "AUX", JSON.stringify(data));
+						})().catch(() => {});
+					},
+					route,
+					signal: exec.signal
+				});
+				return { text: `蒸馏完成：取材 ${outcome.input} 条，产出 ${outcome.distilled} 条高层规律，归档 ${outcome.superseded} 条旧记忆（supersedes 链已建立，可 engram_review 审计）。` };
+			}
+		})
+	];
+}
+//#endregion
+//#region src/index.ts
+/**
+* dsh-engram：DeepSeek Harness 跨会话长期记忆插件（host 半）。
+* 注册 9 个 engram_ 工具、会话开始注入用户画像、自动摄取上一轮对话、
+* 蒸馏/衰减飞轮与审计能力。
+* @module @kenz1117/dsh-engram
+*/
+/** Cordis 插件名（loader 诊断与注入 source 使用）。 */
+const name = "dsh-engram";
+/** 必需服务：工具注册表与 LLM 流式端点（摄取/蒸馏的辅助调用）。 */
+const inject = ["tools", "llm"];
+/** 会话开始注入的画像渲染：top-N 高重要性 user 记忆一行一条。 */
+function renderProfile(topN) {
+	return [
+		"User memory profile (dsh-engram, cross-session):",
+		...topN.map((record) => `- [${record.kind}] ${record.content}`),
+		"Use engram_search to recall details; use engram_save to persist new facts."
+	].join("\n");
+}
+/**
+* agent/pre-step waterfall：每轮第一步注入画像；同时 fire-and-forget 触发
+* 上一轮的自动摄取（不阻塞请求）。必须调用 next() 委托链路；reject 决策
+* 原样透传，记忆库为空或非首轮时不追加消息。
+*/
+async function preStep(ctx, openStore, resolved, embedder, { agent, step, turn, signal }, next) {
+	const decision = await next();
+	if (decision.kind === "reject") return decision;
+	if (step === 1 && resolved.ingest !== "off" && turn > 1) ingestPreviousTurn({
+		events: agent.session.events,
+		sessionId: String(agent.id),
+		turn,
+		openStore: () => openStore("user"),
+		embedder,
+		mode: resolved.ingest,
+		routeOverride: resolved.routeOverride,
+		call: (params) => streamText(ctx, {
+			...params,
+			sessionId: agent.session.id
+		}),
+		logRequest: (data) => {
+			openStore("user").then((store) => store.audit("ingest-request", "AUX", JSON.stringify(data))).catch(() => {});
+		},
+		signal
+	}).catch((error) => {
+		console.warn("[dsh-engram] 本轮自动摄取失败（已跳过，不影响对话）：", error);
+	});
+	if (step !== 1) return decision;
+	const top = await (await openStore("user")).topActive("user", resolved.profileTopN);
+	if (top.length === 0) return decision;
+	const text = renderProfile(top);
+	return {
+		...decision,
+		messages: [...decision.messages, createUserMessage({
+			content: [{
+				type: "text",
+				text
+			}],
+			source: {
+				kind: "plugin",
+				plugin: name,
+				form: "snapshot",
+				sections: [{
+					name,
+					text
+				}]
+			}
+		})]
+	};
+}
+/**
+* 插件体：预热分库与嵌入器，注册 9 个工具、画像注入、自动摄取与衰减调度。
+* @param ctx - host 上下文。
+* @param config - cordis.yml 传入的可选配置；非法值在加载时 loud 失败。
+*/
+function apply(ctx, config = {}) {
+	const resolved = resolveConfig(config);
+	mkdir(resolved.dbDir, {
+		recursive: true,
+		mode: 448
+	});
+	const projectDbName = `project-${Buffer.from(process.cwd()).toString("hex").slice(0, 24)}.db`;
+	const stores = /* @__PURE__ */ new Map();
+	const openStore = (scope) => {
+		const existing = stores.get(scope);
+		if (existing !== void 0) return existing;
+		const created = openEngramStore(scope === "user" ? `${resolved.dbDir}/user.db` : `${resolved.dbDir}/${projectDbName}`);
+		stores.set(scope, created);
+		return created;
+	};
+	const embedder = createLocalEmbedder(resolved.modelCacheDir, resolved.hfEndpoint).catch((error) => {
+		console.warn("[dsh-engram] 嵌入器不可用，检索降级为纯关键词模式：", error);
+	});
+	for (const tool of createEngramTools({
+		openStore,
+		embedder,
+		call: (callParams) => streamText(ctx, {
+			...callParams,
+			sessionId: callParams.sessionId ?? ""
+		}),
+		routeOverride: resolved.routeOverride,
+		exportDir: `${resolved.dbDir}/exports`
+	})) ctx.tools.register(tool);
+	if (resolved.injectProfile || resolved.ingest !== "off") ctx.on("agent/pre-step", (payload, next) => preStep(ctx, openStore, resolved, embedder, payload, next), { prepend: true });
+	const runDecay = async () => {
+		for (const scope of ["user", "project"]) {
+			const archived = await (await openStore(scope)).decay({
+				importanceBelow: resolved.decayImportanceBelow,
+				olderThanDays: resolved.decayAfterDays
+			});
+			if (archived > 0) console.warn(`[dsh-engram] 衰减调度：${scope} 库归档 ${archived} 条低价值记忆（可在 engram_review 查证）`);
+		}
+	};
+	runDecay().catch((error) => {
+		console.warn("[dsh-engram] 启动衰减调度失败（跳过）：", error);
+	});
+	ctx.effect(() => {
+		const timer = setInterval(() => {
+			runDecay().catch((error) => {
+				console.warn("[dsh-engram] 周期衰减调度失败（跳过）：", error);
+			});
+		}, 864e5);
+		return () => {
+			clearInterval(timer);
+		};
+	}, "dsh-engram: decay timer");
+}
+//#endregion
+export { Config, apply, inject, name, renderProfile };