XMemo

XMemo：面向 AI Agent 的 Memory OS

XMemo 是一款由用户掌控、面向 AI Agent 的 Memory OS：提供持久化记忆、项目上下文和会话连续性，并具备 Agent 身份、来源追溯和受管控的访问能力，可通过 MCP、命令行和公共 REST API 接口在多个 AI 客户端之间共享。

English · 简体中文 | 文档 · 托管式 MCP

快速开始 · 本仓库包含的内容 · MCP 之外 · 集成 · 连接模式 · 插件 · 命令 · 版本管理 · 默认安全

本仓库包含的内容

• @xmemo/client：官方 xmemo 命令行工具，用于设置、诊断、行为配置和记忆管理命令。
• MCP 分发：托管式 Streamable HTTP 配置（https://xmemo.dev/mcp）和本地 xmemo-mcp stdio 服务。
• XMemo Skill 和原生集成：面向 Agent 平台的 skills/xmemo，以及原生插件索引（src/plugins/index.json）。
• 市场和注册表元数据：面向 MCP Registry（server.json）、LobeHub（lhm.plugin.json）和 AI Agent（context7.json）的规范描述文件。

托管服务的实现为私有。

超越 MCP

MCP 是 XMemo 的一种访问方式，而非产品边界。XMemo 为 AI 工具和 Agent 提供持久、受治理的记忆操作层：

• 持久记忆：跨会话存储、搜索、列出和软删除持久事实、偏好及操作知识。
• 上下文召回：按需检索聚焦且相关的上下文，并提供令牌预算控制和文档展开功能。
• 会话连续性与工作状态：通过重启快照和状态保存／恢复，让 Agent 在进程重启后继续沿用上下文。
• 项目上下文与决策：跨 Agent 工作流跟踪项目范围内的事实、待办事项和持久决策。
• Agent 身份与来源追踪：通过Agent 实例归属跟踪每条记忆记录的作者和来源，不混淆凭据。
• 受治理的访问：范围限定令牌、客户端支持时使用 OAuth、软删除／硬删除以及敏感记忆处理（治理详情）。
• 原生集成与技能：专为 OpenClaw、Hermes、XMemo 技能（ClawHub）和 DeepSeek DSH 提供专用集成（已提供、已发布并完成试点测试；集成成熟度为 Preview）。
• 访问方式：通过 Model Context Protocol、本地 CLI（xmemo）和公开的 REST API统一访问。

预览：Cloud Skills；Dream（默认关闭）；Teams（Business 方案尚未推出）。启用此功能的账户可使用知识库。

XMemo CLI

@xmemo/client 是用于将 AI 工具连接到 XMemo 的官方控制平面。它让设置可重复执行，将凭据保留在项目文件之外，并为每个受支持的客户端提供一致的途径，以使用持久且归用户所有的记忆。

该软件包有意保持精简：包含 CLI 运行时、安全的客户端配置、行为配置文件、XMemo 技能和市场元数据。服务端代码、数据库、部署文件、日志和内部运维内容均不包含在 npm 分发包中。

架构

Why XMemo CLI

• 统一控制面 — 登录、诊断、配置、配置档案、更新和冒烟测试共用一个可预测的界面。
• 以隐私为设计原则 — 生成的项目配置引用凭据，而不会嵌入凭据值。
• 关键之处采用原生集成 — OpenClaw 和 Hermes 使用专用的记忆集成，而不是通过 MCP 重复实现相同能力。
• 其他场景均可移植 — 托管式 Streamable HTTP MCP 和本地 stdio 支持现代编辑器、终端和 Agent 运行环境。
• 安全自动化 — 受支持的设置和移除流程会在进行更改前提供预览、试运行或明确确认。
• 精简的供应链攻击面 — npm 包受明确的文件允许列表和发布来源证明约束。

快速开始

引导式入门（xmemo init）

如需交互式完成首次运行流程，包括账户身份验证、检测到的客户端、Agent 行为指引、MCP 服务设置、技能和插件，请运行：

npm install -g @xmemo/client
xmemo init

标志和选项：

