docs: cover all 4 CLAUDE_MEM_CLAUDE_AUTH_METHOD values + add decision tree

[github-actions[bot]]

Originally posted as issue #2983 by @frankwonghappy
#2983

---

name: Feature request
about: Suggest an idea for this project
title: "docs: cover all 4 CLAUDE_MEM_CLAUDE_AUTH_METHOD values + add decision tree"
labels: feature-request
assignees: ''

Before submitting

• I searched existing issues and confirmed this is not a duplicate

---

Is your feature request related to a problem? Please describe.

I tried to set up claude-mem on a custom Anthropic-compatible endpoint (corporate proxy, regional bridge, third-party Anthropic-shaped API). The
worker's auth-method env var has 4 valid values, but the docs only document 3 of them, and none of them explain how to choose between them.

Concrete gaps I hit:

1. Doc/code mismatch on the 4th value. SettingsRoutes.ts:201 accepts subscription | api-key | gateway | cli, but
   docs/public/configuration.mdx:18 only documents 3. Setting CLAUDE_MEM_CLAUDE_AUTH_METHOD=cli works (passes validation) but has no documentation.
   Users have no way to discover what it does.

2. api-key mode has no setup guide. The env var is listed in the table, but there is no "how do I configure it?" page. Specifically unclear:

   • Where does the key live — ANTHROPIC_API_KEY? ~/.claude-mem/.env? settings.json?
   • Does it conflict with a logged-in Claude Code OAuth session?
   • Can I combine it with ANTHROPIC_BASE_URL (use my key against a custom endpoint), or is that only the gateway mode?

3. No decision tree. For a first-time user reading the configuration table, "which auth method should I pick?" is not answered anywhere. The
   litellm-gateway.mdx page is excellent if you already know you want a gateway, but it doesn't help you decide.

Describe the solution you'd like

A single, authoritative guide at docs/public/configuration/claude-auth-methods.mdx (or equivalent) that:

• Lists all 4 valid values with a one-line summary each
• Cross-links to the existing litellm-gateway.mdx and custom-anthropic-backends.mdx for detail
• Has a short "choose your auth method" decision tree at the top
• Documents the cli value (currently zero docs), including which Claude executable it reuses and how it differs from subscription
• Documents the api-key value end-to-end (env var name, expected key location, interaction with ANTHROPIC_BASE_URL, OAuth-collision notes — same
  warning style as litellm-gateway.mdx:172)
• Updates the configuration.mdx table at line 18 to list all 4 values, not 3

Page should be cross-linked from configuration.mdx, installation.mdx, and the troubleshooting page.

Describe alternatives you've considered

• Read the source code. This works (the SettingsDefaultsManager, EnvManager, and SettingsRoutes files form a complete picture), but it
  requires understanding the whole worker spawn flow. The docs are the right level for most users.
• Just add the missing cli row to the table. Minimal but doesn't address the api-key documentation gap or the decision-tree need.
• Open a single-line PR fixing the table. Tempting, but the real gap is structural (no overview page), not a typo.

Additional context

Repro for anyone who wants to verify the doc/code mismatch:

# This is what the codebase accepts (v13.6.0):
grep -A1 "validClaudeAuthMethods" src/services/worker/http/routes/SettingsRoutes.ts

# This is what the docs list (v13.6.0 docs):
grep "CLAUDE_MEM_CLAUDE_AUTH_METHOD" docs/public/configuration.mdx

My concrete setup that exposed the gap: corporate Anthropic proxy at https://api.minimaxi.com/anthropic + an issued ANTHROPIC_AUTH_TOKEN. I spent ~2
hours between the env var table and the LiteLLM page trying to figure out whether I needed api-key (because I have a token) or gateway (because I have
a custom base URL). The answer turned out to be gateway + ANTHROPIC_AUTH_TOKEN, but nothing in the docs spells that combination out.

Related but separate: it would also help if getAuthMethodDescription() in src/shared/EnvManager.ts:356 were surfaced in worker-error.log (currently
only logged at debug level, see classifyClaudeError() in src/services/worker/ClaudeProvider.ts) so users hitting an auth failure can see which method
the worker thought it was using. That's an implementation change, not docs — feel free to file a sibling issue if it lands.