Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(llm): say Anthropic refuses anthropic-oauth tokens from third-party apps

AkitaOnRailsf6c165a37a75
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3d42ab25..e61b204d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- Documented that Anthropic currently refuses Claude Free/Pro/Max subscription
+ tokens from third-party apps, so `anthropic-oauth` usually fails with a
+ `429 rate_limit_error` on every request. That is a policy refusal, not a
+ real rate limit; the docs now point to the `anthropic` provider with a
+ Console API key or another provider. Also corrected the claim that
+ `claude setup-token` writes `CLAUDE_CODE_OAUTH_TOKEN`: it only prints the
+ token, which you export yourself. (#1170)
- Documented that Zero runs hook commands inside its sandbox, whose default
policy blocks network (loopback included) and writes outside the
workspace, so hook events stay in the spool instead of reaching the
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 89df0382..400efca2 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -719,8 +719,9 @@ impl RuntimeEnv {
.is_some_and(|value| !value.trim().is_empty()),
claude_code_session_id: env_string("CLAUDE_CODE_SESSION_ID"),
anthropic_api_key: env_secret("ANTHROPIC_API_KEY"),
- // CLAUDE_CODE_OAUTH_TOKEN is what `claude setup-token` writes;
- // ANTHROPIC_OAUTH_TOKEN is our canonical name — accept both.
+ // CLAUDE_CODE_OAUTH_TOKEN is the name Claude Code reads the
+ // `claude setup-token` token from; ANTHROPIC_OAUTH_TOKEN is our
+ // canonical name — accept both.
anthropic_oauth_token: env_secret("ANTHROPIC_OAUTH_TOKEN")
.or_else(|| env_secret("CLAUDE_CODE_OAUTH_TOKEN")),
openai_api_key: env_secret("OPENAI_API_KEY"),
diff --git a/docs/install.md b/docs/install.md
index a89bb289..fc2490b6 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -401,10 +401,11 @@ curl -sI http://127.0.0.1:49374/handoff
> **You do not need a paid platform API key.** ai-memory's LLM features
> (consolidation, lint, auto-improve) are opt-in, and when you enable them you
> can authenticate with a **subscription you already pay for** instead of a
-> metered API key: a Claude Pro/Max plan via `anthropic-oauth`
-> (`claude setup-token`), a ChatGPT Plus/Pro/Codex plan via `openai-oauth`
-> (`ai-memory auth login openai-oauth`), or a GitHub Copilot plan via `copilot`
-> (`ai-memory auth login copilot`). See
+> metered API key: a ChatGPT Plus/Pro/Codex plan via `openai-oauth`
+> (`ai-memory auth login openai-oauth`) or a GitHub Copilot plan via `copilot`
+> (`ai-memory auth login copilot`). (Claude Pro/Max via `anthropic-oauth` is
+> currently refused by Anthropic; see
+> [below](#anthropic-via-claude-subscription-oauth).) See
> [`docs/llm-providers.md`](llm-providers.md) for the full table. And you can
> skip an LLM entirely: the default zero-LLM path still captures, searches
> (FTS), and writes rule-based summaries with no provider at all —
@@ -1904,7 +1905,7 @@ If you set only the provider, ai-memory picks a sensible default:
| Setting | Default | Why |
|---|---|---|
| `AI_MEMORY_LLM_PROVIDER=anthropic` | `claude-haiku-4-5` | **Recommended default.** Best balance of speed, restraint, and classification quality. Not a reasoning model. Consistently classifies durable project rules as `kind: rule`. |
-| `AI_MEMORY_LLM_PROVIDER=anthropic-oauth` | `claude-sonnet-4-6` | Anthropic via Claude subscription. Run `claude setup-token` once; set `ANTHROPIC_OAUTH_TOKEN` (or `CLAUDE_CODE_OAUTH_TOKEN`). No `ANTHROPIC_API_KEY` needed. Same `/v1/messages` endpoint, Bearer token auth. |
+| `AI_MEMORY_LLM_PROVIDER=anthropic-oauth` | `claude-sonnet-4-6` | Anthropic via Claude subscription. Run `claude setup-token` once and export the printed token as `ANTHROPIC_OAUTH_TOKEN` (or `CLAUDE_CODE_OAUTH_TOKEN`). No `ANTHROPIC_API_KEY` needed. Same `/v1/messages` endpoint, Bearer token auth. Anthropic currently refuses these tokens from third-party apps, usually as a `429` on every request. |
| `AI_MEMORY_LLM_PROVIDER=openai` | `gpt-5.4-mini` | Cheaper + faster alternative. Same parse reliability; mild over-classification on thin sessions. |
| `AI_MEMORY_LLM_PROVIDER=openai-oauth` | `gpt-5.5` | ChatGPT/Codex backend. Run `ai-memory auth login openai-oauth` once; ai-memory stores the refresh token in `<data_dir>/auth.json` and refreshes access tokens automatically. Optional `AI_MEMORY_LLM_REASONING_EFFORT` (`none`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`/`ultra`/`persistent`) is mapped to each provider's native reasoning field; omit it to keep the model default. |
| `AI_MEMORY_LLM_PROVIDER=codex` | `gpt-5.6-luna` | Reuses only `access_token` and `account_id` from Codex's `auth.json`; token renewal is delegated to `codex app-server --stdio`. |
@@ -1969,16 +1970,30 @@ export EMBEDDING_API_KEY=sk-or-v1-...
> `anthropic` provider with a real Platform API key. We ship this purely as an
> opt-in convenience and make no guarantees about it.
+> [!IMPORTANT]
+> **Anthropic currently refuses these tokens from third-party apps.** Its
+> [legal and compliance page](https://code.claude.com/docs/en/legal-and-compliance)
+> does not permit third-party developers to route requests through Free, Pro,
+> or Max plan credentials, and the API rejects them server-side. With
+> ai-memory this usually shows up as
+> `provider error 429: {"type":"error","error":{"type":"rate_limit_error",...}}`
+> on every request, including `ai-memory llm-test`, even when the same token
+> works in the `claude` CLI. That is a policy refusal, not a real rate limit,
+> and retrying or changing headers will not fix it. Use the `anthropic`
+> provider with an Anthropic Console API key (`ANTHROPIC_API_KEY`), or another
+> provider from the table above.
+
`anthropic-oauth` is for Claude Pro/Max subscribers who want to use their
existing subscription instead of an Anthropic Platform API key. It hits the
**same** `/v1/messages` endpoint as the `anthropic` provider — only the auth
headers differ (Bearer token + `anthropic-beta: oauth-2025-04-20`).
```bash
-# Obtain a token once using the Claude Code CLI:
+# Obtain a token once using the Claude Code CLI. It prints the token and
+# does not save it anywhere, so copy it:
claude setup-token
-# Then export it (the CLI may also write CLAUDE_CODE_OAUTH_TOKEN automatically):
+# Then export it yourself (CLAUDE_CODE_OAUTH_TOKEN is accepted too):
export ANTHROPIC_OAUTH_TOKEN=<paste token here>
export AI_MEMORY_LLM_PROVIDER=anthropic-oauth
ai-memory serve
diff --git a/docs/llm-providers.md b/docs/llm-providers.md
index 21d98e7c..16b60f82 100644
--- a/docs/llm-providers.md
+++ b/docs/llm-providers.md
@@ -43,7 +43,7 @@ Recommended defaults:
| Provider | Default | Use when |
|---|---|---|
| `anthropic` | `claude-haiku-4-5` | Best default for consolidation quality and rule classification. |
-| `anthropic-oauth` | `claude-sonnet-4-6` | Use a Claude Pro/Max subscription via `claude setup-token`, no API key. |
+| `anthropic-oauth` | `claude-sonnet-4-6` | Use a Claude Pro/Max subscription via `claude setup-token`, no API key. Currently refused by Anthropic for third-party apps (usually `429`); see below. |
| `openai` | `gpt-5.4-mini` | Cheaper and faster hosted option. |
| `openai-oauth` | `gpt-5.5` | ChatGPT Pro/Plus/Codex backend via `ai-memory auth login openai-oauth`; no Platform API key. |
| `codex` | `gpt-5.6-luna` | Reuse the Codex CLI-owned `auth.json`; access-token refresh remains owned by `codex app-server`. |
@@ -297,9 +297,10 @@ alone does not redirect embeddings — set `AI_MEMORY_EMBEDDING_BASE_URL` too.
`anthropic-oauth` hits the same `/v1/messages` endpoint as `anthropic` but
authenticates with an OAuth bearer token instead of an API key. Run
-`claude setup-token` once, then set `AI_MEMORY_LLM_PROVIDER=anthropic-oauth` and
-`ANTHROPIC_OAUTH_TOKEN=<token>` (or `CLAUDE_CODE_OAUTH_TOKEN`, which `claude
-setup-token` writes automatically). No `ANTHROPIC_API_KEY` is needed. The Docker
+`claude setup-token` once; it prints the token and does not save it anywhere, so
+export it yourself as `ANTHROPIC_OAUTH_TOKEN=<token>` (or
+`CLAUDE_CODE_OAUTH_TOKEN`) and set `AI_MEMORY_LLM_PROVIDER=anthropic-oauth`. No
+`ANTHROPIC_API_KEY` is needed. The Docker
wrappers forward either token by name to short-lived helper commands such as
`llm-test`; configure the long-lived server container separately as shown in the
installation guide.
@@ -314,6 +315,14 @@ rule.
it may get your account rate-limited or banned. See
[the warning in `docs/install.md`](install.md#anthropic-via-claude-subscription-oauth).**
+Anthropic currently refuses subscription tokens from third-party apps
+([legal and compliance](https://code.claude.com/docs/en/legal-and-compliance)),
+so expect `anthropic-oauth` to fail on every request, typically with
+`provider error 429` and `rate_limit_error`, even though the same token works
+in the `claude` CLI. That 429 is a policy refusal, not a real rate limit. Use
+the `anthropic` provider with an Anthropic Console API key, or another provider
+from the table above.
+
`copilot` stores a GitHub user token in the same auth file, exchanges it for a
short-lived Copilot API token via GitHub's `/copilot_internal/v2/token`, and
uses the Copilot Chat endpoint with `vscode-chat` integration headers. You can