MemPalace MCP Tools 全解析：45 个工具的 Schema、返回结构、写入约束与协调协议

MemPalace 通过 Model Context Protocol（MCP） 向任意 MCP 兼容的 AI 宿主暴露其"记忆宫殿"能力——语义检索、原文抽屉存取、知识图谱、跨翼隧道导航、Agent 日记，乃至多 Agent 之间的追加式协调事件流。本文以 MCP Tools Reference 为骨架，逐一定义 45 个工具的输入 Schema、返回结构与边界语义，并结合 mcp_server.py 的实现与仓库内文档，讲清每一个参数的作用、默认值、可取值与常见坑位，让你既能直接用、也能按需二次封装。

这份清单从哪来：先理解工具的实现契约

这 45 个 MCP 工具并不是散落的脚本，而是集中定义在 mempalace/mcp_server.py 的 TOOLS 字典中（约在 L4960 起），每个工具条目都包含 description、input_schema（JSON Schema，供宿主端渲染参数与必填校验）以及 handler（真正执行的函数）。也就是说，这份参考文档里出现的每一个参数、Required 标记与枚举取值，都能在同一个文件里逐项对上号。

接入方式本身并不复杂（详见 MCP 接入指南）：

# 打印你所在环境的确切接入命令
mempalace mcp

# 手动接入（不带/带自定义宫殿路径）
claude mcp add mempalace -- python -m mempalace.mcp_server
claude mcp add mempalace -- python -m mempalace.mcp_server --palace /path/to/palace
codex mcp add mempalace -- python -m mempalace.mcp_server --palace /path/to/palace

接入后，AI 在"醒来"时会先调用 mempalace_status 读取宫殿下发的 Memory Protocol（行为指南），随后在回答关于人、项目或历史事件的问题前先搜索、从不猜测。这份工具清单正是该协议得以落地的全部接口面。

按功能，45 个工具可以划分为六大族：

分组	工具数	覆盖能力
Palace — Read（宫殿读取）	7	状态、目录树、语义搜索、去重预检、AAAK 规格
Palace — Write（宫殿写入 / 抽屉维护）	9	存入、批量会话落盘、挖矿、清理、抽屉读取与更新
Knowledge Graph（知识图谱）	6	事实的增、查、作废、取代、时间线与统计
Navigation（图导航 / 隧道 / 走廊）	9	跨翼穿越、隧道增删查、走廊（hallway）维护
Agent Diary（Agent 日记）	2	读写个人日记
System（系统）	3	Hook 行为、检查点状态、数据库重连
Coordination — Logstream（协调事件流）	9	任务创建、事件增查等、工件存取、补丁提交、网格状态

这 9+9+6+9+2+3+… 的数字恰好构成全部 45 个工具；其中 Logstream 一族与 mempalace_mesh_peers 属于较晚加入的多 Agent / 多机协调面（RFC 003/004），也是从早期的 36 个工具增长出来的部分。

两类写入护栏：读与写的边界比看起来更精细

在逐工具展开之前，必须先理解一个贯穿全篇的机制——"写工具"是一个比直觉更窄、也更精确的集合。源码中同时维护着几组用于不同目的的工具集合（见 mcp_server.py）：

• _SQLITE_INTEGRITY_ALLOWED_TOOLS（L369）：当宫殿 SQLite 完整性存疑时仍被允许执行的工具。其中刻意放行了整个 Logstream 事件族，因为协调日志位于独立的 logstream.sqlite3，不依赖 Chroma/FTS5——主索引损坏期间，多 Agent 协调照常可用。
• _MUTATING_TOOLS（L420）：会改动宫殿状态的写工具全集，用于 peer-writer 租约校验：当一个长驻 MCP 进程未能取得宫殿的 mine 锁时，写工具会在触碰 Chroma 与知识图谱之前被拒绝。
• _VECTOR_WRITE_TOOLS（L471）：真正走到 Chroma 向量段写入的子集。知识图谱、隧道、走廊工具维护各自的 SQLite/JSON 状态、从不触碰 HNSW，因此即使向量索引不可用也不受影响——避免一次卡死的写入演变成全宫殿级故障。
• _PEER_WRITER_EXEMPT_TOOLS（L451）：Logstream 写工具只写 logstream.sqlite3，被豁免于 peer-writer 租约，但在 --read-only 下仍然会被隐藏并拒绝。

