ContextQMD
Back to Claude Mem

Custom Anthropic-Compatible Backends

docs/public/configuration/custom-anthropic-backends.mdx

12.7.15.5 KB
Original Source

Custom Anthropic-Compatible Backends

When you use the claude provider, claude-mem talks to the Anthropic API through the Claude Agent SDK. By default, the SDK targets the official Anthropic endpoint, but it honors the standard ANTHROPIC_BASE_URL environment variable. That means you can route claude-mem at any Anthropic-protocol-compatible backend — for example a corporate gateway, a regional bridge, or a third-party provider that exposes an Anthropic-shaped API — without changing any claude-mem source code.

<Note> This page documents how to **persist a custom base URL** so claude-mem's worker uses it consistently. For OpenAI-compatible upstream providers, use a gateway such as LiteLLM and follow the [LiteLLM Gateway](litellm-gateway) guide. </Note>

When to Use This

Use ANTHROPIC_BASE_URL if you need claude-mem's observation worker to talk to:

  • A corporate Anthropic gateway (proxy in front of api.anthropic.com)
  • A regional Anthropic deployment (e.g. AWS Bedrock or GCP Vertex via an Anthropic-compatible shim)
  • A third-party provider that bridges its API to the Anthropic protocol

If your provider only speaks the OpenAI chat-completions protocol, put a gateway such as LiteLLM in front of it and point claude-mem's Claude Agent SDK path at that gateway. See LiteLLM Gateway for the full routing model.

How the Plumbing Works

The flow is intentionally simple:

  1. You write the credential to ~/.claude-mem/.env.
  2. EnvManager.loadClaudeMemEnv() reads that file (src/shared/EnvManager.ts:67).
  3. buildIsolatedEnv() copies ANTHROPIC_BASE_URL into the worker's spawn environment alongside explicit gateway or API credentials (src/shared/EnvManager.ts:164).
  4. ClaudeProvider.startSession() spawns the Claude Agent SDK with that isolated env (src/services/worker/ClaudeProvider.ts:115). The SDK reads ANTHROPIC_BASE_URL natively — claude-mem does not parse or rewrite it.

Because the variable is isolated to the worker process, your interactive Claude Code sessions are unaffected; only the background memory agent uses the override.

Configuration

Step 1: Edit ~/.claude-mem/.env

The credentials file is a plain KEY=VALUE env file at ~/.claude-mem/.env (mode 0600). Add or update the ANTHROPIC_BASE_URL line:

bash
# ~/.claude-mem/.env
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_BASE_URL=https://your-gateway.example.com/v1

If the file does not yet exist, create it. The directory permissions are enforced to 0700 and the file to 0600 automatically on the next worker write.

Step 2: Pick a Compatible Model

CLAUDE_MEM_MODEL (in ~/.claude-mem/settings.json) is passed straight through to the SDK. The model name must be one your bridge accepts — claude-mem does not translate names.

json
{
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

If your bridge expects a non-Anthropic model name (for example, a Bedrock inference profile), set that string here instead.

Step 3: Restart the Worker

Credentials are loaded when the worker spawns the SDK, so a restart is required after you edit .env:

bash
npm run worker:restart

Worked Example: Corporate Gateway

Suppose your team runs https://anthropic-proxy.internal.example.com in front of api.anthropic.com for audit and rate-limit purposes. The proxy accepts the same protocol and the same model names.

~/.claude-mem/.env:

bash
ANTHROPIC_API_KEY=sk-corp-...
ANTHROPIC_BASE_URL=https://anthropic-proxy.internal.example.com

~/.claude-mem/settings.json:

json
{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}

Restart, and the next observation will be routed through your gateway.

Verifying

After restarting, watch the worker logs for the next observation flush:

bash
npm run worker:logs

A successful request through your gateway shows the standard SDK Starting SDK query line followed by Response received. If the gateway rejects the request, the SDK error surfaces verbatim in worker-error.log — there is no silent fallback to the public Anthropic endpoint.

Limitations and Gotchas

  • No model-name translation. If your bridge expects glm-4.7 and CLAUDE_MEM_MODEL is claude-haiku-4-5-20251001, the request will fail. Pin CLAUDE_MEM_MODEL to a name your bridge recognizes.
  • Gateway auth usually uses ANTHROPIC_AUTH_TOKEN. For LiteLLM gateway mode, store the gateway key or virtual key as ANTHROPIC_AUTH_TOKEN. Use ANTHROPIC_API_KEY for direct Anthropic API-key mode or gateways that explicitly expect it.
  • ANTHROPIC_BASE_URL from your shell is not inherited. ANTHROPIC_API_KEY is in the BLOCKED_ENV_VARS list (src/shared/EnvManager.ts:10) to prevent accidental billing on a shell-leaked key — ANTHROPIC_BASE_URL is not blocked, but it must still be set in ~/.claude-mem/.env for the worker to pick it up reliably across restarts. Do not rely on shell exports.
  • No auto-detection. If you have already configured ANTHROPIC_BASE_URL, ANTHROPIC_DEFAULT_HAIKU_MODEL, etc. for Claude Code itself, claude-mem will not read those today. Mirror the relevant values into ~/.claude-mem/.env and ~/.claude-mem/settings.json.