aws-runtime-bridge 1.9.33 → 1.9.40

package/package/aws-client-agent-mcp/dist/mcp-server.js

@@ -3,6 +3,7 @@
  * 提供 MCP Tools 供 AI Agent 调用
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -56,7 +57,7 @@ export class McpServer {
      */
     notifiedFileChangeMemoryIds = new Map();
     /**
-     * 本地缓存 listable 记忆（task_list/recently_memory）的文件 MD5 map。
+     * 本地缓存 listable 记忆（recently_memory/agent_memory）的文件 MD5 map。
      * 服务端（Java 后端）不持久化 file_md5_map 字段，listByType 返回的记录该字段为 undefined。
      * 必须本地缓存才能让 checkMemoriesFileChanges 有正确的旧 MD5 做对比。
      */
@@ -70,6 +71,17 @@ export class McpServer {
      */
     memoryNotificationNullCache = new Map();
     static MEMORY_NOTIFICATION_NULL_TTL_MS = 60_000;
+    /**
+     * poll_message 单例控制：防止并发调用导致消息被第一个消费后第二个空等。
+     * 当已有 poll 在进行时，后续调用直接等待同一个 Promise。
+     */
+    pendingPollMessage = null;
+    /**
+     * Todo 未完成项提醒去重指纹：记录上次通知时的未完成项内容/状态/优先级快照。
+     * 指纹一致则不重复通知；todos 变化时再次通知。
+     * 进程重启后自动清空（届时会重新通知一次，可接受）。
+     */
+    lastTodoNotificationFingerprint = null;
     // 系统提示词由 runtime adapter（ACode/OpenCode/Codex/Claude）在会话创建时注入，
     // 无需通过 MCP 工具返回。三方 runtime（OpenCode/Claude）将三层提示词合并为一条 system prompt，
     // ACode 则直接注入为前三条 system role 消息。
@@ -90,6 +102,100 @@ export class McpServer {
         this.roleMemoryStore = new MemoryStore(McpServer.buildRoleMemoryStorePath(expectedRoleDir));
         this.initialRoleName = expectedRoleDir;
     }
+    /**
+     * 在 profile 到达后检查是否需要将本地永久记忆同步到 server。
+     * 触发条件：当前角色在 server 上还没有任何 memory 类型记录（通常发生在重部署后 server DB 为空时）。
+     * 主流程：异步执行，不阻塞 profile 处理链路。
+     * 1. 调用 server get_memory_stats 获取当前角色 memory 类型计数
+     * 2. 若 count === 0，读取本地永久记忆（角色子目录 + 遗留父目录 fallback）
+     * 3. 逐条调用 server create_memory 写入（已存在则静默跳过）
+     */
+    maybeSyncPermanentMemoryToServer() {
+        this.doMaybeSyncPermanentMemoryToServer().catch((e) => {
+            logger.warn("[McpServer] maybeSyncPermanentMemoryToServer 异常:", e);
+        });
+    }
+    async doMaybeSyncPermanentMemoryToServer() {
+        logger.info("[McpServer] maybeSyncPermanentMemoryToServer 开始，initialRoleName="
+            + this.initialRoleName);
+        // Step 1: 检查 server 当前角色的 memory 计数
+        let stats;
+        try {
+            stats = await this.memoryStore.getStats();
+        }
+        catch (e) {
+            logger.warn("[McpServer] 获取 server 记忆统计失败，跳过同步:", e instanceof Error ? e.message : e);
+            return;
+        }
+        const memoryCount = stats.by_type["project_memory"]?.count ?? 0;
+        logger.info(`[McpServer] server memory 计数=${memoryCount}，`
+            + `是否需要同步=${memoryCount === 0}`);
+        if (memoryCount > 0) {
+            return;
+        }
+        // Step 2: 读取本地永久记忆
+        // 2a: 先读角色子目录
+        let localMemories = [];
+        try {
+            localMemories = await this.roleMemoryStore.listByType("project_memory");
+            logger.info(`[McpServer] 角色子目录读取到 ${localMemories.length} 条永久记忆`);
+        }
+        catch (e) {
+            logger.warn("[McpServer] 读取角色子目录永久记忆失败:", e instanceof Error ? e.message : e);
+        }
+        // 2b: 角色子目录为空时，fallback 读遗留父目录（旧版无角色子目录）
+        if (localMemories.length === 0) {
+            const legacyStorePath = path.dirname(McpServer.buildRoleMemoryStorePath(this.initialRoleName));
+            logger.info(`[McpServer] 尝试从遗留目录读取: ${legacyStorePath}`);
+            try {
+                const legacyStore = new MemoryStore(legacyStorePath);
+                const legacyMemories = await legacyStore.listByType("project_memory");
+                if (legacyMemories.length > 0) {
+                    logger.info(`[McpServer] 从遗留目录读取到 ${legacyMemories.length} 条永久记忆`);
+                    localMemories = legacyMemories;
+                }
+            }
+            catch (e) {
+                logger.warn("[McpServer] 读取遗留目录永久记忆失败:", e instanceof Error ? e.message : e);
+            }
+        }
+        if (localMemories.length === 0) {
+            logger.info("[McpServer] 本地也无永久记忆，跳过同步");
+            return;
+        }
+        // Step 3: 逐条写入 server
+        let synced = 0;
+        let skipped = 0;
+        for (const record of localMemories) {
+            try {
+                await this.memoryStore.createMemory({
+                    memory_type: "project_memory",
+                    uri: record.uri,
+                    title: record.title,
+                    content: record.content,
+                    keywords: record.keywords,
+                    bound_files: record.bound_files,
+                    file_md5_map: record.file_md5_map,
+                    last_check_time: record.last_check_time,
+                });
+                synced++;
+                logger.info(`[McpServer] 同步永久记忆成功: ${record.uri}`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                if (msg.includes("already exists")
+                    || msg.includes("Memory already exists")) {
+                    skipped++;
+                }
+                else {
+                    logger.warn(`[McpServer] 同步永久记忆失败 (${record.uri}): ${msg}`);
+                    skipped++;
+                }
+            }
+        }
+        logger.info(`[McpServer] 永久记忆同步完成: 成功 ${synced}, 跳过 ${skipped}, 共 ${localMemories.length}`);
+        await this.reportCombinedMemoryStats();
+    }
     /**
      * 规范化绑定的文件路径。
      * 项目约定以下前缀都表示工作区根路径：
@@ -281,8 +387,6 @@ export class McpServer {
             case "get_profile": {
                 return await this.agentClient.getProfile();
             }
-            case "get_status":
-                return this.agentClient.getState();
             case "hire_colleague":
                 return await this.handleHireColleague(args);
             case "hire_colleagues_batch":
@@ -329,8 +433,6 @@ export class McpServer {
                 return await this.handleListMemories(args);
             case "get_memory_stats":
                 return await this.handleGetMemoryStats(args);
-            case "archive_recently_memory":
-                return await this.handleArchiveRecentlyMemory(args);
             // Memory 增强功能工具 (v1.6.0)
             case "list_memories_by_file":
                 return await this.handleListMemoriesByFile(args);
@@ -341,23 +443,15 @@ export class McpServer {
                 return await this.handleMemoryRecurrence(args);
             case "memory_recurrence_complete":
                 return await this.handleMemoryRecurrenceComplete();
-            // Memory 短期记忆 TODO 完成工具 (v1.14.0)
-            case "todo_completed":
-                return await this.handleTodoCompleted(args);
-            // 上下文压缩工具 (v1.8.0)
-            case "get_context_stats":
-                return await this.handleGetContextStats(args);
-            case "compact_context":
-                return await this.handleCompactContext(args);
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
     }
     // ============ 工具处理方法 ============
     static MEMORY_TYPES = [
-        "task_list",
         "recently_memory",
-        "memory",
+        "agent_memory",
+        "project_memory",
         "session_context",
     ];
     static MEMORY_TOOL_NAMES = new Set([
@@ -368,15 +462,12 @@ export class McpServer {
         "search_memory",
         "list_memories",
         "get_memory_stats",
-        "archive_recently_memory",
         // Memory 增强功能工具 (v1.6.0)
         "list_memories_by_file",
         "abandon_memory_update",
         // Memory 近期记忆过期与回忆工具 (v1.11.0)
         "memory_recurrence",
         "memory_recurrence_complete",
-        // Memory 短期记忆 TODO 完成工具 (v1.14.0)
-        "todo_completed",
     ]);
     /**
      * 从 startPath 向上逐级查找 .agentswork 目录。
@@ -427,7 +518,7 @@ export class McpServer {
     }
     /**
      * 解析记忆存储路径。
-     * 主流程：task_list/recently_memory 走 server 数据库；长期 memory 默认写入项目 .agentswork/memory/memory/<roleName>/<domain>.json。
+     * 主流程：recently_memory/agent_memory 走 server 数据库；长期 project_memory 默认写入项目 .agentswork/memory/memory/<roleName>/<domain>.json。
      */
     static resolveMemoryStorePaths() {
         const configuredPath = String(process.env.AWS_MEMORY_STORE_PATH || "").trim();
@@ -483,16 +574,16 @@ export class McpServer {
     }
     /**
      * 按记忆生命周期选择存储作用域。
-     * 主流程：长期 memory 走角色级 store；task_list/recently_memory 走当前 Agent 实例级 store。
+     * 主流程：长期 project_memory 走角色级 store；recently_memory/agent_memory 走当前 Agent 实例级 store。
      */
     /**
      * 按记忆生命周期选择存储作用域。
-     * 主流程：永久记忆(memory)仅在 hasRoleName 为 true 时走角色级 store，
-     *         否则回退到实例级 server store（避免空角色名下所有实例共享 default-role 目录导致跨角色污染）。
-     * task_list/recently_memory/session_context 始终走实例级 store。
+     * 主流程：永久记忆(project_memory)始终走本地 roleMemoryStore（.agentswork），
+     *         确保本地文件始终有副本，后续部署恢复时可通过 Local → Server 同步回 server。
+     * recently_memory/agent_memory/session_context 始终走实例级 server store。
      */
     getMemoryStoreForType(memoryType) {
-        if (memoryType === "memory" && this.hasRoleName) {
+        if (memoryType === "project_memory") {
             return this.roleMemoryStore;
         }
         return this.memoryStore;
@@ -508,15 +599,12 @@ export class McpServer {
         if (input.memory_type) {
             return await this.getMemoryStoreForType(input.memory_type).readMemory(input);
         }
-        // hasRoleName 为 false 时不查 roleMemoryStore，避免空角色名共享 default-role 目录
-        if (this.hasRoleName) {
-            const longTermRecord = await this.roleMemoryStore.readMemory({
-                ...input,
-                memory_type: "memory",
-            });
-            if (longTermRecord) {
-                return longTermRecord;
-            }
+        const longTermRecord = await this.roleMemoryStore.readMemory({
+            ...input,
+            memory_type: "project_memory",
+        });
+        if (longTermRecord) {
+            return longTermRecord;
         }
         return await this.memoryStore.readMemory(input);
     }
@@ -534,14 +622,12 @@ export class McpServer {
                 memory_type: input.memory_type,
             };
         }
-        if (this.hasRoleName) {
-            const longTermRecord = await this.roleMemoryStore.readMemory({
-                uri: input.uri,
-                memory_type: "memory",
-            });
-            if (longTermRecord) {
-                return { store: this.roleMemoryStore, memory_type: "memory" };
-            }
+        const longTermRecord = await this.roleMemoryStore.readMemory({
+            uri: input.uri,
+            memory_type: "project_memory",
+        });
+        if (longTermRecord) {
+            return { store: this.roleMemoryStore, memory_type: "project_memory" };
         }
         return { store: this.memoryStore };
     }
@@ -558,17 +644,17 @@ export class McpServer {
         // permanentCount 取两者的较大值作为保守估计（下界）。
         // 注意: 当 instance 和 role 分别有对方没有的唯一 URI 时，实际并集 > Math.max，
         // 但此处只有 count 无 URI 列表，无法精确计算并集，使用下界避免面板显示虚高。
-        const permanentCount = Math.max(instanceStats.by_type.memory.count, roleStats.by_type.memory.count);
-        // total 同样保守估算：用 server 非 memory count + permanentCount 下界
-        const serverNonMemoryTotal = instanceStats.total - instanceStats.by_type.memory.count;
+        const permanentCount = Math.max(instanceStats.by_type.project_memory.count, roleStats.by_type.project_memory.count);
+        // total 同样保守估算：用 server 非 project_memory count + permanentCount 下界
+        const serverNonMemoryTotal = instanceStats.total - instanceStats.by_type.project_memory.count;
         return {
             total: serverNonMemoryTotal + permanentCount,
             listable: instanceStats.listable,
             by_type: {
-                task_list: instanceStats.by_type.task_list,
                 recently_memory: instanceStats.by_type.recently_memory,
-                memory: {
-                    ...roleStats.by_type.memory,
+                agent_memory: instanceStats.by_type.agent_memory,
+                project_memory: {
+                    ...roleStats.by_type.project_memory,
                     count: permanentCount,
                 },
                 session_context: instanceStats.by_type.session_context,
@@ -591,44 +677,6 @@ export class McpServer {
             logger.warn("[McpServer] 上报合并 memory 统计失败，已保留本地记忆写入结果:", error);
         }
     }
-    /**
-     * 同步本地永久记忆到服务端。
-     * 主流程：读取本地 roleMemoryStore 中所有 memory 类型记录 -> 逐条写入服务端 memoryStore -> 已存在的记录静默跳过。
-     */
-    async syncLocalPermanentMemoryToServer() {
-        if (!this.hasRoleName)
-            return;
-        try {
-            const memories = await this.roleMemoryStore.listByType("memory");
-            if (memories.length === 0)
-                return;
-            let syncedCount = 0;
-            for (const memory of memories) {
-                try {
-                    await this.memoryStore.createMemory({
-                        memory_type: "memory",
-                        uri: memory.uri,
-                        title: memory.title,
-                        content: memory.content,
-                        keywords: memory.keywords,
-                        bound_files: memory.bound_files,
-                    });
-                    syncedCount++;
-                }
-                catch (e) {
-                    // If already exists on server, skip
-                    const errMsg = e instanceof Error ? e.message : String(e);
-                    if (!errMsg.includes("already exists")) {
-                        logger.warn(`[McpServer] Failed to sync permanent memory ${memory.uri}:`, e);
-                    }
-                }
-            }
-            logger.info(`[McpServer] Synced ${syncedCount}/${memories.length} permanent memories to server`);
-        }
-        catch (error) {
-            logger.error("[McpServer] Failed to sync permanent memories to server:", error);
-        }
-    }
     /**
      * 系统提示词由 runtime adapter 在会话创建时注入，MCP 层面不再负责返回。
      * 详见 startListeningInternal -> profileHandler 中的合并注入逻辑。
@@ -698,16 +746,16 @@ export class McpServer {
         const created = await this.getMemoryStoreForType(input.memory_type).createMemory(input);
         await this.reportCombinedMemoryStats();
         // Dual-write permanent memory to server
-        if (input.memory_type === "memory") {
+        if (input.memory_type === "project_memory") {
             try {
-                await this.memoryStore.createMemory(input).catch(() => { });
+                await this.memoryStore.createMemory(input);
             }
             catch (e) {
                 logger.warn("[McpServer] Failed to sync permanent memory to server:", e);
             }
         }
-        // v1.13.0: recently_memory 过期判定、task_list todo 状态由服务端 memory_status 字段管理，
-        // 无需 TS 侧本地缓存。服务端默认按类型填充正确状态（recently_memory='normal', task_list='pending'）。
+        // v1.13.0: recently_memory 过期判定、agent_memory 过期/回忆状态由服务端 memory_status 字段管理，
+        // 无需 TS 侧本地缓存。服务端默认按类型填充正确状态（recently_memory='normal', agent_memory='normal'）。
         return this.toMemoryWriteResult(created);
     }
     /**
@@ -779,27 +827,23 @@ export class McpServer {
         });
         await this.reportCombinedMemoryStats();
         // Dual-write permanent memory update to server（同步 MD5 map 避免服务端重复检测）
-        if (target.memory_type === "memory") {
+        if (target.memory_type === "project_memory") {
             try {
-                await this.memoryStore
-                    .updateMemory({
+                await this.memoryStore.updateMemory({
                     ...input,
-                    memory_type: "memory",
+                    memory_type: "project_memory",
                     file_md5_map: fileMd5Map,
                     last_check_time: lastCheckTime,
-                })
-                    .catch(() => { });
+                });
             }
             catch (e) {
                 logger.warn("[McpServer] Failed to sync permanent memory update to server:", e);
             }
         }
-        // v1.13.0: task_list TODO 状态、recently_memory 过期与回忆状态均由服务端 memory_status 字段管理。
-        // 显式传入的 todo_status / recall_status / memory_status 已在 updateMemory 内部透传到服务端。
-        // 服务端会自动处理"所有 TODO 已完成时清理全部已完成项"的逻辑（见 AgentMemoryService.updateMemory）。
-        // 内容变更对 recently_memory 的"续期"语义现在由过期判定基于 created_at 决定，
-        // update_memory 内容变更不会重置 created_at，因此"续期"实际对应"修改 created_at" — 当前不提供该能力，
-        // 如需续期建议使用 archive_recently_memory 归档或重新 createMemory 替代。
+        // v1.13.0: agent_memory 过期与回忆状态由服务端 memory_status 字段管理。
+        // 显式传入的 recall_status / memory_status 已在 updateMemory 内部透传到服务端。
+        // agent_memory 内容变更会触发 TTL ×2 续期（由 MemoryStore.updateMemory 内部处理），
+        // recently_memory 续期建议重新 createMemory 替代。
         return this.toMemoryWriteResult(updated);
     }
     /**
@@ -819,14 +863,12 @@ export class McpServer {
         });
         if (deleted) {
             await this.reportCombinedMemoryStats();
-            // v1.13.0: 服务端 deleteMemory 内部已处理"task_list 删除后清空 completed 残留"逻辑，
+            // v1.13.0: 服务端 deleteMemory 内部已处理相关清理逻辑，
             // TS 侧无需任何本地元数据清理。
             // Dual-write permanent memory delete to server
-            if (effectiveType === "memory") {
+            if (effectiveType === "project_memory") {
                 try {
-                    await this.memoryStore
-                        .deleteMemory({ uri: input.uri, memory_type: "memory" })
-                        .catch(() => { });
+                    await this.memoryStore.deleteMemory({ uri: input.uri, memory_type: "project_memory" });
                 }
                 catch (e) {
                     logger.warn("[McpServer] Failed to sync permanent memory delete to server:", e);
@@ -872,7 +914,7 @@ export class McpServer {
     }
     /**
      * 搜索自己工作区的所有记忆。
-     * 具体逻辑：按 memory_type 分流 -> 无类型时合并 roleMemoryStore(永久)与 memoryStore(task_list/recently)。
+     * 具体逻辑：按 memory_type 分流 -> 无类型时合并 roleMemoryStore(永久)与 memoryStore(recently/agent)。
      */
     async searchOwnMemories(input) {
         if (input.memory_type) {
@@ -886,7 +928,7 @@ export class McpServer {
             return await this.memoryStore.searchMemory(input);
         }
         const [roleResult, instanceResult] = await Promise.all([
-            this.roleMemoryStore.searchMemory({ ...input, memory_type: "memory" }),
+            this.roleMemoryStore.searchMemory({ ...input, memory_type: "project_memory" }),
             this.memoryStore.searchMemory(input),
         ]);
         const seen = new Set();
@@ -926,7 +968,7 @@ export class McpServer {
     }
     /**
      * 列出短期类型记忆。
-     * 主流程：只允许 task_list/recently_memory，由 MemoryStore 阻止长期 memory 的全量列出。
+     * 主流程：只允许 recently_memory/agent_memory/project_memory，由 MemoryStore 阻止 session_context 的全量列出。
      */
     async handleListMemories(args) {
         return await this.memoryStore.listByType(this.getRequiredString(args, "memory_type"));
@@ -952,58 +994,39 @@ export class McpServer {
             },
         };
     }
-    /**
-     * 归档近期记忆。
-     * 主流程：将 recently_memory 原地转换为长期 memory，并递增版本号。
-     */
-    async handleArchiveRecentlyMemory(args) {
-        const uri = this.getRequiredString(args, "uri");
-        if (this.memoryStoresShareFile) {
-            return await this.memoryStore.archiveRecentlyMemory(uri);
-        }
-        const record = await this.memoryStore.readMemory({
-            uri,
-            memory_type: "recently_memory",
-        });
-        if (!record) {
-            throw new Error(`Memory not found: ${uri}`);
-        }
-        const archived = await this.getMemoryStoreForType("memory").createMemory({
-            memory_type: "memory",
-            uri: record.uri,
-            title: record.title,
-            content: record.content,
-            keywords: record.keywords,
-            bound_files: record.bound_files,
-        });
-        await this.memoryStore.deleteMemory({
-            uri: record.uri,
-            memory_type: "recently_memory",
-        });
-        await this.reportCombinedMemoryStats();
-        return archived;
-    }
     /**
      * 按文件查询绑定了该文件的 Memory
      * Memory 增强功能 (v1.6.0)
      */
     /**
      * 按文件路径查询 Memory（支持 scope 跨 Agent 搜索）。
-     * 主流程：解析scope -> own(默认)仅自己 -> children通过server按path_prefix匹配子Agent -> all合并。
-     * 对于永久记忆(type=memory)同时查询本地roleMemoryStore作为补充。
+     * 主流程：解析scope -> own(默认)仅自己 -> children搜索子Agent -> all合并。
+     * 子 Agent 搜索同时走两条路径：
+     *   1. server searchChildByFilePath（查 DB）
+     *   2. 本地文件系统扫描 child .agentswork/memory/memory/（查本地永久记忆文件）
+     * 两条路径结果按 id 去重合并，确保无论子 Agent 的永久记忆是否已同步到
+     * 服务端数据库，父 Agent 都能搜索到。
      */
     async handleListMemoriesByFile(args) {
         const rawPath = this.getRequiredString(args, "file_path");
         const normalizedPath = this.normalizeBoundFilePath(rawPath);
         const memoryType = this.getOptionalMemoryType(args);
         const rawScope = this.getOptionalString(args, "scope");
-        const scope = rawScope === "children" || rawScope === "all" ? rawScope : "own";
-        // scope='children': 仅通过 server 搜索子 Agent（带 path_prefix 自动匹配）
+        // 默认 scope='all'：合并搜索自身与子Agent绑定文件的记忆
+        const scope = rawScope === "own" || rawScope === "children" ? rawScope : "all";
+        // 搜索子 Agent 的 memory（server + 本地文件系统双路径，并行）
+        const fetchChildMemories = async () => {
+            const [serverResult, localResult] = await Promise.all([
+                this.memoryStore.listByFile(normalizedPath, {
+                    memory_type: memoryType,
+                    scope: "children",
+                }).catch(() => []), // server 不可用时降级
+                this.searchChildMemoriesByFileLocal(normalizedPath, memoryType),
+            ]);
+            return this.mergeIdDedupe(serverResult, localResult);
+        };
         if (scope === "children") {
-            const childResult = await this.memoryStore.listByFile(normalizedPath, {
-                memory_type: memoryType,
-                scope: "children",
-            });
+            const childResult = await fetchChildMemories();
             return {
                 file_path: normalizedPath,
                 count: childResult.length,
@@ -1019,11 +1042,8 @@ export class McpServer {
                 memories: ownMemories.map(m => this.toMemoryRecordWithMetadata(m)),
             };
         }
-        // scope='all': 合并自己的 + 子 Agent 的
-        const childResult = await this.memoryStore.listByFile(normalizedPath, {
-            memory_type: memoryType,
-            scope: "children",
-        });
+        // scope='all': 合并自己的 + 子 Agent 的（server + 本地双路径已由 fetchChildMemories 聚合）
+        const childResult = await fetchChildMemories();
         const seen = new Set(ownMemories.map(m => m.id));
         const merged = [...ownMemories];
         for (const m of childResult) {
@@ -1039,6 +1059,135 @@ export class McpServer {
             memories: merged.map(m => this.toMemoryRecordWithMetadata(m)),
         };
     }
+    /**
+     * 按 id 去重合并两批 MemoryRecord，按 updatedAt 倒序排列。
+     * 首批（left）优先级高，其 id 会标记为 seen，重复的 right 项被丢弃。
+     */
+    mergeIdDedupe(left, right) {
+        const seen = new Set();
+        for (const m of left) {
+            if (m.id)
+                seen.add(m.id);
+        }
+        const merged = [...left];
+        for (const m of right) {
+            if (m.id && !seen.has(m.id)) {
+                merged.push(m);
+                seen.add(m.id);
+            }
+        }
+        merged.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return merged;
+    }
+    /**
+     * 通过文件系统扫描子 Agent 的 .agentswork 目录，
+     * 读取永久记忆 JSON 文件，按 path_prefix 匹配 bound_files。
+     *
+     * 主流程：
+     * 1. 解析 file_path（如 ./frontend/src/main.ts）的路径层级
+     * 2. 逐级（从长到短）找到子 Agent 的 .agentswork 目录
+     * 3. 读取该目录下所有 role 的 JSON 文件
+     * 4. 对每条记忆，将 bound_files 与 child-relative 路径比较
+     *
+     * 作为 server searchChildByFilePath 的本地补充，
+     * 确保子 Agent 的本地永久记忆（未同步到 server）也能被搜索到。
+     */
+    async searchChildMemoriesByFileLocal(filePath, memoryType) {
+        const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+        const normalizedFilePath = this.normalizeBoundFilePath(filePath);
+        // 解析路径 segments
+        // 例如 ./frontend/src/main.ts → relativePath = "frontend/src/main.ts"
+        //     segments = ["frontend", "src", "main.ts"]
+        const relativePath = normalizedFilePath.startsWith('./')
+            ? normalizedFilePath.substring(2)
+            : normalizedFilePath;
+        const segments = relativePath.split('/');
+        const results = [];
+        const seenById = new Set();
+        const { access, readdir, readFile } = await import('node:fs/promises');
+        // 从最长的路径前缀开始尝试（兼容嵌套子 Agent：深度=2 时 prefix=frontend/src）
+        for (let depth = segments.length - 1; depth >= 1; depth--) {
+            const prefixSegments = segments.slice(0, depth);
+            const childRelativeSegments = segments.slice(depth);
+            const childRelativePath = './' + childRelativeSegments.join('/');
+            // 子 Agent 的候选工作区路径
+            const childWorkspace = path.join(workspacePath, ...prefixSegments);
+            // 跳过父 Agent 自身（避免把 parent 当 child 扫）
+            if (childWorkspace === workspacePath)
+                continue;
+            const childAgentsworkDir = path.join(childWorkspace, '.agentswork');
+            // 检查 .agentswork 是否存在
+            try {
+                await access(childAgentsworkDir);
+            }
+            catch {
+                continue; // 这个前缀不是子 Agent 工作区
+            }
+            // 读取子 Agent 的永久记忆目录 .agentswork/memory/memory/<roleName>/
+            const memoryBaseDir = path.join(childAgentsworkDir, 'memory', 'memory');
+            let roleDirs;
+            try {
+                const entries = await readdir(memoryBaseDir, { withFileTypes: true });
+                roleDirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+            }
+            catch {
+                continue;
+            }
+            for (const roleDir of roleDirs) {
+                const rolePath = path.join(memoryBaseDir, roleDir);
+                let files;
+                try {
+                    files = await readdir(rolePath);
+                }
+                catch {
+                    continue;
+                }
+                for (const file of files) {
+                    if (!file.endsWith('.json'))
+                        continue;
+                    const jsonPath = path.join(rolePath, file);
+                    let content;
+                    try {
+                        content = await readFile(jsonPath, 'utf-8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(content);
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!parsed.by_uri)
+                        continue;
+                    // 遍历该 domain 的所有记忆，匹配 bound_files
+                    for (const [uri, record] of Object.entries(parsed.by_uri)) {
+                        if (!record)
+                            continue;
+                        const recordId = record.id || uri;
+                        if (seenById.has(recordId))
+                            continue;
+                        if (memoryType && record.memory_type !== memoryType)
+                            continue;
+                        if (record.bound_files && record.bound_files.length > 0) {
+                            const matched = record.bound_files.some(bf => this.normalizeBoundFilePath(bf) === childRelativePath);
+                            if (matched) {
+                                seenById.add(recordId);
+                                results.push({
+                                    ...record,
+                                    uri: record.uri || uri,
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return results;
+    }
     /**
      * 按文件路径搜索本 Agent 的记忆。
      * 同时查询临时记忆(server)和永久记忆(local roleMemoryStore)。
@@ -1049,8 +1198,8 @@ export class McpServer {
         });
         let localResult = [];
         // 补充查询本地永久记忆（server 可能未同步）；无角色名时跳过（避免 default-role 跨角色污染）
-        if (this.hasRoleName && (!memoryType || memoryType === "memory")) {
-            localResult = await this.roleMemoryStore.listByFile(filePath, "memory");
+        if (this.hasRoleName && (!memoryType || memoryType === "project_memory")) {
+            localResult = await this.roleMemoryStore.listByFile(filePath, "project_memory");
         }
         // 去重合并
         const seen = new Set(serverResult.map(m => `${m.memory_type}:${m.uri}`));
@@ -1086,17 +1235,19 @@ export class McpServer {
             message: "Memory 更新状态已清除",
         };
     }
-    // ============ Memory 近期记忆过期与回忆工具处理 (v1.11.0 / v1.13.0) ============
+    // ============ Memory 近期记忆过期与回忆工具处理 (v1.11.0 / v1.13.0 / v1.19.0) ============
     // v1.13.0: 过期判定与 recalling 状态标记已统一迁移到服务端 memory_status 字段，
     // 下方两个工具方法直接调用服务端接口，不再依赖任何本地元数据。
+    // v1.19.0: recently_memory 纳入过期回忆流程，与 agent_memory 行为完全一致。
     /**
      * 处理 memory_recurrence 工具调用。
-     * 主流程：调用服务端 list_expired_memories 拉取已过期 recently_memory ->
+     * 主流程：调用服务端 list_expired_memories 拉取已过期的 recently_memory / agent_memory ->
      * 按过期时间排序（最早优先）-> 取前 limit 条 ->
      * 仅标记这 limit 条为「回忆中」状态 -> 返回这些记忆及剩余数量。
      */
     async handleMemoryRecurrence(args) {
         // v1.13.0: 过期判定与 recalling 状态全部由服务端管理
+        // v1.19.0: recently_memory 同样纳入过期回忆流程
         const limit = Math.max(1, args?.limit ?? 10);
         const expiredMemories = await this.memoryStore.listExpiredRecentlyMemories();
         if (expiredMemories.length === 0) {
@@ -1145,10 +1296,10 @@ export class McpServer {
             totalExpired: expiredMemories.length,
             message: remaining > 0
                 ? `本次处理 ${batch.length} 条即将遗忘的记忆（最早过期优先），剩余 ${remaining} 条待处理。\n` +
-                    `请审查后决定（archive_recently_memory 归档 / update_memory 续期），\n` +
+                    `请审查后决定（update_memory 续期，TTL ×2 / 不处理），\n` +
                     `完成后调用 memory_recurrence_complete 清理，再调 memory_recurrence 处理下一批。`
                 : `已处理全部 ${batch.length} 条即将遗忘的记忆。\n` +
-                    `请审查后决定（archive_recently_memory 归档 / update_memory 续期），\n` +
+                    `请审查后决定（update_memory 续期，TTL ×2 / 不处理），\n` +
                     `完成后调用 memory_recurrence_complete 清理。`,
         };
     }
@@ -1175,104 +1326,6 @@ export class McpServer {
                 : `已清理 ${deletedCount} 条已过期近期记忆。`,
         };
     }
-    // ============ 短期记忆 TODO 完成工具处理 (v1.14.0) ============
-    /**
-     * 标记 task_list 短期记忆为已完成。
-     * 主流程：调用 memoryStore.todoCompleted(uri) -> 标记完成 -> 检查全部完成 -> 自动清理 -> 返回结果。
-     */
-    async handleTodoCompleted(args) {
-        const result = await this.memoryStore.todoCompleted(args.uri);
-        await this.reportCombinedMemoryStats();
-        const allCleanedMsg = result.allCleaned
-            ? `所有 TODO 均已完成，已自动清理 ${result.cleanedCount} 条已完成短期记忆。`
-            : "已标记为已完成。";
-        return {
-            ...result,
-            message: allCleanedMsg,
-        };
-    }
-    // ============ 上下文压缩工具处理 (v1.8.0) ============
-    /**
-     * 获取当前会话的上下文统计。
-     * 主流程：从 profile 获取模型名称 -> 通过模型名查找上下文窗口 -> 调用 ContextManager 获取统计 -> 返回。
-     */
-    async handleGetContextStats(args) {
-        const profile = await this.agentClient.getProfile().catch(() => null);
-        const sessionId = args.sessionId ?? profile?.runtimeSessionId ?? "default";
-        const modelName = profile?.prompt ? this.guessModelName(profile) : "unknown";
-        const modelInfo = {
-            provider: modelName.split("/")[0] || "unknown",
-            model: modelName,
-            contextLimit: 0, // ContextManager 内部会通过 lookupModelLimits 查找
-        };
-        const stats = await this.contextManager.getStats(sessionId, modelInfo);
-        // 如果 contextLimit 仍为 0，用查找表的默认值
-        if (stats.contextLimit === 0) {
-            const limits = this.contextManager.lookupModelLimits(modelName);
-            return { ...stats, contextLimit: limits.contextLimit, remaining: limits.contextLimit - stats.totalUsed, usagePercent: Math.round((stats.totalUsed / limits.contextLimit) * 100) };
-        }
-        return stats;
-    }
-    /**
-     * 从 profile 猜测当前使用的模型名称。
-     * 主流程：读取 prompt 中的模型信息 -> 回退到 runtimeCliCommand 中的提示 -> 最终回退到环境变量或默认值。
-     */
-    guessModelName(profile) {
-        // 尝试从 prompt 中提取模型名（prompt 可能包含 @model 标记）
-        const promptMatch = profile.prompt?.match(/@model\s+(\S+)/i);
-        if (promptMatch?.[1])
-            return promptMatch[1];
-        // 回退到 CLI 命令中的线索
-        if (profile.runtimeMode)
-            return profile.runtimeMode;
-        // 默认值
-        return process.env.AWS_DEFAULT_MODEL || "gpt-4o";
-    }
-    /**
-     * 处理上下文压缩请求。
-     * 主流程：解析策略 -> 获取消息历史 -> 执行压缩 -> 保存结果 -> 返回。
-     */
-    async handleCompactContext(args) {
-        const profile = await this.agentClient.getProfile().catch(() => null);
-        const sessionId = profile?.runtimeSessionId ?? "default";
-        const strategy = args.strategy ?? "auto";
-        const keepLastTurns = args.keepLastTurns ?? 3;
-        // 获取消息历史
-        const messages = await this.fetchRecentMessages();
-        switch (strategy) {
-            case "prune": {
-                const result = this.contextManager.prune(messages, keepLastTurns);
-                await this.contextManager.saveCompactionResult(sessionId, result);
-                return result;
-            }
-            case "summarize": {
-                // summarize 需要 Agent 自己调用 LLM 来完成
-                // 这里先执行 prune 释放部分空间，然后返回需要 Agent 进行 summarize
-                const pruneResult = this.contextManager.prune(messages, keepLastTurns);
-                await this.contextManager.saveCompactionResult(sessionId, pruneResult);
-                return {
-                    ...pruneResult,
-                    strategy: "summarize",
-                    summary: await this.contextManager.getCompactionSummary(sessionId) ?? undefined,
-                };
-            }
-            case "auto":
-            default: {
-                // 先尝试 prune
-                const pruneResult = this.contextManager.prune(messages, keepLastTurns);
-                if (pruneResult.freedTokens >= 20_000) {
-                    await this.contextManager.saveCompactionResult(sessionId, pruneResult);
-                    return pruneResult;
-                }
-                // prune 释放不够，回退到 summarize
-                return {
-                    ...pruneResult,
-                    strategy: "summarize",
-                    summary: await this.contextManager.getCompactionSummary(sessionId) ?? undefined,
-                };
-            }
-        }
-    }
     /**
      * 获取最近的消息历史用于压缩。
      * 主流程：获取未读消息 + 历史消息 -> 合并排序 -> 返回。
@@ -1382,46 +1435,44 @@ export class McpServer {
         return result;
     }
     async handlePollMessage() {
-        // 首次非阻塞预取：先拉一次已有消息填充缓冲区
+        if (this.pendingPollMessage) {
+            logger.info('[McpServer] poll_message 已有进行中的调用，等待其完成');
+            return await this.pendingPollMessage;
+        }
+        this.pendingPollMessage = (async () => {
+            // 入口处检查 Todo 未完成项提醒：仅在每次 poll_message 调用时检查一次，
+            // 不引入后台定时器。状态变化（指纹不同）且有未完成项时立即返回通知；
+            // 否则进入原有阻塞等待真实消息的流程。
+            const todoNotification = await this.buildTodoReminderNotification();
+            if (todoNotification) {
+                return this.buildPollResult({
+                    directMessages: [todoNotification],
+                    groupMessages: [],
+                });
+            }
+            return await this.doPollMessage();
+        })();
+        try {
+            return await this.pendingPollMessage;
+        }
+        finally {
+            this.pendingPollMessage = null;
+        }
+    }
+    async doPollMessage() {
         await this.hydrateUnreadMessagesFromServer({
             blockIfEmpty: false,
             includePipelineTasks: false,
         });
-        // poll_message 永不超时返回空：while(true) 内部每 30s 轮询一次
-        // WebSocket 消息（主动通知）→ 实时响应
-        // Memory 状态变化（无法主动通知）→ 最长 30s 延迟
         while (true) {
-            // 1. 检查 WebSocket 缓冲区（来自 push + 后台补拉）
             const buffered = this.messageBuffer.get();
             if (buffered.directMessages.length > 0 || buffered.groupMessages.length > 0) {
                 return await this.finalizeWithMemoryNotifications(buffered);
             }
-            // 2. 检查 Memory 通知（缓冲区无消息时直接返回）
-            if (!this.memoryFileCheckInterval) {
-                const fileChange = await this.buildMemoryFileChangeNotification();
-                if (fileChange) {
-                    return this.buildPollResult({ directMessages: [fileChange], groupMessages: [] });
-                }
-            }
-            const recurrence = await this.getCachedMemoryNotification('recurrence', () => this.buildMemoryRecurrenceNotification());
-            if (recurrence) {
-                return this.buildPollResult({ directMessages: [recurrence], groupMessages: [] });
-            }
-            const todo = await this.getCachedMemoryNotification('todo', () => this.buildMemoryTodoNotification());
-            if (todo) {
-                return this.buildPollResult({ directMessages: [todo], groupMessages: [] });
-            }
-            const cleanup = await this.getCachedMemoryNotification('cleanup', () => this.buildMemoryCleanupNotification());
-            if (cleanup) {
-                return this.buildPollResult({ directMessages: [cleanup], groupMessages: [] });
-            }
-            // 3. 带超时等 WebSocket 消息（内部轮询周期）
-            // poll() 一旦返回就已消费 buffer，不可 `continue` 回 get()（空）
             const polled = await this.messageBuffer.poll(POLL_MESSAGE_INTERNAL_POLL_INTERVAL_MS);
             if (polled.directMessages.length > 0 || polled.groupMessages.length > 0) {
                 return await this.finalizeWithMemoryNotifications(polled);
             }
-            // 超时 → 继续循环，重新检查 Memory 和缓冲区
         }
     }
     /**
@@ -1435,17 +1486,15 @@ export class McpServer {
         if (await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('recurrence', () => this.buildMemoryRecurrenceNotification()))) {
             return this.buildPollResult(messages);
         }
-        if (await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('todo', () => this.buildMemoryTodoNotification()))) {
-            return this.buildPollResult(messages);
-        }
         await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('cleanup', () => this.buildMemoryCleanupNotification()));
         return this.buildPollResult(messages);
     }
-    buildPollResult(messages) {
+    buildPollResult(messages, fromBuffer = true) {
         return {
             directMessages: messages.directMessages,
             groupMessages: messages.groupMessages,
-            fromBuffer: true,
+            fromBuffer,
+            systemMessages: [],
         };
     }
     /**
@@ -1495,8 +1544,8 @@ export class McpServer {
             const cleanupActions = [
                 "请调用 get_memory_stats 查看容量详情",
                 "调用 list_memories 按类型查看超限记忆",
-                "删除不再需要的 task_list",
-                "删除或 archive_recently_memory 归档 recently_memory 为长期 memory",
+                "删除不再需要的 recently_memory",
+                "更新 agent_memory 续期（TTL ×2）或删除过期项",
             ].join("；");
             return {
                 msgId: `memory-cleanup-${Date.now()}`,
@@ -1516,13 +1565,14 @@ export class McpServer {
     }
     /**
      * 构建近期记忆过期回忆通知（有即将遗忘的记忆需要整理）。
-     * Memory 近期记忆过期 (v1.11.0) / v1.13.0 改用服务端 memory_status 字段
+     * Memory 近期记忆过期 (v1.11.0) / v1.13.0 改用服务端 memory_status 字段 / v1.19.0 扩展
      *
      * 通知策略（基于服务端 memory_status）：
-     * 1. 有过期 recently_memory 且 memory_status='recalling'（回忆中但未完成疏理）：
+     * 1. 有过期 recently_memory / agent_memory 且 memory_status='recalling'（回忆中但未完成疏理）：
      *    通知 "存在待疏理的即将遗忘记忆，请通过 memory_recurrence 获取进行整理"
-     * 2. 有过期 recently_memory 且 memory_status='normal'（尚未开始回忆）：
+     * 2. 有过期 recently_memory / agent_memory 且 memory_status='normal'（尚未开始回忆）：
      *    通知 "有即将遗忘记忆得整理，请通过 memory_recurrence 进行回忆"
+     * v1.19.0: recently_memory 纳入过期回忆流程，与 agent_memory 一并处理。
      */
     async buildMemoryRecurrenceNotification() {
         try {
@@ -1590,7 +1640,7 @@ export class McpServer {
             }
             // 步骤1: 检查是否有 pending 的 updating memories（角色本地永久记忆），
             // 同时检测绑定文件是否再次变更（用户可能在 Agent 处理前又改了文件）
-            const permanentList = await this.roleMemoryStore.listByType('memory');
+            const permanentList = await this.roleMemoryStore.listByType('project_memory');
             const updatingMemories = permanentList.filter(m => m.update_status === 'updating' && m.updating_agent_id === agentId);
             if (updatingMemories.length > 0) {
                 // 对 updating 记忆也检测文件是否再次变更
@@ -1602,7 +1652,7 @@ export class McpServer {
                         if (memory) {
                             await this.roleMemoryStore.updateMemory({
                                 uri: memory.uri,
-                                memory_type: 'memory',
+                                memory_type: 'project_memory',
                                 update_status: 'updating',
                                 updating_agent_id: agentId,
                                 file_md5_map: memory.file_md5_map,
@@ -1642,9 +1692,9 @@ export class McpServer {
                 };
             }
             // 步骤2: 检查短期记忆和近期记忆（服务端存储）
-            const recentlyMemories = await this.memoryStore.listByType('recently_memory');
-            const taskListMemories = await this.memoryStore.listByType('task_list');
-            const listableMemories = [...recentlyMemories, ...taskListMemories];
+            const recentlyMemoryMemories = await this.memoryStore.listByType('recently_memory');
+            const agentMemoryMemories = await this.memoryStore.listByType('agent_memory');
+            const listableMemories = [...recentlyMemoryMemories, ...agentMemoryMemories];
             // 用本地 MD5 缓存补全 listable 记忆（服务端可能不持久化 file_md5_map 字段）
             // 确保 checkMemoriesFileChanges 有正确的旧 MD5 做比对而非始终以空字典开始
             for (const m of listableMemories) {
@@ -1703,7 +1753,7 @@ export class McpServer {
                     if (memory) {
                         await this.roleMemoryStore.updateMemory({
                             uri: memory.uri,
-                            memory_type: 'memory',
+                            memory_type: 'project_memory',
                             update_status: 'updating',
                             updating_agent_id: agentId,
                             // checkMemoriesFileChanges 已更新 in-memory 对象中的 MD5 map
@@ -1817,18 +1867,22 @@ export class McpServer {
         return `${memoryId}:${sorted.map(([k, v]) => `${k}=${v}`).join('|')}`;
     }
     async handleGetMessage() {
+        // 消息来源标记：
+        // - buffer 在 hydrate 前已有消息 → fromBuffer=true（来自本地 buffer）
+        // - buffer 空、hydrate 从服务端拉到消息 → fromBuffer=false（来自服务端）
+        // - buffer 空、hydrate 也无消息（仅有 Memory 通知注入）→ fromBuffer=true（本地注入）
+        const hadBufferedMessages = this.messageBuffer.size() > 0;
         await this.hydrateUnreadMessagesIfNeeded();
         const messages = this.messageBuffer.get();
+        const hasRealMessages = messages.directMessages.length > 0 || messages.groupMessages.length > 0;
+        const fromBuffer = hadBufferedMessages || !hasRealMessages;
         if (await this.prependMemoryNotification(messages, () => this.buildMemoryRecurrenceNotification())) {
-            return this.buildPollResult(messages);
-        }
-        if (await this.prependMemoryNotification(messages, () => this.buildMemoryTodoNotification())) {
-            return this.buildPollResult(messages);
+            return this.buildPollResult(messages, fromBuffer);
         }
         if (await this.prependMemoryNotification(messages, () => this.buildMemoryCleanupNotification())) {
-            return this.buildPollResult(messages);
+            return this.buildPollResult(messages, fromBuffer);
         }
-        return this.buildPollResult(messages);
+        return this.buildPollResult(messages, fromBuffer);
     }
     /**
      * 在本地缓冲区为空时，从服务端补拉离线期间积累的未读消息。
@@ -2009,6 +2063,87 @@ export class McpServer {
         }
         return maybeAgentClient.getState().agentId ?? null;
     }
+    /**
+     * 将 agentId 安全化为文件名片段：仅保留字母数字下划线短横，其余替换为下划线。
+     * 与 acode 包 TodoStore.filePath 的路径安全化逻辑保持一致。
+     */
+    sanitizeAgentIdForTodoFile(agentId) {
+        return String(agentId).replace(/[^a-zA-Z0-9_-]/g, "_");
+    }
+    /**
+     * 构建 Todo 未完成项提醒通知。
+     *
+     * 触发条件（同时满足）：
+     *   1. 当前 agentId 可读取
+     *   2. ~/.acode/todos/{agentId}.json 存在且可解析
+     *   3. 存在 status !== "completed" 的未完成项
+     *   4. 未完成项内容/状态/优先级指纹与上次通知时不同（去重）
+     *
+     * 行为：
+     *   - 指纹变化且有未完成项：构造系统通知并返回；指纹更新为本轮快照。
+     *   - 指纹未变：返回 null（不重复通知）。
+     *   - 全部完成：重置指纹为 null，下次有未完成项时能再次通知。
+     *   - 任何异常（文件不存在/JSON 损坏/agentId 缺失）：静默返回 null，不阻断 poll_message。
+     *
+     * 通知以 DirectMessage 形式注入，senderId="MCP-System"，不落库、不持久化。
+     */
+    async buildTodoReminderNotification() {
+        try {
+            const agentId = this.getCurrentAgentId();
+            if (!agentId)
+                return null;
+            const todoPath = path.join(os.homedir(), ".acode", "todos", `${this.sanitizeAgentIdForTodoFile(agentId)}.json`);
+            let raw;
+            try {
+                raw = await fs.promises.readFile(todoPath, "utf-8");
+            }
+            catch (error) {
+                // 文件不存在视为无 todo，不通知
+                if (error?.code === "ENOENT")
+                    return null;
+                throw error;
+            }
+            const doc = JSON.parse(raw);
+            const todos = Array.isArray(doc.todos)
+                ? doc.todos
+                : [];
+            const incomplete = todos.filter((t) => t &&
+                typeof t === "object" &&
+                typeof t.content === "string" &&
+                (t.status === "pending" ||
+                    t.status === "in_progress" ||
+                    t.status === "cancelled"));
+            if (incomplete.length === 0) {
+                // 全完成（或无未完成项）：重置指纹，下次有未完成项时能再次通知
+                this.lastTodoNotificationFingerprint = null;
+                return null;
+            }
+            const fingerprint = JSON.stringify(incomplete.map((t) => ({
+                c: t.content,
+                s: t.status,
+                p: t.priority,
+            })));
+            if (fingerprint === this.lastTodoNotificationFingerprint) {
+                // 指纹未变：不重复通知
+                return null;
+            }
+            this.lastTodoNotificationFingerprint = fingerprint;
+            return {
+                msgId: `todo-reminder-${Date.now()}`,
+                senderId: "MCP-System",
+                senderName: "系统",
+                receiverId: agentId,
+                content: `Todo 列表存在 ${incomplete.length} 项未完成，请调用 todo_read 查看并处理。`,
+                requireReply: false,
+                prompt: "这是一条 Todo 未完成项提醒，自动生成，无需持久化。请评估是否需要继续处理未完成的 Todo，可调用 todo_read 获取完整列表。",
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            logger.warn("[McpServer] 构建 Todo 提醒失败:", error);
+            return null;
+        }
+    }
     // ============ 生命周期 ============
     async start() {
         const transport = new StdioServerTransport();
@@ -2062,37 +2197,6 @@ export class McpServer {
         }, intervalMs);
         logger.info(`[McpServer] 后台文件变更检测已启动，间隔: ${intervalMs}ms（可通过 AWS_MEMORY_FILE_CHECK_INTERVAL_MS 环境变量调整，设为 0 禁用）`);
     }
-    /**
-     * 构建短期记忆 TODO 通知。
-     * 主流程：调用服务端 list_by_todo_status({ todo_status: 'pending' }) 获取 pending 待办 -> 注入提醒。
-     * v1.13.0: 由服务端 memory_status 字段管理 todo 状态，TS 侧不再维护本地缓存。
-     */
-    async buildMemoryTodoNotification() {
-        try {
-            const pendingTodos = await this.memoryStore.listByTodoStatus('pending');
-            if (pendingTodos.length === 0)
-                return null;
-            const agentId = this.getCurrentAgentId();
-            if (!agentId)
-                return null;
-            const pendingCount = pendingTodos.length;
-            const pendingList = pendingTodos.slice(0, 5).map(m => `- ${m.uri}`).join('\n');
-            return {
-                msgId: `memory-todo-${Date.now()}`,
-                senderId: "MCP-System",
-                senderName: "系统",
-                receiverId: agentId,
-                content: `当前有 ${pendingCount} 个 todo 项未完成，请获取短期记忆(todo 列表)，且已经完成请使用 todo_completed 标注为已完成状态。\n\n待办项：\n${pendingList}${pendingCount > 5 ? `\n  ...及其他 ${pendingCount - 5} 条` : ''}`,
-                requireReply: false,
-                prompt: "这是一条短期记忆 TODO 提醒，请调用 list_memories({ memory_type: 'task_list' }) 查看待办列表，完成后通过 todo_completed({ uri }) 标注为已完成状态。",
-                timestamp: new Date().toISOString(),
-            };
-        }
-        catch (error) {
-            logger.warn("[McpServer] 构建短期记忆 TODO 提醒失败:", error);
-            return null;
-        }
-    }
     /**
      * 停止后台 Memory 文件变更检测定时器。
      */
@@ -2104,10 +2208,10 @@ export class McpServer {
         }
     }
     // ============ 记忆统一状态字段 (v1.13.0) ============
-    // v1.13.0 改用服务端 memory_status 字段管理 task_list todo 状态与 recently_memory 过期/回忆状态，
-    // 下方 4 个工具直接调用服务端接口，本地不再维护元数据缓存。
-    // buildMemoryRecurrenceNotification / buildMemoryTodoNotification / handleMemoryRecurrence / handleMemoryRecurrenceComplete
-    // 已在文件其他位置实现（直接使用 this.memoryStore.listExpiredRecentlyMemories / listByTodoStatus / markExpiredMemoriesRecalling / clearRecallingExpiredMemories）。
+    // v1.13.0 改用服务端 memory_status 字段管理 agent_memory 过期/回忆状态，
+    // 下方工具直接调用服务端接口，本地不再维护元数据缓存。
+    // buildMemoryRecurrenceNotification / handleMemoryRecurrence / handleMemoryRecurrenceComplete
+    // 已在文件其他位置实现（直接使用 this.memoryStore.listExpiredRecentlyMemories / markExpiredMemoriesRecalling / clearRecallingExpiredMemories）。
     async autoRegister() {
         const agentConfig = this.agentClient.getAgentConfig();
         logger.info(`[McpServer] 角色: "${agentConfig.roleName}"`);
@@ -2128,11 +2232,10 @@ export class McpServer {
                     statusReporter.reportWaitingInput();
                 }
                 await this.reportCombinedMemoryStats();
-                // 如果是新创建的角色，将本地永久记忆同步到服务端
-                if (result.isExisting === false) {
-                    logger.info("[McpServer] 新角色创建，同步本地永久记忆到服务端...");
-                    await this.syncLocalPermanentMemoryToServer();
-                }
+                // 注册成功后检查是否需要从本地恢复永久记忆到 server
+                // 触发条件：server 当前角色 memory 计数为 0（重部署后 DB 为空）
+                // 不依赖 isExisting / profileHandler，确保所有场景都能触发
+                this.maybeSyncPermanentMemoryToServer();
                 return;
             }
             catch (error) {
@@ -2189,6 +2292,7 @@ export class McpServer {
                     logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
                     this.messageBuffer.setProfileMessage(profile);
                     this.syncRoleMemoryStore(profile);
+                    this.maybeSyncPermanentMemoryToServer();
                 },
             });
             return;
@@ -2200,6 +2304,7 @@ export class McpServer {
                 logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
                 this.messageBuffer.setProfileMessage(profile);
                 this.syncRoleMemoryStore(profile);
+                this.maybeSyncPermanentMemoryToServer();
             },
         });
     }