Copilot CLI

Prerequisite

Use GitHub Copilot CLI with its MCP configuration support. This route is intentionally separate from the VS Code / GitHub Copilot Chat OAuth route. Copilot CLI supports custom HTTP headers in ~/.copilot/mcp-config.json, or local proxy connectivity via memory-os-cli.

• Endpoint: https://xmemo.dev/mcp.
• Transport: Streamable HTTP (type: "http" in config) or local proxy (xmemo mcp proxy).
• Auth mode: apply Authorization through Copilot's official MCP UI/CLI or a supported secret reference; do not assume environment variable expansion (${env:…}) in header values.
• Config file: ~/.copilot/mcp-config.json.
• Readiness status: Direct environment variable expansion in Copilot CLI headers is not-tested; local proxy path is verified via memory-os-cli MCP-SETUP-GUIDE.md.

Install / setup

Add the XMemo server block to ~/.copilot/mcp-config.json under mcpServers, or run through the memory-os-cli local proxy. Do not reuse the VS Code servers-key entry; Copilot CLI is a different client path.

• Direct remote HTTP: add the XMemo block to ~/.copilot/mcp-config.json with type: "http", url: "https://xmemo.dev/mcp", timeout: 30000, and tools: ["*"].
• Local proxy path: run xmemo setup copilot and keep xmemo mcp proxy running in a background terminal (anchored to memory-os-cli MCP-SETUP-GUIDE.md).
• Direct environment variable expansion in headers (${env:XMEMO_KEY}) is not-tested and unsupported by Core templates.

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

Set the credential

Set the Authorization header value using Copilot's official MCP UI/CLI or a supported secret reference (replacing <replace-with-XMEMO_KEY-or-supported-secret-reference> with your actual token). When using the local proxy, xmemo login manages the credential automatically.

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

Generate / confirm XMEMO_AGENT_INSTANCE_ID

Generate one non-secret value per local Copilot CLI install, persist it outside git, and reuse it after restarts so attribution stays stable.

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

Preserve the existing config block

Use the authoritative Copilot CLI XMemo configuration block matching Core's template (mcp_config.py:267). Apply the real Authorization value through Copilot's official MCP UI/CLI or a supported secret reference; do not rely on unverified ${env:XMEMO_KEY} header expansion.

{
  "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>"
      }
    }
  }
}

Restart the client

Restart Copilot CLI after changing mcp-config.json. If using the local proxy, ensure 'xmemo mcp proxy' remains running in a background terminal before restarting Copilot CLI.

Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

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

Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

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

Common Errors

Copilot CLI is a direct token or proxy client; common errors relate to authentication tokens, proxy lifecycle, or scope approval.

• 401 invalid_token — XMEMO_KEY is missing, expired, revoked, or unexpanded: verify the active secret reference or re-run xmemo login for the local proxy.
• 403 insufficient_scope — the token does not grant memory:read: issue a token with the required scope.
• Connection refused — if using local proxy, verify xmemo mcp proxy is running in a background terminal.
• Literal '${env:XMEMO_KEY}' sent in header — Copilot CLI may not expand environment variables in header values; use the secret reference or local proxy.
• Invalid XMEMO_AGENT_INSTANCE_ID values are normalized to no instance attribution rather than raising an auth error.