Use the OAuth-first Gemini CLI configuration without placing bearer credentials in settings.json.
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.
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.
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.