企业官网建设流程全解析

MemPalace Agent Skill 实战指南：三步安装、三大拓扑与 Shared Brain 协调协议的完整落地方案

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace

本指南以 MemPalace 仓库中skills/mempalace/SKILL.md的 Setup Protocol 为主干，讲解如何以 Skill 优先（skill-first）的方式完成 MemPalace 的安装、初始化、MCP 接线，以及私有本地宫殿（private local palace）、共享大脑枢纽（shared-brain hub）与加入现有枢纽的客户端（client）三种拓扑的选型与实施。读完本文，你将掌握mempalace instructions、mempalace mcp、mempalace serve、mempalace rules、mempalace logstream与mempalace update等核心命令的正确使用姿势，并能在接入共享大脑时理解身份、协调与升级策略的底层约定。

这个 Skill 解决什么问题

MemPalace 是一套开源 AI 记忆系统（"a searchable memory palace"）。当你要把某个 Agent（Claude Code、Codex、Cursor 等）接入记忆宫殿时，正确的安装顺序、拓扑选型和 MCP 配置缺一不可——而mempalaceSkill 的价值正在于此：它在 MemPalace Python 包或 MCP server 尚未存在时就可以被安装，npx skills add是正常的引导（bootstrap）路径，先让 Agent 拥有一份"如何搭起来"的步骤清单，再去执行mempalace init等底层命令。

从仓库结构看，mempalaceSkill 与另外两个 Skill 形成分工：mempalace-recall负责"先检索再回答"的回忆协议（见 skills/mempalace-recall/SKILL.md），mempalace-task负责通过 logstream 在 Agent 间传递任务（见 skills/mempalace-task/SKILL.md），而本 Skill 专管安装、配置与运行——setup、mining、status 三件事。仓库中对应的交互命令宏（slash command）文档位于 commands/mempalace-init.md、commands/mempalace-mine.md、commands/mempalace-search.md、commands/mempalace-status.md、commands/mempalace-help.md，它们统一的做法就是"调用mempalaceskill 并执行mempalace instructions <name>，然后按输出的步骤操作"。

第一步：动手前先检查环境（Inspect before changing anything）

Setup Protocol 的第一条纪律是"在改动任何东西之前先检查"，核心原因在于：Skill 是被独立引导进 Agent 的，Agent 无法假设 Python 包已经装在 PATH 上。检查项包括：

1. 检测操作系统与当前 Agent harness（是 CLI 还是 IDE、能否跑后台进程等）。
2. 版本探测：运行mempalace --version、uv --version，并做一次 Python 版本检查（Python 3.9+）。不要假设已安装的 Python 包一定在 PATH 上可达——它在某个未激活的 venv 里是完全可能的。
3. 检查是否已存在 palace 与 MCP 注册。绝不为了"让安装更简单"而重新初始化或重建已有 palace——数据与索引重建不可逆，会波及历史抽屉与日记。

mempalace/instructions/init.md中把这一步拆得更细：python3 --version（Windows 用python --version）确认不低于 3.9；随后运行mempalace --version，只有命令真的成功才算已安装——即使pip show mempalace或uv tool list报告包已存在，只要command not found，就按"未安装"处理并进入重装流程，否则后续mempalace init ...会直接失败。

第二步：仅在必要时安装 CLI，并优先使用 uv

当检查发现 CLI 缺失时，首选隔离的 uv tool 安装：

uv tool install mempalace

如果uv不可用，退回到 PATH 可见的 Python 环境：

python -m pip install mempalace

安装后务必再次运行mempalace --version；若仍不可达，要么修复 PATH，要么改用对应的uv tool run调用方式，再进行下一步。

mempalace/instructions/init.md为安装失败给出了一份有序的回退与排障清单：

