@xmemo/openclaw-memory 1.0.0

package/README.md

@@ -0,0 +1,212 @@
+# XMemo for OpenClaw
+
+<img src="assets/icon.png" width="128" height="128" alt="XMemo for OpenClaw logo">
+
+[XMemo](https://xmemo.dev) is an identity-aware memory control plane for AI
+agents — a user-owned Memory OS that stores, governs, and audits personal and
+project context across clients, devices, and agent runtimes.
+
+This package is the **native OpenClaw plugin** for XMemo. Once enabled, OpenClaw
+uses XMemo as its active long-term memory backend instead of local file-backed
+or vector-backed stores. It is distributed independently through ClawHub and
+npm as an external plugin and is not bundled in the default OpenClaw release.
+The project does not pursue inclusion through an upstream OpenClaw pull request.
+
+## Features
+
+- Identity-aware memory for OpenClaw via the XMemo REST API
+- Canonical memory tools: `memory_search`, `memory_get`, `memory_store`, `memory_forget`
+- Memory list and update: `xmemo_memory_list`, `xmemo_memory_update`
+- Reminder tools: `xmemo_todo_create`, `xmemo_todo_list`, `xmemo_todo_complete`
+- Timeline event tool: `xmemo_record_event`
+- Restart snapshot tools: `xmemo_restart_snapshot_save`, `xmemo_restart_snapshot_restore`
+- Ledger and audit tools (requires special API key scope): `xmemo_ledger_monthly_summary`, `xmemo_audit_events`, `xmemo_audit_consolidation`
+- Optional automatic capture of high-signal user messages after a successful agent turn
+- No local embedding model or vector store required
+- Works with hosted XMemo (`https://xmemo.dev`) and private/self-hosted instances
+
+## Native plugin vs MCP
+
+This is a native OpenClaw plugin (`kind: "memory"`). It becomes OpenClaw's
+active memory backend when `plugins.slots.memory` is set to `"xmemo-memory"`.
+
+XMemo also provides a hosted MCP server (`https://xmemo.dev/mcp`) for users who
+want tools without occupying the OpenClaw memory slot. The MCP server exposes
+similar read/write memory tools but does **not** replace `active-memory` recall.
+
+## Installation
+
+Install the plugin from ClawHub (recommended):
+
+```bash
+openclaw plugins install clawhub:@xmemo/openclaw-memory
+```
+
+npm is also supported as a secondary distribution channel:
+
+```bash
+openclaw plugins install @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:
+
+```json
+{
+  "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](https://xmemo.dev) → **API Keys** → **Create API key**.
+Copy the one-time secret value, then set it as the `XMEMO_KEY` environment
+variable:
+
+```bash
+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:
+
+1. A literal string.
+2. An env SecretRef object: `{ "source": "env", "provider": "default", "id": "XMEMO_KEY" }`.
+3. 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:
+
+```json
+{
+  "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
+
+```bash
+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`:
+>
+> ```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`:
+
+```json
+{
+  "autoCapture": true,
+  "customTriggers": ["save this", "remember for next time"]
+}
+```
+
+## Smoke test
+
+After installing and configuring the plugin:
+
+```bash
+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`,
+  `xmemo_memory_list`, `xmemo_memory_update`, `xmemo_todo_create`,
+  `xmemo_todo_list`, `xmemo_todo_complete`, `xmemo_record_event`,
+  `xmemo_restart_snapshot_save`, `xmemo_restart_snapshot_restore`,
+  `xmemo_ledger_monthly_summary`, `xmemo_audit_events`,
+  `xmemo_audit_consolidation`, plus the `xmemo` CLI.
+
+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.

package/dist/doctor-contract-api.d.ts

@@ -0,0 +1,13 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+type LegacyConfigRule = {
+    path: string[];
+    message: string;
+};
+export declare const legacyConfigRules: LegacyConfigRule[];
+export declare function normalizeCompatibilityConfig({ cfg }: {
+    cfg: OpenClawConfig;
+}): {
+    config: OpenClawConfig;
+    changes: string[];
+};
+export {};

package/dist/doctor-contract-api.js

@@ -0,0 +1,60 @@
+// XMemo memory plugin doctor contract.
+//
+// Exposes config compatibility fixes for OpenClaw `openclaw doctor --fix`.
+export const legacyConfigRules = [
+    {
+        path: ["plugins", "config", "xmemo-memory"],
+        message: "XMemo memory config moved from plugins.config to plugins.entries['xmemo-memory'].config. Run `openclaw doctor --fix` to migrate.",
+    },
+];
+function asRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+export function normalizeCompatibilityConfig({ cfg }) {
+    const plugins = asRecord(cfg.plugins);
+    const legacyConfig = asRecord(plugins?.config)?.["xmemo-memory"];
+    const entries = asRecord(plugins?.entries);
+    const existingEntry = asRecord(entries?.["xmemo-memory"]);
+    if (!legacyConfig || typeof legacyConfig !== "object" || Array.isArray(legacyConfig)) {
+        return { config: cfg, changes: [] };
+    }
+    const legacy = legacyConfig;
+    const currentConfig = asRecord(existingEntry?.config) ?? {};
+    const migrated = { ...currentConfig };
+    for (const [key, value] of Object.entries(legacy)) {
+        if (migrated[key] === undefined) {
+            migrated[key] = value;
+        }
+    }
+    // Rename deprecated token to apiKey if apiKey is not already set.
+    if (migrated.token !== undefined && migrated.apiKey === undefined) {
+        migrated.apiKey = migrated.token;
+        delete migrated.token;
+    }
+    const nextEntries = { ...entries };
+    nextEntries["xmemo-memory"] = {
+        ...existingEntry,
+        enabled: existingEntry?.enabled ?? true,
+        config: migrated,
+    };
+    const nextPlugins = { ...plugins };
+    const nextLegacyConfig = { ...asRecord(nextPlugins.config) };
+    delete nextLegacyConfig["xmemo-memory"];
+    if (Object.keys(nextLegacyConfig).length === 0) {
+        delete nextPlugins.config;
+    }
+    else {
+        nextPlugins.config = nextLegacyConfig;
+    }
+    nextPlugins.entries = nextEntries;
+    return {
+        config: { ...cfg, plugins: nextPlugins },
+        changes: [
+            "Moved xmemo-memory config from plugins.config to plugins.entries['xmemo-memory'].config.",
+            ...(legacy.token !== undefined ? ["Renamed deprecated token to apiKey."] : []),
+        ],
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
+declare const plugin: OpenClawPluginDefinition;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,32 @@
+// XMemo for OpenClaw plugin entrypoint.
+//
+// This plugin brings XMemo's identity-aware memory control plane into OpenClaw,
+// making XMemo the active long-term memory backend. It implements the OpenClaw
+// `kind: "memory"` slot contract by registering a MemoryPluginCapability with
+// prompt building, flush planning, and a remote MemorySearchManager backed by
+// the XMemo REST API.
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { registerXMemoAutoCapture } from "./src/auto-capture.js";
+import { registerXMemoCli } from "./src/cli.js";
+import { buildXMemoPromptSection } from "./src/prompt-section.js";
+import { createXMemoMemoryRuntime } from "./src/runtime.js";
+import { registerXMemoTools } from "./src/tools.js";
+const plugin = definePluginEntry({
+    id: "xmemo-memory",
+    name: "XMemo for OpenClaw",
+    description: "XMemo identity-aware memory control plane for OpenClaw.",
+    kind: "memory",
+    register(api) {
+        api.registerMemoryCapability({
+            promptBuilder: buildXMemoPromptSection,
+            // XMemo is a remote memory backend; there is no local transcript flush
+            // path. Returning null keeps OpenClaw from writing memory files locally.
+            flushPlanResolver: () => null,
+            runtime: createXMemoMemoryRuntime(api),
+        });
+        registerXMemoTools(api);
+        registerXMemoAutoCapture(api);
+        registerXMemoCli(api);
+    },
+});
+export default plugin;

package/dist/openclaw.plugin.json

@@ -0,0 +1,203 @@
+{
+    "id": "xmemo-memory",
+    "name": "XMemo for OpenClaw",
+    "description": "XMemo identity-aware memory control plane for OpenClaw. Brings user-owned, auditable, cross-agent memory into OpenClaw.",
+    "kind": "memory",
+    "activation": {
+        "onStartup": false,
+        "onCommands": ["memory"]
+    },
+    "contracts": {
+        "tools": [
+            "memory_search",
+            "memory_get",
+            "memory_store",
+            "memory_forget",
+            "xmemo_memory_list",
+            "xmemo_memory_update",
+            "xmemo_todo_create",
+            "xmemo_todo_list",
+            "xmemo_todo_complete",
+            "xmemo_record_event",
+            "xmemo_restart_snapshot_save",
+            "xmemo_restart_snapshot_restore",
+            "xmemo_ledger_monthly_summary",
+            "xmemo_audit_events",
+            "xmemo_audit_consolidation"
+        ]
+    },
+    "uiHints": {
+        "baseUrl": {
+            "label": "XMemo Service URL",
+            "placeholder": "https://xmemo.dev",
+            "help": "Base URL of the XMemo instance. Use a private/self-hosted URL if not using the hosted service.",
+            "advanced": true
+        },
+        "apiKey": {
+            "label": "XMemo API Key",
+            "placeholder": "xmemo_...",
+            "help": "Create a scoped API key in XMemo Memory Console -> API Keys -> Create API key. Prefer setting XMEMO_KEY instead of storing the key here.",
+            "sensitive": true
+        },
+        "token": {
+            "label": "XMemo Token (deprecated)",
+            "placeholder": "xmemo_...",
+            "help": "Deprecated alias for apiKey. Prefer apiKey or the XMEMO_KEY environment variable.",
+            "sensitive": true,
+            "advanced": true
+        },
+        "authMode": {
+            "label": "Auth Mode",
+            "placeholder": "api-key",
+            "help": "How to send the credential: api-key (X-API-Key header), bearer (Authorization: Bearer), or both.",
+            "advanced": true
+        },
+        "bucket": {
+            "label": "Default Bucket",
+            "placeholder": "openclaw",
+            "help": "Default bucket for memories created by OpenClaw."
+        },
+        "scope": {
+            "label": "Default Scope",
+            "placeholder": "openclaw",
+            "help": "Optional scope for isolating this workspace/agent.",
+            "advanced": true
+        },
+        "teamId": {
+            "label": "Team ID",
+            "placeholder": "",
+            "help": "Optional team/organization id for enterprise XMemo deployments.",
+            "advanced": true
+        },
+        "agentId": {
+            "label": "Agent ID",
+            "placeholder": "openclaw",
+            "help": "Non-secret agent identifier sent to XMemo for attribution.",
+            "advanced": true
+        },
+        "autoCapture": {
+            "label": "Auto Capture",
+            "help": "Automatically persist high-signal decisions and fixes to XMemo."
+        },
+        "captureMaxChars": {
+            "label": "Capture Max Chars",
+            "help": "Maximum message length eligible for auto-capture.",
+            "advanced": true,
+            "placeholder": "500"
+        },
+        "customTriggers": {
+            "label": "Custom Auto-Capture Triggers",
+            "help": "Additional words or phrases that trigger auto-capture (case-insensitive).",
+            "advanced": true
+        },
+        "recallMaxChars": {
+            "label": "Recall Query Max Chars",
+            "help": "Maximum prompt/query length sent to XMemo for recall.",
+            "advanced": true,
+            "placeholder": "1000"
+        },
+        "recallMaxItems": {
+            "label": "Recall Max Items",
+            "help": "Maximum number of memories returned by XMemo recall.",
+            "advanced": true,
+            "placeholder": "8"
+        },
+        "recallMaxTokens": {
+            "label": "Recall Max Tokens",
+            "help": "Maximum token budget for the recalled context package.",
+            "advanced": true,
+            "placeholder": "1500"
+        }
+    },
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "baseUrl": {
+                "type": "string",
+                "format": "uri"
+            },
+            "apiKey": {
+                "oneOf": [
+                    { "type": "string" },
+                    {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "source": { "type": "string", "enum": ["env"] },
+                            "provider": { "type": "string" },
+                            "id": { "type": "string" }
+                        },
+                        "required": ["source", "provider", "id"]
+                    }
+                ]
+            },
+            "token": {
+                "oneOf": [
+                    { "type": "string" },
+                    {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "source": { "type": "string", "enum": ["env"] },
+                            "provider": { "type": "string" },
+                            "id": { "type": "string" }
+                        },
+                        "required": ["source", "provider", "id"]
+                    }
+                ]
+            },
+            "authMode": {
+                "type": "string",
+                "enum": ["api-key", "bearer", "both"],
+                "default": "api-key"
+            },
+            "bucket": {
+                "type": "string",
+                "default": "openclaw"
+            },
+            "scope": {
+                "type": ["string", "null"]
+            },
+            "teamId": {
+                "type": ["string", "null"]
+            },
+            "agentId": {
+                "type": "string",
+                "default": "openclaw"
+            },
+            "autoCapture": {
+                "type": "boolean",
+                "default": false
+            },
+            "captureMaxChars": {
+                "type": "number",
+                "minimum": 100,
+                "maximum": 10000,
+                "default": 500
+            },
+            "customTriggers": {
+                "type": "array",
+                "items": { "type": "string" }
+            },
+            "recallMaxChars": {
+                "type": "number",
+                "minimum": 100,
+                "maximum": 10000,
+                "default": 1000
+            },
+            "recallMaxItems": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 50,
+                "default": 8
+            },
+            "recallMaxTokens": {
+                "type": "integer",
+                "minimum": 100,
+                "maximum": 8000,
+                "default": 1500
+            }
+        }
+    }
+}

package/dist/src/auto-capture.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/memory-core-host-runtime-core";
+export declare function registerXMemoAutoCapture(api: OpenClawPluginApi): void;