A minimal OpenClaw lifecycle plugin that recalls memories from MemOS Cloud before each run and adds new messages to MemOS Cloud after each run.

Features

Recall: before_prompt_build (before_agent_start on known older OpenClaw hosts, Moltbot, and ClawDBot) → /search/memory
Add: agent_end → /add/message
Config UI: starting the gateway also starts a local plugin config page for editing plugins.entries.memos-cloud-openclaw-plugin.config
Uses Token auth (Authorization: Token <MEMOS_API_KEY>)

Config UI

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).

Install

Option A — Install from NPM

openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
openclaw gateway restart

Make sure it’s enabled in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "memos-cloud-openclaw-plugin": { "enabled": true }
    }
  }
}

Option B — Development install from this repository

Run these commands from the monorepo repository root. prepare:openclaw installs workspace dependencies and builds the shared core into this package; it does not install the plugin or restart OpenClaw.

pnpm prepare:openclaw
openclaw plugins install .\packages\openclaw
openclaw gateway restart

This installs a copy under OpenClaw's extensions directory and does not require a plugins.load entry. After changing the plugin source or packages/core, rerun preparation and reinstall the directory, then restart the gateway.

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.

Where to configure

Files (priority order):
- ~/.openclaw/.env
- ~/.moltbot/.env
- ~/.clawdbot/.env
Each line is KEY=value

Quick setup (shell / Windows)

echo 'MEMOS_API_KEY="mpg-..."' >> ~/.openclaw/.env

If MEMOS_API_KEY is missing, the plugin will warn with setup instructions and the API key URL.

Minimal config

MEMOS_API_KEY=YOUR_TOKEN

Optional config

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: 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:

{
  "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,
  "recallGlobal": true,
  "addEnabled": true,
  "captureStrategy": "last_turn",
  "maxItemChars": 8000,
  "includeAssistant": true,
  "conversationIdPrefix": "",
  "conversationIdSuffix": "",
  "conversationSuffixMode": "none",
  "resetOnNew": true,
  "knowledgebaseIds": [],
  "memoryLimitNumber": 6,
  "preferenceLimitNumber": 6,
  "includePreference": true,
  "includeToolMemory": false,
  "toolMemoryLimitNumber": 6,
  "relativity": 0.45,
  "tags": ["openclaw"],
  "agentId": "",
  "multiAgentMode": false,
  "allowedAgents": [],
  "asyncMode": true,
  "recallFilterEnabled": false,
  "recallFilterBaseUrl": "http://127.0.0.1:11434/v1",
  "recallFilterApiKey": "",
  "recallFilterModel": "qwen2.5:7b",
  "recallFilterTimeoutMs": 30000,
  "recallFilterRetries": 1,
  "recallFilterCandidateLimit": 30,
  "recallFilterMaxItemChars": 500,
  "recallFilterFailOpen": true,
  "throttleMs": 0,
  "maxMessageChars": 20000
}

How it Works

1) Recall (`before_prompt_build`; legacy hosts use `before_agent_start`)

Recall first reads the running host's api.runtime.version: versions from 2026.5.7 use before_prompt_build; earlier versions use before_agent_start, including official Moltbot/ClawDBot releases. This preserves the plugin's original migration boundary. If the API has no usable version, host package and entrypoint detection provide a fallback; recognized legacy hosts use the old hook, while unknown OpenClaw versions default to the new hook. An early OpenClaw with no detectable version remains a compatibility limitation. Only one recall hook is registered.
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. No user setting is needed: retrieved <memories> remain in prependContext except on confirmed affected OpenClaw releases 2026.10.2–2026.10.7, where current inter_session inputs use appendSystemContext with before_prompt_build. Earlier releases, prereleases (including the unaffected 2026.10.5-beta.1), unknown versions and unverified future releases retain prepend placement to preserve the existing prompt-cache layout. The existing fixed system protocol is also preserved byte-for-byte outside that affected inter-session path. The affected-release list is extended only after verification.
Hosts using legacy before_agent_start, or not providing current input provenance, retain prepended context. The plugin uses only the current turn's host-provided provenance; it never infers the current origin from message text or old history.
System placement includes only filtered memory data, without a user-query marker, and marks it as untrusted reference data for the active agent. Dynamic system content can reduce prompt-cache reuse. Memory retrieval identity and filters are unchanged; no message or source envelope is rewritten.

2) 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.

Environment variable (in ~/.openclaw/.env):

MEMOS_MULTI_AGENT_MODE=true
MEMOS_ALLOWED_AGENTS="agent1,agent2"

Separate multiple agent IDs with commas.

Plugin config (in openclaw.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):

{
  "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.

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).

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).