mem9

What this skill does

```
┌──────────────────────────────────────────────────────────────┐
│                                                              │
│   ███╗   ███╗███████╗███╗   ███╗ █████╗                      │
│   ████╗ ████║██╔════╝████╗ ████║██╔══██╗                     │
│   ██╔████╔██║█████╗  ██╔████╔██║╚██████║                     │
│   ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║ ╚═══██║                     │
│   ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║ █████╔╝                     │
│   ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚════╝                      │
│                                                              │
│   persistent memory for ai agents                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

# mem9

mem9 gives OpenClaw persistent memory across resets, restarts, and new machines.

The plugin connects to one cloud memory space, identified by an API key.

When talking to end users:

- Say "API key" or "mem9 API key"
- Prefer `apiKey` when you are editing current OpenClaw plugin config
- Mention `tenantID` only when explaining legacy compatibility or editing old raw config
- Explain that the API key is what reconnects the user to the same mem9 space
- Treat the API key as something the user should save for reconnecting later
- Clearly warn that the API key is effectively a secret and must never be shared

---

## Trigger phrases

Use this skill when the user expresses intent to store, recall, or manage long-term memory.

Common triggers include:

- "remember this"
- "save this for later"
- "don't forget that..."
- "what did I say last time?"
- "recall my preferences"
- "forget that"

---

## When to use this skill

Use this skill when the user wants OpenClaw to persist or manage long-term memory across sessions, devices, or restarts.

Typical situations include:

- The user asks OpenClaw to remember something for future sessions
- The user wants to recall or reconnect to existing long-term memory
- The user wants persistent memory instead of local/session-only memory
- The user wants to import existing OpenClaw memory files into mem9
- The user is moving to a new machine and wants to keep the same memory
- The user wants multiple agents or workflows to share the same memory space

---

## When NOT to use this skill

Do not use this skill for:

- Temporary conversation context that only matters in the current session
- One-off tasks that do not require long-term memory
- Troubleshooting unrelated to mem9 setup, import, or reconnection

---

## What should be remembered

Good candidates:

- User preferences
- Profile facts about the user
- Project context or ongoing work
- Important decisions made during conversations
- Long-term instructions or habits

Avoid storing:

- Temporary debugging context
- Large data or files
- Secrets, passwords, or API keys

---

## Memory intent detection

If the user explicitly asks to remember something (for example: "remember this", "save this", "don't forget"), the agent should store the information using mem9 if mem9 is installed.

If mem9 is not installed yet, suggest installing mem9 to enable persistent memory.

---

## Definition of Done

This task is NOT complete until all of the following are true:

1. mem9 API key is created or verified reachable
2. plugin is installed
3. openclaw.json is configured correctly
4. OpenClaw is restarted
5. setup is verified
6. the user has been sent the full Step 7 handoff message, including:

- next step: import memories
- API key warning
- recovery steps
- backup plan

---

## What You Get

| Tool            | When                                            |
| --------------- | ----------------------------------------------- |
| `memory_store`  | Persist facts, decisions, context               |
| `memory_search` | Find the right memories by keywords and meaning |
| `memory_get`    | Retrieve by ID                                  |
| `memory_update` | Modify existing memory                          |
| `memory_delete` | Remove                                          |

Lifecycle hooks (automatic — no agent action needed):

| Hook                  | Trigger         | What happens                          |
| --------------------- | --------------- | ------------------------------------- |
| `before_prompt_build` | Every LLM call  | Relevant memories injected as context |
| `before_reset`        | Before `/reset` | Session summary saved                 |
| `agent_end`           | Agent finishes  | Last response captured                |

---

## Common failure mode

Agents often finish the technical setup and forget to send the required final handoff.
Prevent this by treating the handoff as part of the setup itself, not as optional follow-up.

---

## Onboarding

### Terminology

Use this distinction consistently:

| Internal term     | User-facing explanation                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `apiKey`          | Preferred OpenClaw config field; sends the same mem9 API key in `X-API-Key` for v1alpha2 |
| `tenantID`        | Legacy OpenClaw config field; only mention for compatibility or old raw configs          |
| `API_KEY` env var | A local variable holding the user's mem9 API key                                         |
| `secret`          | Treat as the same value as the mem9 API key unless the user clearly means something else |
| "recovery key"    | Avoid this term; say "API key" instead                                                   |

Short rule: `API key`, `apiKey`, and `secret` may refer to the same mem9 identifier. Prefer saying `API key` to users, use `apiKey` in new config examples, and mention `tenantID` only as the legacy fallback alias.
Security note:
Treat the API key like a secret. Anyone who has it can access that mem9 space.

If the user asks "What is this for?" answer plainly:

> This is the API key that reconnects you to your mem9 space. OpenClaw uses it to save and recall your memory in the right place.

If the user asks "What is the relationship between tenantID and key?" answer plainly:

> You only need the API key. In current OpenClaw config, the preferred field is `apiKey`. `tenantID` is the legacy config field for the same value. Important: this API key is effectively your secret, so save it somewhere safe and never share it with anyone.

### Step 0 — Check for existing API key

`[AGENT]` Ask the user before doing anything else:

> Which setup do you want?
>
> 1. Create a new mem9 API key
> 2. Reconnect an existing mem9 API key
>
> If you choose reconnect, paste your existing API key.
>
> Heads-up: OpenClaw will restart later in this setup. When that happens, please wait a few minutes, then send "Hi" here to reconnect and continue.

Branching:

- If the user chooses reconnect and provides an API key, verify it first.
  - If reachable, continue to Step 2.
  - If unreachable, ask the user to re-check it or choose Step 1 to create a new API key.
- If the user chooses create, continue to Step 1.

```text
API_KEY="<paste-from-user>"
```

When the user provides an existing API key, verify it is reachable before continuing:

```bash
curl -sf \
  -H "X-API-Key: $API_KEY" \
  "https://api.mem9.ai/v1alpha2/mem9s/memories?limit=1" \
  && echo "OK" || echo "UNREACHABLE"
```

If the check returns `OK`, say:

> Great, your existing mem9 API key is reachable. I will keep going and connect this setup to that same memory.

If the check fails, say:

> I could not reach that API key. Please double-check it, or create a new mem9 API key instead.

**If no** — proceed to Step 1 to provision a new API key.

---

### Step 1 — Create a new mem9 API key

> Skip this step if the user provided an existing API key in Step 0.

`[AGENT]`

```bash
curl -sX POST https://api.mem9.ai/v1alpha1/mem9s | jq .
```

Response:

```json
{
  "id": "xxxxxxxx-x