aws-runtime-bridge 1.9.10 → 1.9.21

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

@@ -2,6 +2,7 @@
  * MCP Server 实现
  * 提供 MCP Tools 供 AI Agent 调用
  */
+import fs from "node:fs";
 import path from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -11,13 +12,25 @@ import { MCP_SERVER_NAME, MCP_SERVER_VERSION, REGISTER_MAX_RETRIES, REGISTER_RET
 import { logger } from "./logger.js";
 import { MCP_TOOLS } from "./mcp-tools.js";
 import { MessageBuffer } from "./message-buffer.js";
+import { ContextManager } from "./context-manager.js";
 import { MemoryCapacityError, MemoryStore, } from "./memory-store.js";
 import { ServerMemoryStore } from "./server-memory-store.js";
-const DEFAULT_POLL_MESSAGE_BLOCK_WAIT_MS = 30_000;
-const DEFAULT_POLL_MESSAGE_EMPTY_RETRY_DELAY_MS = 100;
-const DEFAULT_POLL_MESSAGE_ERROR_RETRY_DELAY_MS = 5_000;
+/**
+ * poll_message 单次 HTTP 长轮询的默认服务端阻塞等待时间：240 秒（4 分钟）。
+ * 配合 callToolOnce 的 600 秒客户端超时，每次 HTTP 请求可阻塞最多 4 分钟，
+ * 大幅减少轮询次数，同时避免 30s 短轮询在服务端排队时频繁触发 120s 超时。
+ * 可通过环境变量 AWS_POLL_MESSAGE_BLOCK_WAIT_MS 覆盖。
+ */
+const DEFAULT_POLL_MESSAGE_BLOCK_WAIT_MS = 240_000;
+/**
+ * poll_message 底层 HTTP 请求的安全超时参考值：600 秒（10 分钟）。
+ * 用于 clamp blockWaitMs，确保服务端阻塞时间不会超过客户端单次 HTTP 调用的超时时间。
+ * 与 http-client.ts 中的 POLL_MESSAGE_ONCE_TIMEOUT_MS 对齐。
+ */
+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;
+const DEFAULT_MEMORY_FILE_CHECK_INTERVAL_MS = 5_000;
 const PATH_UNSAFE_CHARACTERS = new Set([
     "<",
     ">",
@@ -35,7 +48,92 @@ export class McpServer {
     messageBuffer;
     memoryStore;
     roleMemoryStore;
+    sessionContextMemoryStore;
     memoryStoresShareFile;
+    initialRoleName = "";
+    /** 上下文管理器 (v1.8.0) */
+    contextManager;
+    /**
+     * 内存级去重缓存：记录本轮已通知过的 listable memory 文件变更状态。
+     * key = memoryId，value = 已通知时刻各绑定文件的 MD5 复合哈希。
+     * 文件再次变更（MD5 变化）时仍会触发新通知。
+     * 进程重启后自动清空（届时重新检测）。
+     */
+    notifiedFileChangeMemoryIds = new Map();
+    /**
+     * 本地缓存 listable 记忆（task_list/recently_memory）的文件 MD5 map。
+     * 服务端（Java 后端）不持久化 file_md5_map 字段，listByType 返回的记录该字段为 undefined。
+     * 必须本地缓存才能让 checkMemoriesFileChanges 有正确的旧 MD5 做对比。
+     */
+    listableMd5Cache = new Map();
+    /** 后台 Memory 文件变更检测定时器 (v1.9.0) */
+    memoryFileCheckInterval = null;
+    /**
+     * 收到 Profile 后同步角色存储路径。
+     * 当服务端返回的 roleName 与进程初始化时不一致时，重建 roleMemoryStore 指向正确的目录。
+     */
+    syncRoleMemoryStore(profile) {
+        if (!profile.roleName) {
+            return;
+        }
+        const expectedRoleDir = McpServer.sanitizeRoleDirectoryName(profile.roleName);
+        if (expectedRoleDir === this.initialRoleName) {
+            return;
+        }
+        logger.info(`[McpServer] 角色目录与初始值不一致，重建 roleMemoryStore: "${this.initialRoleName}" -> "${expectedRoleDir}"`);
+        this.roleMemoryStore = new MemoryStore(McpServer.buildRoleMemoryStorePath(expectedRoleDir));
+        this.initialRoleName = expectedRoleDir;
+    }
+    /**
+     * 规范化绑定的文件路径。
+     * 项目约定以下前缀都表示工作区根路径：
+     *   ./xxx → ./xxx (已是相对路径)
+     *   /xxx  → ./xxx (/ 视为工作区根路径)
+     *   @/xxx → ./xxx (@/ 视为工作区根路径别名)
+     *   xxx   → ./xxx (裸路径视为当前工作区相对)
+     */
+    normalizeBoundFilePath(filePath) {
+        const trimmed = String(filePath || "").trim();
+        if (!trimmed)
+            return trimmed;
+        // 去掉 @/ 前缀（@ 视为工作区根路径）
+        const noAt = trimmed.startsWith("@/") ? trimmed.substring(1) : trimmed;
+        if (noAt.startsWith("./"))
+            return noAt;
+        // /xxx 和 xxx 都统一成 ./xxx
+        return `./${noAt.replace(/^\//, "")}`;
+    }
+    /**
+     * 规范化绑定的文件路径数组。
+     */
+    normalizeBoundFiles(files) {
+        if (!files || !Array.isArray(files))
+            return files;
+        return files.map(f => this.normalizeBoundFilePath(String(f)));
+    }
+    /**
+     * 验证绑定文件是否存在。
+     * 主流程：规范化后的路径 -> 相对于工作区根路径解析 -> 逐文件检查是否存在 -> 汇总缺失列表并抛出错误。
+     */
+    async validateBoundFilesExist(boundFiles) {
+        if (!boundFiles || boundFiles.length === 0)
+            return;
+        const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+        const { access } = await import('node:fs/promises');
+        const missingFiles = [];
+        for (const filePath of boundFiles) {
+            try {
+                const resolvedPath = path.resolve(workspacePath, filePath);
+                await access(resolvedPath);
+            }
+            catch {
+                missingFiles.push(filePath);
+            }
+        }
+        if (missingFiles.length > 0) {
+            throw new Error(`绑定的文件不存在，请确认文件路径正确后再重新提交:\n${missingFiles.map(f => `  - ${f}`).join('\n')}`);
+        }
+    }
     /**
      * 记忆写入成功后的 MCP 响应 DTO。
      * 主流程：保留定位与版本元数据，刻意不包含 content，避免 create/update 回显大段提交内容。
@@ -46,19 +144,50 @@ export class McpServer {
             uri: record.uri,
             domain: record.domain,
             path: record.path,
+            title: record.title,
             memory_type: record.memory_type,
             createdAt: record.createdAt,
             updatedAt: record.updatedAt,
             version: record.version,
+            keywords: record.keywords,
+            bound_files: record.bound_files,
+        };
+    }
+    /**
+     * 返回完整的 Memory 记录（包含元数据）。
+     * Memory 增强功能 (v1.6.0)
+     */
+    toMemoryRecordWithMetadata(record) {
+        return {
+            id: record.id,
+            uri: record.uri,
+            domain: record.domain,
+            path: record.path,
+            title: record.title,
+            content: record.content,
+            memory_type: record.memory_type,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            version: record.version,
+            // Memory 增强字段
+            keywords: record.keywords,
+            bound_files: record.bound_files,
+            file_md5_map: record.file_md5_map,
+            update_status: record.update_status,
+            updating_agent_id: record.updating_agent_id,
+            last_check_time: record.last_check_time,
         };
     }
     constructor() {
         this.agentClient = new AgentClient();
         this.messageBuffer = new MessageBuffer();
+        this.initialRoleName = McpServer.resolveRoleMemoryDirectoryName();
         const memoryStorePaths = McpServer.resolveMemoryStorePaths();
         this.memoryStore = new ServerMemoryStore(this.agentClient);
         this.roleMemoryStore = new MemoryStore(memoryStorePaths.rolePath);
+        this.sessionContextMemoryStore = new MemoryStore(path.join(path.dirname(memoryStorePaths.rolePath), "..", "session_context"));
         this.memoryStoresShareFile = false;
+        this.contextManager = new ContextManager(this.sessionContextMemoryStore);
         this.server = new Server({
             name: MCP_SERVER_NAME,
             version: MCP_SERVER_VERSION,
@@ -197,6 +326,16 @@ export class McpServer {
                 return await this.handleRemoveTaskListMemory(args);
             case "archive_recently_memory":
                 return await this.handleArchiveRecentlyMemory(args);
+            // Memory 增强功能工具 (v1.6.0)
+            case "list_memories_by_file":
+                return await this.handleListMemoriesByFile(args);
+            case "abandon_memory_update":
+                return await this.handleAbandonMemoryUpdate(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}`);
         }
@@ -206,6 +345,7 @@ export class McpServer {
         "task_list",
         "recently_memory",
         "memory",
+        "session_context",
     ];
     static MEMORY_TOOL_NAMES = new Set([
         "create_memory",
@@ -217,14 +357,33 @@ export class McpServer {
         "get_memory_stats",
         "remove_task_list_memory",
         "archive_recently_memory",
+        // Memory 增强功能工具 (v1.6.0)
+        "list_memories_by_file",
+        "abandon_memory_update",
     ]);
     /**
-     * 解析角色级记忆目录名。
-     * 主流程：优先使用 AWS_ROLE_NAME，清理路径分隔符等非法字符，避免不同角色的长期 memory 混写。
+     * 从 startPath 向上逐级查找 .agentswork 目录。
+     * 主流程：从 startPath 开始检查是否存在 .agentswork -> 递归父目录直到根目录 -> 如果找到返回完整路径，否则在 startPath 创建。
      */
-    static resolveRoleMemoryDirectoryName() {
-        const roleName = String(process.env.AWS_ROLE_NAME || "").trim();
-        const safeRoleName = roleName
+    static findAgentsworkDirSync(startPath) {
+        let current = path.resolve(startPath);
+        while (true) {
+            if (fs.existsSync(path.join(current, ".agentswork"))) {
+                return path.join(current, ".agentswork");
+            }
+            const parent = path.dirname(current);
+            if (parent === current)
+                break; // 到达根目录
+            current = parent;
+        }
+        return path.join(path.resolve(startPath), ".agentswork");
+    }
+    /**
+     * 清理角色名中的非法路径字符，返回安全的目录名。
+     */
+    static sanitizeRoleDirectoryName(roleName) {
+        const safeRoleName = String(roleName || "")
+            .trim()
             .split("")
             .map((character) => PATH_UNSAFE_CHARACTERS.has(character) || character.charCodeAt(0) < 32
             ? "_"
@@ -234,6 +393,21 @@ export class McpServer {
             .trim();
         return safeRoleName || "default-role";
     }
+    /**
+     * 解析角色级记忆目录名。
+     * 主流程：优先使用 AWS_ROLE_NAME，清理路径分隔符等非法字符，避免不同角色的长期 memory 混写。
+     */
+    static resolveRoleMemoryDirectoryName() {
+        return McpServer.sanitizeRoleDirectoryName(process.env.AWS_ROLE_NAME || "");
+    }
+    /**
+     * 根据 roleName 构建永久记忆存储路径。
+     */
+    static buildRoleMemoryStorePath(roleName) {
+        const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+        const agentsworkDir = McpServer.findAgentsworkDirSync(workspacePath);
+        return path.join(agentsworkDir, "memory", "memory", McpServer.sanitizeRoleDirectoryName(roleName));
+    }
     /**
      * 解析记忆存储路径。
      * 主流程：task_list/recently_memory 走 server 数据库；长期 memory 默认写入项目 .agentswork/memory/memory/<roleName>/<domain>.json。
@@ -244,10 +418,11 @@ export class McpServer {
             return { instancePath: configuredPath, rolePath: configuredPath };
         }
         const workspacePath = process.env.AWS_WORKSPACE_PATH || process.cwd();
+        const agentsworkDir = McpServer.findAgentsworkDirSync(workspacePath);
         const instancePath = String(process.env.AWS_INSTANCE_MEMORY_STORE_PATH || "").trim() ||
-            path.join(workspacePath, ".agentswork", "memory", "server-managed");
+            path.join(agentsworkDir, "memory", "server-managed");
         const rolePath = String(process.env.AWS_ROLE_MEMORY_STORE_PATH || "").trim() ||
-            path.join(workspacePath, ".agentswork", "memory", "memory", McpServer.resolveRoleMemoryDirectoryName());
+            path.join(agentsworkDir, "memory", "memory", McpServer.resolveRoleMemoryDirectoryName());
         return { instancePath, rolePath };
     }
     getRequiredString(args, key) {
@@ -265,6 +440,10 @@ export class McpServer {
         const value = args[key];
         return typeof value === "number" ? value : undefined;
     }
+    getOptionalStringArray(args, key) {
+        const value = args[key];
+        return Array.isArray(value) ? value.map((v) => String(v)) : undefined;
+    }
     getOptionalMemoryType(args) {
         const value = args.memory_type;
         if (value === undefined) {
@@ -353,6 +532,7 @@ export class McpServer {
                     ...roleStats.by_type.memory,
                     count: roleStats.by_type.memory.count,
                 },
+                session_context: instanceStats.by_type.session_context,
             },
         };
     }
@@ -372,6 +552,42 @@ export class McpServer {
             logger.warn("[McpServer] 上报合并 memory 统计失败，已保留本地记忆写入结果:", error);
         }
     }
+    /**
+     * 同步本地永久记忆到服务端。
+     * 主流程：读取本地 roleMemoryStore 中所有 memory 类型记录 -> 逐条写入服务端 memoryStore -> 已存在的记录静默跳过。
+     */
+    async syncLocalPermanentMemoryToServer() {
+        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);
+        }
+    }
     /**
      * 生成安全的工具状态上报参数。
      * 主流程：memory 工具只上报元数据，避免 content/query/old_string/new_string/append 离开本地记忆边界。
@@ -396,6 +612,7 @@ export class McpServer {
         if (name === "search_memory") {
             sanitized.queryProvided =
                 typeof args.query === "string" && args.query.length > 0;
+            sanitized.keyword_mode = args.keyword_mode;
         }
         return sanitized;
     }
@@ -404,13 +621,42 @@ export class McpServer {
      * 主流程：校验必填字段 -> 交给 MemoryStore 规范化 URI 和类型 -> 返回不含 content 的写入结果。
      */
     async handleCreateMemory(args) {
+        const boundFiles = this.normalizeBoundFiles(this.getOptionalStringArray(args, "bound_files"));
+        // 验证绑定文件是否存在，避免创建无有效文件绑定的记忆
+        await this.validateBoundFilesExist(boundFiles);
+        // 创建时即计算绑定文件的 MD5 基线，避免首次文件变更检测产生假阳性
+        let fileMd5Map;
+        let lastCheckTime;
+        if (boundFiles && boundFiles.length > 0) {
+            fileMd5Map = {};
+            for (const f of boundFiles) {
+                const md5 = await this.calculateFileMd5(f);
+                if (md5)
+                    fileMd5Map[f] = md5;
+            }
+            lastCheckTime = new Date().toISOString();
+        }
         const input = {
             memory_type: this.parseMemoryType(this.getRequiredString(args, "memory_type")),
             uri: this.getRequiredString(args, "uri"),
+            title: this.getOptionalString(args, "title"),
             content: this.getRequiredString(args, "content"),
+            keywords: this.getOptionalStringArray(args, "keywords"),
+            bound_files: boundFiles,
+            file_md5_map: fileMd5Map,
+            last_check_time: lastCheckTime,
         };
         const created = await this.getMemoryStoreForType(input.memory_type).createMemory(input);
         await this.reportCombinedMemoryStats();
+        // Dual-write permanent memory to server
+        if (input.memory_type === "memory") {
+            try {
+                await this.memoryStore.createMemory(input).catch(() => { });
+            }
+            catch (e) {
+                logger.warn("[McpServer] Failed to sync permanent memory to server:", e);
+            }
+        }
         return this.toMemoryWriteResult(created);
     }
     /**
@@ -444,16 +690,59 @@ export class McpServer {
         const input = {
             uri: this.getRequiredString(args, "uri"),
             memory_type: this.getOptionalMemoryType(args),
+            title: this.getOptionalString(args, "title"),
             old_string: this.getOptionalString(args, "old_string"),
             new_string: this.getOptionalString(args, "new_string"),
             append,
+            keywords: this.getOptionalStringArray(args, "keywords"),
+            bound_files: this.normalizeBoundFiles(this.getOptionalStringArray(args, "bound_files")),
         };
         const target = await this.findMemoryStoreForMutation(input);
+        // 读取当前记忆以获取 bound_files，用于 MD5 重算
+        const existingForMd5 = await target.store.readMemory({
+            uri: input.uri,
+            memory_type: target.memory_type ?? input.memory_type,
+        });
+        // 当显式传入新 bound_files 时验证文件是否存在
+        if (input.bound_files !== undefined) {
+            await this.validateBoundFilesExist(input.bound_files);
+        }
+        const effectiveBoundFiles = input.bound_files ?? existingForMd5?.bound_files;
+        // 重新计算绑定文件的 MD5 map，确保更新后 MD5 与文件实际内容一致
+        let fileMd5Map;
+        let lastCheckTime;
+        if (effectiveBoundFiles && effectiveBoundFiles.length > 0) {
+            fileMd5Map = {};
+            for (const f of effectiveBoundFiles) {
+                const md5 = await this.calculateFileMd5(f);
+                if (md5)
+                    fileMd5Map[f] = md5;
+            }
+            lastCheckTime = new Date().toISOString();
+        }
         const updated = await target.store.updateMemory({
             ...input,
             memory_type: target.memory_type ?? input.memory_type,
+            file_md5_map: fileMd5Map,
+            last_check_time: lastCheckTime,
         });
         await this.reportCombinedMemoryStats();
+        // Dual-write permanent memory update to server（同步 MD5 map 避免服务端重复检测）
+        if (target.memory_type === "memory") {
+            try {
+                await this.memoryStore
+                    .updateMemory({
+                    ...input,
+                    memory_type: "memory",
+                    file_md5_map: fileMd5Map,
+                    last_check_time: lastCheckTime,
+                })
+                    .catch(() => { });
+            }
+            catch (e) {
+                logger.warn("[McpServer] Failed to sync permanent memory update to server:", e);
+            }
+        }
         return this.toMemoryWriteResult(updated);
     }
     /**
@@ -472,19 +761,60 @@ export class McpServer {
         });
         if (deleted) {
             await this.reportCombinedMemoryStats();
+            // Dual-write permanent memory delete to server
+            if (target.memory_type === "memory") {
+                try {
+                    await this.memoryStore
+                        .deleteMemory({ uri: input.uri, memory_type: "memory" })
+                        .catch(() => { });
+                }
+                catch (e) {
+                    logger.warn("[McpServer] Failed to sync permanent memory delete to server:", e);
+                }
+            }
         }
         return { deleted };
     }
     /**
-     * 搜索本地记忆。
-     * 主流程：校验 query -> MemoryStore 对 uri/content 做大小写不敏感匹配和排序。
+     * 搜索本地记忆与子 Agent 记忆（父子 Agent 可见性）。
+     * 主流程：解析 scope -> own(默认)仅搜自己 -> children仅搜子Agent的file-scoped记忆 -> all合并。
+     * 子 Agent 判定规则：同项目且工作区路径为当前路径子目录。
      */
     async handleSearchMemory(args) {
+        const rawScope = this.getOptionalString(args, "scope");
+        const scope = rawScope === "children" || rawScope === "all" ? rawScope : "own";
+        const rawKeywordMode = this.getOptionalString(args, "keyword_mode");
+        const keywordMode = rawKeywordMode === "all" ? "all" : rawKeywordMode === "any" ? "any" : undefined;
         const input = {
             query: this.getRequiredString(args, "query"),
             limit: this.getOptionalNumber(args, "limit"),
             memory_type: this.getOptionalMemoryType(args),
+            keywords: this.getOptionalStringArray(args, "keywords"),
+            keyword_mode: keywordMode,
+            scope,
         };
+        // scope='children': 仅搜索子 Agent 的 file-scoped 记忆（通过 server 代理）
+        if (scope === "children") {
+            return await this.memoryStore.searchMemory(input);
+        }
+        // 搜索自己的记忆（scope='own' 默认行为）
+        const ownResult = await this.searchOwnMemories(input);
+        // scope='own': 仅返回自己的结果
+        if (scope === "own") {
+            return ownResult;
+        }
+        // scope='all': 合并自己的记忆与子 Agent 的 file-scoped 记忆
+        const childResult = await this.memoryStore.searchMemory({
+            ...input,
+            scope: "children",
+        });
+        return this.mergeSearchResults(ownResult, childResult, input.limit);
+    }
+    /**
+     * 搜索自己工作区的所有记忆。
+     * 具体逻辑：按 memory_type 分流 -> 无类型时合并 roleMemoryStore(永久)与 memoryStore(task_list/recently)。
+     */
+    async searchOwnMemories(input) {
         if (input.memory_type) {
             return await this.getMemoryStoreForType(input.memory_type).searchMemory(input);
         }
@@ -510,6 +840,26 @@ export class McpServer {
             .slice(0, limit);
         return { query: roleResult.query || instanceResult.query, results };
     }
+    /**
+     * 合并两组搜索结果，按 uri 去重、更新时间排序。
+     * 具体逻辑：own 结果优先 -> 补充 child 结果中 uri 不重复的 -> 排序 -> 截断到 limit。
+     */
+    mergeSearchResults(own, child, limit) {
+        const seen = new Set();
+        const maxResults = typeof limit === "number" && limit > 0 ? limit : 10;
+        const merged = [...own.results, ...child.results]
+            .filter((record) => {
+            const key = record.uri;
+            if (seen.has(key)) {
+                return false;
+            }
+            seen.add(key);
+            return true;
+        })
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+            .slice(0, maxResults);
+        return { query: own.query || child.query, results: merged };
+    }
     /**
      * 列出短期类型记忆。
      * 主流程：只允许 task_list/recently_memory，由 MemoryStore 阻止长期 memory 的全量列出。
@@ -566,7 +916,10 @@ export class McpServer {
         const archived = await this.roleMemoryStore.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,
@@ -575,12 +928,231 @@ export class McpServer {
         await this.reportCombinedMemoryStats();
         return archived;
     }
+    /**
+     * 按文件查询绑定了该文件的 Memory
+     * Memory 增强功能 (v1.6.0)
+     */
+    /**
+     * 按文件路径查询 Memory（支持 scope 跨 Agent 搜索）。
+     * 主流程：解析scope -> own(默认)仅自己 -> children通过server按path_prefix匹配子Agent -> all合并。
+     * 对于永久记忆(type=memory)同时查询本地roleMemoryStore作为补充。
+     */
+    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 自动匹配）
+        if (scope === "children") {
+            const childResult = await this.memoryStore.listByFile(normalizedPath, {
+                memory_type: memoryType,
+                scope: "children",
+            });
+            return {
+                file_path: normalizedPath,
+                count: childResult.length,
+                memories: childResult.map(m => this.toMemoryRecordWithMetadata(m)),
+            };
+        }
+        // 搜索自己的记忆
+        const ownMemories = await this.collectOwnMemoriesByFile(normalizedPath, memoryType);
+        if (scope === "own") {
+            return {
+                file_path: normalizedPath,
+                count: ownMemories.length,
+                memories: ownMemories.map(m => this.toMemoryRecordWithMetadata(m)),
+            };
+        }
+        // scope='all': 合并自己的 + 子 Agent 的
+        const childResult = await this.memoryStore.listByFile(normalizedPath, {
+            memory_type: memoryType,
+            scope: "children",
+        });
+        const seen = new Set(ownMemories.map(m => m.id));
+        const merged = [...ownMemories];
+        for (const m of childResult) {
+            if (!seen.has(m.id)) {
+                merged.push(m);
+                seen.add(m.id);
+            }
+        }
+        merged.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        return {
+            file_path: normalizedPath,
+            count: merged.length,
+            memories: merged.map(m => this.toMemoryRecordWithMetadata(m)),
+        };
+    }
+    /**
+     * 按文件路径搜索本 Agent 的记忆。
+     * 同时查询临时记忆(server)和永久记忆(local roleMemoryStore)。
+     */
+    async collectOwnMemoriesByFile(filePath, memoryType) {
+        const serverResult = await this.memoryStore.listByFile(filePath, {
+            memory_type: memoryType,
+        });
+        let localResult = [];
+        // 补充查询本地永久记忆（server 可能未同步）
+        if (!memoryType || memoryType === "memory") {
+            localResult = await this.roleMemoryStore.listByFile(filePath, "memory");
+        }
+        // 去重合并
+        const seen = new Set(serverResult.map(m => `${m.memory_type}:${m.uri}`));
+        const merged = [...serverResult];
+        for (const m of localResult) {
+            const key = `${m.memory_type}:${m.uri}`;
+            if (!seen.has(key)) {
+                merged.push(m);
+                seen.add(key);
+            }
+        }
+        return merged;
+    }
+    /**
+     * 放弃 Memory 更新状态
+     * Memory 增强功能 (v1.6.0)
+     */
+    async handleAbandonMemoryUpdate(args) {
+        const uri = this.getRequiredString(args, "uri");
+        const memoryType = this.getOptionalMemoryType(args);
+        const record = await this.memoryStore.readMemory({ uri, memory_type: memoryType });
+        if (!record) {
+            throw new Error(`Memory not found: ${uri}`);
+        }
+        // 清除 updating 状态
+        await this.memoryStore.updateMemory({
+            uri: record.uri,
+            memory_type: record.memory_type,
+        });
+        return {
+            success: true,
+            uri: record.uri,
+            message: "Memory 更新状态已清除",
+        };
+    }
+    // ============ 上下文压缩工具处理 (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,
+                };
+            }
+        }
+    }
+    /**
+     * 获取最近的消息历史用于压缩。
+     * 主流程：获取未读消息 + 历史消息 -> 合并排序 -> 返回。
+     */
+    async fetchRecentMessages() {
+        const [dmHistory, groupHistory] = await Promise.all([
+            this.agentClient.getDmHistory(undefined, 200).catch(() => ({ messages: [], count: 0 })),
+            this.agentClient.getGroupHistory(200).catch(() => ({ messages: [], count: 0 })),
+        ]);
+        const messages = [
+            ...dmHistory.messages,
+            ...groupHistory.messages,
+        ];
+        messages.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+        return messages;
+    }
     async handleSendGroup(args) {
         if (!args.content || typeof args.content !== "string") {
             throw new Error("content is required");
         }
+        // 记录 token 消耗 (v1.8.0)
+        this.recordMessageTokenUsage(args.content).catch((err) => logger.warn("[McpServer] Failed to record token usage", err));
         return await this.agentClient.sendGroupMessage(args.content, args.projectName, args.roomId);
     }
+    /**
+     * 记录消息发送产生的 token 消耗。
+     * 主流程：估算内容 token -> 获取会话 ID -> 记录到 ContextManager。
+     */
+    async recordMessageTokenUsage(content) {
+        try {
+            const profile = await this.agentClient.getProfile().catch(() => null);
+            if (!profile?.runtimeSessionId)
+                return;
+            const estimatedTokens = this.contextManager.estimateTokens(content);
+            await this.contextManager.recordUsage(profile.runtimeSessionId, { input: 0, output: estimatedTokens });
+        }
+        catch {
+            // 非关键功能，静默失败
+        }
+    }
     async handleHireColleague(args) {
         if (!args.workspacePath || typeof args.workspacePath !== "string") {
             throw new Error("workspacePath is required");
@@ -605,6 +1177,8 @@ export class McpServer {
         if (!args.content || typeof args.content !== "string") {
             throw new Error("content is required");
         }
+        // 记录 token 消耗 (v1.8.0)
+        this.recordMessageTokenUsage(args.content).catch((err) => logger.warn("[McpServer] Failed to record token usage", err));
         return await this.agentClient.sendDirectMessage(args.targetId, args.content, args.waitReply, args.replyToCallId, args.timeoutMs);
     }
     async handleCreateTaskInstanceComment(args) {
@@ -616,10 +1190,28 @@ export class McpServer {
         });
     }
     async handlePollMessage() {
+        // 首次非阻塞预取：使用 get_dm_messages 而非 poll_message，
+        // 避免进入服务端 MVC 异步线程池排队（poll_message 始终走异步池），
+        // 确保快速返回，不影响后续 waitForMessagesWithPoll 的 resolver 注册。
+        // 流程线任务由后续的 waitForMessagesWithPoll → 后台长轮询负责补拉。
         await this.hydrateUnreadMessagesFromServer({
             blockIfEmpty: false,
-            includePipelineTasks: true,
+            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,
+                };
+            }
+        }
         const immediateMemoryNotification = await this.buildMemoryCleanupNotification();
         if (immediateMemoryNotification) {
             const messages = this.messageBuffer.get();
@@ -630,8 +1222,14 @@ export class McpServer {
                 fromBuffer: true,
             };
         }
-        await this.hydrateUnreadMessagesUntilAvailable();
-        const messages = this.messageBuffer.get();
+        const messages = await this.waitForMessagesWithPoll();
+        // 后台定时器启用时跳过，避免与定时器推送重复
+        if (!this.memoryFileCheckInterval) {
+            const fileChangeNotification2 = await this.buildMemoryFileChangeNotification();
+            if (fileChangeNotification2) {
+                messages.directMessages.unshift(fileChangeNotification2);
+            }
+        }
         const memoryNotification = await this.buildMemoryCleanupNotification();
         if (memoryNotification) {
             messages.directMessages.unshift(memoryNotification);
@@ -642,41 +1240,39 @@ export class McpServer {
             fromBuffer: true,
         };
     }
-    /**
-     * 持续补拉未读消息直到有消息可返回。
-     * 主流程：用有限后端长轮询分片阻塞补拉 -> 空返回时短暂退避 -> 继续等待，避免 poll_message 空轮询唤醒模型。
-     * 注意：poll_message 是 Agent 主循环的永久阻塞入口，不能恢复为按总时长限时返回空结果。
-     */
-    async hydrateUnreadMessagesUntilAvailable() {
-        while (this.messageBuffer.size() === 0) {
-            const hydrated = await this.hydrateUnreadMessagesIfNeeded({
-                blockIfEmpty: true,
-                blockTimeoutMs: this.resolvePollMessageBlockWaitMs(),
-                includePipelineTasks: true,
-            });
-            if (this.messageBuffer.size() === 0) {
-                await this.sleep(hydrated
-                    ? this.resolvePollMessageEmptyRetryDelayMs()
-                    : this.resolvePollMessageErrorRetryDelayMs());
-            }
-        }
+    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);
-        const httpTimeoutMs = this.parsePositiveIntegerEnv("AWS_MCP_HTTP_REQUEST_TIMEOUT_MS", DEFAULT_MCP_HTTP_REQUEST_TIMEOUT_MS);
+        // poll_message 走 callToolOnce 专用通道，HTTP 超时使用 POLL_MESSAGE_LONGPOLL_HTTP_TIMEOUT_MS
+        // 与 http-client.ts 中的 callToolOnce 默认超时对齐，不再引用通用的 AWS_MCP_HTTP_REQUEST_TIMEOUT_MS
+        const httpTimeoutMs = POLL_MESSAGE_LONGPOLL_HTTP_TIMEOUT_MS;
         const maxSafeBlockWaitMs = Math.max(1, httpTimeoutMs - POLL_MESSAGE_HTTP_TIMEOUT_BUFFER_MS);
         if (blockWaitMs >= httpTimeoutMs) {
-            logger.warn(`[McpServer] AWS_POLL_MESSAGE_BLOCK_WAIT_MS=${blockWaitMs}ms 不应大于等于 AWS_MCP_HTTP_REQUEST_TIMEOUT_MS=${httpTimeoutMs}ms，已夹紧为 ${maxSafeBlockWaitMs}ms`);
+            logger.warn(`[McpServer] AWS_POLL_MESSAGE_BLOCK_WAIT_MS=${blockWaitMs}ms 不应大于等于 poll_message HTTP 超时 ${httpTimeoutMs}ms，已夹紧为 ${maxSafeBlockWaitMs}ms`);
             return maxSafeBlockWaitMs;
         }
         return blockWaitMs;
     }
-    resolvePollMessageEmptyRetryDelayMs() {
-        return this.parsePositiveIntegerEnv("AWS_POLL_MESSAGE_EMPTY_RETRY_DELAY_MS", DEFAULT_POLL_MESSAGE_EMPTY_RETRY_DELAY_MS);
-    }
-    resolvePollMessageErrorRetryDelayMs() {
-        return this.parsePositiveIntegerEnv("AWS_POLL_MESSAGE_ERROR_RETRY_DELAY_MS", DEFAULT_POLL_MESSAGE_ERROR_RETRY_DELAY_MS);
-    }
     /**
      * 解析正整数环境变量。
      * 主流程：读取环境变量 -> 转成整数 -> 非法值使用默认值。
@@ -743,6 +1339,249 @@ export class McpServer {
             return null;
         }
     }
+    /**
+     * 构建 Memory 文件变更检测通知。
+     * Memory 增强功能 (v1.6.0)
+     *
+     * 检测流程：
+     * 1. 检查本 Agent 标记为 updating 但未处理的 Memory
+     * 2. 检查短期记忆、近期记忆绑定的文件是否变更
+     * 3. 如果没有变更，检查永久记忆的文件变更，标记最多 5 个为 updating
+     */
+    async buildMemoryFileChangeNotification() {
+        try {
+            const agentId = this.getCurrentAgentId();
+            if (!agentId) {
+                return null;
+            }
+            // 步骤1: 检查是否有 pending 的 updating memories（角色本地永久记忆），
+            // 同时检测绑定文件是否再次变更（用户可能在 Agent 处理前又改了文件）
+            const permanentList = await this.roleMemoryStore.listByType('memory');
+            const updatingMemories = permanentList.filter(m => m.update_status === 'updating' && m.updating_agent_id === agentId);
+            if (updatingMemories.length > 0) {
+                // 对 updating 记忆也检测文件是否再次变更
+                const updatingChanges = await this.checkMemoriesFileChanges(updatingMemories);
+                if (updatingChanges.length > 0) {
+                    // 有新的文件变更，更新 MD5 map 持久化，发出新变更通知
+                    for (const change of updatingChanges) {
+                        const memory = updatingMemories.find(m => m.id === change.memoryId);
+                        if (memory) {
+                            await this.roleMemoryStore.updateMemory({
+                                uri: memory.uri,
+                                memory_type: 'memory',
+                                update_status: 'updating',
+                                updating_agent_id: agentId,
+                                file_md5_map: memory.file_md5_map,
+                                last_check_time: memory.last_check_time,
+                            });
+                        }
+                    }
+                    const selectedCount = Math.min(updatingChanges.length, 5);
+                    const changeDetails = updatingChanges
+                        .slice(0, 5)
+                        .map(change => `- ${change.memoryUri} (文件: ${change.changedFiles.join(', ')})`)
+                        .join('\n');
+                    return {
+                        msgId: `memory-file-change-${Date.now()}`,
+                        senderId: "MCP-System",
+                        senderName: "系统",
+                        receiverId: agentId,
+                        content: `检测到以下 ${selectedCount} 个处于更新中的 Memory 绑定的文件再次变更，已更新 MD5 记录：\n\n${changeDetails}\n\n请调用 read_memory 查看最新内容并调用 update_memory 更新。`,
+                        requireReply: false,
+                        prompt: "这是一条文件变更提醒，您之前标记为更新中的记忆绑定的文件又有新变更，请处理。",
+                        timestamp: new Date().toISOString(),
+                    };
+                }
+                const memoryList = updatingMemories
+                    .slice(0, 5)
+                    .map(m => `- ${m.uri} (文件: ${m.bound_files?.join(', ') || '未知'})`)
+                    .join('\n');
+                return {
+                    msgId: `memory-update-pending-${Date.now()}`,
+                    senderId: "MCP-System",
+                    senderName: "系统",
+                    receiverId: agentId,
+                    content: `您有以下 Memory 正处于更新中状态但尚未完成更新：\n\n${memoryList}\n\n请继续完成更新工作。`,
+                    requireReply: false,
+                    prompt: "这是一条更新提醒，您之前已标记这些记忆为更新中，请继续处理。",
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            // 步骤2: 检查短期记忆和近期记忆（服务端存储）
+            const recentlyMemories = await this.memoryStore.listByType('recently_memory');
+            const taskListMemories = await this.memoryStore.listByType('task_list');
+            const listableMemories = [...recentlyMemories, ...taskListMemories];
+            // 用本地 MD5 缓存补全 listable 记忆（服务端可能不持久化 file_md5_map 字段）
+            // 确保 checkMemoriesFileChanges 有正确的旧 MD5 做比对而非始终以空字典开始
+            for (const m of listableMemories) {
+                if (!m.file_md5_map) {
+                    const cached = this.listableMd5Cache.get(m.id);
+                    if (cached) {
+                        m.file_md5_map = cached;
+                    }
+                }
+            }
+            const listableChanges = await this.checkMemoriesFileChanges(listableMemories);
+            // 使用复合 key（memoryId + 当前各绑定文件 MD5）过滤已通知变更，
+            // 同一条记忆文件再次变更（MD5 变化）时仍能触发新通知
+            const newListableChanges = listableChanges.filter(c => {
+                const memory = listableMemories.find(m => m.id === c.memoryId);
+                const md5Map = memory?.file_md5_map;
+                const changeKey = this.buildMemoryChangeNotificationKey(c.memoryId, md5Map);
+                return this.notifiedFileChangeMemoryIds.get(c.memoryId) !== changeKey;
+            });
+            if (newListableChanges.length > 0) {
+                // 记录当前状态的复合键，下次对比时若 MD5 变化则重新通知
+                // 同时将 MD5 map 写入本地缓存，弥补服务端不持久化 file_md5_map 的问题
+                for (const c of newListableChanges) {
+                    const memory = listableMemories.find(m => m.id === c.memoryId);
+                    const md5Map = memory?.file_md5_map;
+                    this.notifiedFileChangeMemoryIds.set(c.memoryId, this.buildMemoryChangeNotificationKey(c.memoryId, md5Map));
+                    if (memory?.file_md5_map) {
+                        this.listableMd5Cache.set(c.memoryId, memory.file_md5_map);
+                    }
+                }
+                const changeDetails = newListableChanges
+                    .map(change => `- ${change.memoryUri} (文件: ${change.changedFiles.join(', ')})`)
+                    .join('\n');
+                return {
+                    msgId: `memory-file-change-${Date.now()}`,
+                    senderId: "MCP-System",
+                    senderName: "系统",
+                    receiverId: agentId,
+                    content: `检测到以下 Memory 绑定的文件已变更，请及时更新：\n\n${changeDetails}\n\n请调用 read_memory 查看内容并调用 update_memory 更新。`,
+                    requireReply: false,
+                    prompt: "这是一条文件变更提醒，自动生成，无需持久化。",
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            // 步骤3: 检查永久记忆（角色本地存储）
+            const normalPermanentMemories = permanentList.filter(m => m.bound_files && m.bound_files.length > 0 &&
+                (m.update_status === 'normal' || !m.update_status));
+            const permanentChanges = await this.checkMemoriesFileChanges(normalPermanentMemories);
+            if (permanentChanges.length > 0) {
+                // 最多选取 5 个
+                const selectedChanges = permanentChanges.slice(0, 5);
+                // 标记为 updating 状态，同时持久化当前 MD5 map，
+                // 确保后续检测能正确对比文件变更，而非每次都视为"已变更"
+                for (const change of selectedChanges) {
+                    const memory = permanentList.find(m => m.id === change.memoryId);
+                    if (memory) {
+                        await this.roleMemoryStore.updateMemory({
+                            uri: memory.uri,
+                            memory_type: 'memory',
+                            update_status: 'updating',
+                            updating_agent_id: agentId,
+                            // checkMemoriesFileChanges 已更新 in-memory 对象中的 MD5 map
+                            file_md5_map: memory.file_md5_map,
+                            last_check_time: memory.last_check_time,
+                        });
+                    }
+                }
+                const changeDetails = selectedChanges
+                    .map(change => `- ${change.memoryUri} (文件: ${change.changedFiles.join(', ')})`)
+                    .join('\n');
+                return {
+                    msgId: `memory-file-change-${Date.now()}`,
+                    senderId: "MCP-System",
+                    senderName: "系统",
+                    receiverId: agentId,
+                    content: `检测到以下 ${selectedChanges.length} 个永久记忆绑定的文件已变更，已为您标记为更新中：\n\n${changeDetails}\n\n请调用 read_memory 查看内容并调用 update_memory 更新。更新完成后状态将自动恢复为正常。`,
+                    requireReply: false,
+                    prompt: "这是一条文件变更提醒，已自动标记更新状态，请处理。",
+                    timestamp: new Date().toISOString(),
+                };
+            }
+            return null;
+        }
+        catch (error) {
+            logger.warn("[McpServer] 构建 Memory 文件变更检测通知失败:", error);
+            return null;
+        }
+    }
+    /**
+     * 检查一组 Memory 的文件变更
+     * Memory 增强功能 (v1.6.0)
+     */
+    async checkMemoriesFileChanges(memories) {
+        const changes = [];
+        for (const memory of memories) {
+            if (!memory.bound_files || memory.bound_files.length === 0) {
+                continue;
+            }
+            try {
+                const changedFiles = [];
+                const newMd5Map = {};
+                const oldMd5Map = memory.file_md5_map || {};
+                for (const filePath of memory.bound_files) {
+                    try {
+                        const currentMd5 = await this.calculateFileMd5(filePath);
+                        if (currentMd5 === null) {
+                            // 文件不存在或无法读取
+                            changedFiles.push(`${filePath} (文件不存在或无法访问)`);
+                            continue;
+                        }
+                        newMd5Map[filePath] = currentMd5;
+                        const oldMd5 = oldMd5Map[filePath];
+                        if (!oldMd5 || oldMd5 !== currentMd5) {
+                            changedFiles.push(filePath);
+                        }
+                    }
+                    catch (error) {
+                        logger.info(`[McpServer] 计算文件 MD5 失败: ${filePath}`, error);
+                        changedFiles.push(`${filePath} (MD5计算失败)`);
+                    }
+                }
+                if (changedFiles.length > 0) {
+                    changes.push({
+                        memoryId: memory.id,
+                        memoryUri: memory.uri,
+                        changedFiles,
+                    });
+                    // 更新 MD5 映射
+                    memory.file_md5_map = newMd5Map;
+                    memory.last_check_time = new Date().toISOString();
+                }
+            }
+            catch (error) {
+                logger.warn(`[McpServer] 检查 Memory ${memory.id} 文件变更失败:`, error);
+            }
+        }
+        return changes;
+    }
+    /**
+     * 计算文件 MD5
+     * Memory 增强功能 (v1.6.0)
+     */
+    async calculateFileMd5(filePath) {
+        try {
+            const { createReadStream } = await import('node:fs');
+            const { createHash } = await import('node:crypto');
+            return new Promise((resolve) => {
+                const hash = createHash('md5');
+                const stream = createReadStream(filePath);
+                stream.on('data', (chunk) => hash.update(chunk));
+                stream.on('end', () => resolve(hash.digest('hex')));
+                stream.on('error', () => resolve(null));
+            });
+        }
+        catch (error) {
+            logger.info(`[McpServer] 计算文件 MD5 失败: ${filePath}`, error);
+            return null;
+        }
+    }
+    /**
+     * 构建 Memory 文件变更通知的复合去重键。
+     * 基于 memoryId + 当前各绑定文件的 MD5 生成，当任意绑定文件内容变化时复合键也随之变化，
+     * 从而确保真实文件变更不会因简单 memoryId 去重而静默吞掉。
+     */
+    buildMemoryChangeNotificationKey(memoryId, md5Map) {
+        if (!md5Map || Object.keys(md5Map).length === 0) {
+            return memoryId;
+        }
+        const sorted = Object.entries(md5Map).sort(([a], [b]) => a.localeCompare(b));
+        return `${memoryId}:${sorted.map(([k, v]) => `${k}=${v}`).join('|')}`;
+    }
     async handleGetMessage() {
         await this.hydrateUnreadMessagesIfNeeded();
         const messages = this.messageBuffer.get();
@@ -949,8 +1788,54 @@ export class McpServer {
         }
         // 后台注册：不阻塞 MCP 工具暴露，Agent 可立即接收工具调用
         this.autoRegisterInBackground();
+        // 启动后台 Memory 文件变更检测
+        this.startMemoryFileWatcher();
         logger.info("[McpServer] MCP Server 已就绪，工具已可用");
     }
+    /**
+     * 停止 McpServer，清理后台定时器。
+     * 主流程：清理文件变更检测定时器 -> 停止 Agent 客户端消息循环。
+     */
+    stop() {
+        this.stopMemoryFileWatcher();
+        this.agentClient.stop();
+        logger.info("[McpServer] MCP Server 已停止");
+    }
+    /**
+     * 启动后台 Memory 文件变更检测定时器。
+     * 主流程：读取 AWS_MEMORY_FILE_CHECK_INTERVAL_MS -> 启动 setInterval -> 每次触发时检查绑定文件 MD5 变更 -> 有变更时直接推入消息缓冲区。
+     * 后台定时器启用后，poll_message 不再重复检查，避免重复推送通知。
+     */
+    startMemoryFileWatcher() {
+        const intervalMs = this.parsePositiveIntegerEnv("AWS_MEMORY_FILE_CHECK_INTERVAL_MS", DEFAULT_MEMORY_FILE_CHECK_INTERVAL_MS);
+        if (intervalMs <= 0) {
+            logger.info("[McpServer] 后台文件变更检测已禁用（AWS_MEMORY_FILE_CHECK_INTERVAL_MS=0），将回退到 poll_message 时检测");
+            return;
+        }
+        this.memoryFileCheckInterval = setInterval(async () => {
+            try {
+                const notification = await this.buildMemoryFileChangeNotification();
+                if (notification) {
+                    this.messageBuffer.push(notification);
+                    logger.info("[McpServer] 后台文件变更检测: 已推送 Memory 变更通知到消息缓冲区");
+                }
+            }
+            catch (error) {
+                logger.warn("[McpServer] 后台文件变更检测失败:", error);
+            }
+        }, intervalMs);
+        logger.info(`[McpServer] 后台文件变更检测已启动，间隔: ${intervalMs}ms（可通过 AWS_MEMORY_FILE_CHECK_INTERVAL_MS 环境变量调整，设为 0 禁用）`);
+    }
+    /**
+     * 停止后台 Memory 文件变更检测定时器。
+     */
+    stopMemoryFileWatcher() {
+        if (this.memoryFileCheckInterval) {
+            clearInterval(this.memoryFileCheckInterval);
+            this.memoryFileCheckInterval = null;
+            logger.info("[McpServer] 后台文件变更检测已停止");
+        }
+    }
     async autoRegister() {
         const agentConfig = this.agentClient.getAgentConfig();
         logger.info(`[McpServer] 角色: "${agentConfig.roleName}"`);
@@ -971,6 +1856,11 @@ export class McpServer {
                     statusReporter.reportWaitingInput();
                 }
                 await this.reportCombinedMemoryStats();
+                // 如果是新创建的角色，将本地永久记忆同步到服务端
+                if (result.isExisting === false) {
+                    logger.info("[McpServer] 新角色创建，同步本地永久记忆到服务端...");
+                    await this.syncLocalPermanentMemoryToServer();
+                }
                 return;
             }
             catch (error) {
@@ -1026,6 +1916,7 @@ export class McpServer {
                     // 收到 Profile 信息后，存储到消息缓冲区
                     logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
                     this.messageBuffer.setProfileMessage(profile);
+                    this.syncRoleMemoryStore(profile);
                 },
             });
             return;
@@ -1036,6 +1927,7 @@ export class McpServer {
                 // 收到 Profile 信息后，存储到消息缓冲区
                 logger.info(`[McpServer] profileHandler 被调用，displayName: ${profile.displayName}`);
                 this.messageBuffer.setProfileMessage(profile);
+                this.syncRoleMemoryStore(profile);
             },
         });
     }