Skill: c4pt0r/mem9-ai (version 1.0.48)

--- name: mem9 version: 1.0.49 homepage: "https://mem9.ai/openclaw-memory" description: "Persistent cloud memory plugin for OpenClaw. This document routes setup, troubleshooting, and uninstall flows and defines config boundaries." keywords: ["mem9", "openclaw memory", "persistent memory", "cloud memory", "memory plugin", "setup mem9", "install mem9", "reconnect mem9", "uninstall mem9"] user-invocable: true metadata: {"openclaw":{"emoji":"🧠","homepage":"https://mem9.ai/openclaw-memory","primaryEnv":"MEM9_API_KEY"}} --- # mem9 mem9 is the persistent cloud memory plugin for OpenClaw. It keeps durable memory across sessions and machines. This top-level `SKILL.md` is a routing and safety document. It is the entry point for setup, troubleshooting, and uninstall flows. It is not the canonical reference for runtime request behavior. ## What This Skill Does - Route first-time install, reconnect, config review, and mainland China / Alibaba Cloud npm install handling to `SETUP.md`. - Route setup failures, recovery work, and broken local state to `TROUBLESHOOTING.md`. - Route local mem9 removal on this machine to `UNINSTALL.md`. - Preserve filtered `utm_*` params from a remote `SKILL.md` URL through the create-new setup flow and first restart. - Install mem9 only through `openclaw plugins install @mem9/mem9`; never substitute `npm install -g @mem9/mem9`, because OpenClaw does not discover global npm packages as plugins. - Prevent invalid compatibility fallbacks: never write `plugins.entries.mem9.apiKey`; only `plugins.entries.mem9.config.apiKey` is valid. - Configure OpenClaw 4.23+ hook permission with `plugins.entries.mem9.hooks.allowConversationAccess = true` so mem9 can read conversation messages during `agent_end`. - Keep create-new verification deterministic: if the first post-restart return message does not produce a key, run the one local OpenClaw agent trigger from `SETUP.md` in that same resumed turn; never ask for repeated `hi` messages. - In create-new mode, do not treat missing `plugins.entries.mem9.config.apiKey` as failure. The generated key is verified from mem9 logs or local provision state until the user explicitly reconnects with it. - Enforce the setup success onboarding handoff: every successful create-new or reconnect setup must end with the template that starts `✅ Your mem9 API key is connected.` followed by `🧭 WHAT YOU CAN DO NEXT`; never replace it with a brief success summary. - Keep API keys out of local memory/history notes during setup. Do not write the full key or a key preview into `MEMORY.md`, `memory/*.md`, or equivalent local logs; show the key only in the final onboarding handoff. - Keep restart notices honest: only claim post-restart verification has resumed after that work has actually started. - Keep history import manual. Do not scan or upload local memory or session files from this skill. ## Source / Runtime Authority - Official source: [mem9-ai/mem9](https://github.com/mem9-ai/mem9) and [mem9.ai](https://mem9.ai/). - Default setup network target is `https://api.mem9.ai` unless the user explicitly chooses another `apiUrl`. - The installed mem9 plugin contains the actual OpenClaw integration, request logic, default base URL handling, and runtime behavior. - This `SKILL.md` is not the backend API contract and does not define day-to-day memory semantics. - For OpenClaw-specific runtime details, use the plugin README: [openclaw-plugin/README.md](https://github.com/mem9-ai/mem9/blob/main/openclaw-plugin/README.md). ## Allowed Config Scope Only these `openclaw.json` paths may be changed during setup: - `plugins.slots.memory` - `plugins.entries.mem9.enabled` - `plugins.entries.mem9.hooks.allowConversationAccess` for OpenClaw 4.23+ / 2026.4.22+ only - `plugins.entries.mem9.config.apiUrl` - `plugins.entries.mem9.config.apiKey` - `plugins.entries.mem9.config.provisionToken` for create-new only; generate it once per create-new run before the first restart and keep it stable through the first successful post-restart provision on this machine - `plugins.entries.mem9.config.provisionQueryParams` for create-new only, and only when the remote `SKILL.md` URL contains filtered `utm_*` parameters; when present, it must be written before the first restart - `plugins.allow` Do not change any other config keys unless the user explicitly asks. The scope above is exhaustive. In particular, do not write `plugins.entries.mem9.apiKey` at the entry top level. OpenClaw rejects that key as invalid config before the mem9 plugin can load. ## Routing - Install, enable, reconnect, or review mem9 config changes: read `SETUP.md`. - Setup failures, broken reconnects, local cleanup issues, or recovery guidance: read `TROUBLESHOOTING.md`. - Uninstall, remove, disable, or roll back mem9 on this machine: read `UNINSTALL.md`. - If an uninstall request also mentions `reset session`, `restart gateway`, `重启网关`, clearing local mem9 history, or equivalent, still route to `UNINSTALL.md` first and keep those actions as post-verification follow-up only. - If this skill is loaded remotely, resolve `SETUP.md`, `TROUBLESHOOTING.md`, and `UNINSTALL.md` relative to the directory containing the current `SKILL.md`. ## Definition of Done - The correct supporting document was used for the user's intent: `SETUP.md`, `TROUBLESHOOTING.md`, or `UNINSTALL.md`. - No `openclaw.json` paths outside the allowed scope were changed. - Runtime behavior claims defer to the installed plugin and its README, not to this top-level routing document.

