@kira905/dsh-memory-toolkit 0.0.0-stage → 0.1.1

package/dsh-memory-local/src/index.js

@@ -0,0 +1,944 @@
+/**
+ * FORK NOTICE — dsh-memory-local (self-maintained fork of the official `dsh-memory`).
+ *
+ * Upstream base : dsh-memory@0.1.0  (npm dist, MIT)
+ * Base file     : lib/index.js
+ * sourceSha256: 494ca272f674918f5acfcf32327c164c6eba26fa08fc28bef50e085754c6f28c
+ * Base lines    : 421
+ * Forked        : 2026-09-20T16:15:20.970Z
+ * Fork owner    : dsh-memory-toolkit maintainers
+ *
+ * Everything below this notice is the upstream file, byte-identical. Local edits are
+ * marked with `FORK-EDIT(<date>):` line comments so upstream merges stay a diff away
+ * (merge procedure: README.md §4).
+ *
+ * This is the SOURCE OF TRUTH for the fork; `lib/index.js` is generated by `npm run build`
+ * (build = syntax check + copy + fingerprint — the upstream publishes compiled JS only,
+ * there is no TypeScript source in the npm tarball, so this fork keeps JS as its source).
+ */
+
+// ══ FORK-EDIT(2026-10-14): R1 解耦 —— 主包「运行时符号」不再静态 import ══════════════════════
+// 依据：`tools\check-decoupling.mjs` R1（禁 `@deepseek-ai/*` 的运行时静态 import，只允许 `import type`）
+//   + `docs\升级方案-2026-09-10.md` §5.2（改法 = 动态 import + 运行时可 try/catch 降级）。
+// 语义（正常宿主）与旧写法**逐点等价**：同两个包、同两个符号、同四处使用点；两个包都在 ⇒ 行为一字不变。
+// 只有主包把符号删/改名时才走降级分支（缺 schemastery ⇒ 内置最小 schema；缺 defineTool ⇒ 跳过工具注册）
+// —— 插件**永不因主包改符号而崩 boot**。
+// ⚠️ 本模块因此含 top-level await：dsh 的插件加载器实测是 `await import()`
+//   （cordis-plugin-loader lib/index.js L275/L279 · dsh-app-boot lib/index.js L185）⇒ TLA 安全；
+//   同步 `require()` 本模块会抛 `ERR_REQUIRE_ASYNC_MODULE`（本包只经 ESM import 加载）。
+const HOST_OPTIONAL_LOAD_ERRORS = [];
+let hostZ = null;
+let defineTool = null;
+try {
+	const mod = await import("@deepseek-ai/schemastery");
+	// ESM（exports.import → lib/index.mjs）/ CJS（exports.require → lib/index.cjs）两种形态都取；
+	// 双层 default 也兜（打包器把 default 再包一层时）。
+	for (const candidate of [mod?.default, mod?.default?.default, mod?.["module.exports"]]) {
+		if (typeof candidate === "function" && typeof candidate.object === "function") {
+			hostZ = candidate;
+			break;
+		}
+	}
+	if (!hostZ) HOST_OPTIONAL_LOAD_ERRORS.push("@deepseek-ai/schemastery: 导出里没有可用的 schema 工厂");
+} catch (error) {
+	HOST_OPTIONAL_LOAD_ERRORS.push(`@deepseek-ai/schemastery: ${error?.message ?? error}`);
+}
+try {
+	const mod = await import("@deepseek-ai/dsh-tools");
+	const candidate = typeof mod?.defineTool === "function"
+		? mod.defineTool
+		: (typeof mod?.default?.defineTool === "function" ? mod.default.defineTool : null);
+	if (candidate) defineTool = candidate;
+	else HOST_OPTIONAL_LOAD_ERRORS.push("@deepseek-ai/dsh-tools: 导出里没有 defineTool");
+} catch (error) {
+	HOST_OPTIONAL_LOAD_ERRORS.push(`@deepseek-ai/dsh-tools: ${error?.message ?? error}`);
+}
+/**
+* 最小 schema 兼容面 —— **仅在**主包拿不到 schemastery 时兜底（正常路径永不执行）。
+* 只实现本文件用到的四个方法；默认值与真 schemastery 逐字段一致（同一段 shape）。
+*/
+function fallbackSchemaField(kind) {
+	const field = { kind, dflt: void 0, req: false };
+	field.required = () => {
+		field.req = true;
+		return field;
+	};
+	field.default = (value) => {
+		field.dflt = value;
+		return field;
+	};
+	return field;
+}
+const fallbackZ = {
+	string: () => fallbackSchemaField("string"),
+	number: () => fallbackSchemaField("number"),
+	boolean: () => fallbackSchemaField("boolean"),
+	object: (shape) => {
+		const resolve = (input) => {
+			const source = input && typeof input === "object" ? input : {};
+			const collected = {};
+			for (const [key, field] of Object.entries(shape)) {
+				const value = source[key];
+				if (value !== void 0) {
+					collected[key] = value;
+					continue;
+				}
+				if (field.req) throw new Error(`memory: config.${key} is required`);
+				collected[key] = field.dflt;
+			}
+			return collected;
+		};
+		resolve.toString = () => `{ ${Object.entries(shape).map(([k, f]) => `${k}${f.req ? "" : "?"}: ${f.kind}`).join(", ")} }`;
+		return resolve;
+	}
+};
+const z = hostZ ?? fallbackZ;
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+// FORK-EDIT(2026-09-21): 记忆引擎 v2 · S2b —— 指针注入 + memory_get（方案 §3.4/§6.1/§7）
+import os from "node:os";
+import path from "node:path";
+import { createRecallLogger } from "./recall-log.mjs";
+import { createModuleGate } from "./module-gate.mjs";
+import { createRecallInjector, lastUserText, SOURCE_KIND, SOURCE_VERSION } from "./injector.mjs";
+import { createUserMessage } from "./user-message.mjs";
+// FORK-EDIT(2026-09-21): 记忆引擎 v2 · S3b —— 表结构自检（`owner_user` / `visibility` 两列 + 索引，方案 §3.8/§3.9）
+import { ensureMemoryColumns, writeSchemaLog } from "./schema-migrate.mjs";
+// FORK-EDIT(2026-09-22): U3 adapter 接入 —— 宿主事实（ctx 服务名）收敛到适配层唯一源。
+// `inject` 是宿主契约声明、名字无法用"语义调用"消除，只能从 SVC 取常量（方案 §10.2 解法 A）。
+import { SVC } from "./host-adapter.js";
+
+//#region src/store.ts
+/** Monotonic on-disk schema version; a mismatch rebuilds the derived index. */
+const SCHEMA_VERSION = 1;
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    text TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '',
+    pinned INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS memories_recent ON memories (updated_at DESC, id DESC);
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts
+    USING fts5(text, tags, content='memories', content_rowid='id');
+  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts (rowid, text, tags) VALUES (new.id, new.text, new.tags);
+  END;
+  CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts (memories_fts, rowid, text, tags) VALUES ('delete', old.id, old.text, old.tags);
+  END;
+  CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts (memories_fts, rowid, text, tags) VALUES ('delete', old.id, old.text, old.tags);
+    INSERT INTO memories_fts (rowid, text, tags) VALUES (new.id, new.text, new.tags);
+  END;
+`;
+/**
+* Normalize a tag list to the lowercase, deduplicated, space-joined form the
+* FTS index stores, so `Foo`, `foo`, and a repeated `foo` all match `foo`.
+* @param tags - tags as supplied by the model or config.
+* @returns the normalized space-joined list, empty when nothing survives.
+*/
+function normalizeTags(tags) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const tag of tags) {
+		const normalized = tag.trim().toLowerCase().replaceAll(/\s+/g, "-");
+		if (normalized.length > 0) seen.add(normalized);
+	}
+	return [...seen].join(" ");
+}
+/**
+* Compile a free-text query into an FTS5 MATCH expression. Every token is
+* quoted, so FTS5 operators a model happens to type (`OR`, `*`, `-`, `"`) are
+* matched literally instead of changing the query's meaning or raising a
+* syntax error mid-tool-call.
+* @param query - the raw query text.
+* @returns the MATCH expression, or undefined when the query has no usable token.
+*/
+function compileMatch(query) {
+	const tokens = query.split(/[^\p{L}\p{N}_]+/u).filter((token) => token.length > 0).map((token) => `"${token}"`);
+	return tokens.length > 0 ? tokens.join(" ") : void 0;
+}
+/** Map one row to the record shape, converting SQLite's integer boolean. */
+function toRecord(row) {
+	return {
+		id: row.id,
+		text: row.text,
+		tags: row.tags,
+		pinned: row.pinned !== 0,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+/**
+* The durable memory store. One instance owns one SQLite connection; `close()`
+* is idempotent and runs from the plugin's disposer.
+*/
+var MemoryStore = class {
+	#db;
+	#closed = false;
+	/** FORK-EDIT(2026-09-21): 库不可用原因（null = 正常）。不可用时**只读接口返回空、写接口抛明确错误**。 */
+	#unavailable = null;
+	/**
+	* Open (creating if absent) the store at `path`, applying the schema.
+	* @param path - database file path, or `:memory:` for an ephemeral store.
+	*/
+	constructor(path) {
+		if (path !== ":memory:") mkdirSync(dirname(path), { recursive: true });
+		this.openWarnings = [];
+		const reason = (e) => (e && e.message ? e.message : String(e));
+		// ── FORK-EDIT(2026-09-21): 记忆引擎 v2 · S3b「绝不阻断 DSH 启动」加固 ──────────────────
+		// 背景（ROG 真机实测 2026-09-21，证据见 `docs\记忆引擎v2-S3b-交付-20260921.md` §B/C 与 §E2）：
+		//   · 库**只读**（只读挂载 / 目录 ACL 拒写）时，上游那行 `PRAGMA user_version = N` 会抛
+		//     `unable to open database file` ⇒ 构造函数抛 ⇒ 插件 apply 抛 ⇒ **表结构自检根本跑不到**；
+		//   · 库**损坏**（非 SQLite 内容）时，上游的 `SCHEMA` exec 抛 ⇒ 插件 apply 抛 ⇒
+		//     实测后果不是"记忆功能没了"，而是 **cordis 整个插件树加载失败**（3090 实例上 10 个
+		//     client 插件全部不加载，GUI 侧边栏按钮/看板/面板全消失）—— 实质等于阻断 DSH。
+		// 处置（本 fork 的行为差异，只在这两类异常库上生效，正常库上与上游逐字一致）：
+		//   ① `journal_mode` / `foreign_keys` / `user_version` 逐个软着陆（连接级设置 + 只写不读的标记）；
+		//   ② `DatabaseSync` 打开失败 或 `SCHEMA` 建表失败 ⇒ 收敛为**降级 store**（`#unavailable`）：
+		//      构造函数不抛，插件正常注册，只读接口返回空、写接口给明确错误 —— 记忆功能不可用，
+		//      但 DSH 与其余插件照常（并在日志留痕，避免静默失效）。
+		// ──────────────────────────────────────────────────────────────────────────────────
+		const softExec = (label, sql) => {
+			try {
+				this.#db.exec(sql);
+			} catch (e) {
+				this.openWarnings.push(`${label}: ${reason(e)}`);
+			}
+		};
+		try {
+			this.#db = new DatabaseSync(path);
+		} catch (e) {
+			this.#db = null;
+			this.#unavailable = `打开失败：${reason(e)}`;
+		}
+		if (this.#db) {
+			softExec("journal_mode", "PRAGMA journal_mode = DELETE; -- 2026-09-07 baidu-sync fix: WAL shm/wal files break BaiduSync; DELETE has no shm/wal");
+			softExec("foreign_keys", "PRAGMA foreign_keys = ON");
+			try {
+				this.#db.exec(SCHEMA);
+			} catch (e) {
+				this.#unavailable = `建表失败：${reason(e)}`;
+			}
+			softExec("user_version", `PRAGMA user_version = ${SCHEMA_VERSION}`);
+		}
+		// FORK-EDIT(2026-09-21): 记忆引擎 v2 · S3b —— 表结构自检（方案 §3.8 / §3.9）
+		// 幂等补 `owner_user` / `visibility` 两列 + `memories_visibility` 索引。
+		// **永不抛**：任何失败只落日志（`<home>/logs/memory-schema.log`）并置 `degraded=true`，
+		// 绝不阻断 DSH 启动（§3.8 风险与对策③）；结果挂在 `schemaCheck()` 上供上层判降级。
+		// `:memory:` 跳过 —— 临时库没有"既存库迁移"语义，跳过同时保证 fork 与上游在内存库上
+		// 逐字一致（`test/regression.mjs` 的同输入同输出对照依赖这一点）。
+		if (path === ":memory:") {
+			this.schemaCheckResult = {
+				ok: true, degraded: false, added: [], present: [], indexCreated: false, statements: [],
+				ownerUser: null, ownerSource: null, notes: [], error: null, skipped: "内存库跳过表结构自检"
+			};
+		} else if (!this.#db) {
+			this.schemaCheckResult = {
+				ok: false, degraded: true, added: [], present: [], indexCreated: false, statements: [],
+				ownerUser: null, ownerSource: null, notes: [], error: this.#unavailable, skipped: null
+			};
+		} else {
+			this.schemaCheckResult = ensureMemoryColumns(this.#db, { dbPath: path });
+		}
+		// FORK-EDIT(2026-09-21): 打开阶段的异常一律落一行日志（否则"库坏了/只读了"会与"库健康"
+		// 看起来一模一样 —— 无人抽检就静默失效）。
+		if (path !== ":memory:" && (this.#unavailable || this.openWarnings.length > 0)) {
+			writeSchemaLog({ dbPath: path }, {
+				event: this.#unavailable ? "open-unavailable" : "open-warning",
+				ok: false,
+				unavailable: this.#unavailable,
+				warnings: this.openWarnings
+			});
+		}
+	}
+	/**
+	* Store one memory.
+	* @param text - the fact to remember.
+	* @param tags - normalized tag list.
+	* @param pinned - whether it always renders in the prompt section.
+	* @returns the new record.
+	*/
+	write(text, tags, pinned) {
+		// FORK-EDIT(2026-09-21): 降级 store（库打不开/建表失败）⇒ 写接口给**明确原因**的错误，
+		// 不静默丢弃主人的记忆（上层工具会把这条错误原样带回模型）。
+		if (this.#isDown()) throw new Error(`memory: 记忆库不可用（${this.#unavailable}）—— 本次写入未落库`);
+		const now = Date.now();
+		return toRecord(this.#db.prepare("INSERT INTO memories (text, tags, pinned, created_at, updated_at) VALUES (?, ?, ?, ?, ?) RETURNING *").get(text, tags, pinned ? 1 : 0, now, now));
+	}
+	/**
+	* Full-text search over memory text and tags, best match first.
+	* @param query - free-text query; FTS operators in it are matched literally.
+	* @param limit - maximum hits to return.
+	* @returns the ranked matches, empty when the query has no usable token.
+	*/
+	search(query, limit) {
+		// FORK-EDIT(2026-09-21): 降级 store ⇒ 返回空结果（**绝不抛**：搜索失败不该打断对话回合）
+		if (this.#isDown()) return [];
+		const match = compileMatch(query);
+		if (match === void 0) return [];
+		return this.#db.prepare(`
+      SELECT m.*, memories_fts.rank AS rank
+      FROM memories_fts JOIN memories m ON m.id = memories_fts.rowid
+      WHERE memories_fts MATCH ? ORDER BY rank LIMIT ?
+    `).all(match, limit).map((row) => ({
+			...toRecord(row),
+			rank: row.rank ?? 0
+		}));
+	}
+	/**
+	* Read one memory in full by id.
+	* FORK-EDIT(2026-09-21): `memory_get` 的读取口 —— 读的是本插件的权威库
+	* （与 memory_write / memory_search 同一个 `path`），不是召回侧的只读副本连接
+	* （方案 §3.4 关 B1：指针指向的那扇门必须由本包自己开，且开的必须是同一间屋）。
+	* @param id - the record id.
+	* @returns the record, or undefined when absent.
+	*/
+	get(id) {
+		// FORK-EDIT(2026-09-21): 降级 store ⇒ 等同于"没有这条"（**绝不抛**）
+		if (this.#isDown()) return void 0;
+		const row = this.#db.prepare("SELECT * FROM memories WHERE id = ?").get(Number(id));
+		return row === void 0 ? void 0 : toRecord(row);
+	}
+	/**
+	* The memories the prompt section renders: pinned first, then most recently
+	* updated, with no record repeated.
+	* @param recentCount - how many unpinned recent memories to include.
+	* @returns pinned records followed by recent ones.
+	*/
+	forPrompt(recentCount) {
+		// FORK-EDIT(2026-09-21): 降级 store ⇒ 段渲染为空（**最关键的一处**：本方法每轮都被
+		// `memory:recall` 段调用，这里抛错会把每一轮对话都带崩，比插件加载失败更糟）
+		if (this.#isDown()) return [];
+		const pinned = this.#db.prepare("SELECT * FROM memories WHERE pinned = 1 ORDER BY updated_at DESC, id DESC").all();
+		const recent = this.#db.prepare("SELECT * FROM memories WHERE pinned = 0 ORDER BY updated_at DESC, id DESC LIMIT ?").all(recentCount);
+		return [...pinned, ...recent].map(toRecord);
+	}
+	/**
+	* Delete one memory.
+	* @param id - the record id.
+	* @returns whether a record was deleted.
+	*/
+	forget(id) {
+		// FORK-EDIT(2026-09-21): 降级 store ⇒ 等同于"没删掉任何东西"（**不谎报成功**）
+		if (this.#isDown()) return false;
+		return this.#db.prepare("DELETE FROM memories WHERE id = ?").run(id).changes > 0;
+	}
+	/**
+	* Total stored memories.
+	* @returns the row count.
+	*/
+	count() {
+		// FORK-EDIT(2026-09-21): 降级 store ⇒ 0 条（**绝不抛**）
+		if (this.#isDown()) return 0;
+		return this.#db.prepare("SELECT COUNT(*) AS n FROM memories").get().n;
+	}
+	/**
+	* FORK-EDIT(2026-09-21): 库是否**不可用** —— 打不开（没有连接）**或** 建表失败（连接在、但表建不出）。
+	* 两者都必须走降级路径：只判"连接是否为 null"会漏掉后者，实测后果是坏库上
+	* `search` / 段渲染真去执行 SQL 并抛错（每轮对话都会被带崩），见交付报告 §E-C。
+	* @returns {boolean}
+	*/
+	#isDown() {
+		return this.#db === null || this.#unavailable !== null;
+	}
+	/**
+	* FORK-EDIT(2026-09-21): 库是否处于降级（不可用）状态。
+	* @returns {boolean} true = 库打不开或建表失败，本 store 只提供空结果/明确错误。
+	*/
+	isUnavailable() {
+		return this.#isDown();
+	}
+	/**
+	* FORK-EDIT(2026-09-21): 库不可用的原因（正常时 null）。
+	* @returns {string|null}
+	*/
+	unavailableReason() {
+		return this.#unavailable;
+	}
+	/**
+	* FORK-EDIT(2026-09-21): 启动自检结果（只读快照，方案 §3.8）。
+	* `degraded === true` ⇒ 两列没加上（库被锁 / 只读 / 损坏），此时依赖 `owner_user`/`visibility`
+	* 的功能必须自我降级，**不许**假设列存在；其余功能照常。
+	* @returns {object} {@link ensureMemoryColumns} 的返回值。
+	*/
+	schemaCheck() {
+		return this.schemaCheckResult;
+	}
+	/**
+	* FORK-EDIT(2026-09-21): 打开阶段的软着陆告警（只读库上 `PRAGMA` 写不进去等）。
+	* 空数组 = 打开阶段的设置全部生效。
+	* @returns {string[]} 形如 `["user_version: unable to open database file"]`。
+	*/
+	openState() {
+		return this.openWarnings ?? [];
+	}
+	/** Close the connection; idempotent, so plugin disposal and tests may both call it. */
+	close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		// FORK-EDIT(2026-09-21): 降级 store（没有连接）也要能安全关闭 —— 否则 disposer 会抛
+		try {
+			this.#db?.close();
+		} catch {
+			/* 关闭失败不影响插件卸载 */
+		}
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const name = "memory";
+// FORK-EDIT(2026-09-22): U3 —— inject 里的两个裸服务名字符串改为适配层常量（值恒等，零语义变化）。
+const inject = [SVC.tools, SVC.systemPrompt];
+const Config = z.object({
+	path: z.string().required(),
+	promptRecentCount: z.number().default(10),
+	promptMaxChars: z.number().default(2e3),
+	maxTextChars: z.number().default(2e3),
+	searchLimitDefault: z.number().default(10),
+	searchLimitMax: z.number().default(50),
+	promptOrder: z.number().default(50),
+	// FORK-EDIT(2026-10-16): `memory:recall` 段的「会话内冻结」（harness 成本与路由线 · 主人拍板 ㈡档）。
+	// true  = 每个会话只渲染一次该段文本，会话内后续 step 复用同一份（前缀缓存稳定）；
+	// false = 旧行为（每次 assemble 重算 —— 写一次记忆，之后每一轮的前缀都从这一段起失效）。
+	promptFreezeSystem: z.boolean().default(true),
+	// 冻结快照的条数上限（本进程长跑，必须有界；超限淘汰最旧的键）。512 条 × 单段上限 2000 字 ≈ 1 MB 量级。
+	promptFreezeMax: z.number().default(512),
+	// FORK-EDIT(2026-09-21): 指针注入配置（记忆引擎 v2 §3.4）。
+	// 全部带默认值 ⇒ 缺省**不改变既有行为**；`recallEnabled` 默认 false（未过验收前不上生产，
+	// 与 L2 模块位 `memory-recall` 默认关同口径：两处都开才注入）。
+	recallEnabled: z.boolean().default(false),
+	recallHome: z.string().default(""),
+	recallMemoryDb: z.string().default(""),
+	recallVectorsDb: z.string().default(""),
+	recallBridgeHost: z.string().default("127.0.0.1"),
+	recallBridgePort: z.number().default(8201),
+	recallBridgePortScanMax: z.number().default(10),
+	recallTimeoutMs: z.number().default(300),
+	recallEncodeTimeoutMs: z.number().default(250),
+	recallMaxItems: z.number().default(8),
+	recallMaxChars: z.number().default(800),
+	recallMaxTokens: z.number().default(600),
+	recallMaxPerSession: z.number().default(3),
+	recallSummaryChars: z.number().default(80),
+	recallQueryMaxChars: z.number().default(512),
+	recallVectorTopK: z.number().default(20),
+	recallFtsTopK: z.number().default(20),
+	recallRrfK: z.number().default(60),
+	recallResultTopK: z.number().default(8),
+	recallIndexTtlMs: z.number().default(6e4)
+});
+const WRITE_DESCRIPTION = "Remember one durable fact across sessions: a user preference, a project convention, a decision and its reason, or a hard-won detail about this codebase. Write one self-contained fact per call — it will be read back with no surrounding conversation. Do NOT store transient task state (use the todo list), secrets, or anything the repository already records.";
+const SEARCH_DESCRIPTION = "Search stored memories by keyword. Pinned and recent memories already appear in your context, so search when you need something older or more specific than what you can already see.";
+const FORGET_DESCRIPTION = "Delete one stored memory by id, for a fact that is now wrong or obsolete. Ids come from memory_search or memory_write.";
+/**
+* Render one memory as a prompt line.
+* @param record - the memory to render.
+* @returns a single line carrying the id, tags, and text.
+*/
+function promptLine(record) {
+	const tags = record.tags.length > 0 ? ` [${record.tags}]` : "";
+	return `- (#${record.id}${record.pinned ? ", pinned" : ""})${tags} ${record.text}`;
+}
+/**
+* Render the prompt section body under a character budget. Pinned memories are
+* emitted first, so a budget too small for everything keeps what the deployment
+* explicitly marked as always-relevant.
+* @param records - pinned records followed by recent ones.
+* @param maxChars - the budget.
+* @returns the section text, or an empty string when nothing fits or nothing is stored.
+*/
+function renderPrompt(records, maxChars) {
+	if (records.length === 0) return "";
+	const header = "Memories you previously stored (use memory_search for anything not listed):\n";
+	const lines = [];
+	let used = 76;
+	let dropped = 0;
+	for (const record of records) {
+		const line = promptLine(record);
+		if (used + line.length + 1 > maxChars) {
+			dropped++;
+			continue;
+		}
+		lines.push(line);
+		used += line.length + 1;
+	}
+	if (lines.length === 0) return "";
+	const tail = dropped > 0 ? `\n(${dropped} more memories not shown; use memory_search)` : "";
+	return header + lines.join("\n") + tail;
+}
+/**
+* Validate the bounds the schema cannot express, so an unusable configuration
+* fails at plugin load rather than at the first tool call.
+* @param config - the schema-validated config.
+* @throws when a bound is not a positive integer, or the default search limit exceeds its cap.
+*/
+function validateConfig(config) {
+	const bounds = [
+		["promptRecentCount", config.promptRecentCount],
+		["promptMaxChars", config.promptMaxChars],
+		["maxTextChars", config.maxTextChars],
+		["searchLimitDefault", config.searchLimitDefault],
+		["searchLimitMax", config.searchLimitMax]
+	];
+	for (const [field, value] of bounds) if (!Number.isInteger(value) || value < 1) throw new Error(`memory: invalid ${field} ${value} — must be an integer >= 1`);
+	if (config.searchLimitDefault > config.searchLimitMax) throw new Error(`memory: searchLimitDefault ${config.searchLimitDefault} exceeds searchLimitMax ${config.searchLimitMax}`);
+	if (config.path.length === 0) throw new Error("memory: `path` must not be empty");
+	// FORK-EDIT(2026-09-21): 注入预算参数必须是正整数（误配在加载期就炸，不拖到第一个回合）
+	const recallBounds = [
+		["recallBridgePort", config.recallBridgePort],
+		["recallBridgePortScanMax", config.recallBridgePortScanMax],
+		["recallTimeoutMs", config.recallTimeoutMs],
+		["recallEncodeTimeoutMs", config.recallEncodeTimeoutMs],
+		["recallMaxItems", config.recallMaxItems],
+		["recallMaxChars", config.recallMaxChars],
+		["recallMaxTokens", config.recallMaxTokens],
+		["recallMaxPerSession", config.recallMaxPerSession],
+		["recallSummaryChars", config.recallSummaryChars],
+		["recallQueryMaxChars", config.recallQueryMaxChars],
+		["recallVectorTopK", config.recallVectorTopK],
+		["recallFtsTopK", config.recallFtsTopK],
+		["recallRrfK", config.recallRrfK],
+		["recallResultTopK", config.recallResultTopK],
+		["recallIndexTtlMs", config.recallIndexTtlMs]
+	];
+	for (const [field, value] of recallBounds) if (!Number.isInteger(value) || value < 1) throw new Error(`memory: invalid ${field} ${value} — must be an integer >= 1`);
+	if (config.recallEncodeTimeoutMs > config.recallTimeoutMs) throw new Error(`memory: recallEncodeTimeoutMs ${config.recallEncodeTimeoutMs} must not exceed recallTimeoutMs ${config.recallTimeoutMs}`);
+}
+/**
+ * FORK-EDIT(2026-09-21): 解析指针注入配置（记忆引擎 v2 §3.4）。
+ * 路径一律按 `DSH_HOME` 解析（跨机/隔离实例口径：不写死机器名与盘符）；测试可全部覆盖。
+ * 召回开关的**权威源 = 插件配置**（方案 §5.1 载体表），环境变量 `MEMORY_RECALL_ENABLED`
+ * 只做**临时**覆盖（不落盘）。
+ * @param {object} config - schema 校验后的配置。
+ * @returns {object} 注入器配置。
+ */
+function resolveRecallConfig(config) {
+	const home = config.recallHome || process.env.DSH_HOME || path.join(os.homedir(), ".dsh");
+	const envFlag = process.env.MEMORY_RECALL_ENABLED;
+	const envEnabled = envFlag === undefined ? null : /^(1|true|yes|on)$/i.test(String(envFlag));
+	return {
+		enabled: envEnabled === null ? Boolean(config.recallEnabled) : envEnabled,
+		envOverride: envEnabled !== null,
+		home,
+		memoryDb: config.recallMemoryDb || config.path,
+		vectorsDb: config.recallVectorsDb || path.join(home, "memory-vectors", "vectors.db"),
+		logsDir: path.join(home, "logs"),
+		bridgeHost: config.recallBridgeHost,
+		bridgePort: config.recallBridgePort,
+		bridgePortScanMax: config.recallBridgePortScanMax,
+		timeoutMs: config.recallTimeoutMs,
+		encodeTimeoutMs: config.recallEncodeTimeoutMs,
+		maxItems: config.recallMaxItems,
+		maxChars: config.recallMaxChars,
+		maxTokens: config.recallMaxTokens,
+		maxPerSession: config.recallMaxPerSession,
+		summaryChars: config.recallSummaryChars,
+		queryMaxChars: config.recallQueryMaxChars,
+		vectorTopK: config.recallVectorTopK,
+		ftsTopK: config.recallFtsTopK,
+		rrfK: config.recallRrfK,
+		resultTopK: config.recallResultTopK,
+		indexTtlMs: config.recallIndexTtlMs
+	};
+}
+/**
+* Open the store, register the three tools, and contribute the recall section.
+* @param ctx - plugin context; the store, tools, and section are disposed with it.
+* @param config - validated {@link Config}.
+*/
+function apply(ctx, config) {
+	validateConfig(config);
+	/**
+	* FORK-EDIT(2026-10-14): R1 解耦 —— 工具注册的唯一入口。
+	* `defineTool` 来自顶层动态探测；不可用（主包删/改名该符号）⇒ **跳过注册**（插件降级、不崩 boot）。
+	* 正常宿主下与 `ctx.tools.register(defineTool(def))` 逐点等价。
+	* @param definition - defineTool 的入参。
+	* @returns 是否真的注册了。
+	*/
+	const registerTool = (definition) => {
+		if (typeof defineTool !== "function") return false;
+		ctx.tools.register(defineTool(definition));
+		return true;
+	};
+	// 主包可选依赖缺失时留一行可查痕迹（不抛、不阻断 apply）。
+	if (HOST_OPTIONAL_LOAD_ERRORS.length > 0) {
+		console.warn(`[memory] 主包可选依赖降级：${HOST_OPTIONAL_LOAD_ERRORS.join("；")}`);
+	}
+	// FORK-EDIT(2026-09-21): 指针注入接线（记忆引擎 v2 · S2b · 方案 §3.4/§6.1/§7）---------
+	// 结构：logger（JSON 行 + 轮转 3×30 天）→ moduleGate（L2 模块位自我 drain）→ injector（编排）
+	const recallConfig = resolveRecallConfig(config);
+	const recallLogger = createRecallLogger({ dir: recallConfig.logsDir });
+	const moduleGate = createModuleGate({ home: recallConfig.home });
+	const injector = createRecallInjector({ config: recallConfig, logger: recallLogger, moduleGate });
+	ctx.effect(() => () => {
+		injector.close();
+		recallLogger.sweep();
+	}, "dsh-memory-local.injector");
+	// FORK-EDIT(2026-09-21): 启动后预热（后台、非阻塞）——把向量矩阵与桥探活成本挪出首个回合，
+	// 免得上线后第一次注入就顶破 300 ms 预算（真机实测踩过 524 ms 的那一次）。
+	if (recallConfig.enabled) {
+		const timer = setTimeout(() => {
+			injector.warmup().then((r) => {
+				if (!r.ok) recallLogger.log({ event: "warmup", ok: false, reason: r.reason });
+			}).catch(() => {});
+		}, 2000);
+		if (typeof timer.unref === "function") timer.unref();
+	}
+	let store;
+	ctx.effect(() => {
+		store = new MemoryStore(config.path);
+		return () => {
+			store?.close();
+			store = void 0;
+		};
+	});
+	/**
+	* The open store, or a loud failure. Reached only while the fiber is active,
+	* so an absent store is a lifecycle bug rather than an expected state.
+	* @returns the live store.
+	*/
+	function open() {
+		if (!store) throw new Error("memory: store is not open");
+		return store;
+	}
+	// FORK-EDIT(2026-10-16): `memory:recall` 段「会话内冻结」（harness 成本与路由线 · 主人拍板 ㈡档）。
+	//
+	// 为什么：下面这段 text() 在**每个 model step** 的 assemble 里都会被调用（宿主
+	// `dsh-agent-loop` → `systemPrompt.assemble(assembleContextFor(agent, signal))`，该 context
+	// 带 `{ agent, scope, signal }`），而它的内容是「最近 N 条记忆」—— 本会话里写一条记忆，
+	// 这一段就变一次，**前缀缓存从这一段起全部失效**。冻结 = 同一会话内渲染一次后复用，
+	// 缓存只在**新会话**第一轮重建。
+	//
+	// 保留（本次**不动**）：紧随其后的 `agent/pre-step` 指针注入 —— 它 append 在 messages
+	// 尾部，本来就缓存友好（上游姿势也是"前缀稳定 + append-only"）。
+	//
+	// 代价（主人在案）：本会话内**新写的记忆**在 system 常驻段看不见；尾部召回指针仍在，
+	// 实际可见性损失比"整个记忆系统冻结"小得多。
+	//
+	// 边界：① 新会话（新 agentId）按最新记忆重新渲染；② 无 agent 上下文的 assemble（宿主
+	// 内部调用）按旧行为每次重算；③ 只有**渲染成功**的结果才入缓存（抛错照旧抛、下次重试，
+	// 不改 `#isDown()` 的降级语义）；④ 快照有上限（`promptFreezeMax`，超限淘汰最旧键），
+	// 长跑进程不累积。
+	const frozenSections = new Map();
+	function renderRecallSection() {
+		return renderPrompt(open().forPrompt(config.promptRecentCount), config.promptMaxChars);
+	}
+	function recallSectionText(context) {
+		if (!config.promptFreezeSystem) return renderRecallSection();
+		const agentId = context && context.agent && context.agent.id !== void 0 ? String(context.agent.id) : null;
+		if (agentId === null) return renderRecallSection();
+		const cached = frozenSections.get(agentId);
+		if (cached !== void 0) return cached;
+		const text = renderRecallSection();
+		if (frozenSections.size >= Math.max(1, config.promptFreezeMax)) {
+			const oldest = frozenSections.keys().next();
+			if (!oldest.done) frozenSections.delete(oldest.value);
+		}
+		frozenSections.set(agentId, text);
+		return text;
+	}
+	ctx.systemPrompt.section({
+		name: "memory:recall",
+		order: config.promptOrder,
+		text: recallSectionText
+	});
+	// FORK-EDIT(2026-09-21): 指针注入 —— 每回合第一个 step 注入一条 ≤800 字召回指针。
+	// 语义（方案 §3.4）：先委派下游拿最终决策；被拒绝/信号已中止则不注入；只在 step===1；
+	// 全异常捕获（fail-open）——最坏结果 = 不注入，绝不阻塞对话。
+	ctx.on("agent/pre-step", async ({ agent, messages, turn, step, signal }, next) => {
+		const decision = await next();
+		try {
+			if (!decision || decision.kind === "reject") return decision;
+			if (signal && signal.aborted) return decision;
+			if (step !== 1) return decision;
+			const query = lastUserText(messages);
+			if (!query) return decision;
+			const sessionId = agent && agent.id ? String(agent.id) : null;
+			const result = await injector.decideWithTimeout({ query, agent, turn, step, sessionId });
+			if (result.action !== "inject") return decision;
+			return {
+				kind: "enter",
+				messages: [...decision.messages, createUserMessage({
+					content: [{ type: "text", text: result.text }],
+					// source 形态写死（方案 §3.4 v4 拍板）：自定义 kind，**不复用 form**（form:'recall' 已被 dsh-session-reference 占用）
+					source: {
+						kind: SOURCE_KIND,
+						version: SOURCE_VERSION,
+						items: result.meta.ids,
+						chars: result.meta.chars,
+						tokens: result.meta.estTokens,
+						model: result.meta.model ?? null
+					}
+				})]
+			};
+		} catch (error) {
+			// fail-open：注入链任何异常都不影响对话（方案 §7）
+			try {
+				recallLogger.log({ event: "skip", reason: "handler-exception", error: String(error && error.message ? error.message : error) });
+			} catch {
+				/* 写日志失败也不得影响对话 */
+			}
+			return decision;
+		}
+	}, { prepend: true });
+	registerTool({
+		name: "memory_write",
+		description: WRITE_DESCRIPTION,
+		parameters: {
+			text: {
+				type: "string",
+				required: true,
+				description: "The self-contained fact to remember."
+			},
+			tags: {
+				type: "array",
+				description: "Optional labels for later retrieval, e.g. [\"preference\", \"build\"].",
+				items: { type: "string" }
+			},
+			pinned: {
+				type: "boolean",
+				description: "Always show this memory in context. Reserve it for facts that matter in every session."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					id: {
+						type: "integer",
+						required: true
+					},
+					tags: {
+						type: "string",
+						required: true
+					},
+					pinned: {
+						type: "boolean",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Stored memory #${value.id}${value.pinned ? " (pinned)" : ""}.`
+			}]
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: "memory_write",
+			kind: "edit",
+			rawInput: args
+		}),
+		async execute(args) {
+			const text = args.text.trim();
+			if (text.length === 0) throw new Error("memory_write: `text` must not be blank");
+			if (text.length > config.maxTextChars) throw new Error(`memory_write: \`text\` is ${text.length} chars, over the ${config.maxTextChars} limit`);
+			const record = open().write(text, normalizeTags(args.tags ?? []), args.pinned ?? false);
+			return {
+				id: record.id,
+				tags: record.tags,
+				pinned: record.pinned
+			};
+		}
+	});
+	registerTool({
+		name: "memory_search",
+		description: SEARCH_DESCRIPTION,
+		parameters: {
+			query: {
+				type: "string",
+				required: true,
+				description: "Keywords to look for in memory text and tags."
+			},
+			limit: {
+				type: "number",
+				description: `Maximum results. Defaults to ${config.searchLimitDefault}.`
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { matches: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							id: {
+								type: "integer",
+								required: true
+							},
+							text: {
+								type: "string",
+								required: true
+							},
+							tags: {
+								type: "string",
+								required: true
+							},
+							pinned: {
+								type: "boolean",
+								required: true
+							}
+						}
+					}
+				} }
+			},
+			render: (args, value) => [{
+				type: "text",
+				text: value.matches.length === 0 ? `No memories match ${JSON.stringify(args.query)}.` : value.matches.map((match) => promptLine({
+					...match,
+					createdAt: 0,
+					updatedAt: 0
+				})).join("\n")
+			}],
+			presentationMeta: (_args, value) => ({ count: value.matches.length })
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `memory_search ${args.query}`,
+			kind: "search"
+		}),
+		async execute(args) {
+			const requested = args.limit ?? config.searchLimitDefault;
+			if (!Number.isInteger(requested) || requested < 1) throw new Error(`memory_search: \`limit\` must be an integer >= 1 (got ${requested})`);
+			return { matches: open().search(args.query, Math.min(requested, config.searchLimitMax)).map(({ id, text, tags, pinned }) => ({
+				id,
+				text,
+				tags,
+				pinned
+			})) };
+		}
+	});
+	registerTool({
+		name: "memory_forget",
+		description: FORGET_DESCRIPTION,
+		parameters: { id: {
+			type: "integer",
+			required: true,
+			description: "The memory id to delete."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					id: {
+						type: "integer",
+						required: true
+					},
+					forgotten: {
+						type: "boolean",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.forgotten ? `Forgot memory #${value.id}.` : `No memory #${value.id} to forget.`
+			}]
+		},
+		async execute(args) {
+			return {
+				id: args.id,
+				forgotten: open().forget(args.id)
+			};
+		}
+	});
+	// FORK-EDIT(2026-09-21): `memory_get` —— 指针指向的那扇门必须由本包自己开（方案 §3.4 关 B1）。
+	// 依据：官方 dsh-memory@0.1.0 只注册 memory_write / memory_search / memory_forget，`memory_get` 零命中。
+	// 只读；超 `maxTextChars` 截断并提示；每次调用留一行 `event:"expand"` 日志（展开率统计，方案 §8.2）。
+	registerTool({
+		name: "memory_get",
+		description: "Read one stored memory in full by id. Recall pointers in your context list ids and one-line summaries; call this to expand the ones you need instead of guessing their content. Read-only.",
+		parameters: { id: {
+			type: "integer",
+			required: true,
+			description: "The memory id to read, as listed in a recall pointer or returned by memory_search / memory_write."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					id: {
+						type: "integer",
+						required: true
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					tags: {
+						type: "string",
+						required: true
+					},
+					pinned: {
+						type: "boolean",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					},
+					chars: {
+						type: "integer",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text.length > 0 ? (value.truncated ? `${value.text}\n\n(truncated: memory #${value.id} is ${value.chars} chars, showing the first ${value.text.length})` : value.text) : `No memory #${value.id}.`
+			}],
+			presentationMeta: (_args, value) => ({
+				chars: value.chars,
+				truncated: value.truncated
+			})
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `memory_get #${args.id}`,
+			kind: "read"
+		}),
+		async execute(args, exec) {
+			const id = Number(args.id);
+			if (!Number.isInteger(id) || id < 1) throw new Error(`memory_get: \`id\` must be a positive integer (got ${String(args.id)})`);
+			const sessionId = exec && exec.agent && exec.agent.id ? String(exec.agent.id) : null;
+			const record = open().get(id);
+			if (record === void 0) {
+				injector.logExpand({ id, chars: 0, truncated: false, found: false, sessionId });
+				return {
+					id,
+					text: "",
+					tags: "",
+					pinned: false,
+					truncated: false,
+					chars: 0
+				};
+			}
+			const full = String(record.text ?? "");
+			const truncated = full.length > config.maxTextChars;
+			injector.logExpand({ id, chars: full.length, truncated, found: true, sessionId });
+			return {
+				id,
+				text: truncated ? full.slice(0, config.maxTextChars) : full,
+				tags: String(record.tags ?? ""),
+				pinned: Boolean(record.pinned),
+				truncated,
+				chars: full.length
+			};
+		}
+	});
+}
+
+//#endregion
+export { Config, apply, inject, name };