Gemini提供者

Claude-mem 支持使用 Google 的 Gemini API 作为 Claude Agent SDK 提取会话观察结果的替代方案。这可以显著降低成本，因为 Gemini 提供了丰厚的免费额度。

免费层速率限制：在未启用计费的情况下，Gemini 有严格的速率限制（每分钟 5-10 次请求）。在您的 Google Cloud 项目中启用计费，即可解锁每分钟 1000-4000 次请求，同时仍可使用免费配额。

为什么使用Gemini？

• 成本节约：免费套餐涵盖大多数个人使用模式
• 相同的质量：Gemini 使用与 Claude 相同的 XML 格式提取观测数据
• 无缝回退：如果 Gemini 不可用，将自动回退到 Claude
• 热插拔：无需重新启动工作进程即可切换提供商

获取免费的 API 密钥

1. 前往 Google AI Studio API 密钥页面
2. 使用您的 Google 帐号登录
3. 接受服务条款和隐私政策
4. 点击 创建 API 密钥 按钮
5. 选择一个 Google Cloud 项目或创建一个新项目
6. 复制并安全存储生成的 API 密钥

无需计费即可开始，但我们建议启用计费以解锁更高的速率限制（1000-4000 RPM 对比 5-10 RPM），同时仍可使用免费配额。

配置

设置

设置	值	默认值	描述
CLAUDE_MEM_PROVIDER	claude，gemini	claude	用于观察提取的 AI 提供商
CLAUDE_MEM_GEMINI_API_KEY	字符串	—	您的 Gemini API 密钥
CLAUDE_MEM_GEMINI_MODEL	gemini-2.5-flash-lite，gemini-2.5-flash，gemini-3-flash-preview	gemini-2.5-flash-lite	要使用的Gemini模型
CLAUDE_MEM_GEMINI_BILLING_ENABLED	true, false	false	如果在 Google Cloud 上启用了计费，则跳过速率限制

使用设置界面

1. 在 http://localhost:37777 打开查看器
2. 点击齿轮图标以打开设置
3. 在AI 提供商下，选择Gemini
4. 输入您的 Gemini API 密钥
5. 可选择不同的模型

设置会立即生效——无需重启。

手动配置

编辑 ~/.claude-mem/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"
}

或者，通过环境变量设置 API 密钥：

设置文件优先于环境变量。

可用型号

模型	免费额度 RPM	备注
gemini-2.5-flash-lite	10	默认，推荐用于免费套餐（最高 RPM）
gemini-2.5-flash	5	更高的能力，更低的速率限制
gemini-3-flash-preview	5	最新型号，较低速率限制

提供商切换

你可以随时在Claude和Gemini之间切换：

• 无需重启：更改将在下次观察时生效
• 对话记录已保存：在会话中途切换时，新提供者可以看到完整的对话上下文
• 无缝过渡：两家供应商使用相同的观察格式

通过界面切换

1. 在查看器中打开设置
2. 更改 AI 提供商 下拉菜单
3. 下一次观察将使用新的提供者

通过设置文件切换

{
  "CLAUDE_MEM_PROVIDER": "gemini"
}

回退行为

如果选择了 Gemini 但遇到错误，claude-mem 会自动回退到 Claude Agent SDK：

触发回退：

• 速率限制（HTTP 429）
• 服务器错误（HTTP 5xx）
• 网络问题（连接被拒绝，超时）

不会触发回退:

• 缺少 API 密钥（记录警告，从一开始就使用 Claude）
• 无效的 API 密钥（错误导致失败）

当回退发生时：

1. 已记录警告
2. 任何正在进行的消息将被重置为待处理
3. Claude SDK 在完整的对话上下文中接管

故障排除

未配置 Gemini API 密钥

要么：

• 在 ~/.claude-mem/settings.json 中设置 CLAUDE_MEM_GEMINI_API_KEY，或者
• 设置 GEMINI_API_KEY 环境变量

速率限制

Google 对免费使用有两个速率限制级别：

无需计费（仅限 API 密钥）：

型号	转速(RPM)	转矩(TPM)
gemini-2.5-flash-lite	10	250K
Gemini-2.5-闪存	5	25万
Gemini-3-闪存预览	5	25万

Claude-mem 会自动通过请求之间的内置延迟来强制执行这些限制。处理可能会更慢，但会保持在限制范围内。

启用计费（仍然是免费套餐）：

型号	转速(RPM)	转矩(TPM)
Gemini-2.5-闪存精简版	4,000	4M
gemini-2.5-闪存	1,000	1M
Gemini-3-闪光-预览	1,000	1M

推荐：在您的 Google Cloud 项目中启用计费以解锁更高的速率限制。除非超出慷慨的免费额度，否则不会产生费用。这允许 claude-mem 即时处理观察结果，而无需在请求之间等待。

如果你达到速率限制：

• Claude-mem 会自动回退到 Claude SDK
• 或者切换回 Claude 作为您的主要提供者

观察质量

如果使用Gemini观测时观测质量似乎较低：

• 请注意，Claude 通常会产生略高质量的观察结果
• 考虑使用 Gemini 来节省成本，并在重要项目中使用 Claude

下一步

• Configuration - 完整设置参考
• 入门 - 基本使用指南
• 故障排除 - 常见问题