XMemo クイックスタート

XMemo を AI アシスタントの共有メモリホームとして使います。クライアントを接続し、有用なコンテキストを一度保存して後から呼び出し、認証情報を公開設定に置かないようにします。

概要 #

ひとつのメモリホーム

長期的な好み、プロジェクトの事実、意思決定、引き継ぎメモをユーザー所有のメモリレイヤーに保存し、承認済みアシスタントが呼び出せるようにします。

クライアントを接続

ChatGPT、Claude、VS Code / GitHub Copilot、Copilot CLI、Codex、Gemini、Cursor、または直接 MCP ランナー向けのクライアントプロファイルでホステッド MCP URL を使用します。

コントロールを維持

対応クライアントでは OAuth を使い、直接クライアントでは環境変数シークレットで受け渡し、アカウント管理で確認・削除・エクスポートの境界を扱います。

Persona onboarding flows #

ChatGPT ユーザー

Goal: bearer token をチャットに貼り付けずに、ChatGPT が XMemo の設定、プロジェクト事実、意思決定、TODO に永続的にアクセスできるようにします。
Connection: ChatGPT/OpenAI app の OAuth フローで hosted XMemo MCP server に接続し、XMemo アカウントに memory:read と memory:write の許可を承認します。
Success action: 合成の設定またはプロジェクトメモを保存し、新しいチャットを開始してから、作業を続ける前に ChatGPT に XMemo 経由でそれを呼び出させます。
Troubleshooting: OAuth が失敗する、またはツールが表示されない場合は、direct token を作成する前に、ホストアプリで MCP server からサインアウトし、XMemo server URL を再接続して再試行します。

Copilot / Codex 開発者

Goal: リポジトリの判断、コーディング規約、バグ修正メモ、タスク履歴を IDE と CLI エージェント間で持ち運べます。
Connection: 利用可能な場合は、VS Code / GitHub Copilot および Gemini CLI に OAuth を使用してください。Copilot CLI、Codex、Cursor、またはその他の直接 MCP クライアントの場合は、XMEMO_KEY をローカル環境またはシークレットストアに保持し、安定した XMEMO_AGENT_INSTANCE_ID を設定してください。
Success action: コードベースの判断またはバグ修正を記録し、次の IDE または CLI エージェントに、編集前に関連する XMemo コンテキストを呼び出させます。
Troubleshooting: 呼び出し結果が空の場合は、選択した MCP 設定パス、direct client 用の XMEMO_KEY 環境変数、ホストアプリ内の古い OAuth 認証情報を確認します。

チーム / エンタープライズ pilot owner

Goal: アカウント制御、ソース attribution、エクスポート/削除ワークフロー、レビュー担当者向けに安全な設定証跡で共有メモリを評価します。
Connection: 保護された XMemo workspace を作成または開き、承認済みユーザーを招待してから、readiness badges に従って OAuth またはスコープ付き direct credential で各クライアントを接続します。
Success action: pilot メンバーに合成のチームメモリを保存してもらい、XMemo でソース attribution を確認し、削除/エクスポートとサポート経路をレビューします。
Troubleshooting: メンバーが接続できない場合は、新しい token を発行する前に、ロール権限、OAuth 承認、クライアント readiness 状態、サポートガイダンスを確認します。

自律エージェント operator

Goal: headless またはスケジュール済みエージェントが進捗を記録し、過去の判断を取得し、安定した非秘密のインスタンス ID を保持できるようにします。
Connection: /api/v1/mcp/config/autonomous-agent を取得します。runner が OAuth + custom headers をサポートする場合は auth_modes.oauth を優先し、完全 headless runner の場合のみ secret store の XMEMO_KEY で auth_modes.xmemo_key を使います。
Success action: XMemo に進捗を書き込む合成タスクを 1 つ実行し、runner を再起動して、同じ XMEMO_AGENT_INSTANCE_ID でその進捗を呼び出せることを確認します。
Troubleshooting: attribution が変わる、または呼び出し結果がインスタンス間で分かれる場合は、XMEMO_AGENT_INSTANCE_ID を git の外に永続化し、runner が起動ごとに再生成していないことを確認します。

