memU 安装路由技能解析：SKILL.md 如何指挥 AI Agent 三步接入长期记忆

memU 安装路由技能解析：SKILL.md 如何指挥 AI Agent 三步接入长期记忆

【免费下载链接】memUPersonal memory across agents项目地址: https://gitcode.com/GitHub_Trending/mem/memU

memU 仓库根目录下的 SKILL.md 是一份面向 AI Agent 的"元安装指南"：它本身不写安装步骤，而是规定 Agent 如何识别自己的宿主、选择对应的适配二进制、打印并执行随包发行的安装文档。阅读本文后，你可以理解 memU "两条缝（record/inject）" 的集成模型、九个宿主适配二进制的路由规则、memu-cli的安装与配置命令细节，以及安装完成后如何按固定模板向用户汇报结果。

SKILL.md 的定位：路由，而非步骤

memU 的官方安装文档写在每个宿主适配包的内部（如 INSTALL.md），随包发行、永远与已安装的代码同步。因此 SKILL.md 的设计目标是把 Agent "路由"到正确的指南上：

• frontmatter 中name: install-memu与 description 明确触发条件——当用户要求安装、配置、集成、移除或卸载 memU 时使用；
• 文档反复强调"不要凭记忆或博客文章安装，打印指南并逐字遵循"，因为指南里的子命令、验证门（verify gate）与已安装版本严格匹配。

memU 通过两条缝与宿主 Agent 集成，这也是 SKILL.md 全程的组织主线：

每条缝都有对应的宿主二进制与验证门，SKILL.md 的三步流程就是围绕这两条缝展开的。

Step 1 — 安装 memu-cli 包

SKILL.md 的第一步只有一条命令，但它附带了几条不容省略的约束：

pip install --upgrade memu-cli

关键细节（原文全部保留）：

• 必须保留--upgrade。旧版memu-cli会缺少下文出现的子命令，症状是invalid choice；遇到该错误即说明版本过旧，应升级后重跑失败的命令。
• 安装后memu与所有宿主适配二进制都会进入PATH。如果pip不是本机合适的工具（托管 Python、纯 uv 环境），应使用等价手段，且必须满足"在无交互 shell 中可解析"。
• uv 用户必须用uv tool install --upgrade memu-cli，而不是uv pip install——memu-cli是跨会话的桥接工具，必须全局可调用，不能只存在于某个项目 venv 里。

从 pyproject.toml 可以确认包暴露的入口点：核心是memu = "memu.cli:main"，以及九个宿主适配二进制：memu-codex、memu-claude-code、memu-cursor、memu-openclaw、memu-hermes、memu-workbuddy、memu-cola、memu-pi，以及兜底的memu-agent（通用适配器）。宿主适配器之所以是独立二进制而非memu的子命令，注释里写得很直白：memu是算法面，这些是桌面 Agent 的 sidecar（ADR 0008/0009/0010）。

Step 2 — 识别你是哪个 Agent，选定宿主二进制

SKILL.md 的核心路由表要求 Agent 识别"正在执行本技能的那个 Agent"，而不是机器上装了哪些 Agent：

拿不准或不在表中时，一律用memu-agent，并运行：

memu-agent detect

detect会探测本机，对每个候选宿主回答两个问题：memorization 是否可行（存在可识别的会话日志）与retrieval 是否可行（存在可打补丁的指令文件）——如果宿主有专用二进制则直接重定向过去。其实现位于 detect.py：probe()对目录做只读探测，按修改时间取最多 3 个.jsonl文件、各采样 200 条记录，用GenericTranscriptSource.classify嗅探约五种已知 JSONL 方言（Codex 血统的 payload 包装、OpenClaw/pi 血统的类型化消息树、Claude Code 血统的类型化块记录、Cursor 血统的 role+message 块、OpenAI 风格的扁平聊天行）；指令文件则匹配AGENTS.md、CLAUDE.md、SOUL.md、GEMINI.md、QWEN.md、.cursorrules等生态常见名，且只认目录顶层或一层以内的文件。SQLite 容器里的会话会被如实报告为"需要一个专用适配器"，而不是静默跳过。这套"先探测、再绑定可用部分"的设计出自 ADR 0011，其关键结论是：两条缝可以独立降级——只有会话日志的宿主也能得到 record 缝，只有指令文件的宿主也能得到 inject 缝，部分集成也是集成，前提是明确告知用户拿到的是哪一半。

