@yunjinlxp/openclaw-mem0

Long-term memory for OpenClaw agents, powered by Mem0 with Alibaba Cloud Tablestore as the vector store backend.

Your agent forgets everything between sessions. This plugin fixes that. It watches conversations, extracts what matters, and brings it back when relevant — automatically.

How it works

Auto-Recall — Before the agent responds, the plugin searches Mem0 for memories that match the current message and injects them into context.

Auto-Capture — After the agent responds, the plugin sends the exchange to Mem0. Mem0 decides what's worth keeping — new facts get stored, stale ones updated, duplicates merged.

Both run silently. No prompting, no configuration, no manual calls.

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 and automatically recalled alongside long-term memories.

• User (long-term) — The agent can explicitly store long-term memories using the memory_store 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.

The agent tools (memory_search, memory_list) accept a scope parameter ("session", "long-term", or "all") to control which memories are queried. The memory_store tool accepts a longTerm boolean (default: true) to choose where to store.

All new parameters are optional and backward-compatible — existing configurations work without changes.

Per-agent memory isolation

In multi-agent setups, each agent automatically gets its own memory namespace. Session keys following the pattern agent:<agentId>:<uuid> are parsed to derive isolated namespaces (${userId}:agent:${agentId}). Single-agent deployments are unaffected — plain session keys and agent:main:* keys resolve to the configured userId.

How it works:

• The agent's session key is inspected on every recall/capture cycle
• If the key matches agent:<name>:<uuid>, memories are stored under userId:agent:<name>
• Different agents never see each other's memories unless explicitly queried

Explicit cross-agent queries:

All memory tools (memory_search, memory_store, memory_list, memory_forget) accept an optional agentId parameter to query another agent's namespace:

memory_search({ query: "user's tech stack", agentId: "researcher" })

Resolution priority: explicit agentId > explicit userId > session-derived > configured default.

Setup

openclaw plugins install @yunjinlxp/[email protected]

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 "default", which means all users share the same memory space.

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

Platform (Mem0 Cloud)

Get an API key from app.mem0.ai, then add to your openclaw.json:

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

Open-Source (Self-hosted)

No Mem0 key needed. Requires OPENAI_API_KEY for default embeddings/LLM.

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

Sensible defaults out of the box. To customize the embedder, vector store, or LLM:

"config": {
  "mode": "open-source",
  "userId": "your-user-id",
  "oss": {
    "embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
    "vectorStore": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } },
    "llm": { "provider": "openai", "config": { "model": "gpt-4o" } }
  }
}

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

Open-Source with Alibaba Cloud Tablestore

Use Alibaba Cloud Tablestore as a persistent, serverless vector store. No external vector database to manage.

Minimal configuration (auto-create Tablestore instance)

If you don't have an existing Tablestore instance, omit endpoint and instanceName — the plugin will automatically create a new Tablestore VCU instance in cn-hangzhou on first use:

"openclaw-mem0": {
  "enabled": true,
  "config": {
    "mode": "open-source",
    "userId": "alice",
    "oss": {
      "vectorStore": {
        "provider": "tablestore",
        "config": {
          "accessKeyId": "${ALIBABA_CLOUD_ACCESS_KEY_ID}",
          "accessKeySecret": "${ALIBABA_CLOUD_ACCESS_KEY_SECRET}"
        }
      }
    }
  }
}

Minimal configuration (with existing Tablestore instance)

If you already have a Tablestore instance, provide endpoint and instanceName:

"openclaw-mem0": {
  "enabled": true,
  "config": {
    "mode": "open-source",
    "userId": "alice",
    "oss": {
      "vectorStore": {
        "provider": "tablestore",
        "config": {
          "endpoint": "https://your-instance.cn-hangzhou.ots.aliyuncs.com",
          "instanceName": "your-instance-name",
          "accessKeyId": "${ALIBABA_CLOUD_ACCESS_KEY_ID}",
          "accessKeySecret": "${ALIBABA_CLOUD_ACCESS_KEY_SECRET}",
          "tableName": "mem0_vectors",       // optional, default: "mem0_vectors"
          "indexName": "mem0_vectors_index",  // optional, default: "<tableName>_index"
          "dimension": 1536                   // optional, must match your embedding model
        }
      }
    }
  }
}