Memory Console の管理 #

XMemo は MCP エンドポイントだけではありません。Memory Console は、エージェント帰属を見える状態に保ちながら、メモリを確認・修正・削除・エクスポートするためのユーザー向け入口です。

メモリの表示と検索

コンソールを開いて保存済みメモリ、パス、メモリタイプを確認し、特定の項目が記憶検索で返るべきだったかを確認します。

項目の編集・修正

古い事実を修正し、項目をより明確なパスへ移動し、古いメモを置き換えて、今後のアシスタントがユーザー承認済みの最新コンテキストを呼び出せるようにします。

削除とエクスポート

アカウントワークフローを使って不要になったメモリを削除し、アカウント単位のメモリ確認に使うエクスポート導線を見つけます。

エージェント帰属

どのクライアントまたはランナーがメモリを書き込んだかを確認します。クライアントが送信する非シークレットのエージェントおよびインスタンスラベルも含みます。

プライバシーと認証情報の管理

個人またはチームのパイロットを拡大する前に、OAuth 同意、直接トークンの利用、環境変数シークレットの受け渡し、サポート境界を見える状態に保ちます。

XMemo へのアクセスを申請 #

アカウント入口を開く ↗

ホステッド XMemo クイックスタート #

まず管理型 XMemo サービスと以下の接続パスから始めます。セルフホスト、Docker、Supabase、Python パッケージのセットアップは開発者向け参考資料であり、ホステッドユーザーの最初の導線ではありません。

エージェントに依頼

通常の安全確認に従う信頼できるエージェントに貼り付けてください。

スタンドアロン XMemo Skill をスキルディレクトリにインストールします: https://xmemo.dev/skill/install (Windows では https://xmemo.dev/skill/install.ps1) からインストーラーを実行し、XMEMO_SKILL_DIR をスキルディレクトリ + /xmemo-memory に設定します。出力される doctor コマンドを実行してインストールを確認し、スキルを再読み込みして Skill の初期設定手順に従ってください。通常の安全確認に従い、管理者権限は使用しないでください。

OAuth クライアント

ホストが OAuth に対応している場合、ChatGPT、OpenAI アプリレビュー、VS Code、GitHub Copilot ではこのパスを使います。ホステッド MCP URL を追加し、memory:read と memory:write を承認し、XMEMO_KEY をクライアント設定に貼り付けないでください。

MCP URL: https://xmemo.dev/mcp
Scopes: memory:read memory:write

XMEMO_KEY を使う直接 MCP

OAuth を完了できないクライアントまたはヘッドレスランナーでのみこのパスを使います。XMEMO_KEY はローカル環境またはシークレットストアに保存し、設定にはホステッド MCP URL を残し、実トークンを公開ドキュメントやチャットへ貼り付けないでください。

MCP URL: https://xmemo.dev/mcp
Token source: XMEMO_KEY environment variable
Optional identity: XMEMO_AGENT_INSTANCE_ID

アカウント管理

初回接続後はアカウント入口で保存内容を確認し、エージェント帰属をチェックし、パイロット拡大前に削除・エクスポートやサポートの導線を確認します。

Account entry: https://xmemo.dev/login

公開向け安全性 #

公開サービス検出は読み取り専用で秘密情報を含みません。
Client setup requires secrets in environment variables or a system secret store, not in generated URLs.
公開製品ドキュメントでは、運用コンソール、API ドキュメント、サービス検出 JSON、インストーラーカタログ、生の初期設定 URL、生のサービス URL、資格情報へのリンクを意図的に避けています。

ソース根拠 #

XMemo のサービス検出ルート、ホスト型サービス検出契約、MCP サーバー、TypeScript SDK に基づくドキュメント。

FAQ / トラブルシューティング #