1. uv tool install失败就换pip install mempalace（反之亦然）；
2. 尝试pip3 install mempalace；
3. 尝试python -m pip install mempalace（或python3 -m pip install ...）；
4. 若报错涉及缺失构建工具或编译失败（常见于 chromadb 及其原生依赖）：Linux/macOS 上装build-essential python3-dev（Debian/Ubuntu）或xcode-select --install（macOS），Windows 上装 Microsoft C++ Build Tools，然后重试；
5. 全部失败则如实上报错误并停下，不掩盖问题继续。

之所以强调uv，从源码注释也可印证：uv tool install把 CLI 与系统 Python 隔离，能规避大多数环境相关故障（见 mempalace/instructions/init.md）。

第三步：与用户确认三大拓扑

在选择任何安装动作前，需要向用户确认目标形态，除非需求已经明确。SKILL 定义了三种互斥的拓扑：

1. 私有本地宫殿（private local palace）：单机，本地 stdio MCP，记忆只属于这台机器；
2. 共享大脑枢纽（shared-brain hub）：本机拥有 palace，并向整个 Agent 舰队提供读写与协调服务；
3. 加入现有枢纽的客户端（client joining an existing hub）：本机只作为客户端连接别处拥有的 hub。

同时询问要初始化的项目/会话语料，默认当前工作目录。共享大脑客户端绝不能去初始化一份"第二个 palace"——记忆只有一份，属于枢纽所有者。

这三者在后续步骤的分叉非常明显：新建本地 palace 或 hub 走mempalace instructions init；客户端则跳过本地初始化，直接向用户索要 hub URL 与 bearer token。

第四步：用"版本正确的指令"做初始化

MemPalace 设计了一个巧妙的机制来对抗文档漂移：CLI 本身就是文档源，按当前安装版本动态输出与该版本严格匹配的指导内容，命令是：

mempalace instructions <command>

其中<command>取值为：help、init、mine、search、status。在源码中对应cmd_instructions处理器，它转发到mempalace/instructions_cli.py的run_instructions并把指令打到 stdout（见 mempalace/cli.py）。仓库内各命令的指令正文分散在 mempalace/instructions/ 目录（init.md、mine.md、search.md、status.md、help.md）。

正确流程是：先运行对应的 instructions 命令，拿到当前版本的步骤清单，再逐条照做。例如 mempalace/instructions/init.md 给出了完整的初始化链：问项目目录 →mempalace init --yes <dir>→ 配置 MCP →mempalace status验证 → 提示下一步用 mine / search。SKILL 在 Step 4 特别强调了两点：

• 新建本地 palace 或 hub：遵循mempalace instructions init，配置好所选语料，再用mempalace status验证；
• 客户端：跳过本地初始化，取得 hub URL 与 bearer token。

初始化是幂等保护的重灾区，这也是第一步"绝不重建已有 palace"的纪律延伸。

第五步：接线 MCP——stdio、hub 与 HTTP 客户端的正确姿势

本地 stdio 集成

本地集成使用mempalace mcp打印出来的接线命令。该命令在源码中根据 palace 路径拼出可复制的命令行（见 mempalace/cli.py），典型注册如下：

claude mcp add mempalace -- mempalace-mcp codex mcp add mempalace -- mempalace-mcp

其中mempalace-mcp是 stdio MCP server 的可执行入口。安装包本身不等于 MCP 已连接——接线完成后必须重启/重连 harness，并核验实时 MCP 工具列表中真的出现了 MemPalace 工具。SKILL 与 mempalace/instructions/init.md 都用整段篇幅强调这一点。

共享大脑 hub：mempalace serve

选共享大脑时，指导用户运行mempalace serve（并参考仓库内的 website/guide/shared-brain.md 完整教程）。serve是mempalace-mcp --transport http的封装：它会解析 bearer token（非 loopback 绑定时自动生成强 token）、打印可直接粘贴的客户端配置，然后以前台进程 exec 真正的 server，便于 Docker/systemd 托管进程生命周期（见 mempalace/cli.py）。一个serve进程持有 palace 的写入租约，两个 server 进程绝不能指向同一个 palace。

hub 与纯本地的关键差异在于：本机 stdio 客户端会每请求检查一次palace 是否有活的 hub，一旦发现就把请求自动代理（auto-proxy）给 hub，而不是自己打开数据库句柄；这是 fleet 免配置共享记忆的底层机制。

