Official MemOS Cloud plugin for OpenClaw. Enables long-term memory for agents by recalling context before execution and saving conversations after each run.
On gateway start, the plugin launches a local config page and prints the URL in the terminal (default: http://127.0.0.1:38463).
The page reads and writes the host config file directly:
OpenClaw: ~/.openclaw/openclaw.json
Moltbot: ~/.moltbot/moltbot.json
ClawDBot: ~/.clawdbot/clawdbot.json
If the preferred UI port is already in use, the plugin automatically picks the next free port.
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).
Note for Windows Users:
If you encounter Error: spawn EINVAL, this is a known issue with OpenClaw's plugin installer on Windows. Please use Option B (Manual Install) below.
Note: The extracted folder usually contains a package subfolder. Point to the folder containing package.json.
Restart the gateway after config changes.
Environment Variables
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.
For env files, it tries them in order (openclaw → moltbot → clawdbot). For each key, the first file with a value wins.
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")
Recall (before_prompt_build; falls back to before_agent_start on older OpenClaw hosts)
Builds a /search/memory request using user_id, query (= prompt + optional prefix), and optional filters.
Default global recall: when recallGlobal=true, it does not pass conversation_id.
Optional second-pass filtering: if recallFilterEnabled=true, candidates are sent to your configured model and only returned keep items are injected.
Injects a stable MemOS recall protocol via appendSystemContext, while the retrieved <memories> block remains in prependContext.
Add (agent_end)
Builds a /add/message request with the last turn by default (user + assistant).
Sends messages with user_id, conversation_id, and optional tags/info/agent_id/app_id.
Multi-Agent Support
The plugin provides native support for multi-agent architectures (via the agent_id parameter):
Enable Mode: Set "multiAgentMode": true in config or MEMOS_MULTI_AGENT_MODE=true in env variables (default is false).
Dynamic Context: When enabled, it automatically captures ctx.agentId during OpenClaw lifecycle hooks. (Note: the default OpenClaw agent "main" is ignored to preserve backwards compatibility for single-agent users).
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.
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.
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.
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).
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).
Acknowledgements
Thanks to @anatolykoptev (Contributor) — LinkedIn: https://www.linkedin.com/in/koptev?utm_source=share&utm_campaign=share_via&utm_content=profile&utm_medium=ios_app
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.