• xmemo init --dry-run：查看完整的入门计划，不执行网络调用或磁盘写入。
• xmemo init --yes：自动接受并应用所有入门步骤，不显示交互式提示。
• xmemo init --json：以结构化 JSON 格式输出计划或结果信封。
• xmemo init --client <id>...：将入门流程限定为指定客户端（例如 cursor、codex、claude-code）。
• xmemo start：xmemo init 的别名，会执行快速入门引导步骤。

全局安装后，xmemo 是主命令，同时也提供 client 和 memory-os 作为别名。

手动逐步设置

xmemo account login
xmemo doctor
xmemo setup codex
xmemo status

将 codex 替换为你的客户端。写入前可预览配置：

xmemo setup cursor --dry-run

使用 npx 运行

你也可以通过 npx @xmemo/client <command> 直接运行任何 CLI 命令，无需全局安装：

# Check version or health
npx @xmemo/client --version
npx @xmemo/client doctor

# Guided onboarding without global install
npx @xmemo/client init

# Install skill or run MCP stdio server
npx @xmemo/client skill install
npx @xmemo/client mcp serve

提示

从 xmemo init 开始（或使用 xmemo account login、xmemo doctor 和 xmemo setup <client>）。 仅当客户端没有经过验证的设置流程时，才手动编辑 MCP 配置。

命令如何协同工作

XMemo CLI 架构建立在四项核心设计原则之上：

1. 统一资源语法（xmemo <resource> <action>）

每个集成组件都是一等资源，具有可预测的生命周期操作：

• 复合命令：xmemo setup [<client>...]、xmemo uninstall [<client>...] 和 xmemo status [<client>] 会根据客户端的声明式配置档案，一步协调这些资源。
• 向后兼容的别名：xmemo mcp add（mcp install 的别名）、xmemo profile uninstall（profile remove 的别名）和 xmemo skill uninstall（skill remove 的别名）等常用命令仍可正常使用，并会在交互式终端中打印一行实用提示。

2. 统一目标解析器

未明确传入客户端时，CLI 会使用确定性的三级优先级解析模型：

1. 显式标志或参数：--client <id>、位置客户端参数或 --all。
2. 调用方 Agent 环境：在 Agent 会话中运行时，自动识别调用方 Agent 运行时（例如，CLAUDECODE / CLAUDE_CODE_ENTRYPOINT 会映射到 claude-code，CODEX_THREAD_ID / CODEX_SESSION_ID 会映射到 codex）。
3. 检测到的已安装客户端：检查本地配置路径和标记。如果恰好找到一个匹配客户端，则自动选择；如果在交互模式下找到多个客户端，则会显示交互式选择器。CLI 绝不会将配置悄悄写入未经验证的任意路径。

3. 规划、一次确认、执行（PlanRunner）

修改命令遵循严格的原子化执行模式：

1. 构建计划：按顺序汇总跨资源的操作（例如，先安装插件，再配置技能）。
2. 预览：在终端打印完整计划（包括修改的路径、命令和统一差异）。
3. 一次确认：针对整个操作序列仅提示一次 [y/N]。使用 --yes 或 -y 重新运行可跳过提示；--dry-run 会显示预览但不进行修改。
4. 按序执行：按依赖顺序运行各步骤，并在首次失败时立即停止。对已配置的客户端重新运行时，会检测到所有组件均为最新状态，并报告 Nothing to do。

4. 声明式客户端注册表

所有客户端配置、配方和功能均集中声明在 src/clients/registry.js 中。命令实现是纯通用的协调器，不包含任何硬编码的客户端 ID 字符串。还可以通过 registerClient() 在运行时动态添加平台。

支持的集成

客户端注册表还涵盖 Devin Desktop（原名 Windsurf）、Cline、Continue、Claude Desktop、 Claude Code、Kimi Code、Muse Code、Zed、JetBrains、OpenCode、Qwen、Trae，以及兼容的 MCP 主机。运行 xmemo mcp list 查看当前机器可读目录。

VS Code 用户如需专用编辑器扩展，请参阅 yonro/xmemo-vscode 仓库。 Cursor 用户如需专用插件，请参阅 yonro/xmemo-cursor-plugin 仓库。 Claude 用户如需专用插件，请参阅 yonro/xmemo-claude-plugin 仓库。

连接模式

托管 MCP

推荐的通用接入方式是 XMemo Streamable HTTP 端点：

