Skip to main content

​
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.
Rate limits without billing: Gemini applies model-specific limits to projects without billing. Enable billing on your Google Cloud project for higher limits, and review Google’s current quota and billing terms before doing so.

​
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
No billing required to get started. Enabling billing can unlock higher rate limits; review Google’s current quota and billing terms first.

​
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:
Alternatively, set the API key via environment variable:
The settings file takes precedence over the environment variable.

​
Available Models

The older gemini-2.5-* and gemini-2.0-* model IDs were removed: Google returns 404 NOT_FOUND (“no longer available to new users”) for these when called with a freshly created API key. The -latest aliases are recommended because they never go stale as Google rotates GA 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

​
Error Behavior

When Gemini refuses a request, queued observations stay pending; what happens next depends on the refusal:
  • Per-minute throttle (a 429 whose quota is per minute): claude-mem waits the delay Google names and resumes. If the throttle keeps refusing, Gemini is held for 90 seconds.
  • Spent daily (or weekly, monthly) quota (a 429 naming a per-day quota): Gemini is held for 30 minutes, then one request checks whether the quota has reset.
  • Region not served (“User location is not supported”): capture pauses with the work kept, and the next session start says to switch providers. Gemini is re-checked once every 30 minutes. Extra keys are not tried, since every key gets the same answer.
  • Invalid or revoked key: with extra keys configured, the next key is tried; otherwise the same pause, and the notice says to fix the key.
  • Server errors and network faults: paused with the work kept, then resumed automatically on a backoff.
  • Other malformed requests (HTTP 400): that session’s pending observations are dropped. A request too long for the model’s window retires the conversation instead and keeps them.
To keep capturing while Gemini is held, configure a quota fallback (opt-in, off by default). Extra keys rotate within Gemini (Multi-Key Rotation). To switch providers for good, change CLAUDE_MEM_PROVIDER.

​
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:
Higher throughput: Enabling billing can unlock much higher rate limits. Review your Google Cloud quota and billing settings first. Claude-mem can then use the higher configured limits instead of its conservative no-billing throttle.
If you hit rate limits:
  • The pending observations stay queued and resume when the limit resets (see Error Behavior)
  • Or configure a quota fallback, 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

​
Multiple keys

CLAUDE_MEM_GEMINI_API_KEYS accepts additional keys (newline- or comma-separated) alongside CLAUDE_MEM_GEMINI_API_KEY. When a key hits a rate limit, spends its quota, or is rejected as invalid, Gemini requests rotate to the next key instead of failing for the rest of the window. See Multi-Key Rotation.