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

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.