path: SETUP.md
content: # mem9 Setup

Use this file only for first-run mem9 onboarding or reconnect.

## First Reply

When this file is read, send only the choice prompt below. Do not include version checks, config paths, config keys, dry-run details, restart counts, or approval phrases in the first reply.

> I can help you set up mem9.
>
> Choose one path:
> 1. Create a new mem9 API key during setup
> 2. Reconnect an existing mem9 API key
>
> If you choose reconnect, paste your existing API key.

## Hard Rules

- Only edit the exact `openclaw.json` keys listed in `SKILL.md`.
- Do not upload local history, memory files, or session files during setup.
- Do not use raw mem9 API calls, direct web-request provisioning, or scripted shell patch commands as a substitute for the plugin flow.
- Do not write the generated or provided API key, even a preview, into local memory files, history notes, `MEMORY.md`, `memory/*.md`, session summaries, or setup logs. Show the key only in the final onboarding handoff.
- Install only with `openclaw plugins install @mem9/mem9`, optionally prefixed by one-shot `NPM_CONFIG_REGISTRY=https://registry.npmmirror.com`. Never substitute `npm install -g @mem9/mem9`, `npm install @mem9/mem9`, `npx`, or a copied npm package.
- Do not point `plugins.slots.memory` at `mem9` until the OpenClaw plugin install succeeds and OpenClaw recognizes plugin id `mem9`.
- Reconnect and create-new are separate branches. After the user chooses one, do not switch unless the user explicitly changes their choice.
- The only valid secret config path is `plugins.entries.mem9.config.apiKey`. Never write `plugins.entries.mem9.apiKey`.
- On OpenClaw `4.23+` / `2026.4.22+`, write `plugins.entries.mem9.hooks.allowConversationAccess = true` as a sibling of `enabled` and `config`. On older versions that reject it, omit it and tell the user full automatic conversation upload requires an OpenClaw upgrade.
- In create-new mode, generate `PROVISION_TOKEN` once after the branch is selected, write it before the first restart, and keep it stable until provisioning succeeds on this machine.
- If the remote `SKILL.md` URL has query params whose keys start with `utm_`, preserve those exact filtered pairs as `REMOTE_SKILL_UTM_PARAMS` and write them only in create-new mode under `plugins.entries.mem9.config.provisionQueryParams`.
- Show one dry-run preview and get one approval for the disclosed install, config, restart, and verification flow. Ask for another approval only if scope materially changes.
- Do not ask the user for repeated `hi` messages while the only missing step is create-new provisioning. Use the one local trigger in this document.
- If install fails, stale local plugin state blocks install, config is already invalid, reconnect auto-provisions a new key, multiple create-new keys appear, or the documented checks cannot be satisfied, stop and use `TROUBLESHOOTING.md`.

## Required Success Handoff

This template is intentionally near the top so remote reads see it even if later sections are truncated.

Once reconnect or create-new success criteria are met, the next user-facing assistant message must be exactly this onboarding handoff with the real key substituted. Do not replace it with a short summary such as `done`, `搞定`, `安装成功`, or diagnostic bullets. Include the full API key exactly once. Do not append log analysis, trigger details, apology text, or extra status notes after it.

```text
✅ Your mem9 API key is connected.
🧭 WHAT YOU CAN DO NEXT

You can also go to https://mem9.ai/your-memory/ to visually manage, analyze, import, and export your memories.
Sign in there with the same mem9 API key from this setup.
If the dashboard still shows "Space ID", enter the same mem9 API key.
Use the dashboard or another reviewed manual workflow if you want to import older history later.
This setup did not upload any local files.
If you later ask me to remember something, I should write it to mem9 and tell you whether the write succeeded.


💾 YOUR MEM9 API KEY

MEM9_API_KEY: <api-key-from-this-setup>

Use this same value as MEM9_API_KEY in recovery or on another trusted machine.
Keep it private and store it somewhere safe.


♻️ RECOVERY

Reinstall mem9 and use the same MEM9_API_KEY in the plugin config.
Your memory will reconnect instantly.


📦 BACKUP PLAN

Keep your original local memory/session files as backup if you plan to import them later.
Also store MEM9_API_KEY in a password manager or secure vault.
```

## Setup Flow

### 1. Choose Branch And Approve

- If the user chooses reconnect, store the pasted key as `USER_PROVIDED_MEM9_API_KEY`.
- If the user chooses create-new, generate and remember `PROVISION_TOKEN`; do not ask the user for an API key.
- If `REMOTE_SKILL_UTM_PARAMS` exists, keep that exact map for create-new.
- Do not probe a key with standalone API calls. Verification happens through OpenClaw loading the plugin.

Before taking action, send one dry-run preview in the user's language. It must include:

- package: `@mem9/mem9`
- install command family: `openclaw plugins install @mem9/mem9`
- selected branch: reconnect or create-new
- exact config keys that may change
- expected restart count: normally 1
- local history will not be uploaded
- restart-and-return instruction: gateway restarts automatically; return to this chat in a few minutes and send `hi`

The config key list must include:

- Always: `plugins.slots.memory`, `plugins.entries.mem9.enabled`, `plugins.entries.mem9.config.apiUrl`, `plugins.allow`
- OpenClaw `4.23+` / `2026.4.22+`: `plugins.entries.mem9.hooks.allowConversationAccess`
- Reconnect only: `plugins.entries.mem9.config.apiKey`
- Create-new only: `plugins.entries.mem9.config.provisionToken`
- Create-new with UTM only: `plugins.entries.mem9.config.provisionQueryParams`