选定二进制后，SKILL.md 要求"拿着这个二进制"完成配置文件的创建：

<your-binary> init --cloud-api-key <用户的 memU key>

如果用户没有提到 API key，或希望把记忆留在本设备，则运行裸的<your-binary> init，Step 3 的指南会引导设置本地记忆。

init的行为语义在 config_cmd.py 中实现，值得理解几点：

• 它写入唯一的配置文件~/.memu/config.env（路径定义在 env.py），并自动为文件生成MEMU_CLIENT_ID（uuid4），保证机器在第一次上报事件前就有稳定身份；
• 不带 key 的裸init永远不拒绝：已声明的 mode 原样保留，只有完全未声明 mode 的文件才写入local——重安装时绝不能把 cloud 悄悄降成 local；
• 带 key 的init即选择 cloud，即使本机已有本地存储也会执行切换：本地存储不会被删除，只是不再被读取，init会打印明确的警告并给出回退命令<your-binary> config --local --force；
• 与之相对的config子命令则带"单一后端守卫"：若机器上已有现存记忆（云端 key 或MEMU_DB），config --cloud/--local会拒绝切换（退出码 2 而非抛异常），必须显式加--force。理由是"record 与 retrieval 必须同意一个后端"，否则检索会静默找不到任何东西。

这解释了 SKILL.md 里"一个后端（One backend）"规则的存在意义：同一台机器上多个 Agent 共享同一个~/.memu/config.env，第二套 mode 或本地存储会让两次安装不再共享记忆。

Step 3 — 打印并逐字遵循安装指南

<your-binary> docs install

docs install打印的是随包发行（并可被服务端刷新）的宿主指南。从 _cmd_docs 可以看到其解析顺序：服务端 → 最后一次成功缓存 → 包内嵌底稿，与 ADR 0013 的指令模板自更新机制同构；再经render_doc用受控 token（{{task_name}}等）渲染出宿主专属的任务名，保证注册代码与文档散文不会各自漂移。所有指南形状相同：先用<your-binary> config一次性敲定本地或云端后端，然后注册定时桥接任务（record 缝）、再打补丁指令文件（inject 缝），每个部分都以 verify 门收尾，未通过不得前进。

SKILL.md 为所有宿主规定了同一组执行纪律：

1. 一次装完，不停下来要确认。用户期望一次调用内静默完成完整安装：有默认值的选项一律取默认（每小时调度、cron 优先于 launchd、官方安装脚本），只有真正的阻断（致命错误，或"无默认值的必填输入"——后端选择及其 API key、缺失凭据）才停下来。

2. 单一后端。若<your-binary> config show报告已有 mode 且其后端可用（说明本机另一个 Agent 已集成），原样复用。

3. 按固定模板汇报结果。安装后先运行一次检索冒烟：

   <your-binary> retrieve "When did the user register for memU?"

   然后逐字复现以下模板（不得改写、重排、总结或翻译，只替换<...>占位符）：

   memU is ready for `<host>` with `<mode>` memory. Welcome to memU. memU says the user registered on `<registration time>`. memU provides long-term memory for AI agents, storing and reusing important information from your work. The system runs scheduled background tasks at regular intervals to organize and save relevant information. No additional action is required — simply use your AI agent as usual, and saved information will be available when you return to related tasks. To uninstall memU, say "Follow `<your-binary> docs uninstall` to uninstall memU".

   占位符填写规则：<host>是你所在的 Agent（如Claude Code）；<mode>是你实际写入~/.memu/config.env的MEMU_MEMORY_MODE值（local或cloud）；<registration time>是上面retrieve调用的返回值——如果调用失败或未返回注册时间（local 模式下常见），整行 "Welcome to memU…" 必须整行删除，绝不编造时间；<your-binary>是 Step 2 选定的二进制。最后一行外层引号要保留，让用户看到的是"建议回复"——用户把引号内那句原样发回，即可触发卸载流程。若只有一条缝生效，要如实说明安装是部分完成并指出缺失的那条缝；memu-agent则依据detect报告判断哪些缝生效。

