XMemo 快速开始

把 XMemo 用作 AI 助手共享的记忆主页：连接一个客户端，一次保存有用上下文，之后随时召回，并避免把凭据放进公开配置。

简介 #

把 XMemo 用作 AI 助手共享的记忆主页：连接一个客户端，一次保存有用上下文，之后随时召回，并避免把凭据放进公开配置。

一个记忆主页

把长期偏好、项目事实、决策和交接备注保存在用户拥有的记忆层中，供已授权的助手召回。

连接你的客户端

将托管 MCP URL 与 ChatGPT、Claude、VS Code / GitHub Copilot、Copilot CLI、Codex、Gemini、Cursor 或直接 MCP runner 的客户端配置一起使用。

保持控制权

在支持时使用 OAuth；直接客户端使用环境变量密钥交接；通过账号控制理解查看、删除和导出边界。

Persona onboarding flows #

ChatGPT 用户

Goal: 让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。
Connection: 通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。
Success action: 保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。
Troubleshooting: 如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

Copilot / Codex 开发者

Goal: 在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。
Connection: 在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。
Success action: 记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。
Troubleshooting: 如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

团队 / 企业 pilot owner

Goal: 用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。
Connection: 创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。
Success action: 让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。
Troubleshooting: 如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

自主 agent operator

Goal: 让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。
Connection: 获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。
Success action: 运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。
Troubleshooting: 如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。

Memory Console 控制 #

XMemo 不只是一个 MCP endpoint。Memory Console 是面向用户的管理入口，可查看、修正、删除和导出记忆，同时保留 agent 归因可见。

查看和搜索记忆

打开控制台查看已保存的记忆、检查路径和记忆类型，并确认某次召回是否应该返回特定条目。

编辑或修正条目

修正过时事实、移动到更清晰的路径，或替换旧备注，让后续助手召回用户认可的最新上下文。

删除和导出

使用账号流程删除不再需要的记忆，并找到账号范围记忆审查的导出路径。

Agent 归因

查看是哪一个客户端或 runner 写入了记忆，包括客户端发送的非密钥 agent 与 instance 标签。

隐私与凭据控制

在扩大个人或团队试点前，保持 OAuth 授权、direct-token 使用、环境变量密钥交接和支持边界可见。

申请 XMemo 访问权限 #

打开账户入口 ↗

托管 XMemo 快速开始 #

先从托管 XMemo 服务和以下连接路径开始。自托管、Docker、Supabase 和 Python 包安装是开发者参考资料，不是托管用户的第一路径。

让你的智能体安装

将此提示粘贴给你信任且会遵守正常安全检查的智能体。

请将独立版 XMemo Skill 安装到您的 skills 目录：从 https://xmemo.dev/skill/install（Windows 下为 https://xmemo.dev/skill/install.ps1）运行安装程序，并将 XMEMO_SKILL_DIR 设置为您的 skills 目录加上 /xmemo-memory。运行其输出的 doctor 命令验证安装，然后重新加载您的 skills 并按照 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

仅当客户端或无头 runner 无法完成 OAuth 时使用这条路径。把 XMEMO_KEY 存在本地环境或密钥库中，在配置里保留托管 MCP URL，绝不要把真实 token 粘贴到公开文档或聊天中。

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

账号控制

首次连接后，通过账号入口查看保存了什么、检查 agent 归因，并在扩大试点前找到删除/导出或支持路径。

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 assistant 不记得我之前告诉它的事情？ —
为什么我的 AI assistant 把不同的 project 或对话混在一起？ —
怎样才能让我的 AI assistant 完全忘记某件事？ —
我更换了电脑或 AI assistant，XMemo 还会记得我吗？ —
为什么我的 AI assistant 把同一件事保存了两次？ —
为什么我的 AI assistant 给了太多或太少的历史上下文？ —
我断开了 XMemo，怎样确认旧 assistant 无法再使用它？ —
为什么我的 AI assistant 不能再使用 XMemo？ —
我应该在 AI assistant 中使用哪个 XMemo connection？ —
如果我的 AI assistant 仍无法连接 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

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 preset #

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.

技能与智能体 (Agent) #

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

自主 agent operator

Memory Console 控制 #

查看和搜索记忆

编辑或修正条目

删除和导出

Agent 归因

隐私与凭据控制

申请 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 preset #

MCP 工具接口 #

SDK 工作流辅助方法 #

技能与智能体 (Agent) #

后续步骤 #