具体到每个工具是否可写，官方参考页给出了两条最容易被误解的规则，值得单独记住：

1. 库版本失配时写工具整体拒绝。mempalace_status 的 library_versions 会报告服务器加载的版本是否仍与磁盘上安装的一致；一旦失配（stale: true，例如运行期间包被升级或卸载），写工具会统一以 JSON-RPC 错误码 -32005 被拒绝，错误中同时给出两个版本名、action_required: "restart_mcp_server"，以及可用于关闭该检查的环境变量名。只有在该进程环境中显式设置 MEMPALACE_MCP_ALLOW_STALE_LIBRARY=1 才会放行，此时返回里会出现 gate_disabled_by 点名该变量。另外，unreadable 键会列出检查未能覆盖的发行版，避免把"什么都没查"误读为"查过且正常"。
2. "写集合"不等于"下面的写入小节"。参考页写工具小节里列的是抽屉类工具，而知识图谱、图导航与日记类写工具也在 _MUTATING_TOOLS 之列；反过来说，mempalace_get_drawer 与 mempalace_list_drawers 是纯读工具，永远不会被 -32005 拒绝。判定请以工具的实际行为为准，不要只看它出现在文档哪一节。

实现提示：读/写判定还在服务端作为能力边界使用——--read-only（或 MEMPALACE_MCP_READ_ONLY）模式除了隐藏 _MUTATING_TOOLS 之外，还会额外拒绝 mempalace_hook_settings 与 mempalace_memories_filed_away（它们会改写 ~/.mempalace/config.json 或删改 hook 状态文件），源码称其为"能力边界而非锁"。

---

Palace — Read Tools（宫殿读取）

本族工具不修改任何状态，回答"宫殿里有什么、搜什么、会不会重复"三类问题。

mempalace_status

宫殿总览：抽屉总数、翼（wing）与房间（room）计数、AAAK 方言规格与记忆协议。

参数： 无

返回：

{ total_drawers, wings, rooms, protocol, aaak_dialect, sqlite_integrity, library_versions, updates }

其中两个字段需要展开理解：

• library_versions：服务器当前加载的版本 vs 磁盘上安装版本的一致性快照。stale: true 表示不再匹配（典型场景是服务器运行期间包被升级/卸载），此时写工具被拒绝（错误码 -32005）直至重启；除非设置环境变量 MEMPALACE_MCP_ALLOW_STALE_LIBRARY=1，此时返回中由 gate_disabled_by 点名该变量。unreadable 键则列出检查未覆盖的发行版——可能是安装元数据读不到，也可能是启动时根本无法解析，因此 stale: false 绝不代表"检查且无恙"，务必同时确认 unreadable 为空。
• updates.server：为当前提供宫殿服务的运行时缓存的发布状态。本地 stdio 进程代理到 hub 时还会附带 updates.client（代理本机安装的运行时）；直接连 HTTP 的客户端只有 server 作用域，因为它没有可检查的本地进程。发布检查默认关闭、由后台线程刷新，因此该工具绝不会因等待 PyPI 而阻塞。出现可用版本仅作告知，任何升级命令都必须先获得用户授权——远端 server 的升级要在 hub 主机上规划，本地 plan 只作用于 updates.client。

mempalace_list_wings

列出所有翼及其抽屉计数。

参数： 无

返回： { wings: { "wing_name": count } }

mempalace_list_rooms

列出某翼内的房间（未给翼时列出全部房间）。

参数	类型	必填	说明
wing	string	否	要列出房间的翼

返回： { wing, rooms: { "room_name": count } }

mempalace_get_taxonomy

完整的一棵树：翼 → 房间 → 抽屉计数。

参数： 无

返回： { taxonomy: { "wing": { "room": count } } }

mempalace_search

语义搜索，返回抽屉原文与相似度分数。这是 AI 在回答前"先查证、再开口"的主力入口。

参数	类型	必填	说明
query	string	是	要搜索的内容
limit	integer	否	最大结果数（默认 5）
wing	string	否	按翼过滤
room	string	否	按房间过滤

返回： { query, filters, results: [{ text, wing, room, source_file, similarity }] }

