How to Add Mem0 Persistent Memory to OpenClaw

OpenClaw's built-in memory auto-loads only the last two days of notes at session start, according to Mem0's integration documentation. For short demos, that works. For agents running across days or weeks, three failure modes compound:

The LLM decides what to save. If it judges a piece of information unimportant, that fact disappears permanently. There is no system-level guarantee that any given exchange will be persisted.

The agent must voluntarily call its own search tools. In practice, agents often answer from training data rather than searching their memory store, especially when the question seems straightforward.

Context compaction summarizes older messages to stay within token limits. If the agent does not re-search memory after compaction, it answers without that context entirely. Developers work around this with MEMORY.md files and SQLite logs, but those live inside the context window and get compacted too.

Mem0 solves this by storing memories externally at the system layer. Capture and recall happen on every turn regardless of what the LLM decides to do.

You need OpenClaw version 2026.4.15 or later. Open your OpenClaw settings or about page to confirm your current version before proceeding.

Cloud setup (recommended, under 30 seconds):

Paste this into any OpenClaw channel where your agent lives:

Setup Mem0 from mem0.ai/claw-setup

The agent walks you through email verification with a 6-digit OTP. Once confirmed, it prints "Connected to Mem0" and memory is active immediately.

CLI setup:

From the terminal, run openclaw plugins install @mem0/openclaw-mem0 (per the official Mem0 docs). This registers the plugin and adds a default configuration block to your OpenClaw config. The plugin occupies the memory slot, meaning it replaces the built-in memory backend entirely.

Self-hosted setup (for teams that need data residency or want fully local operation):

openclaw mem0 init --mode open-source

The interactive wizard lets you choose your LLM provider (OpenAI, Anthropic, or Ollama for fully local), embedding model, and vector store (in-memory default, or Qdrant for production). No Mem0 API key required in this mode.

The Mem0 plugin operates a three-stage lifecycle on every conversation turn: Triage, Recall, and Dream.

Triage (Auto-Capture)

After the agent responds, the full exchange is sent to Mem0's extraction pipeline. Triage applies importance gates and domain overlays to decide what is worth keeping. Facts that pass get stored as structured memories outside the session. The system explicitly rejects credential patterns (strings matching sk-, m0-, ghp_, and similar prefixes) to prevent accidental secret storage.

Captured facts include user preferences, technical decisions, project context, names, and deadlines. Short-lived conversational details (greetings, acknowledgments) are filtered out.

Recall (Auto-Recall)

Before the agent responds to any new message, Mem0 searches for relevant memories using semantic similarity with reranking. Matching memories are injected directly into context. Long-term user memories appear first, followed by session-scoped memories. The default retrieves up to 5 memories per turn with a minimum similarity threshold of 0.3.

This happens at the system layer. The agent does not need to decide to search, and cannot skip the step.

Dream (Consolidation)

Periodically, Mem0 runs a background consolidation pass. Dream merges duplicate memories, resolves conflicts between contradictory facts (keeping the most recent), and removes stale entries. This keeps the memory store compact and accurate over months of use.

Give your OpenClaw agent persistent file storage too

Mem0 handles conversational memory. Fast.io handles file storage. 50GB free, MCP-ready, no credit card required.

Sign Up Free

The full configuration lives in ~/.openclaw/openclaw.json under the plugins section:

{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "apiKey": "${MEM0_API_KEY}",
          "userId": "alice",
          "skills": {
            "triage": { "enabled": true },
            "recall": {
              "enabled": true,
              "tokenBudget": 1500,
              "rerank": true
            },
            "dream": { "enabled": true },
            "domain": "companion"
          }
        }
      }
    }
  }
}

Key Parameters

userId (default: OS username) scopes all memories to a specific person. If multiple people share an OpenClaw instance, each needs a distinct userId or memories bleed across users.