Required approval phrases:

```text
approve reconnect
approve create
```

After approval, send a short notice before running commands:

```text
Approved. I’m starting mem9 setup now.

The gateway will restart automatically; return to this chat in a few minutes and send hi.
```

Use equivalent wording in the user's language. Do not claim post-restart verification has already started.

### 2. Install Plugin

Check registry reachability first. Use the official registry unless it times out or is materially slower than npmmirror; never change global npm config.

```bash
NPMJS_TIME="$(curl -o /dev/null -sS --connect-timeout 2 --max-time 6 -w '%{time_total}' https://registry.npmjs.org/@mem9%2fmem9 || echo timeout)"
MIRROR_TIME="$(curl -o /dev/null -sS --connect-timeout 2 --max-time 6 -w '%{time_total}' https://registry.npmmirror.com/@mem9%2fmem9 || echo timeout)"
```

If npmjs times out, or npmjs is slow while npmmirror is reachable, run:

```bash
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins install @mem9/mem9
```

Otherwise run:

```bash
openclaw plugins install @mem9/mem9
```

After install, confirm OpenClaw recognizes plugin id `mem9`. If only a global npm install happened, or OpenClaw reports `plugin not found: mem9`, setup has not succeeded; use `TROUBLESHOOTING.md`.

Before any restart, send a short user-facing notice that the plugin is installed and the gateway restart is next. Do not stop and wait for another approval.

### 3. Detect OpenClaw Version

Run:

```bash
openclaw --version
```

Routing:

- `>= 2.2.0`: include `plugins.allow`.
- `< 2.2.0`: omit `plugins.allow`.
- `4.23+` or date-style `2026.4.22+`: include `hooks.allowConversationAccess = true`.
- Older versions: omit `hooks.allowConversationAccess` and tell the user to upgrade OpenClaw for full automatic conversation upload.
- If the version is unavailable or unclear, ask the user before editing config.

### 4. Write Config And Read It Back

Preserve unrelated config. Apply mem9 config in one contiguous update after install succeeds.

Common shape:

```json
{
  "plugins": {
    "slots": { "memory": "mem9" },
    "entries": {
      "mem9": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "apiUrl": "https://api.mem9.ai"
        }
      }
    },
    "allow": ["mem9"]
  }
}
```

For reconnect, add:

```json
"apiKey": "<USER_PROVIDED_MEM9_API_KEY>"
```

For create-new, do not write `apiKey` before the first restart. Add:

```json
"provisionToken": "<PROVISION_TOKEN>"
```

If create-new has UTM params, also add:

```json
"provisionQueryParams": {
  "utm_source": "example"
}
```

Before restart, read config back and require:

- `plugins.slots.memory = "mem9"`
- `plugins.entries.mem9.enabled = true`
- `plugins.entries.mem9.config.apiUrl` is present
- OpenClaw `4.23+` / `2026.4.22+`: `plugins.entries.mem9.hooks.allowConversationAccess = true`
- OpenClaw `>= 2.2.0`: `plugins.allow` contains `"mem9"`
- Reconnect: `plugins.entries.mem9.config.apiKey` exactly equals `USER_PROVIDED_MEM9_API_KEY`
- Create-new: `plugins.entries.mem9.config.apiKey` is absent, and `plugins.entries.mem9.config.provisionToken` exactly equals `PROVISION_TOKEN`
- Create-new with UTM: `plugins.entries.mem9.config.provisionQueryParams` exactly equals `REMOTE_SKILL_UTM_PARAMS`

Do not restart until read-back passes. If it cannot pass, use `TROUBLESHOOTING.md`.

### 5. Restart And Resume

Restart the gateway once after read-back passes:

```bash
openclaw gateway restart
```

Tell the user to return to this chat in a few minutes and send `hi`.

When the user returns, resume verification automatically. Send at most one short progress sentence in the user's language after checks have actually started. Do not ask whether to continue.

Reconnect verification:

- Confirm OpenClaw loads mem9 without plugin/config errors.
- Confirm the plugin can reach `https://api.mem9.ai` or shows positive mem9 health logs.
- Confirm reconnect did not auto-provision a different key.
- Empty memory results are acceptable.

Create-new verification:

- Provisioning runs from the mem9 plugin's `before_prompt_build` hook on an OpenClaw agent turn. The user's post-restart `hi` is a resume signal; do not assume that same control chat already ran gateway/plugin hooks.
- Do not check only `plugins.entries.mem9.config.apiKey`; it stays absent by design.
- Check recent mem9 logs and the matching local state under `~/.openclaw/mem9/provision/`.
- Matching state is keyed by `sha256(JSON.stringify({apiUrl, provisionToken, provisionQueryParams: sortedProvisionQueryParams})) + ".json"`, where missing `provisionQueryParams` is `{}`.
- If no generated key is found and there is no mem9 startup/config error, run exactly one local OpenClaw agent turn in the same resumed turn:

```bash
openclaw agent --session-id mem9-setup-provision --message "mem9 setup trigger: reply with OK only" --timeout 180 --json
```