实现细节补充（来自 TOOLS schema）：query 是纯关键词输入（≤250 字符），背景信息应放入 context 参数、不参与向量化、仅供未来重排；返回结果会用余弦距离阈值过滤，max_distance 默认 1.5（0=完全相同，2=完全相反，设 0 关闭）；candidate_strategy 可切到 "union"，把后端 BM25 词汇候选并入向量候选再统一重排；另有 source_file（精确全路径匹配）、since/before（按入库时间筛选）等进阶过滤。若你从结果里拿 source_file 做过滤条件，注意显示字段只是 basename，精确匹配请取返回里的 source_path 字段。

mempalace_check_duplicate

入库前检查内容是否已存在于宫殿，避免重复写入。

参数	类型	必填	说明
content	string	是	要检查的内容
threshold	number	否	相似度阈值 0–1（默认 0.85–0.87）

返回： { is_duplicate, matches: [{ id, wing, room, similarity, content }] }

mempalace_get_aaak_spec

返回 AAAK 方言（压缩记忆格式）规格文本，读写 AAAK 前先调它取格式定义。

参数： 无

返回： { aaak_spec: "..." }

关于 AAAK 的完整词法、情感标记与实体码，可进一步阅读 AAAK 方言概念。

---

Palace — Write Tools（宫殿写入）

本节先复述那条全局限定：服务器运行的库版本不再是磁盘上安装的版本时，写工具一律以 -32005 被拒（判定以 mempalace_status 的 library_versions 为准）。被拒集合并不与本节完全重合——知识图谱、图导航、日记写入也计入其中；而 mempalace_get_drawer / mempalace_list_drawers 是读操作、永不拒绝。错误信息会同时命名两个版本、携带 action_required: "restart_mcp_server" 与 override_env（点名可禁用检查的变量）。

mempalace_add_drawer

把逐字原文归档进宫殿。内容完全一致（相同的确定性抽屉 ID）时会静默跳过；需要基于相似度的重复检测时，请先用 mempalace_check_duplicate。

参数	类型	必填	说明
wing	string	是	翼（项目名）
room	string	是	房间（方面：backend、decisions 等）
content	string	是	要存储的逐字内容
source_file	string	否	内容来源
added_by	string	否	归档者（默认 "mcp"）

返回： { success, drawer_id, wing, room }

关于确定性抽屉 ID（同一内容永远映射到同一 ID，这正是"静默跳过"的根基），可参考 mempalace/ids.py 中的 ID 配方实现。

mempalace_checkpoint

一次调用保存整个会话：先对每个条目做语义去重，把非重复项归档为抽屉，再写入一条日记。相比拆成多次 mempalace_check_duplicate / mempalace_add_drawer / mempalace_diary_write，它在宿主 UI 里只渲染成一张工具调用卡片（整个保存期间 spinner 保持可见）。它复用同一套单条目处理器，因此去重、幂等与逐字保证完全一致。

参数	类型	必填	说明
items	array	是	要归档的逐字条目，每项为 { wing, room, content }
diary	object	否	归档后写入的日记条目：{ agent_name, entry, topic?, wing? }（entry 为 AAAK 格式）
dedup_threshold	number	否	逐条目去重相似度阈值 0–1（默认 0.9）
added_by	string	否	这些抽屉的归档者；显式传入优先，否则用 diary 的 agent_name，再否则为 checkpoint

返回： { added: [...], duplicates: [...], errors: [...], diary? }

mempalace_delete_drawer

按 ID 删除一个抽屉。不可逆。

参数	类型	必填	说明
drawer_id	string	是	要删除的抽屉 ID

返回： { success, drawer_id }

mempalace_mine

把目录挖矿进宫殿——对应 CLI 的 mempalace mine；mode='convos' 时也接受单个会话文件。它包装的是 CLI 使用的同一套进程内矿机，同步执行并把矿机摘要作为 output 返回。宫殿写锁是自动的——并发挖矿会得到结构化的 already-running 错误。孤儿清理是另一件事，交给 mempalace_sync。

参数	类型	必填	说明
source	string	是	要挖的目录；mode='convos' 时可为单个会话文件
mode	string	否	projects（代码/文档，默认）、convos（聊天记录）、extract（Office 文档，需要 mempalace[extract] extra）
wing	string	否	目标翼（默认：源目录名）
agent	string	否	记录到每个抽屉上（默认 mempalace）
limit	integer	否	最多处理的文件数（0 = 全部，默认 0）
dry_run	boolean	否	只报告将归档什么而不写盘（默认 false）
extract	string	否	Convos 抽取策略：exchange（默认）或 general；其他模式忽略

