Gemini & OpenRouter Integrations

Relevant source files

The following files were used as context for generating this wiki page:

• src/services/worker/GeminiAgent.ts
• src/services/worker/http/routes/SettingsRoutes.ts
• src/services/worker/README.md
• CLAUDE.md
• src/servers/mcp-server.ts
• README.md

The Gemini and OpenRouter integrations provide alternative AI provider support for the claude-mem worker service. While the project is primarily designed for Claude Code, these integrations allow the system to leverage Google's Gemini API and the OpenRouter aggregator for processing observations and summaries. This multi-provider architecture ensures resilience through fallback mechanisms and provides flexibility in model selection for memory compression tasks.

The system uses these providers to extract observations from tool usage and generate session summaries, which are then stored in a SQLite database and synchronized with a Chroma vector database for semantic search.

Sources: src/services/worker/GeminiAgent.ts:11-20, CLAUDE.md:10-15, src/services/worker/README.md:14-25

Gemini Integration Architecture

The GeminiAgent serves as a direct alternative to the SDKAgent (Claude-based). It interacts with the Google Generative Language API using multi-turn conversations to maintain context across a session.

Core Components and Logic

• Rate Limiting: Implements a Requests Per Minute (RPM) enforcement mechanism for Gemini free tier models to avoid 429 errors.
• Multi-Turn Conversation: Converts internal ConversationMessage structures into Gemini's specific contents format (mapping "assistant" role to "model").
• Fallback Mechanism: If the Gemini API encounters transient errors (429, 5xx, or network timeouts), the agent can trigger a fallback to the Claude-based agent to ensure processing continuity.

The flow illustrates how the GeminiAgent handles requests, enforces limits, and manages failures via fallback logic.

Sources: src/services/worker/GeminiAgent.ts:40-66, src/services/worker/GeminiAgent.ts:153-180, src/services/worker/GeminiAgent.ts:257-278

Configuration Parameters

Gemini is configured via ~/.claude-mem/settings.json or environment variables.

Setting Key	Type	Description	Default
CLAUDE_MEM_GEMINI_API_KEY	string	API key for Google Gemini	N/A
CLAUDE_MEM_GEMINI_MODEL	string	Model name (e.g., gemini-2.0-flash)	gemini-2.5-flash
CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED	boolean	Enables RPM safety buffer	true

Sources: src/services/worker/GeminiAgent.ts:391-419, src/services/worker/http/routes/SettingsRoutes.ts:100-110

OpenRouter Integration

OpenRouter is integrated as a secondary provider, managed through the SettingsRoutes. It allows the worker to utilize a broad range of models via the OpenRouter unified API.

Configuration and Validation

OpenRouter settings include site-specific metadata to identify the application to the OpenRouter platform, as well as token limit configurations.

The diagram shows the validation and storage flow for OpenRouter settings within the worker service.

Sources: src/services/worker/http/routes/SettingsRoutes.ts:111-120, src/services/worker/http/routes/SettingsRoutes.ts:275-300

Key OpenRouter Settings

Setting Key	Description
CLAUDE_MEM_OPENROUTER_API_KEY	API Key for OpenRouter.ai
CLAUDE_MEM_OPENROUTER_MODEL	Target model slug on OpenRouter
CLAUDE_MEM_OPENROUTER_SITE_URL	Metadata for OpenRouter rankings
CLAUDE_MEM_OPENROUTER_MAX_TOKENS	Hard limit on response length (1k - 1M)

Sources: src/services/worker/http/routes/SettingsRoutes.ts:111-120, src/services/worker/http/routes/SettingsRoutes.ts:322-337

Data Flow and XML Parsing

Regardless of the provider (Gemini or OpenRouter), the system expects a specific XML format in the AI's response to extract structured data. This format is shared with the primary Claude integration to ensure compatibility with the DatabaseManager and ChromaSync.

Processing Pipeline

1. Prompt Construction: Uses buildObservationPrompt or buildSummaryPrompt to generate provider-agnostic instructions.
2. AI Query: Sends the prompt to the configured provider API.
3. Parsing: Uses parseObservations and parseSummary to extract XML blocks.
4. Persistence:
   • storeObservation: Saves to SQLite.
   • syncObservation: Generates embeddings and saves to Chroma.
   • SSEBroadcaster: Sends real-time updates to the web viewer.

Sources: src/services/worker/GeminiAgent.ts:100-140, src/services/worker/GeminiAgent.ts:285-320, src/services/worker/GeminiAgent.ts:335-360

Provider Selection Logic

The worker determines which agent to instantiate based on the CLAUDE_MEM_PROVIDER setting. If "gemini" is selected, the isGeminiSelected() helper returns true, and the worker initiates the session using the GeminiAgent.

// Provider check in GeminiAgent.ts
export function isGeminiSelected(): boolean {
  const settingsPath = path.join(homedir(), '.claude-mem', 'settings.json');
  const settings = SettingsDefaultsManager.loadFromFile(settingsPath);
  return settings.CLAUDE_MEM_PROVIDER === 'gemini';
}

Sources: src/services/worker/GeminiAgent.ts:430-435, src/services/worker/http/routes/SettingsRoutes.ts:248-255

Conclusion

The Gemini and OpenRouter integrations extend claude-mem beyond the Anthropic ecosystem, providing users with options for cost-effective or high-performance memory processing. By implementing provider-specific agents like GeminiAgent while maintaining a unified XML-based data extraction layer, the system ensures that project continuity and semantic search remain consistent regardless of the underlying LLM provider.