Gemini 提供商¶

Claude-mem 支持 Google 的 Gemini API，作为 Claude Agent SDK 的替代方案，用于从会话中提取观察结果。记忆在你的 Gemini 密钥上运行，不计入你的 Claude 套餐；因此观察提取永远不会占用你的 Claude 套餐用量。

为什么使用 Gemini？¶

• 套餐外运行：观察提取发生在你的 Gemini 密钥上，而不是你的 Claude 套餐中
• 相同质量：Gemini 使用与 Claude 相同的 XML 格式提取观察结果
• 错误清晰抛出：429、5xx 和网络故障会抛出错误——使消息保持待处理状态，以便可以重试
• 热切换：无需重启 worker 即可切换提供商

获取 API 密钥¶

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

配置¶

设置¶

使用设置界面¶

1. 打开启动时打印的 worker URL
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-flash-latest",
  "CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED": "true"
}

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

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

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

可用模型¶

切换提供商¶

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

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

通过界面切换¶

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

通过设置文件切换¶

{
  "CLAUDE_MEM_PROVIDER": "gemini"
}

错误行为¶

当 Gemini 拒绝请求时，已排队的观察保持待处理状态；接下来会发生什么取决于拒绝的原因：

• 每分钟限流（配额按分钟计算的 429）：claude-mem 会等待 Google 指定的延迟，然后恢复。如果限流持续拒绝，Gemini 将被暂停 90 秒。
• 日（或周、月）配额已用完（提到按日配额的 429）：Gemini 将被暂停 30 分钟，然后发送一个请求检查配额是否已重置。
• 区域不受支持（“User location is not supported”）：捕获暂停，但保留已有工作，下次会话启动时会提示切换提供商。Gemini 每 30 分钟重新检查一次。不会尝试额外密钥，因为每个密钥都会得到相同的答复。
• 密钥无效或已被吊销：如果配置了额外密钥，则尝试下一个密钥；否则同样暂停，并会在提示中说明需要修复该密钥。
• 服务器错误和网络故障：暂停并保留已有工作，然后在退避后自动恢复。
• 其他格式错误的请求（HTTP 400）：该会话的待处理观察将被丢弃。如果请求对模型的上下文窗口来说过长，则会改为终止该会话的对话并保留这些观察。

要在 Gemini 被暂停期间继续捕获，请配置 配额回退（可选加入，默认关闭）。额外密钥在 Gemini 内部轮换（多密钥轮换）。要永久切换提供商，请更改 CLAUDE_MEM_PROVIDER。

故障排除¶

“Gemini API 密钥未配置”¶

可以这样做：

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

速率限制¶

Google 会根据是否启用结算而应用不同的速率限制：

无计费（仅 API 密钥）：

Claude-mem 会自动执行这些限制，并在请求之间加入内置延迟。处理速度可能会较慢，但会保持在限制范围内。

启用计费后：

如果遇到速率限制： - 待处理的观察记录会保持排队状态，并在限制重置后继续处理（参见错误行为） - 或者配置配额回退，或切换回 Claude 作为主要提供商

观察记录质量¶

如果使用 Gemini 时观察记录质量较低： - 请注意，Claude 通常能生成略高质量的观察记录 - 可以考虑使用 Gemini 处理计划外的记忆任务，而将 Claude 用于重要项目

后续步骤¶

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

多个密钥¶

CLAUDE_MEM_GEMINI_API_KEYS 接受额外的密钥（以换行符或逗号分隔），与 CLAUDE_MEM_GEMINI_API_KEY 配合使用。当某个密钥达到速率限制、配额用尽或被判定为无效时，Gemini 请求会轮换到下一个密钥，而不是在当前时间窗口的剩余时间内持续失败。参见多密钥轮换。