返回（成功）： { success, mode, dry_run, output }——output 是矿机的人类可读摘要；超大摘要被尾部截断时会追加 output_truncated: true。 返回（失败）： { success: false, error, error_class? }

mempalace_delete_by_source

批量删除从同一个 source_file（精确匹配）挖出的所有抽屉。典型用途是清理被误挖进用户翼的基准/测试数据——例如淹没了真实记忆的 ShareGPT dump 或 results_mempal_*.jsonl 评测文件。匹配通过 where 过滤下推到存储后端，因此无论共享同一 source 的抽屉有多少，都不受 SQLite 变量数上限约束。默认返回 dry-run 的匹配数与少量样本；传 dry_run=false 才真正提交。不可逆。

参数	类型	必填	说明
source_file	string	是	要移除的精确 source_file 元数据值（例如当初被挖的完整路径）
dry_run	boolean	否	预览匹配数而不删除；默认 true。传 false 才执行删除

返回（dry run）： { success, dry_run, source_file, match_count, sample, hint } 返回（提交）： { success, dry_run, source_file, deleted }

mempalace_sync

剪除那些源文件已被 gitignore、删除或移动的抽屉。默认返回 dry-run 报告；传 apply=true 才提交删除。

参数	类型	必填	说明
project_dir	string	否	限定同步范围的项目根目录（省略时从抽屉元数据自动探测）
wing	string	否	只处理一个翼
apply	boolean	否	真正删除抽屉；默认是 dry-run 预览

返回：

{ scanned, kept, gitignored, missing, unresolved, no_source, out_of_scope,
  removed_drawers, removed_closets, dry_run, by_source, unresolved_by_source }

语义边界值得细读：只有 gitignored 和 missing 两类会被移除。某个源文件不在其路径上，仅当宫殿在同目录下仍能看到属于它自己的源文件时才计入 missing——一次删除会留下邻居文件，而一次卸载卷则会把它们一起带走。其余情况统统计入 unresolved，保留不动，并像删除清单 by_source 那样在 unresolved_by_source 中列名。换言之：同步永远只清理"明确失效"的来源，拿不准的一律留证。

mempalace_get_drawer

按 ID 取单个抽屉——返回完整内容与元数据。

参数	类型	必填	说明
drawer_id	string	是	要获取的抽屉 ID

返回： { drawer_id, content, wing, room, metadata }。注意其中 metadata.source_file 出现时仅保留 basename——矿机写入的绝对路径在返回给 MCP 客户端之前会被缩减。

mempalace_list_drawers

带分页地列出抽屉，支持可选的翼/房间过滤。返回 ID、翼、房间与内容预览。

参数	类型	必填	说明
wing	string	否	按翼过滤
room	string	否	按房间过滤
limit	integer	否	每页最大结果数（默认 20，上限 100）
offset	integer	否	分页偏移（默认 0）

返回： { drawers: [...], total, limit, offset }

schema 补充（源码）：实现中还提供 since/before 两个按 filed_at 的 ISO 时间过滤参数（since 含边界、before 不含；带时间边界时无 filed_at 的抽屉被排除），便于"取最近归档的抽屉"。

mempalace_update_drawer

更新既有抽屉的内容与/或元数据（wing、room）。先取回既有抽屉；未找到则报错。

参数	类型	必填	说明
drawer_id	string	是	要更新的抽屉 ID
content	string	否	新内容（省略则保留原样）
wing	string	否	新翼（省略则保留原样）
room	string	否	新房间（省略则保留原样）

返回： { success, drawer_id, updated_fields }

---

Knowledge Graph Tools（知识图谱）

知识图谱把"事实"存成带时间有效性的三元组（subject → predicate → object），支持时间点查询。背后的持久化与语义参见 知识图谱概念 与 mempalace/knowledge_graph.py。

mempalace_kg_query

带时间过滤地查询某实体的关系。

参数	类型	必填	说明
entity	string	是	要查询的实体（例如 "Max"、"MyProject"）
as_of	string	否	日期过滤——只返回在该日期仍有效的事实（YYYY-MM-DD）
direction	string	否	outgoing、incoming 或 both（默认 both）

返回： { entity, as_of, facts: [{ direction, subject, predicate, object, valid_from, valid_to, current }], count }

mempalace_kg_add

向知识图谱添加一条事实。

