OpenClaw

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. Auto-Recall — Before the agent responds, memories matching the current message are injected into context
2. Auto-Capture — After the agent responds, the exchange is sent to Mem0 which decides what's worth keeping
3. Agent Tools — Eight tools for explicit memory operations during conversations

Both auto-recall and auto-capture are opt-in (autoRecall: true, autoCapture: true in config). Once enabled, they run silently with no manual intervention required.

Requirements

Check your OpenClaw version:

openclaw --version
# OpenClaw 2026.4.15 (041266a)

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:

Setup Mem0 from mem0.ai/claw-setup

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.

<Tip>In a multi-user application, set userId dynamically per user (e.g. from your auth system) rather than hardcoding a single value.</Tip>

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.

```
Setup Mem0 from mem0.ai/claw-setup
```

OpenClaw responds with a Mem0 setup card and immediately asks:

> "What's your email address? I'll send you a verification code to connect your Mem0 account."

> "Check your email for a 6-digit code and paste it here."

You'll see the confirmation:

> "Connected to Mem0."

That's it. No API key, no config file editing, no environment variables. The plugin is now active and auto-capture and auto-recall are running on every turn.

<Note>The chat flow uses the same underlying config as manual setup — it writes apiKey and userId into openclaw.json for you. You can still open the file to inspect or override values afterward.</Note>

Option 2: Manual Config

```json5
{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "apiKey": "${MEM0_API_KEY}",
          "userId": "alice"  // any unique identifier you choose for this user
        }
      }
    }
  }
}
```

Open-Source Mode (Self-hosted)

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

Option 1: Interactive Wizard (Recommended)

Run the guided 4-step wizard:

openclaw mem0 init --mode open-source

The wizard walks you through:

Option 2: Non-Interactive Setup

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

# Fully local with Ollama + Qdrant
openclaw mem0 init --mode open-source \
  --oss-llm ollama --oss-embedder ollama --oss-vector qdrant

# OpenAI + Qdrant
openclaw mem0 init --mode open-source \
  --oss-llm openai --oss-llm-key <key> \
  --oss-embedder openai --oss-embedder-key <key> \
  --oss-vector qdrant

# Anthropic LLM + OpenAI embeddings + PGVector
openclaw mem0 init --mode open-source \
  --oss-llm anthropic --oss-llm-key <key> \
  --oss-embedder openai --oss-embedder-key <key> \
  --oss-vector pgvector --oss-vector-user postgres --oss-vector-password secret

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

Option 3: Manual Config

Minimal config — uses OpenAI defaults:

{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "mode": "open-source",
          "userId": "alice"  // any unique identifier you choose for this user
        }
      }
    }
  }
}

To customize providers:

{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "mode": "open-source",
          "userId": "your-user-id",
          "oss": {
            "embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
            "vectorStore": { "provider": "qdrant", "config": { "url": "http://localhost:6333" } },
            "llm": { "provider": "openai", "config": { "model": "gpt-5-mini" } }
          }
        }
      }
    }
  }
}

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 — long-term memories first, then session memories — so the agent has full context.

Agent Tools

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 — useful when an LLM agent drives the CLI programmatically. Run openclaw mem0 help --json to discover every command and flag.

# Search all memories (long-term + session)
openclaw mem0 search "what languages does the user know"

# Search only long-term memories
openclaw mem0 search "what languages does the user know" --scope long-term

# Search only session/short-term memories
openclaw mem0 search "what languages does the user know" --scope session

# List all memories
openclaw mem0 list
openclaw mem0 list --user-id alice --top-k 20

# JSON output (any command)
openclaw mem0 search "preferences" --json
openclaw mem0 status --json

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

openclaw plugins update openclaw-mem0

Checking Plugin Status

openclaw plugins list
openclaw plugins inspect openclaw-mem0

Troubleshooting

"plugins.allow excludes mem0" Error

If you see an error like:

[openclaw] Failed to start CLI: Error: The `openclaw mem0` command is unavailable
because `plugins.allow` excludes "mem0". Add "mem0" to `plugins.allow` if you want
that bundled plugin CLI surface.

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

{
  "plugins": {
    "allow": ["mem0"],
    "slots": {
      "memory": "openclaw-mem0"
    }
  }
}

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:
   bashCopy

   openclaw plugins uninstall openclaw-mem0
   openclaw plugins install @mem0/openclaw-mem0
   

Privacy & Security

Data Flow

Enabling Auto-Capture and Auto-Recall

Auto-capture and auto-recall are disabled by default (opt-in). To enable either or both:

{
  "plugins": {
    "entries": {
      "openclaw-mem0": {
        "config": {
          "autoCapture": true,   // send conversations to Mem0 for extraction
          "autoRecall": true     // inject relevant memories into context
        }
      }
    }
  }
}

Without these enabled, the agent can still use memory tools (memory_add, memory_search, etc.) explicitly — only the automatic background behavior is off.

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:

export MEM0_TELEMETRY=false

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.