MemTensor · CaralHsi · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/apps/MemOS-Cloud-OpenClaw-Plugin/README.md b/apps/MemOS-Cloud-OpenClaw-Plugin/README.md
@@ -44,7 +44,7 @@ Make sure it’s enabled in `~/.openclaw/openclaw.json`:
     },
     "load": {
       "paths": [
-        "C:\\Users\\YourName\\.openclaw\\extensions\\memos-cloud-openclaw-plugin\\package"
+        "C:\\Users\\YourName\\.openclaw\\extensions\\memos-cloud-openclaw-plugin"
       ]
     }
   }
@@ -55,7 +55,8 @@ Make sure it’s enabled in `~/.openclaw/openclaw.json`:
 Restart the gateway after config changes.
 
 ## Environment Variables
-The plugin tries env files in order (**openclaw → moltbot → clawdbot**). For each key, the first file with a value wins.
+The plugin resolves runtime config in this order: **plugin config → env files → process environment**.
+Among env files, it tries them in order (**openclaw → moltbot → clawdbot**). For each key, the first file with a value wins.
 If none of these files exist (or the key is missing), it falls back to the process environment.
 
 **Where to configure**
@@ -91,21 +92,31 @@ MEMOS_API_KEY=YOUR_TOKEN
 - `MEMOS_BASE_URL` (default: `https://memos.memtensor.cn/api/openmem/v1`)
 - `MEMOS_API_KEY` (required; Token auth) — get it at https://memos-dashboard.openmem.net/cn/apikeys/
 - `MEMOS_USER_ID` (optional; default: `openclaw-user`)
+- `MEMOS_USE_DIRECT_SESSION_USER_ID` (default: `false`; when enabled, direct session keys like `agent:main:<provider>:direct:<peer-id>` use `<peer-id>` as MemOS `user_id`)
 - `MEMOS_CONVERSATION_ID` (optional override)
+- `MEMOS_KNOWLEDGEBASE_IDS` (optional; comma-separated global knowledge base IDs for `/search/memory`, e.g., `"kb-123, kb-456"`)
+- `MEMOS_ALLOW_KNOWLEDGEBASE_IDS` (optional; comma-separated knowledge base IDs for `/add/message`, e.g., `"kb-123"`)
+- `MEMOS_TAGS` (optional; comma-separated tags for `/add/message`, default: `"openclaw"`, e.g., `"openclaw, dev"`)
 - `MEMOS_RECALL_GLOBAL` (default: `true`; when true, search does **not** pass conversation_id)
 - `MEMOS_MULTI_AGENT_MODE` (default: `false`; enable multi-agent data isolation)
+- `MEMOS_ALLOWED_AGENTS` (optional; comma-separated allowlist for multi-agent mode, e.g. `"agent1,agent2"`; empty means all agents enabled)
 - `MEMOS_CONVERSATION_PREFIX` / `MEMOS_CONVERSATION_SUFFIX` (optional)
 - `MEMOS_CONVERSATION_SUFFIX_MODE` (`none` | `counter`, default: `none`)
 - `MEMOS_CONVERSATION_RESET_ON_NEW` (default: `true`, requires hooks.internal.enabled)
 - `MEMOS_RECALL_FILTER_ENABLED` (default: `false`; run model-based memory filtering before injection)
 - `MEMOS_RECALL_FILTER_BASE_URL` (OpenAI-compatible base URL, e.g. `http://127.0.0.1:11434/v1`)
 - `MEMOS_RECALL_FILTER_API_KEY` (optional; required if your endpoint needs auth)
 - `MEMOS_RECALL_FILTER_MODEL` (model name used to filter recall candidates)
-- `MEMOS_RECALL_FILTER_TIMEOUT_MS` (default: `6000`)
-- `MEMOS_RECALL_FILTER_RETRIES` (default: `0`)
+- `MEMOS_RECALL_FILTER_TIMEOUT_MS` (default: `30000`)
+- `MEMOS_RECALL_FILTER_RETRIES` (default: `1`)
 - `MEMOS_RECALL_FILTER_CANDIDATE_LIMIT` (default: `30` per category)
 - `MEMOS_RECALL_FILTER_MAX_ITEM_CHARS` (default: `500`)
 - `MEMOS_RECALL_FILTER_FAIL_OPEN` (default: `true`; fallback to unfiltered recall on failure)
