claude-mem Custom Backend Setup

Route the claude-mem background worker to a TokenHub Anthropic-compatible backend without changing Claude Code sessions.

Create TokenHub API Key

What is claude-mem?

claude-mem is a persistent memory system that runs a background worker alongside Claude Code and supported coding tools.

This claude-mem guide writes the custom Anthropic-compatible endpoint to the worker-specific environment file, pins the exact model in settings, and restarts the worker so configuration is actually loaded. The worker reads its own environment and settings files, so changing a terminal export or the main Claude Code configuration may have no effect. Persist the gateway credentials in the documented worker file, select an Anthropic-compatible model, restart the worker, and compare worker logs with TokenHub requests after the next processing cycle.

claude-mem's claude provider sends requests through the Claude Agent SDK. Its official Custom Anthropic-Compatible Backends flow changes only the background observation worker; it does not change the interactive Claude Code session. Put this configuration in claude-mem's own directory instead of relying on shell exports.

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

For a TokenHub Anthropic-compatible gateway that uses a Bearer token, add:

ANTHROPIC_AUTH_TOKEN=YOUR_TOKENHUB_API_KEY
ANTHROPIC_BASE_URL=__API_BASE_URL__

The official guide requires 0600 permissions on this file and 0700 on its directory; the worker also enforces those permissions on its next write. The Claude Agent SDK reads ANTHROPIC_BASE_URL directly, and claude-mem does not parse or rewrite it.

Do not rely on ANTHROPIC_BASE_URL in the current terminal. claude-mem constructs an isolated worker environment, so the setting must exist in ~/.claude-mem/.env to survive a restart. Use ANTHROPIC_API_KEY instead only when a gateway explicitly requires x-api-key rather than Bearer authentication.

Step 2: pin the worker model in settings.json

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

{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_MODEL": "YOUR_TOKENHUB_ANTHROPIC_MODEL_ID"
}

CLAUDE_MEM_MODEL is passed to the SDK unchanged. claude-mem does not translate aliases and does not read Claude Code's ANTHROPIC_DEFAULT_HAIKU_MODEL, so enter the complete Anthropic-compatible model ID accepted by TokenHub.

Step 3: restart with the official commands and inspect logs

npm run worker:restart
npm run worker:logs

Wait for the next observation flush. A successful run first logs SDK Starting SDK query and then Response received. Gateway failures are written to worker-error.log; claude-mem does not silently fall back to Anthropic's public endpoint.

Troubleshoot the isolated worker configuration

  • Claude Code uses TokenHub but claude-mem does not: these are separate settings; inspect ~/.claude-mem/.env and settings.json.
  • Old URL remains after an edit: run worker:restart; reopening a terminal is not enough.
  • Model does not exist: CLAUDE_MEM_MODEL has no alias translation, so copy the TokenHub model ID again.
  • Authentication error: use ANTHROPIC_AUTH_TOKEN for TokenHub Bearer authentication; use ANTHROPIC_API_KEY only when explicitly required.
  • TokenHub endpoint exposes only OpenAI Chat Completions: the claude provider cannot call it directly; place an Anthropic-protocol adapter such as LiteLLM in between.

Official reference

Choose a compatible claude-mem model

WorkloadModel choiceWhy it fits
Complex coding tasksA tool-capable reasoning modelUse a model with reliable tool use, streaming, and the context length your workflow needs.
Daily implementationA balanced coding modelPrioritize reliable edits and useful latency for normal coding loops.
Background and subagent workA fast, lower-cost modelUse this for iterations, summaries, and simpler work only after validating tool use.
Browse TokenHub models and compatibility

claude-mem custom backend FAQ

Will this change my Claude Code session?

No. claude-mem reads its own worker environment, so the override is isolated from interactive Claude Code sessions.

Why use ANTHROPIC_AUTH_TOKEN?

The claude-mem custom-backend guide notes that gateway credentials commonly use ANTHROPIC_AUTH_TOKEN. Use the credential format your TokenHub endpoint requires.

Can I use an OpenAI-only model endpoint?

Not directly with the claude provider. Put an Anthropic-compatible gateway such as LiteLLM in front of an OpenAI-only upstream first.

How do I verify the claude-mem worker uses TokenHub?

Restart the worker, wait for the next observation-processing cycle, and compare the worker log with an Anthropic Messages request in TokenHub logs.

Why did a shell export not update claude-mem?

An existing background worker may not inherit the current shell. Persist values in ~/.claude-mem/.env and restart the worker.

References

This setup is based on TokenHub and official documentation, last verified on 2026-09-08.

Explore API setup guides for related tools and workflows.

LangChainOpenAI Compatible