- Re-check logs and provision state after that trigger.
- If a stable generated key exists, use it as `MEM9_API_KEY` in the final handoff.
- Do not schedule a second restart just to persist `apiKey` in `openclaw.json`.
- If no key appears after the one trigger, use `TROUBLESHOOTING.md`; do not ask for another `hi`.

Positive mem9 health signals include:

- `[mem9] Injecting N memories into prompt context`
- `[mem9] Ingest accepted for async processing`
- `[mem9] Ingested session: memories_changed=...`
- `[mem9] *** Auto-provisioned apiKey=...`
- `[mem9] reusing locally persisted create-new API key for this provisionToken`
- `[mem9] Server mode (v1alpha2)` with no later startup error

If recent logs contain a positive health signal, treat mem9 as healthy even if `openclaw status` briefly says `enabled (plugin mem9) · unavailable`.

### 6. Finish

Success requires:

- plugin install completed through OpenClaw
- config read-back passed before restart
- gateway restarted
- plugin loaded without mem9 startup/config errors
- reconnect: active key is still `USER_PROVIDED_MEM9_API_KEY`
- create-new: one stable generated key was verified from logs or local provision state

When success is reached, send the Required Success Handoff template from this file immediately. Do not replace it with a summary and do not append diagnostics.

## Post-Setup Use

- After setup succeeds, do not route `remember this`, `save this for later`, `save this to mem9`, `don't forget this`, `记住`, `记下来`, or `保存一下` back into setup.
- Treat explicit remember/save requests as direct mem9 write requests.
- Preserve the user's original language in saved memory content.
- For explicit writes, attempt the actual mem9 write path before replying, then say only whether the write succeeded or failed in the user's language.
- If the user asks whether something was recorded in mem9, confirm from actual mem9 write state rather than inferring from an earlier reply.


path: TROUBLESHOOTING.md
content: # mem9 Troubleshooting

Use this file for reconnect, setup failures, uninstall failures, and dashboard/login confusion after the main mem9 flow.

## Quick Checks

Confirm these first:

- `plugins.slots.memory` is set to `mem9`
- `plugins.entries.mem9.enabled` is `true`
- `plugins.entries.mem9.config.apiUrl` points to the intended mem9 API
- `plugins.entries.mem9.config.apiKey` is present for the steady-state reconnect flow
- In reconnect mode, the read-back value of `plugins.entries.mem9.config.apiKey` exactly matches the user's original key before the first restart
- On OpenClaw `4.23+` / `2026.4.22+`, `plugins.entries.mem9.hooks.allowConversationAccess` is `true`
- On OpenClaw `>= 2.2.0`, `plugins.allow` includes `mem9`

## Common Issues

### Plugin Does Not Load

- Re-check the memory slot and enabled flag
- Re-check that the mem9 package was installed successfully
- Re-check that the config only edits the exact mem9 keys and does not corrupt unrelated JSON

### Install Hit `plugin not found: mem9`

- Treat this as setup ordering failure, not as an API-key problem
- Re-check whether the flow wrote `plugins.slots.memory = "mem9"` before `openclaw plugins install @mem9/mem9` succeeded
- Re-check whether `plugins.entries.mem9` or `plugins.allow += "mem9"` were also written before install success
- If yes, fix the ordering bug in the setup flow: install first, then apply all disclosed mem9 config in one contiguous update
- If the machine is already stuck in that invalid state, temporarily restore only the currently valid memory slot and remove only the premature mem9 wiring, then install the plugin, then re-apply the approved mem9 config
- Do not require a fresh extra approval for that missing-plugin recovery when it is only undoing the same mem9 wiring disclosed in the original setup scope

### Create-New Flow Did Not Return A Key

- Make sure the first restart happened with `plugins.entries.mem9.config.apiKey` absent
- Make sure `plugins.entries.mem9.config.provisionToken` was present and stable before that restart
- Make sure the first resumed user message after that restart actually reached the plugin hook path
- Make sure that resumed turn produced exactly one generated key in logs
- If the first resumed turn did not produce a key, stop the first-run flow and ask the user whether to retry the clean create-new flow or switch to reconnect with an existing API key

### Create-New Flow Did Not Carry Expected UTM Params

- If the setup started from a remote `SKILL.md` URL with `utm_*`, re-check whether `plugins.entries.mem9.config.provisionQueryParams` was disclosed in the dry-run preview
- Re-check the config read-back from before the first restart
- The pre-restart read-back must exactly match the filtered `utm_*` map from the remote `SKILL.md` URL
- If `provisionQueryParams` was absent, partial, renamed, or different before the first restart, do not assume the generated key was attributed correctly
- In that case, stop the happy-path create-new handoff and decide whether to re-run create-new cleanly or switch to reconnect

### Create-New Flow Generated Multiple Keys

- Treat this as abnormal create-new behavior, not as automatic success
- Do not silently keep the latest key without checking the earlier provision attempts
- Re-check whether `plugins.entries.mem9.config.provisionToken` was already present before the first successful provision and stayed unchanged for the whole create-new run
- Re-check whether `plugins.entries.mem9.config.provisionQueryParams` was already present before the first successful provision
- Re-check whether more than one post-restart provision attempt ran before the first key was reused locally
- Re-check whether startup logs show an unexpected provision before the first resumed user message
- Re-check whether later logs reused the same locally persisted key for the same `provisionToken`
- If attribution or final-key correctness cannot be confirmed, stop and troubleshoot instead of handing off the newest key
- If the installed plugin version is older than `@mem9/mem9@0.4.7`, upgrade first; newer builds provision only from the first post-restart user message and also reuse one local result across duplicate setup retries

