XMemo Cloud Memory plugin for OpenClaw

This is an external OpenClaw plugin. It is distributed through npm and ClawHub; it is not bundled in the default OpenClaw release. Source lives in the standalone repository xmemo-openclaw-memory, following the same external plugin pattern as memory-lancedb, slack, discord, qqbot, and synology-chat.

The plugin uses XMemo as the active long-term memory backend. It competes for the plugins.slots.memory slot and replaces local file-backed or vector-backed memory with XMemo's hosted semantic memory.

Features

Remote semantic memory via XMemo REST API
memory_search / memory_get / memory_store / memory_forget canonical memory tools
xmemo_todo_create / xmemo_todo_list / xmemo_todo_complete reminder tools
xmemo_record_event timeline event tool
Optional automatic capture of high-signal user messages after a successful agent turn
No local embedding model or vector store required
Support for hosted XMemo (https://xmemo.dev) and private/self-hosted instances

Native plugin vs MCP

This is a native OpenClaw plugin (kind: "memory"). It becomes the active memory backend when plugins.slots.memory is set to "xmemo-memory". XMemo also offers an MCP server; the MCP server exposes similar tools but does not occupy the OpenClaw memory slot or replace active-memory recall.

Installation

Install the plugin from npm or ClawHub:

openclaw plugins install @xmemo/openclaw-memory
# or
openclaw plugins install clawhub:@xmemo/openclaw-memory

Then set the memory slot to xmemo-memory and enable the entry as shown below.

Configuration

Activate the plugin by setting the memory slot:

{
  "plugins": {
    "slots": {
      "memory": "xmemo-memory"
    },
    "entries": {
      "xmemo-memory": {
        "enabled": true,
        "package": "@xmemo/openclaw-memory",
        "config": {
          "baseUrl": "https://xmemo.dev",
          "apiKey": { "source": "env", "provider": "default", "id": "XMEMO_KEY" },
          "bucket": "openclaw",
          "scope": "my-project",
          "autoCapture": false
        }
      }
    }
  }
}

Config lives at plugins.entries["xmemo-memory"].config, not plugins.config. For production setups, keep the API key in the environment (XMEMO_KEY) instead of storing it in openclaw.json.

Authentication

Create a scoped API key in the XMemo Memory Console: xmemo.dev → API Keys → Create API key. Copy the one-time secret value, then set it as the XMEMO_KEY environment variable:

export XMEMO_KEY="your-xmemo-api-key"

The key can also be configured with apiKey (preferred) or the deprecated token field. For production setups, keep the key in the environment or a secret manager and omit the apiKey field from openclaw.json; the plugin will read XMEMO_KEY directly.

SecretRef support

The plugin resolves apiKey/token in this order:

A literal string.
An env SecretRef object: { "source": "env", "provider": "default", "id": "XMEMO_KEY" }.
The environment variables XMEMO_KEY, MEMORY_OS_API_KEY, or MEMORY_OS_MCP_TOKEN.

Only env SecretRefs are supported. file and exec sources are not implemented and are rejected by the manifest config schema.

Required environment variables

XMEMO_KEY — XMemo API key (preferred)
MEMORY_OS_API_KEY — alternate env var name
XMEMO_AGENT_INSTANCE_ID — optional stable device-level identifier

Auth mode

By default the credential is sent as X-API-Key. To use Bearer auth or both:

{
  "authMode": "bearer"
}

Allowed values: api-key (default), bearer, both.

Agent identity headers

The plugin sends non-secret attribution headers to XMemo:

X-Memory-OS-Agent-ID: openclaw
X-Memory-OS-Agent-Instance-ID: <stable-device-id>

If XMEMO_AGENT_INSTANCE_ID is not set, a process-local UUID is generated. The plugin does not write JSON sidecars to disk.

CLI

openclaw xmemo status
openclaw xmemo status --json

Auto-capture

When autoCapture: true, the plugin listens for agent_end and stores high-signal user messages (preferences, decisions, facts) to XMemo.

External plugin permission required: OpenClaw external plugins do not receive conversation access by default. To enable auto-capture, add this to your openclaw.json:
{
  "hooks": {
    "allowConversationAccess": ["xmemo-memory"]
  }
}
Without this, the agent_end hook is silently skipped and no messages are captured.

It skips:

envelope/transport metadata
injected context blocks
prompt-injection-looking payloads
messages without a memory trigger word

Customize triggers with customTriggers:

{
  "autoCapture": true,
  "customTriggers": ["save this", "remember for next time"]
}

Smoke test

After installing and configuring the plugin:

export XMEMO_KEY="your-xmemo-api-key"
openclaw xmemo status
openclaw xmemo status --json

Expected results:

status shows configured: true and connected: true (or a clear not connected error if the key/network is wrong).
openclaw plugins inspect xmemo-memory --runtime --json lists the registered tools (memory_search, memory_get, memory_store, memory_forget, plus the xmemo_* workflow tools).

The memory_* tools are invoked by the OpenClaw agent during a turn, not as standalone CLI commands.

Migration from memory-core or memory-lancedb

Switching the memory slot replaces the active backend. Existing local memories remain on disk but are no longer queried automatically. To migrate content into XMemo, use memory_get on the old backend and memory_store on XMemo, or use XMemo's import endpoints.

XMemo Cloud Memory