XMemo

XMemo：AI エージェント向けメモリー OS

XMemo は AI エージェント向けの、ユーザーが所有するメモリー OS です。エージェントの ID、出所、管理されたアクセスとともに、永続的なメモリー、プロジェクトのコンテキスト、セッションの継続性を提供し、MCP、CLI、パブリック REST API を通じて複数の AI クライアント間で共有できます。

English · 简体中文 | ドキュメント · ホスト型 MCP

クイックスタート · このリポジトリの内容 · MCP を超えて · 対応インテグレーション · 接続モード · プラグイン · コマンド · バージョン管理 · デフォルトのセキュリティ

このリポジトリの内容

• @xmemo/client：セットアップ、診断、動作プロファイル、メモリーコマンドに対応する公式 xmemo CLI です。
• MCP 配布：ホスト型 Streamable HTTP の設定（https://xmemo.dev/mcp）と、ローカルの xmemo-mcp stdio サーバーです。
• XMemo スキルとネイティブインテグレーション：エージェントプラットフォーム向けの skills/xmemo と、ネイティブプラグインのインデックス（src/plugins/index.json）です。
• マーケットプレイスとレジストリのメタデータ：MCP Registry（server.json）、LobeHub（lhm.plugin.json）、AI エージェント（context7.json）向けの正規ディスクリプターです。

ホスト型サービスの実装は非公開です。

MCP の先へ

MCP は XMemo のアクセス手段の一つであり、製品の境界ではありません。XMemo は、AI ツールやエージェントに永続的で、ガバナンスが適用されたメモリ運用レイヤーを提供します。

• 永続メモリ：セッションをまたいで、事実、好み、運用知識を保存、検索、一覧表示し、論理削除できます。
• コンテキストの想起：トークン予算の制御やドキュメントの展開により、必要に応じて関連性の高いコンテキストを絞り込んで取得できます。
• セッションの継続性と作業状態：再起動用のスナップショットと状態の保存・復元により、エージェントはプロセスの再起動後もコンテキストを引き継いで再開できます。
• プロジェクトのコンテキストと決定事項：エージェントのワークフローをまたいで、プロジェクト単位の情報、TODO、永続的な決定事項を追跡できます。
• エージェントの識別情報と出所：エージェントインスタンスの帰属情報を通じて、認証情報を混同せずに、メモリレコードごとの作成者と出所を追跡できます。
• ガバナンスに基づくアクセス：スコープ付きトークン、クライアントが対応している場合の OAuth、論理削除・完全削除、機密メモリの取り扱いを提供します（ガバナンスの詳細）。
• ネイティブ連携とスキル：OpenClaw、Hermes、XMemo Skill（ClawHub）、DeepSeek DSH（利用可能で、リリース済みかつパイロットテスト済み。連携の成熟度は Preview）専用の連携を提供します。
• アクセス手段：Model Context Protocol、ローカル CLI（xmemo）、公開 REST API を通じて統合されています。

Preview：Cloud Skills、Dream（デフォルトでは無効）、Teams（Business プランはまだ利用できません）。Knowledge Bases は、アカウントで有効化されている場合に利用できます。

XMemo CLI

@xmemo/client は、AI ツールを XMemo に接続するための公式コントロールプレーンです。セットアップを再現可能にし、認証情報をプロジェクトファイルに含めず、サポート対象のすべてのクライアントで、ユーザーが所有する永続メモリへの一貫した接続方法を提供します。

このパッケージは意図的に小さく設計されています。CLI ランタイム、安全なクライアント設定、動作プロファイル、XMemo スキル、マーケットプレイスのメタデータが含まれます。サーバーコード、データベース、デプロイファイル、ログ、内部運用機能は npm パッケージの配布対象外です。

アーキテクチャ

XMemo CLI を選ぶ理由