参数	类型	必填	说明
subject	string	是	做某件事/处于某种状态的实体
predicate	string	是	关系类型（例如 loves、works_on）
object	string	是	被连接的实体
valid_from	string	否	该事实何时开始为真（YYYY-MM-DD）
source_closet	string	否	该事实出现的 closet ID

返回： { success, triple_id, fact }

schema 补充（源码）：还可传 valid_to 一次性回填一条已结束的历史事实；source_file / source_drawer_id 用于记录事实抽取来源（RFC 002 溯源）。

mempalace_kg_invalidate

把一条事实标记为不再为真（例如脚踝伤愈、工作结束、搬家）。

参数	类型	必填	说明
subject	string	是	实体
predicate	string	是	关系
object	string	是	被连接实体
ended	string	否	何时开始不再为真（默认：今天）

返回： { success, fact, ended }

mempalace_kg_supersede

在同一共享时间边界上原子地把一条事实替换为其后继。单值事实发生变化时（模型、雇主、地址）请用它，而不是拆成一次 mempalace_kg_invalidate + mempalace_kg_add——这样在边界时刻做时间点查询只会返回新值，绝不会出现"两个都真"或"两个都假"的窗口。

参数	类型	必填	说明
subject	string	是	事实发生变化的实体
predicate	string	是	关系（例如 uses_model、works_at）
old_object	string	是	被替换的旧值
new_object	string	是	新值
at	string	否	边界时刻（YYYY-MM-DD 或 YYYY-MM-DDTHH:MM:SSZ；默认：当前 UTC）

返回： { success, triple_id, fact, superseded }

mempalace_kg_timeline

事实的按时间顺序时间线。

参数	类型	必填	说明
entity	string	否	要获取时间线的实体（省略则获取完整时间线）

返回： { entity, timeline: [{ subject, predicate, object, valid_from, valid_to, current }], count }

mempalace_kg_stats

知识图谱总览。

参数： 无

返回： { entities, triples, current_facts, expired_facts, relationship_types }

---

Navigation Tools（图导航）

宫殿把"记忆之间的关系"建模成图：房间之内是挖矿时构建的走廊（实体共现链接），房间之间是隧道。本节工具的底层算法在 mempalace/palace_graph.py 与 mempalace/hallways.py 中实现，结构模型见 宫殿概念。

mempalace_traverse

从某个房间出发沿图漫游，寻找跨翼关联的想法。

参数	类型	必填	说明
start_room	string	是	起始房间
max_hops	integer	否	沿连接前进的步数（默认 2）

返回： [{ room, wings, halls, count, hop, connected_via }]

mempalace_find_tunnels

找出连接两个翼的房间（桥接两域的房间）。

参数	类型	必填	说明
wing_a	string	否	第一个翼
wing_b	string	否	第二个翼

返回： [{ room, wings, halls, count, recent }]

mempalace_graph_stats

宫殿图总览：节点、隧道、边、连通性。

参数： 无

返回： { total_rooms, tunnel_rooms, total_edges, rooms_per_wing, top_tunnels }

mempalace_create_tunnel

创建连接两个宫殿位置的跨翼隧道。当一个项目的内容与另一个项目相关时使用——例如 project_api 的 API 设计与 project_database 的数据库 schema 有关联。

参数	类型	必填	说明
source_wing	string	是	来源所在翼
source_room	string	是	来源翼中的房间
target_wing	string	是	目标所在翼
target_room	string	是	目标翼中的房间
label	string	否	连接说明
source_drawer_id	string	否	指定来源抽屉 ID
target_drawer_id	string	否	指定目标抽屉 ID

返回： { success, tunnel_id, source, target }

mempalace_list_tunnels

列出所有显式跨翼隧道，可按翼过滤。

参数	类型	必填	说明
wing	string	否	按翼过滤隧道（作为来源或目标）

返回： { tunnels: [...], count }

mempalace_delete_tunnel

按 ID 删除显式隧道。

参数	类型	必填	说明
tunnel_id	string	是	要删除的隧道 ID

返回： { success, tunnel_id }

mempalace_list_hallways

列出翼内的走廊记录（挖矿时构建的实体-实体共现链接），可按翼过滤。

参数	类型	必填	说明
wing	string	否	按翼过滤走廊

返回： [ { id, wing, entity_a, entity_b, co_occurrence_count, rooms, ... }, ... ]

mempalace_delete_hallway

按 ID 删除一条走廊记录。

