Skip to content

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

Rust

docs(llm): stop recommending gpt-5-mini for openai-oauth (#831)

AkitaOnRails5d5f01088d30
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c59817a..62074689 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
unaffected. (#794)
### Docs
+- Stopped recommending `AI_MEMORY_LLM_MODEL=gpt-5-mini` for the `openai-oauth`
+ provider in `docs/llm-providers.md` and `docs/install.md`. The Codex/ChatGPT
+ backend only accepts a small server-defined set of model ids and rejects
+ others (including `gpt-5-mini`) with a deterministic 400; the docs now advise
+ leaving the provider default (`gpt-5.5`) for `openai-oauth`/`codex`, keep
+ `claude-haiku-4-5` for `anthropic-oauth`, and qualify `gpt-5-mini` for
+ `copilot` as unverified. (#831)
- `docs/llm-providers.md` now covers the `opencode` LLM provider, which has
shipped since 1.x but was missing from the recommended-defaults table:
`OPENCODE_API_KEY` as the only credential, Go as the default endpoint, Zen
diff --git a/docs/install.md b/docs/install.md
index 1e86f884..a98218c5 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1730,13 +1730,13 @@ Use `ai-memory auth status` to check whether a token is present and
`ai-memory auth logout openai-oauth` to remove it.
> [!TIP]
-> **Pick a small, fast model.** Consolidation / lint / explore are
-> summarisation tasks, not hard reasoning — a mini-class model is plenty and
-> is much easier on subscription rate limits. Set e.g.
-> `AI_MEMORY_LLM_MODEL=gpt-5-mini` (the `gpt-5.5` default works but is
-> overkill for this workload). If you stay on a reasoning model, set
-> `AI_MEMORY_LLM_REASONING_EFFORT=none` or `low` so hidden thought tokens
-> do not eat the JSON budget. Reserve high-effort reasoning for your
+> **Leave the model at the provider default (`gpt-5.5`).** The Codex/ChatGPT
+> backend behind `openai-oauth` only accepts a small server-defined set of model
+> ids and rejects others — including `gpt-5-mini` — with a deterministic 400, so
+> do not set `AI_MEMORY_LLM_MODEL` for this backend. Consolidation / lint /
+> explore are summarisation tasks, so if the default reasoning is too heavy set
+> `AI_MEMORY_LLM_REASONING_EFFORT=none` or `low` instead, so hidden thought
+> tokens do not eat the JSON budget. Reserve high-effort reasoning for your
> coding agent.
### Codex credential reuse
diff --git a/docs/llm-providers.md b/docs/llm-providers.md
index 7affe2b5..6f807396 100644
--- a/docs/llm-providers.md
+++ b/docs/llm-providers.md
@@ -133,12 +133,19 @@ uses the Copilot Chat endpoint with `vscode-chat` integration headers. You can
also set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` on the server.
> [!TIP]
-> **For the OAuth/subscription backends (`anthropic-oauth`, `openai-oauth`, `codex`,
-> `copilot`), pick a small, fast model** via `AI_MEMORY_LLM_MODEL` — e.g.
-> `claude-haiku-4-5` or `gpt-5-mini`. ai-memory's LLM work (consolidation,
-> lint, explore) is summarisation, not hard reasoning, so a Haiku/mini-class
-> model is plenty and is much easier on subscription rate limits. Save the
-> high-effort thinking models for your coding agent.
+> **For the OAuth/subscription backends, prefer a small, fast model** via
+> `AI_MEMORY_LLM_MODEL` where the backend lets you choose one. ai-memory's LLM
+> work (consolidation, lint, explore) is summarisation, not hard reasoning, so a
+> Haiku/mini-class model is plenty and is much easier on subscription rate
+> limits. Save the high-effort thinking models for your coding agent. Per backend:
+> - `anthropic-oauth`: set `claude-haiku-4-5`.
+> - `openai-oauth` / `codex`: leave the provider default (`gpt-5.5`). The
+> Codex/ChatGPT backend only accepts a small server-defined set of model ids
+> and rejects others (e.g. `gpt-5-mini`) with a deterministic 400, so do not
+> override the model here.
+> - `copilot`: a mini-class id such as `gpt-5-mini` may work, but Copilot's
+> accepted model set is unverified — check before relying on it, and fall back
+> to the default if the endpoint rejects your choice.
> [!TIP]
> **OpenAI-compatible structured output is schema-constrained by default.**