Skip to content

Commit 06d73e7

Browse files
CaralHsiCaralHsi
authored
Update cloud plugin 2026 04 03 (#1416)
## Description This PR introduces several major enhancements to the MemOS Cloud OpenClaw Plugin, bumping the version to 0.1.12 : 1. Config UI Web Server : Added a local web-based configuration UI ( lib/config-ui-server.js and frontend assets) for real-time visualization, modification, and syncing of plugin settings. 2. Aliyun ARMS RUM Integration : Implemented custom event reporting ( lib/arms-reporter.js ) to track core behaviors like memory search and recall filtering. 3. Configuration Schema Refactoring : Centralized configuration definitions into lib/config-resolution-schema.js , removing redundant default values from plugin JSON manifests ( openclaw.plugin.json , moltbot.plugin.json , etc.). 4. Hooks Enhancements : Officially registered lifecycle hooks via the hooks array in package.json and documented command:new usages. 5. Updated README.md , README_ZH.md , and HOOK.md to reflect the new configurations and UI server usage. ## Type of change Please delete options that are not relevant. - [x] New feature (non-breaking change which adds functionality) - [x] Refactor (does not change functionality, e.g. code style improvements, linting) - [x] Documentation update ## How Has This Been Tested? - [x] Test Script Or Test Steps: 1. Ran the local gateway and verified that the Config UI server starts automatically and becomes available in the browser. 2. Modified configuration properties via the UI and ensured disk synchronization matches runtime behavior. 3. Validated ARMS reporter successfully triggers during memory recall events without disrupting core plugin flow. 4. Verified that configuration values fall back appropriately between UI, config , and env per the new centralized schema. ## Checklist - [x] I have performed a self-review of my own code | 我已自行检查了自己的代码 - [x] I have commented my code in hard-to-understand areas | 我已在难以理解的地方对代码进行了注释 - [x] I have added tests that prove my fix is effective or that my feature works | 我已添加测试以证明我的修复有效或功能正常 - [x] I have created related documentation issue/PR in MemOS-Docs (if applicable) | 我已在 MemOS-Docs 中创建了相关的文档 issue/PR（如果适用） - [x] I have linked the issue to this PR (if applicable) | 我已将 issue 链接到此 PR（如果适用） - [x] I have mentioned the person who will review this PR | 我已提及将审查此 PR 的人 ## Reviewer Checklist - [ ] closes #xxxx (Replace xxxx with the GitHub issue number) - [ ] Made sure Checks passed - [ ] Tests have been provided
2 parents 6703bf3 + 735f74f commit 06d73e7

File tree

18 files changed

+3500
-312
lines changed

18 files changed

+3500
-312
lines changed

‎apps/MemOS-Cloud-OpenClaw-Plugin/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ node_modules
44
# Environment variables
55
.env
66
.env.*
7+
.memos_arms_uid
78

89
# NPM
910
.npmrc

‎apps/MemOS-Cloud-OpenClaw-Plugin/HOOK.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: memos-cloud-openclaw-plugin
3+
description: "OpenClaw lifecycle plugin for MemOS Cloud (add + recall memory)"
4+
homepage: https://github.com/MemTensor/MemOS-Cloud-OpenClaw-Plugin
5+
metadata: {
6+
"openclaw": {
7+
"emoji": "🧠",
8+
"events": ["before_agent_start", "agent_end", "command:new"],
9+
"requires": {
10+
"bins": ["node"]
11+
}
12+
}
13+
}
14+
---
15+
16+
# MemOS Cloud OpenClaw Plugin Hooks
17+
18+
This plugin registers the following OpenClaw lifecycle hooks to interact with MemOS Cloud:
19+
20+
- `before_agent_start`: Intercepts the agent startup sequence to recall relevant memories from MemOS Cloud and injects them into the agent's context.
21+
- `agent_end`: Intercepts the agent termination sequence to capture the completed conversation turn and saves it to MemOS Cloud.
22+
- `command:new`: Increments a numeric conversation suffix when the `/new` command is issued to keep MemOS contexts distinct.

‎apps/MemOS-Cloud-OpenClaw-Plugin/README.md‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,18 @@ A minimal OpenClaw lifecycle plugin that **recalls** memories from MemOS Cloud b
77
## Features
88
- **Recall**: `before_agent_start` → `/search/memory`
99
- **Add**: `agent_end` → `/add/message`
10+
- **Config UI**: starting the gateway also starts a local plugin config page for editing `plugins.entries.memos-cloud-openclaw-plugin.config`
1011
- Uses **Token** auth (`Authorization: Token <MEMOS_API_KEY>`)
1112

13+
## Config UI
14+
- On gateway start, the plugin launches a local config page and prints the URL in the terminal (default: `http://127.0.0.1:38463`).
15+
- The page reads and writes the host config file directly:
16+
- OpenClaw: `~/.openclaw/openclaw.json`
17+
- Moltbot: `~/.moltbot/moltbot.json`
18+
- ClawDBot: `~/.clawdbot/clawdbot.json`
19+
- If the preferred UI port is already in use, the plugin automatically picks the next free port.
20+
- Saving changes writes `plugins.entries.memos-cloud-openclaw-plugin.config`. (Note: you may need to manually restart the gateway after saving for settings to take effect).
21+
1222
## Install
1323

1424
### Option A — NPM (Recommended)
@@ -55,9 +65,8 @@ Make sure it’s enabled in `~/.openclaw/openclaw.json`:
5565
Restart the gateway after config changes.
5666

5767
## Environment Variables
58-
The plugin resolves runtime config in this order: **plugin config → env files → process environment**.
59-
Among env files, it tries them in order (**openclaw → moltbot → clawdbot**). For each key, the first file with a value wins.
60-
If none of these files exist (or the key is missing), it falls back to the process environment.
68+
The plugin resolves runtime config in this order: **plugin config → env files**. Due to strict security sandboxing, it **does not** read credentials from process environment variables.
69+
For env files, it tries them in order (**openclaw → moltbot → clawdbot**). For each key, the first file with a value wins.
6170

6271
**Where to configure**
6372
- Files (priority order):
@@ -66,19 +75,9 @@ If none of these files exist (or the key is missing), it falls back to the proce
6675
- `~/.clawdbot/.env`
6776
- Each line is `KEY=value`
6877

69-
**Quick setup (shell)**
78+
**Quick setup (shell / Windows)**
7079
```bash
71-
echo 'export MEMOS_API_KEY="mpg-..."' >> ~/.zshrc
72-
source ~/.zshrc
73-
# or
74-
75-
echo 'export MEMOS_API_KEY="mpg-..."' >> ~/.bashrc
76-
source ~/.bashrc
77-
```
78-
79-
**Quick setup (Windows PowerShell)**
80-
```powershell
81-
[System.Environment]::SetEnvironmentVariable("MEMOS_API_KEY", "mpg-...", "User")
80+
echo 'MEMOS_API_KEY="mpg-..."' >> ~/.openclaw/.env
8281
```
8382

8483
If `MEMOS_API_KEY` is missing, the plugin will warn with setup instructions and the API key URL.
@@ -306,7 +305,7 @@ MEMOS_AGENT_OVERRIDES='{"research-agent": {"memoryLimitNumber": 12, "relativity"
306305
- **What it does**: when enabled, session keys like `agent:main:<provider>:direct:<peer-id>` reuse `<peer-id>` as MemOS `user_id`.
307306
- **What it does not do**: non-direct session keys such as `agent:main:<provider>:channel:<channel-id>` keep using the configured fallback `userId`.
308307
- **Request paths affected**: the same resolver is used by both `buildSearchPayload()` and `buildAddMessagePayload()`, so recall and add stay consistent.
309-
- **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.
308+
- **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`).
310309

311310

312311
## Notes

‎apps/MemOS-Cloud-OpenClaw-Plugin/README_ZH.md‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,18 @@
99
## 功能
1010
- **Recall**：`before_agent_start` → `/search/memory`
1111
- **Add**：`agent_end` → `/add/message`
12+
- **Config UI**：启动 gateway 时同时启动本地插件配置页面，用来编辑 `plugins.entries.memos-cloud-openclaw-plugin.config`
1213
- 使用 **Token** 认证（`Authorization: Token <MEMOS_API_KEY>`）
1314

15+
## 配置页面
16+
- Gateway 启动后，插件会同时拉起一个本地配置页面，并在终端输出访问地址（默认：`http://127.0.0.1:38463`）。
17+
- 页面会直接读取并写回当前宿主的配置文件：
18+
- OpenClaw：`~/.openclaw/openclaw.json`
19+
- Moltbot：`~/.moltbot/moltbot.json`
20+
- ClawDBot：`~/.clawdbot/clawdbot.json`
21+
- 如果默认端口被占用，插件会自动顺延到下一个可用端口。
22+
- 页面保存后会写回 `plugins.entries.memos-cloud-openclaw-plugin.config`。（注意：保存后可能需要手动重启 Gateway 以使配置生效）
23+
1424
## 安装
1525

1626
### 方式 A — NPM（推荐）
@@ -57,9 +67,8 @@ openclaw gateway restart
5767
修改配置后需要重启 gateway。
5868

5969
## 环境变量
60-
插件运行时配置的优先级是：**插件 config → env 文件 → 进程环境变量**。
70+
插件运行时配置的优先级是：**插件 config → env 文件**。为符合纯粹的安全沙箱规范，插件不再支持回退到进程环境变量去读取敏感凭证。
6171
在 env 文件层，按顺序读取（**openclaw → moltbot → clawdbot**），每个键优先使用最先匹配到的值。
62-
若三个文件都不存在（或该键未找到），才会回退到进程环境变量。
6372

6473
**配置位置**
6574
- 文件（优先级顺序）：
@@ -68,19 +77,9 @@ openclaw gateway restart
6877
- `~/.clawdbot/.env`
6978
- 每行格式：`KEY=value`
7079

71-
**快速配置（Shell）**
80+
**快速配置（Shell / Windows）**
7281
```bash
73-
echo 'export MEMOS_API_KEY="mpg-..."' >> ~/.zshrc
74-
source ~/.zshrc
75-
# 或者
76-
77-
echo 'export MEMOS_API_KEY="mpg-..."' >> ~/.bashrc
78-
source ~/.bashrc
79-
```
80-
81-
**快速配置（Windows PowerShell）**
82-
```powershell
83-
[System.Environment]::SetEnvironmentVariable("MEMOS_API_KEY", "mpg-...", "User")
82+
echo 'MEMOS_API_KEY="mpg-..."' >> ~/.openclaw/.env
8483
```
8584

8685
若未读取到 `MEMOS_API_KEY`，插件会提示配置方式并附 API Key 获取地址。
@@ -311,7 +310,7 @@ MEMOS_AGENT_OVERRIDES='{"research-agent": {"memoryLimitNumber": 12, "relativity"
311310
- **行为说明**：开启后，像 `agent:main:<provider>:direct:<peer-id>` 这样的私聊 sessionKey，会把 `<peer-id>` 当作 MemOS `user_id`。
312311
- **不会影响的场景**：像 `agent:main:<provider>:channel:<channel-id>` 这类非私聊 sessionKey，仍继续使用配置好的 fallback `userId`。
313312
- **作用范围**：同一套解析逻辑同时作用于 `buildSearchPayload()` 和 `buildAddMessagePayload()`，保证 recall 与 add 一致。
314-
- **配置优先级**：仍遵循插件现有规则——插件 config 优先，其次是 `.env` 文件（`~/.openclaw/.env` -> `~/.moltbot/.env` -> `~/.clawdbot/.env`），最后才回退到进程环境变量。
313+
- **配置优先级**：仍遵循插件现有规则——插件 config 优先，其次是 `.env` 文件（`~/.openclaw/.env` -> `~/.moltbot/.env` -> `~/.clawdbot/.env`）。
315314

316315

317316
## 说明

‎apps/MemOS-Cloud-OpenClaw-Plugin/clawdbot.plugin.json‎

Lines changed: 49 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"id": "memos-cloud-openclaw-plugin",
33
"name": "MemOS Cloud OpenClaw Plugin",
44
"description": "MemOS Cloud recall + add memory via lifecycle hooks",
5-
"version": "0.1.11",
5+
"version": "0.1.12",
66
"kind": "lifecycle",
77
"main": "./index.js",
88
"configSchema": {
@@ -18,8 +18,7 @@
1818
},
1919
"userId": {
2020
"type": "string",
21-
"description": "MemOS user_id (default: openclaw-user)",
22-
"default": "openclaw-user"
21+
"description": "MemOS user_id (default: openclaw-user)"
2322
},
2423
"conversationId": {
2524
"type": "string",
@@ -38,17 +37,14 @@
3837
"enum": [
3938
"none",
4039
"counter"
41-
],
42-
"default": "none"
40+
]
4341
},
4442
"useDirectSessionUserId": {
4543
"type": "boolean",
46-
"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.",
47-
"default": false
44+
"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."
4845
},
4946
"resetOnNew": {
50-
"type": "boolean",
51-
"default": true
47+
"type": "boolean"
5248
},
5349
"queryPrefix": {
5450
"type": "string",
@@ -63,8 +59,37 @@
6359
"default": true
6460
},
6561
"recallGlobal": {
66-
"type": "boolean",
67-
"default": true
62+
"type": "boolean"
63+
},
64+
"recallFilterEnabled": {
65+
"type": "boolean"
66+
},
67+
"recallFilterBaseUrl": {
68+
"type": "string",
69+
"description": "OpenAI-compatible base URL for recall filter model"
70+
},
71+
"recallFilterApiKey": {
72+
"type": "string",
73+
"description": "API key for recall filter model endpoint"
74+
},
75+
"recallFilterModel": {
76+
"type": "string",
77+
"description": "Model name used to filter recall candidates"
78+
},
79+
"recallFilterTimeoutMs": {
80+
"type": "integer"
81+
},
82+
"recallFilterRetries": {
83+
"type": "integer"
84+
},
85+
"recallFilterCandidateLimit": {
86+
"type": "integer"
87+
},
88+
"recallFilterMaxItemChars": {
89+
"type": "integer"
90+
},
91+
"recallFilterFailOpen": {
92+
"type": "boolean"
6893
},
6994
"addEnabled": {
7095
"type": "boolean",
@@ -75,26 +100,23 @@
75100
"enum": [
76101
"last_turn",
77102
"full_session"
78-
],
79-
"default": "last_turn"
103+
]
80104
},
81105
"maxMessageChars": {
82106
"type": "integer",
83-
"description": "Max chars per message when adding",
84-
"default": 20000
107+
"description": "Max chars per message when adding"
85108
},
86109
"maxItemChars": {
87110
"type": "integer",
88111
"description": "Max chars per memory item when injecting prompt",
89112
"default": 8000
90113
},
91114
"includeAssistant": {
92-
"type": "boolean",
93-
"default": true
115+
"type": "boolean"
94116
},
95117
"memoryLimitNumber": {
96118
"type": "integer",
97-
"default": 6
119+
"default": 9
98120
},
99121
"preferenceLimitNumber": {
100122
"type": "integer",
@@ -112,50 +134,15 @@
112134
"type": "integer",
113135
"default": 6
114136
},
137+
"relativity": {
138+
"type": "number",
139+
"description": "Minimum relativity score required before a recalled item is injected"
140+
},
115141
"filter": {
116142
"type": "object",
117143
"description": "MemOS search filter",
118144
"additionalProperties": true
119145
},
120-
"relativity": {
121-
"type": "number",
122-
"description": "Search relativity threshold",
123-
"default": 0.45
124-
},
125-
"recallFilterEnabled": {
126-
"type": "boolean",
127-
"default": false
128-
},
129-
"recallFilterBaseUrl": {
130-
"type": "string",
131-
"description": "OpenAI-compatible API base URL for recall filtering"
132-
},
133-
"recallFilterApiKey": {
134-
"type": "string"
135-
},
136-
"recallFilterModel": {
137-
"type": "string"
138-
},
139-
"recallFilterTimeoutMs": {
140-
"type": "integer",
141-
"default": 30000
142-
},
143-
"recallFilterRetries": {
144-
"type": "integer",
145-
"default": 1
146-
},
147-
"recallFilterCandidateLimit": {
148-
"type": "integer",
149-
"default": 30
150-
},
151-
"recallFilterMaxItemChars": {
152-
"type": "integer",
153-
"default": 500
154-
},
155-
"recallFilterFailOpen": {
156-
"type": "boolean",
157-
"default": true
158-
},
159146
"knowledgebaseIds": {
160147
"type": "array",
161148
"items": {
@@ -176,8 +163,7 @@
176163
"type": "string"
177164
},
178165
"multiAgentMode": {
179-
"type": "boolean",
180-
"default": false
166+
"type": "boolean"
181167
},
182168
"allowedAgents": {
183169
"type": "array",
@@ -200,6 +186,9 @@
200186
}
201187
},
202188
"asyncMode": {
189+
"type": "boolean"
190+
},
191+
"rumEnabled": {
203192
"type": "boolean",
204193
"default": true
205194
},
@@ -212,8 +201,7 @@
212201
"default": 1
213202
},
214203
"throttleMs": {
215-
"type": "integer",
216-
"default": 0
204+
"type": "integer"
217205
},
218206
"agentOverrides": {
219207
"type": "object",

0 commit comments

Comments
 (0)