Gemini CLI

Prerequisite

Use Gemini CLI developer tooling with its reviewed settings.json MCP configuration and browser OAuth support. Support applies to the Gemini CLI developer tool and does not imply integration into Gemini consumer web chat (gemini.google.com) or official extension gallery approval.

• Endpoint: https://xmemo.dev/mcp.
• Auth mode: OAuth.
• Config file: ~/.gemini/settings.json.
• Transport: Streamable HTTP (httpUrl for the hosted endpoint).
• Extension repository: github:yonro/xmemo-gemini-cli (manifest 0.1.0; documented GitHub installation, no official-gallery approval inferred).

Install / setup

Install the extension using the Gemini CLI extensions command, or manually merge the XMemo configuration block into ~/.gemini/settings.json under mcpServers.

• Extension command: gemini extensions install https://github.com/yonro/xmemo-gemini-cli (anchored to yonro/xmemo-gemini-cli @ 39e25b185b README).
• Manual fallback: merge the XMemo block into ~/.gemini/settings.json, preserving httpUrl and identity headers.

gemini extensions install https://github.com/yonro/xmemo-gemini-cli

Set the credential

No key — complete browser OAuth after restarting Gemini CLI. Do not put XMEMO_KEY or an Authorization header in settings.json.

No XMEMO_KEY
Complete browser OAuth in Gemini CLI

Generate / confirm XMEMO_AGENT_INSTANCE_ID

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

export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'

Preserve the existing config block

Use the existing Gemini CLI XMemo configuration block rendered on this page. Preserve httpUrl and the non-secret identity headers; do not add Authorization or XMEMO_KEY.

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

Restart the client

Restart Gemini CLI after saving settings.json so it loads the endpoint and the current instance identity, then complete the OAuth consent.

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

Gemini CLI OAuth failures use the hosted OAuth error contract.

• invalid_grant — the OAuth authorization code is invalid, expired, or already used: reconnect Gemini CLI and authorize again.
• invalid_target — the OAuth resource does not match this MCP server: use https://xmemo.dev/mcp and reconnect.
• 403 insufficient_scope — the grant does not include memory:read: approve the required scope and reconnect.