onboard

name	onboard
description	Sets up mem0 for a new project including API key configuration, MCP authentication, project file import, and coding categories. Use on first run in a new project, when API key needs updating, or to re-run initial setup after configuration changes.

Mem0 Onboarding Wizard

Run this wizard to set up the mem0 plugin for the current project. Complete in ~60 seconds.

IMPORTANT: Execute steps strictly in order (0 → 1 → 2 → 3 → 4 → 5 → 6). Each step depends on the previous one. Do NOT run steps in parallel or skip ahead. Complete one step fully before starting the next.

Step 0: Ensure mem0ai SDK is installed

The plugin installs the mem0ai Python SDK automatically on session start via a venv in ${CLAUDE_PLUGIN_DATA}/venv. If Step 5 (categories) fails with an import error, run:

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

This is silent and idempotent — safe to run anytime.

Step 1: Set up API key

Check if the API key is available from any source:

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

IMPORTANT: Never run echo $MEM0_API_KEY — that prints the secret in plaintext to the conversation log.

If API key IS set (output is "SET")

Print: - API key found. and proceed to Step 2.

If API key is NOT set (output is "NOT_SET")

Guide the user through API key setup. Show this message:

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"

After the user confirms, re-run the verify command. If NOT_SET, repeat. If SET, proceed to Step 2.

Step 2: MCP server connection

First, check if MCP tools are already available using ToolSearch with query "mem0 search_memories". The exact tool name varies by install method (may be mcp__mem0__search_memories or mcp__plugin_mem0_mem0__search_memories).

If MCP tools ARE found: Print - MCP already connected. and proceed to Step 3.

If MCP tools are NOT found:

The MCP server authenticates using the MEM0_API_KEY set in Step 1. No OAuth or browser login is needed.

1. Verify the API key is set (re-run the Step 1 check)
2. Check the plugin is installed: run /plugins and confirm mem0 appears
3. Check the MCP server is listed: run /mcp and look for mcp.mem0.ai
4. If the server shows an error, ask the user to restart Claude Code and run /mem0:onboard again
5. If all checks pass but tools are still missing: "Restart Claude Code and run /mem0:onboard again."

STOP here — do not proceed without MCP tools.

Step 3: Verify connectivity and show identity

Call search_memories with query="project setup", filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}, top_k=1 to verify connectivity.

Print:

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

If the search fails, troubleshoot the API key and MCP connection.

Step 4: Import project files

Project files (CLAUDE.md, AGENTS.md, etc.) are automatically imported into mem0 when a session starts. This step verifies import status and triggers a re-import if needed.

4a: Detect project files

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

If no files found, print - No project files found. Skipping import. and proceed to Step 5.

4b: Check and import

Run auto_import in foreground to check status and import if needed:

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

4c: Report to user

Parse the auto_import output and print a user-friendly summary:

• If output contains Imported lines:

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

• If output contains only skipping lines:

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

• If output contains re-importing:

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

• If output contains errors or no files were processed:

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

Step 5: Coding categories (automatic)

Coding categories optimized for development workflows are installed automatically in the background on session start — the same way project files are imported (Step 4). The user is no longer asked. This step only verifies they are in place and applies them if the background run hasn't finished yet.

The installer is idempotent and self-caching: it compares existing categories against the proposed set, skips the API call when they already match, and skips all network calls entirely once applied for this account (re-applying only if the taxonomy changes). Safe to run anytime.

Run it in the foreground to verify, using the plugin's 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

Parse the output:

• contains Applied <N> coding categories → Print: - Coding categories installed (<N> categories).
• contains already configured → Print: - Coding categories already configured.
• error or SDK not ready → run the dependency installer first, then retry:

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

Then retry the categories script.

Step 6: Summary

Print a summary:

- 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.