Full configuration with Alibaba Cloud Bailian (DashScope)

Use Alibaba Cloud Bailian (DashScope) for both embeddings and LLM, eliminating the need for an OpenAI API key:

"openclaw-mem0": {
  "enabled": true,
  "config": {
    "mode": "open-source",
    "userId": "alice",
    "oss": {
      "embedder": {
        "provider": "openai",
        "config": {
          "apiKey": "${DASHSCOPE_API_KEY}",
          "model": "text-embedding-v3",
          "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
          "embeddingDims": 1024
        }
      },
      "vectorStore": {
        "provider": "tablestore",
        "config": {
          // endpoint and instanceName are optional — omit to auto-create a new instance
          "endpoint": "https://your-instance.cn-hangzhou.ots.aliyuncs.com",
          "instanceName": "your-instance-name",
          "accessKeyId": "${ALIBABA_CLOUD_ACCESS_KEY_ID}",
          "accessKeySecret": "${ALIBABA_CLOUD_ACCESS_KEY_SECRET}",
          "dimension": 1024
        }
      },
      "llm": {
        "provider": "openai",
        "config": {
          "apiKey": "${DASHSCOPE_API_KEY}",
          "model": "qwen-plus",
          "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
        }
      }
    }
  }
}

Note: DashScope's text-embedding-v3 model outputs 1024-dimensional vectors by default. Make sure the dimension in the Tablestore config matches your embedding model's output dimension.

The Tablestore provider automatically creates the data table and search index on first use. The search index includes a VECTOR field for cosine-similarity KNN search and KEYWORD fields for metadata filtering (user_id, agent_id, run_id, etc.).

Building and installing the plugin

Since the Tablestore provider is bundled into a custom build of mem0ai, you need to build the plugin from source:

# 1. Clone the repo and build the plugin tgz
cd mem0/openclaw
bash build-plugin.sh

# 2. Install on any machine (no npm registry needed)
openclaw plugins install ./mem0-openclaw-mem0-0.3.0.tgz

# 3. Rebuild native addons (required for better-sqlite3)
cd ~/.openclaw/extensions/openclaw-mem0
npm rebuild better-sqlite3

# 4. Restart the gateway to load the new plugin
openclaw gateway restart

The build script bundles the modified mem0ai and the tablestore SDK into the plugin package, so end-users do not need to install any extra dependencies.

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | Cannot read properties of null (reading 'QueryType') | Tablestore SDK failed to load in the runtime environment | Check that tablestore is in node_modules. Run node -e "console.log(require('tablestore').QueryType)" in the plugin directory to verify. | | 401 Incorrect API key provided | Embedding requests are being sent to OpenAI instead of DashScope | Ensure baseURL is set in the embedder config (e.g. "baseURL": "https://dashscope.aliyuncs.com/compatible-mode/v1"). | | Could not locate the bindings file (better-sqlite3) | Native addon not compiled for the current platform | Run cd ~/.openclaw/extensions/openclaw-mem0 && npm rebuild better-sqlite3. | | OTSObjectNotExist on first use | Normal — the table/index is being created | Wait 5-10 seconds and retry. The provider auto-creates tables on first initialize(). | | Plugin not loading after install | openclaw config not updated | Ensure openclaw.json has "openclaw-mem0" in plugins.allow and plugins.slots.memory. Restart gateway after config changes. |

Agent tools

The agent gets five tools it can call during conversations:

| Tool | Description | |------|-------------| | memory_search | Search memories by natural language. Optional agentId to scope to a specific agent. | | memory_list | List all stored memories for a user. Optional agentId to scope to a specific agent. | | memory_store | Explicitly save a fact. Optional agentId to store under a specific agent's namespace. | | memory_get | Retrieve a memory by ID | | memory_forget | Delete by ID or by query. Optional agentId to scope deletion to a specific agent. |

CLI

# 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

# Stats
openclaw mem0 stats

# Search a specific agent's memories
openclaw mem0 search "user preferences" --agent researcher

# Stats for a specific agent
openclaw mem0 stats --agent researcher

Options

General

