​

OpenRouter Provider

​

Why Use OpenRouter?

• Access to 100+ models: Choose from models across multiple providers through one API
• Free tier options: Several high-quality models are completely free to use
• Cost flexibility: Pay-as-you-go pricing on premium models with no commitments
• Seamless fallback: Automatically falls back to Claude if OpenRouter is unavailable
• Hot-swappable: Switch providers without restarting the worker
• Multi-turn conversations: Full conversation history maintained across API calls

​

Free Models on OpenRouter

​

Featured Free Models

​

Free Model Considerations

• Rate limits: Free models may have stricter rate limits than paid models
• Availability: Free capacity depends on provider partnerships and demand
• Queue times: During peak usage, requests may be queued briefly
• Max tokens: Most free models support 65,536 completion tokens

• Tool use and function calling
• Temperature and sampling controls
• Stop sequences
• Streaming responses

​

Getting an API Key

1. Go to OpenRouter
2. Sign in with Google, GitHub, or email
3. Navigate to API Keys
4. Click Create Key
5. Copy and securely store your API key

​

Configuration

​

Settings

​

Using the Settings UI

1. Open the viewer at http://localhost:37777
2. Click the gear icon to open Settings
3. Under AI Provider, select OpenRouter
4. Enter your OpenRouter API key
5. Optionally select a different model

​

Manual Configuration

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": "xiaomi/mimo-v2-flash:free"
}

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"

​

Model Selection Guide

​

For Free Usage (No Cost)

• Best-in-class performance on coding benchmarks
• 256K context window handles large observations
• 65K max completion tokens
• Mixture-of-experts architecture (15B active parameters)

• google/gemini-2.0-flash-exp:free - 1M context, Google’s flagship
• deepseek/deepseek-r1:free - Excellent reasoning capabilities
• meta-llama/llama-3.1-70b-instruct:free - Strong general purpose

​

For Paid Usage (Higher Quality/Speed)

​

Context Window Management

​

Automatic Truncation

1. Checks if message count exceeds MAX_CONTEXT_MESSAGES (default: 20)
2. Checks if estimated tokens exceed MAX_TOKENS (default: 100,000)
3. If limits exceeded, keeps most recent messages only
4. Logs warnings with dropped message counts

​

Token Estimation

• Conservative estimate: 1 token ≈ 4 characters
• Used for proactive context management
• Actual usage logged from API response

​

Cost Tracking

OpenRouter API usage: {
  model: "xiaomi/mimo-v2-flash:free",
  inputTokens: 2500,
  outputTokens: 1200,
  totalTokens: 3700,
  estimatedCostUSD: "0.00",
  messagesInContext: 8
}

​

Provider Switching

• 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: All 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

{
  "CLAUDE_MEM_PROVIDER": "openrouter"
}

​

Fallback Behavior

• Rate limiting (HTTP 429)
• Server errors (HTTP 500, 502, 503)
• Network issues (connection refused, timeout)
• Generic fetch failures

• Missing API key (logs warning, uses Claude from start)
• Invalid API key (fails with error)

1. A warning is logged
2. Any in-progress messages are reset to pending
3. Claude SDK takes over with the full conversation context

​

Multi-Turn Conversation Support

Session Created
  ↓
Load Pending Messages (observations from queue)
  ↓
For each message:
  → Add to conversation history
  → Call OpenRouter API with FULL history
  → Parse XML response
  → Store observations in database
  → Sync to Chroma vector DB
  ↓
Session complete

• Coherent multi-turn exchanges
• Context preservation across observations
• Seamless provider switching mid-session

​

Troubleshooting

​

”OpenRouter API key not configured”

• Set CLAUDE_MEM_OPENROUTER_API_KEY in ~/.claude-mem/settings.json, or
• Set the OPENROUTER_API_KEY environment variable

​

Rate Limiting

• Claude-mem automatically falls back to Claude SDK
• Consider switching to a different free model
• Add credits for premium model access

​

Model Not Found

• Check OpenRouter Models for current availability
• Use the :free suffix for free model variants
• Model IDs are case-sensitive

​

High Token Usage Warning

• Reduce CLAUDE_MEM_OPENROUTER_MAX_CONTEXT_MESSAGES
• Reduce CLAUDE_MEM_OPENROUTER_MAX_TOKENS
• Consider a model with larger context window

​

Connection Errors

• Check your internet connection
• Verify OpenRouter service status at status.openrouter.ai
• The agent will automatically fall back to Claude

​

API Details

Authorization: Bearer {apiKey}
HTTP-Referer: https://github.com/thedotmack/claude-mem
X-Title: claude-mem
Content-Type: application/json

{
  "model": "xiaomi/mimo-v2-flash:free",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "temperature": 0.3,
  "max_tokens": 4096
}

​

Comparing Providers

​

Next Steps

• Configuration - Full settings reference
• Gemini Provider - Alternative free provider
• Getting Started - Basic usage guide
• Troubleshooting - Common issues