なぜAIアシスタントは、以前伝えたことを覚えていないのですか？ —
なぜAIアシスタントはprojectやconversationを混同するのですか？ —
AIアシスタントに何かを完全に忘れさせるにはどうすればよいですか？ —
computerやAIアシスタントを変えても、XMemoは私を覚えていますか？ —
なぜAIアシスタントは同じことを2回保存したのですか？ —
なぜAIアシスタントは過去のcontextを多すぎたり少なすぎたりして返すのですか？ —
XMemoの接続を解除した後、古いアシスタントが使えないことを確認するには？ —
なぜAIアシスタントでXMemoを使えなくなったのですか？ —
AIアシスタントでは、どのXMemo connectionを使えばよいですか？ —
AIアシスタントがまだXMemoに接続できない場合はどうすればよいですか？ —

前提条件 #

Approved service URL - Used by xmemo setup --url to fetch discovery, onboarding status, and MCP config templates.
Node.js and npm - Discovery and the product page advertise @xmemo/client as the public CLI package.
Scoped token or OAuth grant - ChatGPT and VS Code / GitHub Copilot use OAuth; direct MCP and REST clients use XMEMO_KEY from an environment variable or secret store.

XMemo に接続 #

xmemo setup --url drives the entire trial. The documented hosted setup flow is implemented as discovery → onboarding status → MCP config template → reviewed client configuration.

npm install -g @xmemo/client
npx @xmemo/client setup --url https://xmemo.dev

MCP 設定 #

XMemo MCP setup lives in Docs because auth differs by client. ChatGPT, VS Code / GitHub Copilot, and Gemini CLI use hosted OAuth; direct/headless clients use the hosted Streamable HTTP URL plus XMEMO_KEY from the local environment or secret store.

VS Code / GitHub Copilot

%APPDATA%\Code\User\mcp.json

{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Codex

~/.codex/config.toml

[mcp_servers.XMemo]
url = "https://xmemo.dev/mcp"
bearer_token_env_var = "XMEMO_KEY"

[mcp_servers.XMemo.http_headers]
X-Memory-OS-Agent-ID = "codex"

[mcp_servers.XMemo.env_http_headers]
X-Memory-OS-Agent-Instance-ID = "XMEMO_AGENT_INSTANCE_ID"

Gemini CLI

~/.gemini/settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Devin Desktop (formerly Windsurf)

~/.config/devin/mcp_config.json

{
  "mcpServers": {
    "XMemo": {
      "serverUrl": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "windsurf",
        "X-Memory-OS-Agent-Instance-ID": "${env:XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Kiro

~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "kiro",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "oauth": {
        "oauthScopes": [
          "memory:read",
          "knowledge:read"
        ]
      }
    }
  }
}

Muse Code

~/.config/muse/settings.json

{"schema_version": 1, "mcpServers": {"xmemo": {"type": "streamable-http", "url": "https://xmemo.dev/mcp", "mode": "optional"}}}

OpenClaw

~/.openclaw/openclaw.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "openclaw",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Copilot CLI

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

ChatGPT / OpenAI Apps SDK

OpenAI Platform アプリ管理ダッシュボード

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "transport": "streamable-http",
      "auth": {
        "type": "oauth2",
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      }
    }
  }
}

Autonomous agent

エージェントランナー MCP 設定

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "autonomous-agent",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      },
      "auth": {
        "type": "oauth2",
        "flow": "authorization_code",
        "pkce_required": true,
        "resource": "https://xmemo.dev/mcp",
        "scopes": ["memory:read", "memory:write"]
      },
      "fallback": {
        "use_when": "headless runner cannot complete OAuth sign-in or persist OAuth tokens",
        "authorization_header": "Bearer ${XMEMO_KEY}"
      }
    }
  }
}

その他

MCP 対応の任意のエージェント