https://xmemo.dev/mcp

支持 OAuth 的客户端会在浏览器中完成身份验证。其他客户端会引用 XMEMO_KEY，而不会将其值复制到仓库文件中。

通用配置格式：

{
  "mcpServers": {
    "XMemo": {
      "type": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

客户端配置键各不相同；请优先使用 xmemo setup <client>，而不是直接复制此通用示例。

本地 stdio MCP

xmemo-mcp 是专为启动本地进程的市场和客户端提供的 stdio 入口点。安全发现无需令牌即可公开 20 个工具、三个提示词和两个文档资源。执行工具仍需身份验证。

全局安装后：

xmemo-mcp

免安装的 MCP 配置：

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@xmemo/client@latest",
        "xmemo-mcp"
      ]
    }
  }
}

如果已安装 CLI，xmemo mcp serve 的作用相同。

原生集成

OpenClaw 和 Hermes 提供专用记忆提供程序。默认设置会避免安装第二套重复的 XMemo 工具：

• OpenClaw：默认不使用 --force，安装固定版本的插件 clawhub:@xmemo/[email protected]。重新运行设置时会妥善检测已有安装；使用 --force 可重新安装或覆盖。
• Hermes：通过 pip install 安装固定版本的提供程序包 hermes-xmemo==1.1.3，不使用 -U。
• 每条安装命令都会在执行前打印确切命令。使用 --dry-run 可预览操作而不安装。

# Native OpenClaw plugin (clawhub:@xmemo/[email protected]) + XMemo Skill
xmemo setup openclaw

# Native Hermes memory provider (hermes-xmemo==1.1.3)
xmemo setup hermes

仅在需要明确的回退方案时添加托管 MCP：

xmemo setup openclaw --with-mcp
xmemo setup hermes --with-mcp

使用 --mcp-only 可跳过原生集成，仅安装托管 MCP 回退方案。

安装 XMemo Skill

CLI 会将经过验证的 XMemo Skill 安装到本地的 Agent 技能文件夹或指定目录：

• 安装到客户端技能目录：
  • Claude Code：~/.claude/skills/xmemo-memory（全局），或 .claude/skills/xmemo-memory（项目级，使用 --project）
  • Codex：~/.codex/skills/xmemo-memory
  • OpenClaw：~/.openclaw/skills/xmemo-memory
  • 其他 21 个客户端在官方文档发布前均保持为 null。
• 默认从 npm 安装固定版本 @xmemo/[email protected]，并在解压前验证 tarball 完整性（sha512 SRI）。
• 使用 --version <semver> 指定版本，或通过 --version latest 明确选择最新版本。
• 对于气隙环境或离线安装，可使用 --from <dir|tgz> 从本地目录或打包的 tarball 安装（可选使用 --integrity <sha512>）。
• 使用 skill status、skill update 和 skill remove 管理客户端技能。
• 使用 --dry-run 预览操作而不写入文件。
• 安全与许可：
  • 交互式安装会在写入前提示 [y/N]（按 Enter、遇到 EOF 或输入为空都会取消），除非指定 --yes。
  • 已有安装不会在未指定 --force 时覆盖；使用 --force 时，会在 ~/.xmemo/backups/skills/<client>/ 中创建备份（位于 Agent 技能目录之外）。
  • skill remove 只会移除经过验证的 XMemo 技能目录，拒绝移除非 XMemo 文件夹，并报告保留的备份位置。

# Install to agent skill folder (Claude Code global, Codex, or OpenClaw)
xmemo skill install --client claude-code
xmemo skill install --client codex
xmemo skill install --client openclaw

# Install OpenClaw skill globally (shared ~/.openclaw/skills)
xmemo skill install --client openclaw --global

# Install to project-level skill folder (Claude Code project: .claude/skills/xmemo-memory)
xmemo skill install --client claude-code --project

# Install for all detected supported clients
xmemo skill install --all

# Automatically resolve detected client(s) (or specify --client <id>)
xmemo skill install

# Install into a custom directory path
xmemo skill install --dir ./custom-skill-dir

# Non-interactive install (skips [y/N] prompt)
xmemo skill install --client codex --yes

# Replace existing installation (creates backup in ~/.xmemo/backups/skills/<client>/)
xmemo skill install --client codex --force --yes