• 一元管理 — ログイン、診断、設定、プロファイル、更新、スモークテストを、予測可能な単一のインターフェースで実行できます。
• プライバシーを設計の中心に — 生成されるプロジェクト設定では認証情報を参照しますが、認証情報の値を埋め込むことはありません。
• 必要な箇所ではネイティブに対応 — OpenClaw と Hermes では、MCP 経由で同じ機能を重複させるのではなく、専用のメモリ統合を使用します。
• それ以外の環境でも幅広く対応 — ホスト型 Streamable HTTP MCP とローカル stdio により、最新のエディター、ターミナル、エージェントランタイムをサポートします。
• 安全な自動化 — サポート対象のセットアップと削除では、変更を加える前にプレビュー、ドライラン、または明示的な確認を行います。
• サプライチェーンの対象範囲を最小限に — npm パッケージは、明示的なファイル許可リストとリリースの来歴情報によって管理されています。

クイックスタート

ガイド付きオンボーディング（xmemo init）

アカウント認証、検出されたクライアント、エージェントの動作指示、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 のアーキテクチャは、次の 4 つの基本設計原則に基づいています。

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 のエイリアス）などの使い慣れたコマンドも引き続き完全に動作し、対話型ターミナルでは役立つヒントを 1 行表示します。

2. 統合ターゲットリゾルバー

クライアントが明示的に指定されていない場合、CLI は決定論的な3段階の優先順位解決モデルを使用します。

1. 明示的なフラグまたは引数：--client <id>、位置引数のクライアント指定、または --all。
2. 呼び出し元エージェントの環境：エージェントのセッション内で実行されている場合、呼び出し元のエージェントランタイムを自動的に識別します（例：CLAUDECODE / CLAUDE_CODE_ENTRYPOINT は claude-code に、CODEX_THREAD_ID / CODEX_SESSION_ID は codex に対応します）。
3. 検出されたインストール済みクライアント：ローカルの設定パスと識別マーカーを調べます。一致するクライアントが1つだけ見つかった場合は自動的に選択され、対話モードで複数のクライアントが見つかった場合は、対話型ピッカーが表示されます。CLI が未検証の任意のパスに設定を書き込むことはありません。

3. 計画、1回の確認、適用（PlanRunner）

変更を伴うコマンドは、厳格でアトミックな実行パターンに従います。

1. 計画の作成：リソースをまたぐアクションの順序付きシーケンスを組み立てます（例：プラグインのインストール後にスキルを設定）。
2. プレビュー：変更対象のパス、コマンド、統合差分を含む計画全体をターミナルに表示します。
3. 1回だけ確認：シーケンス全体に対して [y/N] のプロンプトを1回だけ表示します。--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 個のツール、3 つのプロンプト、2 つのドキュメントリソースを公開します。ツールの実行には引き続き認証が必要です。

グローバルインストール後：

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 をエージェントのスキルフォルダーまたは指定したディレクトリにローカルインストールします。

• クライアントのスキルディレクトリにインストールします。
  • 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>（任意の --integrity <sha512>）を使用して、ローカルディレクトリまたはパック済み tarball からインストールします。
• skill status、skill update、skill remove でクライアントのスキルを管理します。
• ファイルを書き込まずに操作を確認するには --dry-run を使用します。
• 安全性と同意：
  • --yes を指定しない場合、対話型インストールでは書き込み前に [y/N] を求めます（Enter、EOF、または空の入力を指定するとキャンセルされます）。
  • 既存のインストールは --force を指定しない限り上書きを拒否します。--force を使用すると、エージェントのスキルディレクトリの外にある ~/.xmemo/backups/skills/<client>/ にバックアップが作成されます。
  • skill remove は検証済みの 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://xmemo.dev/skill/install（POSIX sh）および https://xmemo.dev/skill/install.ps1（PowerShell）で単体の HTTPS インストーラーを提供しています。

インストーラーはエージェントを認識し、現在使用中のエージェントに適した対象ディレクトリを自動的に特定します。

# 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 エージェントへのプロンプト（Claude Code、Codex、または別のエージェントに直接コピーして貼り付けてください）：