{
  "mcpServers": {
    "XMemo": {
      "transport": "streamable-http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "${XMEMO_AGENT_ID}",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Kimi Code

~/.kimi-code/mcp.json

{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "bearerTokenEnvVar": "XMEMO_KEY",
      "headers": {
        "X-Memory-OS-Agent-ID": "kimi-code",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Code

~/.claude.json

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-code",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:claude-desktop",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Cline (VS Code)

~/Documents/Cline/MCP/cline_mcp_settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cline",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Continue (VS Code / JetBrains)

~/.continue/config.json

{
  "mcpServers": {
    "XMemo": {
      "transport": {
        "type": "streamable-http",
        "url": "https://xmemo.dev/mcp",
        "headers": {
          "Authorization": "Bearer ${XMEMO_KEY}",
          "X-Memory-OS-Agent-ID": "continue",
          "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
        }
      }
    }
  }
}

Zed

Zed settings.json (varies by OS)

{
  "context_servers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:zed",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Trae

Trae user config mcp.json (varies by OS)

{
  "mcpServers": {
    "XMemo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://xmemo.dev/mcp",
        "--header",
        "Authorization:Bearer ${XMEMO_KEY}",
        "--header",
        "X-Memory-OS-Agent-ID:trae",
        "--header",
        "X-Memory-OS-Agent-Instance-ID:${XMEMO_AGENT_INSTANCE_ID}"
      ],
      "env": {
        "XMEMO_AGENT_INSTANCE_ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Grok

~/.grok/config.toml

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "grok",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Antigravity 2.0

~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "XMemo": {
      "serverUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "antigravity",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Qwen

~/.qwen/settings.json

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "qwen",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

OpenCode

~/.config/opencode/opencode.json

{
  "mcp": {
    "XMemo": {
      "type": "remote",
      "url": "https://xmemo.dev/mcp",
      "enabled": true,
      "headers": {
        "X-Memory-OS-Agent-ID": "opencode",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

Client capability matrix #

The canonical matrix is the source of truth for each client's OAuth mode, MCP transport, credential handling, readiness, evidence boundary, and marketplace state. This page only provides the setup console; do not copy a status into another page without checking the matrix.

Read CLIENT_CAPABILITY_MATRIX.md on GitHub ↗

Autonomous agent プリセット #

Autonomous agents should fetch /api/v1/mcp/config/autonomous-agent instead of asking humans to choose identity fields.

MCP ツール面 #

The discovery response lists the actual MCP transport as streamable-http and advertises tools implemented by the XMemo MCP server.

Recall tools - search_memory, recall, recall_plan, and recall_context.
Write tools - remember, store_memory, update_memory, and record_event.
Governance tools - forget_memory, redact_memory, explain_memory, and conflict/version helpers.

SDK ワークフロー補助機能 #

The TypeScript SDK exposes workflow helpers in packages/memory-os-js. These helpers route events through capture policy before writing memory.

スキルとエージェント #

Skills are the instruction-and-command lane for agents that do not mount a hosted MCP server directly.

XMemo クイックスタート

概要 #

Persona onboarding flows #

ChatGPT ユーザー

Copilot / Codex 開発者

チーム / エンタープライズ pilot owner

自律エージェント operator

Memory Console の管理 #

メモリの表示と検索

項目の編集・修正

削除とエクスポート

エージェント帰属

プライバシーと認証情報の管理

XMemo へのアクセスを申請 #

ホステッド XMemo クイックスタート #

エージェントに依頼

OAuth クライアント

XMEMO_KEY を使う直接 MCP

アカウント管理

公開向け安全性 #

ソース根拠 #

FAQ / トラブルシューティング #

前提条件 #

XMemo に接続 #

MCP 設定 #

VS Code / GitHub Copilot

Cursor

Codex

Gemini CLI

Claude Desktop

Devin Desktop (formerly Windsurf)

Kiro

Muse Code

OpenClaw

Copilot CLI

ChatGPT / OpenAI Apps SDK

Autonomous agent

その他

Kimi Code

Claude Code

Claude Desktop

Cline (VS Code)

Continue (VS Code / JetBrains)

Zed

Trae

Grok

Antigravity 2.0

Qwen

OpenCode

Client capability matrix #

Autonomous agent プリセット #

MCP ツール面 #

SDK ワークフロー補助機能 #

スキルとエージェント #

次のステップ #