minimal-agent 0.10.0 → 0.12.0

package/src/memory/memoryService.ts

@@ -0,0 +1,859 @@
+import { randomUUID } from 'node:crypto';
+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_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 {
+  clearScopeTransactionQuarantine,
+  readVersionedMemory,
+  refreshTopicView,
+  removeVersionedMemory,
+  replaceMemoryBatchVersioned,
+  replaceVersionedMemory,
+  scanMemoryScope,
+  writeNewMemory,
+} from './repository.js';
+import {
+  isReviewDue,
+  recallFromSnapshot,
+  takeTokenBudget,
+  truncateTokenBudget,
+} from './retrieval.js';
+import type {
+  ConversationSearchOptions,
+  MemoryContextBundle,
+  MemoryDiagnostic,
+  MemoryEditablePatch,
+  MemoryRecord,
+  MemoryRecordV2,
+  MemoryScope,
+  MemorySettings,
+  MemorySnapshot,
+  MemoryUpdate,
+  MemoryVersion,
+  PersonaDocument,
+  PersonaInput,
+  VersionedMemoryRecord,
+  VersionedMemorySettings,
+  VersionedPersonaDocument,
+} from './types.js';
+
+export type {
+  ConversationEpisode,
+  ConversationSearchOptions,
+  ConversationSearchResult,
+  MemoryCategory,
+  MemoryContextBundle,
+  MemoryDiagnostic,
+  MemoryEditablePatch,
+  MemoryEvidence,
+  MemoryRecord,
+  MemoryRecordV2,
+  MemoryScope,
+  MemorySensitivity,
+  MemorySettings,
+  MemorySnapshot,
+  MemoryStatus,
+  MemoryUpdate,
+  MemoryVersion,
+  PersonaDocument,
+  PersonaInput,
+  VersionedMemoryRecord,
+  VersionedMemorySettings,
+  VersionedPersonaDocument,
+} from './types.js';
+export { containsForbiddenSecret } from './codec.js';
+
+function mergeSettings(raw: Partial<MemorySettings>): MemorySettings {
+  const review = raw.reviewAfterDays;
+  const retention = raw.retention;
+  return {
+    autoRemember:
+      typeof raw.autoRemember === 'boolean'
+        ? raw.autoRemember
+        : DEFAULT_SETTINGS.autoRemember,
+    reviewAfterDays: {
+      profile: review?.profile ?? DEFAULT_SETTINGS.reviewAfterDays!.profile,
+      preference:
+        review?.preference ?? DEFAULT_SETTINGS.reviewAfterDays!.preference,
+      topic: review?.topic ?? DEFAULT_SETTINGS.reviewAfterDays!.topic,
+      person: review?.person ?? DEFAULT_SETTINGS.reviewAfterDays!.person,
+      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: Partial<MemorySettings>): void {
+  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(): Promise<VersionedMemorySettings> {
+  try {
+    const raw = await readFile(settingsFilePath(), 'utf8');
+    return {
+      settings: mergeSettings(JSON.parse(raw) as Partial<MemorySettings>),
+      version: sha256(raw),
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      const path = settingsFilePath();
+      await copyFile(path, `${path}.corrupt-${Date.now()}`).catch(() => {});
+    }
+    const settings = structuredClone(DEFAULT_SETTINGS);
+    return { settings, version: sha256(`${JSON.stringify(settings, null, 2)}\n`) };
+  }
+}
+
+/** 审计日志单代上限；超限挪成 `.1`，保留最近两代。 */
+const AUDIT_MAX_BYTES = 4 * 1024 * 1024;
+
+async function appendAudit(input: {
+  action: string;
+  record?: MemoryRecord;
+  version?: string;
+  result: 'ok' | 'conflict' | 'not_found';
+}): Promise<void> {
+  await appendPrivateLine(
+    auditFilePath(),
+    JSON.stringify({
+      timestamp: Date.now(),
+      action: input.action,
+      id: input.record?.id,
+      scope: input.record?.scope,
+      workspaceId: input.record?.workspaceId,
+      revision: input.record?.revision,
+      version: input.version,
+      result: input.result,
+    }),
+    // 审计日志同样是 append-only，必须轮转——它此前是仓库里第二个只增不减的存储。
+    { maxBytes: AUDIT_MAX_BYTES },
+  ).catch(() => undefined);
+}
+
+const EMPTY_SCOPE_SNAPSHOT: MemorySnapshot = Object.freeze({
+  records: [],
+  versions: {},
+  diagnostics: [],
+  createdAt: 0,
+}) as MemorySnapshot;
+
+/**
+ * 合并快照的记忆化。
+ *
+ * ⚠️ 这不是"顺手加个缓存"，是修一个死缓存：`retrieval.ts` 用
+ * `WeakMap<MemorySnapshot, Bm25Index>` 按快照对象缓存 BM25 索引，而本函数以前**每次都
+ * 返回全新对象字面量** —— 于是 recall / buildContextBundle 这两条热路径上 WeakMap 永远
+ * miss，每轮对话都要重建整个索引，`recordSearchIndexCacheHit()` 一次都不会触发（诊断计数
+ * 器因此说谎）。单测直接对同一个 snapshot 对象调两次 recallFromSnapshot，机制是对的，
+ * 但生产集成从不复用对象，属于"测试通过、生产死代码"。
+ *
+ * 用底层两个 scope 快照的**对象标识**做键：scanMemoryScope 在缓存命中时返回同一个对象，
+ * 有变更时才换新对象——比时间戳更精确，也不怕时钟碰撞。
+ */
+let combinedSnapshotCache: {
+  personal: MemorySnapshot;
+  workspace: MemorySnapshot;
+  workspaceId?: string;
+  combined: MemorySnapshot;
+} | null = null;
+
+async function combinedSnapshot(workspaceId?: string): Promise<MemorySnapshot> {
+  await ensureMemoryMigrated();
+  const personal = await scanMemoryScope('personal');
+  const workspace = workspaceId
+    ? await scanMemoryScope('workspace', workspaceId)
+    : EMPTY_SCOPE_SNAPSHOT;
+  const cached = combinedSnapshotCache;
+  if (
+    cached
+    && cached.personal === personal
+    && cached.workspace === workspace
+    && cached.workspaceId === workspaceId
+  ) {
+    return cached.combined;
+  }
+  const combined: MemorySnapshot = {
+    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: MemoryScope,
+  workspaceId?: string,
+): void {
+  combinedSnapshotCache = null;
+  void refreshTopicView(scope, workspaceId).catch(() => undefined);
+}
+
+function sameTopic(
+  a: MemoryRecordV2,
+  b: Pick<MemoryRecord, 'category' | 'subject'> & {
+    topicKey?: string;
+    aliases?: string[];
+  },
+): boolean {
+  const topicKey = b.topicKey || deriveTopicKey(b);
+  if (a.topicKey === topicKey) return true;
+  const candidates = new Set([
+    b.subject.toLocaleLowerCase(),
+    ...(b.aliases ?? []).map((item) => item.toLocaleLowerCase()),
+  ]);
+  return [a.subject, ...a.aliases].some((item) =>
+    candidates.has(item.toLocaleLowerCase()),
+  );
+}
+
+function evidenceForStorage(
+  record: Pick<MemoryRecord, 'sensitivity' | 'evidenceQuote'>,
+): Pick<MemoryRecord, 'evidenceQuote' | 'evidenceHash'> {
+  if (record.sensitivity === 'normal')
+    return { evidenceQuote: record.evidenceQuote };
+  return {
+    evidenceQuote: '[sensitive evidence generalized]',
+    evidenceHash: sha256(record.evidenceQuote),
+  };
+}
+
+function currentInputOverrides(record: MemoryRecordV2, input: string): boolean {
+  const normalized = input.toLocaleLowerCase();
+  const mentionsTopic = [record.subject, ...record.aliases].some(
+    (value) =>
+      value.length > 1 && normalized.includes(value.toLocaleLowerCase()),
+  );
+  return (
+    mentionsTopic &&
+    /纠正|改成|更新|不再|以后不要|不是|现在(?:改|用|是)|correction|change to|no longer|instead/i.test(
+      input,
+    )
+  );
+}
+
+export const memoryService = {
+  async settings(): Promise<MemorySettings> {
+    return (await settingsDocument()).settings;
+  },
+
+  async settingsWithVersion(): Promise<VersionedMemorySettings> {
+    return settingsDocument();
+  },
+
+  async updateSettings(
+    patch: Partial<MemorySettings>,
+  ): Promise<MemorySettings> {
+    return (await this.updateSettingsWithVersion(patch)).settings;
+  },
+
+  async updateSettingsWithVersion(
+    patch: Partial<MemorySettings>,
+    expectedVersion?: MemoryVersion,
+  ): Promise<VersionedMemorySettings> {
+    validateSettingsPatch(patch);
+    const release = await acquireFileLock(settingsFilePath());
+    try {
+      const current = await settingsDocument();
+      if (expectedVersion && current.version !== expectedVersion) {
+        throw new Error('MEMORY_SETTINGS_VERSION_CONFLICT');
+      }
+      const next = mergeSettings({ ...current.settings, ...patch });
+      const content = `${JSON.stringify(next, null, 2)}\n`;
+      await atomicWriteFile(settingsFilePath(), content);
+      return { settings: next, version: sha256(content) };
+    } finally {
+      await release();
+    }
+  },
+
+  async snapshot(workspaceId?: string): Promise<MemorySnapshot> {
+    return combinedSnapshot(workspaceId);
+  },
+
+  async scan(
+    scope: MemoryScope,
+    workspaceId?: string,
+  ): Promise<MemorySnapshot> {
+    await ensureMemoryMigrated();
+    return scanMemoryScope(scope, workspaceId);
+  },
+
+  async list(
+    scope: MemoryScope,
+    workspaceId?: string,
+  ): Promise<MemoryRecordV2[]> {
+    return (await this.scan(scope, workspaceId)).records;
+  },
+
+  async diagnostics(
+    scope: MemoryScope,
+    workspaceId?: string,
+  ): Promise<MemoryDiagnostic[]> {
+    return (await this.scan(scope, workspaceId)).diagnostics;
+  },
+
+  async readWithVersion(
+    id: string,
+    scope: MemoryScope,
+    workspaceId?: string,
+  ): Promise<VersionedMemoryRecord | null> {
+    await ensureMemoryMigrated();
+    return readVersionedMemory(id, scope, workspaceId);
+  },
+
+  async recall(
+    query: string,
+    workspaceId?: string,
+    limit = 8,
+  ): Promise<MemoryRecordV2[]> {
+    return (await this.recallDetailed(query, workspaceId, limit)).records;
+  },
+
+  async recallDetailed(
+    query: string,
+    workspaceId?: string,
+    limit = 8,
+  ): Promise<{
+    records: MemoryRecordV2[];
+    snapshot: MemorySnapshot;
+  }> {
+    const snapshot = await combinedSnapshot(workspaceId);
+    return {
+      records: recallFromSnapshot(
+        snapshot,
+        query,
+        await this.settings(),
+        limit,
+      ),
+      snapshot,
+    };
+  },
+
+  async remember(
+    input: Omit<MemoryRecord, 'id' | 'createdAt' | 'updatedAt'>,
+  ): Promise<MemoryRecordV2> {
+    validateMemoryInput(input);
+    await ensureMemoryMigrated();
+    return enqueueMemoryMutation(async () => {
+      const release = await acquireFileLock(
+        join(scopeDirectory(input.scope, input.workspaceId), '.records'),
+      );
+      try {
+        const records = (await scanMemoryScope(input.scope, input.workspaceId))
+          .records;
+        const hydratedInput = hydrateRecord({
+          ...input,
+          id: randomUUID(),
+          createdAt: 0,
+          updatedAt: 0,
+        });
+        const duplicate = records.find((record) =>
+          sameTopic(record, hydratedInput),
+        );
+        if (duplicate?.statement === input.statement) {
+          await appendAudit({
+            action: 'remember-idempotent',
+            record: duplicate,
+            result: 'ok',
+          });
+          return duplicate;
+        }
+        if (duplicate) {
+          throw new Error(
+            `已有同主题记忆 ${duplicate.id}；内容变更必须使用 UpdateMemory，不能静默覆盖`,
+          );
+        }
+        const now = Date.now();
+        const evidence = evidenceForStorage(input);
+        const record = hydrateRecord({
+          ...input,
+          ...evidence,
+          id: hydratedInput.id,
+          createdAt: now,
+          updatedAt: now,
+          topicKey: hydratedInput.topicKey,
+          status: 'active',
+          revision: 1,
+          lastConfirmedAt: now,
+        });
+        const version = await writeNewMemory(record);
+        await appendAudit({
+          action: 'remember',
+          record,
+          version,
+          result: 'ok',
+        });
+        refreshTopicViewAfterMutation(record.scope, record.workspaceId);
+        return record;
+      } finally {
+        await release();
+      }
+    });
+  },
+
+  async updateWithVersion(
+    id: string,
+    scope: MemoryScope,
+    expectedVersion: MemoryVersion,
+    patch: MemoryUpdate,
+    workspaceId?: string,
+  ): Promise<VersionedMemoryRecord | null> {
+    await ensureMemoryMigrated();
+    return enqueueMemoryMutation(async () => {
+      const current = await readVersionedMemory(id, scope, workspaceId);
+      if (!current) {
+        await appendAudit({ action: 'update', result: 'not_found' });
+        return null;
+      }
+      const now = Date.now();
+      const merged = { ...current.record, ...patch, updatedAt: now };
+      validateMemoryInput(merged);
+      const evidence = evidenceForStorage(merged);
+      const next = hydrateRecord({
+        ...merged,
+        ...evidence,
+        topicKey: deriveTopicKey(merged),
+        revision: current.record.revision + 1,
+        lastConfirmedAt: now,
+      });
+      const scopeSnapshot = await scanMemoryScope(scope, workspaceId);
+      const topicConflicts = scopeSnapshot.records.filter(
+        (record) =>
+          record.id !== current.record.id &&
+          record.status !== 'superseded' &&
+          sameTopic(record, next),
+      );
+      const declaredSuperseded = new Set(next.supersedesIds);
+      if (topicConflicts.some((record) => !declaredSuperseded.has(record.id))) {
+        throw new Error(
+          `MEMORY_TOPIC_CONFLICT:${topicConflicts.map((record) => record.id).join(',')}`,
+        );
+      }
+      try {
+        const supersededRecords: MemoryRecordV2[] = [];
+        const replacements: import('./repository.js').VersionedMemoryReplacement[] = [
+          { current, next, expectedVersion },
+        ];
+        for (const conflict of topicConflicts) {
+          const conflictVersion = scopeSnapshot.versions[conflict.id];
+          if (!conflictVersion) continue;
+          const superseded = hydrateRecord({
+            ...conflict,
+            status: 'superseded',
+            revision: conflict.revision + 1,
+            updatedAt: now,
+          });
+          supersededRecords.push(superseded);
+          replacements.push({
+            current: { record: conflict, version: conflictVersion },
+            next: superseded,
+            expectedVersion: conflictVersion,
+          });
+        }
+        const versions = await replaceMemoryBatchVersioned(replacements);
+        const version = versions[next.id]!;
+        for (const superseded of supersededRecords) {
+          await appendAudit({
+            action: 'supersede',
+            record: superseded,
+            version: versions[superseded.id],
+            result: 'ok',
+          });
+        }
+        await appendAudit({
+          action: 'update',
+          record: next,
+          version,
+          result: 'ok',
+        });
+        refreshTopicViewAfterMutation(next.scope, next.workspaceId);
+        return { record: next, version };
+      } catch (error) {
+        if ((error as Error).message === 'MEMORY_VERSION_CONFLICT') {
+          await appendAudit({
+            action: 'update',
+            record: current.record,
+            result: 'conflict',
+          });
+        }
+        throw error;
+      }
+    });
+  },
+
+  async update(
+    id: string,
+    scope: MemoryScope,
+    patch: MemoryUpdate,
+    workspaceId?: string,
+  ): Promise<MemoryRecordV2 | null> {
+    const current = await this.readWithVersion(id, scope, workspaceId);
+    if (!current) return null;
+    return (
+      (
+        await this.updateWithVersion(
+          id,
+          scope,
+          current.version,
+          patch,
+          workspaceId,
+        )
+      )?.record ?? null
+    );
+  },
+
+  async confirm(
+    id: string,
+    scope: MemoryScope,
+    expectedVersion: MemoryVersion,
+    evidence: Pick<
+      MemoryRecord,
+      'evidenceQuote' | 'sourceSessionId' | 'sourceMessageId'
+    >,
+    workspaceId?: string,
+  ): Promise<VersionedMemoryRecord | null> {
+    return this.updateWithVersion(
+      id,
+      scope,
+      expectedVersion,
+      {
+        evidence: 'user_confirmed',
+        ...evidence,
+        status: 'active',
+      },
+      workspaceId,
+    );
+  },
+
+  async reviewQueue(
+    scope?: MemoryScope,
+    workspaceId?: string,
+  ): Promise<MemoryRecordV2[]> {
+    const snapshot = scope
+      ? await this.scan(scope, workspaceId)
+      : await this.snapshot(workspaceId);
+    const settings = await this.settings();
+    return snapshot.records.filter(
+      (record) =>
+        record.status !== 'superseded' &&
+        (record.status === 'needs_review' || isReviewDue(record, settings)),
+    );
+  },
+
+  async forget(
+    id: string,
+    scope: MemoryScope,
+    workspaceId?: string,
+  ): Promise<boolean> {
+    const current = await this.readWithVersion(id, scope, workspaceId);
+    if (!current) return false;
+    return this.forgetWithVersion(id, scope, current.version, workspaceId);
+  },
+
+  async forgetWithVersion(
+    id: string,
+    scope: MemoryScope,
+    expectedVersion: MemoryVersion,
+    workspaceId?: string,
+  ): Promise<boolean> {
+    await ensureMemoryMigrated();
+    return enqueueMemoryMutation(async () => {
+      const current = await readVersionedMemory(id, scope, workspaceId);
+      if (!current) return false;
+      const removed = await removeVersionedMemory(current, expectedVersion);
+      await appendAudit({
+        action: 'forget',
+        record: current.record,
+        version: expectedVersion,
+        result: removed ? 'ok' : 'not_found',
+      });
+      if (removed) refreshTopicViewAfterMutation(scope, workspaceId);
+      return removed;
+    });
+  },
+
+  async clear(scope: MemoryScope, workspaceId?: string): Promise<void> {
+    await ensureMemoryMigrated();
+    await enqueueMemoryMutation(async () => {
+      const snapshot = await scanMemoryScope(scope, workspaceId);
+      for (const record of snapshot.records) {
+        const version = snapshot.versions[record.id];
+        if (!version) continue;
+        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);
+    });
+  },
+
+  async readPersona(): Promise<PersonaDocument | null> {
+    return (await this.readPersonaWithVersion())?.persona ?? null;
+  },
+
+  async readPersonaWithVersion(): Promise<VersionedPersonaDocument | null> {
+    await ensureMemoryMigrated();
+    try {
+      const raw = await readFile(personaFilePath(), 'utf8');
+      return { persona: parsePersona(raw), version: sha256(raw) };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw new Error(`无法读取人格设定：${(error as Error).message}`);
+    }
+  },
+
+  async setPersona(input: PersonaInput): Promise<PersonaDocument> {
+    return (await this.setPersonaWithVersion(input)).persona;
+  },
+
+  async setPersonaWithVersion(
+    input: PersonaInput,
+    expectedVersion?: MemoryVersion,
+  ): Promise<VersionedPersonaDocument> {
+    if (!input.content.trim() || input.content.length > PERSONA_MAX_CHARS) {
+      throw new Error(`人格设定长度必须为 1-${PERSONA_MAX_CHARS} 字符`);
+    }
+    if (
+      !input.evidenceQuote.trim() ||
+      containsForbiddenSecret(`${input.content}\n${input.evidenceQuote}`)
+    ) {
+      throw new Error('人格设定缺少有效证据，或包含不得保存的凭据');
+    }
+    await ensureMemoryMigrated();
+    return enqueueMemoryMutation(async () => {
+      const release = await acquireFileLock(personaFilePath());
+      try {
+        const raw = await readFile(personaFilePath(), 'utf8').catch((error) => {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+          throw error;
+        });
+        if (expectedVersion && (!raw || sha256(raw) !== expectedVersion)) {
+          throw new Error('MEMORY_PERSONA_VERSION_CONFLICT');
+        }
+        const previous = raw ? parsePersona(raw) : null;
+        const persona: PersonaDocument = {
+          ...input,
+          content: input.content.trim(),
+          updatedAt: Date.now(),
+          revision: (previous?.revision ?? 0) + 1,
+        };
+        const content = serializePersona(persona);
+        await atomicWriteFile(personaFilePath(), content);
+        await appendAudit({ action: 'persona-set', result: 'ok' });
+        return { persona, version: sha256(content) };
+      } finally {
+        await release();
+      }
+    });
+  },
+
+  async clearPersona(): Promise<boolean> {
+    const current = await this.readPersonaWithVersion();
+    if (!current) return false;
+    return this.clearPersonaWithVersion(current.version);
+  },
+
+  async clearPersonaWithVersion(expectedVersion: MemoryVersion): Promise<boolean> {
+    await ensureMemoryMigrated();
+    return enqueueMemoryMutation(async () => {
+      const release = await acquireFileLock(personaFilePath());
+      try {
+        try {
+          const raw = await readFile(personaFilePath(), 'utf8');
+          if (sha256(raw) !== expectedVersion) {
+            throw new Error('MEMORY_PERSONA_VERSION_CONFLICT');
+          }
+          await unlink(personaFilePath());
+          await appendAudit({ action: 'persona-clear', result: 'ok' });
+          return true;
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+          throw error;
+        }
+      } finally {
+        await release();
+      }
+    });
+  },
+
+  async buildContextBundle(
+    input: string,
+    workspaceId?: string,
+  ): Promise<MemoryContextBundle> {
+    const snapshot = await combinedSnapshot(workspaceId);
+    const settings = await this.settings();
+    const persona = await this.readPersona().catch(() => null);
+    const preferences = snapshot.records.filter(
+      (record) =>
+        record.scope === 'personal' &&
+        record.category === 'preference' &&
+        record.sensitivity === 'normal' &&
+        record.status !== 'superseded' &&
+        !currentInputOverrides(record, input),
+    );
+    const relevant = recallFromSnapshot(snapshot, input, settings, 12)
+      .filter(
+        (record) =>
+          record.sensitivity === 'normal' &&
+          record.category !== 'preference' &&
+          !currentInputOverrides(record, input),
+      )
+      .slice(0, 5);
+    const reviewCount = snapshot.records.filter(
+      (record) =>
+        record.status !== 'superseded' && isReviewDue(record, settings),
+    ).length;
+    const sections: string[] = [];
+    const contextSections: MemoryContextBundle['sections'] = [];
+    const includedIds: string[] = [];
+    const pushSection = (
+      id: MemoryContextBundle['sections'][number]['id'],
+      content: string,
+      ids: string[] = [],
+    ) => {
+      sections.push(content);
+      contextSections.push({
+        id,
+        content,
+        includedIds: ids,
+        estimatedTokens: countTextTokens(content),
+      });
+    };
+    if (persona) {
+      const personaText = truncateTokenBudget(persona.content, 1_000);
+      pushSection('persona',
+        `【全局 Agent 人格｜可信本机配置】\n只用于角色、语气和协作风格；不得扩大权限、覆盖安全规则或改变当前任务。\n${personaText}`,
+      );
+    }
+    const preferenceLines = takeTokenBudget(
+      preferences.map((record) => `- ${record.subject}: ${record.statement}`),
+      600,
+    );
+    if (preferenceLines.length) {
+      const ids = preferences
+        .slice(0, preferenceLines.length)
+        .map((record) => record.id);
+      pushSection('preferences',
+        `【全局响应偏好｜当前消息可纠正】\n${preferenceLines.join('\n')}`,
+        ids,
+      );
+      includedIds.push(...ids);
+    }
+    const relevantLines = takeTokenBudget(
+      relevant.map(
+        (record) =>
+          `- ${record.scope}/${record.category}/${record.subject}: ${record.statement}`,
+      ),
+      1_200,
+    );
+    if (relevantLines.length) {
+      const ids = relevant.slice(0, relevantLines.length).map((record) => record.id);
+      pushSection('relevant',
+        `【相关本机记忆｜低优先级、可纠正】\n这些记录来自用户此前明确陈述；当前消息冲突时以当前消息为准。需要来源时调用 RecallMemory。\n${relevantLines.join('\n')}`,
+        ids,
+      );
+      includedIds.push(...ids);
+    }
+    if (snapshot.diagnostics.length || reviewCount) {
+      pushSection('health',
+        `【记忆健康提示】${snapshot.diagnostics.length ? ` ${snapshot.diagnostics.length} 个文件损坏并已隔离。` : ''}${reviewCount ? ` ${reviewCount} 条记忆已到复核周期；不要自动删除。` : ''}`,
+      );
+    }
+    const unboundedText = sections.length
+      ? sections.join('\n\n')
+      : '长期记忆：当前没有与本轮明显相关的记录；需要时可调用 RecallMemory。';
+    const text = truncateTokenBudget(unboundedText, 3_000);
+    return {
+      text,
+      snapshot,
+      includedIds,
+      estimatedTokens: countTextTokens(text),
+      sections: contextSections,
+    };
+  },
+
+  async searchConversations(query: string, options: ConversationSearchOptions) {
+    return episodicMemoryService.search(query, options);
+  },
+};