客户端：HTTP MCP + bearer token

加入现有 hub 的客户端，需要在 harness 上配置 HTTP MCP 传输并携带用户提供的 bearer token。SKILL 有一条安全红线：绝不把 token 打印或存储到项目指令、抽屉（drawers）或 logstream 事件里。部署角度的延伸见 website/guide/remote-server.md。

验证环节不可跳过

无论哪种拓扑，最后一步都是：重启/重连 harness → 检查实时 MCP 工具列表已包含 MemPalace 工具。包安装成功不能作为 MCP 已连接的证明。

第六步：共享大脑的身份与协调配置

当共享大脑模式被选中时，SKILL 要求依次处理以下事项：

1. 约定稳定身份：为该 Agent 商定一个<machine>-<harness>形式的稳定身份（例如mac-claude、windows-codex），永不轮换、绝不冒充他人——事件流只能靠稳定身份才能审计。

2. 渲染规范规则块：

   mempalace rules --agent <machine-harness>

   该命令由cmd_rules实现，按给定 agent 身份输出共享大脑规则块（见 mempalace/cli.py，实现转发到instructions_cli.run_rules）。website/guide/shared-brain.md 进一步说明：输出被<!-- mempalace-shared-brain:start/end -->标记包裹，更新协议后应重渲染并整块替换，而不是手改 N 份系统提示词；放哪取决于 harness（Claude Code 放~/.claude/CLAUDE.md，Codex 放~/.codex/AGENTS.md，Antigravity 等另有位置）。

3. 核验协调可达性：用只读的mempalace logstream list（或等效的 MCP 事件列表调用）确认能读到事件流。logstream 与记忆抽屉是两层：记忆层（drawers / KG / diary）存"值得回想的持久知识"，logstream 层（events / artifacts）存"需要在 Agent 间流转的进行中工作"。

4. 确定监视（watcher）模式，按 Agent 能力分流：

   • 能维持后台 watcher 的本地 palace 所有者或同步副本：准备mempalace logstream watch --agent ... --state-file ...命令（详见 website/guide/shared-brain.md 第 7 节：--agent <id>展开为--to-agent <id> --exclude-from-agent <id>，自排除对防自唤醒是承重的；退出码才是唤醒信号，0=有匹配、2=空闲超时、130=被打断）；
   • 纯远程 MCP 客户端：只能用重复的mempalace_event_wait调用做长轮询，把最后处理的事件 id 作为since_event_id携带前进——绝不能指向本地 SQLite watcher；
   • 两者都做不到的轮转型 Agent：明确记录"turn-based，唤醒时必须用mempalace_event_list清扫 MCP 收件箱"，并解释可能需要给 watch 命令做权限白名单。

   另外，不要未经告知就发测试事件：logstream 事件不可变（append-only）。用户批准冒烟事件时，要窄化其主题，并以一个确认事件闭环。

第七步：汇报就绪状态与可选的每周稳定版检查

配置结束后向用户汇总：安装版本、palace 位置或 hub URL（不含机密）、MCP 连接状态、稳定 Agent 身份、watcher 模式，以及第一个安全的下一步动作。若涉及活跃委派，转交mempalace-taskSkill（见 skills/mempalace-task/SKILL.md）。

每周稳定版检查（默认关闭，且从不自动安装）

SKILL 明确要询问用户是否需要每周稳定版检查，默认否。启用前应说明：该功能会联系 PyPI，但不发送任何 palace 内容、身份或遥测。启用时务必记录实际使用的安装器：

mempalace update configure --enable --installer uv-tool # 或 pipx / pip mempalace update configure --disable # 退出

源码证据：update_awareness.py的_INSTALL_ACTIONS精确限定uv-tool/pipx/pip三种安装器，configure_updates把策略写入~/.mempalace/updates.json，channel固定为stable、默认interval_days=7，且启用时未提供合法 installer 会直接抛错（见 mempalace/update_awareness.py 与 mempalace/update_awareness.py）。mempalace update configure由cmd_update驱动（见 mempalace/cli.py）。