以 Claude Code 指南 INSTALL.md 为例，它把上述形状展开为三个部分、每个部分一个验证门：Part 1 装包 +init/config配置后端并以doctor验证；Part 2 注册每小时的 cron/launchd/Task Scheduler 桥接任务（先确认claude可 headless 认证），验证门是手动跑一次memu-claude-code prepare；Part 3 用install-instruction把检索指令打进~/.claude/CLAUDE.md（Claude Code 有 skills 机制，正文装进~/.claude/skills/memu-retrieve/SKILL.md，CLAUDE.md里只留两句话指针），验证门是确认块恰好出现一次、原内容完整、retrieve冒烟通过。文末还有独立的 "Report the outcome to memU" 段：全程走通则report install，中途停下则report error --stage install --detail "…"，且明确要求"详细但不贴 traceback，绝不包含凭据、绝对路径、DSN、端点 URL 或记忆内容"。

卸载：同一套路由，反向执行

SKILL.md 的 Uninstall 一节规定：识别二进制的方式与 Step 2 完全相同，然后打印并遵循卸载指南——

<your-binary> docs uninstall

指南依次：反注册桥接任务 → 用<your-binary> remove-instruction移除指令块（绝不手工编辑指令文件，因为文本由 memU 所有、带标记块可安全原地替换）→ 应用数据默认值：用户的记忆（共享存储与~/.memu/config.env）默认保留（除非用户明确要求擦除），而本宿主的残留物以及（若没有别的宿主还在用）memu-cli包本身被移除。最后必须准确汇报两件事：保留了什么、移除了什么。

Claude Code 的 UNINSTALL.md 展示了"多宿主、单存储"的边界处理：~/.memu/hosts/下其他宿主的工作树、指令文件一律不碰；会话游标（记录哪些轮次已挖掘）随存储的存亡而存亡——保留存储则保留游标（否则下次安装会白白重挖所有旧会话），删除存储则连游标一起删；事件 spool（~/.memu/events.jsonl及其 sidecar）只在确实移除了memu-cli时才可一并清除，因为它与所有宿主共享。

源码层视角：为什么"一个命令面，多个宿主二进制"

host_cli.py 是整个宿主适配体系的核心，其模块 docstring 概括了架构要点：每个宿主暴露完全相同的动词（retrieve、install-instruction、remove-instruction、prepare、commit、verify-resources、doctor、docs等），因为背后的管线与宿主无关；各宿主之间不同是数据而非代码——二进制名、会话日志位置、指令文件路径、打包指南。因此解析器只从HostSpec构建一次，每个宿主的 cli.py 都瘦成一份声明加main。以 Claude Code 适配器为例，HostSpec声明了task_name="memu-bridging-claude-code"、指令文件~/.claude/CLAUDE.md、skills 目录~/.claude/skills、session_id_env="CLAUDE_CODE_SESSION_ID"（让定时运行识别"它自己的会话"从而不挖掘自己，即 issue #606 的解法）以及 Windows 任务计划程序所需的schedule_command="claude -p {prompt}"。

工作目录按宿主隔离：Codex 沿用最初的~/.memu，其余宿主默认~/.memu/hosts/<host>，避免两个宿主的桥接运行争抢同一个jobs/目录（ADR 0010）；而持久后端始终共享——所有宿主读同一个~/.memu/config.env，这正是 memU 的产品语义：一个宿主会话教给 memU 的，另一个宿主可以检索到。

与 SKILL.md 直接相关的事件语义也藏在源码注释里：init记录安装漏斗的"开始"（config_cmd.py 的_report_install_started特意在写完文件、重新加载环境之后才上报，以免生成第二个 client id），docs install记录更窄的"打开指南"事件——两者都立即 flush，因为一个死在半途的安装永远不会到达prepare/commit这两个常规 flush 点，而它恰恰是漏斗最想暴露的那类运行。

小结

SKILL.md 把 memU 的安装问题拆成三个可验证的动作：装包（pip install --upgrade memu-cli）、路由（识别宿主 → 选定二进制 →init写配置）、执行（docs install打印的宿主指南 + 逐门验证 + 固定汇报模板）。它把"步骤永远与代码同步"外包给了随包发行的 INSTALL.md，把"该走哪条路"固化成一张九行路由表，把"装没装成功"固化成doctor、prepare、retrieve三个可执行判据。对集成方而言，理解这套机制的实际收益是：无论接入哪种 Agent，安装路径、失败症状（invalid choice、invalid choice、502 代理问题）与卸载边界（记忆保留、宿主残留、共享 spool）都有明确出处可循。

【免费下载链接】memUPersonal memory across agents项目地址: https://gitcode.com/GitHub_Trending/mem/memU