From e219961f9d465c7d096b8267893bacb053f69c2b Mon Sep 17 00:00:00 2001
From: Utkarsh <utkarsh.kumar@mem0.ai>
Date: Mon, 9 Mar 2026 22:17:15 +0530
Subject: [PATCH] docs(openclaw): clarify userId is user-defined (#4277)

---
 docs/integrations/openclaw.mdx | 18 ++++++++++++++++--
 openclaw/README.md             | 20 +++++++++++++++++---
 2 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/docs/integrations/openclaw.mdx b/docs/integrations/openclaw.mdx
index 989b6b29a..d4a7f8b72 100644
--- a/docs/integrations/openclaw.mdx
+++ b/docs/integrations/openclaw.mdx
@@ -25,6 +25,20 @@ openclaw plugins install @mem0/openclaw-mem0
 
 ## 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"`, `"alice@example.com"`)
+- 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.</Tip>
+
 ### Platform Mode (Mem0 Cloud)
 
 <Note>Get your API key from [app.mem0.ai](https://app.mem0.ai).</Note>
@@ -37,7 +51,7 @@ Add to your `openclaw.json`:
   "enabled": true,
   "config": {
     "apiKey": "${MEM0_API_KEY}",
-    "userId": "your-user-id"
+    "userId": "alice"  // any unique identifier you choose for this user
   }
 }
 ```
@@ -51,7 +65,7 @@ No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings/LLM.
   "enabled": true,
   "config": {
     "mode": "open-source",
-    "userId": "your-user-id"
+    "userId": "alice"  // any unique identifier you choose for this user
   }
 }
 ```
diff --git a/openclaw/README.md b/openclaw/README.md
index ef2f79dbf..46d2b24fd 100644
--- a/openclaw/README.md
+++ b/openclaw/README.md
@@ -56,6 +56,20 @@ Resolution priority: explicit `agentId` > explicit `userId` > session-derived >
 openclaw plugins install @mem0/openclaw-mem0
 ```
 
+### 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"`, `"alice@example.com"`)
+- 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](https://app.mem0.ai), then add to your `openclaw.json`:
@@ -66,7 +80,7 @@ Get an API key from [app.mem0.ai](https://app.mem0.ai), then add to your `opencl
   "enabled": true,
   "config": {
     "apiKey": "${MEM0_API_KEY}",
-    "userId": "your-user-id"
+    "userId": "alice"  // any unique identifier you choose for this user
   }
 }
 ```
@@ -80,7 +94,7 @@ No Mem0 key needed. Requires `OPENAI_API_KEY` for default embeddings/LLM.
   "enabled": true,
   "config": {
     "mode": "open-source",
-    "userId": "your-user-id"
+    "userId": "alice"  // any unique identifier you choose for this user
   }
 }
 ```
@@ -142,7 +156,7 @@ openclaw mem0 stats --agent researcher
 | Key | Type | Default | |
 |-----|------|---------|---|
 | `mode` | `"platform"` \| `"open-source"` | `"platform"` | Which backend to use |
-| `userId` | `string` | `"default"` | Scope memories per user |
+| `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 |