mem9.ai

SKILL.md

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