读取mempalace_status时必须正确区分两个版本字段：

• updates.server：palace 服务的运行时（hub）；
• updates.client（存在时）：本地代理/客户端的运行时。

两者版本与安装器不可混为一谈。客户端的升级走本机的mempalace update plan；远程 server 的升级对客户端只是信息性提示——自然地向用户呈现，并请 hub 操作者在 palace 所在机器上准备与授权该计划。两条铁律：绝不把客户端生成的计划用于升级 server；任何计划未经明确授权绝不执行。这与_INSTALL_ACTIONS体现的"只产出命令，由用户执行"的保守设计一脉相承。

回忆与任务的边界：何时转交其他 Skill

mempalaceSkill 只覆盖 setup、mining 与 status。凡是涉及过去的工作、先前的决策、已经归档的人这类问题，SKILL 明确要求转交mempalace-recallSkill（见 skills/mempalace-recall/SKILL.md）——它强制执行"先检索再回答"（search-before-answer），让 Agent 读 palace 而不是靠模型记忆猜测。回忆工具的选择逻辑在那里被整理成一张清晰的映射表：

需要强调的边界：活跃协调不是回忆。向共享 hub 上的其他 Agent 委派任务、或等待其回复/补丁时，应当使用 logstream 工具（mempalace_event_append、mempalace_event_wait、mempalace_patch_submit、mempalace_artifact_get），而不是抽屉或搜索。同样的边界规则也写在记忆层的回忆协议与协调协议两个规范文件中（见 integrations/shared/recall-protocol.md 与 integrations/shared/coordination-protocol.md）。

Cursor 专属注意事项

Cursor 环境有三条特别提示：

1. Cursor 插件会自动注册mempalace-mcp，而独立的npx skills add安装不会——所以"检查实时工具列表"这一验证环节在 Cursor 下同样不可省略（commands/mempalace-init.md 也重申了这点：插件已自动注册，无需手改mcp.json）。
2. 若需要每 N 轮 Agent 自动后台保存 + 会话开始时的记忆召回，还要从克隆的 MemPalace 仓库单独运行hooks/cursor/install.sh --scope user安装 Cursor hooks，完整教程见仓库内的 website/guide/cursor-hooks.md。
3. 从 Cursor 会话调用mempalace_diary_write时，推荐的agent_name是cursor-ide——与claude-code、codex的命名先例保持一致，这是"稳定身份"规则在具体 harness 上的落地样例。

规范参考：把协议落在仓库里

原 SKILL 指向的规范文档在仓库内均有对应文件，可直接按根目录相对路径阅读（外部站点链接不在此展开）：

• 共享大脑完整教程（hub 启动、本地代理自动代理、远程机器接线、身份、首次委派、唤醒机制、跨机同步等）：website/guide/shared-brain.md；
• Agent 协调协议（logstream 事件模型与 watcher 纪律的单一事实源）：integrations/shared/coordination-protocol.md；
• 回忆协议（与 Cursor recall rule 及各集成共享的标准文本）：integrations/shared/recall-protocol.md；
• MCP 集成与部署扩展：仓库 website/guide/mcp-integration.md、website/guide/remote-server.md。

整体走查一遍可以看出，这个 Skill 的技术要点最终都收敛到同几条仓库级纪律上：先查再动（不重建已有 palace）、版本即文档（一切以mempalace instructions输出为准）、身份稳定（<machine>-<harness>永不轮换）、事件不可变（logstream append-only，闭环必须靠新的 ack 事件）、更新从不开箱即装（检查只报信，安装必须显式授权）。这套引导协议既适合单机首次接入，也完整覆盖了共享大脑舰队从接线到升级的运营生命周期。

【免费下载链接】mempalaceThe best-benchmarked open-source AI memory system. And it's free.项目地址: https://gitcode.com/GitHub_Trending/me/mempalace