### Restart Returned But The Setup Kept Waiting For Another `hi`

- One short post-restart `hi` is normal because the gateway restart cuts the current execution turn
- More than one extra `hi` without another real restart is abnormal orchestration behavior
- Re-check the restart logs for a second config-driven restart caused by splitting install/config into multiple phases
- Re-check whether the user-facing resume message was sent before post-restart verification had actually started
- Re-check whether the flow was still waiting on an internal plugin tool or another non-user-reachable interface
- If the flow asked for another keepalive without a new restart, stop the happy path and treat it as setup orchestration failure, not as normal mem9 onboarding behavior

### Gateway Aborted After Adding `plugins.entries.mem9.apiKey`

- Treat this as setup orchestration failure, not as a mem9 runtime failure
- `plugins.entries.mem9.apiKey` at the entry top level is not a supported compatibility fallback
- OpenClaw rejects that key before the mem9 plugin can load
- Remove only the invalid top-level `plugins.entries.mem9.apiKey`
- Keep the real secret only at `plugins.entries.mem9.config.apiKey`
- Read back the config again before restarting
- Do not keep experimenting with duplicate secret fields outside the documented mem9 config scope

### Existing API Key Fails After Reconnect

- Re-check the value for typos
- Re-check `apiUrl`
- Re-check that the same API key was written to `plugins.entries.mem9.config.apiKey`
- Re-check that config was read back before restart and matched the user-provided key exactly
- Re-check for OpenClaw plugin or config errors after restart

### Existing API Key Was Replaced By A New Auto-Provisioned Key

- Treat this as reconnect failure, not success
- Do not hand off the auto-provisioned key to the user
- Re-check the write order: the user-provided key must be saved before the first restart
- Re-check the exact config path: `plugins.entries.mem9.config.apiKey`
- Re-check the read-back value from `openclaw.json` before the first restart
- Rewrite the original user-provided key to the correct field
- Restart and verify again
- If a new key is still auto-provisioned after that, stop the reconnect flow and keep troubleshooting instead of silently switching mem9 spaces

### Plugin Loads But Conversations Are Not Uploaded

- Treat this as missing OpenClaw hook permission before treating it as a mem9 API failure
- Re-check whether gateway logs contain `[mem9] agent_end conversation messages are unavailable`
- On OpenClaw `4.23+` / `2026.4.22+`, set `plugins.entries.mem9.hooks.allowConversationAccess = true`
- Keep `allowConversationAccess` as a sibling of `enabled` and `config`; do not put it under `plugins.entries.mem9.config`
- Restart OpenClaw after writing the hook policy
- On older OpenClaw versions that reject `hooks.allowConversationAccess`, upgrade OpenClaw before expecting full automatic conversation upload from `agent_end`

### Reconnect Looked Broken, But Logs Already Show mem9 Activity

- If recent logs already show `[mem9] Injecting N memories into prompt context`, `[mem9] Ingest accepted for async processing`, or `[mem9] Ingested session: memories_changed=...`, mem9 is already operational
- Do not keep troubleshooting just because `openclaw status` still says `enabled (plugin mem9) · unavailable`
- Do not add top-level compatibility keys such as `plugins.entries.mem9.apiKey` after positive health signals already appeared
- Treat the remaining problem as host-side status reporting or session orchestration, not as a mem9 credential failure
- Resume the normal success handoff once the active key and current config read-back are confirmed

### Memory Shows Unavailable In Status But Plugin Is Working

- `openclaw status` may briefly show `enabled (plugin mem9) · unavailable` after a restart
- This is a known transient state caused by OpenClaw's status probe timing out before the plugin finishes its first API call
- Check recent gateway logs for positive health signals:
  - `[mem9] Injecting N memories into prompt context`
  - `[mem9] Ingest accepted for async processing`
  - `[mem9] Server mode (v1alpha2)` with no subsequent startup error
- If any positive signal is present, the plugin is healthy — ignore the `unavailable` status
- If no positive signal appears after 2+ minutes and the logs show repeated timeouts, check network connectivity to the configured `apiUrl`
- Do not re-run setup or treat this as a setup failure when logs confirm the plugin is operational

### Create-New Provisioned A Key, But The Chat Or Gateway Looked Hung

- If gateway logs already show `[mem9] *** Auto-provisioned apiKey=... *** Save this for recovery or reconnect as apiKey`, create-new already reached the mem9 API
- If the same restart window also shows host/session errors such as `refresh_token_reused`, `ws-stream` `401`, or repeated auth fallback logs, treat those as host resume problems, not as create-new failure
- Do not rerun create-new or rotate to a different key just because the final handoff reply was interrupted
- First confirm that later mem9 logs reuse the same provisioned key or continue without mem9 startup errors
- Then either finish the setup handoff or troubleshoot the host auth/session issue separately from mem9 onboarding

### Removed mem9 But Gateway Will Not Start

