XMemo for OpenClaw README

XMemo for OpenClaw

Native, user-owned long-term memory for OpenClaw agents.

Replace the active OpenClaw memory backend with XMemo for durable recall, cross-agent context, continuity tools, and governed cloud memory.

English · 简体中文

Quick start · Architecture · Tools · Configuration · Operations · Security

@xmemo/openclaw-memory is the native XMemo memory provider for OpenClaw. It registers as kind: "memory" and becomes OpenClaw's active long-term memory backend when the xmemo-memory slot is selected.

The plugin talks directly to XMemo. No local embedding model or vector database is required. Memories written by approved XMemo clients can be recalled across OpenClaw, ChatGPT, Hermes, Codex, Claude, Cursor, and other connected agents.

[!NOTE] This is an external OpenClaw plugin distributed through ClawHub. It is not bundled in the default OpenClaw release.

Architecture

Why this plugin

• Native active memory — participates in OpenClaw's memory lifecycle instead of exposing a parallel tool collection only.
• Cross-agent context — reads all user-visible XMemo buckets by default, so OpenClaw can reuse memories created by other approved clients.
• No local vector stack — semantic search, persistence, and governance live in XMemo.
• Operational continuity — TODOs, timeline events, and restart snapshots are available beside core memory operations.
• Resilient by default — a user-scoped recall cache and write outbox absorb transient network failures.
• Explicit automation — auto-capture is opt-in, permission-gated, filtered, and secret-aware.

Quick start

Install from ClawHub

openclaw plugins install clawhub:@xmemo/openclaw-memory
printf '%s' 'xmemo_...' | openclaw xmemo setup --stdin
openclaw xmemo status

openclaw xmemo setup enables the plugin, selects xmemo-memory as the active memory slot, and saves the credential source. No manual openclaw.json editing is required for normal installs.

PowerShell:

$xmemoKey = Read-Host "XMemo API key"
$xmemoKey | openclaw xmemo setup --stdin
Remove-Variable xmemoKey

Install from npm

openclaw plugins install @xmemo/openclaw-memory

Reuse an XMemo CLI login

The plugin can reuse the user-scoped credential created by xmemo login:

npm install -g @xmemo/client
xmemo login
openclaw plugins install clawhub:@xmemo/openclaw-memory
openclaw xmemo status

[!TIP] On production or shared hosts, prefer an environment SecretRef: openclaw xmemo setup --env XMEMO_KEY.

Tool catalog

The plugin registers 15 tools. memory_* tools are used by the OpenClaw agent during a turn; they are not standalone shell commands.

Core memory

Continuity and workflow

Owner and governance surfaces

Ledger and audit tools require the corresponding API-key scopes.

Native plugin, Skill, and MCP

These components complement each other but have different responsibilities:

For OpenClaw, the recommended pairing is this plugin plus the XMemo Skill. The Skill guides behavior; the plugin performs real reads and writes.

Hosted MCP at https://xmemo.dev/mcp can coexist with the native plugin, but it creates a second XMemo tool surface. Prefer the native plugin for OpenClaw memory operations and add MCP only when a deliberate portable fallback is needed.

Configuration

Most users should use the CLI setup command. The equivalent explicit configuration is:

{
  "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",
          "readBucket": "%",
          "autoCapture": false
        }
      }
    }
  }
}

Configuration belongs under plugins.entries["xmemo-memory"].config, not plugins.config.

Configuration reference

Previous tagged configurations remain compatible. The deprecated token field is still accepted as an alias for apiKey; new setup writes apiKey.

Cross-agent read policy

bucket and scope control where OpenClaw-authored memories are written. Recall and search read all visible user-owned XMemo memories by default:

{
  "bucket": "openclaw",
  "readBucket": "%",
  "readScope": null
}

Advanced operators can narrow reads with readBucket and readScope.

Authentication

Recommended production setup

Make XMEMO_KEY available to the OpenClaw service, then save an environment reference:

export XMEMO_KEY="your-xmemo-api-key"
openclaw xmemo setup --env XMEMO_KEY
openclaw xmemo status

A shell export affects only that shell. Daemon or gateway deployments must set the variable in the service environment.

Credential resolution

The plugin resolves credentials in this order:

1. apiKey or deprecated token string in plugin configuration.
2. An environment SecretRef such as { "source": "env", "provider": "default", "id": "XMEMO_KEY" }.
3. XMEMO_KEY, MEMORY_OS_API_KEY, or MEMORY_OS_MCP_TOKEN.
4. The shared user credential written by xmemo login.

Only env SecretRefs are supported. Unsupported file and exec sources are rejected by the manifest schema.

Shared XMemo CLI credentials default to Bearer authentication. Other credentials default to X-API-Key unless authMode is set explicitly.

Environment variables

Non-localhost http:// service URLs are rejected. Use HTTPS outside local development.

Local resilience

The plugin maintains a small user-scoped recall cache and write outbox:

Storage root:

