OpenClaw - Mem0

Add long-term memory to OpenClaw agents with the @mem0/openclaw-mem0 plugin. Your agent forgets everything between sessions. This plugin fixes that by automatically watching conversations, extracting what matters, and bringing it back when relevant.

Overview

The plugin provides:

1. Triage: The agent extracts durable facts from conversations using a structured protocol with importance gates and domain overlays
2. Recall: Before each turn, relevant memories are retrieved with reranking and injected into context
3. Dream: Periodic memory consolidation merges duplicates, resolves conflicts, prunes stale entries
4. Agent Tools: Eight tools for explicit memory operations during conversations

Skills mode, autoRecall, and autoCapture are all enabled by default during openclaw mem0 init.

Requirements

Check your OpenClaw version:

Installation

The fastest way is to install directly from your OpenClaw chat, no CLI or config editing needed. Copy and paste this into your OpenClaw chat; Telegram, WhatsApp, default chat, or any channel where your agent lives:

OpenClaw installs the plugin, prompts you for your email, and connects your Mem0 account with OTP verification. See Chat Setup below for the full walkthrough. If you prefer the OpenClaw CLI, or are setting up self-hosted / open-source mode, see Manual Config and Open-Source Mode below.

Setup and Configuration

Understanding userId

The userId field is a string you choose to uniquely identify the user whose memories are being stored. It is not something you look up in the Mem0 dashboard: you define it yourself. Pick any stable, unique identifier for the user. Common choices:

• Your application’s internal user ID (e.g. "user_123", "[email protected]")
• A UUID (e.g. "550e8400-e29b-41d4-a716-446655440000")
• A simple username (e.g. "alice")

All memories are scoped to this userId: different values create separate memory namespaces. If you don’t set it, it defaults to your OS username.

Platform Mode (Mem0 Cloud)

There are two ways to set up @mem0/openclaw-mem0 on the Mem0 platform:

• Chat setup (recommended): run the setup inside any OpenClaw chat. No config editing, no API key handling.
• Manual config: edit openclaw.json directly.

Option 1: Chat Setup (Recommended)

You no longer need manual config editing to get started. Everything happens inside the OpenClaw chat itself.

That’s it. No API key, no config file editing, no environment variables. The plugin is now active with skills-based memory (triage, recall, and dream) running automatically.

Option 2: Manual Config

Open-Source Mode (Self-hosted)

No Mem0 key is needed. Defaults use OpenAI (gpt-5-mini for LLM, text-embedding-3-small for embeddings), so OPENAI_API_KEY is required. For a fully local setup, use Ollama for both.

Option 1: Interactive Wizard (Recommended)

Run the guided 4-step wizard:

The wizard walks you through:

Option 2: Non-Interactive Setup

For CI/CD, scripts, or agent-driven setup: pass all options as flags:

Add --json for machine-readable output (useful when an LLM agent is driving the setup).

All --oss-* flags

Option 3: Manual Config

Minimal config: uses OpenAI defaults:

To customize providers:

All oss fields are optional. See Mem0 OSS docs for available providers.

Short-term vs Long-term Memory

Memories are organized into two scopes:

• Session (short-term): Auto-capture stores memories scoped to the current session via Mem0’s run_id / runId parameter. These are contextual to the ongoing conversation.
• User (long-term): The agent can explicitly store long-term memories using the memory_add tool (with longTerm: true, the default). These persist across all sessions for the user.

During auto-recall, the plugin searches both scopes and presents them separately, with long-term memories first and session memories second. This means the agent has full context.

The agent gets eight tools it can call during conversations:

The memory_search and memory_list tools accept a scope parameter ("session", "long-term", or "all") to control which memories are queried.

CLI Commands

All commands support --json for machine-readable output. Use it when an LLM agent drives the CLI programmatically. Run openclaw mem0 help --json to discover every command and flag.

Configuration Options

General Options

Platform Mode Options

Open-Source Mode Options

Everything inside oss is optional: defaults use OpenAI embeddings (text-embedding-3-small), in-memory vector store, and OpenAI LLM (gpt-5-mini).

Plugin Management

Updating the Plugin

Checking Plugin Status

Troubleshooting

”plugins.allow excludes mem0” Error

If you see an error like:

Add mem0 to your plugins.allow list in openclaw.json:

Plugin Not Activating

If the plugin installs but doesn’t work:

1. Verify plugins.slots.memory is set to "openclaw-mem0" (not the npm package name)
2. Check openclaw plugins list --enabled to confirm the plugin is loaded
3. Run openclaw mem0 status to verify configuration

Plugin Update Not Working

If openclaw plugins update fails:

1. Use the plugin ID: openclaw plugins update openclaw-mem0
2. Update all plugins at once: openclaw plugins update --all
3. If that fails, uninstall and reinstall:

Privacy & Security

Data Flow

Auto-Capture and Auto-Recall

Auto-capture and auto-recall are enabled by default. When skills mode is configured (the default after openclaw mem0 init), these are ignored in favor of the skills-based triage/recall/dream protocol. To disable either:

The agent can always use memory tools (memory_add, memory_search, etc.) explicitly regardless of these settings.

Credential Protection

The plugin never stores API keys, tokens, or secrets as memories. Five independent layers enforce this:

1. Triage gate: The extraction prompt rejects values matching known credential patterns (sk-, m0-, ghp_, AKIA, Bearer, password=, token=, secret=)
2. Dream cleanup: Periodic memory consolidation deletes any memories that slipped through containing credential patterns
3. Extraction instructions: Default extraction rules explicitly instruct the model to store only that a credential was configured, never the value
4. Configurable patterns: Add custom credential patterns via skills.triage.credentialPatterns
5. CLI redaction: openclaw mem0 config show redacts sensitive fields (apiKey, oss.*.config.apiKey)

API Key Storage

Plugin config is stored in ~/.openclaw/openclaw.json with file permissions 0o600 (owner-read-only). For production deployments, use environment variable references (${MEM0_API_KEY}) or SecretRef objects instead of plaintext keys.

Telemetry

Anonymous usage telemetry (PostHog) is enabled by default to help improve the plugin. No conversation content or memory values are included, only event counts (recall, capture, tool usage, CLI commands). To opt out, set the environment variable:

System Prompt Context

The plugin injects memory-related instructions into the agent’s system context via OpenClaw’s prependSystemContext mechanism. This includes the memory triage protocol and recalled memories. This is the standard OpenClaw plugin SDK pattern for memory backends. No user-facing prompts are modified.