mindforge-memory 6.4.1__py3-none-any.whl

mindforge/mcp/server.py

@@ -0,0 +1,2559 @@
+"""MindForge MCP Server — Model Context Protocol (stdio transport).
+
+Implements MCP 2024-11-05 over stdio JSON-RPC.
+
+Launch options:
+  python -m MindForge.mcp.server --db-path ./memory.db
+  MindForge-mcp --db-path ./memory.db
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import time as _time
+import traceback
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+# Allow running without editable install: add parent of mcp/ to sys.path
+_PKG_ROOT = Path(__file__).resolve().parent.parent
+if str(_PKG_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PKG_ROOT))
+
+# v5.6.2 收敛：版本号唯一真值在 mindforge/core/version.py，此处仅做再导出，
+# 避免发版时出现版本漂移（v5.8.13 起统一 mindforge.* 命名空间，不再需要回退）。
+from mindforge.core.version import __version__
+
+
+# ---------------------------------------------------------------------------
+# MCP transport — Content-Length framed JSON-RPC over stdio
+# ---------------------------------------------------------------------------
+
+def _log(msg: str) -> None:
+    """Debug output goes to stderr; never write to stdout."""
+    sys.stderr.write(f"[mcp-mindforge] {msg}\n")
+    sys.stderr.flush()
+
+
+# P3-07：错误详情里可能夹带绝对路径，回给客户端前做脱敏。
+_PATH_RE = re.compile(r"(?:[A-Za-z]:\\[^\s\"']+|/(?:[^\s/\"']+/)+[^\s\"']*)")
+
+
+def _safe_error_msg(exc: Exception) -> str:
+    """把异常转成可安全返回给 MCP 客户端的短消息：抹掉路径、截断超长文本。"""
+    msg = _PATH_RE.sub("<path>", str(exc))
+    return msg[:200]
+
+
+def _read_message() -> Dict[str, Any]:
+    headers: Dict[str, str] = {}
+    # v5.6.2 安全修复：消息体大小上限（与 REST API 一致，10MB）
+    MAX_CONTENT_LENGTH = 10 * 1024 * 1024
+    while True:
+        line = sys.stdin.buffer.readline()
+        if not line:
+            # P2 #17 补强：stdin 关闭（EOF）直接退出，而不是落入
+            # "无 Content-Length → ValueError → 重试" 的 100% CPU 空转。
+            # 此前把 EOF 与"空头部行"同样当作 break，随后 length<=0 抛
+            # ValueError，serve_forever 会无限重读同一 EOF。
+            raise EOFError("stdin closed")
+        if line in (b"\r\n", b"\n"):
+            break
+        try:
+            decoded = line.decode("ascii", errors="replace").strip()
+        except Exception:
+            continue
+        if ":" in decoded:
+            k, v = decoded.split(":", 1)
+            headers[k.strip().lower()] = v.strip()
+    try:
+        length = int(headers.get("content-length", "0"))
+    except ValueError:
+        length = 0
+    # v5.6.2 安全修复：拒绝超大消息体，防止内存耗尽 DoS
+    if length > MAX_CONTENT_LENGTH:
+        raise ValueError(f"Content-Length {length} exceeds maximum {MAX_CONTENT_LENGTH}")
+    # P2 #17 修复：Content-Length 缺失或 ≤ 0 时直接拒绝，不再用 readline() 试探
+    # （MCP 协议必须有 Content-Length 头，readline 可能读到无限长数据）
+    if length <= 0:
+        raise ValueError("Missing or invalid Content-Length header")
+    raw = sys.stdin.buffer.read(length)
+    if not raw:
+        raise EOFError("stdin closed")
+    # P2 #23 修复：外部输入用安全 JSON 解析（深度限制）
+    try:
+        from mindforge.core.storage import _safe_json_loads
+        return _safe_json_loads(raw.decode("utf-8"))
+    except ImportError:
+        return json.loads(raw.decode("utf-8"))
+
+
+def _write_message(payload: Dict[str, Any]) -> None:
+    body = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
+    sys.stdout.buffer.write(f"Content-Length: {len(body)}\r\n\r\n".encode("ascii"))
+    sys.stdout.buffer.write(body)
+    sys.stdout.buffer.flush()
+
+
+def _respond(request: Dict[str, Any], result: Any) -> None:
+    _write_message({"jsonrpc": "2.0", "id": request.get("id"), "result": result})
+
+
+def _respond_error(request: Dict[str, Any], code: int, message: str, data: Any = None) -> None:
+    body: Dict[str, Any] = {"jsonrpc": "2.0", "id": request.get("id"),
+                            "error": {"code": code, "message": message}}
+    if data is not None:
+        body["error"]["data"] = data
+    _write_message(body)
+
+
+def _notify(method: str, params: Optional[Dict[str, Any]] = None) -> None:
+    msg: Dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+    if params is not None:
+        msg["params"] = params
+    _write_message(msg)
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas — matches MCP tools/list
+# ---------------------------------------------------------------------------
+
+TOOL_SCHEMAS: List[Dict[str, Any]] = [
+    {
+        "name": "memory_add",
+        "description": "Add a new memory entry to MindForge lifelong memory system.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["content"],
+            "properties": {
+                "content": {"type": "string", "description": "记忆正文内容"},
+                "category": {"type": "string", "description": "分类，默认 general"},
+                "tags": {"type": "array", "items": {"type": "string"}, "description": "标签列表"},
+                "importance": {"type": "string", "enum": ["critical", "high", "medium", "low"],
+                              "description": "重要性级别，默认 medium"},
+                "layer": {"type": "string", "enum": ["sensory", "short_term", "long_term", "permanent"],
+                         "description": "记忆层级，默认 short_term"},
+                "agent_id": {"type": "string", "description": "关联 Agent ID（可选）"},
+                "valid_from": {"type": "number", "description": "事实有效起始时间（Unix 秒，v5.7.6；0=无边界）"},
+                "valid_to": {"type": "number", "description": "事实有效截止时间（Unix 秒，v5.7.6；0=仍有效）"},
+            },
+        },
+    },
+    {
+        "name": "memory_supersede",
+        "description": "Bi-temporal 事实取代（v5.7.6）：关闭旧事实有效窗口并创建新事实，旧版本保留在历史中。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["id", "content"],
+            "properties": {
+                "id": {"type": "string", "description": "要取代的旧记忆 ID"},
+                "content": {"type": "string", "description": "新事实内容"},
+                "category": {"type": "string", "description": "新分类（默认继承旧事实）"},
+                "tags": {"type": "array", "items": {"type": "string"}, "description": "新标签（默认继承旧事实）"},
+                "importance": {"type": "string", "enum": ["critical", "high", "medium", "low"],
+                              "description": "新重要性（默认继承旧事实）"},
+                "layer": {"type": "string", "enum": ["sensory", "short_term", "long_term", "permanent"],
+                         "description": "新层级（默认继承旧事实）"},
+                "valid_from": {"type": "number", "description": "新事实有效起始时间（Unix 秒，默认=当前时间）"},
+                "agent_id": {"type": "string", "description": "调用者 Agent ID（写入审计）"},
+            },
+        },
+    },
+    {
+        "name": "memory_valid_at",
+        "description": "按事实有效时间查询（Bi-temporal as-of，v5.7.6）：返回 timestamp 时处于有效窗口的记忆。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "ts": {"type": "number", "description": "Unix 时间戳（默认=当前时间）"},
+                "category": {"type": "string", "description": "按分类过滤"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50},
+                "actor": {"type": "string", "description": "调用者身份（Agent ID），启用隐私过滤"},
+                "session_id": {"type": "string", "description": "调用者会话 ID"},
+            },
+        },
+    },
+    {
+        "name": "memory_agent_pin",
+        "description": "Agent 自主标记关键记忆（v5.7.7）：置顶冻结衰减 + 重置遗忘分，可提升重要度。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+                "id": {"type": "string", "description": "记忆 ID"},
+                "importance": {"type": "string", "enum": ["low", "medium", "high", "critical"],
+                              "description": "提升重要度（可选）"},
+                "agent_id": {"type": "string", "description": "调用者 Agent ID"},
+            },
+        },
+    },
+    {
+        "name": "memory_agent_forget",
+        "description": "Agent 自主遗忘（v5.7.7）：软删除移入回收站（可 restore 恢复），记录原因。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+                "id": {"type": "string", "description": "记忆 ID"},
+                "reason": {"type": "string", "description": "遗忘原因（写入审计）"},
+                "agent_id": {"type": "string", "description": "调用者 Agent ID"},
+            },
+        },
+    },
+    {
+        "name": "memory_agent_decay_boost",
+        "description": "Agent 标记「这条不再重要」（v5.7.7）：提升 forgetting_score 加速遗忘（封顶 10）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["id"],
+            "properties": {
+                "id": {"type": "string", "description": "记忆 ID"},
+                "amount": {"type": "number", "minimum": 0.1, "maximum": 10.0,
+                          "description": "遗忘分增量（默认 1.0）"},
+                "agent_id": {"type": "string", "description": "调用者 Agent ID"},
+            },
+        },
+    },
+    {
+        "name": "memory_connector_ingest",
+        "description": "通过连接器导入数据（v5.7.7）：json / csv / markdown / file / url。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["connector", "source"],
+            "properties": {
+                "connector": {"type": "string",
+                             "description": "连接器名称（json/csv/markdown/file/url）"},
+                "source": {"type": "string", "description": "数据源（文件路径或 URL）"},
+                "category": {"type": "string", "description": "导入分类"},
+                "source_agent": {"type": "string", "description": "来源 Agent 标记"},
+            },
+        },
+    },
+    {
+        "name": "conflict_reconcile",
+        "description": "冲突自动调和（Bi-temporal，v5.7.7）：keep_newer / keep_higher_importance 自动失效旧事实，其余待人工。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "auto": {"type": "boolean", "default": True,
+                        "description": "false 时仅报告不执行"},
+                "memory_ids": {"type": "array", "items": {"type": "string"},
+                              "description": "限定记忆 ID 列表（可选）"},
+            },
+        },
+    },
+    {
+        "name": "memory_search",
+        "description": "Hybrid search: vector recall + TF-IDF + FTS5 + fuzzy (v5.4.5). Set use_embedding=false to disable vector search. Set explain=true for a per-result score breakdown (v6.3.2).",
+        "inputSchema": {
+            "type": "object",
+            "required": ["query"],
+            "properties": {
+                "query": {"type": "string", "description": "搜索查询"},
+                "max_results": {"type": "integer", "minimum": 1, "maximum": 50, "default": 5},
+                "min_relevance": {"type": "number", "minimum": 0.0, "maximum": 1.0, "default": 0.0},
+                "category": {"type": "string", "description": "按分类过滤（可选）"},
+                "agent_id": {"type": "string", "description": "按 Agent ID 过滤（可选）"},
+                "use_embedding": {"type": "boolean", "default": True, "description": "启用向量召回（v5.4.5，默认 true）"},
+                "explain": {"type": "boolean", "default": False, "description": "返回每条结果的得分分解：四路召回各自原始分、胜出路径、文本+向量融合明细（v6.3.2，默认 false 零开销）"},
+            },
+        },
+    },
+    {
+        "name": "memory_list",
+        "description": "分页列出记忆条目，支持按分类/层级/重要性过滤和排序。"
+                       "传入 actor 后会按隐私引擎过滤（仅返回该调用者有权访问的记忆），"
+                       "不传则返回全部（兼容既有客户端）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "category": {"type": "string"},
+                "layer": {"type": "string", "enum": ["sensory", "short_term", "long_term", "permanent"]},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 20},
+                "offset": {"type": "integer", "minimum": 0, "default": 0},
+                "sort_by": {"type": "string", "enum": ["created_at", "updated_at", "importance"],
+                           "default": "created_at"},
+                "actor": {"type": "string",
+                          "description": "调用者身份（Agent ID）。传入后启用隐私过滤，见 F1 方案。"},
+                "session_id": {"type": "string", "description": "调用者会话 ID（配合 actor 使用）"},
+            },
+        },
+    },
+    {
+        "name": "memory_stats",
+        "description": "记忆库统计：总数、分类、层级、重要性、标签数量等。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "memory_importance",
+        "description": "Agent 记忆重要度分析：分布、漂移、低估/高估与重评估建议。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id"],
+            "properties": {"agent_id": {"type": "string"}},
+        },
+    },
+    {
+        "name": "memory_context",
+        "description": "为 LLM Prompt 格式化上下文注入（Token 预算感知）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id", "query"],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "query": {"type": "string"},
+                "token_budget": {"type": "integer", "minimum": 256, "maximum": 128000, "default": 4000},
+            },
+        },
+    },
+    {
+        "name": "agent_emotion",
+        "description": "Agent 情感追踪：每日情感、转换序列、波动性评分。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id"],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "days": {"type": "integer", "minimum": 1, "maximum": 365, "default": 30},
+            },
+        },
+    },
+    {
+        "name": "char_relationship",
+        "description": "短剧角色关系分析：六型分类（ally/rival/romance/family/mentor/stranger）+ 情感弧线 + 强度。需同时提供 char1_id 和 char2_id。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["drama_id"],
+            "properties": {
+                "drama_id": {"type": "string"},
+                "char1_id": {"type": "string", "description": "角色 1 ID（可选，用于特定角色关系分析）"},
+                "char2_id": {"type": "string", "description": "角色 2 ID（可选，用于特定角色关系分析）"},
+            },
+        },
+    },
+    {
+        "name": "drama_genre_trend",
+        "description": "短剧类型趋势：rising / declining / stable + 平均评分。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "drama_binge_score",
+        "description": "短剧追剧粘性评分（节奏/张力/互动/经典/完成率）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["drama_id"],
+            "properties": {"drama_id": {"type": "string"}},
+        },
+    },
+    # ===== v5.4.1 新增六大能力 =====
+    {
+        "name": "memory_reflection",
+        "description": "记忆反思（元认知）：主题分布、情感基调、关键经验、焦点漂移与结构化反思报告。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id"],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "days": {"type": "integer", "minimum": 1, "maximum": 365, "default": 30},
+            },
+        },
+    },
+    {
+        "name": "memory_lineage",
+        "description": "记忆血缘溯源：单条记忆的版本历史、关联链接、审计事件与生命周期时间线。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {"memory_id": {"type": "string"}},
+        },
+    },
+    {
+        "name": "memory_reinforce",
+        "description": "记忆强化候选：识别高价值但正在衰减的记忆，给出强化排序与推荐动作。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id"],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "days": {"type": "integer", "minimum": 1, "maximum": 365, "default": 90},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10},
+            },
+        },
+    },
+    {
+        "name": "drama_plot_thread",
+        "description": "剧情伏笔线索追踪：识别伏笔埋设与回收，输出线索列表、未回收线索与回收率。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["drama_id"],
+            "properties": {"drama_id": {"type": "string"}},
+        },
+    },
+    {
+        "name": "drama_episode_curve",
+        "description": "分集张力曲线：按集聚合张力指标，输出全剧曲线、高潮集、波动率与形态分类。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["drama_id"],
+            "properties": {"drama_id": {"type": "string"}},
+        },
+    },
+    {
+        "name": "drama_screen_time",
+        "description": "角色戏份平衡：角色台词量/字数/出场占比 + 基尼系数 + 独角戏/双核/群像结构判定。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["drama_id"],
+            "properties": {"drama_id": {"type": "string"}},
+        },
+    },
+    # ===== v5.4.2 新增两大能力 =====
+    {
+        "name": "fed_acl_add",
+        "description": "联邦记忆细粒度 ACL：添加规则（主体×资源×操作×allow/deny，支持优先级/信任阈值/过期）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["principal", "resource"],
+            "properties": {
+                "principal": {"type": "string", "description": "peer ID 或 * 表示任意节点"},
+                "resource": {"type": "string", "description": "all / memory:<id> / category:<名> / tag:<名>"},
+                "operations": {"type": "string", "default": "read", "description": "read/write/reshare/*，逗号分隔"},
+                "effect": {"type": "string", "enum": ["allow", "deny"], "default": "allow"},
+                "priority": {"type": "integer", "minimum": 0, "maximum": 10000, "default": 100},
+                "trust_min": {"type": "number", "minimum": 0, "maximum": 1, "default": 0},
+                "expires_hours": {"type": "number", "description": "规则有效时长（小时），缺省永久"},
+                "note": {"type": "string"},
+            },
+        },
+    },
+    {
+        "name": "fed_acl_remove",
+        "description": "联邦记忆细粒度 ACL：删除规则。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["rule_id"],
+            "properties": {"rule_id": {"type": "string"}},
+        },
+    },
+    {
+        "name": "fed_acl_list",
+        "description": "联邦记忆细粒度 ACL：规则列表（可按主体/效果过滤）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "principal": {"type": "string"},
+                "effect": {"type": "string", "enum": ["allow", "deny"]},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 200},
+            },
+        },
+    },
+    {
+        "name": "fed_acl_check",
+        "description": "联邦记忆细粒度 ACL：访问评估（默认拒绝；返回 allowed/effect/reason/matched_rule）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["peer_id", "memory_id"],
+            "properties": {
+                "peer_id": {"type": "string"},
+                "memory_id": {"type": "string"},
+                "operation": {"type": "string", "enum": ["read", "write", "reshare"], "default": "read"},
+                "peer_trust": {"type": "number", "minimum": 0, "maximum": 1},
+                "memory_category": {"type": "string"},
+                "memory_tags": {"type": "array", "items": {"type": "string"}},
+            },
+        },
+    },
+    {
+        "name": "fed_acl_stats",
+        "description": "联邦记忆细粒度 ACL：规则分布与拒绝审计统计。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "share_conflict_list",
+        "description": "共享记忆冲突：冲突记录列表（可按状态过滤 open/resolved/dismissed）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "status": {"type": "string", "enum": ["open", "resolved", "dismissed"]},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50},
+            },
+        },
+    },
+    {
+        "name": "share_conflict_resolve",
+        "description": "共享记忆冲突：按策略解决 open 冲突（lww=版本+时间戳决胜覆盖；keep_both=另存分支并关联）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["conflict_id", "strategy"],
+            "properties": {
+                "conflict_id": {"type": "string"},
+                "strategy": {"type": "string", "enum": ["lww", "keep_both"]},
+                "actor": {"type": "string"},
+            },
+        },
+    },
+    {
+        "name": "share_conflict_dismiss",
+        "description": "共享记忆冲突：人工关闭 open 冲突（判定无需处理）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["conflict_id"],
+            "properties": {
+                "conflict_id": {"type": "string"},
+                "actor": {"type": "string"},
+            },
+        },
+    },
+    {
+        "name": "share_conflict_stats",
+        "description": "共享记忆冲突：冲突态势统计（按状态/类型/解决方式）。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    # ===== v5.3.9 新增五大能力 =====
+    {
+        "name": "intent_router",
+        "description": "意图分类路由（规则正则→关键词加权→LLM 兜底）。返回 intent / label / confidence / routing_target。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["text"],
+            "properties": {
+                "text": {"type": "string", "description": "要分类的文本"},
+                "force": {"type": "string", "description": "强制指定意图 ID（debug 用）"},
+            },
+        },
+    },
+    {
+        "name": "conflict_scan",
+        "description": "记忆矛盾扫描：反义词对 / 属性值不一致 / 时间线冲突，并可自动衰减（降重要性 + 打标签）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "category": {"type": "string", "description": "只扫描指定分类"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 5000, "default": 500},
+                "apply_decay": {"type": "boolean", "default": False,
+                                "description": "若 true，直接写入衰减动作"},
+            },
+        },
+    },
+    {
+        "name": "skill_extract",
+        "description": "从记忆中抽取可复用的技能模板（聚类→槽位→步骤→触发词）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "category": {"type": "string"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 2000},
+                "min_cluster_size": {"type": "integer", "minimum": 1, "default": 2},
+            },
+        },
+    },
+    {
+        "name": "rerank_search",
+        "description": "混合检索增强：同义词/上位词查询扩展 + 三路召回 + Cross-Encoder 重排。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["query"],
+            "properties": {
+                "query": {"type": "string"},
+                "max_results": {"type": "integer", "minimum": 1, "maximum": 50, "default": 10},
+                "expand": {"type": "boolean", "default": True},
+                "rerank": {"type": "boolean", "default": True},
+            },
+        },
+    },
+    {
+        "name": "session_focus",
+        "description": "会话焦点分析：主题聚类、焦点词、漂移检测、可生成增强查询。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["messages"],
+            "properties": {
+                "messages": {
+                    "type": "array",
+                    "description": '每条为 {"id","role","content","timestamp?"} 或 {"role":"user","content":"..."}',
+                    "items": {"type": "object"},
+                },
+                "window_size": {"type": "integer", "minimum": 5, "maximum": 400, "default": 40},
+                "augment_query": {"type": "string", "description": "若提供，生成带焦点的增强查询"},
+            },
+        },
+    },
+    # v5.4.5 新增向量检索工具
+    {
+        "name": "rebuild_embeddings",
+        "description": "重建所有记忆的嵌入向量（需安装 sentence-transformers）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "batch_size": {"type": "integer", "minimum": 1, "maximum": 1000, "default": 100},
+            },
+        },
+    },
+    {
+        "name": "embedding_status",
+        "description": "查看嵌入向量引擎状态：是否可用、模型名、维度、向量数量。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "memory_diff",
+        "description": "对比两个记忆版本的差异（v5.5.8 新增）。返回内容、分类、标签和重要度的结构化差异报告。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["version_a", "version_b"],
+            "properties": {
+                "version_a": {"type": "string", "description": "版本 A 的 ID"},
+                "version_b": {"type": "string", "description": "版本 B 的 ID"},
+            },
+        },
+    },
+    {
+        "name": "memory_graph_stats",
+        "description": "知识图谱统计（v5.7.9）：实体/关系总数与类型分布。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "memory_graph_related",
+        "description": "查询与指定实体相关的实体（BFS，v5.7.9）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["entity"],
+            "properties": {
+                "entity": {"type": "string", "description": "实体名称"},
+                "depth": {"type": "integer", "minimum": 1, "maximum": 5, "default": 2, "description": "BFS 深度"},
+                "max_results": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "返回上限"},
+            },
+        },
+    },
+    {
+        "name": "memory_graph_extract",
+        "description": "触发知识图谱抽取（v5.7.9）：指定记忆 ID 或全库增量（同进程防抖，STRICT 隐私跳过）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "memory_id": {"type": "string", "description": "指定记忆 ID（缺省=全库增量）"},
+            },
+        },
+    },
+    {
+        "name": "memory_experience_record",
+        "description": "记录一次任务经验（v5.8.0）：Agent 把成功任务存为 Case，供后续蒸馏为可复用技能。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["task"],
+            "properties": {
+                "task": {"type": "string", "description": "任务描述"},
+                "content": {"type": "string", "description": "过程/步骤内容"},
+                "result": {"type": "string", "description": "结果"},
+                "outcome": {"type": "string", "enum": ["success", "partial", "failure"], "default": "success"},
+                "duration_seconds": {"type": "number", "description": "耗时秒"},
+                "tags": {"type": "array", "items": {"type": "string"}, "description": "标签"},
+                "source_memory_ids": {"type": "array", "items": {"type": "string"}, "description": "来源记忆 ID"},
+                "agent_id": {"type": "string", "description": "Agent ID（写入审计）"},
+            },
+        },
+    },
+    {
+        "name": "memory_skill_distill",
+        "description": "从成功案例蒸馏技能模板并持久化（v5.8.0）。",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "min_cluster_size": {"type": "integer", "minimum": 1, "maximum": 20, "default": 2},
+                "max_skills": {"type": "integer", "minimum": 1, "maximum": 500, "default": 50},
+            },
+        },
+    },
+    {
+        "name": "memory_skill_match",
+        "description": "按新任务匹配已存技能（v5.8.0，触发词/标签/bigram 三重评分）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["query"],
+            "properties": {
+                "query": {"type": "string", "description": "任务描述/查询"},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 5},
+            },
+        },
+    },
+    {
+        "name": "memory_skill_render",
+        "description": "用参数渲染技能为可执行流程（v5.8.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["name"],
+            "properties": {
+                "name": {"type": "string", "description": "技能名"},
+                "params": {"type": "object", "description": "槽位参数 key=value 映射"},
+            },
+        },
+    },
+    {
+        "name": "memory_skill_stats",
+        "description": "经验统计（v5.8.0）：案例数/技能数/结果分布。",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "fed_peer_register",
+        "description": "注册联邦对等节点（v5.8.6）。Ed25519 签名+防重放。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["peer_id", "name"],
+            "properties": {
+                "peer_id": {"type": "string"},
+                "name": {"type": "string"},
+                "trust_level": {"type": "number"},
+                "shared_categories": {"type": "array", "items": {"type": "string"}}
+            }
+        },
+    },
+    {
+        "name": "fed_peer_remove",
+        "description": "移除联邦对等节点（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["peer_id"],
+            "properties": {
+                "peer_id": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "fed_peer_list",
+        "description": "列出联邦对等节点及状态（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {}
+        },
+    },
+    {
+        "name": "fed_memory_share",
+        "description": "把记忆共享给一组对等节点（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id", "peer_ids"],
+            "properties": {
+                "memory_id": {"type": "string"},
+                "peer_ids": {"type": "array", "items": {"type": "string"}},
+                "access_policy": {"type": "string"},
+                "expires_hours": {"type": "number"}
+            }
+        },
+    },
+    {
+        "name": "fed_memory_revoke",
+        "description": "撤销记忆的联邦共享（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {
+                "memory_id": {"type": "string"},
+                "peer_ids": {"type": "array", "items": {"type": "string"}}
+            }
+        },
+    },
+    {
+        "name": "fed_memory_list_shared",
+        "description": "列出已共享的记忆（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {
+                "peer_id": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "fed_search",
+        "description": "跨联邦节点检索记忆（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["query"],
+            "properties": {
+                "query": {"type": "string"},
+                "peer_ids": {"type": "array", "items": {"type": "string"}},
+                "max_per_peer": {"type": "integer"}
+            }
+        },
+    },
+    {
+        "name": "fed_stats",
+        "description": "联邦共享统计（v5.8.6）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {}
+        },
+    },
+    # ---- v6.0.0 功能 1-8 ----
+    {
+        "name": "chat_import",
+        "description": "功能 1：一键导入记忆（ChatGPT/Claude 对话导出，v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["data"],
+            "properties": {
+                "data": {"type": "object", "description": "ChatGPT/Claude 导出 JSON"},
+                "dry_run": {"type": "boolean"}
+            }
+        },
+    },
+    {
+        "name": "timeline_viz",
+        "description": "功能 2：记忆时间线可视化（聚合统计，不含明文，v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {
+                "category": {"type": "string"},
+                "days": {"type": "integer"}
+            }
+        },
+    },
+    {
+        "name": "skill_pack_export",
+        "description": "功能 3：导出可分享技能包（v6.0.0）。",
+        "inputSchema": {"type": "object", "required": [], "properties": {}},
+    },
+    {
+        "name": "skill_pack_import",
+        "description": "功能 3：导入技能包（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["pack"],
+            "properties": {
+                "pack": {"type": "object"},
+                "mode": {"type": "string", "enum": ["merge", "replace"]}
+            }
+        },
+    },
+    {
+        "name": "memory_evolve",
+        "description": "功能 4：记忆演变（保留旧版本 + 记录原因，v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {
+                "memory_id": {"type": "string"},
+                "content": {"type": "string"},
+                "category": {"type": "string"},
+                "reason": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "memory_evolution_history",
+        "description": "功能 4：记忆演变历史（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {"memory_id": {"type": "string"}, "limit": {"type": "integer"}}
+        },
+    },
+    {
+        "name": "memory_learn_outcome",
+        "description": "功能 5：按结果学习的记忆（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {
+                "memory_id": {"type": "string"},
+                "outcome": {"type": "string", "enum": ["success", "partial", "failure"]},
+                "note": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "passport_export",
+        "description": "功能 6：导出记忆护照（跨模型迁移，v6.0.0）。",
+        "inputSchema": {"type": "object", "required": [], "properties": {}},
+    },
+    {
+        "name": "passport_import",
+        "description": "功能 6：导入记忆护照（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["passport"],
+            "properties": {
+                "passport": {"type": "object"},
+                "mode": {"type": "string", "enum": ["merge", "replace"]}
+            }
+        },
+    },
+    {
+        "name": "passport_revoke",
+        "description": "功能 6：撤销记忆护照导入（可逆，v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["passport_id"],
+            "properties": {"passport_id": {"type": "string"}}
+        },
+    },
+    {
+        "name": "forget_explain",
+        "description": "功能 7：解释记忆的遗忘原因（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {"memory_id": {"type": "string"}}
+        },
+    },
+    {
+        "name": "forget_run",
+        "description": ("功能 7：执行有原则遗忘 GC（v6.0.0）。"
+                        "v6.1.2：days 为冷却窗口，创建不足 days 天的记忆不归档，"
+                        "0 表示关闭冷却。"),
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {
+                "dry_run": {"type": "boolean"},
+                "days": {"type": "integer",
+                         "description": "冷却天数（默认 30，0 = 不过滤新记忆）"}
+            }
+        },
+    },
+    {
+        "name": "follow_up_create",
+        "description": "功能 8：登记跟进事项（主动收尾，v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {
+                "memory_id": {"type": "string"},
+                "note": {"type": "string"},
+                "due_at": {"type": "number"}
+            }
+        },
+    },
+    {
+        "name": "follow_up_due",
+        "description": "功能 8：查询到期未办结跟进（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {"limit": {"type": "integer"}}
+        },
+    },
+    {
+        "name": "follow_up_resolve",
+        "description": "功能 8：办结跟进事项（v6.0.0）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["follow_up_id"],
+            "properties": {"follow_up_id": {"type": "string"}}
+        },
+    },
+    {
+        "name": "follow_up_nag",
+        "description": "功能 8：主动催办到期未办结跟进并生成回执（v6.1.1）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {
+                "interval_hours": {"type": "number"},
+                "max_nags": {"type": "integer"}
+            }
+        },
+    },
+    # ---- v6.0.0 正式版：v6 端口总览 ----
+    {
+        "name": "v6_status",
+        "description": "v6.0.0 正式版：查看 v6 端口总览（多 Agent 协作 + 6G AI 记忆预览）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {}
+        },
+    },
+    # ---- v6.0.0 正式版：多 Agent 记忆空间 ----
+    {
+        "name": "space_create",
+        "description": "v6.0.0 正式版：创建多 Agent 共享记忆空间（owner 自动加入）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["name", "owner_agent"],
+            "properties": {
+                "name": {"type": "string"},
+                "owner_agent": {"type": "string"},
+                "description": {"type": "string"},
+                "policy": {"type": "string", "enum": ["shared", "restricted"], "default": "shared"}
+            }
+        },
+    },
+    {
+        "name": "space_list",
+        "description": "v6.0.0 正式版：列出多 Agent 记忆空间（可只看我加入的）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "mine": {"type": "boolean", "default": False}
+            }
+        },
+    },
+    {
+        "name": "space_join",
+        "description": "v6.0.0 正式版：以 reader 身份加入多 Agent 记忆空间。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["space", "agent_id"],
+            "properties": {
+                "space": {"type": "string"},
+                "agent_id": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "space_add_member",
+        "description": "v6.0.0 正式版：向空间添加成员并分配角色（仅 owner，editor/reader）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["space", "member_agent", "actor"],
+            "properties": {
+                "space": {"type": "string"},
+                "member_agent": {"type": "string"},
+                "role": {"type": "string", "enum": ["editor", "reader"], "default": "reader"},
+                "actor": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "space_share",
+        "description": "v6.0.0 正式版：把记忆共享进多 Agent 空间（PRIVATE/STRICT 禁止）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["space", "memory_id", "actor"],
+            "properties": {
+                "space": {"type": "string"},
+                "memory_id": {"type": "string"},
+                "actor": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "space_memories",
+        "description": "v6.0.0 正式版：列出空间中的共享记忆。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["space", "actor"],
+            "properties": {
+                "space": {"type": "string"},
+                "actor": {"type": "string"},
+                "limit": {"type": "integer", "default": 50}
+            }
+        },
+    },
+    {
+        "name": "space_stats",
+        "description": "v6.0.0 正式版：多 Agent 记忆空间统计（单空间或全局）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {"space": {"type": "string"}}
+        },
+    },
+    # ---- v6.0.0 正式版：6G AI 记忆预览 ----
+    {
+        "name": "preview_open",
+        "description": "6G：开启预览通道（与稳定版并行、互不污染，独立 SQLite 预览库）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {"config": {"type": "object"}}
+        },
+    },
+    {
+        "name": "preview_close",
+        "description": ("6G：关闭并清理预览通道。"
+                        "v6.1.2：purge=false 时只标记关闭、保留独立预览库文件。"),
+        "inputSchema": {
+            "type": "object",
+            "required": ["channel_id"],
+            "properties": {
+                "channel_id": {"type": "string"},
+                "purge": {"type": "boolean",
+                          "description": "是否删除独立库文件（默认 true）"}
+            }
+        },
+    },
+    {
+        "name": "preview_channels",
+        "description": "6G：列出预览通道。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {"include_closed": {"type": "boolean", "default": False}}
+        },
+    },
+    {
+        "name": "preview_snapshot",
+        "description": "6G：把主库记忆快照进预览通道（不修改主库）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["channel_id", "memory_id"],
+            "properties": {
+                "channel_id": {"type": "string"},
+                "memory_id": {"type": "string"}
+            }
+        },
+    },
+    {
+        "name": "preview_distill",
+        "description": "6G：上下文蒸馏（分层摘要 HIGH 保留全文 + Token 压缩）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_ids"],
+            "properties": {
+                "memory_ids": {"type": "array", "items": {"type": "string"}},
+                "max_tokens": {"type": "integer", "default": 2000}
+            }
+        },
+    },
+    {
+        "name": "preview_index",
+        "description": "6G：增量索引统计（写入即索引的近实时召回指标）。",
+        "inputSchema": {
+            "type": "object",
+            "required": [],
+            "properties": {}
+        },
+    },
+    {
+        "name": "preview_timeline",
+        "description": "6G：单记忆时间线（版本历史 + 演变记录 + 审计足迹）。",
+        "inputSchema": {
+            "type": "object",
+            "required": ["memory_id"],
+            "properties": {"memory_id": {"type": "string"}}
+        },
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Enum helpers
+# ---------------------------------------------------------------------------
+
+def _to_importance(s: Optional[str], default):
+    from mindforge import Importance
+    if not s:
+        return default
+    return Importance.from_string(s)
+
+
+def _to_layer(s: Optional[str], default):
+    from mindforge import MemoryLayer
+    if not s:
+        return default
+    return MemoryLayer.from_string(s)
+
+
+def _to_list_str(v) -> List[str]:
+    if v is None:
+        return []
+    if isinstance(v, str):
+        return [t.strip() for t in v.split(",") if t.strip()]
+    return [str(x) for x in v]
+
+
+# v5.5.8: 必需参数校验装饰器
+def _require_args(args: Dict[str, Any], *required: str) -> Optional[Dict[str, Any]]:
+    """检查必需参数是否存在，返回 error dict 或 None（校验通过）"""
+    missing = [k for k in required if k not in args or args[k] is None or args[k] == ""]
+    if missing:
+        return {"ok": False, "error": f"Missing required parameter(s): {', '.join(missing)}"}
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Serialization helpers
+# ---------------------------------------------------------------------------
+
+def _safe_int(v: Any, default: int = 0, lo: Optional[int] = None, hi: Optional[int] = None) -> int:
+    """Safely coerce arbitrary input to int, with optional range clamping.
+
+    Returns *default* for None / empty / non-numeric strings instead of raising.
+    """
+    if v is None or v == "":
+        return default
+    try:
+        iv = int(v)
+    except (ValueError, TypeError):
+        return default
+    if lo is not None and iv < lo:
+        iv = lo
+    if hi is not None and iv > hi:
+        iv = hi
+    return iv
+
+
+def _safe_float(v: Any, default: float = 0.0, lo: Optional[float] = None, hi: Optional[float] = None) -> float:
+    """Safely coerce arbitrary input to float, with optional range clamping.
+
+    v5.6.2 安全修复：拒绝 inf/nan 等非法值，防止异常输入直达底层。
+    """
+    if v is None or v == "":
+        return default
+    try:
+        fv = float(v)
+    except (ValueError, TypeError):
+        return default
+    import math
+    if math.isnan(fv) or math.isinf(fv):
+        return default
+    if lo is not None and fv < lo:
+        fv = lo
+    if hi is not None and fv > hi:
+        fv = hi
+    return fv
+
+
+def _clean(v: Any) -> Any:
+    if isinstance(v, dict):
+        return {str(k): _clean(x) for k, x in v.items()}
+    if isinstance(v, (list, tuple, set)):
+        return [_clean(x) for x in v]
+    if hasattr(v, "isoformat"):
+        try:
+            return v.isoformat()
+        except Exception:
+            return str(v)
+    if hasattr(v, "value"):
+        return str(v.value)
+    return v
+
+
+def _entry_to_dict(m) -> Dict[str, Any]:
+    d: Dict[str, Any] = {
+        "id": str(m.id),
+        "content": str(m.content),
+        "category": str(m.category),
+        "tags": list(m.tags) if m.tags else [],
+        "importance": _clean(m.importance),
+        "layer": _clean(m.layer),
+        "agent_id": str(getattr(m, "source_agent", "") or ""),
+        "created_at": None,
+        "updated_at": None,
+        "starred": bool(getattr(m, "starred", False)),
+        "pinned": bool(getattr(m, "pinned", False)),
+    }
+    ca = getattr(m, "created_at", None)
+    ua = getattr(m, "updated_at", None)
+    if ca is not None:
+        try:
+            d["created_at"] = ca.isoformat()
+        except Exception:
+            d["created_at"] = str(ca)
+    if ua is not None:
+        try:
+            d["updated_at"] = ua.isoformat()
+        except Exception:
+            d["updated_at"] = str(ua)
+    return d
+
+
+# ---------------------------------------------------------------------------
+# Tool handlers
+# ---------------------------------------------------------------------------
+
+def h_memory_add(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    from mindforge import Importance, MemoryLayer, PrivacyLevel
+    err = _require_args(args, "content")
+    if err:
+        return err
+    try:
+        entry = mf.add(
+            content=str(args["content"]),
+            category=args.get("category") or "general",
+            tags=_to_list_str(args.get("tags")),
+            importance=_to_importance(args.get("importance"), Importance.MEDIUM),
+            layer=_to_layer(args.get("layer"), MemoryLayer.SHORT_TERM),
+            privacy=PrivacyLevel.INTERNAL,
+            source_agent=args.get("agent_id") or "",
+            valid_from=_safe_float(args.get("valid_from"), 0.0, 0.0),
+            valid_to=_safe_float(args.get("valid_to"), 0.0, 0.0),
+        )
+        return {"ok": True, "memory": _entry_to_dict(entry)}
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_memory_search(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "query")
+    if err:
+        return err
+    categories = [args["category"]] if args.get("category") else None
+    use_emb = args.get("use_embedding", True)
+    if not isinstance(use_emb, bool):
+        use_emb = True
+    # v6.3.2: explain 透传（默认 False 零开销；True 时每条结果携带得分分解）
+    explain = args.get("explain", False)
+    if not isinstance(explain, bool):
+        explain = False
+    res = mf.search(
+        query=str(args["query"]),
+        max_results=_safe_int(args.get("max_results", 5), 5, 1, 100),
+        min_relevance=_safe_float(args.get("min_relevance", 0.0), 0.0, 0.0, 1.0),
+        categories=categories,
+        agent_id=args.get("agent_id") or "",
+        use_embedding=use_emb,
+        explain=explain,
+    )
+    items = []
+    for c in res.chunks:
+        item = {
+            "relevance_score": float(c.relevance_score),
+            "memory_id": str(c.memory_id),
+            "content": str(c.content),
+            "category": str(c.category),
+            "tags": list(getattr(c, "tags", None) or []),
+            "layer": _clean(getattr(c, "layer", None)),
+        }
+        # v6.3.2: 仅 explain=true 时携带（不请求则响应形状与旧版完全一致）
+        if explain:
+            item["score_breakdown"] = getattr(c, "score_breakdown", None)
+        items.append(item)
+    return {"count": len(items), "results": items}
+
+
+def h_memory_list(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    entries = mf.list(
+        category=args.get("category") or None,
+        layer=_to_layer(args.get("layer"), None),
+        limit=_safe_int(args.get("limit", 20), 20, 1, 10000),
+        offset=_safe_int(args.get("offset", 0), 0, 0),
+        sort_by=str(args.get("sort_by", "created_at")),
+        # F1 修复：MCP 列表入口接入隐私过滤。传了 actor 才过滤，
+        # 未传时保持原有"返回全部"语义（兼容既有客户端）。
+        actor=str(args.get("actor") or ""),
+        session_id=str(args.get("session_id") or ""),
+    )
+    return {"count": len(entries), "results": [_entry_to_dict(e) for e in entries]}
+
+
+def h_memory_stats(mf, _args: Dict[str, Any]) -> Dict[str, Any]:
+    s = mf.stats()
+    return _clean(s)
+
+
+def h_memory_importance(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "agent_id")
+    if err:
+        return err
+    agent_id = str(args["agent_id"])
+    return {"agent_id": agent_id, "result": _clean(mf.storage.memory_importance(agent_id))}
+
+
+def h_memory_context(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "agent_id", "query")
+    if err:
+        return err
+    agent_id = str(args["agent_id"])
+    query = str(args["query"])
+    token_budget = _safe_int(args.get("token_budget", 4000), 4000, 256, 128000)
+    return {
+        "agent_id": agent_id,
+        "query": query,
+        "token_budget": token_budget,
+        "result": _clean(mf.storage.memory_context(agent_id, query, max_tokens=token_budget)),
+    }
+
+
+def h_agent_emotion(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "agent_id")
+    if err:
+        return err
+    agent_id = str(args["agent_id"])
+    days = _safe_int(args.get("days", 30), 30, 1, 3650)
+    return {"agent_id": agent_id, "days": days,
+            "result": _clean(mf.storage.agent_emotion(agent_id, days=days))}
+
+
+def h_char_relationship(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "drama_id")
+    if err:
+        return err
+    drama_id = str(args["drama_id"])
+    char1_id = str(args.get("char1_id") or "")
+    char2_id = str(args.get("char2_id") or "")
+    if not char1_id or not char2_id:
+        return {
+            "drama_id": drama_id,
+            "error": "char_relationship 需要同时提供 char1_id 和 char2_id",
+            "hint": "传 char1_id + char2_id 可分析特定角色关系；仅传 drama_id 不足以完成分析",
+        }
+    result = mf.storage.char_relationship(drama_id, char1_id, char2_id)
+    return {"drama_id": drama_id, "char1_id": char1_id, "char2_id": char2_id,
+            "result": _clean(result)}
+
+
+def h_drama_genre_trend(mf, _args: Dict[str, Any]) -> Dict[str, Any]:
+    return {"result": _clean(mf.storage.drama_genre_trend())}
+
+
+def h_drama_binge_score(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "drama_id")
+    if err:
+        return err
+    drama_id = str(args["drama_id"])
+    return {"drama_id": drama_id, "result": _clean(mf.storage.drama_binge_score(drama_id))}
+
+
+# ===== v5.4.1 六大能力 MCP handlers =====
+
+def h_memory_reflection(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "agent_id")
+    if err:
+        return err
+    agent_id = str(args["agent_id"])
+    days = _safe_int(args.get("days", 30), 30, 1, 365)
+    return {"agent_id": agent_id, "days": days,
+            "result": _clean(mf.storage.memory_reflection(agent_id, days))}
+
+
+def h_memory_lineage(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    memory_id = str(args["memory_id"])
+    return {"memory_id": memory_id,
+            "result": _clean(mf.storage.memory_lineage(memory_id))}
+
+
+def h_memory_reinforce(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "agent_id")
+    if err:
+        return err
+    agent_id = str(args["agent_id"])
+    days = _safe_int(args.get("days", 90), 90, 1, 365)
+    limit = _safe_int(args.get("limit", 10), 10, 1, 50)
+    return {"agent_id": agent_id, "days": days, "limit": limit,
+            "result": _clean(mf.storage.memory_reinforce(agent_id, days, limit))}
+
+
+def h_drama_plot_thread(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "drama_id")
+    if err:
+        return err
+    drama_id = str(args["drama_id"])
+    return {"drama_id": drama_id, "result": _clean(mf.storage.drama_plot_thread(drama_id))}
+
+
+def h_drama_episode_curve(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "drama_id")
+    if err:
+        return err
+    drama_id = str(args["drama_id"])
+    return {"drama_id": drama_id, "result": _clean(mf.storage.drama_episode_curve(drama_id))}
+
+
+def h_drama_screen_time(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "drama_id")
+    if err:
+        return err
+    drama_id = str(args["drama_id"])
+    return {"drama_id": drama_id, "result": _clean(mf.storage.drama_screen_time(drama_id))}
+
+
+# ===== v5.4.2 两大能力 MCP handlers =====
+
+def h_fed_acl_add(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "principal", "resource")
+    if err:
+        return err
+    expires_hours = args.get("expires_hours")
+    try:
+        expires_hours = float(expires_hours) if expires_hours is not None else None
+    except (TypeError, ValueError):
+        expires_hours = None
+    result = mf.federated_acl.add_rule(
+        principal=str(args["principal"]),
+        resource=str(args["resource"]),
+        operations=str(args.get("operations", "read")),
+        effect=str(args.get("effect", "allow")),
+        priority=_safe_int(args.get("priority", 100), 100, 0, 10000),
+        trust_min=float(args.get("trust_min", 0.0) or 0.0),
+        expires_hours=expires_hours,
+        note=str(args.get("note", "")))
+    return _clean(result)
+
+
+def h_fed_acl_remove(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "rule_id")
+    if err:
+        return err
+    return _clean(mf.federated_acl.remove_rule(str(args["rule_id"])))
+
+
+def h_fed_acl_list(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    rules = mf.federated_acl.list_rules(
+        principal=args.get("principal"),
+        effect=args.get("effect"),
+        limit=_safe_int(args.get("limit", 200), 200, 1, 1000))
+    return {"count": len(rules), "rules": _clean(rules)}
+
+
+def h_fed_acl_check(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "peer_id", "memory_id")
+    if err:
+        return err
+    peer_trust = args.get("peer_trust")
+    try:
+        peer_trust = float(peer_trust) if peer_trust is not None else None
+    except (TypeError, ValueError):
+        peer_trust = None
+    tags = args.get("memory_tags") or []
+    if isinstance(tags, str):
+        tags = [tags]
+    result = mf.federated_acl.check_access(
+        peer_id=str(args["peer_id"]),
+        memory_id=str(args["memory_id"]),
+        operation=str(args.get("operation", "read")),
+        peer_trust=peer_trust,
+        memory_category=args.get("memory_category"),
+        memory_tags=[str(t) for t in tags])
+    return _clean(result)
+
+
+def h_fed_acl_stats(mf, _args: Dict[str, Any]) -> Dict[str, Any]:
+    return _clean(mf.federated_acl.acl_stats())
+
+
+def h_share_conflict_list(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    conflicts = mf.share_conflict.list_conflicts(
+        status=args.get("status"),
+        limit=_safe_int(args.get("limit", 50), 50, 1, 500))
+    return {"count": len(conflicts), "conflicts": _clean(conflicts)}
+
+
+def h_share_conflict_resolve(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "conflict_id", "strategy")
+    if err:
+        return err
+    return _clean(mf.share_conflict.resolve(
+        str(args["conflict_id"]), str(args["strategy"]),
+        actor=str(args.get("actor", ""))))
+
+
+def h_share_conflict_dismiss(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "conflict_id")
+    if err:
+        return err
+    return _clean(mf.share_conflict.dismiss(
+        str(args["conflict_id"]), actor=str(args.get("actor", ""))))
+
+
+def h_share_conflict_stats(mf, _args: Dict[str, Any]) -> Dict[str, Any]:
+    return _clean(mf.share_conflict.stats())
+
+
+# ===== v5.3.9 五大能力 MCP handlers =====
+
+def h_intent_router(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "text")
+    if err:
+        return err
+    result = mf.classify_intent(str(args["text"]), force=args.get("force"))
+    return _clean(result)
+
+
+def h_conflict_scan(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    return _clean(mf.scan_conflicts(
+        category=args.get("category"),
+        limit=_safe_int(args.get("limit", 500), 500, 1, 5000),
+        apply_decay=bool(args.get("apply_decay", False)),
+    ))
+
+
+def h_skill_extract(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    return _clean(mf.extract_skills(
+        category=args.get("category"),
+        limit=_safe_int(args.get("limit", 2000), 2000, 1, 50000),
+        min_cluster_size=max(1, _safe_int(args.get("min_cluster_size", 2), 2, 1, 100)),
+    ))
+
+
+def h_rerank_search(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "query")
+    if err:
+        return err
+    return _clean(mf.search_enhanced(
+        query=str(args["query"]),
+        max_results=min(50, max(1, _safe_int(args.get("max_results", 10), 10, 1, 50))),
+        expand=bool(args.get("expand", True)),
+        rerank=bool(args.get("rerank", True)),
+    ))
+
+
+def h_session_focus(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    raw_msgs = args.get("messages") or []
+    msgs: List[Dict[str, Any]] = []
+    for i, m in enumerate(raw_msgs, 1):
+        if not isinstance(m, dict):
+            continue
+        msgs.append({
+            "id": str(m.get("id") or f"m{i}"),
+            "role": str(m.get("role") or "user").lower(),
+            "content": str(m.get("content") or ""),
+            "timestamp": float(m.get("timestamp") or i),
+        })
+    return _clean(mf.session_focus(
+        msgs,
+        window_size=max(5, _safe_int(args.get("window_size", 40), 40, 5, 500)),
+        augment_query=args.get("augment_query"),
+    ))
+
+
+def h_rebuild_embeddings(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    batch_size = _safe_int(args.get("batch_size", 100), 100, 1, 1000)
+    return _clean(mf.rebuild_embeddings(batch_size=batch_size))
+
+
+def h_embedding_status(mf, _args: Dict[str, Any]) -> Dict[str, Any]:
+    return _clean(mf.get_embedding_status())
+
+
+def h_memory_diff(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "version_a", "version_b")
+    if err:
+        return err
+    return _clean(mf.memory_diff(
+        str(args["version_a"]),
+        str(args["version_b"]),
+    ))
+
+
+def h_memory_supersede(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    err = _require_args(args, "id", "content")
+    if err:
+        return err
+    try:
+        new_id = mf.supersede(
+            entry_id=str(args["id"]),
+            content=str(args["content"]),
+            category=args.get("category"),
+            tags=_to_list_str(args["tags"]) if args.get("tags") else None,
+            importance=_to_importance(args["importance"], None) if args.get("importance") else None,
+            layer=_to_layer(args["layer"], None) if args.get("layer") else None,
+            actor=args.get("agent_id") or "",
+            valid_from=_safe_float(args.get("valid_from"), 0.0, 0.0) or None,
+        )
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+    if not new_id:
+        return {"ok": False, "error": "memory not found or not accessible"}
+    return {"ok": True, "new_id": new_id}
+
+
+def h_memory_valid_at(mf, args: Dict[str, Any]) -> Dict[str, Any]:
+    ts_raw = args.get("ts")
+    ts_v = None if ts_raw is None else _safe_float(ts_raw, 0.0, 0.0)
+    entries = mf.valid_at(
+        timestamp=ts_v,
+        category=args.get("category"),
+        limit=_safe_int(args.get("limit", 50), 50, 1, 500),
+        actor=args.get("actor") or "",
+        session_id=args.get("session_id") or "",
+    )
+    return {
+        "as_of": ts_v,
+        "total": len(entries),
+        "memories": [_entry_to_dict(e) for e in entries],
+    }
+
+
+def h_memory_agent_pin(mf, args):
+    err = _require_args(args, "id")
+    if err:
+        return err
+    try:
+        ok = mf.agent_pin(str(args["id"]), importance=args.get("importance"),
+                          actor=args.get("agent_id") or "")
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+    return {"ok": ok}
+
+
+def h_memory_agent_forget(mf, args):
+    err = _require_args(args, "id")
+    if err:
+        return err
+    try:
+        ok = mf.agent_forget(str(args["id"]), reason=args.get("reason") or "",
+                             actor=args.get("agent_id") or "")
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+    return {"ok": ok}
+
+
+def h_memory_agent_decay_boost(mf, args):
+    err = _require_args(args, "id")
+    if err:
+        return err
+    try:
+        ok = mf.agent_decay_boost(
+            str(args["id"]),
+            amount=_safe_float(args.get("amount", 1.0), 1.0, 0.1, 10.0),
+            actor=args.get("agent_id") or "")
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+    return {"ok": ok}
+
+
+def h_memory_connector_ingest(mf, args):
+    err = _require_args(args, "connector", "source")
+    if err:
+        return err
+    try:
+        stats = mf.connector_ingest(
+            str(args["connector"]), str(args["source"]),
+            category=args.get("category"),
+            source_agent=args.get("source_agent") or "connector")
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+    return {"ok": True, "stats": stats}
+
+
+def h_experience_record(mf, args):
+    err = _require_args(args, "task")
+    if err:
+        return err
+    try:
+        case = mf.record_experience(
+            task=str(args["task"]), content=args.get("content", ""),
+            result=args.get("result", ""),
+            outcome=str(args.get("outcome", "success") or "success"),
+            duration_seconds=float(args.get("duration_seconds", 0.0) or 0.0),
+            tags=args.get("tags"), source_memory_ids=args.get("source_memory_ids"),
+            agent_id=str(args.get("agent_id", "") or ""))
+        return {"ok": True, "case": case}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_chat_import(mf, args):
+    data = args.get("data")
+    if not isinstance(data, dict):
+        return {"ok": False, "error": "Field 'data' must be an object"}
+    try:
+        return {"ok": True, **mf.import_chat_history(
+            data, dry_run=bool(args.get("dry_run", False)))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_timeline_viz(mf, args):
+    try:
+        return {"ok": True, **mf.timeline_visual(
+            category=args.get("category") or None,
+            days=int(args.get("days", 365) or 365))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_skill_pack_export(mf, _args):
+    try:
+        return {"ok": True, **mf.skill_pack_export()}
+    except Exception as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_skill_pack_import(mf, args):
+    pack = args.get("pack")
+    if not isinstance(pack, dict):
+        return {"ok": False, "error": "Field 'pack' must be an object"}
+    try:
+        v = mf.skill_pack_validate(pack)
+        if not v.get("valid"):
+            return {"ok": False, "error": "Invalid skill pack",
+                    "details": v.get("errors")}
+        return {"ok": True, **mf.skill_pack_import(
+            pack, mode=args.get("mode", "merge"))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_memory_evolve(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.evolve_memory(
+            args["memory_id"], content=args.get("content"),
+            category=args.get("category"), reason=args.get("reason", ""))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_memory_evolution_history(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, "memory_id": args["memory_id"],
+                "evolutions": mf.list_evolutions(
+                    args["memory_id"], limit=int(args.get("limit", 50) or 50))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_memory_learn_outcome(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.learn_from_outcome(
+            args["memory_id"], outcome=args.get("outcome", "success"),
+            note=args.get("note", ""))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_passport_export(mf, _args):
+    try:
+        return {"ok": True, **mf.passport_export()}
+    except Exception as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_passport_import(mf, args):
+    pp = args.get("passport")
+    if not isinstance(pp, dict):
+        return {"ok": False, "error": "Field 'passport' must be an object"}
+    try:
+        return {"ok": True, **mf.passport_import(
+            pp, mode=args.get("mode", "merge"))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_passport_revoke(mf, args):
+    err = _require_args(args, "passport_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.passport_revoke(args["passport_id"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_forget_explain(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.forget_explain(args["memory_id"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_forget_run(mf, args):
+    try:
+        # v6.1.2：接通 days 冷却窗口（此前 core 有参数但三层都传不进去）
+        return {"ok": True, **mf.forget_run(
+            dry_run=bool(args.get("dry_run", False)),
+            days=_safe_int(args.get("days", 30), default=30, lo=0, hi=3650))}
+    except Exception as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_follow_up_create(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.follow_up_create(
+            args["memory_id"], note=args.get("note", ""),
+            due_at=float(args.get("due_at", 0) or 0))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_follow_up_due(mf, args):
+    try:
+        return {"ok": True, "due": mf.follow_up_due(
+            limit=int(args.get("limit", 20) or 20))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_follow_up_resolve(mf, args):
+    err = _require_args(args, "follow_up_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.follow_up_resolve(args["follow_up_id"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_follow_up_nag(mf, args):
+    try:
+        return {"ok": True, **mf.follow_up_nag(
+            interval_hours=float(args.get("interval_hours", 24.0) or 24.0),
+            max_nags=int(args.get("max_nags", 3) or 3))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+# ---------------------------------------------------------------------------
+# v6.0.0 正式版：v6 端口总览 + 多 Agent 空间 + 6G AI 记忆预览 handlers
+# ---------------------------------------------------------------------------
+
+def h_v6_status(mf, _args):
+    try:
+        return {"ok": True, **mf.v6_status()}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_create(mf, args):
+    err = _require_args(args, "name", "owner_agent")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.multi_agent.create_space(
+            name=args["name"], owner_agent=args["owner_agent"],
+            description=args.get("description", ""),
+            policy=args.get("policy", "shared"))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_list(mf, args):
+    try:
+        agent_id = args.get("agent_id", "")
+        if args.get("mine") and not agent_id:
+            agent_id = "mcp"
+        return {"ok": True, "spaces": mf.multi_agent.list_spaces(
+            agent_id=agent_id)}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_join(mf, args):
+    err = _require_args(args, "space", "agent_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.multi_agent.add_member(
+            space_ref=args["space"], agent_id=args["agent_id"],
+            role="reader", actor=args["agent_id"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_add_member(mf, args):
+    err = _require_args(args, "space", "member_agent", "actor")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.multi_agent.add_member(
+            space_ref=args["space"], agent_id=args["member_agent"],
+            role=args.get("role", "reader"), actor=args["actor"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_share(mf, args):
+    err = _require_args(args, "space", "memory_id", "actor")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.multi_agent.share_memory(
+            space_ref=args["space"], memory_id=args["memory_id"],
+            actor=args["actor"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_memories(mf, args):
+    err = _require_args(args, "space", "actor")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.multi_agent.list_space_memories(
+            space_ref=args["space"], actor=args["actor"],
+            limit=int(args.get("limit", 50) or 50))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_space_stats(mf, args):
+    try:
+        return {"ok": True, **mf.multi_agent.space_stats(
+            space_ref=args.get("space", ""))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_open(mf, args):
+    try:
+        cfg = args.get("config")
+        if cfg is not None and not isinstance(cfg, dict):
+            return {"ok": False, "error": "Field 'config' must be an object"}
+        return {"ok": True, **mf.memory_preview.open_preview_channel(cfg)}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_close(mf, args):
+    err = _require_args(args, "channel_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.memory_preview.close_preview_channel(
+            args["channel_id"], purge=bool(args.get("purge", True)))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_channels(mf, args):
+    try:
+        return {"ok": True, "channels": mf.memory_preview.list_preview_channels(
+            include_closed=bool(args.get("include_closed", False)))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_snapshot(mf, args):
+    err = _require_args(args, "channel_id", "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.memory_preview.snapshot_memory(
+            args["channel_id"], args["memory_id"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_distill(mf, args):
+    mids = args.get("memory_ids")
+    if not isinstance(mids, list) or not mids:
+        return {"ok": False, "error": "Missing 'memory_ids' array field"}
+    try:
+        return {"ok": True, **mf.memory_preview.distill_context(
+            mids, max_tokens=int(args.get("max_tokens", 2000) or 2000))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_index(mf, _args):
+    try:
+        return {"ok": True, **mf.memory_preview.incremental_index_stats()}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_preview_timeline(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    try:
+        return {"ok": True, **mf.memory_preview.timeline(args["memory_id"])}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_skill_distill(mf, args):
+    try:
+        stats = mf.distill_skills(
+            min_cluster_size=int(args.get("min_cluster_size", 2) or 2),
+            max_skills=int(args.get("max_skills", 50) or 50))
+        return {"ok": True, **stats}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_skill_match(mf, args):
+    err = _require_args(args, "query")
+    if err:
+        return err
+    try:
+        return {"ok": True, "query": args["query"],
+                "skills": mf.skill_match(str(args["query"]),
+                                          limit=int(args.get("limit", 5) or 5))}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_skill_render(mf, args):
+    err = _require_args(args, "name")
+    if err:
+        return err
+    try:
+        params = args.get("params") or {}
+        out = mf.skill_render(str(args["name"]), **params)
+        if out is None:
+            return {"ok": False, "error": f"skill not found: {args['name']}"}
+        return {"ok": True, "rendered": out}
+    except (ValueError, TypeError) as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_skill_stats(mf, args):
+    try:
+        return {"ok": True, "stats": mf.skill_stats()}
+    except Exception as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_graph_stats(mf, args):
+    try:
+        return {"ok": True, "stats": mf.graph_stats()}
+    except Exception as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_graph_related(mf, args):
+    err = _require_args(args, "entity")
+    if err:
+        return err
+    try:
+        return {"ok": True, "entity": args["entity"],
+                "related": mf.graph_related(str(args["entity"]), depth=int(args.get("depth", 2)))}
+    except Exception as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_graph_extract(mf, args):
+    try:
+        mid = args.get("memory_id", "") or ""
+        stats = mf.extract_graph(memory_id=mid) if mid else mf.extract_graph()
+        return {"ok": True, **stats}
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+
+
+def h_conflict_reconcile(mf, args):
+    try:
+        auto = args.get("auto", True)
+        if not isinstance(auto, bool):
+            raise ValueError("Field 'auto' must be a boolean")
+        result = mf.reconcile_conflicts(
+            memory_ids=args.get("memory_ids"),
+            auto=auto)
+    except ValueError as e:
+        return {"ok": False, "error": _safe_error_msg(e)}
+    return {"ok": True, **result}
+
+
+
+# ---------------------------------------------------------------------------
+# v5.8.6 新增：联邦共享 MCP 工具（对等节点管理 + 跨节点共享/检索）
+# ---------------------------------------------------------------------------
+def h_fed_peer_register(mf, args):
+    err = _require_args(args, "peer_id", "name")
+    if err:
+        return err
+    return _clean(mf.federated.register_peer(
+        str(args["peer_id"]), str(args["name"]),
+        trust_level=float(args.get('trust_level', 0.5)),
+        shared_categories=args.get('shared_categories')))
+
+
+def h_fed_peer_remove(mf, args):
+    err = _require_args(args, "peer_id")
+    if err:
+        return err
+    return _clean(mf.federated.remove_peer(str(args["peer_id"])))
+
+
+def h_fed_peer_list(mf, _args):
+    return _clean(mf.federated.get_peers())
+
+
+def h_fed_memory_share(mf, args):
+    err = _require_args(args, "memory_id", "peer_ids")
+    if err:
+        return err
+    return _clean(mf.federated.share_memory(
+        str(args["memory_id"]), list(args["peer_ids"]),
+        access_policy=str(args.get('access_policy', 'read_only')),
+        expires_hours=args.get('expires_hours')))
+
+
+def h_fed_memory_revoke(mf, args):
+    err = _require_args(args, "memory_id")
+    if err:
+        return err
+    return _clean(mf.federated.revoke_share(
+        str(args["memory_id"]), args.get("peer_ids")))
+
+
+def h_fed_memory_list_shared(mf, args):
+    return _clean(mf.federated.get_shared_memories(
+        peer_id=args.get('peer_id')))
+
+
+def h_fed_search(mf, args):
+    err = _require_args(args, "query")
+    if err:
+        return err
+    return _clean(mf.federated.federated_search(
+        str(args["query"]),
+        peer_ids=args.get('peer_ids'),
+        max_per_peer=_safe_int(args.get('max_per_peer', 5), 5, 1, 50)))
+
+
+def h_fed_stats(mf, _args):
+    return _clean(mf.federated.compute_federated_stats())
+
+HANDLERS: Dict[str, Any] = {
+    "memory_add": h_memory_add,
+    "memory_search": h_memory_search,
+    "memory_list": h_memory_list,
+    "memory_stats": h_memory_stats,
+    "memory_importance": h_memory_importance,
+    "memory_context": h_memory_context,
+    "agent_emotion": h_agent_emotion,
+    "char_relationship": h_char_relationship,
+    "drama_genre_trend": h_drama_genre_trend,
+    "drama_binge_score": h_drama_binge_score,
+    # v5.4.1 新增
+    "memory_reflection": h_memory_reflection,
+    "memory_lineage": h_memory_lineage,
+    "memory_reinforce": h_memory_reinforce,
+    "drama_plot_thread": h_drama_plot_thread,
+    "drama_episode_curve": h_drama_episode_curve,
+    "drama_screen_time": h_drama_screen_time,
+    # v5.4.2 新增
+    "fed_acl_add": h_fed_acl_add,
+    "fed_acl_remove": h_fed_acl_remove,
+    "fed_acl_list": h_fed_acl_list,
+    "fed_acl_check": h_fed_acl_check,
+    "fed_acl_stats": h_fed_acl_stats,
+    "share_conflict_list": h_share_conflict_list,
+    "share_conflict_resolve": h_share_conflict_resolve,
+    "share_conflict_dismiss": h_share_conflict_dismiss,
+    "share_conflict_stats": h_share_conflict_stats,
+    # v5.3.9 新增
+    "intent_router": h_intent_router,
+    "conflict_scan": h_conflict_scan,
+    "skill_extract": h_skill_extract,
+    "rerank_search": h_rerank_search,
+    "session_focus": h_session_focus,
+    # v5.4.5 新增向量检索
+    "rebuild_embeddings": h_rebuild_embeddings,
+    "embedding_status": h_embedding_status,
+    # v5.5.8 新增
+    "memory_diff": h_memory_diff,
+    # v5.7.6 新增：Bi-temporal 事实时序
+    "memory_supersede": h_memory_supersede,
+    "memory_valid_at": h_memory_valid_at,
+    # v5.7.7 新增：Agent 记忆治理 + 连接器 + 冲突调和
+    "memory_agent_pin": h_memory_agent_pin,
+    "memory_agent_forget": h_memory_agent_forget,
+    "memory_agent_decay_boost": h_memory_agent_decay_boost,
+    "memory_connector_ingest": h_memory_connector_ingest,
+    "conflict_reconcile": h_conflict_reconcile,
+    # v5.7.9 新增：知识图谱
+    "memory_graph_stats": h_graph_stats,
+    "memory_graph_related": h_graph_related,
+    "memory_graph_extract": h_graph_extract,
+    # v5.8.0 新增：程序性记忆 / 经验蒸馏
+    "memory_experience_record": h_experience_record,
+    "memory_skill_distill": h_skill_distill,
+    "memory_skill_match": h_skill_match,
+    "memory_skill_render": h_skill_render,
+    "memory_skill_stats": h_skill_stats,
+    # v5.8.6 新增：联邦共享 MCP
+    "fed_peer_register": h_fed_peer_register,
+    "fed_peer_remove": h_fed_peer_remove,
+    "fed_peer_list": h_fed_peer_list,
+    "fed_memory_share": h_fed_memory_share,
+    "fed_memory_revoke": h_fed_memory_revoke,
+    "fed_memory_list_shared": h_fed_memory_list_shared,
+    "fed_search": h_fed_search,
+    "fed_stats": h_fed_stats,
+    # v6.0.0 功能 1-8
+    "chat_import": h_chat_import,
+    "timeline_viz": h_timeline_viz,
+    "skill_pack_export": h_skill_pack_export,
+    "skill_pack_import": h_skill_pack_import,
+    "memory_evolve": h_memory_evolve,
+    "memory_evolution_history": h_memory_evolution_history,
+    "memory_learn_outcome": h_memory_learn_outcome,
+    "passport_export": h_passport_export,
+    "passport_import": h_passport_import,
+    "passport_revoke": h_passport_revoke,
+    "forget_explain": h_forget_explain,
+    "forget_run": h_forget_run,
+    "follow_up_create": h_follow_up_create,
+    "follow_up_due": h_follow_up_due,
+    "follow_up_resolve": h_follow_up_resolve,
+    "follow_up_nag": h_follow_up_nag,
+    # v6.0.0 正式版：v6 端口总览 + 多 Agent 空间 + 6G AI 记忆预览
+    "v6_status": h_v6_status,
+    "space_create": h_space_create,
+    "space_list": h_space_list,
+    "space_join": h_space_join,
+    "space_add_member": h_space_add_member,
+    "space_share": h_space_share,
+    "space_memories": h_space_memories,
+    "space_stats": h_space_stats,
+    "preview_open": h_preview_open,
+    "preview_close": h_preview_close,
+    "preview_channels": h_preview_channels,
+    "preview_snapshot": h_preview_snapshot,
+    "preview_distill": h_preview_distill,
+    "preview_index": h_preview_index,
+    "preview_timeline": h_preview_timeline,
+}
+
+
+# ---------------------------------------------------------------------------
+# MCP request dispatcher
+# ---------------------------------------------------------------------------
+
+def _handle_initialize(request: Dict[str, Any]) -> Dict[str, Any]:
+    _notify("notifications/initialized")
+    return {
+        "protocolVersion": "2024-11-05",
+        "capabilities": {"tools": {}, "logging": {}},
+        "serverInfo": {"name": "mindforge", "version": __version__},
+    }
+
+
+def _handle_tools_list(_request: Dict[str, Any]) -> Dict[str, Any]:
+    return {"tools": list(TOOL_SCHEMAS)}
+
+
+def _is_tool_error(result: Any) -> bool:
+    """判断 handler 返回值是否表示「工具执行失败」。
+
+    v6.1.2 修复：本项目的 handler 有两种失败写法——`{"ok": False, "error": ...}`
+    （参数校验、_require_args）与 `{"success": False, "error": ...}`（core 门面
+    直接透传）。此前 `_handle_tools_call` 无论成败都返回同一个成功信封，MCP 客户端
+    只能解析文本才知道失败，把报错当结果用（例如自动化流程会以为写入成功）。
+
+    只认显式的 False：`ok`/`success` 缺失或为真值都按成功处理，避免把
+    「返回体恰好带 success 字段」的正常结果误判为失败。
+    """
+    if not isinstance(result, dict):
+        return False
+    return result.get("ok") is False or result.get("success") is False
+
+
+def _handle_tools_call(mf, request: Dict[str, Any]) -> Dict[str, Any]:
+    params = request.get("params") or {}
+    if not isinstance(params, dict):
+        raise ValueError("Invalid params: expected object")
+    name = params.get("name")
+    arguments = params.get("arguments") or {}
+    if not isinstance(arguments, dict):
+        arguments = {}
+    if name not in HANDLERS:
+        raise ValueError(f"Unknown tool: {name}")
+    result = HANDLERS[name](mf, arguments)
+    text = json.dumps(result, ensure_ascii=False, indent=2, default=str)
+    envelope: Dict[str, Any] = {"content": [{"type": "text", "text": text}]}
+    # MCP spec：工具层失败用 isError 标记（JSON-RPC 本身仍是成功响应，
+    # 失败信息随 content 返回，客户端据此区分「查询无结果」与「调用出错」）。
+    if _is_tool_error(result):
+        envelope["isError"] = True
+    return envelope
+
+
+def _parse_args(argv: List[str]) -> Dict[str, Any]:
+    cfg: Dict[str, Any] = {"db_path": None, "key_file": None, "auth_secret": None}
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a == "--db-path" and i + 1 < len(argv):
+            cfg["db_path"] = argv[i + 1]; i += 2
+        elif a.startswith("--db-path="):
+            cfg["db_path"] = a.split("=", 1)[1]; i += 1
+        elif a == "--key-file" and i + 1 < len(argv):
+            cfg["key_file"] = argv[i + 1]; i += 2
+        elif a.startswith("--key-file="):
+            cfg["key_file"] = a.split("=", 1)[1]; i += 1
+        elif a == "--auth-secret" and i + 1 < len(argv):
+            cfg["auth_secret"] = argv[i + 1]; i += 2
+        elif a.startswith("--auth-secret="):
+            cfg["auth_secret"] = a.split("=", 1)[1]; i += 1
+        else:
+            i += 1
+    return cfg
+
+
+def _check_auth(msg: Dict[str, Any], expected_secret: str) -> bool:
+    """认证检查：initialize 请求须携带 _meta.authSecret，与 shared-secret 比对"""
+    if not expected_secret:
+        return True
+    params = msg.get("params") or {}
+    meta = params.get("_meta") or {}
+    client_secret = meta.get("authSecret", "")
+    import hmac as _hmac
+    return _hmac.compare_digest(str(client_secret), expected_secret)
+
+
+# v5.6.5 P2 #17：认证态改为下方加锁的 _AuthState 持有者（不再用裸全局 bool）
+_AUTH_IDLE_TIMEOUT = 30 * 60  # 30 分钟无活动自动登出（P2 #16 修复）
+
+
+class _AuthState:
+    """线程安全的认证状态（v5.6.5 P2 #17）。
+
+    此前认证态是裸全局 bool，多线程下读改写无原子保护；空闲时间戳改用
+    time.monotonic（P3 #23），不受系统墙上时钟回拨影响。
+    """
+
+    def __init__(self):
+        import threading
+        self._lock = threading.Lock()
+        self.authed = False
+        self.last_activity = 0.0
+
+    def reset(self) -> None:
+        with self._lock:
+            self.authed = False
+            self.last_activity = 0.0
+
+    def login(self, now: float) -> None:
+        with self._lock:
+            self.authed = True
+            self.last_activity = now
+
+    def is_authed(self) -> bool:
+        with self._lock:
+            return self.authed
+
+    def authorize(self, now: float, timeout: float):
+        """已认证则刷新活跃时间返回 True；过期登出返回 'expired'；未认证 False。"""
+        with self._lock:
+            if not self.authed:
+                return False
+            if now - self.last_activity > timeout:
+                self.authed = False
+                self.last_activity = 0.0
+                return "expired"
+            self.last_activity = now
+            return True
+
+
+def serve_forever(db_path: Optional[str] = None, key_file: Optional[str] = None,
+                  auth_secret: Optional[str] = None) -> int:
+    from mindforge import MindForge
+    if not db_path:
+        # v5.6.5 P2 #18：与 CLI 统一默认数据库路径（core.paths 单点真值）
+        from mindforge.core.paths import get_default_db_path
+        db_path = get_default_db_path()
+    _log(f"db: {db_path}")
+    kwargs: Dict[str, Any] = {"db_path": db_path, "encrypted": False}
+    if key_file:
+        kwargs["key_file"] = key_file
+        kwargs["encrypted"] = True
+    mf = MindForge(**kwargs)
+
+    # v5.6.5 P2 #17：认证状态收敛到加锁的 _AuthState 持有者
+    _auth = _AuthState()
+    expected_secret = auth_secret or os.environ.get("MINDFORGE_MCP_SECRET", "")
+
+    # v5.6.3 安全增强：未设置认证密钥时，MCP 服务对所有能连上的客户端开放。
+    # 信任模型：MCP 走 stdin/stdout，传输层本身不认证对端——能拉起本进程或向
+    # stdin 写数据的即被视为受信本地宿主。若把它桥接到网络/多用户环境，则属于
+    # 暴露面，需要 shared-secret 认证（客户端在 initialize 携带 _meta.authSecret）。
+    if not expected_secret:
+        # P2-09 加固：受管/CI 环境可设 MINDFORGE_MCP_REQUIRE_AUTH 强制 fail-closed，
+        # 避免误以无认证方式启动。
+        require_auth = os.environ.get("MINDFORGE_MCP_REQUIRE_AUTH", "").strip().lower()
+        if require_auth in ("1", "true", "yes", "on"):
+            _log(
+                "ERROR: MINDFORGE_MCP_REQUIRE_AUTH is set but MINDFORGE_MCP_SECRET "
+                "(or --auth-secret) is empty. Refusing to start an unauthenticated "
+                "MCP server."
+            )
+            return 2
+        _log(
+            "WARNING: MINDFORGE_MCP_SECRET not set — MCP server accepts all clients. "
+            "This is only safe for a local stdio host you trust. If this server is "
+            "reachable over a network, set MINDFORGE_MCP_SECRET to enable shared-secret "
+            "authentication (client sends _meta.authSecret on initialize), or set "
+            "MINDFORGE_MCP_REQUIRE_AUTH=1 to refuse startup without a secret."
+        )
+
+    while True:
+        try:
+            msg = _read_message()
+        except EOFError:
+            _log("stdin closed")
+            return 0
+        except Exception as e:
+            _log(f"read error: {e}")
+            continue
+
+        method = msg.get("method", "")
+        rid = msg.get("id")
+        try:
+            if method == "initialize":
+                if _check_auth(msg, expected_secret):
+                    _auth.login(_time.monotonic())
+                    _respond(msg, _handle_initialize(msg))
+                else:
+                    _auth.reset()
+                    if rid is not None:
+                        _respond_error(msg, code=-32001, message="Authentication failed")
+            elif method == "notifications/initialized":
+                pass
+            elif expected_secret and not _auth.is_authed():
+                if rid is not None:
+                    _respond_error(msg, code=-32001, message="Not authenticated")
+            elif expected_secret and _auth.is_authed():
+                # P2 #16 修复：认证过期检查（30 分钟无活动自动登出）。
+                # v5.6.5：状态读改写在 _AuthState 锁内原子完成，计时用 monotonic。
+                _authz = _auth.authorize(_time.monotonic(), _AUTH_IDLE_TIMEOUT)
+                if _authz == "expired":
+                    if rid is not None:
+                        _respond_error(msg, code=-32001, message="Session expired")
+                    continue
+                if method == "tools/list":
+                    _respond(msg, _handle_tools_list(msg))
+                elif method == "tools/call":
+                    _respond(msg, _handle_tools_call(mf, msg))
+                elif method == "ping":
+                    _respond(msg, {})
+                elif method in ("shutdown", "exit"):
+                    if rid is not None:
+                        _respond(msg, {})
+                    return 0
+                else:
+                    if rid is None:
+                        _log(f"ignored notification: {method}")
+                    else:
+                        _respond_error(msg, code=-32601, message=f"Method not found: {method}")
+            elif method == "tools/list":
+                _respond(msg, _handle_tools_list(msg))
+            elif method == "tools/call":
+                _respond(msg, _handle_tools_call(mf, msg))
+            elif method == "ping":
+                _respond(msg, {})
+            elif method in ("shutdown", "exit"):
+                if rid is not None:
+                    _respond(msg, {})
+                return 0
+            else:
+                if rid is None:
+                    _log(f"ignored notification: {method}")
+                else:
+                    _respond_error(msg, code=-32601, message=f"Method not found: {method}")
+        except Exception as e:
+            tb = traceback.format_exc(limit=6)
+            _log(f"handler error {method}: {e}\n{tb}")
+            if rid is not None:
+                _respond_error(msg, code=-32000, message="Internal server error")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cfg = _parse_args(argv)
+    return serve_forever(db_path=cfg.get("db_path"), key_file=cfg.get("key_file"),
+                         auth_secret=cfg.get("auth_secret"))
+
+
+if __name__ == "__main__":
+    sys.exit(main())