- Treat this as uninstall failure, not success
- First re-check the current config read-back
- The most common cause is `plugins.slots.memory` still pointing to `mem9`
- If logs show `config reload skipped (invalid config): plugins.slots.memory: plugin not found: mem9` or `Invalid config ... plugin not found: mem9`, treat that as local rollback failure, not a mem9 cloud problem
- If logs show `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`, treat that as unmanaged local install residue, not as successful uninstall
- If logs show `plugins.entries.memory-core: plugin disabled (disabled in config) but config is present`, treat that as rollback failure. The default memory plugin was not restored cleanly yet.
- Also re-check whether `plugins.entries.memory-core.enabled = true` after restoring the default memory slot
- Re-check that `plugins.entries.mem9` was removed
- Re-check that `plugins.installs.mem9` was removed if it existed before
- Re-check that `"mem9"` is no longer present in `plugins.allow`
- Re-check whether `~/.openclaw/extensions/mem9` still exists locally and remove it if the uninstall command did not
- After the config read-back, inspect the gateway logs for the exact startup error
- If the config still matches the uninstall failure pattern, re-apply the safe rollback from `UNINSTALL.md` before trying another restart

### Reinstall Fails Because The mem9 Plugin Already Exists Locally

- Treat this as local uninstall residue, not an API-key problem and not a mem9 cloud problem
- The common pattern is:
  - uninstall appeared to finish
  - config rollback succeeded
  - `plugins.installs.mem9` may already be gone
  - later reinstall fails with `plugin already exists`
  - a stale local extension directory still exists at `~/.openclaw/extensions/mem9`
- Re-check whether the local extension directory is still present
- If it is, remove that stale local mem9 extension directory
- Then rerun the mem9 install flow
- Do not continue into config write or restart until the stale local extension directory issue is resolved

### Gateway Became Unhealthy After mem9 Uninstall

- Treat this as uninstall orchestration failure, not a mem9 remote API problem
- The most common cause is that uninstall rollback already triggered one deferred restart, and the flow then added another explicit restart or a current-session reset on top
- Another common cause is that plugin removal happened before the config rollback had finished, leaving `plugins.slots.memory` pointing at a plugin that no longer exists
- Another common cause is that `openclaw plugins uninstall mem9 --force` failed with `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`, leaving `~/.openclaw/extensions/mem9` behind as unmanaged local residue
- Another common cause is that the rollback switched the slot away from mem9 but left `memory-core` disabled, which shows up as `plugins.entries.memory-core: plugin disabled (disabled in config) but config is present`
- First inspect gateway reload logs for:
  - `config change requires gateway restart`
  - `deferring until ... complete`
  - `config reload skipped (invalid config): plugins.slots.memory: plugin not found: mem9`
- Then check for:
  - `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`
  - `plugins.entries.memory-core: plugin disabled (disabled in config) but config is present`
  - `Invalid --scope. Expected "config", "config+creds+sessions", or "full".`
- Then check whether a second `SIGTERM` happened after the gateway had already come back once
- Then check whether runtime is `inactive` while the gateway port is still in use
- If that pattern is present, do not keep re-running uninstall steps blindly
- Re-check the current config read-back
- If the uninstall command reported `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`, stop retrying that uninstall command and remove `~/.openclaw/extensions/mem9` after the rollback config is safe
- If `Invalid --scope. Expected "config", "config+creds+sessions", or "full".` appears right after uninstall actions, treat that as an out-of-band session-reset attempt and stop adding reset or restart actions
- If the config still shows the uninstall-failure shape, re-apply the safe rollback from `UNINSTALL.md` before trying anything else
- Let the gateway return to a healthy steady state with the rollback config in place before suggesting a new session or manual session reset
- Do not attribute this pattern to remote mem9 cloud availability

### User Asked To Remember, Recall, Or Forget After Setup, But mem9 Did Not Handle It Correctly

- First decide whether the user said `remember this`, `save this for later`, `save this to mem9`, `don't forget this`, `what did I say last time?`, `recall my preferences`, `forget that`, `记住`, `记下来`, `保存一下`, `别忘了`, `我上次说过什么`, `回忆一下我的偏好`, `忘掉这件事`, or equivalent
- If yes, do not treat it as a setup-success question and do not re-run onboarding
- Route remember or save requests to the direct mem9 write path
- Route recall requests such as `what did I say last time?` to the mem9 recall or search path
- Route forget requests to mem9 memory-management behavior
- Do not accept background or delayed auto-capture as the success signal for an explicit write request
- If the write or recall still fails, then troubleshoot write-path availability, plugin load state, and mem9 API reachability
- Interpret equivalent remember, recall, and forget intent in any language
- Do not send an unverified conversational acknowledgment unless mem9 actually stored or returned the memory
- Do not tell the user about internal tool names, interface exposure, or background-ingest mechanics

### Assistant Said It Could Not Write Because No Direct mem9 Interface Was Available

- Treat that as a documentation failure, not an acceptable final user-facing reply
- The correct user-facing outcome is still short and operational:
  - a short success confirmation in the user's language
  - or a short failure reason in the user's language
- Keep internal diagnosis internal
- If needed, troubleshoot the write path, plugin load state, and mem9 API reachability without narrating those implementation details back to the user

### User Returned After Restart But Verification Is Still In Progress

- This usually means the gateway restart finished but verification has not completed yet
- Resume verification automatically; do not ask whether the user wants to continue
- First check gateway status, recent mem9-related logs, and the current config read-back
- Tell the user clearly that verification is resuming after the restart and that final success has not been declared yet
- Default to "no action needed right now" unless the verification step truly needs new user input
- Do not send the final success handoff until verification is actually complete
- If there was a real interruption beyond the normal restart, say exactly which step was incomplete and what you are resuming now instead of using vague phrases like `mid-flight` or `system event`