# Update alias (equivalent to skill install --force)
xmemo skill update --client codex --yes

# Inspect installation status across clients
xmemo skill status
xmemo skill status --client codex
xmemo skill status --all --json

# Remove installed skill from an agent folder (refuses non-XMemo folders)
xmemo skill remove --client codex --yes
xmemo skill remove --client claude-code --project --yes

# Dry run preview
xmemo skill install --client codex --dry-run

独立的 curl 和 PowerShell 安装程序

对于没有 Node.js 或 @xmemo/client 的环境，XMemo 提供独立的 HTTPS 安装程序：https://xmemo.dev/skill/install（POSIX sh）和 https://xmemo.dev/skill/install.ps1（PowerShell）。

安装程序能够识别 Agent，并自动为当前使用的 Agent 确定正确的目标目录：

# Claude Code: installs to ~/.claude/skills/xmemo-memory
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_AGENT=claude-code sh

# Codex: installs to ${CODEX_HOME:-$HOME/.codex}/skills/xmemo-memory
curl -fsSL https://xmemo.dev/skill/install | XMEMO_SKILL_AGENT=codex sh

# OpenClaw: install via OpenClaw CLI
openclaw skills install @xmemo/xmemo --version 1.1.48

# Windows (PowerShell):
# $env:XMEMO_SKILL_AGENT="claude-code"; irm https://xmemo.dev/skill/install.ps1 | iex
# $env:XMEMO_SKILL_AGENT="codex"; irm https://xmemo.dev/skill/install.ps1 | iex

提示

给 AI Agent 的提示词（直接复制并粘贴到 Claude Code、Codex 或其他 Agent 中）：

将独立的 XMemo Skill 安装到你的 skills 目录：运行 https://xmemo.dev/skill/install 中的安装程序（在 Windows 上使用 https://xmemo.dev/skill/install.ps1），并将 XMEMO_SKILL_DIR 设置为你的 skills 目录加上 /xmemo-memory。运行它输出的 doctor 命令以验证安装，然后重新加载你的 skills，并按照 Skill 的首次运行步骤操作。遵循你常规的安全检查，不要使用提升的权限。

目标解析优先级（以首个匹配项为准）：

1. XMEMO_SKILL_DIR：安装到指定目录。
2. XMEMO_SKILL_AGENT=claude-code|codex：安装到指定 Agent 的 skills 目录（openclaw 会转而运行 openclaw skills install xmemo）。
3. 自动检测：自动检测 Claude Code（CLAUDECODE=1）或 Codex（CODEX_THREAD_ID、CODEX_SESSION_ID 或 CODEX_HOME）。
4. 主目录发现：如果 HOME 中仅存在 ~/.claude 或 ~/.codex，则选择对应的 Agent。
5. 回退：安装到 ./xmemo-skill，并在 stderr 上发出警告，说明 AI Agent 不会从此目录自动加载该 Skill。

安全与替换：

• 除非提供 XMEMO_SKILL_FORCE=1，否则拒绝覆盖现有安装。
• 替换时，会将之前的安装移至 ~/.xmemo/backups/skills/<agent>/<name>-<timestamp>（安全地置于 Agent Skill 搜索路径之外）。
• 安装后，会输出绝对安装路径、验证用的 doctor 命令（node <path>/scripts/xmemo-skill.mjs doctor --anonymous），以及重新加载 Agent 的提示。

Agent 插件

CLI 提供经过精选的静态索引，其中包含直接随 @xmemo/client 发布的已验证 Agent 插件。每个条目都包含在发布时确定的固定版本、发布标签和确切的 Git 提交 SHA。

ℹ️ 严格区分规则：xmemo plugin 仅安装 Agent 插件（例如 @xmemo/openclaw-memory）。技能只能通过 xmemo skill install 安装（例如 @xmemo/xmemo）。

命令：

# List available plugins (excluding legacy entries)
xmemo plugin list

# Include legacy plugins
xmemo plugin list --all

# View plugin details and verification metadata
xmemo plugin info <id>

# Preview install plan without executing
xmemo plugin install <id> --dry-run

# Install with explicit confirmation (prompts [y/N] by default)
xmemo plugin install <id>