+- `MEMOS_CAPTURE_STRATEGY` (default: `last_turn`)
+- `MEMOS_ASYNC_MODE` (default: `true`; non-blocking memory addition)
+- `MEMOS_THROTTLE_MS` (default: `0`; throttle memory requests)
+- `MEMOS_INCLUDE_ASSISTANT` (default: `true`; include assistant messages in memory)
+- `MEMOS_MAX_MESSAGE_CHARS` (default: `20000`; max characters for message history)
 
 ## Optional Plugin Config
 In `plugins.entries.memos-cloud-openclaw-plugin.config`:
@@ -114,6 +125,7 @@ In `plugins.entries.memos-cloud-openclaw-plugin.config`:
   "baseUrl": "https://memos.memtensor.cn/api/openmem/v1",
   "apiKey": "YOUR_API_KEY",
   "userId": "memos_user_123",
+  "useDirectSessionUserId": false,
   "conversationId": "openclaw-main",
   "queryPrefix": "important user context preferences decisions ",
   "recallEnabled": true,
@@ -136,16 +148,19 @@ In `plugins.entries.memos-cloud-openclaw-plugin.config`:
   "tags": ["openclaw"],
   "agentId": "",
   "multiAgentMode": false,
+  "allowedAgents": [],
   "asyncMode": true,
   "recallFilterEnabled": false,
   "recallFilterBaseUrl": "http://127.0.0.1:11434/v1",
   "recallFilterApiKey": "",
   "recallFilterModel": "qwen2.5:7b",
-  "recallFilterTimeoutMs": 6000,
-  "recallFilterRetries": 0,
+  "recallFilterTimeoutMs": 30000,
+  "recallFilterRetries": 1,
   "recallFilterCandidateLimit": 30,
   "recallFilterMaxItemChars": 500,
-  "recallFilterFailOpen": true
+  "recallFilterFailOpen": true,
+  "throttleMs": 0,
+  "maxMessageChars": 20000
 }
 ```
 
@@ -167,6 +182,133 @@ The plugin provides native support for multi-agent architectures (via the `agent
 - **Data Isolation**: The `agent_id` is automatically injected into both `/search/memory` and `/add/message` requests. This ensures completely isolated memory and message histories for different agents, even under the same user or session.
 - **Static Override**: You can also force a specific agent ID by setting `"agentId": "your_agent_id"` in the plugin's `config`.
 
