Skip to main content
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.
Free tier rate limits: Without billing enabled, Gemini enforces strict rate limits (5–10 RPM). Enable billing on your Google Cloud project to unlock 1,000–4,000 RPM while still using the free quota.

​
Why use Gemini?

Cost savings

The free tier covers most individual usage patterns with no credit card required to get started.

Same observation quality

Gemini extracts observations using the same XML format as Claude, so output is compatible throughout.

Seamless fallback

Automatically falls back to Claude if Gemini is unavailable due to rate limiting or errors.

Hot-swappable

Switch providers without restarting the worker. Changes take effect on the next observation.

​
Getting a free API key

1

Open Google AI Studio

Go to the Google AI Studio API Key page and sign in with your Google account.
2

Accept terms

Accept the Terms of Service and privacy policies when prompted.
3

Create the key

Click Create API key, then choose an existing Google Cloud project or create a new one.
4

Copy and store your key

Copy the generated API key and store it somewhere secure — you won’t be able to view it again.
No billing is required to get started. Enable billing on your Google Cloud project to unlock much higher rate limits (1,000–4,000 RPM vs. 5–10 RPM) while remaining within the free quota.

​
Available models

ModelFree tier RPMNotes
gemini-2.5-flash-lite10Default — recommended for free tier (highest RPM)
gemini-2.5-flash5Higher capability, lower rate limit
gemini-3-flash-preview5Latest model, lower rate limit

​
Rate limits with billing enabled

Enabling billing on your Google Cloud project does not incur charges within the free quota but dramatically raises rate limits:
ModelRPMTPM
gemini-2.5-flash-lite4,0004M
gemini-2.5-flash1,0001M
gemini-3-flash-preview1,0001M

​
Configuration

​
Settings reference

​
CLAUDE_MEM_PROVIDER
string
default:"claude"
AI provider for observation extraction. Set to gemini to use the Gemini API.
​
CLAUDE_MEM_GEMINI_API_KEY
string
Your Gemini API key. Takes precedence over the GEMINI_API_KEY environment variable.
​
CLAUDE_MEM_GEMINI_MODEL
string
default:"gemini-2.5-flash-lite"
Gemini model to use. Supported values: gemini-2.5-flash-lite, gemini-2.5-flash, gemini-3-flash-preview.
​
CLAUDE_MEM_GEMINI_BILLING_ENABLED
boolean
default:"false"
Set to true to skip built-in rate-limit delays when billing is enabled on your Google Cloud project.

​
Using the settings UI

1

Open the viewer

Go to http://localhost:37777 and click the gear icon to open Settings.
2

Select Gemini

Under AI Provider, select Gemini from the dropdown.
3

Enter your API key

Paste your Gemini API key into the Gemini API Key field.
4

Choose a model (optional)

Select a model from the dropdown. gemini-2.5-flash-lite is recommended for the free tier.
Settings are applied immediately — no restart required.

​
Manual configuration

Edit ~/.claude-mem/settings.json:
settings.json
{
  "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: 
export GEMINI_API_KEY="your-api-key-here"
The settings file takes precedence over the GEMINI_API_KEY environment variable.

​
Switching providers

You can switch between Claude and Gemini at any time.
1

Open Settings

Open the viewer at http://localhost:37777 and click the gear icon.
2

Change provider

Change the AI Provider dropdown to Gemini (or back to Claude).
3

Observe the change

The next observation will use the new provider. No restart is needed.
  • 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.

​
Fallback behavior

If Gemini encounters errors, Claude Mem automatically falls back to the Claude Agent SDK.
  • Rate limiting (HTTP 429)
  • Server errors (HTTP 5xx)
  • Network issues (connection refused, timeout)
When fallback occurs, a warning is logged, any in-progress messages are reset to pending, and the Claude SDK takes over with the full conversation context.
  • Missing API key: Logs a warning and uses Claude from the start (no mid-session switch).
  • Invalid API key: Fails with an error rather than silently switching.

​
Troubleshooting

You need to supply the API key in one of two ways:
  • Set CLAUDE_MEM_GEMINI_API_KEY in ~/.claude-mem/settings.json, or
  • Set the GEMINI_API_KEY environment variable
The settings file takes precedence if both are present.
Without billing enabled, Claude Mem enforces built-in delays between requests to stay within the free quota. Processing may be slower but remains within limits.To resolve rate limiting:
  • Enable billing on your Google Cloud project and set CLAUDE_MEM_GEMINI_BILLING_ENABLED to true
  • Switch to gemini-2.5-flash-lite, which has the highest free RPM (10 RPM)
  • Fall back to Claude as your primary provider while Gemini recovers
Claude Mem automatically falls back to the Claude SDK when a 429 rate limit response is received.
Claude typically produces slightly higher quality observations than Gemini. If observation quality is important for a specific project, consider using Claude as the provider for that work and Gemini for lower-stakes sessions where cost savings matter more.

​
Next steps

OpenRouter provider

Access 100+ models through OpenRouter’s unified API, including several free options.

Configuration reference

Full settings reference for all Claude Mem configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us