onboard

Mem0 入门向导

运行此向导，为当前项目设置 mem0 插件。约 60 秒即可完成。

重要：必须严格按顺序执行步骤（0 → 1 → 2 → 3 → 4 → 5 → 6）。每一步都依赖上一步。不要并行执行步骤，也不要跳过步骤。完成当前步骤后，再开始下一步。

步骤 0：确保已安装 mem0ai SDK

插件会在会话启动时，通过 ${CLAUDE_PLUGIN_DATA}/venv 中的虚拟环境自动安装 mem0ai Python SDK。如果步骤 5（类别）因导入错误而失败，请运行：

"${CLAUDE_PLUGIN_ROOT}/scripts/ensure_deps.sh"

此操作不会输出信息且可重复执行，随时运行都安全。

步骤 1：设置 API 密钥

检查是否可从任何来源获取 API 密钥：

[ -n "${MEM0_API_KEY:-${CLAUDE_PLUGIN_OPTION_API_KEY:-}}" ] && echo "SET" || echo "NOT_SET"

重要：切勿运行 echo $MEM0_API_KEY — 这会将密钥以明文形式打印到对话日志中。

如果 API 密钥已设置（输出为 "SET"）

打印：- 已找到 API 密钥。，然后继续步骤 2。

如果 API 密钥未设置（输出为 "NOT_SET"）

引导用户设置 API 密钥。显示以下消息：

Step 1: Setting up API key.

- API key not found. Let's set it up.

  1. Get your API key from https://app.mem0.ai/dashboard/api-keys

  2. Choose ONE method:

     Option A — CLI (shell profile):
       echo 'export MEM0_API_KEY="m0-your-key-here"' >> ~/.zshrc
       source ~/.zshrc

     Option B — Desktop app (local environment editor):
       Click the environment dropdown next to the prompt box,
       hover over "Local", click the gear icon, and add:
         MEM0_API_KEY = m0-your-key-here
       (Stored encrypted on your machine, applies to all local sessions)

     Note: The Desktop app does NOT inherit custom env vars from
     shell profiles — it only reads PATH. Use Option B for Desktop.

  3. Verify:
     [ -n "${MEM0_API_KEY:-${CLAUDE_PLUGIN_OPTION_API_KEY:-}}" ] && echo "SET" || echo "NOT_SET"

用户确认后，重新运行验证命令。如果仍为 NOT_SET，请重复上述操作。如果为 SET，则继续步骤 2。

步骤 2：MCP 服务连接

首先，使用查询 "mem0 search_memories" 通过 ToolSearch 检查是否已能使用 MCP 工具。具体工具名称因安装方式而异（可能是 mcp__mem0__search_memories 或 mcp__plugin_mem0_mem0__search_memories）。

如果找到了 MCP 工具： 打印 - MCP 已连接。，然后继续步骤 3。

如果未找到 MCP 工具：

MCP 服务使用步骤 1 中设置的 MEM0_API_KEY 进行身份验证。无需 OAuth 或浏览器登录。

1. 验证 API 密钥已设置（重新运行步骤 1 中的检查）
2. 检查插件是否已安装：运行 /plugins 并确认其中显示 mem0
3. 检查 MCP 服务是否已列出：运行 /mcp 并查找 mcp.mem0.ai
4. 如果服务显示错误，请让用户重启 Claude Code，然后再次运行 /mem0:onboard
5. 如果所有检查均通过，但仍缺少工具：“重启 Claude Code，然后再次运行 /mem0:onboard。”

在此处停止 — 没有 MCP 工具时，不要继续。

步骤 3：验证连接并显示身份信息

调用 search_memories，并设置 query="project setup"、filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}、top_k=1，以验证连接。

打印：

- Connected
  user:    <user_id>
  project: <project_id>
  branch:  <branch>

如果搜索失败，请排查 API 密钥和 MCP 连接问题。

步骤 4：导入项目文件

会话启动时，项目文件（CLAUDE.md、AGENTS.md 等）会自动导入 mem0。此步骤用于检查导入状态，并在需要时触发重新导入。

4a：检测项目文件

for f in CLAUDE.md AGENTS.md .cursorrules .windsurfrules mem0.md; do
  [ -f "$f" ] && echo "FOUND: $f ($(wc -c < "$f") bytes)"
done || true

如果未找到文件，请打印 - 未找到项目文件。跳过导入。，然后继续步骤 5。

4b：检查并导入

在前台运行 auto_import，以检查状态，并在需要时导入：

MEM0_DEBUG=1 MEM0_CWD="$PWD" python3 "${CLAUDE_PLUGIN_ROOT}/scripts/auto_import.py"

4c：向用户报告

解析 auto_import 的输出，并打印易于用户理解的摘要：

• 如果输出包含 Imported 行：

  - Importing project files into mem0... done.
    <N> file(s) imported (<M> chunks). These are stored verbatim for future context.
  

• 如果输出仅包含 skipping 行：

  - Project files already in mem0 (imported during session start). Verified server-side.
  

• 如果输出包含 re-importing：

  - Project files were missing from mem0. Re-imported successfully.
  

• 如果输出包含错误或未处理任何文件：

  - Project file import failed. Check API key and retry with: /mem0:onboard
  

步骤 5：编码类别（自动）

针对开发工作流优化的编码类别会在会话启动时在后台自动安装，与导入项目文件（步骤 4）的方式相同。不再向用户询问。此步骤仅用于验证类别是否已就位，并在后台安装尚未完成时应用这些类别。

安装程序具有幂等性和自缓存功能：它会将现有类别与拟议类别集进行比较；如果两者已匹配，则跳过 API 调用；一旦为此账户应用了类别，便会完全跳过所有网络调用（仅在分类体系发生变化时重新应用）。可随时安全运行。

使用插件的 venv python 在前台运行，以进行验证：

VENV_PY="${CLAUDE_PLUGIN_DATA}/venv/bin/python3"
if [ -x "${VENV_PY}" ]; then
  MEM0_DEBUG=1 "${VENV_PY}" "${CLAUDE_PLUGIN_ROOT}/scripts/auto_setup_categories.py"
else
  MEM0_DEBUG=1 python3 "${CLAUDE_PLUGIN_ROOT}/scripts/auto_setup_categories.py"
fi

解析输出：

• 包含 Applied <N> coding categories → 输出：- 已安装编码类别（<N> 个类别）。
• 包含 already configured → 输出：- 编码类别已配置。
• 出错或包含 SDK not ready → 先运行依赖安装程序，然后重试：

"${CLAUDE_PLUGIN_ROOT}/scripts/ensure_deps.sh"

然后重试类别脚本。

步骤 6：摘要

输出摘要：

- Onboarding complete.
  user_id:    <user_id>
  project_id: <project_id> (app_id)
  files:      <N> found, <M> imported
  categories: <installed | already configured>

Memory is now active for this project. Start working — mem0 will
automatically search relevant context and capture learnings.

Run /mem0:tour to see what mem0 already knows about this project.