| Key | Type | Default | | |-----|------|---------|---| | mode | "platform" | "open-source" | "platform" | Which backend to use | | userId | string | "default" | Any unique identifier you choose for the user (e.g. "alice", "user_123"). All memories are scoped to this value. Not found in any dashboard — you define it yourself. | | autoRecall | boolean | true | Inject memories before each turn | | autoCapture | boolean | true | Store facts after each turn | | topK | number | 5 | Max memories per recall | | searchThreshold | number | 0.3 | Min similarity (0–1) |

Platform mode

| Key | Type | Default | | |-----|------|---------|---| | apiKey | string | — | Required. Mem0 API key (supports ${MEM0_API_KEY}) | | orgId | string | — | Organization ID | | projectId | string | — | Project ID | | enableGraph | boolean | false | Entity graph for relationships | | customInstructions | string | (built-in) | Extraction rules — what to store, how to format | | customCategories | object | (12 defaults) | Category name → description map for tagging |

Open-source mode

Works with zero extra config. The oss block lets you swap out any component:

| Key | Type | Default | | |-----|------|---------|---| | customPrompt | string | (built-in) | Extraction prompt for memory processing | | oss.embedder.provider | string | "openai" | Embedding provider ("openai", "ollama", etc.) | | oss.embedder.config | object | — | Provider config: apiKey, model, baseURL | | oss.vectorStore.provider | string | "memory" | Vector store ("memory", "qdrant", "chroma", etc.) | | oss.vectorStore.config | object | — | Provider config: host, port, collectionName, dimension | | oss.llm.provider | string | "openai" | LLM provider ("openai", "anthropic", "ollama", etc.) | | oss.llm.config | object | — | Provider config: apiKey, model, baseURL, temperature | | oss.historyDbPath | string | — | SQLite path for memory edit history |

Everything inside oss is optional — defaults use OpenAI embeddings (text-embedding-3-small), in-memory vector store, and OpenAI LLM. Override only what you need.

Tablestore vector store config

When using "provider": "tablestore" (or "aliyun_tablestore"), the following config keys are available:

| Key | Type | Default | | |-----|------|---------|---| | endpoint | string | — | Optional. Tablestore instance endpoint URL. If omitted, a new instance is auto-created. | | instanceName | string | — | Optional. Tablestore instance name. If omitted, a new instance is auto-created. | | accessKeyId | string | — | Alibaba Cloud AccessKey ID. Required unless roleName is set. (supports ${ALIBABA_CLOUD_ACCESS_KEY_ID}) | | accessKeySecret | string | — | Alibaba Cloud AccessKey Secret. Required unless roleName is set. (supports ${ALIBABA_CLOUD_ACCESS_KEY_SECRET}) | | roleName | string | — | ECS RAM Role name for automatic credential retrieval. When set, accessKeyId and accessKeySecret are fetched from the ECS metadata service and refreshed automatically before expiration. (supports ${TABLESTORE_ROLE_NAME}) | | stsToken | string | — | Optional STS token for temporary credentials | | regionId | string | — | Region ID (e.g. "cn-hangzhou"). Required when auto-provisioning. (supports ${TABLESTORE_REGION_ID}) | | tableName | string | "mem0_vectors" | Data table name | | indexName | string | "<tableName>_index" | Search index name | | dimension | number | 1536 | Vector dimension (must match your embedding model) |

Authentication modes

The plugin supports two authentication modes:

1. AccessKey (static credentials)

Provide accessKeyId and accessKeySecret directly in the config or via environment variables. Suitable for development or non-ECS environments.

2. ECS RAM Role (automatic, recommended for ECS)

Set roleName to the name of the RAM role attached to your ECS instance. The plugin will automatically fetch temporary STS credentials from the ECS metadata service (http://100.100.100.200/latest/meta-data/ram/security-credentials/{roleName}), cache them, and refresh before expiration. No AccessKey needed in the config.

"vectorStore": {
  "provider": "tablestore",
  "config": {
    "roleName": "EcsRamRoleForTablestore"
    // No accessKeyId or accessKeySecret needed
  }
}

Environment variable: TABLESTORE_ROLE_NAME

License

Apache 2.0