• $OPENCLAW_DATA_DIR/xmemo/<scope-hash>/ when configured
• $XDG_DATA_HOME/xmemo/<scope-hash>/ on XDG systems
• ~/.xmemo/<scope-hash>/ otherwise

The scope hash is derived from the service URL and a credential hash; the credential itself is never written to the path. Directories and files use owner-only permissions where supported.

Idempotent writes can replay automatically. Non-idempotent writes are held for manual handling to avoid duplicate side effects.

Auto-capture

Auto-capture is disabled by default. When enabled, the plugin inspects successful agent turns for high-signal preferences, decisions, and facts.

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

External plugins need explicit conversation permission:

{
  "hooks": {
    "allowConversationAccess": ["xmemo-memory"]
  }
}

The capture filter rejects transport metadata, injected context, prompt-like payloads, known secret patterns, oversized messages, and content without a memory trigger. At most three eligible messages are captured per processed turn.

Operations

CLI

openclaw xmemo setup --stdin
openclaw xmemo setup --env XMEMO_KEY
openclaw xmemo setup --dry-run
openclaw xmemo status
openclaw xmemo status --json

openclaw xmemo login and openclaw xmemo key set remain deprecated aliases for compatibility.

Health check

openclaw xmemo status --json

Important fields:

• configured — a supported credential source was resolved
• credentialSource — config, env-secret-ref, env, or shared-credential
• connected — the XMemo endpoint passed the connectivity probe
• provider — xmemo-memory

Inspect the loaded plugin runtime:

openclaw plugins inspect xmemo-memory --runtime --json

The output should list the 15 tools, the xmemo CLI, memory capability, and registered lifecycle hooks.

Retrieval troubleshooting

An empty semantic search result does not always prove absence. Retry with:

• alternate wording or synonyms
• the saved path
• the source agent
• an approximate time
• xmemo_memory_list for path-oriented browsing
• debug: true for query expansion and tracing

Memory Operations & Contract Specification

Precise Read vs. Search

Supported References

• Explicit UUID: id: "31ca3aa2-d058-4da8-8dae-5a341e305d61"
• Canonical Path: path: "openclaw/31ca3aa2-d058-4da8-8dae-5a341e305d61" or path: "openclaw/docs/31ca3aa2-d058-4da8-8dae-5a341e305d61"
• Validation: Path traversal (../), null bytes, or malformed IDs fail fast before any network request is issued.

Line Ranges & EOF Pagination

• from: 1-based start line (default: 1).
• lines: Maximum lines to return.
• If from > totalLines, the tool returns a typed range_out_of_bounds error indicating totalLines and the requested line.
• truncated: Only true when unread lines remain after the current slice (startIndex + returnedLines < totalLines), eliminating false EOF truncation.

Cache & Offline Failure Semantics

• Transient-Only Fallback: Stale cache is returned only on transient infrastructure failures (network loss, timeouts, HTTP 5xx, HTTP 429).
• Deterministic Rejection: HTTP 401 Unauthorized, HTTP 403 Forbidden, HTTP 404 Not Found, and AbortError never serve cached content, ensuring revoked permissions or deleted memories do not leak.
• Degradation Transparency: When operating from cache, tool response text explicitly prefixes [Degraded / Offline Cache: fromCache=true, isFresh=...], and details exposes { fromCache: true, isFresh: boolean }.
• Mutation Invalidation: Successful memory_store, xmemo_memory_update, memory_forget, or xmemo_restart_snapshot_restore operations immediately purge affected local cache entries for the matching bucket, scope, and team, while preserving queued outbox writes.

Ledger & Audit Permission Prerequisites

• xmemo_ledger_summary and xmemo_audit_events require specialized account permissions (e.g. ledger:read, audit:read). Standard memory tokens lacking these scopes return HTTP 401/403 by design.

Migration from another memory provider

Selecting xmemo-memory replaces the active backend. Existing memories in memory-core, memory-lancedb, or another provider remain in their original store but are no longer queried automatically.

Migrate selected content by reading it from the previous provider and writing it to XMemo, or use an XMemo import workflow. Do not delete the old store until the migration has been verified.

Security and privacy

For sensitive environments, place the OpenClaw data directory on an encrypted user profile or encrypted disk, and clear local XMemo state when rotating accounts or retiring a device.

Development

pnpm install --frozen-lockfile
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm pack

Verify the compiled package entry point:

node scripts/verify-plugin.mjs <unpacked-package-directory>

The release workflow tests the minimum supported OpenClaw baseline and a forward-compatibility version before publishing to npm and ClawHub.

Agent-readable metadata

If an OpenClaw-compatible setup agent sees only https://xmemo.dev, it should read the public discovery document and prefer the Skill + native plugin pairing. Other MCP-compatible clients should use hosted MCP unless they have a native XMemo integration.

Links

• XMemo
• XMemo MCP guide
• XMemo OpenClaw plugin on ClawHub
• XMemo Skill on ClawHub
• GitHub Repository
• Issues
• Releases