+### Per-Agent Memory Toggle
+
+In multi-agent mode, you can use `MEMOS_ALLOWED_AGENTS` to control exactly which agents have memory enabled. Agents not in the allowlist will skip both memory recall and memory capture entirely.
+
+**Environment variable** (in `~/.openclaw/.env`):
+```env
+MEMOS_MULTI_AGENT_MODE=true
+MEMOS_ALLOWED_AGENTS="agent1,agent2"
+```
+
+Separate multiple agent IDs with commas.
+
+**Plugin config** (in `openclaw.json`):
+```json
+{
+  "plugins": {
+    "entries": {
+      "memos-cloud-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "multiAgentMode": true,
+          "allowedAgents": ["agent1", "agent2"]
+        }
+      }
+    }
+  }
+}
+```
+
+**Behavior**:
+| Config | Effect |
+|--------|--------|
+| `MEMOS_ALLOWED_AGENTS` unset or empty | All agents have memory enabled |
+| `MEMOS_ALLOWED_AGENTS="agent1,agent2"` | Only `agent1` and `agent2` are enabled; others are skipped |
+| `MEMOS_ALLOWED_AGENTS="agent1"` | Only `agent1` is enabled; all other agents are skipped |
+| `MEMOS_MULTI_AGENT_MODE=false` | Allowlist has no effect; all requests use single-agent mode |
+
+> **Note**: The allowlist only takes effect when `multiAgentMode=true`. When multi-agent mode is off, memory works for all agents and the allowlist is ignored.
+
+### Per-Agent Configuration (agentOverrides)
+
+Beyond simple on/off toggles, you can configure **different memory parameters for each agent** using `agentOverrides`. Each agent can have its own knowledge base, recall limits, relativity threshold, and more.
+
+**Plugin config** (in `openclaw.json`):
+```json
+{
+  "plugins": {
+    "entries": {
+      "memos-cloud-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "multiAgentMode": true,
+          "allowedAgents": ["default", "research-agent", "coding-agent"],
+          "knowledgebaseIds": [],
+          "memoryLimitNumber": 6,
+          "relativity": 0.45,
+
+          "agentOverrides": {
+            "research-agent": {
+              "knowledgebaseIds": ["kb-research-papers", "kb-academic"],
+              "memoryLimitNumber": 12,
+              "relativity": 0.3,
+              "includeToolMemory": true,
+              "captureStrategy": "full_session",
+              "queryPrefix": "research context: "
+            },
+            "coding-agent": {
+              "knowledgebaseIds": ["kb-codebase", "kb-api-docs"],
+              "memoryLimitNumber": 9,
+              "relativity": 0.5,
+              "addEnabled": false
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Environment variable** (in `~/.openclaw/.env`):
+You can use `MEMOS_AGENT_OVERRIDES` to configure a JSON string to override global parameters. Note: `.env` configuration has a lower priority than `agentOverrides` in `openclaw.json`.
+```env
+MEMOS_AGENT_OVERRIDES='{"research-agent": {"memoryLimitNumber": 12, "relativity": 0.3}, "coding-agent": {"memoryLimitNumber": 9}}'
+```
+
+**How it works**:
+- Fields in `agentOverrides.<agentId>` override the global defaults for that specific agent.
+- Only the fields you specify are overridden; all other parameters inherit from the global config.
+- If no override exists for an agent, it uses the global config as-is.
+
+**Overridable fields**:
+
+| Field | Description |
+|-------|-------------|
+| `knowledgebaseIds` | Knowledge base IDs for `/search/memory` |
+| `memoryLimitNumber` | Max memory items to recall |
+| `preferenceLimitNumber` | Max preference items to recall |
+| `includePreference` | Enable preference recall |
+| `includeToolMemory` | Enable tool memory recall |
+| `toolMemoryLimitNumber` | Max tool memory items |
+| `relativity` | Relevance threshold (0-1) |
+| `recallEnabled` | Enable/disable recall for this agent |
+| `addEnabled` | Enable/disable memory capture for this agent |
+| `captureStrategy` | `last_turn` or `full_session` |
+| `queryPrefix` | Prefix for search queries |
+| `maxItemChars` | Max chars per memory item in prompt |
+| `maxMessageChars` | Max chars per message when adding |
+| `includeAssistant` | Include assistant messages in capture |
+| `recallGlobal` | Global recall (skip conversation_id) |
+| `recallFilterEnabled` | Enable model-based recall filtering |
+| `recallFilterModel` | Model for recall filtering |
+| `recallFilterBaseUrl` | Base URL for recall filter model |
+| `recallFilterApiKey` | API key for recall filter |
+| `allowKnowledgebaseIds` | Knowledge bases for `/add/message` |
+| `tags` | Tags for `/add/message` |
+| `throttleMs` | Throttle interval |
+
+## Direct Session User ID
+- **Default behavior**: the plugin still uses the configured `userId` (or `MEMOS_USER_ID`) and stays fully backward compatible.
+- **Enable mode**: set `"useDirectSessionUserId": true` in plugin config or `MEMOS_USE_DIRECT_SESSION_USER_ID=true` in env.
+- **What it does**: when enabled, session keys like `agent:main:<provider>:direct:<peer-id>` reuse `<peer-id>` as MemOS `user_id`.
+- **What it does not do**: non-direct session keys such as `agent:main:<provider>:channel:<channel-id>` keep using the configured fallback `userId`.
+- **Request paths affected**: the same resolver is used by both `buildSearchPayload()` and `buildAddMessagePayload()`, so recall and add stay consistent.
+- **Config precedence**: runtime config still follows the same rule as the rest of the plugin - plugin config first, then `.env` files (`~/.openclaw/.env` -> `~/.moltbot/.env` -> `~/.clawdbot/.env`), then process env.
+
+
 ## Notes
 - `conversation_id` defaults to OpenClaw `sessionKey` (unless `conversationId` is provided). **TODO**: consider binding to OpenClaw `sessionId` directly.
 - Optional **prefix/suffix** via env or config; `conversationSuffixMode=counter` increments on `/new` (requires `hooks.internal.enabled`).