> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claude-mem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini Provider

> Use Google's Gemini API as an alternative to Claude for observation extraction

# Gemini Provider

Claude-mem supports Google's Gemini API as an alternative to the Claude Agent SDK for extracting observations from your sessions. This can significantly reduce costs since Gemini offers a generous free tier.

<Warning>
  **Free Tier Rate Limits**: Without billing enabled, Gemini has strict rate limits (5-10 RPM). Enable billing on your Google Cloud project to unlock 1000-4000 RPM while still using the free quota.
</Warning>

## Why Use Gemini?

* **Cost savings**: The free tier covers most individual usage patterns
* **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 a Free API Key

1. Go to the [Google AI Studio API Key page](https://aistudio.google.com/app/apikey)
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

<Tip>
  **No billing required** to get started, but we recommend enabling billing to unlock higher rate limits (1000-4000 RPM vs 5-10 RPM) while still using the free quota.
</Tip>

## Configuration

### Settings

| Setting                             | Values                                                                | Default                 | Description                                              |
| ----------------------------------- | --------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------- |
| `CLAUDE_MEM_PROVIDER`               | `claude`, `gemini`                                                    | `claude`                | AI provider for observation extraction                   |
| `CLAUDE_MEM_GEMINI_API_KEY`         | string                                                                | —                       | Your Gemini API key                                      |
| `CLAUDE_MEM_GEMINI_MODEL`           | `gemini-2.5-flash-lite`, `gemini-2.5-flash`, `gemini-3-flash-preview` | `gemini-2.5-flash-lite` | Gemini model to use                                      |
| `CLAUDE_MEM_GEMINI_BILLING_ENABLED` | `true`, `false`                                                       | `false`                 | Skip rate limiting if billing is enabled on Google Cloud |

### Using the Settings UI

1. Open the viewer at [http://localhost:37777](http://localhost:37777)
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`:

```json theme={null}
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "your-api-key-here",
  "CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash-lite",
  "CLAUDE_MEM_GEMINI_BILLING_ENABLED": "true"
}
```

Alternatively, set the API key via environment variable:

```bash theme={null}
export GEMINI_API_KEY="your-api-key-here"
```

The settings file takes precedence over the environment variable.

## Available Models

| Model                    | Free Tier RPM | Notes                                            |
| ------------------------ | ------------- | ------------------------------------------------ |
| `gemini-2.5-flash-lite`  | 10            | Default, recommended for free tier (highest RPM) |
| `gemini-2.5-flash`       | 5             | Higher capability, lower rate limit              |
| `gemini-3-flash-preview` | 5             | Latest model, lower rate limit                   |

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

```json theme={null}
{
  "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 has two rate limit tiers for free usage:

**Without billing (API key only):**

| Model                  | RPM | TPM  |
| ---------------------- | --- | ---- |
| gemini-2.5-flash-lite  | 10  | 250K |
| gemini-2.5-flash       | 5   | 250K |
| gemini-3-flash-preview | 5   | 250K |

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

**With billing enabled (still free tier):**

| Model                  | RPM   | TPM |
| ---------------------- | ----- | --- |
| gemini-2.5-flash-lite  | 4,000 | 4M  |
| gemini-2.5-flash       | 1,000 | 1M  |
| gemini-3-flash-preview | 1,000 | 1M  |

<Tip>
  **Recommended**: Enable billing on your Google Cloud project to unlock much higher rate limits. You won't be charged unless you exceed the generous free quota. This allows claude-mem to process observations instantly instead of waiting between requests.
</Tip>

If you hit rate limits:

* Claude-mem automatically falls back to Claude SDK
* 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 for cost savings and Claude for important projects

## Next Steps

* [Configuration](/configuration) - Full settings reference
* [Getting Started](/usage/getting-started) - Basic usage guide
* [Troubleshooting](/troubleshooting) - Common issues