topK (default: 5) controls how many memories get injected per turn. Increase to 10-15 for research-heavy workflows where the agent needs broad context. Decrease to 2-3 for focused coding tasks where fewer, more relevant memories reduce noise.

searchThreshold (default: 0.3) sets the minimum semantic similarity score. Raise to 0.5-0.6 if you get too many tangentially related memories. Lower to 0.2 if the agent seems to forget things it should know.

tokenBudget (default: 1500) caps how many tokens recalled memories can consume per turn. This prevents memory injection from crowding out the actual conversation context.

Memory Scopes

Two scopes operate simultaneously:

• Session memory is scoped to the current conversation via runId. Facts captured here are relevant to the active task but might not matter next week. Session memories appear after long-term ones during recall.

• User memory persists across all sessions indefinitely. When the agent explicitly calls memory_add with longTerm: true, facts go here. User memory is also cross-channel: tell OpenClaw something in Telegram, and it recalls that fact when you continue in Discord.

The two systems solve different problems. OpenClaw's built-in context compaction manages the current session's token budget. Mem0 manages everything that lives beyond the session.

Use built-in memory when:

• You run short, single-session tasks (under a few hours)
• Your agent operates in a fixed domain with a small, stable knowledge base loaded via system prompt
• You want zero external dependencies

Use Mem0 when:

• Your agent runs across days or weeks on the same project
• Users interact with the agent across multiple channels (Telegram, Discord, Slack, web)
• You need guaranteed fact persistence without relying on the LLM to decide importance
• You work with multiple team members who each need isolated memory scopes
• Context compaction has caused your agent to "forget" critical instructions

The two can coexist. Mem0 occupies the memory plugin slot, which replaces the built-in memory search and storage. But OpenClaw's context compaction still operates on the active conversation window. Mem0 just ensures that when compaction drops older context, the important facts have already been captured externally and will be re-injected on the next relevant turn.

Migration from Built-In Memory

If you have existing .md memory files from the built-in system, Mem0 does not automatically ingest them. You can bootstrap by running:

openclaw mem0 search "preferences"

If results are empty, paste your critical facts into a conversation and let Auto-Capture pick them up. For large memory files, break them into focused conversation segments over a few sessions rather than dumping everything at once.

After installation, verify that memories persist across sessions. Start a conversation and share a distinctive fact:

"My project uses Python 3.12 with FastAPI and deploys to Railway."

End the session. Start a new one and ask:

"What tech stack does my project use?"

If Mem0 is working, the agent answers with your exact stack without you needing to repeat it.

CLI Verification

openclaw mem0 list --user-id alice --top-k 20
openclaw mem0 search "tech stack" --scope long-term

Both commands support --json output for programmatic use by other agents.

Eight Memory Tools

The plugin exposes eight tools to the agent automatically:

• memory_search finds memories by semantic query with scope filtering
• memory_add stores a fact explicitly (set longTerm: true for cross-session persistence)
• memory_get retrieves a specific memory by ID
• memory_list shows all stored memories with optional filters
• memory_update modifies an existing memory
• memory_delete removes a memory permanently
• memory_event_list shows the capture/recall event log
• memory_event_status checks processing status of pending captures

All tools accept a scope filter: "session", "long-term", or "all".

Pairing Memory with Persistent File Storage

Mem0 handles conversational facts, but agents working on real projects also produce files: code, documents, datasets, reports. Those need storage that survives sessions too.

Fast.io provides persistent workspaces where agents store files via MCP or API. Enable Intelligence Mode on a workspace and every uploaded file gets auto-indexed for semantic search. The agent can then query both its Mem0 memories (conversational context) and its Fast.io workspace (file contents) to build complete project awareness.

The free agent tier includes 50GB storage, 5,000 credits per month, and 5 workspaces with no credit card and no expiration. Connect via Streamable HTTP at /mcp or legacy SSE at /sse. Combined with Mem0 for conversational memory, this gives OpenClaw agents both fact persistence and file persistence in one workflow.