# Non-interactive install
xmemo plugin install <id> --yes

# Specify profile for deepseek-dsh
xmemo plugin install deepseek-dsh --profile default --yes

# Specify custom target directory for git-dir plugins
xmemo plugin install claude-code --yes --dir ~/.custom-plugins/claude-code

# Open plugin documentation or marketplace in browser
xmemo plugin install <id> --open

# Check installation status
xmemo plugin status [<id>]

安全与授权：

• 仅接受静态索引中的已验证插件 ID；任意 URL 和未知 ID 都会被拒绝，并返回退出代码 2。
• 交互式安装始终会显示执行计划，并要求明确授权（[y/N]；输入为空或 EOF 时默认取消）。
• --dry-run 保证不会写入任何磁盘，也不会启动任何进程。
• Marketplace 和手动安装的插件会在执行 plugin install <id> 时显示插件仓库中的精确分步说明（传入 --open 可在浏览器中打开文档）。
• Git 目录插件（claude-code）会克隆到每位用户独有的稳定位置（~/.xmemo/plugins/<id>），支持通过 --dir <path> 覆盖路径，逐字节验证检出的 HEAD 提交，并输出确切的加载命令（claude --plugin-dir <dir>）。如果提交不匹配，会立即删除该目录。
• 插件子进程会在隔离环境中运行，身份验证令牌（XMEMO_KEY、MEMORY_OS_MCP_TOKEN、XMEMO_TOKEN）会从 argv 和环境变量中清除。

账户与身份验证

账户命令

通过 account 命令系列管理本地身份验证、已存储的凭据和令牌：

# Browser device login
xmemo account login

# Check active authentication state
xmemo account status

# Optional remote verification
xmemo account status --verify

# Check or store token credentials
xmemo account token status
printf '%s\n' 'your-token' | xmemo account token add --from-stdin --allow-plaintext

# Logout: remove locally stored XMemo credentials owned by the CLI
xmemo account logout

# Non-interactive logout
xmemo account logout --yes

安全退出账户（xmemo account logout）

• **移除目标：**仅移除由 CLI 所有、用户专属的凭据文件（~/.config/xmemo/credentials.json 或操作系统配置根目录中的文件）。
• **明确确认：**显示目标凭据路径，并提示 Proceed with logout? [y/N]（默认选择 No），除非指定了 --yes。
• **客户端与 Agent 隔离：**保留所有客户端 MCP 配置文件（Cursor、Claude、VS Code 等）和由 Agent 管理的 OAuth 会话。
• **隐私：**绝不在 stdout、stderr 或 JSON 信封中显示或泄露令牌值。
• **脚本使用：**指定 --json 时必须同时指定 --yes，以防止意外执行无头退出账户操作。

旧版身份验证别名

旧版命令仍受全面支持，并作为向后兼容的别名：

• xmemo login（xmemo account login 的别名）
• xmemo auth status（xmemo account status 的别名）
• xmemo auth-status（xmemo account status 的别名）
• xmemo token <status|add|set>（xmemo account token <status|add|set> 的别名）

在人类可读的交互模式下，旧版别名会向 stderr 输出一行弃用提示。使用 --json 或 --help 运行时，会抑制弃用提示。

导入现有令牌

通过 stdin 管道传入现有令牌，避免令牌出现在命令历史记录中：

printf '%s\n' 'your-token' | xmemo account token add --from-stdin --allow-plaintext
xmemo account token status --verify

PowerShell：

$xmemoToken = Read-Host "XMemo token"
$xmemoToken | xmemo account token add --from-stdin --allow-plaintext
Remove-Variable xmemoToken

对于 CI 和受管理的工作站，请通过平台的密钥管理器提供 XMEMO_KEY。不要将其提交到 .env、MCP 配置、日志、问题报告或聊天记录中。

通用 --json 输出

每条命令和子命令都支持 --json，便于编写可预测的脚本：

• 成功时：在 stdout 上输出有效的 JSON，退出代码为 0。
• 出错时：在 stdout 上输出结构化 JSON 错误封装 { schemaVersion, ok: false, command, data: null, error: { code, message, ... } }，并使用非零退出代码（例如，用于用法／输入错误的退出代码 2，用于内部／网络错误的退出代码 1）。

