onboard

What this skill does

# 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:

```bash
"${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:

```bash
[ -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

```bash
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:

```bash
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:

```bash
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:
```bash
"${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.
```