@yandy0725/pi-memory 1.4.0 → 2.0.0

package/src/fs-lock.ts

@@ -0,0 +1,251 @@
+import { link, open, readFile, rm, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+
+/**
+ * **跨进程**锁。只保护「毫秒级的物理写入」这一件事。
+ *
+ * 作用域分工（见 process-lock.ts 的说明）：进程内的**逻辑作用域**（单次调用、dream 整轮）由
+ * `process-lock.ts` 的 Promise 队列承担，因此这里永远只被持有一瞬间 —— 不存在「持有太久」，
+ * 也就不需要 TTL、续约心跳与存活探测。
+ *
+ * **永不自动回收**：另一个进程崩溃留下的锁没有任何人能释放它，但**也不会被自动删掉**。
+ * 原因是「移走别人的锁」无法用 POSIX 原语做到可证明安全：`link` 这个合法获取原语的条件正是
+ * 「锁路径不存在」，所以任何「先移走旧锁、再建立自己的」的接管都会产生一个空窗，其它等待者
+ * 可以合法地抢占它；一旦移走的其实是某个**活持有者**刚建立的记录，互斥就无法再恢复（把记录
+ * 挪回去又会顶掉抢占者，而路径只能容纳一条记录）。实测：把 `rm` 换成原子 `rename` 仍然会双持有，
+ * 加上「比字节 + 放回」则会把空窗拉长，同进程内可稳定复现双持有。
+ *
+ * 因此这里的策略是「安全优先」：崩溃遗留的锁**立刻**报一条可操作的错误（写明 pid / op /
+ * startedAt / 路径，并提示如何清除），由人（或 Plan B 的显式 `/memory unlock`）处理。
+ */
+export interface LockInfo {
+	pid: number;
+	hostname: string;
+	startedAt: string;
+	op: string;
+}
+
+export interface LockOptions {
+	timeoutMs: number;
+	pollMs?: number;
+	now?: () => number;
+}
+
+export class MemoryLockedError extends Error {
+	constructor(
+		readonly lockPath: string,
+		readonly holder: LockInfo | null,
+		readonly op: string,
+		/** 记录指向一个已死的本机进程，或本身无法解释 —— 没有任何人会释放它，只能人工清除。 */
+		readonly abandoned: boolean,
+	) {
+		const described = holder
+			? `${holder.op} (pid ${holder.pid}, started ${holder.startedAt})`
+			: "an unreadable record";
+		super(
+			abandoned
+				? `Memory lock at ${lockPath} is abandoned by ${described} — delete the file to clear it`
+				: `Memory is locked by ${described}`,
+		);
+		this.name = "MemoryLockedError";
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** 仅用于诊断（决定错误文案，不参与任何回收决策）。 */
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		// 只有 ESRCH（无此进程）才算死亡；EPERM 是「存在但无权限发信号」，其余意外 errno 一并按存活处理。
+		return (e as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function isLockInfo(value: unknown): value is LockInfo {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.pid === "number" &&
+		Number.isFinite(record.pid) &&
+		typeof record.hostname === "string" &&
+		typeof record.startedAt === "string" &&
+		typeof record.op === "string"
+	);
+}
+
+type LockRead =
+	/** 锁路径不存在 —— 这是「空闲」，不是「有问题」。 */
+	| { kind: "absent" }
+	/** 存在但无法解释（非 JSON、空文件、形状不对、读不到）：只有人工能清除它。 */
+	| { kind: "unreadable" }
+	| { kind: "held"; holder: LockInfo };
+
+/**
+ * 读锁的三种状态。**必须区分「不存在」与「存在但读不懂」** —— 把前者当成后者会让
+ * 「持有者刚释放、锁刚被删」被误报成「遗弃的锁」，从而在正常竞争下抛出误导性的错误。
+ */
+async function readLockState(lockPath: string): Promise<LockRead> {
+	let raw: string;
+	try {
+		raw = await readFile(lockPath, "utf8");
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT") return { kind: "absent" };
+		// 权限之类的错误：无法判断内容，按「读不懂」处理（不接管、报可操作错误）
+		return { kind: "unreadable" };
+	}
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return isLockInfo(parsed) ? { kind: "held", holder: parsed } : { kind: "unreadable" };
+	} catch {
+		return { kind: "unreadable" };
+	}
+}
+
+/**
+ * 锁的诊断视图（spec §14 的 `/memory`）。
+ *
+ * **复用私有的 `readLockState`**，不另写一份读逻辑：三态必须与获取路径同源，
+ * 否则会出现「`/memory` 说 free，下一次写入却报 locked」这种无法诊断的矛盾。
+ * 它**不判断存活、也不删任何东西**（永不自动回收）；持有者是否已死由调用方自己看 pid。
+ */
+export async function readLockStatus(
+	lockPath: string,
+): Promise<{ kind: "absent" } | { kind: "unreadable" } | { kind: "held"; holder: LockInfo }> {
+	return readLockState(lockPath);
+}
+
+type AcquireOutcome =
+	| { acquired: true }
+	| { acquired: false; holder: LockInfo | null; abandoned: boolean };
+
+/**
+ * 尝试一次获取。路径为空时不当作失败 —— 那是「刚好被释放」，直接再试一次 link（CAS 会自然地
+ * 决出唯一赢家）；两次都撞上「刚好被释放」才交回给调用方重试。
+ */
+async function acquireOnce(lockPath: string, info: LockInfo): Promise<AcquireOutcome> {
+	for (let round = 0; round < 2; round++) {
+		if (await writeExclusive(lockPath, info)) return { acquired: true };
+		const state = await readLockState(lockPath);
+		if (state.kind === "absent") continue;
+		if (state.kind === "unreadable") return { acquired: false, holder: null, abandoned: true };
+		return { acquired: false, holder: state.holder, abandoned: isAbandoned(state.holder) };
+	}
+	return { acquired: false, holder: null, abandoned: false };
+}
+
+let tempCounter = 0;
+
+/**
+ * 原子获取：先把持有者信息写进同目录的唯一临时文件，再 `link` 到锁路径。
+ *
+ * 不能用 `open(lockPath, "wx")` 后紧接着单独写内容 —— 那会让锁路径出现「存在但 0 字节」的
+ * 中间态，等待者读到空文件会把它判为「无法解释」并据为己有。link 是原子的：锁路径要么不存在，
+ * 要么内容是完整的 JSON。
+ */
+async function writeExclusive(lockPath: string, info: LockInfo): Promise<boolean> {
+	tempCounter += 1;
+	const tempPath = `${lockPath}.${process.pid}.${tempCounter}.tmp`;
+	try {
+		const handle = await open(tempPath, "wx");
+		try {
+			await handle.writeFile(JSON.stringify(info), "utf8");
+		} finally {
+			await handle.close();
+		}
+		try {
+			await link(tempPath, lockPath);
+			return true;
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code === "EEXIST") return false;
+			throw e;
+		}
+	} finally {
+		await unlink(tempPath).catch(() => {});
+	}
+}
+
+function holderInfo(op: string, now: number): LockInfo {
+	return { pid: process.pid, hostname: hostname(), startedAt: new Date(now).toISOString(), op };
+}
+
+/**
+ * 这把锁是否「已被遗弃」（没有任何人会释放它）。
+ * - 记录无法解释：没有持有者能续约，也没人能释放 —— 遗弃。
+ * - 同 host 且进程已死：持有者永远不会再释放它 —— 遗弃（这是唯一能确定的遗弃情形）。
+ * - 跨 host：存活状况不可知 —— 一律按活持有者处理，绝不接管。
+ */
+function isAbandoned(holder: LockInfo | null): boolean {
+	if (holder === null) return true;
+	return holder.hostname === hostname() && !isProcessAlive(holder.pid);
+}
+
+/**
+ * 只在锁仍是自己持有的情况下删除；否则留给真正的持有者。
+ * 记录读不懂时也**不删** —— 那是别人的状态（或需要人工处理的状态），不该由我们清理。
+ */
+async function releaseLock(lockPath: string): Promise<void> {
+	const state = await readLockState(lockPath);
+	if (state.kind === "unreadable") return;
+	if (state.kind === "held" && !isOwnRecord(state.holder)) return;
+	await rm(lockPath, { force: true });
+}
+
+function isOwnRecord(holder: LockInfo): boolean {
+	return holder.pid === process.pid && holder.hostname === hostname();
+}
+
+/** 等待获取锁（轮询 pollMs，默认 50ms）；超时或被遗弃时抛 MemoryLockedError。 */
+export async function withLock<T>(
+	lockPath: string,
+	op: string,
+	options: LockOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
+	const clock = options.now ?? Date.now;
+	const info = holderInfo(op, clock());
+	const deadline = clock() + options.timeoutMs;
+
+	for (;;) {
+		const outcome = await acquireOnce(lockPath, info);
+		if (outcome.acquired) break;
+		// 没人能释放它 → 等下去毫无意义；立刻给出可操作的错误，而不是耗满 timeout
+		if (outcome.abandoned) throw new MemoryLockedError(lockPath, outcome.holder, op, true);
+		if (clock() >= deadline) throw new MemoryLockedError(lockPath, outcome.holder, op, false);
+		await sleep(options.pollMs ?? 50);
+	}
+
+	try {
+		return await fn();
+	} finally {
+		await releaseLock(lockPath);
+	}
+}
+
+/**
+ * 只尝试一次，不等待。
+ * 活持有者占用 → 返回 null（调用方跳过本轮）；被遗弃的锁 → **抛错而不是返回 null** ——
+ * 它不会自愈，静默跳过只会让 extract 之类的后台任务永远不再运行且毫无提示。
+ */
+export async function tryWithLock<T>(
+	lockPath: string,
+	op: string,
+	options: LockOptions,
+	fn: () => Promise<T>,
+): Promise<T | null> {
+	const clock = options.now ?? Date.now;
+	const outcome = await acquireOnce(lockPath, holderInfo(op, clock()));
+	if (!outcome.acquired) {
+		if (outcome.abandoned) throw new MemoryLockedError(lockPath, outcome.holder, op, true);
+		return null;
+	}
+	try {
+		return await fn();
+	} finally {
+		await releaseLock(lockPath);
+	}
+}

package/src/index-source.ts

@@ -0,0 +1,140 @@
+import * as sdk from "@earendil-works/pi-coding-agent";
+
+/**
+ * 索引 section 的名字（spec §9.1）。pi 要求 section 名匹配 `/^[a-z][a-z0-9_-]*$/`
+ * （0.99.2 `core/system-prompt.js`），渲染为 `<memory_index>…</memory_index>`。
+ */
+export const MEMORY_INDEX_SECTION = "memory_index";
+
+/**
+ * 重放录制值所需的最小 `SessionManager` 面（结构类型）。
+ *
+ * 本地类型是 pi-coding-agent **0.80.2**，它的 `ReadonlySessionManager` 没有
+ * `buildContextEntries`（0.99.2 才加），所以这里不 import SDK 的类型，而是按结构声明：
+ * 0.80.2 能过 `tsc`，0.99.2 的实例天然满足，测试也能直接塞假对象。
+ */
+export interface ReplayableSessionManager {
+	getEntries(): unknown[];
+	getLeafId(): string | null;
+	buildContextEntries?(entries: unknown[], leafId?: string | null): unknown[];
+}
+
+/** 可注入的转换函数（测试用；生产路径从 SDK 包根动态取）。 */
+export interface ReplayOpts {
+	sessionEntryToContextMessages?: (entry: unknown) => unknown[];
+}
+
+/**
+ * 脱掉宿主为 section 值加的一层包裹（R42）。
+ *
+ * 0.99.2 `core/system-prompt.js` 把每个非 `preamble` section 渲染成
+ * `<${name}>\n${content}\n</${name}>` 之后才写进 transcript；`sessionEntryToContextMessages`
+ * 原样返回录制消息，所以重放拿到的是**带标签**的值。直接回写成 `options.sections[name]`
+ * 会被宿主二次包裹：`wrap(wrap(x)) !== wrap(x)` —— resume/fork/reload 第一轮就产生 patch
+ *（D13/D14 的头部字节恒等失效），内层闭合标签还会提前闭合外层标签。
+ *
+ * 只脱一层；不匹配（裸值、老 session、内容碰巧含标签）原样返回。
+ */
+export function unwrapSectionValue(value: string): string {
+	const prefix = `<${MEMORY_INDEX_SECTION}>\n`;
+	const suffix = `\n</${MEMORY_INDEX_SECTION}>`;
+	if (value.length >= prefix.length + suffix.length && value.startsWith(prefix) && value.endsWith(suffix)) {
+		return value.slice(prefix.length, value.length - suffix.length);
+	}
+	return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * 按 pi 的 patch 语义重放 transcript 里的 system 消息，得到「模型当前看到的 sections」。
+ *
+ * - `value === null` → **删除**该 section（pi 用 null 表示「不存在」，
+ *   `diffSystemPromptSections` 对「上一状态有、当前状态没有」正是生成 `patch[name] = null`）；
+ * - 字符串 → 覆盖值，并**保留首次插入位置**（`Map.set` 对已存在的键不改位置）——
+ *   折叠路径 `getCurrentSystemMessage` 按顺序重放，位置本身就是语义的一部分。
+ */
+export function replaySystemSections(messages: unknown[]): Map<string, string> {
+	const sections = new Map<string, string>();
+	for (const message of messages) {
+		if (!isRecord(message) || message.role !== "system") continue;
+		const patch = message.sections;
+		if (!isRecord(patch)) continue;
+		for (const [name, value] of Object.entries(patch)) {
+			if (value === null) sections.delete(name);
+			else if (typeof value === "string") sections.set(name, value);
+		}
+	}
+	return sections;
+}
+
+/**
+ * 动态取 SDK 包根的 `sessionEntryToContextMessages`。
+ *
+ * 不能写成 `import { sessionEntryToContextMessages } from "…"`：本地类型是 0.80.2，
+ * 具名导入会让 `tsc` 直接报 `has no exported member`，而这个包**不得**动 peerDependencies /
+ * lockfile。取不到就返回 null，调用方回退磁盘读（spec §19 的退路）。
+ */
+function resolveConverter(): ((entry: unknown) => unknown[]) | null {
+	const candidate = (sdk as unknown as Record<string, unknown>).sessionEntryToContextMessages;
+	return typeof candidate === "function" ? (candidate as (entry: unknown) => unknown[]) : null;
+}
+
+/**
+ * 从 transcript 里取出**录制的**索引值（D14：resume / fork / reload 必须用它，
+ * 否则被恢复会话的 system prompt 头部会被改写，折叠路径下其后的整段对话全部失去缓存）。
+ *
+ * 任何一步不可得都返回 `null`，由调用方回退磁盘读：SDK 太旧（没有转换函数）、
+ * sessionManager 形状不认识、entry 转换抛错、重放后没有这个键、或该键被 `null` patch 删除。
+ * **绝不把 `null` 当录制值返回**（spec §9.1 的 null 陷阱）。
+ *
+ * 返回值是**裸值**：宿主把 section 渲染成 `<memory_index>…</memory_index>` 后才写进
+ * transcript，所以这里要脱掉那一层再回写（R42 / `unwrapSectionValue`）。
+ */
+export function readRecordedMemoryIndex(sessionManager: unknown, opts?: ReplayOpts): string | null {
+	const toMessages = opts?.sessionEntryToContextMessages ?? resolveConverter();
+	if (!toMessages) return null;
+	if (!isRecord(sessionManager)) return null;
+	const sm = sessionManager as unknown as Partial<ReplayableSessionManager>;
+	if (typeof sm.getEntries !== "function" || typeof sm.getLeafId !== "function") return null;
+
+	let entries: unknown[] = [];
+	try {
+		const raw = sm.getEntries();
+		if (Array.isArray(raw)) entries = raw;
+	} catch {
+		return null;
+	}
+
+	let leafId: string | null = null;
+	try {
+		leafId = sm.getLeafId();
+	} catch {
+		// Finding 2 / R43：这个函数在 index.ts 的 session_start 路径上被调用，抛错会让整个
+		// session_start 失败 → memory 工具整个会话不注册。拿不到 leaf 就退化成「没有 branch」：
+		// 用全部 entry 重放，多出来的 system patch 只会被后面的覆盖或删掉。
+	}
+	if (typeof sm.buildContextEntries === "function") {
+		try {
+			const built = sm.buildContextEntries(entries, leafId);
+			if (Array.isArray(built)) entries = built;
+		} catch {
+			// 解析不出当前分支就用全部 entry：多出来的 system patch 只会被后面的覆盖或删掉
+		}
+	}
+
+	const messages: unknown[] = [];
+	for (const e of entries) {
+		try {
+			const converted = toMessages(e);
+			if (Array.isArray(converted)) messages.push(...converted);
+		} catch {
+			// 单条 entry 的形状不认识：跳过它，别让整次重放失败
+		}
+	}
+
+	const recorded = replaySystemSections(messages).get(MEMORY_INDEX_SECTION);
+	return typeof recorded === "string" ? unwrapSectionValue(recorded) : null;
+}

package/src/inject.ts

@@ -1,20 +1,36 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { join } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { runHeadlessAgent } from "./agent-runner";
 import type { SessionPersistenceConfig, ThinkLevel } from "./config";
-import { truncateForInjection } from "./index-file";
-import { parseFrontmatter } from "./topic-file";
+import type { EntryType } from "./entry-file";
+import { MEMORY_INDEX_SECTION } from "./index-source";
+import type { MemoryStore } from "./memory-store";
+import { sanitizeForInjection } from "./sanitize";
 
-export async function loadIndexSnapshot(memoryDir: string, maxLines: number, maxBytes: number): Promise<string> {
-	try {
-		const raw = await readFile(join(memoryDir, "MEMORY.md"), "utf8");
-		const { content } = truncateForInjection(raw, maxLines, maxBytes);
-		return content ? `# Memory Index\n${content}` : "";
-	} catch {
-		return "";
+/**
+ * 注入用的「按行 + 按字节」截断。原本住在 `index-file.ts`（topic 模型的索引层），
+ * 但它的两个消费者都在本文件里（索引快照 + entry 正文），因此随 v2 迁到此处，行为逐字不变。
+ */
+export function truncateForInjection(
+	content: string,
+	maxLines: number,
+	maxBytes: number,
+): { ok: boolean; content: string; truncated: boolean } {
+	const lines = content.split("\n");
+	let out = content;
+	let truncated = false;
+	if (lines.length > maxLines) {
+		out = lines.slice(0, maxLines).join("\n");
+		truncated = true;
 	}
+	if (Buffer.byteLength(out, "utf8") > maxBytes) {
+		let cut = out;
+		while (Buffer.byteLength(cut, "utf8") > maxBytes && cut.length > 0) cut = cut.slice(0, -1);
+		out = cut;
+		truncated = true;
+	}
+	if (truncated) out += `\n[truncated: memory index exceeds injection limit]`;
+	return { ok: !truncated, content: out, truncated };
 }
 
 export function buildInjection(systemPrompt: string, snapshot: string): string {
@@ -22,67 +38,98 @@ export function buildInjection(systemPrompt: string, snapshot: string): string {
 	return `${systemPrompt}\n\n${snapshot}`;
 }
 
-export interface TopicManifest {
-	filename: string;
-	name: string;
-	description: string;
-	type: string;
-	mtimeMs: number;
+/**
+ * `memory_index` section 的值（spec §9.1 / D13）：读索引 → 截断 → 净化。
+ *
+ * **不再自己加 `# Memory Index\n` 前缀**：v1 的索引快照函数会补一份头部，而 v2 的
+ * `MEMORY.md` 由 `rebuildIndex`（默认头部就是 `# Memory Index`）与迁移写入 —— 再补一次
+ * 注入文本里就有两份标题。
+ *
+ * 空索引返回 `""`（调用方仍要把 `""` 无条件写进 sections，见 `applyIndexSection`）。
+ */
+export async function buildIndexSection(store: MemoryStore, maxLines: number, maxBytes: number): Promise<string> {
+	const raw = await store.readIndex();
+	const { content } = truncateForInjection(raw, maxLines, maxBytes);
+	return sanitizeForInjection(content);
 }
 
-export async function scanTopics(memoryDir: string): Promise<TopicManifest[]> {
-	const files = (await readdir(memoryDir).catch(() => [])).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+/**
+ * 把冻结的索引值写进 `event.systemPromptOptions.sections`（就地修改这个可变对象）。
+ *
+ * 返回 `false` 表示宿主 SDK 太旧、没有 `sections`（本地类型是 0.80.2），调用方必须回退
+ * `{ systemPrompt: buildInjection(…) }`（spec §19 的退路：功能不受损，只是缓存变差）。
+ *
+ * **无条件设置**，哪怕值是 `""`：省略这个键等于告诉 pi「该 section 不应存在」，
+ * `diffSystemPromptSections` 会生成 `{ memory_index: null }`，索引被从 system prompt 里
+ * **静默删除**（spec §9.1 的 null 陷阱）。「不想改」只能靠喂回逐字节相同的值实现。
+ */
+export function applyIndexSection(systemPromptOptions: unknown, value: string): boolean {
+	const options = systemPromptOptions as { sections?: unknown } | null | undefined;
+	const sections = options?.sections;
+	if (typeof sections !== "object" || sections === null) return false;
+	(sections as Record<string, string | null>)[MEMORY_INDEX_SECTION] = value;
+	return true;
+}
 
-	const manifests: TopicManifest[] = [];
-	for (const f of files.slice(0, 200)) {
-		try {
-			const raw = await readFile(join(memoryDir, f), "utf8");
-			const meta = parseFrontmatter(raw);
-			if (!meta) continue;
-			let mtimeMs = 0;
-			try {
-				const s = await stat(join(memoryDir, f));
-				mtimeMs = s.mtimeMs;
-			} catch {
-				/* ignore */
-			}
-			manifests.push({
-				filename: f,
-				name: meta.name,
-				description: meta.description,
-				type: meta.type,
-				mtimeMs,
-			});
-		} catch {
-			/* skip unreadable files */
-		}
-	}
-	return manifests.sort((a, b) => b.mtimeMs - a.mtimeMs);
+/** 侧查询清单的一行 = 一条 entry（v1 是一个 topic 文件）。 */
+export interface EntryManifest {
+	file: string;
+	name: string;
+	description: string;
+	type: EntryType;
+	modified: string;
 }
 
+/** 清单总预算（字符）。v1 把每条 description 硬切成 80 字符，v2 改为按清单长度均分。 */
+export const SIDE_QUERY_MANIFEST_CHARS = 4000;
+/** 均分的下限：清单再长，每条也至少留 80 字符，否则侧查询没有判别依据。 */
+export const SIDE_QUERY_MIN_DESC_CHARS = 80;
+/**
+ * 清单条数上限。恢复了 v1 的界：v1 的候选集合就是 MEMORY.md 索引本身，而索引有
+ * `memIndexMaxLines`（默认 200）行上限，所以侧查询看到的条目天然有界。v2 改成扫描目录后
+ * 清单会随目录无限增长，而 `buildSideQueryTask` 每行都要带 description —— 不封顶会把 prompt
+ * 和每轮迭代开销一起拉爆。200 与索引上限同量级。
+ */
+export const SIDE_QUERY_MAX_ENTRIES = 200;
 
+/**
+ * 从 store 取清单。**不逐文件 readFile** —— mtime 缓存由 store 持有（spec §9.2），
+ * 于是每轮只付一次 `readdir` + 每文件一次 `stat`，而不是最多 200 次 `readFile`。
+ *
+ * 排序为 `modified` **降序**：新记忆优先给侧查询看（`listEntries` 是升序，这里翻过来），
+ * 然后截到 `SIDE_QUERY_MAX_ENTRIES`（Finding I2）。
+ */
+export async function scanEntries(store: MemoryStore): Promise<EntryManifest[]> {
+	const summaries = await store.listEntries();
+	return summaries
+		.map((s) => ({ file: s.file, name: s.name, description: s.description, type: s.type, modified: s.modified }))
+		.sort((a, b) =>
+			a.modified === b.modified ? a.file.localeCompare(b.file) : b.modified.localeCompare(a.modified),
+		)
+		.slice(0, SIDE_QUERY_MAX_ENTRIES);
+}
 
 export async function injectSurfacedContent(
-	memoryDir: string,
+	store: MemoryStore,
 	selectedFiles: string[],
-	maxTopicBytes: number,
+	maxEntryBytes: number,
 	maxInjectionBytes: number,
 ): Promise<string> {
 	const blocks: string[] = [];
 	let totalBytes = 0;
 
-	for (const f of selectedFiles) {
-		try {
-			const raw = await readFile(join(memoryDir, f), "utf8");
-			const { content } = truncateForInjection(raw, 999999, maxTopicBytes);
-			const block = `## ${f}\n${content}`;
-			const blockBytes = Buffer.byteLength(block, "utf8");
-			if (totalBytes + blockBytes > maxInjectionBytes) break;
-			blocks.push(block);
-			totalBytes += blockBytes;
-		} catch {
-			/* skip unreadable files */
-		}
+	for (const file of selectedFiles) {
+		// 经 store 读：v2 的注入单位是 entry 的**正文**，不是整个文件（frontmatter 不进上下文）。
+		const entry = await store.readEntry(file);
+		if (!entry) continue;
+		const { content } = truncateForInjection(entry.body, 999999, maxEntryBytes);
+		// spec §13：正文与 name 都要净化（用户/模型写进磁盘的内容可能含 `</relevant_memories>`
+		// 之类的仿冒标签）。包裹标签是我们自己生成的，不净化。
+		const block = `## ${sanitizeForInjection(entry.name)}\n${sanitizeForInjection(content)}`;
+		const blockBytes = Buffer.byteLength(block, "utf8");
+		if (totalBytes + blockBytes > maxInjectionBytes) break;
+		blocks.push(block);
+		totalBytes += blockBytes;
 	}
 
 	if (blocks.length === 0) return "";
@@ -90,20 +137,19 @@ export async function injectSurfacedContent(
 }
 
 /** Build the side-query task prompt. */
-export function buildSideQueryTask(
-	manifest: TopicManifest[],
-	userPrompt: string,
-	maxFiles: number,
-): string {
-	const lines = manifest.map((t) =>
-		`[${t.type}] ${t.filename} — ${t.description.slice(0, 80)}`,
+export function buildSideQueryTask(manifest: EntryManifest[], userPrompt: string, maxFiles: number): string {
+	// `Math.max(1, …)`：空清单不会走到这里（runSideQuery 先返回 []），但除零会得到 Infinity。
+	const perEntry = Math.max(
+		SIDE_QUERY_MIN_DESC_CHARS,
+		Math.floor(SIDE_QUERY_MANIFEST_CHARS / Math.max(1, manifest.length)),
 	);
+	const lines = manifest.map((e) => `[${e.type}] ${e.file} — ${e.description.slice(0, perEntry)}`);
 
 	return [
-		`You are a memory relevance selector. Select up to ${maxFiles} topic files most relevant to the user query.`,
+		`You are a memory relevance selector. Select up to ${maxFiles} memory files most relevant to the user query.`,
 		"If nothing matches, select none.",
 		"",
-		"=== Topic Files ===",
+		"=== Memory Files ===",
 		...lines,
 		"",
 		"=== User Query ===",
@@ -114,24 +160,24 @@ export function buildSideQueryTask(
 }
 
 /** Parse selected_files JSON from headless agent response. */
-function parseSelectedFiles(result: string, candidates: TopicManifest[], maxFiles: number): string[] {
+function parseSelectedFiles(result: string, candidates: EntryManifest[], maxFiles: number): string[] {
 	try {
 		const jsonMatch = result.match(/\{[^}]*"selected_files"[^}]*\}/s);
 		if (!jsonMatch) return [];
 		const parsed = JSON.parse(jsonMatch[0]);
 		const files: string[] = parsed.selected_files ?? [];
-		return files.filter((f: string) => candidates.some((c) => c.filename === f)).slice(0, maxFiles);
+		return files.filter((f: string) => candidates.some((c) => c.file === f)).slice(0, maxFiles);
 	} catch {
 		return [];
 	}
 }
 
-/** Run a lightweight headless side-query to select relevant topic files.
+/** Run a lightweight headless side-query to select relevant entry files.
  *  Returns [] on timeout/failure — no fallback. */
 export async function runSideQuery(
-	manifest: TopicManifest[],
+	manifest: EntryManifest[],
 	userPrompt: string,
-	injectedTopics: Set<string>,
+	injectedFiles: Set<string>,
 	maxFiles: number,
 	thinkLevel: ThinkLevel,
 	model: string | undefined,
@@ -140,7 +186,7 @@ export async function runSideQuery(
 	memoryDir: string,
 	sessionPersistence?: SessionPersistenceConfig,
 ): Promise<string[]> {
-	const candidates = manifest.filter((t) => !injectedTopics.has(t.filename));
+	const candidates = manifest.filter((entry) => !injectedFiles.has(entry.file));
 	if (candidates.length === 0) return [];
 	const task = buildSideQueryTask(candidates, userPrompt, maxFiles);
 	try {
@@ -153,6 +199,8 @@ export async function runSideQuery(
 			thinkLevel,
 			maxTurns: 1,
 			timeoutMs: 30_000,
+			// 侧查询没有任何 customTools，零工具就是意图：tools: []（白名单）把 builtin 也关掉。
+			// 若以后要给它加 customTools，必须改成 noTools: "builtin"（见 agent-runner.ts 的警告）。
 			tools: [],
 			sessionPersistence,
 		});