命令参考

xmemo init [--client <id>...] [--yes] [--dry-run] [--json]

# Backward-compatible alias
xmemo start [--json]

# High-level client configuration
xmemo setup <client> [--url <url>] [--no-profile] [--json] [--force]
xmemo setup <client> --dry-run
xmemo setup --all [--write] [--profile] [--force]

# Direct MCP server configuration
xmemo mcp serve
xmemo mcp list
xmemo mcp config --client <client-id> [--base-url <url>] [--json]
xmemo mcp add <client-id> [--write] [--config <path>]
xmemo mcp proxy [--port 8765] [--base-url <url>]

# Workspace behavior profiles
xmemo profile install <client-id> [--target <path>] [--dry-run]
xmemo profile show <client-id> [--target <path>] [--json]
xmemo profile status <client-id> [--target <path>] [--json]
xmemo profile uninstall <client-id> [--target <path>] [--yes]

# Install verified pinned skill into agent skill folders
xmemo skill install [--client <id>|--all] [--project] [--dir <path>] [--dry-run] [--yes] [--force] [--json]

# Inspect installation status across clients
xmemo skill status [--client <id>|--all] [--json]

# Remove installed skill from an agent folder (refuses non-XMemo folders)
xmemo skill remove --client <id> [--project] [--yes] [--json]

# Update skill installation (creates backup in ~/.xmemo/backups/skills/<client>/)
xmemo skill update [--client <id>|--all] [--yes] [--json]

xmemo plugin list [--all] [--json]
xmemo plugin info <id> [--json]
xmemo plugin install <id> [--dry-run] [--yes] [--open] [--dir <path>] [--json]
xmemo plugin status [<id>] [--all] [--json]

xmemo memory add --content "Remember this" --path notes/example --json
xmemo memory search "example" --json
xmemo memory read <id> --json
xmemo memory list [--path-prefix <prefix>] [--project <name>] [--query <text>] [--type <type>] [--all] [--limit <n>] [--offset <n>] --json
xmemo memory delete <id> [--reason <text>] [--yes] --json
xmemo memory restore <id> [--yes] --json
xmemo memory import --file memories.jsonl [--dry-run] [--idempotency-key <key>] [--yes] --json
xmemo memory ledger-delete --id <transaction-uuid> --yes --json
xmemo context recall "resume this task" --include-knowledge --json
xmemo state save --current-task "ship the client" --next-action "run tests" --json
xmemo state restore --json
xmemo restart snapshot --json
xmemo restart restore --snapshot-id <snapshot-id> --json

xmemo knowledge add --base <base-id> --file ./guide.pdf --title "Guide" --json
xmemo knowledge search "setup" --base <base-id> --json
xmemo knowledge read <item-id> --json > knowledge-view.json
xmemo knowledge update <item-id> --text "Updated" --from knowledge-view.json --publish --yes --json

xmemo dream preview --wait --json
xmemo dream show <run-id> --json > dream-view.json
xmemo dream apply <run-id> --item <candidate-id> --from dream-view.json --yes --json

xmemo cloud-skill list --json
xmemo cloud-skill add --file ./SKILL.md --json
xmemo cloud-skill show <skill-id> --json > skill-view.json
xmemo cloud-skill update <skill-id> --from skill-view.json --file ./SKILL.md --json
xmemo cloud-skill run <skill-id> --input ./args.json --from skill-view.json --yes --json

xmemo login --scopes memory:read,memory:write,memory:restore,knowledge:read,knowledge:write

xmemo account login [--base-url <url>] [--allow-plaintext] [--json]
xmemo account logout [--yes] [--json]
xmemo account status [--verify] [--base-url <url>] [--json]
xmemo account token status [--verify] [--json]
xmemo account token add --from-stdin --allow-plaintext [--json]
xmemo account token set --from-stdin [--allow-plaintext] [--json]

# Backward-compatible aliases (emit one-line deprecation note on stderr in human mode)
xmemo login
xmemo auth status
xmemo auth-status
xmemo token status
xmemo token add --from-stdin --allow-plaintext

# Diagnostics and environment validation
xmemo doctor [--services [memory,dream,knowledge,cloud-skill]] [--base-url <url>] [--json]
xmemo doctor --discovery [--base-url <url>] [--json]
xmemo doctor --client <client-id> [--config <path>] [--smoke] [--auth oauth|key] [--fix] [--json]

