aws-runtime-bridge 1.9.21 → 1.9.30

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

@@ -30,6 +30,13 @@ const DEFAULT_POLL_MESSAGE_BLOCK_WAIT_MS = 240_000;
 const POLL_MESSAGE_LONGPOLL_HTTP_TIMEOUT_MS = 600_000;
 const DEFAULT_MCP_HTTP_REQUEST_TIMEOUT_MS = 120_000;
 const POLL_MESSAGE_HTTP_TIMEOUT_BUFFER_MS = 1_000;
+/**
+ * poll_message 内部轮询间隔：每 30 秒在永久阻塞的 poll_message 中醒来一次，
+ * 检查 WebSocket 缓冲区、Memory 通知（文件变更/TODO/容量等）。
+ * 能主动通知的消息（WebSocket）实时响应，无法主动通知的状态变化最长 30s 延迟。
+ * poll_message 永不超时返回空，只在有消息可返回时才退出。
+ */
+const POLL_MESSAGE_INTERNAL_POLL_INTERVAL_MS = 30_000;
 const DEFAULT_MEMORY_FILE_CHECK_INTERVAL_MS = 5_000;
 const PATH_UNSAFE_CHARACTERS = new Set([
     "<",
@@ -51,6 +58,8 @@ export class McpServer {
     sessionContextMemoryStore;
     memoryStoresShareFile;
     initialRoleName = "";
+    /** 是否有真实的角色名（非 env 空值 fallback "default-role"） */
+    hasRoleName = false;
     /** 上下文管理器 (v1.8.0) */
     contextManager;
     /**
@@ -68,6 +77,16 @@ export class McpServer {
     listableMd5Cache = new Map();
     /** 后台 Memory 文件变更检测定时器 (v1.9.0) */
     memoryFileCheckInterval = null;
+    /**
+     * Memory 通知 null 结果缓存：key → expiresAt 时间戳。
+     * 仅缓存 null（无通知）结果，避免 while(true) 每 30s 重复读盘。
+     * 有通知时立即投递并清除缓存，不缓存非 null 结果。
+     */
+    memoryNotificationNullCache = new Map();
+    static MEMORY_NOTIFICATION_NULL_TTL_MS = 60_000;
+    // 系统提示词由 runtime adapter（ACode/OpenCode/Codex/Claude）在会话创建时注入，
+    // 无需通过 MCP 工具返回。三方 runtime（OpenCode/Claude）将三层提示词合并为一条 system prompt，
+    // ACode 则直接注入为前三条 system role 消息。
     /**
      * 收到 Profile 后同步角色存储路径。
      * 当服务端返回的 roleName 与进程初始化时不一致时，重建 roleMemoryStore 指向正确的目录。
@@ -77,6 +96,7 @@ export class McpServer {
             return;
         }
         const expectedRoleDir = McpServer.sanitizeRoleDirectoryName(profile.roleName);
+        this.hasRoleName = true; // Profile 确认了角色名
         if (expectedRoleDir === this.initialRoleName) {
             return;
         }
@@ -182,6 +202,7 @@ export class McpServer {
         this.agentClient = new AgentClient();
         this.messageBuffer = new MessageBuffer();
         this.initialRoleName = McpServer.resolveRoleMemoryDirectoryName();
+        this.hasRoleName = !!process.env.AWS_ROLE_NAME; // 只有明确设置了 env 才认为有角色名
         const memoryStorePaths = McpServer.resolveMemoryStorePaths();
         this.memoryStore = new ServerMemoryStore(this.agentClient);
         this.roleMemoryStore = new MemoryStore(memoryStorePaths.rolePath);
@@ -322,8 +343,6 @@ export class McpServer {
                 return await this.handleListMemories(args);
             case "get_memory_stats":
                 return await this.handleGetMemoryStats(args);
-            case "remove_task_list_memory":
-                return await this.handleRemoveTaskListMemory(args);
             case "archive_recently_memory":
                 return await this.handleArchiveRecentlyMemory(args);
             // Memory 增强功能工具 (v1.6.0)
@@ -331,6 +350,11 @@ export class McpServer {
                 return await this.handleListMemoriesByFile(args);
             case "abandon_memory_update":
                 return await this.handleAbandonMemoryUpdate(args);
+            // Memory 近期记忆过期与回忆工具 (v1.11.0)
+            case "memory_recurrence":
+                return await this.handleMemoryRecurrence();
+            case "memory_recurrence_complete":
+                return await this.handleMemoryRecurrenceComplete();
             // 上下文压缩工具 (v1.8.0)
             case "get_context_stats":
                 return await this.handleGetContextStats(args);
@@ -355,11 +379,13 @@ export class McpServer {
         "search_memory",
         "list_memories",
         "get_memory_stats",
-        "remove_task_list_memory",
         "archive_recently_memory",
         // Memory 增强功能工具 (v1.6.0)
         "list_memories_by_file",
         "abandon_memory_update",
+        // Memory 近期记忆过期与回忆工具 (v1.11.0)
+        "memory_recurrence",
+        "memory_recurrence_complete",
     ]);
     /**
      * 从 startPath 向上逐级查找 .agentswork 目录。
@@ -468,8 +494,17 @@ export class McpServer {
      * 按记忆生命周期选择存储作用域。
      * 主流程：长期 memory 走角色级 store；task_list/recently_memory 走当前 Agent 实例级 store。
      */
+    /**
+     * 按记忆生命周期选择存储作用域。
+     * 主流程：永久记忆(memory)仅在 hasRoleName 为 true 时走角色级 store，
+     *         否则回退到实例级 server store（避免空角色名下所有实例共享 default-role 目录导致跨角色污染）。
+     * task_list/recently_memory/session_context 始终走实例级 store。
+     */
     getMemoryStoreForType(memoryType) {
-        return memoryType === "memory" ? this.roleMemoryStore : this.memoryStore;
+        if (memoryType === "memory" && this.hasRoleName) {
+            return this.roleMemoryStore;
+        }
+        return this.memoryStore;
     }
     /**
      * 在未显式指定类型时按两个作用域读取。
@@ -482,12 +517,15 @@ export class McpServer {
         if (input.memory_type) {
             return await this.getMemoryStoreForType(input.memory_type).readMemory(input);
         }
-        const longTermRecord = await this.roleMemoryStore.readMemory({
-            ...input,
-            memory_type: "memory",
-        });
-        if (longTermRecord) {
-            return longTermRecord;
+        // hasRoleName 为 false 时不查 roleMemoryStore，避免空角色名共享 default-role 目录
+        if (this.hasRoleName) {
+            const longTermRecord = await this.roleMemoryStore.readMemory({
+                ...input,
+                memory_type: "memory",
+            });
+            if (longTermRecord) {
+                return longTermRecord;
+            }
         }
         return await this.memoryStore.readMemory(input);
     }
@@ -505,12 +543,14 @@ export class McpServer {
                 memory_type: input.memory_type,
             };
         }
-        const longTermRecord = await this.roleMemoryStore.readMemory({
-            uri: input.uri,
-            memory_type: "memory",
-        });
-        if (longTermRecord) {
-            return { store: this.roleMemoryStore, memory_type: "memory" };
+        if (this.hasRoleName) {
+            const longTermRecord = await this.roleMemoryStore.readMemory({
+                uri: input.uri,
+                memory_type: "memory",
+            });
+            if (longTermRecord) {
+                return { store: this.roleMemoryStore, memory_type: "memory" };
+            }
         }
         return { store: this.memoryStore };
     }
@@ -522,15 +562,23 @@ export class McpServer {
         if (this.memoryStoresShareFile) {
             return instanceStats;
         }
+        // 服务端 now 也按角色级返回永久记忆统计（同角色实例共享），
+        // 本地 roleMemoryStore 也可能有尚未同步到服务端的记录。
+        // 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;
         return {
-            total: instanceStats.total + roleStats.by_type.memory.count,
+            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,
-                    count: roleStats.by_type.memory.count,
+                    count: permanentCount,
                 },
                 session_context: instanceStats.by_type.session_context,
             },
@@ -541,12 +589,12 @@ export class McpServer {
      * 主流程：读取实例级与角色级统计 -> 合并长期 memory count -> 通过 server 广播给 Dashboard。
      */
     async reportCombinedMemoryStats() {
-        const [instanceStats, roleStats] = await Promise.all([
-            this.memoryStore.getStats(),
-            this.roleMemoryStore.getStats(),
-        ]);
+        const instanceStats = await this.memoryStore.getStats();
+        const mergedStats = this.hasRoleName
+            ? this.combineMemoryStats(instanceStats, await this.roleMemoryStore.getStats())
+            : instanceStats;
         try {
-            await this.agentClient.reportMemoryStats(this.combineMemoryStats(instanceStats, roleStats));
+            await this.agentClient.reportMemoryStats(mergedStats);
         }
         catch (error) {
             logger.warn("[McpServer] 上报合并 memory 统计失败，已保留本地记忆写入结果:", error);
@@ -557,6 +605,8 @@ export class McpServer {
      * 主流程：读取本地 roleMemoryStore 中所有 memory 类型记录 -> 逐条写入服务端 memoryStore -> 已存在的记录静默跳过。
      */
     async syncLocalPermanentMemoryToServer() {
+        if (!this.hasRoleName)
+            return;
         try {
             const memories = await this.roleMemoryStore.listByType("memory");
             if (memories.length === 0)
@@ -588,6 +638,14 @@ export class McpServer {
             logger.error("[McpServer] Failed to sync permanent memories to server:", error);
         }
     }
+    /**
+     * 系统提示词由 runtime adapter 在会话创建时注入，MCP 层面不再负责返回。
+     * 详见 startListeningInternal -> profileHandler 中的合并注入逻辑。
+     *
+     * @deprecated 启动记忆不再通过 MCP 的 systemMessages 返回。
+     *   三方 runtime（OpenCode/Claude）在 adapter 层将三层提示词合并为一条 system prompt；
+     *   ACode 则直接注入为前三条 system role 消息。
+     */
     /**
      * 生成安全的工具状态上报参数。
      * 主流程：memory 工具只上报元数据，避免 content/query/old_string/new_string/append 离开本地记忆边界。
@@ -657,6 +715,8 @@ export class McpServer {
                 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'）。
         return this.toMemoryWriteResult(created);
     }
     /**
@@ -743,6 +803,12 @@ export class McpServer {
                 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 替代。
         return this.toMemoryWriteResult(updated);
     }
     /**
@@ -755,14 +821,17 @@ export class McpServer {
             memory_type: this.getOptionalMemoryType(args),
         };
         const target = await this.findMemoryStoreForMutation(input);
+        const effectiveType = target.memory_type ?? input.memory_type;
         const deleted = await target.store.deleteMemory({
             ...input,
-            memory_type: target.memory_type ?? input.memory_type,
+            memory_type: effectiveType,
         });
         if (deleted) {
             await this.reportCombinedMemoryStats();
+            // v1.13.0: 服务端 deleteMemory 内部已处理"task_list 删除后清空 completed 残留"逻辑，
+            // TS 侧无需任何本地元数据清理。
             // Dual-write permanent memory delete to server
-            if (target.memory_type === "memory") {
+            if (effectiveType === "memory") {
                 try {
                     await this.memoryStore
                         .deleteMemory({ uri: input.uri, memory_type: "memory" })
@@ -821,6 +890,10 @@ export class McpServer {
         if (this.memoryStoresShareFile) {
             return await this.memoryStore.searchMemory(input);
         }
+        // 无角色名时不查询 roleMemoryStore（避免 default-role 共享目录导致跨角色污染）
+        if (!this.hasRoleName) {
+            return await this.memoryStore.searchMemory(input);
+        }
         const [roleResult, instanceResult] = await Promise.all([
             this.roleMemoryStore.searchMemory({ ...input, memory_type: "memory" }),
             this.memoryStore.searchMemory(input),
@@ -872,11 +945,10 @@ export class McpServer {
      * 主流程：读取 MemoryStore 统计结果，供 Agent 在创建前判断 listable/type 容量。
      */
     async handleGetMemoryStats(args) {
-        const [instanceStats, roleStats] = await Promise.all([
-            this.memoryStore.getStats(),
-            this.roleMemoryStore.getStats(),
-        ]);
-        const stats = this.combineMemoryStats(instanceStats, roleStats);
+        const instanceStats = await this.memoryStore.getStats();
+        const stats = this.hasRoleName
+            ? this.combineMemoryStats(instanceStats, await this.roleMemoryStore.getStats())
+            : instanceStats;
         const memoryType = this.getOptionalMemoryType(args);
         if (!memoryType) {
             return stats;
@@ -889,14 +961,6 @@ export class McpServer {
             },
         };
     }
-    /**
-     * 移除任务清单记忆。
-     * 主流程：按 uri 读取并校验 task_list 类型后删除，避免误删长期记忆。
-     */
-    async handleRemoveTaskListMemory(args) {
-        const removed = await this.memoryStore.removeTaskListMemory(this.getRequiredString(args, "uri"));
-        return { removed };
-    }
     /**
      * 归档近期记忆。
      * 主流程：将 recently_memory 原地转换为长期 memory，并递增版本号。
@@ -913,7 +977,7 @@ export class McpServer {
         if (!record) {
             throw new Error(`Memory not found: ${uri}`);
         }
-        const archived = await this.roleMemoryStore.createMemory({
+        const archived = await this.getMemoryStoreForType("memory").createMemory({
             memory_type: "memory",
             uri: record.uri,
             title: record.title,
@@ -993,8 +1057,8 @@ export class McpServer {
             memory_type: memoryType,
         });
         let localResult = [];
-        // 补充查询本地永久记忆（server 可能未同步）
-        if (!memoryType || memoryType === "memory") {
+        // 补充查询本地永久记忆（server 可能未同步）；无角色名时跳过（避免 default-role 跨角色污染）
+        if (this.hasRoleName && (!memoryType || memoryType === "memory")) {
             localResult = await this.roleMemoryStore.listByFile(filePath, "memory");
         }
         // 去重合并
@@ -1031,6 +1095,74 @@ export class McpServer {
             message: "Memory 更新状态已清除",
         };
     }
+    // ============ Memory 近期记忆过期与回忆工具处理 (v1.11.0 / v1.13.0) ============
+    // v1.13.0: 过期判定与 recalling 状态标记已统一迁移到服务端 memory_status 字段，
+    // 下方两个工具方法直接调用服务端接口，不再依赖任何本地元数据。
+    /**
+     * 处理 memory_recurrence 工具调用。
+     * 主流程：调用服务端 list_expired_memories 拉取已过期 recently_memory ->
+     * 批量调用 mark_expired_memories_recalling 把这些记录标记为「回忆中」状态 -> 返回过期记忆列表。
+     */
+    async handleMemoryRecurrence() {
+        // v1.13.0: 过期判定与 recalling 状态全部由服务端管理
+        const expiredMemories = await this.memoryStore.listExpiredRecentlyMemories();
+        if (expiredMemories.length === 0) {
+            return {
+                memories: [],
+                count: 0,
+                message: "没有待回忆的即将遗忘记忆。",
+            };
+        }
+        // 标记所有过期记忆为 recalling 状态（服务端）
+        try {
+            await this.memoryStore.markExpiredMemoriesRecalling();
+        }
+        catch (e) {
+            logger.warn("[McpServer] 标记过期记忆为 recalling 失败:", e);
+        }
+        // 返回过期记忆的摘要（不含完整 content 以减少上下文占用）
+        const memorySummaries = expiredMemories.map(m => ({
+            uri: m.uri,
+            title: m.title,
+            domain: m.domain,
+            path: m.path,
+            recall_status: 'recalling',
+            memory_status: 'recalling',
+            contentPreview: m.content && m.content.length > 200 ? m.content.substring(0, 200) + '...' : m.content,
+            createdAt: m.createdAt,
+            updatedAt: m.updatedAt,
+        }));
+        return {
+            memories: memorySummaries,
+            count: expiredMemories.length,
+            message: `发现 ${expiredMemories.length} 条即将遗忘的近期记忆。请审查后决定：\n` +
+                `1) 使用 archive_recently_memory 归档为长期记忆\n` +
+                `2) 完成审查后调用 memory_recurrence_complete 进行清理`,
+        };
+    }
+    /**
+     * 处理 memory_recurrence_complete 工具调用。
+     * 主流程：调用服务端 clear_recalling_expired_memories 删除所有「recalling + 已过期」记录。
+     */
+    async handleMemoryRecurrenceComplete() {
+        // v1.13.0: 删除操作由服务端完成
+        let result = { deleted: 0, uris: [] };
+        try {
+            result = await this.memoryStore.clearRecallingExpiredMemories();
+        }
+        catch (e) {
+            logger.warn("[McpServer] 清理回忆中记忆失败:", e);
+        }
+        await this.reportCombinedMemoryStats();
+        const deletedCount = result.deleted ?? 0;
+        return {
+            deleted: deletedCount,
+            uris: result.uris ?? [],
+            message: deletedCount === 0
+                ? "没有待疏理的回忆中记忆。"
+                : `已清理 ${deletedCount} 条已过期近期记忆。`,
+        };
+    }
     // ============ 上下文压缩工具处理 (v1.8.0) ============
     /**
      * 获取当前会话的上下文统计。
@@ -1189,78 +1321,118 @@ export class McpServer {
             content,
         });
     }
+    /**
+     * 构建内存通知并前置到消息列表。
+     * @returns 若生成了通知并已前置，返回 true；否则返回 false。
+     */
+    async prependMemoryNotification(messages, buildFn) {
+        const notification = await buildFn();
+        if (notification) {
+            messages.directMessages.unshift(notification);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 带 null 结果缓存的 Memory 通知构建。
+     * 主流程：查缓存 → 命中且未过期则返回 null → 未命中则调 buildFn →
+     *   结果为 null 则写入缓存（TTL 60s）→ 结果非 null 则清除缓存并返回。
+     * 目的：while(true) 每 30s 轮询时避免重复读盘，有通知时立即投递不受缓存影响。
+     */
+    async getCachedMemoryNotification(key, buildFn) {
+        const expiresAt = this.memoryNotificationNullCache.get(key);
+        if (expiresAt !== undefined && expiresAt > Date.now()) {
+            return null;
+        }
+        const result = await buildFn();
+        if (result === null) {
+            this.memoryNotificationNullCache.set(key, Date.now() + McpServer.MEMORY_NOTIFICATION_NULL_TTL_MS);
+        }
+        else {
+            this.memoryNotificationNullCache.delete(key);
+        }
+        return result;
+    }
     async handlePollMessage() {
-        // 首次非阻塞预取：使用 get_dm_messages 而非 poll_message，
-        // 避免进入服务端 MVC 异步线程池排队（poll_message 始终走异步池），
-        // 确保快速返回，不影响后续 waitForMessagesWithPoll 的 resolver 注册。
-        // 流程线任务由后续的 waitForMessagesWithPoll → 后台长轮询负责补拉。
+        // 首次非阻塞预取：先拉一次已有消息填充缓冲区
         await this.hydrateUnreadMessagesFromServer({
             blockIfEmpty: false,
             includePipelineTasks: false,
         });
-        // Memory 文件变更检测通知（优先级最高）
-        // 后台定时器启用时由定时器负责推送，poll_message 不再重复检查
-        if (!this.memoryFileCheckInterval) {
-            const fileChangeNotification = await this.buildMemoryFileChangeNotification();
-            if (fileChangeNotification) {
-                const messages = this.messageBuffer.get();
-                messages.directMessages.unshift(fileChangeNotification);
-                return {
-                    directMessages: messages.directMessages,
-                    groupMessages: messages.groupMessages,
-                    fromBuffer: true,
-                };
+        let backendPollStarted = 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. 首次循环：触发后台 HTTP 长轮询（仅一次，后续循环复用）
+            if (!backendPollStarted) {
+                backendPollStarted = true;
+                const blockTimeoutMs = this.resolvePollMessageBlockWaitMs();
+                this.hydrateUnreadMessagesIfNeeded({
+                    blockIfEmpty: true,
+                    blockTimeoutMs,
+                    includePipelineTasks: true,
+                }).catch((error) => {
+                    logger.warn("[McpServer] 后台 HTTP 长轮询补拉失败:", error);
+                });
+            }
+            // 4. 带超时等 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 和缓冲区
         }
-        const immediateMemoryNotification = await this.buildMemoryCleanupNotification();
-        if (immediateMemoryNotification) {
-            const messages = this.messageBuffer.get();
-            messages.directMessages.unshift(immediateMemoryNotification);
-            return {
-                directMessages: messages.directMessages,
-                groupMessages: messages.groupMessages,
-                fromBuffer: true,
-            };
-        }
-        const messages = await this.waitForMessagesWithPoll();
-        // 后台定时器启用时跳过，避免与定时器推送重复
+    }
+    /**
+     * 后检 Memory 通知并注入到待返回的消息中。按优先级从高到低注入：
+     * 文件变更（始终注入）→ 近期记忆过期回忆（触发即返回）→ TODO（触发即返回）→ 容量整理（始终注入）
+     */
+    async finalizeWithMemoryNotifications(messages) {
         if (!this.memoryFileCheckInterval) {
-            const fileChangeNotification2 = await this.buildMemoryFileChangeNotification();
-            if (fileChangeNotification2) {
-                messages.directMessages.unshift(fileChangeNotification2);
-            }
+            await this.prependMemoryNotification(messages, () => this.buildMemoryFileChangeNotification());
+        }
+        if (await this.prependMemoryNotification(messages, () => this.getCachedMemoryNotification('recurrence', () => this.buildMemoryRecurrenceNotification()))) {
+            return this.buildPollResult(messages);
         }
-        const memoryNotification = await this.buildMemoryCleanupNotification();
-        if (memoryNotification) {
-            messages.directMessages.unshift(memoryNotification);
+        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) {
         return {
             directMessages: messages.directMessages,
             groupMessages: messages.groupMessages,
             fromBuffer: true,
         };
     }
-    async waitForMessagesWithPoll() {
-        // 如果缓冲区已有消息（来自上层的非阻塞补拉），立即返回
-        const buffered = this.messageBuffer.get();
-        if (buffered.directMessages.length > 0 || buffered.groupMessages.length > 0) {
-            return buffered;
-        }
-        // 后台长轮询补拉：作为 WebSocket 之外的第二消息通道，不阻塞 poll 的 resolver 注册
-        // 长轮询返回的消息会入 buffer → tryDispatch()，若 poll 已注册 resolver 则被立即唤醒
-        const blockTimeoutMs = this.resolvePollMessageBlockWaitMs();
-        this.hydrateUnreadMessagesIfNeeded({
-            blockIfEmpty: true,
-            blockTimeoutMs,
-            includePipelineTasks: true,
-        }).catch((error) => {
-            logger.warn("[McpServer] 后台 HTTP 长轮询补拉失败:", error);
-        });
-        // 永久阻塞等待 WebSocket 推送的消息
-        // WebSocket 消息到达时，push() → tryDispatch() 会解析此 Promise
-        // 不传递超时参数，确保不会因超时返回空消息而重试
-        return await this.messageBuffer.poll();
-    }
     resolvePollMessageBlockWaitMs() {
         const blockWaitMs = this.parsePositiveIntegerEnv("AWS_POLL_MESSAGE_BLOCK_WAIT_MS", DEFAULT_POLL_MESSAGE_BLOCK_WAIT_MS);
         // poll_message 走 callToolOnce 专用通道，HTTP 超时使用 POLL_MESSAGE_LONGPOLL_HTTP_TIMEOUT_MS
@@ -1339,6 +1511,62 @@ export class McpServer {
             return null;
         }
     }
+    /**
+     * 构建近期记忆过期回忆通知（有即将遗忘的记忆需要整理）。
+     * Memory 近期记忆过期 (v1.11.0) / v1.13.0 改用服务端 memory_status 字段
+     *
+     * 通知策略（基于服务端 memory_status）：
+     * 1. 有过期 recently_memory 且 memory_status='recalling'（回忆中但未完成疏理）：
+     *    通知 "存在待疏理的即将遗忘记忆，请通过 memory_recurrence 获取进行整理"
+     * 2. 有过期 recently_memory 且 memory_status='normal'（尚未开始回忆）：
+     *    通知 "有即将遗忘记忆得整理，请通过 memory_recurrence 进行回忆"
+     */
+    async buildMemoryRecurrenceNotification() {
+        try {
+            // v1.13.0: 改为调用服务端 list_expired_memories，返回的记录带 memory_status
+            const expiredMemories = await this.memoryStore.listExpiredRecentlyMemories();
+            if (expiredMemories.length === 0)
+                return null;
+            const agentId = this.getCurrentAgentId();
+            if (!agentId)
+                return null;
+            const recallingExpired = expiredMemories.filter(m => m.recall_status === 'recalling' || m.memory_status === 'recalling');
+            const normalExpired = expiredMemories.filter(m => !recallingExpired.includes(m));
+            // 场景1: 有 recalling 状态的过期记忆（Agent 未完成疏理）
+            if (recallingExpired.length > 0) {
+                const memoryList = recallingExpired.slice(0, 5).map(m => m.uri).join('\n');
+                return {
+                    msgId: `memory-recurrence-pending-${Date.now()}`,
+                    senderId: "MCP-System",
+                    senderName: "系统",
+                    receiverId: agentId,
+                    content: `存在待疏理的即将遗忘记忆，请通过 memory_recurrence 获取进行整理。\n\n待疏理记忆：\n${memoryList}${recallingExpired.length > 5 ? `\n  ...及其他 ${recallingExpired.length - 5} 条` : ''}`,
+                    requireReply: false,
+                    prompt: "memory_recurrence 取回的记忆仍在回忆中，请通过 memory_recurrence_complete 完成疏理，或继续归档/续期。",
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            // 场景2: 有待回忆的过期记忆
+            if (normalExpired.length > 0) {
+                const memoryList = normalExpired.slice(0, 5).map(m => m.uri).join('\n');
+                return {
+                    msgId: `memory-recurrence-${Date.now()}`,
+                    senderId: "MCP-System",
+                    senderName: "系统",
+                    receiverId: agentId,
+                    content: `有即将遗忘记忆得整理，请通过 memory_recurrence 进行回忆，若有必要存留请通过创建永久记忆/归档/更新近期记忆时间的方式保留在近期记忆里的时长。\n\n即将遗忘的记忆：\n${memoryList}${normalExpired.length > 5 ? `\n  ...及其他 ${normalExpired.length - 5} 条` : ''}`,
+                    requireReply: false,
+                    prompt: "这是一条近期记忆过期提醒，请调用 memory_recurrence 获取即将遗忘的记忆并决定处理方式。",
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            return null;
+        }
+        catch (error) {
+            logger.warn("[McpServer] 构建近期记忆过期回忆通知失败:", error);
+            return null;
+        }
+    }
     /**
      * 构建 Memory 文件变更检测通知。
      * Memory 增强功能 (v1.6.0)
@@ -1349,6 +1577,9 @@ export class McpServer {
      * 3. 如果没有变更，检查永久记忆的文件变更，标记最多 5 个为 updating
      */
     async buildMemoryFileChangeNotification() {
+        // 无角色名时不检测本地永久记忆文件变更（避免 default-role 跨角色污染）
+        if (!this.hasRoleName)
+            return null;
         try {
             const agentId = this.getCurrentAgentId();
             if (!agentId) {
@@ -1585,15 +1816,16 @@ export class McpServer {
     async handleGetMessage() {
         await this.hydrateUnreadMessagesIfNeeded();
         const messages = this.messageBuffer.get();
-        const memoryNotification = await this.buildMemoryCleanupNotification();
-        if (memoryNotification) {
-            messages.directMessages.unshift(memoryNotification);
+        if (await this.prependMemoryNotification(messages, () => this.buildMemoryRecurrenceNotification())) {
+            return this.buildPollResult(messages);
         }
-        return {
-            directMessages: messages.directMessages,
-            groupMessages: messages.groupMessages,
-            fromBuffer: this.messageBuffer.size() > 0 || !!memoryNotification,
-        };
+        if (await this.prependMemoryNotification(messages, () => this.buildMemoryTodoNotification())) {
+            return this.buildPollResult(messages);
+        }
+        if (await this.prependMemoryNotification(messages, () => this.buildMemoryCleanupNotification())) {
+            return this.buildPollResult(messages);
+        }
+        return this.buildPollResult(messages);
     }
     /**
      * 在本地缓冲区为空时，从服务端补拉离线期间积累的未读消息。
@@ -1786,6 +2018,7 @@ export class McpServer {
         if (DEGRADED_MODE_ENABLED) {
             logger.info(`[McpServer] 降级模式已启用，注册失败时将以离线模式继续运行`);
         }
+        // v1.13.0: 不再加载本地元数据缓存，过期/TODO/回忆状态统一由服务端 memory_status 字段管理
         // 后台注册：不阻塞 MCP 工具暴露，Agent 可立即接收工具调用
         this.autoRegisterInBackground();
         // 启动后台 Memory 文件变更检测
@@ -1826,6 +2059,37 @@ 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 列表)，且已经完成请移除标注为已完成状态。\n\n待办项：\n${pendingList}${pendingCount > 5 ? `\n  ...及其他 ${pendingCount - 5} 条` : ''}`,
+                requireReply: false,
+                prompt: "这是一条短期记忆 TODO 提醒，请调用 list_memories({ memory_type: 'task_list' }) 查看待办列表，完成后通过 update_memory({ todo_status: 'completed' }) 标注为已完成，或通过 delete_memory 移除已完成项。",
+                timestamp: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            logger.warn("[McpServer] 构建短期记忆 TODO 提醒失败:", error);
+            return null;
+        }
+    }
     /**
      * 停止后台 Memory 文件变更检测定时器。
      */
@@ -1836,6 +2100,11 @@ export class McpServer {
             logger.info("[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）。
     async autoRegister() {
         const agentConfig = this.agentClient.getAgentConfig();
         logger.info(`[McpServer] 角色: "${agentConfig.roleName}"`);