Copilot CLI

前置条件

使用支持 MCP 配置的 GitHub Copilot CLI。该路径特意与 VS Code / GitHub Copilot Chat 的 OAuth 路径区分开。Copilot CLI 支持在 ~/.copilot/mcp-config.json 中配置自定义 HTTP 请求头，或通过 memory-os-cli 接入本地代理。

• 端点：https://xmemo.dev/mcp。
• 传输协议：Streamable HTTP（配置中声明 type: "http"）或本地代理（xmemo mcp proxy）。
• 认证方式：通过 Copilot 官方 MCP UI/CLI 或受支持的密钥引用填入 Authorization；请勿假设请求头中会自动展开环境变量（${env:…}）。
• 配置文件：~/.copilot/mcp-config.json。
• 就绪状态：Copilot CLI 请求头中的环境变量直接展开为 not-tested；本地代理路径已通过 memory-os-cli 的 MCP-SETUP-GUIDE.md 验证。

安装 / 设置

将 XMemo 服务块添加至 ~/.copilot/mcp-config.json 的 mcpServers 下，或通过 memory-os-cli 本地代理运行。不要复用 VS Code 的 servers 键配置；Copilot CLI 属于不同的客户端路径。

• 直接远程 HTTP：在 ~/.copilot/mcp-config.json 中添加带有 type: "http", url: "https://xmemo.dev/mcp", timeout: 30000 及 tools: ["*"] 的 XMemo 配置块。
• 本地代理路径：运行 xmemo setup copilot，并在后台终端保持运行 xmemo mcp proxy（参考 memory-os-cli 的 MCP-SETUP-GUIDE.md）。
• 请求头中直接展开环境变量（${env:XMEMO_KEY}）属于 not-tested 状态，Core 模板暂不提供支持。

# Local proxy path (recommended if direct remote HTTP is unsupported):
xmemo login
xmemo setup copilot
xmemo mcp proxy  # keep running in a background terminal

设置凭据

使用 Copilot 官方 MCP UI/CLI 或受支持的密钥引用设置 Authorization 请求头的值（将 <replace-with-XMEMO_KEY-or-supported-secret-reference> 替换为您真实的 Token）。使用本地代理时，xmemo login 会自动管理该凭据。

# For local proxy:
xmemo login
# For direct configuration, apply token through Copilot CLI or supported secret reference

生成 / 确认 XMEMO_AGENT_INSTANCE_ID

每个本地 Copilot CLI install 生成一个非机密值，将它保存在 git 外，并在重启后复用，使 attribution 保持稳定。

export XMEMO_AGENT_INSTANCE_ID='<stable-local-copilot-cli-instance-id>'
# Persist and reuse this value for the same local install

保留现有配置块

使用与 Core 模板（mcp_config.py:267）匹配的权威 Copilot CLI XMemo 配置块。通过 Copilot 官方 MCP UI/CLI 或受支持的密钥引用填入真实的 Authorization 值；请勿依赖未经检验的 ${env:XMEMO_KEY} 请求头展开。

{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "tools": [
        "*"
      ],
      "timeout": 30000,
      "headers": {
        "Authorization": "Bearer <replace-with-XMEMO_KEY-or-supported-secret-reference>",
        "X-Memory-OS-Agent-ID": "copilot-cli",
        "X-Memory-OS-Agent-Instance-ID": "<stable-local-copilot-cli-instance-id>"
      }
    }
  }
}

重启客户端

修改 mcp-config.json 后重启 Copilot CLI。如果使用本地代理，请在重启 Copilot CLI 前确保后台终端中的 'xmemo mcp proxy' 保持运行状态。

使用真实 recall call 测试

第一次 MCP call 应为只读。这是实际的 recall invocation，不是 health-check placeholder，也不会写入 memory。

recall({ query: "connection check", limit: 1 })

预期响应（literal shape）

成功调用会返回下面的公开 ranked text shape；reference 和 content 是来自已授权 memory space 的真实值。

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

常见错误

Copilot CLI 属于直接 Token 或代理型客户端；常见错误多与认证 Token、代理生命周期或权限范围授权相关。

• 401 invalid_token — XMEMO_KEY 缺失、已过期、已被撤销或未展开：检查当前生效的密钥引用，或为本地代理重新运行 xmemo login。
• 403 insufficient_scope — Token 未授予 memory:read 权限：请颁发包含必要权限范围的 Token。
• Connection refused — 若使用本地代理，请确认后台终端中的 xmemo mcp proxy 正常运行。
• 请求头中发送了字面量 '${env:XMEMO_KEY}' — Copilot CLI 可能不会展开请求头中的环境变量；请使用密钥引用或本地代理。
• 无效的 XMEMO_AGENT_INSTANCE_ID 值会被规范化为不附加实例归属，而不会触发认证错误。