@memtensor/memos-cloud-openclaw-plugin 0.1.10 → 0.1.11-beta.0

package/README.md

@@ -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,9 +92,14 @@ 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)
@@ -119,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,
@@ -141,6 +148,7 @@ 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",
@@ -174,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`).

package/README_ZH.md

@@ -57,7 +57,8 @@ openclaw gateway restart
 修改配置后需要重启 gateway。
 
 ## 环境变量
-插件按顺序读取 env 文件（**openclaw → moltbot → clawdbot**），每个键优先使用最先匹配到的值。
+插件运行时配置的优先级是：**插件 config → env 文件 → 进程环境变量**。
+在 env 文件层，按顺序读取（**openclaw → moltbot → clawdbot**），每个键优先使用最先匹配到的值。
 若三个文件都不存在（或该键未找到），才会回退到进程环境变量。
 
 **配置位置**
@@ -93,9 +94,14 @@ MEMOS_API_KEY=YOUR_TOKEN
 - `MEMOS_BASE_URL`（默认 `https://memos.memtensor.cn/api/openmem/v1`）
 - `MEMOS_API_KEY`（必填，Token 认证）—— 获取地址：https://memos-dashboard.openmem.net/cn/apikeys/
 - `MEMOS_USER_ID`（可选，默认 `openclaw-user`）
+- `MEMOS_USE_DIRECT_SESSION_USER_ID`（默认 `false`；开启后，对 `agent:main:<provider>:direct:<peer-id>` 这类私聊 sessionKey，会把 `<peer-id>` 作为 MemOS `user_id`）
 - `MEMOS_CONVERSATION_ID`（可选覆盖）
+- `MEMOS_KNOWLEDGEBASE_IDS`（可选；逗号分隔的全局知识库 ID 列表，用于 `/search/memory`，例如：`"kb-123, kb-456"`）
+- `MEMOS_ALLOW_KNOWLEDGEBASE_IDS`（可选；逗号分隔的知识库 ID 列表，用于 `/add/message`，例如：`"kb-123"`）
+- `MEMOS_TAGS`（可选；逗号分隔的标签列表，用于 `/add/message`，默认：`"openclaw"`，例如：`"openclaw, dev"`）
 - `MEMOS_RECALL_GLOBAL`（默认 `true`；为 true 时检索不传 conversation_id）
 - `MEMOS_MULTI_AGENT_MODE`（默认 `false`；是否开启多 Agent 数据隔离模式）
+- `MEMOS_ALLOWED_AGENTS`（可选；多 Agent 模式下的白名单，逗号分隔，例如 `"agent1,agent2"`；为空则所有 Agent 均启用）
 - `MEMOS_CONVERSATION_PREFIX` / `MEMOS_CONVERSATION_SUFFIX`（可选）
 - `MEMOS_CONVERSATION_SUFFIX_MODE`（`none` | `counter`，默认 `none`）
 - `MEMOS_CONVERSATION_RESET_ON_NEW`（默认 `true`，需 hooks.internal.enabled）
@@ -121,6 +127,7 @@ MEMOS_API_KEY=YOUR_TOKEN
   "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,
@@ -141,6 +148,7 @@ MEMOS_API_KEY=YOUR_TOKEN
   "tags": ["openclaw"],
   "agentId": "",
   "multiAgentMode": false,
+  "allowedAgents": [],
   "asyncMode": true,
   "recallFilterEnabled": false,
   "recallFilterBaseUrl": "http://127.0.0.1:11434/v1",
@@ -179,6 +187,133 @@ MEMOS_API_KEY=YOUR_TOKEN
 - **数据隔离**：在调用 `/search/memory`（检索记忆）和 `/add/message`（添加记录）时会自动附带该 `agent_id`，从而保证即使是同一用户下的不同 Agent 之间，记忆和反馈数据也是完全隔离的。
 - **静态配置**：如果需要，也可在上述插件的 `config` 中显式指定 `"agentId": "your_agent_id"` 作为固定值。
 