参数	类型	必填	说明
hallway_id	string	是	要删除的走廊 ID

返回： { deleted: bool }

mempalace_follow_tunnels

从一个房间沿隧道出发，查看它在其他翼连接到什么。返回带抽屉预览的连接房间。

参数	类型	必填	说明
wing	string	是	出发翼
room	string	是	出发房间

返回： [{ wing, room, label, previews }]

---

Agent Diary Tools（Agent 日记）

日记是每个 Agent 专属的纵向记忆流：过去的"自己"记录了什么，现在的"自己"可以读回来。推荐用 AAAK 压缩格式书写，例如 'SESSION:2026-04-04|built.palace.graph+diary.tools|★★★'（完整格式先调 mempalace_get_aaak_spec 获取）。

mempalace_diary_write

写入个人 Agent 日记。

参数	类型	必填	说明
agent_name	string	是	你的名字——每个 Agent 拥有自己的翼
entry	string	是	日记条目（建议 AAAK 格式）
topic	string	否	主题标签（默认 "general"）

返回： { success, entry_id, agent, topic, timestamp }

schema 补充（源码）：还接受 wing（省略时默认写入 wing_{agent_name}；传入则可把日记写进项目翼），并接受 content 作为 entry 的别名（两者都传时 entry 优先）。

mempalace_diary_read

读取最近日记条目。

参数	类型	必填	说明
agent_name	string	是	你的名字
last_n	integer	否	最近条目数（默认 10）

返回： { agent, entries: [{ date, timestamp, topic, content }], total, showing }

---

System Tools（系统）

mempalace_hook_settings

读取或设置自动保存 hook 的行为。silent_save=true 时直接静默保存、避免 MCP 层刷屏；silent_save=false 使用旧的阻塞路径。desktop_toast=true 在保存完成时通过桌面通知弹出提示。不带参数调用则查看当前设置。

参数	类型	必填	说明
silent_save	boolean	否	true = 静默直接保存；false = 阻塞式 MCP 调用
desktop_toast	boolean	否	true = 通过 notify-send 显示桌面 toast

返回： { silent_save, desktop_toast }

mempalace_memories_filed_away

检查最近一次宫殿检查点是否已保存，返回消息数与上次保存时间戳。

参数： 无

返回： { filed, message_count, timestamp }

mempalace_reconnect

强制重连宫殿数据库。当外部脚本或 CLI 命令直接改动过宫殿、可能让进程内 HNSW 索引变得陈旧时使用。

参数： 无

返回： { success, message, drawers, vector_disabled[, vector_disabled_reason] }；无宫殿时返回 { success: false, message, drawers, vector_disabled }；异常时返回 { success: false, error }。

---

Agent Coordination Tools（Logstream，多 Agent 协调）

最后一族是把 MemPalace 从"单 Agent 记忆"扩展成"多 Agent 协调层"的接口：追加式协调事件与精确工件（patch、文件、日志、JSON）的存取。它由宫殿目录下的 logstream.sqlite3 承载，独立于向量索引——挖矿、修复、重建索引期间协调照常可用。完整协议与状态机见 Agent Logstream 概念页（RFC 003）与 共享大脑指南。在 --read-only 模式下，本节 5 个变更类工具（task_create、event_append、event_ack、artifact_put、patch_submit）会被隐藏并拒绝。

事件类型使用 task.request / task.reply / patch.ready 等命名，路由字段包含 stream（逻辑流，如 project/myapp）、room（子频道：delegation、patches、reviews、status）、topic（把同一子团队的相关工作归组，避免共用身份下的串扰）、correlation_id（贯穿请求—应答—ack 的关联 ID），to_agent 支持 * 广播，status 取值为 open / claimed / ready / applied / blocked / failed / superseded。

mempalace_task_create

创建一条完整、规范的 task.request，返回存储后的事件与一行可复制的交接语。这是连接远端共享大脑 hub 的 Agent 的首选建任务接口；它让 correlation-id 生成、body 结构、路由与 mempalace task create 完全一致。

参数	类型	必填	说明
project	string	是	项目路由名
from_agent	string	是	请求方 Agent 身份
to_agent	string	是	执行方 Agent 身份
goal	string	是	精确逐字任务目标
branch	string	是	工作的 Git 分支
base_commit	string	是	执行方必须基于其开工的不可变十六进制 commit id；分支名与 tag 会被拒绝
done	string	是	精确逐字的"完成定义"

