minimal-agent 0.10.0 → 0.12.0

package/src/tools/memory/memory.ts

@@ -0,0 +1,625 @@
+import { z } from 'zod';
+
+import {
+  type MemoryCategory,
+  type MemoryScope,
+  memoryService,
+} from '../../memory/memoryService.js';
+import type { Tool } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import {
+  EXPLICIT_CROSS_WORKSPACE_INTENT,
+  EXPLICIT_FORGET_INTENT,
+  EXPLICIT_MEMORY_INTENT,
+  EXPLICIT_PERSONA_INTENT,
+  confirmSensitiveMemory,
+  denyUnlessLocalOwner,
+  requireCurrentEvidence,
+} from './policy.js';
+
+const scopeSchema = z.enum(['personal', 'workspace']);
+const categorySchema = z.enum([
+  'profile',
+  'preference',
+  'topic',
+  'person',
+  'project',
+  'decision',
+]);
+function formatRecord(
+  record: Awaited<ReturnType<typeof memoryService.recall>>[number],
+  version?: string,
+): string {
+  const workspace = record.workspaceId
+    ? ` workspace=${record.workspaceId}`
+    : '';
+  const lifecycle = ` status=${record.status ?? 'active'} revision=${record.revision ?? 1}`;
+  return `- [${record.id}] ${record.category}/${record.subject}${workspace}${lifecycle}${version ? ` version=${version}` : ''}: ${record.statement}（${record.evidence}，${new Date(record.updatedAt).toISOString()}）`;
+}
+
+function diagnosticSuffix(
+  diagnostics: Array<{ path: string; message: string }>,
+): string {
+  if (!diagnostics.length) return '';
+  return `\n\n警告：有 ${diagnostics.length} 个 Markdown 记忆文件无法解析，已跳过；首个错误：${diagnostics[0]!.path}：${diagnostics[0]!.message}`;
+}
+
+const recallSchema = z.object({
+  query: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('要回忆的主题、人物、项目或偏好；省略时返回最近记忆'),
+  limit: z.number().int().min(1).max(20).optional(),
+});
+
+export const recallMemoryTool: Tool<z.infer<typeof recallSchema>> = {
+  name: 'RecallMemory',
+  description:
+    '按主题读取本机主人已保存的个人与当前工作区长期记忆。仅用于避免重复询问稳定事实；返回内容仍需结合当前用户消息判断，当前消息优先。',
+  inputSchema: recallSchema,
+  parameters: toToolParameters(recallSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'RecallMemory 需要本机会话上下文' }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx, 'read');
+    if (denied) return denied;
+    const { records, snapshot } = await memoryService.recallDetailed(
+      input.query ?? '',
+      ctx.workspaceId,
+      input.limit ?? 8,
+    );
+    const suffix = diagnosticSuffix(snapshot.diagnostics);
+    return {
+      ok: true,
+      content: `${records.length ? records.map((record) => formatRecord(record, snapshot.versions[record.id])).join('\n') : '没有匹配的长期记忆。'}${suffix}`,
+    };
+  },
+};
+
+const rememberSchema = z.object({
+  scope: scopeSchema.describe('personal 跨本机会话；workspace 仅当前工作区'),
+  category: categorySchema,
+  subject: z.string().min(1).max(120),
+  statement: z
+    .string()
+    .min(1)
+    .max(1000)
+    .describe('只记录用户明确表达的稳定事实、偏好或决定，不记录推断'),
+  evidenceQuote: z
+    .string()
+    .min(1)
+    .max(1000)
+    .describe('当前用户消息中的逐字证据片段'),
+  sensitivity: z.enum(['normal', 'sensitive']).optional(),
+  aliases: z.array(z.string().min(1).max(120)).max(20).optional(),
+});
+
+export const rememberMemoryTool: Tool<z.infer<typeof rememberSchema>> = {
+  name: 'RememberMemory',
+  description:
+    '保存本机主人明确陈述的稳定事实、偏好或决定。evidenceQuote 必须逐字来自当前用户消息；不得保存推断、搜索结果、代码事实、短期状态或任何凭据。敏感内容必须由交互宿主再次确认。',
+  inputSchema: rememberSchema,
+  parameters: toToolParameters(rememberSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'RememberMemory 需要本机会话上下文' }),
+  callWithContext: async (input, signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx);
+    if (denied) return denied;
+    const current = ctx.currentUserInput ?? '';
+    const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
+    if (invalidEvidence) return invalidEvidence;
+    if (input.scope === 'workspace' && !ctx.workspaceId) {
+      return {
+        ok: false,
+        error: '当前会话没有稳定 workspaceId，不能保存工作区记忆',
+      };
+    }
+    const sensitivity = input.sensitivity ?? 'normal';
+    if (
+      sensitivity === 'sensitive' &&
+      input.statement.trim() === input.evidenceQuote.trim()
+    ) {
+      return {
+        ok: false,
+        error: '敏感内容不得逐字保存；请先概括、去除不必要细节后再请求确认',
+      };
+    }
+    let evidence: 'user_stated' | 'user_confirmed' = 'user_stated';
+    if (
+      sensitivity === 'normal' &&
+      !(await memoryService.settings()).autoRemember
+    ) {
+      if (!EXPLICIT_MEMORY_INTENT.test(current)) {
+        return {
+          ok: false,
+          error:
+            '用户已关闭自动记忆；只有用户在当前消息中明确要求记住时才能写入',
+        };
+      }
+      evidence = 'user_confirmed';
+    }
+    if (sensitivity === 'sensitive') {
+      const confirmed = await confirmSensitiveMemory(
+        input.statement,
+        sensitivity,
+        signal,
+      );
+      if (!confirmed)
+        return {
+          ok: false,
+          error: '敏感记忆需要交互确认，且只能保存概括后的内容',
+        };
+      evidence = confirmed;
+    }
+    const record = await memoryService.remember({
+      scope: input.scope as MemoryScope,
+      ...(input.scope === 'workspace' ? { workspaceId: ctx.workspaceId } : {}),
+      category: input.category as MemoryCategory,
+      subject: input.subject,
+      statement: input.statement,
+      evidence,
+      evidenceQuote: input.evidenceQuote,
+      sourceSessionId: ctx.sessionId ?? 'unknown',
+      sourceMessageId: ctx.userMessageId ?? 'unknown',
+      sensitivity,
+      ...(input.aliases ? { aliases: input.aliases } : {}),
+    });
+    return {
+      ok: true,
+      content: `已保存本机${record.scope === 'personal' ? '个人' : '工作区'}记忆：${record.subject}（id=${record.id}）`,
+    };
+  },
+};
+
+const updateSchema = z.object({
+  id: z.string().uuid(),
+  scope: scopeSchema,
+  category: categorySchema.optional(),
+  subject: z.string().min(1).max(120).optional(),
+  statement: z.string().min(1).max(1000),
+  evidenceQuote: z
+    .string()
+    .min(1)
+    .max(1000)
+    .describe('当前用户消息中的逐字证据片段'),
+  sensitivity: z.enum(['normal', 'sensitive']).optional(),
+  aliases: z.array(z.string().min(1).max(120)).max(20).optional(),
+  supersedesIds: z
+    .array(z.string().uuid())
+    .max(20)
+    .optional()
+    .describe('明确解决同主题冲突时被此记录替代的 ID'),
+  expectedVersion: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/i)
+    .optional()
+    .describe(
+      'RecallMemory/read 返回的文件版本；提供后可防止覆盖手工或并发修改',
+    ),
+});
+
+export const updateMemoryTool: Tool<z.infer<typeof updateSchema>> = {
+  name: 'UpdateMemory',
+  description:
+    '在用户当前陈述纠正或替换旧事实时，按 RecallMemory 返回的 ID 整条更新。必须先读取旧记录，evidenceQuote 必须逐字来自当前用户消息；不得用推断补写历史。',
+  inputSchema: updateSchema,
+  parameters: toToolParameters(updateSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'UpdateMemory 需要本机会话上下文' }),
+  callWithContext: async (input, signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx);
+    if (denied) return denied;
+    const current = ctx.currentUserInput ?? '';
+    const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
+    if (invalidEvidence) return invalidEvidence;
+    if (input.scope === 'workspace' && !ctx.workspaceId) {
+      return {
+        ok: false,
+        error: '当前会话没有稳定 workspaceId，不能更新工作区记忆',
+      };
+    }
+    if (
+      !(await memoryService.settings()).autoRemember &&
+      !EXPLICIT_MEMORY_INTENT.test(current)
+    ) {
+      return {
+        ok: false,
+        error: '用户已关闭自动记忆；当前消息没有明确要求更新记忆',
+      };
+    }
+    const sensitivity = input.sensitivity ?? 'normal';
+    if (
+      sensitivity === 'sensitive' &&
+      input.statement.trim() === input.evidenceQuote.trim()
+    ) {
+      return {
+        ok: false,
+        error: '敏感内容不得逐字更新；请先概括、去除不必要细节后再请求确认',
+      };
+    }
+    const evidence = await confirmSensitiveMemory(
+      input.statement,
+      sensitivity,
+      signal,
+    );
+    if (!evidence) return { ok: false, error: '敏感记忆更新未获确认' };
+    const currentRecord = await memoryService.readWithVersion(
+      input.id,
+      input.scope,
+      input.scope === 'workspace' ? ctx.workspaceId : undefined,
+    );
+    if (!currentRecord) return { ok: false, error: '未找到该记忆，未做修改' };
+    const expectedVersion = input.expectedVersion ?? currentRecord.version;
+    let updated: Awaited<ReturnType<typeof memoryService.updateWithVersion>>;
+    try {
+      updated = await memoryService.updateWithVersion(
+        input.id,
+        input.scope,
+        expectedVersion,
+        {
+          ...(input.category
+            ? { category: input.category as MemoryCategory }
+            : {}),
+          ...(input.subject ? { subject: input.subject } : {}),
+          statement: input.statement,
+          evidence,
+          evidenceQuote: input.evidenceQuote,
+          sourceSessionId: ctx.sessionId ?? 'unknown',
+          sourceMessageId: ctx.userMessageId ?? 'unknown',
+          sensitivity,
+          ...(input.aliases ? { aliases: input.aliases } : {}),
+          ...(input.supersedesIds
+            ? { supersedesIds: input.supersedesIds }
+            : {}),
+        },
+        input.scope === 'workspace' ? ctx.workspaceId : undefined,
+      );
+    } catch (error) {
+      if ((error as Error).message === 'MEMORY_VERSION_CONFLICT') {
+        return {
+          ok: false,
+          error:
+            '记忆已被手工或并发修改。请重新 RecallMemory 后基于新版本更新。',
+        };
+      }
+      if ((error as Error).message.startsWith('MEMORY_TOPIC_CONFLICT:')) {
+        return {
+          ok: false,
+          error: `存在其他同主题有效记忆：${(error as Error).message.split(':')[1]}。请先召回并通过 supersedesIds 明确合并。`,
+        };
+      }
+      throw error;
+    }
+    return updated
+      ? {
+          ok: true,
+          content: `已更新本机${updated.record.scope === 'personal' ? '全局' : '工作区'}记忆：${updated.record.subject}（id=${updated.record.id}，version=${updated.version}）`,
+        }
+      : { ok: false, error: '未找到该记忆，未做修改' };
+  },
+};
+
+const listSchema = z.object({
+  scope: scopeSchema.optional().describe('缺省同时列出个人与当前工作区记忆'),
+  limit: z.number().int().min(1).max(100).optional(),
+});
+
+export const listMemoriesTool: Tool<z.infer<typeof listSchema>> = {
+  name: 'ListMemories',
+  description:
+    '列出本机主人当前范围的长期记忆摘要，用于用户明确要求查看记忆时。',
+  inputSchema: listSchema,
+  parameters: toToolParameters(listSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'ListMemories 需要本机会话上下文' }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx, 'read');
+    if (denied) return denied;
+    const snapshot =
+      input.scope === 'personal'
+        ? await memoryService.scan('personal')
+        : input.scope === 'workspace'
+          ? ctx.workspaceId
+            ? await memoryService.scan('workspace', ctx.workspaceId)
+            : {
+                records: [],
+                diagnostics: [],
+                versions: {},
+                createdAt: Date.now(),
+              }
+          : (
+              await memoryService.recallDetailed(
+                '',
+                ctx.workspaceId,
+                input.limit ?? 20,
+              )
+            ).snapshot;
+    const records = snapshot.records;
+    const content =
+      records
+        .slice(0, input.limit ?? 20)
+        .map((record) => formatRecord(record, snapshot.versions[record.id]))
+        .join('\n') || '当前没有长期记忆。';
+    return {
+      ok: true,
+      content: `${content}${diagnosticSuffix(snapshot.diagnostics)}`,
+    };
+  },
+};
+
+const forgetSchema = z.object({
+  id: z.string().uuid(),
+  scope: scopeSchema,
+});
+
+export const forgetMemoryTool: Tool<z.infer<typeof forgetSchema>> = {
+  name: 'ForgetMemory',
+  description:
+    '仅在用户明确要求删除某条长期记忆时按 ID 删除。不得自行清理或猜测用户想忘记什么。',
+  inputSchema: forgetSchema,
+  parameters: toToolParameters(forgetSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'ForgetMemory 需要本机会话上下文' }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx);
+    if (denied) return denied;
+    if (!EXPLICIT_FORGET_INTENT.test(ctx.currentUserInput ?? '')) {
+      return {
+        ok: false,
+        error: '只有用户当前消息明确要求忘记或删除时才能删除长期记忆',
+      };
+    }
+    const removed = await memoryService.forget(
+      input.id,
+      input.scope,
+      input.scope === 'workspace' ? ctx.workspaceId : undefined,
+    );
+    return removed
+      ? { ok: true, content: `已删除记忆 ${input.id}` }
+      : { ok: false, error: '未找到该记忆，未做修改' };
+  },
+};
+
+const setPersonaSchema = z.object({
+  content: z
+    .string()
+    .min(1)
+    .max(4000)
+    .describe(
+      '用户明确要求的 Agent 角色、语气与协作风格；不得加入权限扩张或新任务',
+    ),
+  evidenceQuote: z
+    .string()
+    .min(1)
+    .max(1000)
+    .describe('当前用户消息中的逐字证据片段'),
+});
+
+export const setPersonaTool: Tool<z.infer<typeof setPersonaSchema>> = {
+  name: 'SetPersona',
+  description:
+    '仅在用户明确要求设置或修改 Agent 人格、角色、语气或协作风格时覆盖全局 persona.md。人格不能扩大权限、覆盖安全规则或改变当前任务。',
+  inputSchema: setPersonaSchema,
+  parameters: toToolParameters(setPersonaSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'SetPersona 需要本机会话上下文' }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx);
+    if (denied) return denied;
+    const current = ctx.currentUserInput ?? '';
+    if (
+      !current.includes(input.evidenceQuote) ||
+      !EXPLICIT_PERSONA_INTENT.test(current)
+    ) {
+      return {
+        ok: false,
+        error:
+          '当前用户消息没有明确的人格设置要求，或 evidenceQuote 不是逐字证据',
+      };
+    }
+    await memoryService.setPersona({
+      content: input.content,
+      evidenceQuote: input.evidenceQuote,
+      sourceSessionId: ctx.sessionId ?? 'unknown',
+      sourceMessageId: ctx.userMessageId ?? 'unknown',
+    });
+    return {
+      ok: true,
+      content: '已更新全局 Agent 人格设定；从下一次用户回合开始生效。',
+    };
+  },
+};
+
+const clearPersonaSchema = z.object({});
+
+export const clearPersonaTool: Tool<z.infer<typeof clearPersonaSchema>> = {
+  name: 'ClearPersona',
+  description:
+    '仅在用户明确要求清除或重置 Agent 人格设定时删除 persona.md，恢复内置默认人格。',
+  inputSchema: clearPersonaSchema,
+  parameters: toToolParameters(clearPersonaSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'ClearPersona 需要本机会话上下文' }),
+  callWithContext: async (_input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx);
+    if (denied) return denied;
+    const current = ctx.currentUserInput ?? '';
+    if (
+      !/(?:清除|删除|重置|恢复默认).{0,12}(?:人格|人设|角色设定|语气|风格)|reset.{0,12}(?:persona|personality|style)/i.test(
+        current,
+      )
+    ) {
+      return {
+        ok: false,
+        error: '只有用户当前消息明确要求重置人格时才能删除人格设定',
+      };
+    }
+    const removed = await memoryService.clearPersona();
+    return {
+      ok: true,
+      content: removed
+        ? '已清除全局 Agent 人格设定。'
+        : '当前没有自定义 Agent 人格设定。',
+    };
+  },
+};
+
+const confirmMemorySchema = z.object({
+  id: z.string().uuid(),
+  scope: scopeSchema,
+  expectedVersion: z.string().regex(/^[0-9a-f]{64}$/i),
+  evidenceQuote: z
+    .string()
+    .min(1)
+    .max(1000)
+    .describe('当前用户消息中重新确认该事实的逐字证据'),
+});
+
+export const confirmMemoryTool: Tool<z.infer<typeof confirmMemorySchema>> = {
+  name: 'ConfirmMemory',
+  description:
+    '用户明确重申一条已有记忆时更新时间与版本，不创建重复记录。必须使用读取到的 ID/version，并提供当前消息证据。',
+  inputSchema: confirmMemorySchema,
+  parameters: toToolParameters(confirmMemorySchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'ConfirmMemory 需要本机会话上下文' }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx);
+    if (denied) return denied;
+    const invalidEvidence = requireCurrentEvidence(ctx, input.evidenceQuote);
+    if (invalidEvidence) return invalidEvidence;
+    if (!EXPLICIT_MEMORY_INTENT.test(ctx.currentUserInput ?? '')) {
+      return { ok: false, error: '当前消息没有明确确认或更新记忆的意图' };
+    }
+    try {
+      const updated = await memoryService.confirm(
+        input.id,
+        input.scope,
+        input.expectedVersion,
+        {
+          evidenceQuote: input.evidenceQuote,
+          sourceSessionId: ctx.sessionId ?? 'unknown',
+          sourceMessageId: ctx.userMessageId ?? 'unknown',
+        },
+        input.scope === 'workspace' ? ctx.workspaceId : undefined,
+      );
+      return updated
+        ? {
+            ok: true,
+            content: `已确认记忆 ${updated.record.id}（revision=${updated.record.revision}，version=${updated.version}）`,
+          }
+        : { ok: false, error: '未找到该记忆，未做修改' };
+    } catch (error) {
+      if ((error as Error).message === 'MEMORY_VERSION_CONFLICT') {
+        return { ok: false, error: '记忆版本已变化，请重新读取后确认' };
+      }
+      throw error;
+    }
+  },
+};
+
+const reviewMemoriesSchema = z.object({
+  scope: scopeSchema.optional(),
+  limit: z.number().int().min(1).max(100).optional(),
+});
+
+export const reviewMemoriesTool: Tool<z.infer<typeof reviewMemoriesSchema>> = {
+  name: 'ReviewMemories',
+  description:
+    '列出已到复核周期或显式标记 needs_review 的记忆。只提示用户复核，绝不自动更新或删除。',
+  inputSchema: reviewMemoriesSchema,
+  parameters: toToolParameters(reviewMemoriesSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({ ok: false, error: 'ReviewMemories 需要本机会话上下文' }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx, 'read');
+    if (denied) return denied;
+    const records = await memoryService.reviewQueue(
+      input.scope,
+      ctx.workspaceId,
+    );
+    return {
+      ok: true,
+      content:
+        records
+          .slice(0, input.limit ?? 20)
+          .map((record) => formatRecord(record))
+          .join('\n') || '当前没有需要复核的长期记忆。',
+    };
+  },
+};
+
+const searchConversationsSchema = z.object({
+  query: z.string().min(1).max(500),
+  scope: z
+    .enum(['workspace', 'all'])
+    .optional()
+    .describe('默认仅当前工作区；all 必须由用户当前消息明确要求跨项目'),
+  limit: z.number().int().min(1).max(20).optional(),
+});
+
+export const searchConversationsTool: Tool<
+  z.infer<typeof searchConversationsSchema>
+> = {
+  name: 'SearchConversations',
+  description:
+    '搜索本机历史会话原文。用户提到“之前、上次、那个方案、我们讨论过”等共享历史线索时使用；query 只填项目名、人名、主题等内容名词，不填“之前讨论”等元词或整段消息。默认仅当前工作区；助手建议、草稿和假设不能当作用户长期事实。',
+  inputSchema: searchConversationsSchema,
+  parameters: toToolParameters(searchConversationsSchema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  call: async () => ({
+    ok: false,
+    error: 'SearchConversations 需要本机会话上下文',
+  }),
+  callWithContext: async (input, _signal, ctx) => {
+    const denied = denyUnlessLocalOwner(ctx, 'read');
+    if (denied) return denied;
+    if (!ctx.workspaceId)
+      return { ok: false, error: '当前会话没有稳定 workspaceId' };
+    const crossWorkspace = input.scope === 'all';
+    const explicitCrossWorkspace =
+      crossWorkspace &&
+      EXPLICIT_CROSS_WORKSPACE_INTENT.test(ctx.currentUserInput ?? '');
+    if (crossWorkspace && !explicitCrossWorkspace) {
+      return { ok: false, error: '跨工作区历史检索必须由用户当前消息明确提出' };
+    }
+    const results = await memoryService.searchConversations(input.query, {
+      workspaceId: ctx.workspaceId,
+      scope: input.scope ?? 'workspace',
+      explicitCrossWorkspace,
+      limit: input.limit ?? 8,
+    });
+    return {
+      ok: true,
+      content:
+        results
+          .map(
+            (item) =>
+              `- [${item.role}] workspace=${item.workspaceId} session=${item.sessionId} ${new Date(item.createdAt).toISOString()}: ${item.snippet}`,
+          )
+          .join('\n') || '没有匹配的历史会话片段。',
+    };
+  },
+};

package/src/tools/memory/policy.js

@@ -0,0 +1,53 @@
+import { hasAskHandler, requestUserChoice } from '../../askBridge.js';
+export const EXPLICIT_MEMORY_INTENT = /记住|记下来|保存.{0,8}(?:记忆|偏好|决定)|更新.{0,8}(?:记忆|偏好|决定)|确认.{0,8}(?:记忆|偏好|事实)|remember|save.{0,12}(?:memory|preference|decision)|update.{0,12}(?:memory|preference|decision)|confirm.{0,12}(?:memory|fact)/i;
+export const EXPLICIT_FORGET_INTENT = /忘记|别再记|删除.{0,8}(?:记忆|偏好|决定)|清除.{0,8}(?:记忆|偏好|决定)|forget|delete.{0,12}(?:memory|preference|decision)/i;
+export const EXPLICIT_PERSONA_INTENT = /人格|人设|角色设定|你的(?:语气|风格|性格)|你以后.{0,12}(?:说话|回答|表现)|扮演|persona|your (?:tone|style|personality)|act as/i;
+export const EXPLICIT_CROSS_WORKSPACE_INTENT = /所有(?:项目|工作区)|跨(?:项目|工作区)|其他(?:项目|工作区)|all (?:projects|workspaces)|across (?:projects|workspaces)/i;
+export function denyUnlessLocalOwner(ctx, access = 'write') {
+    const allowed = access === 'read'
+        ? ctx.memoryAccess === 'read-only'
+            || ctx.memoryAccess === 'read-write'
+            || ctx.memoryAccess === 'local-owner'
+        : ctx.memoryAccess === 'read-write' || ctx.memoryAccess === 'local-owner';
+    if (allowed)
+        return null;
+    return {
+        ok: false,
+        error: ctx.memoryAccess === 'read-only'
+            ? '当前本机会话对长期记忆只有读取权限；请交由主 Agent 完成写入'
+            : '当前宿主未获长期记忆访问权限',
+        recovery: 'user-action',
+        sensitivity: 'local',
+    };
+}
+export function requireCurrentEvidence(ctx, evidenceQuote) {
+    return (ctx.currentUserInput ?? '').includes(evidenceQuote)
+        ? null
+        : {
+            ok: false,
+            error: 'evidenceQuote 不是当前用户消息的逐字片段，拒绝写入推断性记忆',
+        };
+}
+export async function confirmSensitiveMemory(statement, sensitivity, signal) {
+    if (sensitivity === 'normal')
+        return 'user_stated';
+    if (!hasAskHandler())
+        return null;
+    const [answer] = await requestUserChoice([
+        {
+            header: '保存记忆',
+            question: `是否把概括后的内容“${statement.slice(0, 120)}”保存为本机长期记忆？`,
+            options: [
+                {
+                    label: '不保存（推荐）',
+                    description: '继续当前任务，但不写入长期记忆。',
+                },
+                {
+                    label: '确认保存',
+                    description: '只保存概括；原始敏感证据不会写入 Markdown。',
+                },
+            ],
+        },
+    ], signal);
+    return answer?.selected.includes('确认保存') ? 'user_confirmed' : null;
+}