minimal-agent 0.11.0 → 0.12.0

package/src/memory/episodicMemory.ts

@@ -1,10 +1,11 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { open, readFile, readdir, stat } from 'node:fs/promises';
+import { open, readFile, readdir, stat, unlink } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
 import { agentStateDir } from '../context/agentHome.js';
 import { containsForbiddenSecret, sha256 } from './codec.js';
 import {
+  acquireFileLock,
   appendPrivateLine,
   atomicWriteFile,
   ensurePrivateDir,
@@ -29,6 +30,16 @@ const MAX_EPISODE_CHARS = 8_000;
 const MAX_SEARCH_FILES = 200;
 const MAX_SEARCH_LINES = 20_000;
 const MAX_SNIPPET_CHARS = 500;
+/**
+ * 已解析 episode 常驻内存的上限。
+ *
+ * ⚠️ `episodeFileCache` 缓存的是**整个文件解析出的全部 episode**，而日志本身是只增不减的
+ * （每条 user/assistant 消息 ≤8000 字符）。没有上限时，Desktop 这种长驻进程搜一次历史就把
+ * 几十 MB 对话原文永久钉在堆上。按 episode 条数做 LRU，逐出最久未用的文件。
+ */
+const MAX_CACHED_EPISODES = 20_000;
+/** 两次保留清理之间的最小间隔——清理是尽力而为的后台动作，不该每条消息都扫盘。 */
+const RETENTION_SWEEP_INTERVAL_MS = 5 * 60_000;
 
 interface CachedEpisodeFile {
   ino: number;
@@ -36,6 +47,8 @@ interface CachedEpisodeFile {
   mtimeMs: number;
   trailing: string;
   episodes: ConversationEpisode[];
+  /** 单调递增的使用序号，用于 LRU 逐出（不用时间戳，避免同毫秒并列）。 */
+  usedAt: number;
 }
 
 interface CachedEpisodeIndex {
@@ -50,6 +63,8 @@ const episodeDiagnostics = {
   fullFileReads: 0,
   incrementalFileReads: 0,
   unchangedFileHits: 0,
+  cacheEvictions: 0,
+  retentionSweeps: 0,
 };
 
 export function episodeSearchDiagnostics(): Readonly<typeof episodeDiagnostics> {
@@ -60,8 +75,40 @@ export function resetEpisodeSearchDiagnostics(): void {
   episodeDiagnostics.fullFileReads = 0;
   episodeDiagnostics.incrementalFileReads = 0;
   episodeDiagnostics.unchangedFileHits = 0;
+  episodeDiagnostics.cacheEvictions = 0;
+  episodeDiagnostics.retentionSweeps = 0;
   episodeFileCache.clear();
   episodeIndexCache.clear();
+  cacheClock = 0;
+  retentionSweepStates.clear();
+}
+
+let cacheClock = 0;
+interface RetentionSweepState {
+  lastStartedAt: number;
+  lastUsedAt: number;
+  inFlight: boolean;
+}
+const retentionSweepStates = new Map<string, RetentionSweepState>();
+const MAX_RETENTION_SWEEP_STATES = 128;
+
+function cachedEpisodeCount(): number {
+  let total = 0;
+  for (const entry of episodeFileCache.values()) total += entry.episodes.length;
+  return total;
+}
+
+/** 超出 MAX_CACHED_EPISODES 就按最久未用逐出整份文件缓存，直到回到上限之内。 */
+function evictEpisodeCache(): void {
+  if (cachedEpisodeCount() <= MAX_CACHED_EPISODES) return;
+  const byAge = [...episodeFileCache.entries()].sort((a, b) => a[1].usedAt - b[1].usedAt);
+  for (const [path] of byAge) {
+    if (cachedEpisodeCount() <= MAX_CACHED_EPISODES) break;
+    episodeFileCache.delete(path);
+    episodeDiagnostics.cacheEvictions += 1;
+  }
+  // 文件缓存变了，基于它建的 BM25 语料签名也就失效了。
+  episodeIndexCache.clear();
 }
 
 function episodeRoot(): string {
@@ -89,6 +136,10 @@ function backfillMarkerPath(workspaceId: string): string {
   return join(episodeRoot(), `.backfill-${validPart(workspaceId)}.json`);
 }
 
+function workspaceJournalLockPath(workspaceId: string): string {
+  return join(episodeRoot(), `.workspace-${validPart(workspaceId)}.journal`);
+}
+
 export function sanitizeEpisodeContent(content: string): string | null {
   const normalized = content
     .replace(/data:[^;\s]+;base64,[A-Za-z0-9+/=]{80,}/g, '[binary omitted]')
@@ -130,6 +181,243 @@ export async function appendConversationEpisode(input: {
   return episode;
 }
 
+/** 删除某工作区（缺省为全部）的会话原文日志。供 Desktop「清空记忆」一并调用。 */
+export async function clearConversationEpisodes(workspaceId?: string): Promise<number> {
+  const release = workspaceId
+    ? await acquireFileLock(workspaceJournalLockPath(workspaceId))
+    : null;
+  try {
+    return await clearConversationEpisodesUnlocked(workspaceId);
+  } finally {
+    await release?.();
+  }
+}
+
+async function clearConversationEpisodesUnlocked(workspaceId?: string): Promise<number> {
+  const files = await episodeFiles(workspaceId).catch(() => []);
+  let removed = 0;
+  for (const path of files) {
+    const result = await mutateEpisodeFile(path, () => ({ kind: 'delete' })).catch(() => null);
+    if (result?.changed) removed += 1;
+  }
+  // ⚠️ backfill 标记必须**留下（没有就补写）**，绝不能删。
+  //    backfillLegacyHistory 会从 `sessions/*.json` 一次性导入旧会话；标记一旦消失，
+  //    下一次 SearchConversations 就会把刚刚清掉的对话原文整批重新导回来 —— 用户点了
+  //    "永久清空"，转头又能搜到，等于清空是假的。
+  if (workspaceId) {
+    await atomicWriteFile(
+      backfillMarkerPath(workspaceId),
+      `${JSON.stringify(
+        { version: 1, workspaceId, sources: 0, completedAt: Date.now(), reason: 'cleared-by-user' },
+        null,
+        2,
+      )}\n`,
+    ).catch(() => undefined);
+  }
+  episodeIndexCache.clear();
+  return removed;
+}
+
+interface StableEpisodeFile {
+  raw: string;
+  ino: number;
+  size: number;
+  mtimeMs: number;
+}
+
+type EpisodeFileMutation =
+  | { kind: 'unchanged' }
+  | { kind: 'write'; content: string }
+  | { kind: 'delete' };
+
+interface EpisodeFileMutationResult {
+  changed: boolean;
+  bytes: number;
+}
+
+function sameEpisodeFile(
+  left: Pick<StableEpisodeFile, 'ino' | 'size' | 'mtimeMs'>,
+  right: Pick<StableEpisodeFile, 'ino' | 'size' | 'mtimeMs'>,
+): boolean {
+  return left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+
+async function readStableEpisodeFile(path: string): Promise<StableEpisodeFile | null> {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const before = await stat(path).catch((error) => {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw error;
+    });
+    if (!before) return null;
+    const raw = await readFile(path, 'utf8');
+    const after = await stat(path).catch(() => null);
+    if (
+      after
+      && before.ino === after.ino
+      && before.size === after.size
+      && before.mtimeMs === after.mtimeMs
+      && Buffer.byteLength(raw, 'utf8') === after.size
+    ) {
+      return { raw, ino: after.ino, size: after.size, mtimeMs: after.mtimeMs };
+    }
+  }
+  return null;
+}
+
+/**
+ * 与 appendPrivateLine 共用同一把 `<episode>.lock`。大文件的解析在锁外完成，
+ * 获锁后只验证文件代际并提交；如果这期间有追加，就重读重算，绝不覆盖新行。
+ */
+async function mutateEpisodeFile(
+  path: string,
+  plan: (raw: string) => EpisodeFileMutation,
+): Promise<EpisodeFileMutationResult> {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const source = await readStableEpisodeFile(path);
+    if (!source) return { changed: false, bytes: 0 };
+    const mutation = plan(source.raw);
+    if (mutation.kind === 'unchanged') return { changed: false, bytes: source.size };
+    const release = await acquireFileLock(path);
+    try {
+      const live = await stat(path).catch(() => null);
+      if (!live || !sameEpisodeFile(source, live)) continue;
+      if (mutation.kind === 'delete') await unlink(path);
+      else await atomicWriteFile(path, mutation.content);
+      episodeFileCache.delete(path);
+      episodeIndexCache.clear();
+      return {
+        changed: true,
+        bytes: mutation.kind === 'write' ? Buffer.byteLength(mutation.content, 'utf8') : 0,
+      };
+    } finally {
+      await release();
+    }
+  }
+  // 文件持续忙时跳过本轮维护；下次保留扫描会再处理。
+  const current = await stat(path).catch(() => null);
+  return { changed: false, bytes: current?.size ?? 0 };
+}
+
+/** 列出某工作区（或全部）的会话原文日志文件。 */
+async function episodeFiles(workspaceId?: string): Promise<string[]> {
+  const prefix = workspaceId ? `workspace-${validPart(workspaceId)}--` : 'workspace-';
+  try {
+    return (await readdir(episodeRoot(), { withFileTypes: true }))
+      .filter((entry) =>
+        entry.isFile() && entry.name.endsWith('.jsonl') && entry.name.startsWith(prefix))
+      .map((entry) => join(episodeRoot(), entry.name));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/** 按龄清理一个文件；返回清理后的字节数（文件被清空则删除并返回 0）。 */
+async function pruneFileByAge(path: string, cutoff: number): Promise<number> {
+  const result = await mutateEpisodeFile(path, (raw) => {
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const kept = lines.filter((line) => {
+      const episode = parseEpisode(line);
+      // 解析不出来的行按"保留"处理：清理是维护动作，不该顺手吞掉看不懂的数据。
+      return episode ? episode.createdAt >= cutoff : true;
+    });
+    if (kept.length === lines.length) return { kind: 'unchanged' };
+    if (kept.length === 0) return { kind: 'delete' };
+    return { kind: 'write', content: `${kept.join('\n')}\n` };
+  });
+  return result.bytes;
+}
+
+/**
+ * 会话原文保留策略：先按龄清理，仍超体积上限就从**最旧的文件**整份删起。
+ *
+ * 全程 best-effort：清理失败绝不能影响正在进行的对话（这是维护动作，不是功能）。
+ * 与 records 的删除语义严格区分——records 只有用户能删，这里删的是为检索而留的对话副本。
+ */
+export async function applyEpisodeRetention(
+  workspaceId: string,
+  retention: { episodeDays: number; episodeMaxMegabytes: number },
+  now = Date.now(),
+): Promise<void> {
+  const files = await episodeFiles(workspaceId).catch(() => []);
+  if (!files.length) return;
+  episodeDiagnostics.retentionSweeps += 1;
+  const cutoff = now - retention.episodeDays * 86_400_000;
+  const sized: Array<{ path: string; bytes: number; mtimeMs: number }> = [];
+  for (const path of files) {
+    const bytes = await pruneFileByAge(path, cutoff).catch(() => -1);
+    if (bytes <= 0) continue;
+    const info = await stat(path).catch(() => null);
+    sized.push({ path, bytes, mtimeMs: info?.mtimeMs ?? 0 });
+  }
+  const limit = retention.episodeMaxMegabytes * 1024 * 1024;
+  let total = sized.reduce((sum, item) => sum + item.bytes, 0);
+  if (total <= limit) return;
+  // 从最旧的文件开始按**条目**裁剪，而不是整份删除：
+  // 一个工作区常常只有一个长期会话文件，整份删会让全部历史在某次追加后突然消失（悬崖），
+  // 而按条目裁剪的结果是"最旧的对话先被丢掉"，与按龄清理的语义一致。
+  for (const item of sized.sort((a, b) => a.mtimeMs - b.mtimeMs)) {
+    if (total <= limit) break;
+    const keepBytes = Math.max(0, item.bytes - (total - limit));
+    const remaining = await trimFileToNewestBytes(item.path, keepBytes).catch(() => item.bytes);
+    total -= item.bytes - remaining;
+  }
+  episodeIndexCache.clear();
+}
+
+/** 只保留文件末尾（最新）能放进 keepBytes 的整行；keepBytes 为 0 时删除文件。返回剩余字节数。 */
+async function trimFileToNewestBytes(path: string, keepBytes: number): Promise<number> {
+  const result = await mutateEpisodeFile(path, (raw) => {
+    if (keepBytes <= 0) return { kind: 'delete' };
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    const kept: string[] = [];
+    let bytes = 0;
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const size = Buffer.byteLength(`${lines[index]}\n`, 'utf8');
+      if (bytes + size > keepBytes) break;
+      kept.unshift(lines[index]!);
+      bytes += size;
+    }
+    if (!kept.length) return { kind: 'delete' };
+    if (kept.length === lines.length) return { kind: 'unchanged' };
+    return { kind: 'write', content: `${kept.join('\n')}\n` };
+  });
+  return result.bytes;
+}
+
+/**
+ * 是否该跑一次保留清理（同一进程内每 RETENTION_SWEEP_INTERVAL_MS 最多一次）。
+ *
+ * 本模块**不自己去读设置**：那需要 `import('./memoryService.js')`，而 memoryService 正好
+ * 静态 import 本模块，绕一圈会变成动态 import 的循环依赖——dev 下能跑，但 `bun --compile`
+ * 的绿色版打包期解析动态 import 的行为另算，不值得赌（见 GREEN-BUILD 相关教训）。
+ * 由知道设置的那一层（turnJournal）来问「该扫了吗」，本模块只保留纯粹的存储职责。
+ */
+export function shouldSweepRetention(workspaceId: string, now = Date.now()): boolean {
+  const current = retentionSweepStates.get(workspaceId);
+  if (current?.inFlight || (current && now - current.lastStartedAt < RETENTION_SWEEP_INTERVAL_MS)) {
+    if (current) current.lastUsedAt = now;
+    return false;
+  }
+  retentionSweepStates.set(workspaceId, { lastStartedAt: now, lastUsedAt: now, inFlight: true });
+  if (retentionSweepStates.size > MAX_RETENTION_SWEEP_STATES) {
+    const victims = [...retentionSweepStates.entries()]
+      .filter(([, state]) => !state.inFlight)
+      .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt)
+      .slice(0, retentionSweepStates.size - MAX_RETENTION_SWEEP_STATES);
+    for (const [key] of victims) retentionSweepStates.delete(key);
+  }
+  return true;
+}
+
+export function finishRetentionSweep(workspaceId: string): void {
+  const state = retentionSweepStates.get(workspaceId);
+  if (state) {
+    state.inFlight = false;
+    state.lastUsedAt = Date.now();
+  }
+}
+
 function parseEpisode(line: string): ConversationEpisode | null {
   try {
     const value = JSON.parse(line) as Partial<ConversationEpisode>;
@@ -181,12 +469,14 @@ async function readEpisodeBytes(path: string, offset: number, length: number): P
 async function loadEpisodeFile(path: string): Promise<CachedEpisodeFile> {
   const info = await stat(path);
   const cached = episodeFileCache.get(path);
+  cacheClock += 1;
   if (
     cached
     && cached.ino === info.ino
     && cached.size === info.size
     && cached.mtimeMs === info.mtimeMs
   ) {
+    cached.usedAt = cacheClock;
     episodeDiagnostics.unchangedFileHits += 1;
     return cached;
   }
@@ -199,9 +489,11 @@ async function loadEpisodeFile(path: string): Promise<CachedEpisodeFile> {
       mtimeMs: info.mtimeMs,
       trailing: parsed.trailing,
       episodes: [...cached.episodes, ...parsed.episodes],
+      usedAt: cacheClock,
     };
     episodeFileCache.set(path, next);
     episodeDiagnostics.incrementalFileReads += 1;
+    evictEpisodeCache();
     return next;
   }
   const raw = await readFile(path, 'utf8');
@@ -212,9 +504,11 @@ async function loadEpisodeFile(path: string): Promise<CachedEpisodeFile> {
     mtimeMs: info.mtimeMs,
     trailing: parsed.trailing,
     episodes: parsed.episodes,
+    usedAt: cacheClock,
   };
   episodeFileCache.set(path, next);
   episodeDiagnostics.fullFileReads += 1;
+  evictEpisodeCache();
   return next;
 }
 
@@ -289,6 +583,15 @@ async function workspaceArchiveDirs(workspaceId: string): Promise<string[]> {
 }
 
 async function backfillLegacyHistory(workspaceId: string): Promise<void> {
+  const release = await acquireFileLock(workspaceJournalLockPath(workspaceId));
+  try {
+    await backfillLegacyHistoryUnlocked(workspaceId);
+  } finally {
+    await release();
+  }
+}
+
+async function backfillLegacyHistoryUnlocked(workspaceId: string): Promise<void> {
   const marker = backfillMarkerPath(workspaceId);
   if (await pathExists(marker)) return;
   const sources: Array<{ path: string; sessionId: string }> = [];
@@ -507,4 +810,6 @@ function conversationResult(
 export const episodicMemoryService = {
   append: appendConversationEpisode,
   search: searchConversationEpisodes,
+  clear: clearConversationEpisodes,
+  applyRetention: applyEpisodeRetention,
 };

package/src/memory/fileStore.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { chmod, mkdir, open, readFile, rename, rm, unlink, writeFile, } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, rename, rm, stat, unlink, writeFile, } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { agentStateDir } from '../context/agentHome.js';
 import { CATEGORY_DIR, MEMORY_ID_PATTERN } from './constants.js';
@@ -67,8 +67,11 @@ export async function acquireFileLock(path) {
                 throw error;
             const raw = await readFile(lock, 'utf8').catch(() => '');
             const createdAt = Number(raw.split(':')[1]);
-            if (!Number.isFinite(createdAt) ||
-                Date.now() - createdAt > LOCK_STALE_MS) {
+            const lockInfo = await stat(lock).catch(() => null);
+            if ((Number.isFinite(createdAt) && Date.now() - createdAt > LOCK_STALE_MS) ||
+                (!Number.isFinite(createdAt)
+                    && lockInfo !== null
+                    && Date.now() - lockInfo.mtimeMs > LOCK_STALE_MS)) {
                 await unlink(lock).catch(() => { });
                 continue;
             }
@@ -109,10 +112,12 @@ export function enqueueMemoryMutation(operation) {
     });
     return result;
 }
-export async function appendPrivateLine(path, line) {
+export async function appendPrivateLine(path, line, options) {
     const release = await acquireFileLock(path);
     try {
         await ensurePrivateDir(dirname(path));
+        if (options?.maxBytes)
+            await rotateIfLarge(path, options.maxBytes);
         const handle = await open(path, 'a', 0o600);
         try {
             await handle.writeFile(`${line.replace(/[\r\n]+$/g, '')}\n`);
@@ -126,3 +131,18 @@ export async function appendPrivateLine(path, line) {
         await release();
     }
 }
+/**
+ * 超限就把当前文件挪成 `.1`（覆盖上一代），与 `vision/telemetry.ts::rotateIfLarge` 同款。
+ * 失败静默——轮转不了也要能继续写，日志不该反过来拖垮功能。
+ */
+async function rotateIfLarge(path, maxBytes) {
+    try {
+        const info = await stat(path);
+        if (info.size < maxBytes)
+            return;
+        await rename(path, `${path}.1`);
+    }
+    catch {
+        /* 文件不存在或挪不动，都不影响追加 */
+    }
+}

package/src/memory/fileStore.ts

@@ -6,6 +6,7 @@ import {
   readFile,
   rename,
   rm,
+  stat,
   unlink,
   writeFile,
 } from 'node:fs/promises';
@@ -95,9 +96,12 @@ export async function acquireFileLock(
       if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
       const raw = await readFile(lock, 'utf8').catch(() => '');
       const createdAt = Number(raw.split(':')[1]);
+      const lockInfo = await stat(lock).catch(() => null);
       if (
-        !Number.isFinite(createdAt) ||
-        Date.now() - createdAt > LOCK_STALE_MS
+        (Number.isFinite(createdAt) && Date.now() - createdAt > LOCK_STALE_MS) ||
+        (!Number.isFinite(createdAt)
+          && lockInfo !== null
+          && Date.now() - lockInfo.mtimeMs > LOCK_STALE_MS)
       ) {
         await unlink(lock).catch(() => {});
         continue;
@@ -147,10 +151,12 @@ export function enqueueMemoryMutation<T>(
 export async function appendPrivateLine(
   path: string,
   line: string,
+  options?: { maxBytes?: number },
 ): Promise<void> {
   const release = await acquireFileLock(path);
   try {
     await ensurePrivateDir(dirname(path));
+    if (options?.maxBytes) await rotateIfLarge(path, options.maxBytes);
     const handle = await open(path, 'a', 0o600);
     try {
       await handle.writeFile(`${line.replace(/[\r\n]+$/g, '')}\n`);
@@ -162,3 +168,17 @@ export async function appendPrivateLine(
     await release();
   }
 }
+
+/**
+ * 超限就把当前文件挪成 `.1`（覆盖上一代），与 `vision/telemetry.ts::rotateIfLarge` 同款。
+ * 失败静默——轮转不了也要能继续写，日志不该反过来拖垮功能。
+ */
+async function rotateIfLarge(path: string, maxBytes: number): Promise<void> {
+  try {
+    const info = await stat(path);
+    if (info.size < maxBytes) return;
+    await rename(path, `${path}.1`);
+  } catch {
+    /* 文件不存在或挪不动，都不影响追加 */
+  }
+}

package/src/memory/memoryService.js

@@ -3,15 +3,16 @@ import { copyFile, readFile, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { countTextTokens } from '../context/tokenCounter.js';
 import { containsForbiddenSecret, deriveTopicKey, hydrateRecord, parsePersona, serializePersona, sha256, validateMemoryInput, } from './codec.js';
-import { DEFAULT_SETTINGS, PERSONA_MAX_CHARS } from './constants.js';
-import { episodicMemoryService } from './episodicMemory.js';
+import { DEFAULT_RETENTION, DEFAULT_SETTINGS, MEMORY_RETENTION_DAYS_MAX, MEMORY_RETENTION_DAYS_MIN, MEMORY_RETENTION_MB_MAX, MEMORY_RETENTION_MB_MIN, PERSONA_MAX_CHARS, } from './constants.js';
+import { clearConversationEpisodes, episodicMemoryService, } from './episodicMemory.js';
 import { acquireFileLock, appendPrivateLine, atomicWriteFile, auditFilePath, enqueueMemoryMutation, personaFilePath, scopeDirectory, settingsFilePath, } from './fileStore.js';
 import { ensureMemoryMigrated } from './migration.js';
-import { readVersionedMemory, removeVersionedMemory, replaceMemoryBatchVersioned, scanMemoryScope, writeNewMemory, } from './repository.js';
+import { clearScopeTransactionQuarantine, readVersionedMemory, refreshTopicView, removeVersionedMemory, replaceMemoryBatchVersioned, scanMemoryScope, writeNewMemory, } from './repository.js';
 import { isReviewDue, recallFromSnapshot, takeTokenBudget, truncateTokenBudget, } from './retrieval.js';
 export { containsForbiddenSecret } from './codec.js';
 function mergeSettings(raw) {
     const review = raw.reviewAfterDays;
+    const retention = raw.retention;
     return {
         autoRemember: typeof raw.autoRemember === 'boolean'
             ? raw.autoRemember
@@ -24,16 +25,35 @@ function mergeSettings(raw) {
             project: review?.project ?? DEFAULT_SETTINGS.reviewAfterDays.project,
             decision: review?.decision ?? DEFAULT_SETTINGS.reviewAfterDays.decision,
         },
+        retention: {
+            episodeDays: retention?.episodeDays ?? DEFAULT_RETENTION.episodeDays,
+            episodeMaxMegabytes: retention?.episodeMaxMegabytes ?? DEFAULT_RETENTION.episodeMaxMegabytes,
+        },
     };
 }
 function validateSettingsPatch(patch) {
-    if (patch.reviewAfterDays === undefined)
-        return;
-    for (const [category, days] of Object.entries(patch.reviewAfterDays)) {
-        if (!Number.isInteger(days) || days < 7 || days > 3_650) {
-            throw new Error(`复核周期 ${category} 必须是 7-3650 之间的整数天`);
+    if (patch.reviewAfterDays !== undefined) {
+        for (const [category, days] of Object.entries(patch.reviewAfterDays)) {
+            if (!Number.isInteger(days) || days < 7 || days > 3_650) {
+                throw new Error(`复核周期 ${category} 必须是 7-3650 之间的整数天`);
+            }
         }
     }
+    if (patch.retention === undefined)
+        return;
+    const { episodeDays, episodeMaxMegabytes } = patch.retention;
+    if (episodeDays !== undefined
+        && (!Number.isInteger(episodeDays)
+            || episodeDays < MEMORY_RETENTION_DAYS_MIN
+            || episodeDays > MEMORY_RETENTION_DAYS_MAX)) {
+        throw new Error(`会话原文保留天数必须是 ${MEMORY_RETENTION_DAYS_MIN}-${MEMORY_RETENTION_DAYS_MAX} 之间的整数`);
+    }
+    if (episodeMaxMegabytes !== undefined
+        && (!Number.isInteger(episodeMaxMegabytes)
+            || episodeMaxMegabytes < MEMORY_RETENTION_MB_MIN
+            || episodeMaxMegabytes > MEMORY_RETENTION_MB_MAX)) {
+        throw new Error(`会话原文体积上限必须是 ${MEMORY_RETENTION_MB_MIN}-${MEMORY_RETENTION_MB_MAX} 之间的整数 MB`);
+    }
 }
 async function settingsDocument() {
     try {
@@ -52,6 +72,8 @@ async function settingsDocument() {
         return { settings, version: sha256(`${JSON.stringify(settings, null, 2)}\n`) };
     }
 }
+/** 审计日志单代上限；超限挪成 `.1`，保留最近两代。 */
+const AUDIT_MAX_BYTES = 4 * 1024 * 1024;
 async function appendAudit(input) {
     await appendPrivateLine(auditFilePath(), JSON.stringify({
         timestamp: Date.now(),
@@ -62,23 +84,55 @@ async function appendAudit(input) {
         revision: input.record?.revision,
         version: input.version,
         result: input.result,
-    })).catch(() => undefined);
+    }), 
+    // 审计日志同样是 append-only，必须轮转——它此前是仓库里第二个只增不减的存储。
+    { maxBytes: AUDIT_MAX_BYTES }).catch(() => undefined);
 }
+const EMPTY_SCOPE_SNAPSHOT = Object.freeze({
+    records: [],
+    versions: {},
+    diagnostics: [],
+    createdAt: 0,
+});
+/**
+ * 合并快照的记忆化。
+ *
+ * ⚠️ 这不是"顺手加个缓存"，是修一个死缓存：`retrieval.ts` 用
+ * `WeakMap<MemorySnapshot, Bm25Index>` 按快照对象缓存 BM25 索引，而本函数以前**每次都
+ * 返回全新对象字面量** —— 于是 recall / buildContextBundle 这两条热路径上 WeakMap 永远
+ * miss，每轮对话都要重建整个索引，`recordSearchIndexCacheHit()` 一次都不会触发（诊断计数
+ * 器因此说谎）。单测直接对同一个 snapshot 对象调两次 recallFromSnapshot，机制是对的，
+ * 但生产集成从不复用对象，属于"测试通过、生产死代码"。
+ *
+ * 用底层两个 scope 快照的**对象标识**做键：scanMemoryScope 在缓存命中时返回同一个对象，
+ * 有变更时才换新对象——比时间戳更精确，也不怕时钟碰撞。
+ */
+let combinedSnapshotCache = null;
 async function combinedSnapshot(workspaceId) {
     await ensureMemoryMigrated();
     const personal = await scanMemoryScope('personal');
     const workspace = workspaceId
         ? await scanMemoryScope('workspace', workspaceId)
-        : { records: [], versions: {}, diagnostics: [], createdAt: Date.now() };
-    return {
+        : EMPTY_SCOPE_SNAPSHOT;
+    const cached = combinedSnapshotCache;
+    if (cached
+        && cached.personal === personal
+        && cached.workspace === workspace
+        && cached.workspaceId === workspaceId) {
+        return cached.combined;
+    }
+    const combined = {
         records: [...personal.records, ...workspace.records],
         versions: { ...personal.versions, ...workspace.versions },
         diagnostics: [...personal.diagnostics, ...workspace.diagnostics],
         createdAt: Date.now(),
     };
+    combinedSnapshotCache = { personal, workspace, workspaceId, combined };
+    return combined;
 }
 function refreshTopicViewAfterMutation(scope, workspaceId) {
-    void scanMemoryScope(scope, workspaceId).catch(() => undefined);
+    combinedSnapshotCache = null;
+    void refreshTopicView(scope, workspaceId).catch(() => undefined);
 }
 function sameTopic(a, b) {
     const topicKey = b.topicKey || deriveTopicKey(b);
@@ -348,6 +402,19 @@ export const memoryService = {
                 await removeVersionedMemory({ record, version }, version);
                 await appendAudit({ action: 'clear', record, version, result: 'ok' });
             }
+            // ★ 会话原文日志也要清掉。
+            //   Desktop「永久清空」以前只删 records，而同一个记忆中心页面还提供
+            //   ConversationHistorySearch —— 用户"清空记忆"后全部对话原文依然可搜，
+            //   与按钮承诺严重不符。工作区范围才有对应的 episodes 文件。
+            if (scope === 'workspace' && workspaceId) {
+                const removed = await clearConversationEpisodes(workspaceId).catch(() => 0);
+                if (removed) {
+                    await appendAudit({ action: 'clear-episodes', result: 'ok' });
+                }
+            }
+            // 只有用户明确清空整个 scope 才表示隔离事务的复核现场也不再需要。
+            // 普通新增/更新记忆不得清除这类诊断。
+            await clearScopeTransactionQuarantine(scope, workspaceId);
             refreshTopicViewAfterMutation(scope, workspaceId);
         });
     },