Gemini Provider

Claude-mem supports Google's Gemini API as an alternative to the Claude Agent SDK for extracting observations from your sessions. Memory runs off-plan on your Gemini key, so observation extraction never shares your Claude plan usage.

Why Use Gemini?

• Runs off-plan: Observation extraction happens on your Gemini key, not your Claude plan
• Same quality: Gemini extracts observations using the same XML format as Claude
• Errors throw clearly: 429s, 5xx, and network failures throw — leaving messages pending so they can be retried
• Hot-swappable: Switch providers without restarting the worker

Getting an API Key

1. Go to the Google AI Studio API Key page
2. Sign in with your Google account
3. Accept the Terms of Service and privacy policies
4. Click the Create API key button
5. Choose a Google Cloud project or create a new one
6. Copy and securely store the generated API key

Configuration

Settings

Using the Settings UI

1. Open the worker URL printed on startup
2. Click the gear icon to open Settings
3. Under AI Provider, select Gemini
4. Enter your Gemini API key
5. Optionally select a different model

Settings are applied immediately—no restart required.

Manual Configuration

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "your-api-key-here",
  "CLAUDE_MEM_GEMINI_MODEL": "gemini-flash-latest",
  "CLAUDE_MEM_GEMINI_BILLING_ENABLED": "true"
}

Alternatively, set the API key via environment variable:

export GEMINI_API_KEY="your-api-key-here"

The settings file takes precedence over the environment variable.

Available Models

Provider Switching

You can switch between Claude and Gemini at any time:

• No restart required: Changes take effect on the next observation
• Conversation history preserved: When switching mid-session, the new provider sees the full conversation context
• Seamless transition: Both providers use the same observation format

Switching via UI

1. Open Settings in the viewer
2. Change the AI Provider dropdown
3. The next observation will use the new provider

Switching via Settings File

{
  "CLAUDE_MEM_PROVIDER": "gemini"
}

Error Behavior

If Gemini is selected and the API errors, claude-mem logs the failure and re-throws so the message stays pending for later retry. There is no Claude SDK fallback — earlier docs claimed automatic Claude fallback, but the wiring was never actually engaged in production (#2087). To switch providers, change CLAUDE_MEM_PROVIDER in settings.

Throwing conditions:

• Rate limiting (HTTP 429)
• Server errors (HTTP 5xx)
• Network issues (connection refused, timeout)
• 4xx errors other than 429
• Missing API key

Troubleshooting

"Gemini API key not configured"

Either:

• Set CLAUDE_MEM_GEMINI_API_KEY in ~/.claude-mem/settings.json, or
• Set the GEMINI_API_KEY environment variable

Rate Limiting

Google applies different rate limits depending on whether billing is enabled:

Without billing (API key only):

Claude-mem enforces these limits automatically with built-in delays between requests. Processing may be slower but stays within limits.

With billing enabled:

If you hit rate limits:

• The failed message remains pending and can be retried after the rate limit resets
• Or switch back to Claude as your primary provider

Observation Quality

If observations seem lower quality with Gemini:

• Note that Claude typically produces slightly higher quality observations
• Consider using Gemini to keep memory off-plan and Claude for important projects

Next Steps

• Configuration - Full settings reference
• Getting Started - Basic usage guide
• Troubleshooting - Common issues