OpenRouter Provider

Claude-mem supports OpenRouter as an alternative provider for observation extraction. OpenRouter provides a unified API to access 100+ models from different providers including Google, Meta, Mistral, DeepSeek, and many others.

Memory runs off-plan: With OpenRouter (or the claude-mem observer, which runs on this provider), observation extraction happens off your Claude plan — so memory work never shares your plan usage.

claude-mem observer: When you sign in during npx claude-mem install and choose the claude-mem observer, claude-mem configures this provider for you automatically with a provisioned key — no manual setup needed. The rest of this page covers bringing your own OpenRouter key.

Why Use OpenRouter?

Runs off-plan: Observation extraction never shares your Claude plan usage
Access to 100+ models: Choose from models across multiple providers through one API
Free model options: Several high-quality models are available at no charge
Errors throw clearly: 429s, 5xx, and network failures throw — leaving messages pending so they can be retried
Hot-swappable: Switch providers without restarting the worker
Multi-turn conversations: Full conversation history maintained across API calls

Free Models on OpenRouter

OpenRouter actively supports democratizing AI access by offering free models. These are production-ready models suitable for observation extraction.

Featured Free Models

Model	ID	Parameters	Context	Best For
Cohere North Mini Code	`cohere/north-mini-code:free`	30B (3B active, MoE)	256K	Default; agentic coding
Poolside Laguna XS 2.1	`poolside/laguna-xs-2.1:free`	33B (3B active, MoE)	256K	Coding agents
NVIDIA Nemotron 3 Ultra	`nvidia/nemotron-3-ultra-550b-a55b:free`	550B (55B active, MoE)	1M	Reasoning, orchestration

Default Model: Claude-mem uses cohere/north-mini-code:free by default, a sparse mixture-of-experts coding model with a 256K context window.

Free Model Considerations

Rate limits: Free models may have stricter rate limits than paid models
Availability: Free capacity depends on provider partnerships and demand
Retirement: OpenRouter retires free model ids regularly. If the default is retired, claude-mem moves stored settings off it automatically. If a model you picked is retired, the observer reports “OpenRouter model unavailable” (see Troubleshooting)
Queue times: During peak usage, requests may be queued briefly
Max tokens: Most free models support 65,536 completion tokens

All free models support:

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

Getting an API Key

Go to OpenRouter
Sign in with Google, GitHub, or email
Navigate to API Keys
Click Create Key
Copy and securely store your API key

Free to start: No credit card required to create an account or use free models. Add credits only if you want to use premium models.

Configuration

Settings

Setting	Values	Default	Description
`CLAUDE_MEM_PROVIDER`	`claude`, `codex`, `gemini`, `openrouter`, `openai-compatible`	`claude`	AI provider for observation extraction
`CLAUDE_MEM_OPENROUTER_API_KEY`	string	—	Your OpenRouter API key
`CLAUDE_MEM_OPENROUTER_MODEL`	string or array	`cohere/north-mini-code:free`	Model identifier, or a list to fall back through (see Model fallbacks)
`CLAUDE_MEM_OPENROUTER_BASE_URL`	string	—	Optional: custom OpenAI-compatible base URL (see Custom OpenAI-compatible gateways)
`CLAUDE_MEM_OPENROUTER_SITE_URL`	string	—	Optional: URL for analytics attribution
`CLAUDE_MEM_OPENROUTER_REASONING_EFFORT`	`none`, `minimal`, `low`, `medium`, `high`	—	Optional: reasoning effort for openrouter.ai models. `none` turns reasoning off, the fix for a model that spends the output budget thinking and answers with nothing. Unset sends nothing. Never sent to custom base URLs or the claude-mem observer
`CLAUDE_MEM_OPENROUTER_APP_NAME`	string	`claude-mem`	Optional: App name for analytics
`CLAUDE_MEM_OPENROUTER_TEMPERATURE`	Number, 0–2	Unset (0.3)	Optional worker sampling temperature, e.g. `0.7` or `"0.7"`. Settings file or environment; environment takes precedence. Overrides extra-body temperature when set. Blank or invalid values preserve existing behavior
`CLAUDE_MEM_OPENROUTER_EXTRA_BODY`	JSON object	—	Optional: extra request fields (see Extra request fields). Settings file or environment only

Using the Settings UI

Open the worker URL printed on startup
Click the gear icon to open Settings
Under AI Provider, select OpenRouter
Enter your OpenRouter API key
Optionally select a different model

Settings are applied immediately—no restart required.

Manual Configuration

Edit ~/.claude-mem/settings.json:

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": "cohere/north-mini-code:free"
}

Model fallbacks