### Dashboard Still Shows "Space ID"

- In the current dashboard, `Space ID` may still refer to the same mem9 credential
- Enter the same `MEM9_API_KEY`

### China Network / npm Registry Problems

- Retry installation with a temporary npm mirror such as `https://registry.npmmirror.com`
- Avoid changing the user's global npm config unless they explicitly ask

## Reconnect On A New Machine

- Install the mem9 plugin
- Write the same `MEM9_API_KEY` into `plugins.entries.mem9.config.apiKey`
- Keep the same `apiUrl` unless the user intentionally changed servers
- Restart OpenClaw

## Legacy Compatibility

- `tenantID` is a legacy alias for the same mem9 credential
- Prefer `apiKey` for new config
- If old config only has `tenantID`, reconnect using the same value and plan a later cleanup to `apiKey`


path: UNINSTALL.md
content: # mem9 Uninstall

Use this file only when the user explicitly wants to remove mem9 from this machine.

## First Reply

When this file is read, start with this structure:

> I can help you uninstall mem9 from this machine and restore OpenClaw's local memory config.
>
> This removes the local mem9 plugin wiring and local mem9 install residue from this machine.
> It does not delete remote mem9 cloud data.
> It does not revoke your mem9 API key.
> It does not reset the current chat session as part of this uninstall flow.
>
> I will show one dry-run preview and ask for a single approval for the full uninstall flow.

## Safety Rules

- Only remove or restore the local OpenClaw keys needed to stop using mem9 on this machine.
- Treat the local mem9 extension directory under `~/.openclaw/extensions/mem9` as part of uninstall scope.
- Do not promise remote mem9 data deletion from this uninstall flow.
- Do not revoke or rotate the user's mem9 API key from this uninstall flow.
- Do not leave OpenClaw in an intermediate state where `plugins.slots.memory` still points to `mem9` after the plugin is gone.
- Do not perform `reset session` or any equivalent current-session reset inside this uninstall flow.
- Do not trigger a second explicit gateway restart after the config rollback has already scheduled or completed the required restart.
- If the user asks to clear local mem9 memories, interpret that as local mem9 plugin/config/install residue cleanup only. Do not add session reset to the uninstall execution steps.
- Preserve unrelated config keys.
- Use one explicit approval for the entire disclosed flow. Do not ask for a second approval unless the scope materially changes.

## Step 0 — Dry-Run Preview And Approval

- Before making any changes, show one dry-run preview.
- The preview must include:
  - plugin id: `mem9`
  - package family being removed: `@mem9/mem9`
  - local mem9 install residue may be removed from `~/.openclaw/extensions/mem9`
  - exact config keys that may change
  - expected restart count: `1`
  - that this flow does not delete remote mem9 data
  - that this flow does not reset the current chat session automatically
  - a short restart-and-return instruction in the user's language that says the gateway will restart automatically, the user should return to this chat in a few minutes, and the user should say `hi`
- Approval phrase:
  - `approve uninstall`

Required prompt structure:

```text
Dry-run preview:
Plugin to remove: mem9
Package family: @mem9/mem9
Local install residue that may be removed: ~/.openclaw/extensions/mem9
Exact config keys that may change only:
plugins.slots.memory
plugins.entries.memory-core.enabled
plugins.entries.mem9
plugins.installs.mem9
plugins.allow
Expected restarts: 1
Remote mem9 data deletion: will not happen in this uninstall flow
Current session reset: will not happen automatically in this uninstall flow

If that looks good, reply exactly:

approve uninstall

[Then send one short restart-and-return instruction in the user's language telling the user that the gateway will restart automatically, they should return to this chat in a few minutes, and they should say `hi`.]
```

## Step 1 — Prepare Config Rollback

Before uninstalling the plugin:

- Show the exact keys that will change.
- Prepare the final safe local config state first.
- Apply the rollback in one config edit so the gateway never restarts with `plugins.slots.memory = "mem9"` after mem9 is gone.
- Immediately read back the edited config before uninstalling the plugin.
- If the read-back still shows `plugins.slots.memory = "mem9"`, missing `plugins.entries.memory-core.enabled = true` when restoring `memory-core`, remaining `plugins.entries.mem9`, remaining `plugins.installs.mem9`, or `"mem9"` still present in `plugins.allow`, stop and fix the rollback before continuing.
- If the user asked to `reset session`, acknowledge that as a follow-up suggestion after uninstall verification completes. Do not include it in the actual uninstall execution steps.
- If the user later still wants a separate session reset after uninstall, first confirm this OpenClaw version has a session-only reset path before running any reset command. Do not silently substitute a broader reset scope.

Rollback rules:

- If `plugins.slots.memory = "mem9"`, set `plugins.slots.memory = "memory-core"`.
- If the memory slot is being restored to `memory-core`, set `plugins.entries.memory-core.enabled = true`.
- Delete `plugins.entries.mem9` if it exists.
- Delete `plugins.installs.mem9` if it exists.
- Remove `"mem9"` from `plugins.allow` if it exists there.
- If `plugins.slots.memory` is already some non-mem9 value, do not overwrite that slot.
- Do not change any unrelated keys.

For OpenClaw `< 2.2.0`, use the same rollback shape without `plugins.allow`.

## Step 2 — Uninstall Plugin