返回： { success, task, handoff }。调用方必须先把确切的 task 展示给用户预览，再执行这次不可变追加。

mempalace_event_append

向 logstream 追加一条不可变的 Agent 协调事件（RFC 003）。

参数	类型	必填	说明
type	string	是	事件类型，如 task.request、task.reply、patch.ready
stream	string	是	逻辑流，如 project/myapp 或 shared_agent_brain
room	string	是	子频道：delegation、patches、reviews、status
topic	string	否	归组相关工作的主题，如 auth-v2
from_agent	string	是	写入方 Agent 身份
to_agent	string	否	目标 Agent，或 * 广播
correlation_id	string	否	把请求与应答事件关联起来的任务 ID
branch	string	否	相关时的 Git 分支
base_commit	string	否	工作基于的 Git commit
status	string	否	open、claimed、ready、applied、blocked、failed、superseded
body	string	否	逐字内容（上限 256 KiB）
metadata	object	否	附加结构化字段，逐字存储
artifact_ids	array	否	引用已存储工件的 ID 列表

返回： { success, event }——存储后的事件含服务端生成的 id、seq 与 created_at。seq 是追加序游标：把最后看到的事件 ID 传给 since_event_id，即可从断点精确续读。

mempalace_event_list

带结构化过滤地列出事件。阅读日志流的正确姿势是"按追加序而非时间序"理解：since_event_id 是严格位于该事件之后的前向恢复游标（rowid > anchor），绝不丢事件；before_event_id 用于反向/历史翻页（rowid < anchor）；order 默认 asc（最旧在前），desc 适合单次调用扫尾。千万不要用 since_created_at 做恢复游标——对端事件何时同步过来不定，它可能已经比你的时间戳水位更旧，从而被永久静默跳过；since_created_at 只适合"今天发生了什么"这类时间窗口查询（用时要按 id 去重）。

参数	类型	必填	说明
stream	string	否	按流过滤
room	string	否	按房间过滤
topic	string	否	按主题过滤
type	string	否	按事件类型过滤
to_agent	string	否	按目标过滤；也匹配 * 广播
from_agent	string	否	按写入方过滤
correlation_id	string	否	按关联 ID 过滤
status	string	否	按状态过滤
since_event_id	string	否	只返回追加序中严格位于此事件之后的事件（精确前向游标）
before_event_id	string	否	只返回追加序中严格位于此事件之前的事件（反向/历史翻页）
since_created_at	string	否	只返回该时刻及之后的事件（含边界，非恢复游标）
order	string	否	asc（最旧在前，默认）或 desc（最新在前）
limit	integer	否	最大事件数（默认 50，上限 500）

返回： { events: [...], count }

schema 补充（源码）：另有 preview=true 把每条 body 截成短摘录（标记 body_truncated + body_length），扫描繁忙流时省 token；注意 since_event_id 严格"位于其后"，不要拿被截断事件自身的 ID 去回取它。

mempalace_event_wait

阻塞至出现匹配事件或超时（长轮询，最长 5 分钟）。接受前向过滤参数 stream、room、topic、type、to_agent、from_agent、correlation_id、status、since_event_id、since_created_at，外加：

参数	类型	必填	说明
timeout_ms	integer	否	等待毫秒数（默认 60000，封顶 300000）
limit	integer	否	命中时最多返回的事件数（默认 50）

返回： { timed_out, events: [...], count }——超时是正常结果而非错误。

能保持 HTTP 连接打开的实时订阅端，应改用 GET /logstream/stream 的 SSE 推送；event_wait 是轮询型 MCP 接口。它内部已做退避（0.25s→1s），因此不要在它外面包紧循环重试；超时后把 since_event_id 推进到最后处理的事件再调一次即可。

mempalace_event_ack

确认某事件：会追加一条新的 event.ack 并路由回原写入方。默认复制目标事件的 topic（除非显式覆盖），correlation_id 复制目标值、以其 ID 作为回退。它从不修改目标事件。

参数	类型	必填	说明
event_id	string	是	要确认的事件
from_agent	string	是	确认方 Agent 身份
status	string	否	例如 applied、failed
body	string	否	逐字确认备注
topic	string	否	主题覆盖（默认取目标事件的 topic）

返回： { success, event }——新的 ack 事件。

mempalace_artifact_put