CLAUDE_MEM_OPENROUTER_MODEL also accepts a list of model ids. The first is the one normally used; the rest are handed to OpenRouter’s native models fallback array, which tries them in order when the one before it errors.

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
  "CLAUDE_MEM_OPENROUTER_MODEL": [
    "vendor/fast-model:free",
    "vendor/backup-model:free",
    "vendor/paid-model"
  ]
}

A comma- or space-separated string works too, so "vendor/a, vendor/b" means the same thing as the two-entry array. Fallbacks are sent only to openrouter.ai. A custom CLAUDE_MEM_OPENROUTER_BASE_URL gateway speaks plain OpenAI, which has no models field, so it receives the first id and ignores the rest. Alternatively, set the API key via environment variable:

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

The settings file takes precedence over the environment variable.

Custom OpenAI-compatible gateways

The OpenRouter provider is a generic OpenAI-compatible client. Set CLAUDE_MEM_OPENROUTER_BASE_URL to any server that speaks /chat/completions, such as DeepSeek (https://api.deepseek.com), LM Studio (http://localhost:1234/v1) or IO Intelligence by io.net. The model id is sent as-is, and the first id of a fallback list is used (plain OpenAI has no models field). Use the key that endpoint issued: a claude-mem observer key (cm_pro_…) is only ever sent to the claude-mem observer.

The OpenAI-compatible provider does the same job on settings of its own, with presets for common endpoints, and sends none of OpenRouter’s attribution headers. Prefer it for an endpoint that is not OpenRouter.

For example, IO Intelligence:

{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_BASE_URL": "https://api.intelligence.io.solutions/api/v1",
  "CLAUDE_MEM_OPENROUTER_MODEL": "meta-llama/Llama-3.3-70B-Instruct",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_IO_INTELLIGENCE_API_KEY"
}

Model ids are org/name pairs from the IO Intelligence model list, for example deepseek-ai/DeepSeek-R1-0528 or zai-org/GLM-4.6. A trailing slash on the base URL is fine; /chat/completions is appended automatically.

Extra request fields

CLAUDE_MEM_OPENROUTER_EXTRA_BODY merges a JSON object into every request, for provider-specific fields claude-mem does not set itself. The common case is a reasoning model that spends the whole output budget thinking and answers with nothing. Turn its reasoning off:

{
  "CLAUDE_MEM_OPENROUTER_EXTRA_BODY": { "reasoning": { "enabled": false } }
}

As an environment variable it is the same object as a string: CLAUDE_MEM_OPENROUTER_EXTRA_BODY='{"reasoning":{"enabled":false}}'. A custom gateway may use its vendor’s own field instead, for example {"thinking":{"type":"disabled"}}.

The value must be a JSON object. Anything else is ignored with a warning in the worker log.
It cannot replace model, models, messages, stream, max_tokens or max_completion_tokens. Those fields are dropped with a warning. Set the output cap with CLAUDE_MEM_OBSERVER_MAX_OUTPUT_TOKENS.
It is never sent to the claude-mem observer.
When CLAUDE_MEM_OPENROUTER_REASONING_EFFORT is set, it decides reasoning and the extra body’s reasoning field is ignored.
Set it in ~/.claude-mem/settings.json or the environment. The settings UI and API do not write it.

Model Selection Guide

Free Models

Recommended: cohere/north-mini-code:free (the default)

256K context window handles large observations
64K max completion tokens
Sparse mixture-of-experts architecture (3B active parameters)

Alternatives:

poolside/laguna-xs-2.1:free - Coding-agent model, 256K context
nvidia/nemotron-3-ultra-550b-a55b:free - 1M context, strong reasoning

Premium Models (Higher Quality/Speed)

Model	Best For
`anthropic/claude-haiku-4.5`	Same model as the Claude provider’s default
`google/gemini-2.5-flash`	Fast responses
`openai/gpt-4o`	GPT-4 quality

Premium models draw on your OpenRouter credit — still off-plan, so they never touch your Claude plan usage.

Context Window Management

The full conversation history is sent to the model on each request. claude-mem does not apply any client-side truncation or message-count cap — the provider and model own their own context window. If you need to bound context for a specific model, choose a model with an appropriate context length or manage limits at the OpenRouter/provider level.

Usage Tracking

Logs include detailed usage information:

OpenRouter API usage: {
  model: "cohere/north-mini-code:free",
  inputTokens: 2500,
  outputTokens: 1200,
  totalTokens: 3700,
  estimatedCostUSD: "0.00",
  messagesInContext: 8
}

Provider Switching

You can switch between providers at any time:

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

Open Settings in the viewer
Change the AI Provider dropdown
The next observation will use the new provider

Switching via Settings File

{
  "CLAUDE_MEM_PROVIDER": "openrouter"
}

Error Behavior

If OpenRouter errors, claude-mem logs the failure and re-throws so the message stays pending for later retry. There is no Claude SDK fallback — earlier docs claimed automatic Claude fallback, but the wiring was never actually engaged in production (#2087). To switch providers, change CLAUDE_MEM_PROVIDER in settings. Throwing conditions:

Rate limiting (HTTP 429)
Server errors (HTTP 500, 502, 503)
Network issues (connection refused, timeout)
4xx errors other than 429
Missing API key

Multi-Turn Conversation Support

OpenRouter agent maintains full conversation history across API calls:

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

This enables:

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

Troubleshooting

”OpenRouter API key not configured”

Either:

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

Rate Limiting

Free models may have rate limits during peak usage. If you hit rate limits:

The agent throws and leaves the message pending — it will be retried later
Consider switching to a different free model
Add credits for premium model access

Model unavailable

The observer reports OpenRouter model unavailable when OpenRouter says the configured model is retired (“This model has been deprecated”), unknown (“is not a valid model ID”), or has no endpoint left (“No endpoints found for …”). Retrying cannot fix that, so it is not retried; the worker log and the session-start warning tell you to change the model:

Pick a model from OpenRouter Models and set it as CLAUDE_MEM_OPENROUTER_MODEL in ~/.claude-mem/settings.json (or in the viewer’s Settings). The next observation uses it
Use the :free suffix for free model variants
Model IDs are case-sensitive

If you were still on the retired xiaomi/mimo-v2-flash:free default, claude-mem already moved you to cohere/north-mini-code:free the first time it loaded your settings.

High Token Usage

If a session accumulates a large conversation history, requests can grow. To keep per-request size down:

Choose a model suited to your usage volume
Consider a model with a larger context window if you hit provider-side limits

Connection Errors

If you see connection errors:

Check your internet connection
Verify OpenRouter service status at status.openrouter.ai
The agent throws and leaves the message pending for later retry

API Details

OpenRouter uses an OpenAI-compatible REST API: Endpoint: https://openrouter.ai/api/v1/chat/completions Headers:

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

Request Format:

{
  "model": "cohere/north-mini-code:free",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."}
  ],
  "temperature": 0.3,
  "max_tokens": 4096
}

Comparing Providers

Feature	Claude (SDK)	Gemini	OpenRouter
Plan usage	Shares your Claude plan	Off-plan (your Gemini key)	Off-plan (your OpenRouter credit or the claude-mem observer)
Models	Claude only	Gemini only	100+ models
Quality	Highest	High	Varies by model
Rate limits	Based on tier	5-4000 RPM	Varies by model
On error	Throws	Throws	Throws
Setup	Automatic	API key required	API key required

Recommendation: The claude-mem observer (chosen at install) is the easiest way to run memory off-plan. Bringing your own key? Start with the free cohere/north-mini-code:free model. If you need higher quality or encounter rate limits, switch to a premium model or the Claude provider.

Next Steps

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

Multiple keys

CLAUDE_MEM_OPENROUTER_API_KEYS accepts additional keys (newline- or comma-separated) alongside CLAUDE_MEM_OPENROUTER_API_KEY. When a key hits a rate limit, spends its quota, or is rejected as invalid, OpenRouter requests rotate to the next key instead of failing for the rest of the window. See Multi-Key Rotation.

​OpenRouter Provider

​Why Use OpenRouter?

​Free Models on OpenRouter

​Featured Free Models

​Free Model Considerations

​Getting an API Key

​Configuration

​Settings

​Using the Settings UI

​Manual Configuration

​Model fallbacks

​Custom OpenAI-compatible gateways

​Extra request fields

​Model Selection Guide

​Free Models

​Premium Models (Higher Quality/Speed)

​Context Window Management

​Usage Tracking

​Provider Switching

​Switching via UI

​Switching via Settings File

​Error Behavior

​Multi-Turn Conversation Support

​Troubleshooting

​”OpenRouter API key not configured”

​Rate Limiting

​Model unavailable

​High Token Usage

​Connection Errors

​API Details

​Comparing Providers

​Next Steps

​Multiple keys

OpenRouter Provider

Why Use OpenRouter?

Free Models on OpenRouter

Featured Free Models

Free Model Considerations

Getting an API Key

Configuration

Settings

Using the Settings UI

Manual Configuration

Model fallbacks

Custom OpenAI-compatible gateways

Extra request fields

Model Selection Guide

Free Models

Premium Models (Higher Quality/Speed)

Context Window Management

Usage Tracking

Provider Switching

Switching via UI

Switching via Settings File

Error Behavior

Multi-Turn Conversation Support

Troubleshooting

”OpenRouter API key not configured”

Rate Limiting

Model unavailable

High Token Usage

Connection Errors

API Details

Comparing Providers

Next Steps

Multiple keys