# Probes, updates, and environment
xmemo status [--url <url>] [--json]
xmemo update [--dry-run] [--json]
xmemo env [--example] [--shell bash|powershell|cmd] [--json]
xmemo privacy [--json]
xmemo --version [--json]

# Safe removal (only XMemo-owned entries and profiles are removed)
xmemo uninstall <client> --dry-run
xmemo uninstall <client> --yes
xmemo uninstall --all --dry-run
xmemo uninstall --all --yes --profiles

# Backward-compatible aliases (emit one-line deprecation note on stderr in human mode)
xmemo smoke --client codex
xmemo discovery show

运行 xmemo help 或 xmemo <command> --help，查看与当前版本匹配的完整选项。

客户端说明

xmemo setup codex
xmemo doctor --client codex --smoke

xmemo setup cursor

xmemo setup gemini
xmemo setup antigravity

xmemo login
xmemo setup openclaw
openclaw xmemo status

xmemo login
xmemo setup hermes

xmemo login
xmemo setup copilot
xmemo mcp proxy

默认安全

凭据优先级和兼容性别名说明见：

xmemo env example --shell bash
xmemo privacy

对于私有或可自托管的部署，请设置 XMEMO_URL 或传入 --url <service-url>。MEMORY_OS_URL 仍是兼容性别名。

软件包边界

发布到 npm：

bin/
docs/assets/
src/
README.md
LICENSE

不发布：

.github/
docs/analysis/
docs/architecture/
docs/design/
test/
coverage/
server code
database migrations
deployment files
logs and local state

开发

npm install
npm run release:check
npm run lint
npm test
npm run pack:dry-run

在提议发布版本之前，请运行完整的软件包检查：

npm run prepublishOnly

可直接检查本地 stdio 服务：

node bin/mcp-stdio.js

版本管理

此仓库分发两个版本轨道相互独立的产品：

• CLI（@xmemo/client）：发布到 npm。
  • 版本来源：package.json。
  • 标签约定：cli-v*（版本 0.4.181 及之前的旧标签使用 v0.4.xxx）。
  • 在 npm（@xmemo/client）查看版本。
• Skill（xmemo）：发布到 ClawHub，并通过 xmemo.dev分发。
  • 版本来源：skills/xmemo/scripts/xmemo-skill.mjs（SKILL_VERSION）。
  • 标签约定：skill-v*。
  • 在 ClawHub（xmemo）查看版本。Skill 发布对应的 GitHub Releases 会明确带有 Latest 发布徽标，以支持自动安装程序和服务端回退下载。

发布模型

常规版本由 GitHub Actions 根据确切的标签提交生成，而不是从可变的分支检出或开发者工作站生成：

develop → CLI version sync → test → cli-v tag → GitHub Actions → npm publish --provenance

CLI 包和托管 MCP 服务有意采用独立的版本序列：

• CLI/npm 版本：package.json、package-lock.json 和 server.json 中的 npm 包条目。
• 托管 MCP/Registry 版本：顶层 server.json.version 和 lhm.plugin.json。此版本与已部署的 XMemo 服务保持一致。

node scripts/check-release-version.mjs 会验证这两项约定。cli-vX.Y.Z 标签必须与 CLI/npm 版本一致，且只会发布 npm。MCP Registry 会单独发布，使用 mcp-vX.Y.Z 运行 Publish MCP Registry metadata 工作流；该标签必须与托管 MCP/Registry 版本一致。单独的 npm 发布工作流仅用于手动恢复，因此创建 GitHub Release 不会导致重复发布。CLI npm 发布使用 OIDC 可信发布（environment: npm、id-token: write）；不再使用静态 NPM_TOKEN。通过 .github/workflows/publish.yml 手动恢复发布，需要在 npmjs.com 上为其单独配置可信发布者。

文档与支持

规范的服务文档位于 docs.xmemo.dev。 此仓库介绍客户端；以下页面介绍它所连接的托管服务。

• XMemo
• MCP 服务参考
• 添加新客户端
• 问题反馈
• 版本发布

许可证

MIT © 2025–2026 Yonro