スタンドアロン版の XMemo Skill をスキルディレクトリにインストールしてください。XMEMO_SKILL_DIR にスキルディレクトリと /xmemo-memory を指定して、https://xmemo.dev/skill/install からインストーラーを実行してください（Windows の場合は https://xmemo.dev/skill/install.ps1）。表示された doctor コマンドを実行してインストールを確認した後、スキルを再読み込みし、Skill の初回実行手順に従ってください。通常の安全確認を行い、昇格した権限は使用しないでください。

対象ディレクトリの決定優先順位（最初に一致したものを適用）：

1. XMEMO_SKILL_DIR：指定されたディレクトリにインストールします。
2. XMEMO_SKILL_AGENT=claude-code|codex：指定されたエージェントのスキルディレクトリにインストールします（openclaw の場合は openclaw skills install xmemo を実行します）。
3. 自動検出：Claude Code（CLAUDECODE=1）または Codex（CODEX_THREAD_ID、CODEX_SESSION_ID、または CODEX_HOME）を自動的に検出します。
4. ホームディレクトリの検出：HOME に ~/.claude または ~/.codex のどちらか一方だけが存在する場合、そのエージェントを選択します。
5. フォールバック：./xmemo-skill にインストールします。このディレクトリからは AI エージェントがスキルを自動的に読み込まないことを説明する警告を stderr に出力します。

安全性と置き換え：

• XMEMO_SKILL_FORCE=1 が指定されていない場合、既存のインストールを上書きしません。
• 置き換え時は、以前のインストールを ~/.xmemo/backups/skills/<agent>/<name>-<timestamp> に移動します（エージェントのスキル検索パスの外に安全に保管します）。
• インストール後、絶対インストールパス、確認用 doctor コマンド（node <path>/scripts/xmemo-skill.mjs doctor --anonymous）、およびエージェントを再読み込みするためのプロンプトを表示します。

エージェントプラグイン

CLI は、@xmemo/client に直接同梱された、検証済みエージェントプラグインの厳選された静的インデックスを提供します。各エントリには、リリース時に確定した固定バージョン、リリースタグ、正確な Git コミット SHA が含まれます。

ℹ️ 厳格な分離ルール：xmemo plugin でインストールできるのはエージェントプラグインのみです（例：@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 を指定すると、ディスクへの書き込みもプロセスの起動も一切行われません。
• マーケットプレイスプラグインと手動インストールプラグインでは、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 と env から除去した隔離環境で実行されます。

アカウントと認証

アカウントコマンド

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 または OS の設定ルート）のみを削除します。
• 明示的な確認： --yes を指定しない場合、対象となる認証情報のパスを表示し、Proceed with logout? [y/N] と確認します（デフォルトは「いいえ」です）。
• クライアントとエージェントの分離： すべてのクライアントの MCP 設定ファイル（Cursor、Claude、VS Code など）と、エージェントが管理する OAuth セッションを保持します。
• プライバシー： 標準出力、標準エラー出力、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> のエイリアス）

対話型の人間向けモードでは、レガシーエイリアスを実行すると、非推奨を知らせるヒントが1行、stderr に出力されます。--json または --help を指定して実行した場合、このヒントは表示されません。

既存トークンのインポート

既存のトークンを標準入力経由で渡すと、コマンド履歴に表示されません。

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 をサポートしています。

• 成功時：終了コード 0 で、有効な JSON を stdout に出力します。
• エラー時：構造化された JSON エラーエンベロープ { schemaVersion, ok: false, command, data: null, error: { code, message, ... } } を stdout に出力し、ゼロ以外の終了コードを返します（例：使用法／入力エラーでは終了コード 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

バージョン管理

このリポジトリでは、バージョン系列を独立して管理する、相互に独立した2つの製品を配布しています。

• 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／レジストリのバージョン：トップレベルの server.json.version と lhm.plugin.json。このバージョンは、デプロイ済みの XMemo サービスに準じます。

node scripts/check-release-version.mjs で、両方のルールを検証します。cli-vX.Y.Z タグは CLI/npm のバージョンと一致する必要があり、npm のみを公開します。MCP レジストリは mcp-vX.Y.Z を使用して Publish MCP Registry metadata ワークフローから個別に公開し、ホスト型 MCP／レジストリのバージョンと一致する必要があります。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