@xmemo/client 0.4.169 → 0.4.171

package/README.md

@@ -12,6 +12,33 @@ setup helper code needed on a user's machine.
 The XMemo server, database, token registry, deployment files, logs, and
 internal scripts are not part of this npm package.
 
+> 🧠 **XMemo is also an MCP Server** — give your AI agents persistent memory across sessions. See [MCP Setup](#mcp-setup) below.
+
+## MCP Server Overview
+
+**XMemo** is a user-owned, hosted MCP memory service that lets AI agents persistently store, search, recall, update, and manage notes and memory fragments across sessions, projects, and tools.
+
+- **MCP Endpoint**: `https://xmemo.dev/mcp` (Streamable HTTP)
+- **Auth**: Bearer Token (`XMEMO_KEY`) or MCP OAuth
+- **Tools**: `remember`, `recall`, `search_memory`, `update_memory`, `forget`, `redact_memory`, `explain_memory`, `create_memory_todo`, `list_memory_todos`, `complete_memory_todo`, `record_event`, `get_timeline`, `add_expense`
+- **Clients**: Kimi, Claude, Cursor, Copilot, Gemini, Grok, Windsurf, Cline, Trae, Zed, Qwen, and more
+
+```json
+{
+  "mcpServers": {
+    "XMemo": {
+      "type": "streamable-http",
+      "url": "https://xmemo.dev/mcp",
+      "headers": {
+        "Authorization": "Bearer ${XMEMO_KEY}"
+      }
+    }
+  }
+}
+```
+
+See [MCP Setup](#mcp-setup) for detailed client configuration.
+
 ## Install
 
 ```bash
@@ -37,6 +64,13 @@ xmemo setup cursor
 xmemo setup cursor --dry-run
 xmemo setup copilot
 xmemo setup copilot --dry-run
+xmemo setup openclaw
+xmemo setup openclaw --dry-run
+xmemo setup openclaw --with-mcp
+xmemo setup openclaw --mcp-only
+xmemo setup hermes
+xmemo setup hermes --with-mcp
+xmemo setup hermes --mcp-only
 xmemo setup gemini
 xmemo setup gemini --dry-run
 xmemo setup antigravity
@@ -167,6 +201,8 @@ xmemo setup codex
 xmemo setup codex --url "https://your-private-service.example"
 xmemo setup cursor
 xmemo setup copilot
+xmemo setup openclaw
+xmemo setup hermes
 xmemo setup gemini
 xmemo setup antigravity
 ```
@@ -175,10 +211,12 @@ xmemo setup antigravity
 clients, it applies the user-scoped config directly; use `--dry-run` to preview
 without writing. Codex/Cursor configs reference `XMEMO_KEY`; OAuth-native
 clients such as Gemini CLI and Antigravity use the client's MCP OAuth flow
-instead. No generated config embeds a token value. Write-capable client configs
-also include stable non-secret agent identity headers where the client format
-supports them. `--yes` remains accepted for Codex and Cursor as a compatibility
-no-op.
+instead. `xmemo setup openclaw` is a custom OpenClaw installer: it installs or
+updates the native `@xmemo/openclaw-memory` plugin and the XMemo Skill, and does
+not add the hosted MCP server unless `--with-mcp` is passed. No generated config
+embeds a token value. Write-capable client configs also include stable
+non-secret agent identity headers where the client format supports them.
+`--yes` remains accepted for Codex and Cursor as a compatibility no-op.
 
 After writing MCP config, `xmemo setup <client>` prompts:
 
@@ -269,12 +307,100 @@ template and apply it manually after review:
 xmemo mcp config --client generic --base-url "https://your-private-service.example" --json
 ```
 
-Codex, Cursor, Copilot CLI, Gemini CLI, Antigravity, and Kiro have write-capable setup
-helpers. Antigravity 2.0 is write-capable through `xmemo mcp add antigravity2
---write`.
+Codex, Cursor, Copilot CLI, Gemini CLI, Antigravity, OpenClaw, Hermes, and Kiro
+have write-capable setup helpers. Antigravity 2.0 is write-capable through
+`xmemo mcp add antigravity2 --write`.
 Other client writes should only be added after their official user-scoped config
 format is verified.
 
+OpenClaw and Hermes use the same setup modes:
+
+| Command | Result |
+|---------|--------|
+| `xmemo setup <openclaw|hermes>` | Install/update the native integration and sync credentials. MCP is not installed. |
+| `xmemo setup <openclaw|hermes> --with-mcp` | Install/update the native integration, sync credentials, and add hosted MCP fallback. |
+| `xmemo setup <openclaw|hermes> --mcp-only` | Add hosted MCP fallback only. Native plugin/Skill install and native credential sync are skipped. |
+
+### OpenClaw
+
+Recommended OpenClaw setup:
+
+```bash
+xmemo login
+xmemo setup openclaw
+openclaw xmemo status
+```
+
+`xmemo setup openclaw` installs or updates OpenClaw's native XMemo memory plugin
+from `@xmemo/openclaw-memory`, installs the XMemo Skill with `openclaw skills
+install xmemo --force`, and then runs `openclaw xmemo status --json` so the user
+can see whether credentials are available. The native plugin reads the same
+user-scoped XMemo credential used by `xmemo login` and `xmemo token add
+--from-stdin`, so normal users do not need to separately configure an OpenClaw
+API key.
+
+Hosted MCP is not installed by default because it creates a second XMemo tool
+surface beside the native memory plugin. If you intentionally want that fallback
+too, run:
+
+```bash
+xmemo setup openclaw --with-mcp
+```
+
+The fallback MCP entry references `Authorization: Bearer ${XMEMO_KEY}` and does
+not embed the token value. To install only the hosted MCP fallback without the
+native plugin or Skill, run:
+
+```bash
+xmemo setup openclaw --mcp-only
+```
+
+Use `--no-skill` only when the XMemo Skill is managed by another deployment
+path. Use `--openclaw-bin <path>` for custom OpenClaw binary locations.
+
+### Hermes
+
+Recommended Hermes setup:
+
+```bash
+xmemo login
+xmemo setup hermes
+```
+
+`xmemo setup hermes` is Hermes-aware rather than a raw MCP writer. It installs
+or updates the native `hermes-xmemo` package with `python -m pip install -U
+hermes-xmemo`, runs `hermes-xmemo install`, then resolves the XMemo token from,
+in order, process environment (`XMEMO_KEY`, `MEMORY_OS_API_KEY`, or
+`MEMORY_OS_MCP_TOKEN`), the shared `@xmemo/client` credential written by
+`xmemo login` / `xmemo token add --from-stdin`, and an existing
+`$HERMES_HOME/.env`. It syncs the token to Hermes' `$HERMES_HOME/.env` as
+`XMEMO_KEY`, which keeps the native `hermes-xmemo` plugin and any optional
+Hermes MCP fallback on the same credential.
+
+Hosted MCP is not installed by default because it creates a second XMemo tool
+surface beside the native memory provider. If you intentionally want that
+fallback too, run:
+
+```bash
+xmemo setup hermes --with-mcp
+```
+
+The fallback MCP entry references `Authorization:Bearer ${XMEMO_KEY}` and does
+not embed the token value. To install only the hosted MCP fallback without the
+native plugin or native credential sync, run:
+
+```bash
+xmemo setup hermes --mcp-only
+```
+
+If an older Hermes plugin setup already created `$HERMES_HOME/.env`,
+`xmemo setup hermes` can backfill the same token into the shared `@xmemo/client`
+credential file so future XMemo CLI and MCP flows reuse it. Use `--no-plugin`
+only when the native Hermes plugin is managed by another deployment path. Use
+`--hermes-home <path>` for non-default Hermes homes. The legacy
+`hermes memory setup xmemo` flow remains supported by the plugin and can reuse
+the shared credential when present.
+
 ### Copilot CLI
 
 Copilot CLI has `/mcp` management and reads user MCP configuration from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmemo/client",
-  "version": "0.4.169",
+  "version": "0.4.171",
   "description": "Privacy-first CLI and MCP setup helper for XMemo.",
   "mcpName": "io.github.yonro/xmemo",
   "type": "module",

package/src/commands/hermes.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { hasFlag, optionValue } from '../core/args.js';
+import { TOKEN_ENV_VAR, LEGACY_TOKEN_ENV_VAR } from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import {
+  bestEffortChmod,
+  readTextIfExists,
+  runProcess
+} from '../core/runtime.js';
+import {
+  readStoredCredential,
+  resolveCredentialToken,
+  storeTokenValue
+} from '../network/auth.js';
+
+const HERMES_MCP_NAME = 'XMemo';
+const HERMES_PLUGIN_PACKAGE = 'hermes-xmemo';
+const DEFAULT_PYTHON_BIN = process.platform === 'win32' ? 'python' : 'python3';
+
+export function defaultHermesHome(env) {
+  if (env.HERMES_HOME) {
+    return env.HERMES_HOME;
+  }
+  const home = env.USERPROFILE || env.HOME;
+  if (!home) {
+    throw new UsageError('Cannot determine Hermes home. Set HERMES_HOME or HOME.');
+  }
+  return path.join(home, '.hermes');
+}
+
+function parseEnvContent(content) {
+  const values = new Map();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) {
+      continue;
+    }
+    const [rawKey, ...rest] = trimmed.split('=');
+    const key = rawKey.trim();
+    let value = rest.join('=').trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values.set(key, value);
+  }
+  return values;
+}
+
+async function readHermesEnvToken(envPath) {
+  const content = await readTextIfExists(envPath);
+  if (!content.trim()) {
+    return null;
+  }
+  const values = parseEnvContent(content);
+  return values.get(TOKEN_ENV_VAR) || values.get('MEMORY_OS_API_KEY') || values.get(LEGACY_TOKEN_ENV_VAR) || null;
+}
+
+async function writeHermesEnvToken(envPath, token) {
+  const existing = await readTextIfExists(envPath);
+  const lines = existing ? existing.split(/\r?\n/) : [];
+  const output = [];
+  let wrote = false;
+
+  for (const line of lines) {
+    const key = line.includes('=') ? line.split('=', 1)[0].trim() : '';
+    if (key === TOKEN_ENV_VAR) {
+      output.push(`${TOKEN_ENV_VAR}=${token}`);
+      wrote = true;
+    } else {
+      output.push(line);
+    }
+  }
+
+  if (!wrote) {
+    output.push(`${TOKEN_ENV_VAR}=${token}`);
+  }
+
+  const text = `${output.join('\n').replace(/\n*$/, '')}\n`;
+  await fs.mkdir(path.dirname(envPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(envPath, text, { mode: 0o600 });
+  await bestEffortChmod(path.dirname(envPath), 0o700);
+  await bestEffortChmod(envPath, 0o600);
+}
+
+async function resolveHermesCredential(io, hermesEnvPath) {
+  const envToken = io.env[TOKEN_ENV_VAR] || io.env.MEMORY_OS_API_KEY || io.env[LEGACY_TOKEN_ENV_VAR];
+  if (envToken) {
+    return { token: envToken, source: 'process-env' };
+  }
+
+  const sharedToken = await resolveCredentialToken(io.env);
+  if (sharedToken) {
+    return { token: sharedToken, source: 'shared-credential' };
+  }
+
+  const hermesToken = await readHermesEnvToken(hermesEnvPath);
+  if (hermesToken) {
+    return { token: hermesToken, source: 'hermes-env' };
+  }
+
+  return { token: null, source: 'missing' };
+}
+
+function commandText(command, args) {
+  return [command, ...args].join(' ');
+}
+
+async function runHermesCommand(command, args, io) {
+  const result = await runProcess(command, args, io, { stream: false });
+  if (result.code !== 0) {
+    throw new UsageError(
+      `Hermes setup command failed (${result.code}): ${commandText(command, args)}\n${result.stderr || result.stdout}`,
+    );
+  }
+  return result;
+}
+
+export async function hermesSetupPlan({ setupPlan, optionArgs, io, dryRun, identity, client, force }) {
+  const hermesHome = optionValue(optionArgs, '--hermes-home') ?? defaultHermesHome(io.env);
+  const hermesEnvPath = path.join(hermesHome, '.env');
+  const configPath = optionValue(optionArgs, '--config') ?? path.join(hermesHome, 'config.yaml');
+  const mcpOnly = hasFlag(optionArgs, '--mcp-only');
+  const withMcp = mcpOnly || hasFlag(optionArgs, '--with-mcp');
+  const noPlugin = hasFlag(optionArgs, '--no-plugin');
+  const noEnvSync = hasFlag(optionArgs, '--no-env-sync');
+  const pythonBin = optionValue(optionArgs, '--python') ?? DEFAULT_PYTHON_BIN;
+  const hermesXmemoBin = optionValue(optionArgs, '--hermes-xmemo-bin') ?? 'hermes-xmemo';
+
+  const credential = await resolveHermesCredential(io, hermesEnvPath);
+  const storedCredential = await readStoredCredential(io.env);
+  const shouldBackfillSharedCredential = credential.token
+    && credential.source === 'hermes-env'
+    && !storedCredential.token;
+  const shouldWriteHermesEnv = Boolean(credential.token) && !noEnvSync;
+
+  const selectedClient = {
+    id: 'hermes',
+    label: 'Hermes',
+    configKind: 'hermes-native-and-mcp',
+    setupMode: mcpOnly ? 'mcp-only' : withMcp ? 'native-with-mcp' : 'native',
+    configPath,
+    hermesHome,
+    hermesEnvPath,
+    written: false,
+    writesTokenValue: shouldWriteHermesEnv,
+    tokenValueEmbeddedInMcpConfig: false,
+    credential: {
+      ready: Boolean(credential.token),
+      source: credential.source,
+      sharedCredentialBackfilled: false,
+      hermesEnvSynced: false,
+    },
+    nativePlugin: {
+      package: HERMES_PLUGIN_PACKAGE,
+      installCommand: commandText(pythonBin, ['-m', 'pip', 'install', '-U', HERMES_PLUGIN_PACKAGE]),
+      activateCommand: commandText(hermesXmemoBin, ['install', '--hermes-home', hermesHome]),
+      installed: false,
+      skipped: noPlugin || mcpOnly,
+      note: noPlugin || mcpOnly
+        ? mcpOnly
+          ? 'Native Hermes plugin install skipped by --mcp-only.'
+          : 'Native Hermes plugin install skipped by --no-plugin.'
+        : 'Installs/updates the native Hermes XMemo plugin before syncing credentials.',
+    },
+    mcp: {
+      enabled: withMcp,
+      serverName: HERMES_MCP_NAME,
+      mcpUrl: setupPlan.mcpUrl,
+      written: false,
+      only: mcpOnly,
+      note: withMcp
+        ? mcpOnly
+          ? `Hosted MCP references ${TOKEN_ENV_VAR}; native Hermes plugin install and credential sync are skipped by --mcp-only.`
+          : `Hosted MCP references ${TOKEN_ENV_VAR} from Hermes .env/process env; token value is not embedded in config.yaml.`
+        : 'Hosted MCP is not installed by default; use --with-mcp for an explicit fallback.',
+    },
+    dryRun,
+  };
+
+  if (dryRun) {
+    return selectedClient;
+  }
+
+  if (!noPlugin && !mcpOnly) {
+    await runHermesCommand(pythonBin, ['-m', 'pip', 'install', '-U', HERMES_PLUGIN_PACKAGE], io);
+    await runHermesCommand(hermesXmemoBin, ['install', '--hermes-home', hermesHome], io);
+    selectedClient.nativePlugin.installed = true;
+  }
+
+  if (shouldBackfillSharedCredential && !mcpOnly) {
+    await storeTokenValue(credential.token, { source: 'hermes-env-sync' }, io.env);
+    selectedClient.credential.sharedCredentialBackfilled = true;
+  }
+
+  if (shouldWriteHermesEnv && !mcpOnly) {
+    await writeHermesEnvToken(hermesEnvPath, credential.token);
+    selectedClient.credential.hermesEnvSynced = true;
+  }
+
+  if (withMcp) {
+    await client.writeConfig(configPath, setupPlan.mcpUrl, identity, { force });
+    selectedClient.mcp.written = true;
+  }
+
+  selectedClient.written = selectedClient.nativePlugin.installed
+    || selectedClient.credential.hermesEnvSynced
+    || selectedClient.mcp.written;
+  return selectedClient;
+}

package/src/commands/openclaw.js

@@ -0,0 +1,153 @@
+import { hasFlag, optionValue } from '../core/args.js';
+import { TOKEN_ENV_VAR } from '../core/constants.js';
+import { UsageError } from '../core/errors.js';
+import { runProcess } from '../core/runtime.js';
+import { resolveCredentialToken } from '../network/auth.js';
+
+const DEFAULT_OPENCLAW_BIN = 'openclaw';
+const OPENCLAW_PLUGIN_SPEC = '@xmemo/openclaw-memory';
+const OPENCLAW_SKILL_REF = 'xmemo';
+const OPENCLAW_MCP_NAME = 'xmemo';
+
+function commandText(command, args) {
+  return [command, ...args].join(' ');
+}
+
+function extractLastJsonObject(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return null;
+  }
+  for (let index = trimmed.lastIndexOf('{'); index >= 0; index = trimmed.lastIndexOf('{', index - 1)) {
+    const candidate = trimmed.slice(index);
+    try {
+      return JSON.parse(candidate);
+    } catch {
+      // Keep scanning; OpenClaw may print warnings before the final JSON object.
+    }
+  }
+  return null;
+}
+
+async function runOpenClaw(openclawBin, args, io) {
+  const result = await runProcess(openclawBin, args, io, { stream: false });
+  if (result.code !== 0) {
+    throw new UsageError(
+      `OpenClaw command failed (${result.code}): ${commandText(openclawBin, args)}\n${result.stderr || result.stdout}`,
+    );
+  }
+  return result;
+}
+
+function credentialPlan(env) {
+  if (env[TOKEN_ENV_VAR]) {
+    return { ready: true, source: 'env', variable: TOKEN_ENV_VAR };
+  }
+  if (env.MEMORY_OS_MCP_TOKEN) {
+    return { ready: true, source: 'env', variable: 'MEMORY_OS_MCP_TOKEN' };
+  }
+  return { ready: false, source: 'shared-credential-or-missing', variable: null };
+}
+
+export async function openclawSetupPlan({ setupPlan, optionArgs, io, dryRun }) {
+  const openclawBin = optionValue(optionArgs, '--openclaw-bin') ?? DEFAULT_OPENCLAW_BIN;
+  const mcpOnly = hasFlag(optionArgs, '--mcp-only');
+  const withMcp = mcpOnly || hasFlag(optionArgs, '--with-mcp');
+  const noSkill = hasFlag(optionArgs, '--no-skill');
+  const credential = credentialPlan(io.env);
+  const sharedToken = await resolveCredentialToken(io.env);
+  if (sharedToken && !credential.ready) {
+    credential.ready = true;
+    credential.source = 'shared-credential';
+  }
+
+  const selectedClient = {
+    id: 'openclaw',
+    label: 'OpenClaw',
+    configKind: 'native-plugin',
+    setupMode: mcpOnly ? 'mcp-only' : withMcp ? 'native-with-mcp' : 'native',
+    written: false,
+    writesTokenValue: false,
+    openclawBin,
+    credential,
+    nativePlugin: {
+      package: OPENCLAW_PLUGIN_SPEC,
+      command: commandText(openclawBin, ['plugins', 'install', OPENCLAW_PLUGIN_SPEC, '--force']),
+      installed: false,
+      skipped: mcpOnly,
+    },
+    skill: {
+      ref: OPENCLAW_SKILL_REF,
+      command: commandText(openclawBin, ['skills', 'install', OPENCLAW_SKILL_REF, '--force']),
+      installed: false,
+      skipped: noSkill || mcpOnly,
+    },
+    mcp: {
+      enabled: withMcp,
+      serverName: OPENCLAW_MCP_NAME,
+      mcpUrl: setupPlan.mcpUrl,
+      command: commandText(openclawBin, [
+        'mcp',
+        'add',
+        OPENCLAW_MCP_NAME,
+        '--url',
+        setupPlan.mcpUrl,
+        '--transport',
+        'streamable-http',
+        '--header',
+        `Authorization=Bearer \${${TOKEN_ENV_VAR}}`,
+        '--no-probe',
+      ]),
+      written: false,
+      only: mcpOnly,
+      note: withMcp
+        ? mcpOnly
+          ? `Hosted MCP references ${TOKEN_ENV_VAR}; native plugin and Skill are skipped by --mcp-only.`
+          : `Hosted MCP fallback references ${TOKEN_ENV_VAR}; native plugin remains primary.`
+        : 'Hosted MCP is not installed by default; use --with-mcp for an explicit fallback.',
+    },
+    status: null,
+    dryRun,
+  };
+
+  if (dryRun) {
+    return selectedClient;
+  }
+
+  if (!mcpOnly) {
+    await runOpenClaw(openclawBin, ['plugins', 'install', OPENCLAW_PLUGIN_SPEC, '--force'], io);
+    selectedClient.nativePlugin.installed = true;
+
+    if (!noSkill) {
+      await runOpenClaw(openclawBin, ['skills', 'install', OPENCLAW_SKILL_REF, '--force'], io);
+      selectedClient.skill.installed = true;
+    }
+  }
+
+  if (withMcp) {
+    await runOpenClaw(
+      openclawBin,
+      [
+        'mcp',
+        'add',
+        OPENCLAW_MCP_NAME,
+        '--url',
+        setupPlan.mcpUrl,
+        '--transport',
+        'streamable-http',
+        '--header',
+        `Authorization=Bearer \${${TOKEN_ENV_VAR}}`,
+        '--no-probe',
+      ],
+      io,
+    );
+    selectedClient.mcp.written = true;
+  }
+
+  if (!mcpOnly) {
+    const statusResult = await runOpenClaw(openclawBin, ['xmemo', 'status', '--json'], io);
+    selectedClient.status = extractLastJsonObject(statusResult.stdout);
+  }
+  selectedClient.written = true;
+  return selectedClient;
+}

package/src/commands/setup.js

@@ -28,6 +28,8 @@ import {
   supportedMcpClients
 } from '../mcp/clients.js';
 import { mergeCopilotMcpConfig } from '../mcp/proxy/copilot.js';
+import { hermesSetupPlan } from './hermes.js';
+import { openclawSetupPlan } from './openclaw.js';
 
 import {
   agentIdentity,
@@ -134,7 +136,26 @@ export async function setupCommand(args, io) {
       setupPlan.detectedClients.push(clientPlan);
     }
   } else if (clientId) {
-    if (clientId === 'copilot-cli') {
+    if (clientId === 'hermes') {
+      const client = MCP_CLIENTS.get(clientId);
+      const identity = writeConfig ? await agentIdentity(clientId, io.env) : envReferenceIdentity(clientId);
+      setupPlan.selectedClient = await hermesSetupPlan({
+        setupPlan,
+        optionArgs,
+        io,
+        dryRun,
+        identity,
+        client,
+        force
+      });
+    } else if (clientId === 'openclaw') {
+      setupPlan.selectedClient = await openclawSetupPlan({
+        setupPlan,
+        optionArgs,
+        io,
+        dryRun
+      });
+    } else if (clientId === 'copilot-cli') {
       const proxyPort = parsePositiveInteger(optionValue(optionArgs, '--port') ?? String(DEFAULT_PROXY_PORT), '--port');
       setupPlan.selectedClient = copilotSetupPlan(setupPlan.mcpUrl, proxyPort, io.env);
       if (writeConfig) {

package/src/mcp/core/templates.js

@@ -35,9 +35,10 @@ export function mcpConfigTemplate(clientId, mcpUrl, options = {}) {
 
   const jsonDefinition = jsonMcpClientDefinition(clientId);
   if (jsonDefinition) {
+    const identityClientId = jsonDefinition.defaultIdentityId ?? clientId;
     return jsonDefinition.authentication === 'oauth'
-      ? oauthJsonMcpTemplate(clientId, mcpUrl, jsonClientConfig(clientId, mcpUrl), options)
-      : bearerJsonMcpTemplate(clientId, mcpUrl, jsonClientConfig(clientId, mcpUrl), options);
+      ? oauthJsonMcpTemplate(clientId, identityClientId, mcpUrl, jsonClientConfig(clientId, mcpUrl), options)
+      : bearerJsonMcpTemplate(clientId, identityClientId, mcpUrl, jsonClientConfig(clientId, mcpUrl), options);
   }
 
   return {
@@ -112,7 +113,7 @@ export function agentInstanceGenerationPolicy(clientId, options = {}) {
   };
 }
 
-function bearerJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
+function bearerJsonMcpTemplate(clientId, identityClientId, mcpUrl, snippet, options) {
   return {
     client: clientId,
     serverName: MCP_SERVER_NAME,
@@ -122,7 +123,7 @@ function bearerJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
     optionalEnv: [AGENT_INSTANCE_ENV_VAR],
     authentication: 'env-bearer',
     agentIdentity: {
-      agentId: clientId,
+      agentId: identityClientId,
       agentIdHeader: AGENT_ID_HEADER,
       agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
       agentInstanceHeader: AGENT_INSTANCE_HEADER
@@ -133,7 +134,7 @@ function bearerJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
   };
 }
 
-function oauthJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
+function oauthJsonMcpTemplate(clientId, identityClientId, mcpUrl, snippet, options) {
   return {
     client: clientId,
     serverName: MCP_SERVER_NAME,
@@ -143,7 +144,7 @@ function oauthJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
     optionalEnv: [AGENT_INSTANCE_ENV_VAR],
     authentication: 'oauth',
     agentIdentity: {
-      agentId: clientId,
+      agentId: identityClientId,
       agentIdHeader: AGENT_ID_HEADER,
       agentInstanceEnvVar: AGENT_INSTANCE_ENV_VAR,
       agentInstanceHeader: AGENT_INSTANCE_HEADER
@@ -153,4 +154,3 @@ function oauthJsonMcpTemplate(clientId, mcpUrl, snippet, options) {
     writesTokenValue: false
   };
 }
-

package/src/mcp/formats/json.js

@@ -22,9 +22,9 @@ export const JSON_MCP_CLIENT_DEFINITIONS = Object.freeze([
   httpClientDefinition('cursor', 'Cursor', 'defaultCursorConfigPath', { urlKey: 'url', authentication: 'env-bearer' }),
   httpClientDefinition('gemini-cli', 'Gemini CLI', 'defaultGeminiConfigPath', { urlKey: 'httpUrl', authentication: 'oauth' }),
   httpClientDefinition('antigravity', 'Antigravity', 'defaultAntigravityConfigPath', { urlKey: 'serverUrl', authentication: 'oauth' }),
-  httpClientDefinition('antigravity-ide', 'Antigravity IDE', 'defaultAntigravityIdeConfigPath', { urlKey: 'url', authentication: 'oauth', defaultIdentityId: 'antigravity', extra: { type: 'http' } }),
-  httpClientDefinition('antigravity2', 'Antigravity 2.0', 'defaultAntigravity2ConfigPath', { urlKey: 'url', authentication: 'oauth', defaultIdentityId: 'antigravity', extra: { type: 'http' } }),
-  httpClientDefinition('antigravity-cli', 'Antigravity CLI', 'defaultAntigravityCliConfigPath', { urlKey: 'httpUrl', authentication: 'oauth', defaultIdentityId: 'antigravity' }),
+  httpClientDefinition('antigravity-ide', 'Antigravity IDE', 'defaultAntigravityIdeConfigPath', { urlKey: 'serverUrl', authentication: 'oauth', defaultIdentityId: 'antigravity' }),
+  httpClientDefinition('antigravity2', 'Antigravity 2.0', 'defaultAntigravity2ConfigPath', { urlKey: 'serverUrl', authentication: 'oauth', defaultIdentityId: 'antigravity' }),
+  httpClientDefinition('antigravity-cli', 'Antigravity CLI', 'defaultAntigravityCliConfigPath', { urlKey: 'serverUrl', authentication: 'oauth', defaultIdentityId: 'antigravity' }),
   httpClientDefinition('windsurf', 'Windsurf', 'defaultWindsurfConfigPath', { urlKey: 'serverUrl', authentication: 'env-bearer' }),
   httpClientDefinition('cline', 'Cline', 'defaultClineConfigPath', { urlKey: 'httpUrl', authentication: 'env-bearer' }),
   nestedTransportClientDefinition('continue', 'Continue', 'defaultContinueConfigPath'),

package/src/ui/help.js

@@ -25,6 +25,15 @@ export function writeHelp(io) {
   writeLine(io.stdout, `      Detects active workspace to auto-inject project-scoped instruction rules.`);
   writeLine(io.stdout, `      Pass --force to overwrite an existing mcpServers.XMemo entry.`);
   writeLine(io.stdout, '');
+  writeLine(io.stdout, `  ${COMMAND_NAME} setup openclaw [--with-mcp|--mcp-only] [--no-skill] [--dry-run] [--json]`);
+  writeLine(io.stdout, `      Installs/updates the native OpenClaw memory plugin and XMemo Skill.`);
+  writeLine(io.stdout, `      Use --with-mcp for native+MCP, or --mcp-only for MCP without native plugin/Skill.`);
+  writeLine(io.stdout, '');
+  writeLine(io.stdout, `  ${COMMAND_NAME} setup hermes [--with-mcp|--mcp-only] [--no-plugin] [--hermes-home <path>] [--dry-run] [--json]`);
+  writeLine(io.stdout, `      Installs/updates the native Hermes plugin and syncs the shared XMemo credential.`);
+  writeLine(io.stdout, `      Use --with-mcp for native+MCP, or --mcp-only for MCP without native plugin.`);
+  writeLine(io.stdout, `      Compatible with existing hermes-xmemo plugin .env setup.`);
+  writeLine(io.stdout, '');
   writeLine(io.stdout, `  ${COMMAND_NAME} uninstall --all [--yes] [--profiles] [--dry-run]`);
   writeLine(io.stdout, `      Removes the XMemo MCP server entry from every detected client config.`);
   writeLine(io.stdout, `      Use --profiles to also remove installed behavior profiles.`);

package/src/ui/setup.js

@@ -54,7 +54,7 @@ const SETUP_CLIENT_ALIASES = new Map([
 ]);
 
 export function supportedSetupClientIds(mcpClients) {
-  return [...supportedMcpClientIds(mcpClients), 'copilot-cli'];
+  return [...supportedMcpClientIds(mcpClients), 'copilot-cli', 'openclaw'];
 }
 
 export function requiredOption(args, name) {
@@ -172,6 +172,70 @@ export function writeSetupSummary(plan, io) {
   if (plan.selectedClient) {
     writeLine(io.stdout, '');
     writeLine(io.stdout, `Selected client: ${plan.selectedClient.label}`);
+    if (plan.selectedClient.id === 'openclaw') {
+      writeLine(io.stdout, `  Setup kind: ${plan.selectedClient.configKind}`);
+      writeLine(io.stdout, `  Setup mode: ${plan.selectedClient.setupMode}`);
+      writeLine(io.stdout, `  Plugin: ${plan.selectedClient.nativePlugin.package}`);
+      writeLine(io.stdout, `  Plugin installed: ${plan.selectedClient.nativePlugin.installed}`);
+      writeLine(io.stdout, `  Skill: ${plan.selectedClient.skill.ref}`);
+      writeLine(io.stdout, `  Skill installed: ${plan.selectedClient.skill.installed}`);
+      writeLine(io.stdout, `  Skill skipped: ${plan.selectedClient.skill.skipped}`);
+      writeLine(io.stdout, `  Credential source: ${plan.selectedClient.status?.credentialSource ?? plan.selectedClient.credential.source}`);
+      writeLine(io.stdout, `  Connected: ${plan.selectedClient.status?.connected ?? 'unknown'}`);
+      writeLine(io.stdout, `  Hosted MCP fallback: ${plan.selectedClient.mcp.enabled ? 'enabled' : 'not installed'}`);
+      if (plan.selectedClient.mcp.enabled) {
+        writeLine(io.stdout, `  MCP written: ${plan.selectedClient.mcp.written}`);
+        writeLine(io.stdout, `  MCP note: ${plan.selectedClient.mcp.note}`);
+      }
+      if (!plan.selectedClient.credential.ready) {
+        writeLine(io.stdout, `  Next credential step: ${COMMAND_NAME} login`);
+      }
+      if (plan.selectedClient.dryRun) {
+        writeLine(io.stdout, '  Dry run commands:');
+        writeLine(io.stdout, `    ${plan.selectedClient.nativePlugin.command}`);
+        if (!plan.selectedClient.skill.skipped) {
+          writeLine(io.stdout, `    ${plan.selectedClient.skill.command}`);
+        }
+        if (plan.selectedClient.mcp.enabled) {
+          writeLine(io.stdout, `    ${plan.selectedClient.mcp.command}`);
+        }
+      }
+      return;
+    }
+    if (plan.selectedClient.id === 'hermes') {
+      writeLine(io.stdout, `  Setup kind: ${plan.selectedClient.configKind}`);
+      writeLine(io.stdout, `  Setup mode: ${plan.selectedClient.setupMode}`);
+      writeLine(io.stdout, `  Config path: ${plan.selectedClient.configPath}`);
+      writeLine(io.stdout, `  Hermes home: ${plan.selectedClient.hermesHome}`);
+      writeLine(io.stdout, `  Hermes env: ${plan.selectedClient.hermesEnvPath}`);
+      writeLine(io.stdout, `  Credential ready: ${plan.selectedClient.credential.ready}`);
+      writeLine(io.stdout, `  Credential source: ${plan.selectedClient.credential.source}`);
+      writeLine(io.stdout, `  Hermes env synced: ${plan.selectedClient.credential.hermesEnvSynced}`);
+      writeLine(io.stdout, `  Shared credential backfilled: ${plan.selectedClient.credential.sharedCredentialBackfilled}`);
+      writeLine(io.stdout, `  Native plugin package: ${plan.selectedClient.nativePlugin.package}`);
+      writeLine(io.stdout, `  Native plugin installed: ${plan.selectedClient.nativePlugin.installed}`);
+      writeLine(io.stdout, `  Native plugin skipped: ${plan.selectedClient.nativePlugin.skipped}`);
+      writeLine(io.stdout, `  Native plugin note: ${plan.selectedClient.nativePlugin.note}`);
+      writeLine(io.stdout, `  Hosted MCP fallback: ${plan.selectedClient.mcp.enabled ? 'enabled' : 'not installed'}`);
+      writeLine(io.stdout, `  MCP written: ${plan.selectedClient.mcp.written}`);
+      writeLine(io.stdout, `  MCP note: ${plan.selectedClient.mcp.note}`);
+      writeLine(io.stdout, `  Token value embedded in MCP config: ${plan.selectedClient.tokenValueEmbeddedInMcpConfig}`);
+      if (!plan.selectedClient.credential.ready) {
+        writeLine(io.stdout, `  Next credential step: ${COMMAND_NAME} login`);
+      }
+      if (plan.selectedClient.dryRun) {
+        writeLine(io.stdout, '  Dry run actions:');
+        if (!plan.selectedClient.nativePlugin.skipped) {
+          writeLine(io.stdout, `    ${plan.selectedClient.nativePlugin.installCommand}`);
+          writeLine(io.stdout, `    ${plan.selectedClient.nativePlugin.activateCommand}`);
+        }
+        writeLine(io.stdout, `    sync XMemo credential to ${plan.selectedClient.hermesEnvPath}`);
+        if (plan.selectedClient.mcp.enabled) {
+          writeLine(io.stdout, `    write Hermes MCP config to ${plan.selectedClient.configPath}`);
+        }
+      }
+      return;
+    }
     writeLine(io.stdout, `  Config path: ${plan.selectedClient.configPath}`);
     writeLine(io.stdout, `  Written: ${plan.selectedClient.written}`);
     writeLine(io.stdout, `  Token value embedded: ${plan.selectedClient.writesTokenValue}`);