存储交接用的精确工件内容。仅限 UTF-8 文本，最大 4 MiB，存 sha256 与 size_bytes 供接收方校验。

参数	类型	必填	说明
kind	string	是	patch、file、log、json、note
content	string	是	精确内容
created_by	string	是	写入方 Agent 身份
metadata	object	否	附加字段，例如 branch/base_commit

返回： { success, artifact: { id, kind, sha256, size_bytes, created_by, created_at } }

mempalace_artifact_get

按 ID 取工件——精确内容外加 sha256 用于校验。

参数	类型	必填	说明
artifact_id	string	是	工件 ID

返回： { artifact: { id, kind, sha256, size_bytes, content, created_by, created_at, metadata } }（未找到时返回 { error }）

mempalace_patch_submit

便捷工具：一步完成"存 patch 工件 + 追加其 patch.ready 事件"。

参数	类型	必填	说明
content	string	是	unified diff 内容
from_agent	string	是	提交方 Agent 身份
stream	string	是	逻辑流
room	string	否	子频道（默认 patches）
topic	string	否	主题名，如 auth-v2
to_agent	string	否	目标 Agent 或 *
correlation_id	string	否	把 patch 关联到其请求的任务 ID
branch	string	否	Git 分支
base_commit	string	否	patch 所基于的 Git commit
body	string	否	逐字备注
metadata	object	否	附加结构化字段

返回： { success, artifact, event }

mempalace_mesh_peers

网格（mesh）资产快照——本 hub 视角下的 logstream 对端视图（见 共享大脑指南）：本副本的身份、版本向量与自推导节点画像；每个配置对端的可达性、最近一次同步结果、远端版本向量与对外宣告的画像；仅通过传递得知的 origin；以及按副本 ID 索引的 origin_profiles。它与 GET /sync/peers 的 payload 完全一致、由同一函数产出，是网格仪表盘的既定兼容面。绝不包含 Bearer token。

参数： 无

返回：

{ self: { replica_id, name, version_vector, profile },
  peers: [ { name, url, replica_id, reachable, last_success_at, last_error,
            remote_version_vector, profile } ],
  unnamed_origins, origin_profiles, sync_interval_s }

节点 profile 是纯粹的派生数据、绝非配置：roles（replica / agents / compute 的子集）、accelerator（{ provider, embedder }，来自解析出的 onnxruntime provider——CUDA、DirectML、CoreML 或 CPU）、drawers（实时存储计数）、hardware（平台字符串）、advertised_at。画像会随同步面传播，因此中转方也能为它只间接知晓的副本转发画像。

---

典型的双 Agent 交接闭环

把本族的工具串起来，就是参考文档里最常用的编排样例（与 Agent Logstream 概念页 中的 delegation loop 一一对应）：

• 请求方 Agent A：mempalace_task_create（或 mempalace_event_append，type=task.request）→ mempalace_event_wait（等 patch.ready）→ mempalace_artifact_get（取 patch 并核对 sha256）→ 本地应用与测试（应用永远是本地的显式决策，logstream 不会替你应用任何内容）→ mempalace_event_ack（status=applied 或 failed 并附备注）。
• 执行方 Agent B：mempalace_event_wait（to_agent=<me>, type=task.request）→ 完成工作 → mempalace_patch_submit（一步落盘工件并广播 patch.ready）。

产出不了 patch 时也要回话：task.reply 或 blocked/failed 状态加逐字说明。在 logstream 的语义里，沉默是唯一它无法帮你修复的失败模式。任务收尾后的结论与决策仍应归档进宫殿（mempalace_add_drawer / mempalace_checkpoint）——事件流记录工作如何在 Agent 间流动，抽屉记录学到了什么。

相关资源

• 全量工具 Schema 与分类见 MCP Tools Reference（本文骨架来源）
• 接入与宿主兼容性见 MCP 接入指南；多机/共享大脑部署见 共享大脑指南
• 概念背景：Agent Logstream、知识图谱、记忆宫殿结构、AAAK 方言
• 实现位置：工具注册表、写工具护栏集合、图遍历与隧道、走廊、知识图谱、事件日志存储
• 行为验证：仓库 tests/ 下的 test_mcp_server*.py、test_mcp_logstream.py、test_mcp_mine.py 等测试用例覆盖了上述多数工具的参数校验、错误码与边界分支，是核对返回结构是否与文档一致的最可靠途径。