# Gemini CLI

Use the OAuth-first Gemini CLI configuration without placing bearer credentials in settings.json.

- Canonical: https://docs.xmemo.dev/docs/mcp/gemini
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: ce76e9d3792acedbd7c9286f7b98644f341e3ae563f666ae260df60677528c37
- Edition-Digest: db4c926bc9d673f8bdd8c85fd6fcbd73893ab9f2e4665f1b79ccad1c0314f711
- Source-Revision: sha256:f763a6aaa1fe7cb2187c347ac0b10d146c4895bada5a02c7a5fe27fb486ce99f

## Prerequisite

Use Gemini CLI with its reviewed settings.json MCP configuration and browser OAuth support.

- Endpoint: https://xmemo.dev/mcp.
- Auth mode: OAuth.
- Config file: ~/.gemini/settings.json.
- Use httpUrl for the hosted endpoint.

## Install / setup

Merge the existing XMemo block into ~/.gemini/settings.json, preserving its httpUrl and identity-header keys.

## Set the credential

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

```text
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.

```bash
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.

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

```text
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.

```text
### 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.

## Gemini CLI

OAuth client: merge this XMemo block into settings.json, set one stable XMEMO_AGENT_INSTANCE_ID for local attribution, then restart Gemini CLI and complete MCP OAuth. Do not add Authorization or XMEMO_KEY to this snippet.

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