+### 按 Agent 开关记忆插件
+
+在多 Agent 模式下，可以通过 `MEMOS_ALLOWED_AGENTS` 精确控制哪些 Agent 启用记忆功能。未在白名单中的 Agent 将完全跳过记忆召回和记忆添加。
+
+**环境变量配置**（在 `~/.openclaw/.env` 中设置）：
+```env
+MEMOS_MULTI_AGENT_MODE=true
+MEMOS_ALLOWED_AGENTS="agent1,agent2"
+```
+
+多个 Agent ID 之间用英文逗号分隔。
+
+**插件配置**（在 `openclaw.json` 中设置）：
+```json
+{
+  "plugins": {
+    "entries": {
+      "memos-cloud-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "multiAgentMode": true,
+          "allowedAgents": ["agent1", "agent2"]
+        }
+      }
+    }
+  }
+}
+```
+
+**行为规则**：
+| 配置 | 效果 |
+|------|------|
+| `MEMOS_ALLOWED_AGENTS` 未设置或为空 | 所有 Agent 均启用记忆 |
+| `MEMOS_ALLOWED_AGENTS="agent1,agent2"` | 仅 `agent1` 和 `agent2` 启用，其余跳过 |
+| `MEMOS_ALLOWED_AGENTS="agent1"` | 仅 `agent1` 启用，其他 Agent 均跳过 |
+| `MEMOS_MULTI_AGENT_MODE=false` | 白名单不生效，所有请求按单 Agent 模式处理 |
+
+> **注意**：白名单仅在 `multiAgentMode=true` 时生效。关闭多 Agent 模式时，所有 Agent 的记忆功能均正常工作，白名单配置被忽略。
+
+### 按 Agent 独立配置参数（agentOverrides）
+
+除了按 Agent 开关记忆功能外，你还可以通过 `agentOverrides` 为**每个 Agent 配置不同的记忆参数**，包括知识库、召回条数、相关性阈值等。
+
+**插件配置**（在 `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
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**环境变量配置**（在 `~/.openclaw/.env` 中设置）：
+你可以使用 `MEMOS_AGENT_OVERRIDES` 来配置一个 JSON 字符串，覆盖全局参数。注意：`.env` 中的配置优先级低于 `openclaw.json` 中的 `agentOverrides` 配置。
+```env
+MEMOS_AGENT_OVERRIDES='{"research-agent": {"memoryLimitNumber": 12, "relativity": 0.3}, "coding-agent": {"memoryLimitNumber": 9}}'
+```
+
+**工作原理**：
+- `agentOverrides.<agentId>` 中的字段会覆盖该 Agent 对应的全局默认值
+- 只需写需要覆盖的字段，其余参数从全局配置继承
+- 若某个 Agent 没有对应的 override 条目，则完全使用全局配置
+
+**可覆盖字段**：
+
+| 字段 | 说明 |
+|------|------|
+| `knowledgebaseIds` | `/search/memory` 使用的知识库 ID 列表 |
+| `memoryLimitNumber` | 召回的事实记忆最大条数 |
+| `preferenceLimitNumber` | 召回的偏好记忆最大条数 |
+| `includePreference` | 是否启用偏好记忆召回 |
+| `includeToolMemory` | 是否启用工具记忆召回 |
+| `toolMemoryLimitNumber` | 工具记忆最大条数 |
+| `relativity` | 相关性阈值（0-1） |
+| `recallEnabled` | 该 Agent 是否启用记忆检索 |
+| `addEnabled` | 该 Agent 是否启用记忆写入 |
+| `captureStrategy` | `last_turn` 或 `full_session` |
+| `queryPrefix` | 搜索查询前缀 |
+| `maxItemChars` | 注入 prompt 时每条记忆的最大字符数 |
+| `maxMessageChars` | 写入记忆时每条消息的最大字符数 |
+| `includeAssistant` | 写入记忆时是否包含助手回复 |
+| `recallGlobal` | 全局召回（不传 conversation_id） |
+| `recallFilterEnabled` | 是否启用模型二次过滤 |
+| `recallFilterModel` | 过滤模型名 |
+| `recallFilterBaseUrl` | 过滤模型接口地址 |
+| `recallFilterApiKey` | 过滤模型鉴权密钥 |
+| `allowKnowledgebaseIds` | `/add/message` 允许写入的知识库 |
+| `tags` | `/add/message` 标签 |
+| `throttleMs` | 请求节流间隔 |
+
+## 私聊 Session User ID（Direct Session User ID）
+- **默认行为**：仍然使用配置里的 `userId`（或 `MEMOS_USER_ID`），完全兼容旧行为。
+- **开启方式**：在插件 config 中设置 `"useDirectSessionUserId": true`，或在环境变量中设置 `MEMOS_USE_DIRECT_SESSION_USER_ID=true`。
+- **行为说明**：开启后，像 `agent:main:<provider>:direct:<peer-id>` 这样的私聊 sessionKey，会把 `<peer-id>` 当作 MemOS `user_id`。
+- **不会影响的场景**：像 `agent:main:<provider>:channel:<channel-id>` 这类非私聊 sessionKey，仍继续使用配置好的 fallback `userId`。
+- **作用范围**：同一套解析逻辑同时作用于 `buildSearchPayload()` 和 `buildAddMessagePayload()`，保证 recall 与 add 一致。
+- **配置优先级**：仍遵循插件现有规则——插件 config 优先，其次是 `.env` 文件（`~/.openclaw/.env` -> `~/.moltbot/.env` -> `~/.clawdbot/.env`），最后才回退到进程环境变量。
+
+
 ## 说明
 - 未显式指定 `conversation_id` 时，默认使用 OpenClaw `sessionKey`。**TODO**：后续考虑直接绑定 OpenClaw `sessionId`。
 - 可配置前后缀；`conversationSuffixMode=counter` 时会在 `/new` 递增（需 `hooks.internal.enabled`）。

package/clawdbot.plugin.json

@@ -2,7 +2,7 @@
   "id": "memos-cloud-openclaw-plugin",
   "name": "MemOS Cloud OpenClaw Plugin",
   "description": "MemOS Cloud recall + add memory via lifecycle hooks",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.0",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {
@@ -41,6 +41,11 @@
         ],
         "default": "none"
       },
+      "useDirectSessionUserId": {
+        "type": "boolean",
+        "description": "When enabled, direct-session keys like agent:main:<provider>:direct:<id> use the direct id as MemOS user_id instead of the default configured userId.",
+        "default": false
+      },
       "resetOnNew": {
         "type": "boolean",
         "default": true
@@ -174,6 +179,13 @@
         "type": "boolean",
         "default": false
       },
+      "allowedAgents": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "When multiAgentMode is true, only these agent IDs will activate the memory plugin. Comma-separated in env var MEMOS_ALLOWED_AGENTS. Empty list means all agents are allowed."
+      },
       "appId": {
         "type": "string"
       },
@@ -202,6 +214,108 @@
       "throttleMs": {
         "type": "integer",
         "default": 0
+      },
+      "agentOverrides": {
+        "type": "object",
+        "description": "Per-agent config overrides. Keys are agent IDs, values override global defaults for that agent.",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "knowledgebaseIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "memoryLimitNumber": {
+              "type": "integer"
+            },
+            "preferenceLimitNumber": {
+              "type": "integer"
+            },
+            "includePreference": {
+              "type": "boolean"
+            },
+            "includeToolMemory": {
+              "type": "boolean"
+            },
+            "toolMemoryLimitNumber": {
+              "type": "integer"
+            },
+            "includeSkill": {
+              "type": "boolean"
+            },
+            "skillLimitNumber": {
+              "type": "integer"
+            },
+            "relativity": {
+              "type": "number"
+            },
+            "filter": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "recallEnabled": {
+              "type": "boolean"
+            },
+            "addEnabled": {
+              "type": "boolean"
+            },
+            "captureStrategy": {
+              "type": "string",
+              "enum": [
+                "last_turn",
+                "full_session"
+              ]
+            },
+            "queryPrefix": {
+              "type": "string"
+            },
+            "maxQueryChars": {
+              "type": "integer"
+            },
+            "maxItemChars": {
+              "type": "integer"
+            },
+            "maxMessageChars": {
+              "type": "integer"
+            },
+            "includeAssistant": {
+              "type": "boolean"
+            },
+            "recallGlobal": {
+              "type": "boolean"
+            },
+            "recallFilterEnabled": {
+              "type": "boolean"
+            },
+            "recallFilterModel": {
+              "type": "string"
+            },
+            "recallFilterBaseUrl": {
+              "type": "string"
+            },
+            "recallFilterApiKey": {
+              "type": "string"
+            },
+            "allowKnowledgebaseIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "throttleMs": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": false
+        }
       }
     },
     "additionalProperties": false

package/index.js

@@ -5,6 +5,8 @@ import {
   extractResultData,
   extractText,
   formatRecallHookResult,
+  isAgentAllowed,
+  resolveAgentConfig,
   searchMemory,
   stripOpenClawInjectedPrefix,
 } from "./lib/memos-cloud-api.js";
@@ -53,6 +55,21 @@ function getEffectiveAgentId(cfg, ctx) {
   return agentId === "main" ? undefined : agentId;
 }
 
+export function extractDirectSessionUserId(sessionKey) {
+  if (!sessionKey || typeof sessionKey !== "string") return "";
+  const parts = sessionKey.split(":");
+  const directIndex = parts.lastIndexOf("direct");
+  if (directIndex === -1) return "";
+  return parts[directIndex + 1] || "";
+}
+
+export function resolveMemosUserId(cfg, ctx) {
+  const fallback = cfg?.userId || "openclaw-user";
+  if (!cfg?.useDirectSessionUserId) return fallback;
+  const directUserId = extractDirectSessionUserId(ctx?.sessionKey);
+  return directUserId || fallback;
+}
+
 function resolveConversationId(cfg, ctx) {
   if (cfg.conversationId) return cfg.conversationId;
   // TODO: consider binding conversation_id directly to OpenClaw sessionId (prefer ctx.sessionId).
@@ -65,7 +82,7 @@ function resolveConversationId(cfg, ctx) {
   return `${prefix}openclaw-${Date.now()}${dynamicSuffix}${suffix}`;
 }
 
-function buildSearchPayload(cfg, prompt, ctx) {
+export function buildSearchPayload(cfg, prompt, ctx) {
   const cleanPrompt = stripOpenClawInjectedPrefix(prompt);
   const queryRaw = `${cfg.queryPrefix || ""}${cleanPrompt}`;
   const query =
@@ -74,7 +91,7 @@ function buildSearchPayload(cfg, prompt, ctx) {
       : queryRaw;
 
   const payload = {
-    user_id: cfg.userId,
+    user_id: resolveMemosUserId(cfg, ctx),
     query,
     source: MEMOS_SOURCE,
   };
@@ -113,9 +130,9 @@ function buildSearchPayload(cfg, prompt, ctx) {
   return payload;
 }
 
-function buildAddMessagePayload(cfg, messages, ctx) {
+export function buildAddMessagePayload(cfg, messages, ctx) {
   const payload = {
-    user_id: cfg.userId,
+    user_id: resolveMemosUserId(cfg, ctx),
     conversation_id: resolveConversationId(cfg, ctx),
     messages,
     source: MEMOS_SOURCE,
@@ -413,6 +430,15 @@ export default {
       log.warn?.(`[memos-cloud] No .env found in ${searchPaths}; falling back to process env or plugin config.`);
     }
 
+    if (cfg.multiAgentMode && cfg.allowedAgents?.length > 0) {
+      log.info?.(`[memos-cloud] Multi-agent mode enabled. Allowed agents: [${cfg.allowedAgents.join(", ")}]`);
+    }
+
+    const overrideAgentIds = Object.keys(cfg._agentOverrides || {});
+    if (overrideAgentIds.length > 0) {
+      log.info?.(`[memos-cloud] Per-agent overrides configured for: [${overrideAgentIds.join(", ")}]`);
+    }
+
     if (cfg.conversationSuffixMode === "counter" && cfg.resetOnNew) {
       if (api.config?.hooks?.internal?.enabled !== true) {
         log.warn?.("[memos-cloud] command:new hook requires hooks.internal.enabled = true");
@@ -432,24 +458,29 @@ export default {
     }
 
     api.on("before_agent_start", async (event, ctx) => {
-      if (!cfg.recallEnabled) return;
+      if (!isAgentAllowed(cfg, ctx)) {
+        log.info?.(`[memos-cloud] recall skipped: agent "${ctx?.agentId}" not in allowedAgents [${cfg.allowedAgents?.join(", ")}]`);
+        return;
+      }
+      const agentCfg = resolveAgentConfig(cfg, ctx?.agentId);
+      if (!agentCfg.recallEnabled) return;
       const userPrompt = stripOpenClawInjectedPrefix(event?.prompt || "");
       if (!userPrompt || userPrompt.length < 3) return;
-      if (!cfg.apiKey) {
+      if (!agentCfg.apiKey) {
         warnMissingApiKey(log, "recall");
         return;
       }
 
       try {
-        const payload = buildSearchPayload(cfg, userPrompt, ctx);
-        const result = await searchMemory(cfg, payload);
+        const payload = buildSearchPayload(agentCfg, userPrompt, ctx);
+        const result = await searchMemory(agentCfg, payload);
         const resultData = extractResultData(result);
         if (!resultData) return;
-        const filteredData = await maybeFilterRecallData(cfg, resultData, userPrompt, log);
+        const filteredData = await maybeFilterRecallData(agentCfg, resultData, userPrompt, log);
         const hookResult = formatRecallHookResult({ data: filteredData }, {
           wrapTagBlocks: true,
           relativity: payload.relativity,
-          maxItemChars: cfg.maxItemChars,
+          maxItemChars: agentCfg.maxItemChars,
         });
         if (!hookResult.appendSystemContext && !hookResult.prependContext) return;
 
@@ -460,29 +491,34 @@ export default {
     });
 
     api.on("agent_end", async (event, ctx) => {
-      if (!cfg.addEnabled) return;
+      if (!isAgentAllowed(cfg, ctx)) {
+        log.info?.(`[memos-cloud] add skipped: agent "${ctx?.agentId}" not in allowedAgents [${cfg.allowedAgents?.join(", ")}]`);
+        return;
+      }
+      const agentCfg = resolveAgentConfig(cfg, ctx?.agentId);
+      if (!agentCfg.addEnabled) return;
       if (!event?.success || !event?.messages?.length) return;
-      if (!cfg.apiKey) {
+      if (!agentCfg.apiKey) {
         warnMissingApiKey(log, "add");
         return;
       }
 
       const now = Date.now();
-      if (cfg.throttleMs && now - lastCaptureTime < cfg.throttleMs) {
+      if (agentCfg.throttleMs && now - lastCaptureTime < agentCfg.throttleMs) {
         return;
       }
       lastCaptureTime = now;
 
       try {
         const messages =
-          cfg.captureStrategy === "full_session"
-            ? pickFullSessionMessages(event.messages, cfg)
-            : pickLastTurnMessages(event.messages, cfg);
+          agentCfg.captureStrategy === "full_session"
+            ? pickFullSessionMessages(event.messages, agentCfg)
+            : pickLastTurnMessages(event.messages, agentCfg);
 
         if (!messages.length) return;
 
-        const payload = buildAddMessagePayload(cfg, messages, ctx);
-        await addMessage(cfg, payload);
+        const payload = buildAddMessagePayload(agentCfg, messages, ctx);
+        await addMessage(agentCfg, payload);
       } catch (err) {
         log.warn?.(`[memos-cloud] add failed: ${String(err)}`);
       }

package/lib/memos-cloud-api.js

@@ -157,6 +157,28 @@ function parseNumber(value, fallback) {
   return Number.isFinite(n) ? n : fallback;
 }
 
+function parseStringArray(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value.map((v) => String(v).trim()).filter(Boolean);
+  return String(value)
+    .split(",")
+    .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+    .filter(Boolean);
+}
+
+function parseJsonObject(value) {
+  if (!value || typeof value !== "string") return null;
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // ignore parse error
+  }
+  return null;
+}
+
 export function buildConfig(pluginConfig = {}) {
   const cfg = pluginConfig ?? {};
 
@@ -184,6 +206,10 @@ export function buildConfig(pluginConfig = {}) {
     parseBool(loadEnvVar("MEMOS_MULTI_AGENT_MODE"), false),
   );
 
+  const allowedAgents = parseStringArray(
+    cfg.allowedAgents ?? loadEnvVar("MEMOS_ALLOWED_AGENTS"),
+  );
+
   const recallFilterEnabled = parseBool(
     cfg.recallFilterEnabled,
     parseBool(loadEnvVar("MEMOS_RECALL_FILTER_ENABLED"), false),
@@ -200,6 +226,10 @@ export function buildConfig(pluginConfig = {}) {
       ? parseBool(loadEnvVar("MEMOS_INCLUDE_ASSISTANT"), true)
       : cfg.includeAssistant !== false;
   const maxMessageChars = cfg.maxMessageChars ?? parseNumber(loadEnvVar("MEMOS_MAX_MESSAGE_CHARS"), 20000);
+  const useDirectSessionUserId = parseBool(
+    cfg.useDirectSessionUserId,
+    parseBool(loadEnvVar("MEMOS_USE_DIRECT_SESSION_USER_ID"), false),
+  );
 
   return {
     baseUrl: baseUrl.replace(/\/+$/, ""),
@@ -209,6 +239,7 @@ export function buildConfig(pluginConfig = {}) {
     conversationIdPrefix,
     conversationIdSuffix,
     conversationSuffixMode,
+    useDirectSessionUserId,
     recallGlobal,
     resetOnNew,
     envFileStatus: getEnvFileStatus(),
@@ -230,15 +261,16 @@ export function buildConfig(pluginConfig = {}) {
       return v ? parseFloat(v) : 0.45;
     })()),
     filter: cfg.filter,
-    knowledgebaseIds: cfg.knowledgebaseIds ?? [],
-    tags: cfg.tags ?? ["openclaw"],
+    knowledgebaseIds: cfg.knowledgebaseIds ?? (loadEnvVar("MEMOS_KNOWLEDGEBASE_IDS") ? parseStringArray(loadEnvVar("MEMOS_KNOWLEDGEBASE_IDS")) : []),
+    tags: cfg.tags ?? (loadEnvVar("MEMOS_TAGS") ? parseStringArray(loadEnvVar("MEMOS_TAGS")) : ["openclaw"]),
     info: cfg.info ?? {},
     agentId: cfg.agentId,
     appId: cfg.appId,
     allowPublic: cfg.allowPublic ?? false,
-    allowKnowledgebaseIds: cfg.allowKnowledgebaseIds ?? [],
+    allowKnowledgebaseIds: cfg.allowKnowledgebaseIds ?? (loadEnvVar("MEMOS_ALLOW_KNOWLEDGEBASE_IDS") ? parseStringArray(loadEnvVar("MEMOS_ALLOW_KNOWLEDGEBASE_IDS")) : []),
     asyncMode,
     multiAgentMode,
+    allowedAgents,
     recallFilterEnabled,
     recallFilterBaseUrl:
       (cfg.recallFilterBaseUrl ?? loadEnvVar("MEMOS_RECALL_FILTER_BASE_URL") ?? "").replace(/\/+$/, ""),
@@ -257,9 +289,35 @@ export function buildConfig(pluginConfig = {}) {
     timeoutMs: cfg.timeoutMs ?? 5000,
     retries: cfg.retries ?? 1,
     throttleMs,
+    _agentOverrides: cfg.agentOverrides ?? parseJsonObject(loadEnvVar("MEMOS_AGENT_OVERRIDES")) ?? {},
   };
 }
 
+const AGENT_OVERRIDABLE_KEYS = [
+  "knowledgebaseIds", "memoryLimitNumber", "preferenceLimitNumber",
+  "includePreference", "includeToolMemory", "toolMemoryLimitNumber",
+  "relativity",
+  "recallEnabled", "addEnabled", "captureStrategy", "queryPrefix",
+  "maxItemChars", "maxMessageChars", "includeAssistant",
+  "recallGlobal", "recallFilterEnabled", "recallFilterModel",
+  "recallFilterBaseUrl", "recallFilterApiKey",
+  "allowKnowledgebaseIds", "tags", "throttleMs",
+];
+
+export function resolveAgentConfig(baseCfg, agentId) {
+  if (!agentId || !baseCfg._agentOverrides) return baseCfg;
+  const overrides = baseCfg._agentOverrides[agentId];
+  if (!overrides || typeof overrides !== "object") return baseCfg;
+
+  const merged = { ...baseCfg };
+  for (const key of AGENT_OVERRIDABLE_KEYS) {
+    if (key in overrides) {
+      merged[key] = overrides[key];
+    }
+  }
+  return merged;
+}
+
 export async function callApi({ baseUrl, apiKey, timeoutMs = 5000, retries = 1 }, path, body) {
   if (!apiKey) {
     throw new Error("Missing MEMOS API key (Token auth)");
@@ -317,6 +375,13 @@ function sanitizeAddMessageEntry(entry) {
   return { ...entry, content };
 }
 
+export function isAgentAllowed(cfg, ctx) {
+  if (!cfg.multiAgentMode) return true;
+  if (!cfg.allowedAgents || cfg.allowedAgents.length === 0) return true;
+  const agentId = ctx?.agentId || cfg.agentId || "main";
+  return cfg.allowedAgents.includes(agentId);
+}
+
 export async function searchMemory(cfg, payload) {
   return callApi(cfg, "/search/memory", sanitizeSearchPayload(payload));
 }

package/moltbot.plugin.json

@@ -2,7 +2,7 @@
   "id": "memos-cloud-openclaw-plugin",
   "name": "MemOS Cloud OpenClaw Plugin",
   "description": "MemOS Cloud recall + add memory via lifecycle hooks",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.0",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {
@@ -41,6 +41,11 @@
         ],
         "default": "none"
       },
+      "useDirectSessionUserId": {
+        "type": "boolean",
+        "description": "When enabled, direct-session keys like agent:main:<provider>:direct:<id> use the direct id as MemOS user_id instead of the default configured userId.",
+        "default": false
+      },
       "resetOnNew": {
         "type": "boolean",
         "default": true
@@ -174,6 +179,13 @@
         "type": "boolean",
         "default": false
       },
+      "allowedAgents": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "When multiAgentMode is true, only these agent IDs will activate the memory plugin. Comma-separated in env var MEMOS_ALLOWED_AGENTS. Empty list means all agents are allowed."
+      },
       "appId": {
         "type": "string"
       },
@@ -202,6 +214,108 @@
       "throttleMs": {
         "type": "integer",
         "default": 0
+      },
+      "agentOverrides": {
+        "type": "object",
+        "description": "Per-agent config overrides. Keys are agent IDs, values override global defaults for that agent.",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "knowledgebaseIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "memoryLimitNumber": {
+              "type": "integer"
+            },
+            "preferenceLimitNumber": {
+              "type": "integer"
+            },
+            "includePreference": {
+              "type": "boolean"
+            },
+            "includeToolMemory": {
+              "type": "boolean"
+            },
+            "toolMemoryLimitNumber": {
+              "type": "integer"
+            },
+            "includeSkill": {
+              "type": "boolean"
+            },
+            "skillLimitNumber": {
+              "type": "integer"
+            },
+            "relativity": {
+              "type": "number"
+            },
+            "filter": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "recallEnabled": {
+              "type": "boolean"
+            },
+            "addEnabled": {
+              "type": "boolean"
+            },
+            "captureStrategy": {
+              "type": "string",
+              "enum": [
+                "last_turn",
+                "full_session"
+              ]
+            },
+            "queryPrefix": {
+              "type": "string"
+            },
+            "maxQueryChars": {
+              "type": "integer"
+            },
+            "maxItemChars": {
+              "type": "integer"
+            },
+            "maxMessageChars": {
+              "type": "integer"
+            },
+            "includeAssistant": {
+              "type": "boolean"
+            },
+            "recallGlobal": {
+              "type": "boolean"
+            },
+            "recallFilterEnabled": {
+              "type": "boolean"
+            },
+            "recallFilterModel": {
+              "type": "string"
+            },
+            "recallFilterBaseUrl": {
+              "type": "string"
+            },
+            "recallFilterApiKey": {
+              "type": "string"
+            },
+            "allowKnowledgebaseIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "throttleMs": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": false
+        }
       }
     },
     "additionalProperties": false

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "memos-cloud-openclaw-plugin",
   "name": "MemOS Cloud OpenClaw Plugin",
   "description": "MemOS Cloud recall + add memory via lifecycle hooks",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.0",
   "kind": "lifecycle",
   "main": "./index.js",
   "configSchema": {
@@ -41,6 +41,11 @@
         ],
         "default": "none"
       },
+      "useDirectSessionUserId": {
+        "type": "boolean",
+        "description": "When enabled, direct-session keys like agent:main:<provider>:direct:<id> use the direct id as MemOS user_id instead of the default configured userId.",
+        "default": false
+      },
       "resetOnNew": {
         "type": "boolean",
         "default": true
@@ -174,6 +179,13 @@
         "type": "boolean",
         "default": false
       },
+      "allowedAgents": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "When multiAgentMode is true, only these agent IDs will activate the memory plugin. Comma-separated in env var MEMOS_ALLOWED_AGENTS. Empty list means all agents are allowed."
+      },
       "appId": {
         "type": "string"
       },
@@ -202,6 +214,108 @@
       "throttleMs": {
         "type": "integer",
         "default": 0
+      },
+      "agentOverrides": {
+        "type": "object",
+        "description": "Per-agent config overrides. Keys are agent IDs, values override global defaults for that agent.",
+        "additionalProperties": {
+          "type": "object",
+          "properties": {
+            "knowledgebaseIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "memoryLimitNumber": {
+              "type": "integer"
+            },
+            "preferenceLimitNumber": {
+              "type": "integer"
+            },
+            "includePreference": {
+              "type": "boolean"
+            },
+            "includeToolMemory": {
+              "type": "boolean"
+            },
+            "toolMemoryLimitNumber": {
+              "type": "integer"
+            },
+            "includeSkill": {
+              "type": "boolean"
+            },
+            "skillLimitNumber": {
+              "type": "integer"
+            },
+            "relativity": {
+              "type": "number"
+            },
+            "filter": {
+              "type": "object",
+              "additionalProperties": true
+            },
+            "recallEnabled": {
+              "type": "boolean"
+            },
+            "addEnabled": {
+              "type": "boolean"
+            },
+            "captureStrategy": {
+              "type": "string",
+              "enum": [
+                "last_turn",
+                "full_session"
+              ]
+            },
+            "queryPrefix": {
+              "type": "string"
+            },
+            "maxQueryChars": {
+              "type": "integer"
+            },
+            "maxItemChars": {
+              "type": "integer"
+            },
+            "maxMessageChars": {
+              "type": "integer"
+            },
+            "includeAssistant": {
+              "type": "boolean"
+            },
+            "recallGlobal": {
+              "type": "boolean"
+            },
+            "recallFilterEnabled": {
+              "type": "boolean"
+            },
+            "recallFilterModel": {
+              "type": "string"
+            },
+            "recallFilterBaseUrl": {
+              "type": "string"
+            },
+            "recallFilterApiKey": {
+              "type": "string"
+            },
+            "allowKnowledgebaseIds": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "tags": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "throttleMs": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": false
+        }
       }
     },
     "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memtensor/memos-cloud-openclaw-plugin",
-  "version": "0.1.10",
+  "version": "0.1.11-beta.0",
   "description": "OpenClaw lifecycle plugin for MemOS Cloud (add + recall memory)",
   "scripts": {
     "sync-version": "node scripts/sync-version.js",

package/test/direct-session-user-id.test.mjs

@@ -0,0 +1,94 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildConfig } from "../lib/memos-cloud-api.js";
+import {
+  buildAddMessagePayload,
+  buildSearchPayload,
+  extractDirectSessionUserId,
+  resolveMemosUserId,
+} from "../index.js";
+
+test("buildConfig keeps useDirectSessionUserId disabled by default", () => {
+  const previous = process.env.MEMOS_USE_DIRECT_SESSION_USER_ID;
+  delete process.env.MEMOS_USE_DIRECT_SESSION_USER_ID;
+  try {
+    const cfg = buildConfig({});
+    assert.equal(cfg.useDirectSessionUserId, false);
+  } finally {
+    if (previous === undefined) {
+      delete process.env.MEMOS_USE_DIRECT_SESSION_USER_ID;
+    } else {
+      process.env.MEMOS_USE_DIRECT_SESSION_USER_ID = previous;
+    }
+  }
+});
+
+test("extractDirectSessionUserId returns the id for direct session keys", () => {
+  assert.equal(
+    extractDirectSessionUserId("agent:main:discord:direct:1160853368999247882"),
+    "1160853368999247882",
+  );
+  assert.equal(extractDirectSessionUserId("agent:main:telegram:direct:8361983702"), "8361983702");
+});
+
+test("extractDirectSessionUserId ignores non-direct session keys", () => {
+  assert.equal(extractDirectSessionUserId("agent:main:discord:channel:1482035270651220051"), "");
+  assert.equal(extractDirectSessionUserId(""), "");
+});
+
+test("resolveMemosUserId falls back to configured userId when switch is off", () => {
+  const cfg = { userId: "openclaw-user", useDirectSessionUserId: false };
+  const ctx = { sessionKey: "agent:main:discord:direct:1160853368999247882" };
+  assert.equal(resolveMemosUserId(cfg, ctx), "openclaw-user");
+});
+
+test("resolveMemosUserId uses direct id when switch is on", () => {
+  const cfg = { userId: "openclaw-user", useDirectSessionUserId: true };
+  const ctx = { sessionKey: "agent:main:discord:direct:1160853368999247882" };
+  assert.equal(resolveMemosUserId(cfg, ctx), "1160853368999247882");
+});
+
+test("buildSearchPayload uses direct session id as user_id for private chats", () => {
+  const cfg = {
+    userId: "openclaw-user",
+    useDirectSessionUserId: true,
+    queryPrefix: "",
+    maxQueryChars: 0,
+    recallGlobal: true,
+    knowledgebaseIds: [],
+    memoryLimitNumber: 6,
+    includePreference: true,
+    preferenceLimitNumber: 6,
+    includeToolMemory: false,
+    toolMemoryLimitNumber: 0,
+    relativity: 0.45,
+    multiAgentMode: false,
+  };
+  const ctx = { sessionKey: "agent:main:discord:direct:1160853368999247882" };
+
+  const payload = buildSearchPayload(cfg, "你好", ctx);
+  assert.equal(payload.user_id, "1160853368999247882");
+});
+
+test("buildAddMessagePayload keeps configured userId for non-direct chats", () => {
+  const cfg = {
+    userId: "openclaw-user",
+    useDirectSessionUserId: true,
+    multiAgentMode: false,
+    appId: "",
+    tags: [],
+    info: {},
+    allowPublic: false,
+    allowKnowledgebaseIds: [],
+    asyncMode: true,
+    conversationId: "",
+    conversationIdPrefix: "",
+    conversationIdSuffix: "",
+    conversationSuffixMode: "none",
+  };
+  const ctx = { sessionKey: "agent:main:discord:channel:1482035270651220051" };
+
+  const payload = buildAddMessagePayload(cfg, [{ role: "user", content: "hi" }], ctx);
+  assert.equal(payload.user_id, "openclaw-user");
+});