Preferred command:

```bash
openclaw plugins uninstall mem9 --force
```

Hard rules:

- Use the approval already obtained in Step 0.
- Only continue if the rollback read-back already matches the safe non-mem9 state.
- If `plugins.installs.mem9` is already absent before uninstall but `~/.openclaw/extensions/mem9` still exists, treat that as unmanaged local install residue and skip straight to local extension cleanup instead of retrying `openclaw plugins uninstall mem9 --force`.
- If the uninstall command leaves any mem9 config residue behind, fix the config before restart.
- The plugin directory or install record may be removed by the uninstall command; do not rely on mem9 still being loadable after this step.
- The uninstall is not complete unless the local mem9 extension directory is absent after cleanup.
- If config rollback succeeds but the local mem9 extension directory under `~/.openclaw/extensions/mem9` still exists, treat that as uninstall failure, not success.
- If the rollback config already caused OpenClaw to schedule a deferred restart, treat that deferred restart as the only restart for this uninstall flow.
- If the uninstall command prints `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`, treat that as unmanaged local install residue, not as successful uninstall.
- In that unmanaged-local-install case, stop retrying `openclaw plugins uninstall mem9 --force`, remove `~/.openclaw/extensions/mem9` after the rollback config is already in the safe non-mem9 state, and continue verification from there.
- If any out-of-band session-reset command errors with `Invalid --scope. Expected "config", "config+creds+sessions", or "full".`, treat that as uninstall orchestration failure. Stop adding reset or restart actions and continue only with rollback verification plus the single required gateway restart.

## Step 3 — Restart Flow

Before restart, send this notice:

```text
Approved. I’m starting mem9 uninstall now.

[Then send one short restart-and-return instruction in the user's language.]
```

The restart-and-return instruction must stay short and must tell the user all three points:

- the gateway will restart automatically
- the user should return to this same chat in a few minutes
- the user should say `hi`

- Use one restart only.
- If the rollback config or uninstall step already triggered a deferred gateway restart, do not issue another explicit restart command.
- If the logs already show `config change requires gateway restart` and `deferring until ... complete`, wait for that queued restart instead of starting another restart path.
- Do not reset the current session before or after the restart.
- If the user asked for `reset session`, acknowledge it only as a separate follow-up option after the gateway is healthy again.
- If that later follow-up reset is attempted, first verify a session-only reset command exists for this CLI version, for example via `openclaw reset --help`. Do not broaden the scope automatically.
- When the user returns and sends `hi` or another short message, resume verification automatically.
- Do not ask `Want me to continue?`
- The first resume reply must stay short and user-facing, for example:
- Keep user-facing restart and resume notices in the user's language instead of replaying fixed English strings verbatim.

```text
Resuming mem9 uninstall verification after the gateway restart now. You do not need to do anything right now.
```

## Step 4 — Verify

Success criteria:

- The gateway is running normally.
- The gateway no longer reports `plugins.slots.memory: plugin not found: mem9`.
- The active memory slot is not `mem9`.
- The current config read-back matches the rollback target before success is declared.
- `plugins.entries.mem9` is gone.
- `plugins.installs.mem9` is gone if that install record existed before.
- `"mem9"` is no longer present in `plugins.allow` if that allowlist exists.
- The local mem9 extension directory under `~/.openclaw/extensions/mem9` is absent.
- If the memory slot was restored to `memory-core`, `plugins.entries.memory-core.enabled = true`.
- No extra uninstall-time `reset session` or second explicit restart was attempted after the first required restart was already in flight.
- If the uninstall command had reported `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`, that unmanaged local residue path was completed and the extension directory is now absent.

Failure rules:

- If the gateway does not come back up cleanly, do not declare success.
- If `plugins.slots.memory` still points to `mem9`, treat the uninstall as failed and fix config first.
- If the config read-back still matches the uninstall-failure pattern even once after restart, treat the uninstall as failed and re-apply the safe rollback before any further uninstall or restart action.
- If the local mem9 extension directory is still present after uninstall, treat the uninstall as failed and keep cleaning local residue before declaring success.
- If the logs include `Plugin "mem9" is not managed by plugins config/install records and cannot be uninstalled.`, do not retry the uninstall command as the primary fix. Remove the local extension directory and re-verify the rollback config instead.
- If the logs include `Invalid --scope. Expected "config", "config+creds+sessions", or "full".`, treat that as an out-of-band reset attempt and do not add another reset or restart during the same uninstall flow.
- If verification fails, use `TROUBLESHOOTING.md` from the same directory.

## Step 5 — Required Final Handoff

Use this exact structure after successful verification:

```text
mem9 has been removed from this machine.

What changed locally:
- OpenClaw is no longer using the mem9 plugin for the memory slot
- mem9 config and install references were removed
- local mem9 install residue was removed from this machine
- the gateway restarted successfully

Important:
- This uninstall did not delete any remote mem9 cloud data
- This uninstall did not revoke your mem9 API key
- This uninstall did not reset the current chat session automatically

If you want to reconnect later:
- reinstall mem9
- use the same MEM9_API_KEY in the plugin config

If you want a clean chat after uninstall:
- start a new session after the gateway is healthy again
- or reset the session manually as a separate follow-up step

If you want to delete cloud data or manage memories directly:
- go to https://mem9.ai/your-memory/
```

Do not append extra internal diagnostics after the final handoff.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)