Skip to content

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

Rust

feat(llm): map typed reasoning effort onto native provider fields

Matheus Cardoso8f664f78abdb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e07efeff..4f2fcb26 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+- `llm_reasoning_effort` / `AI_MEMORY_LLM_REASONING_EFFORT` is a typed
+ enum (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`,
+ `ultra`, `persistent`); unknown values fail at config load. Unset keeps
+ the model default. Each chat provider maps the value to its native
+ field: OpenAI `reasoning_effort`, OpenRouter `reasoning.effort`,
+ xAI Grok `reasoning_effort`, Anthropic `output_config.effort` (plus
+ adaptive/disabled thinking on models that accept it), and Codex
+ Responses `reasoning.effort`. Gemini and Copilot ignore the key.
+ Host-unsupported values are clamped (`ultra`/`persistent` → `max` on
+ OpenAI/OpenRouter/Codex; Anthropic `xhigh`/`max` per model; `none`
+ does not send `thinking: disabled` on always-on Claude models).
+
## [1.38.0] - 2026-08-30
### Added
diff --git a/Cargo.lock b/Cargo.lock
index b76998bc..0c1661e4 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -56,6 +56,7 @@ dependencies = [
"jsonc-parser",
"reqwest 0.12.28",
"rmcp",
+ "rstest",
"secrecy",
"serde",
"serde_json",
@@ -65,7 +66,7 @@ dependencies = [
"tempfile",
"tokio",
"tokio-util",
- "toml_edit",
+ "toml_edit 0.22.27",
"tower",
"tower-http",
"tracing",
@@ -164,9 +165,11 @@ dependencies = [
"anyhow",
"async-trait",
"base64",
+ "cognomen",
"jiff",
"regex",
"reqwest 0.12.28",
+ "rstest",
"schemars",
"secrecy",
"serde",
@@ -346,7 +349,7 @@ version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
dependencies = [
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -357,7 +360,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
dependencies = [
"anstyle",
"once_cell_polyfill",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -648,6 +651,27 @@ version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+[[package]]
+name = "cognomen"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31c96aac453db73ae5d52665320b902889e596d64cb6a1212b66762367ca857"
+dependencies = [
+ "cognomen-macros",
+ "serde",
+]
+
+[[package]]
+name = "cognomen-macros"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "956eeb02b6e4e9c30f26500b8f933b15c5bbf3f0331cedae5f64671bbb394922"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
[[package]]
name = "colorchoice"
version = "1.0.5"
@@ -936,7 +960,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
dependencies = [
"libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -1117,6 +1141,12 @@ version = "0.3.32"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+[[package]]
+name = "futures-timer"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af43fadb8a98512d547e37b4e92e0ced13e205c061b87b4623eff01d918d6968"
+
[[package]]
name = "futures-util"
version = "0.3.32"
@@ -1197,6 +1227,12 @@ dependencies = [
"log",
]
+[[package]]
+name = "glob"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
+
[[package]]
name = "h2"
version = "0.4.16"
@@ -1589,7 +1625,7 @@ dependencies = [
"portable-atomic",
"portable-atomic-util",
"serde_core",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -1906,7 +1942,7 @@ version = "0.50.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
dependencies = [
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -2077,6 +2113,15 @@ dependencies = [
"syn",
]
+[[package]]
+name = "proc-macro-crate"
+version = "3.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
+dependencies = [
+ "toml_edit 0.25.13+spec-1.1.0",
+]
+
[[package]]
name = "proc-macro2"
version = "1.0.106"
@@ -2372,6 +2417,12 @@ version = "0.8.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
+[[package]]
+name = "relative-path"
+version = "1.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba39f3699c378cd8970968dcbff9c43159ea4cfbd88d43c00b22f2ef10a435d2"
+
[[package]]
name = "reqwest"
version = "0.12.28"
@@ -2506,6 +2557,35 @@ dependencies = [
"syn",
]
+[[package]]
+name = "rstest"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5a3193c063baaa2a95a33f03035c8a72b83d97a54916055ba22d35ed3839d49"
+dependencies = [
+ "futures-timer",
+ "futures-util",
+ "rstest_macros",
+]
+
+[[package]]
+name = "rstest_macros"
+version = "0.26.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c845311f0ff7951c5506121a9ad75aec44d083c31583b2ea5a30bcb0b0abba0"
+dependencies = [
+ "cfg-if",
+ "glob",
+ "proc-macro-crate",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "relative-path",
+ "rustc_version",
+ "syn",
+ "unicode-ident",
+]
+
[[package]]
name = "rusqlite"
version = "0.32.1"
@@ -2545,7 +2625,7 @@ dependencies = [
"errno",
"libc",
"linux-raw-sys",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -2890,7 +2970,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e"
dependencies = [
"libc",
- "windows-sys 0.60.2",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -2996,7 +3076,7 @@ dependencies = [
"getrandom 0.4.2",
"once_cell",
"rustix",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -3175,8 +3255,8 @@ checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
dependencies = [
"serde",
"serde_spanned",
- "toml_datetime",
- "toml_edit",
+ "toml_datetime 0.6.11",
+ "toml_edit 0.22.27",
]
[[package]]
@@ -3188,6 +3268,15 @@ dependencies = [
"serde",
]
+[[package]]
+name = "toml_datetime"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+dependencies = [
+ "serde_core",
+]
+
[[package]]
name = "toml_edit"
version = "0.22.27"
@@ -3197,9 +3286,30 @@ dependencies = [
"indexmap",
"serde",
"serde_spanned",
- "toml_datetime",
+ "toml_datetime 0.6.11",
"toml_write",
- "winnow",
+ "winnow 0.7.15",
+]
+
+[[package]]
+name = "toml_edit"
+version = "0.25.13+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6975367e4d2ef766d86af01ffad14b622fecc8d4357a998fbc4deb6e9bacaf9b"
+dependencies = [
+ "indexmap",
+ "toml_datetime 1.1.1+spec-1.1.0",
+ "toml_parser",
+ "winnow 1.0.4",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.3+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
+dependencies = [
+ "winnow 1.0.4",
]
[[package]]
@@ -3663,7 +3773,7 @@ version = "0.1.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
dependencies = [
- "windows-sys 0.48.0",
+ "windows-sys 0.61.2",
]
[[package]]
@@ -3962,6 +4072,15 @@ dependencies = [
"memchr",
]
+[[package]]
+name = "winnow"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
+dependencies = [
+ "memchr",
+]
+
[[package]]
name = "wiremock"
version = "0.6.5"
diff --git a/Cargo.toml b/Cargo.toml
index bd93ca61..c15bbd0f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -44,6 +44,9 @@ thiserror = "2"
# Serialization.
serde = { version = "1", features = ["derive"] }
+# Compile-time enum labels for wire/config strings. `serde` generates
+# Serialize/Deserialize from the same labels as `Label::as_str`.
+cognomen = { version = "0.5", features = ["serde"] }
# `preserve_order` keeps existing JSON key order intact when we
# round-trip user config files via `install-mcp --apply`. Without it,
# `~/.claude.json` (which has dozens of CC-managed keys) would be
@@ -144,6 +147,7 @@ async-trait = "0.1"
# Testing.
tempfile = "3"
+rstest = "0.26"
[workspace.lints.rust]
unsafe_code = "forbid"
diff --git a/crates/ai-memory-cli/Cargo.toml b/crates/ai-memory-cli/Cargo.toml
index 280bb4a9..6826916f 100644
--- a/crates/ai-memory-cli/Cargo.toml
+++ b/crates/ai-memory-cli/Cargo.toml
@@ -56,6 +56,7 @@ tempfile.workspace = true
[dev-dependencies]
tempfile.workspace = true
+rstest.workspace = true
tower.workspace = true
tokio = { workspace = true, features = ["test-util"] }
diff --git a/crates/ai-memory-cli/src/commands/llm_test.rs b/crates/ai-memory-cli/src/commands/llm_test.rs
index f1c4212a..382d345d 100644
--- a/crates/ai-memory-cli/src/commands/llm_test.rs
+++ b/crates/ai-memory-cli/src/commands/llm_test.rs
@@ -25,6 +25,7 @@ pub async fn run(config: &Config, args: LlmTestArgs) -> Result<()> {
base_url: args.base_url.or_else(|| config.llm_test_base_url()),
compat_strict: config.llm_compat_strict,
request_timeout_secs: config.llm_timeout_secs,
+ reasoning_effort: config.llm_reasoning_effort,
};
let client = build_provider(provider_config).context("building LLM provider")?;
info!(
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index 47638b01..c3f24257 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -10,7 +10,7 @@ use std::path::{Path, PathBuf};
use ai_memory_llm::{
AuthRequirement, EmbedderChoice, EmbedderConfig, LlmError, LlmResult, OPENCODE_DEFAULT_MODEL,
- ProviderAuth, ProviderChoice, ProviderConfig,
+ ProviderAuth, ProviderChoice, ProviderConfig, ReasoningEffort,
};
use anyhow::{Context, Result};
use figment::{
@@ -170,6 +170,14 @@ pub struct Config {
/// ceiling (observed with free aggregator tiers). Set with
/// `AI_MEMORY_LLM_TIMEOUT_SECS`.
pub llm_timeout_secs: u64,
+ /// Optional reasoning / thinking effort. Omitted when unset so the
+ /// model default applies. Env: `AI_MEMORY_LLM_REASONING_EFFORT`.
+ /// Values: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`,
+ /// `max`, `ultra`, `persistent`. Each provider maps this to its
+ /// native request field (OpenAI `reasoning_effort`, OpenRouter
+ /// `reasoning`, xAI Grok `reasoning_effort`, Anthropic
+ /// `output_config.effort`, Codex `reasoning.effort`).
+ pub llm_reasoning_effort: Option<ReasoningEffort>,
/// Opt-in: run LLM consolidation on SessionEnd (in addition to the
/// always-written heuristic session page), when an LLM provider is
/// configured. Off by default. Provider work is durably queued after the
@@ -602,6 +610,7 @@ impl Default for Config {
llm_base_url: None,
llm_compat_strict: true,
llm_timeout_secs: ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS,
+ llm_reasoning_effort: None,
consolidate_on_session_end: false,
capture_assistant: false,
strip_root_combinators: false,
@@ -992,7 +1001,6 @@ impl Config {
config.llm_timeout_secs
);
}
-
Ok(config)
}
@@ -1059,6 +1067,7 @@ impl Config {
.or_else(|| self.runtime_env.llm_base_url.clone()),
compat_strict: self.llm_compat_strict,
request_timeout_secs: self.llm_timeout_secs,
+ reasoning_effort: self.llm_reasoning_effort,
}))
}
@@ -1351,6 +1360,7 @@ fn normalize_home_dir(home: &str) -> Option<String> {
#[cfg(test)]
mod tests {
use super::*;
+ use rstest::rstest;
use secrecy::ExposeSecret;
use tempfile::TempDir;
@@ -1580,6 +1590,35 @@ mod tests {
);
}
+ fn load_reasoning_effort(raw: &str) -> anyhow::Result<Config> {
+ let tmp = TempDir::new().unwrap();
+ let config_path = tmp.path().join("config.toml");
+ std::fs::write(&config_path, format!("llm_reasoning_effort = \"{raw}\"\n")).unwrap();
+ Config::load(Some(&config_path), Some(tmp.path().to_path_buf()))
+ }
+
+ #[rstest]
+ #[case::none("none", ReasoningEffort::None)]
+ #[case::low("low", ReasoningEffort::Low)]
+ #[case::high("high", ReasoningEffort::High)]
+ fn load_accepts_reasoning_effort(#[case] raw: &str, #[case] expected: ReasoningEffort) {
+ let cfg = load_reasoning_effort(raw).unwrap();
+ assert_eq!(cfg.llm_reasoning_effort, Some(expected));
+ }
+
+ #[rstest]
+ #[case::unknown("ludicrous")]
+ #[case::uppercase("HIGH")]
+ fn load_rejects_invalid_reasoning_effort(#[case] raw: &str) {
+ let error =
+ load_reasoning_effort(raw).expect_err("invalid reasoning effort must fail closed");
+ let rendered = format!("{error:#}");
+ assert!(
+ rendered.contains("llm_reasoning_effort") && rendered.contains("unknown variant"),
+ "unexpected error: {rendered}"
+ );
+ }
+
#[test]
fn defaults_bound_consolidation_prompts_for_a_large_context_provider() {
let tmp = TempDir::new().unwrap();
@@ -2117,6 +2156,26 @@ mod tests {
provider.auth.require_openai_oauth_token_file().unwrap(),
tmp.path().join("auth.json")
);
+ assert_eq!(provider.reasoning_effort, None);
+ }
+
+ #[rstest]
+ #[case::unset(None)]
+ #[case::low(Some(ReasoningEffort::Low))]
+ #[case::none_wire(Some(ReasoningEffort::None))]
+ fn openai_oauth_provider_config_forwards_reasoning_effort(
+ #[case] effort: Option<ReasoningEffort>,
+ ) {
+ let tmp = TempDir::new().unwrap();
+ let cfg = Config {
+ data_dir: tmp.path().to_path_buf(),
+ llm_provider: Some("openai-oauth".into()),
+ llm_reasoning_effort: effort,
+ ..Config::default()
+ };
+
+ let provider = cfg.llm_provider_config().unwrap().unwrap();
+ assert_eq!(provider.reasoning_effort, effort);
}
#[test]
diff --git a/crates/ai-memory-llm/Cargo.toml b/crates/ai-memory-llm/Cargo.toml
index 8b6d8496..275742d7 100644
--- a/crates/ai-memory-llm/Cargo.toml
+++ b/crates/ai-memory-llm/Cargo.toml
@@ -14,6 +14,7 @@ anyhow.workspace = true
thiserror.workspace = true
serde.workspace = true
serde_json.workspace = true
+cognomen.workspace = true
schemars.workspace = true
secrecy.workspace = true
tokio.workspace = true
@@ -28,6 +29,7 @@ jiff.workspace = true
[dev-dependencies]
tokio = { workspace = true }
tempfile.workspace = true
+rstest.workspace = true
# In-process HTTP mock for the openai-compat strict-fallback tests.
# Scoped to dev-dependencies so production binaries don't pull it in.
wiremock = "0.6"
diff --git a/crates/ai-memory-llm/src/anthropic.rs b/crates/ai-memory-llm/src/anthropic.rs
index a1bd67c8..342b3a43 100644
--- a/crates/ai-memory-llm/src/anthropic.rs
+++ b/crates/ai-memory-llm/src/anthropic.rs
@@ -3,6 +3,7 @@
use std::time::Duration;
use async_trait::async_trait;
+use cognomen::Cognomen;
use secrecy::{ExposeSecret, SecretString};
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
@@ -11,7 +12,7 @@ use tracing::debug;
use crate::error::{LlmError, LlmResult};
use crate::provider::LlmProvider;
use crate::response::{provider_error_body, response_json_limited};
-use crate::types::{ChatRequest, ChatResponse, Role, Usage};
+use crate::types::{ChatRequest, ChatResponse, ReasoningEffort, Usage};
/// Default Anthropic API base.
pub const DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
@@ -46,6 +47,7 @@ pub struct AnthropicProvider {
base_url: String,
model: String,
timeout: Duration,
+ reasoning_effort: Option<ReasoningEffort>,
}
impl AnthropicProvider {
@@ -62,6 +64,7 @@ impl AnthropicProvider {
base_url: DEFAULT_BASE_URL.to_string(),
model: model.into(),
timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
+ reasoning_effort: None,
})
}
@@ -82,6 +85,7 @@ impl AnthropicProvider {
base_url: DEFAULT_BASE_URL.to_string(),
model: model.into(),
timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
+ reasoning_effort: None,
})
}
@@ -99,6 +103,15 @@ impl AnthropicProvider {
self.timeout = Duration::from_secs(secs);
self
}
+
+ /// Set Claude effort / thinking. `None` omits both fields so the model
+ /// default applies. On models that accept `output_config.effort`, a
+ /// configured value is mapped onto that field; `none` disables thinking.
+ #[must_use]
+ pub fn with_reasoning_effort(mut self, effort: Option<ReasoningEffort>) -> Self {
+ self.reasoning_effort = effort;
+ self
+ }
}
#[derive(Debug, Serialize)]
@@ -114,6 +127,22 @@ struct AnthropicRequest<'a> {
tools: Option<Vec<AnthropicTool>>,
#[serde(skip_serializing_if = "Option::is_none")]
tool_choice: Option<AnthropicToolChoice>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ output_config: Option<AnthropicOutputConfig>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ thinking: Option<AnthropicThinking>,
+}
+
+#[derive(Debug, Serialize)]
+struct AnthropicOutputConfig {
+ effort: ReasoningEffort,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(tag = "type", rename_all = "snake_case")]
+enum AnthropicThinking {
+ Adaptive,
+ Disabled,
}
#[derive(Debug, Serialize)]
@@ -220,10 +249,7 @@ impl AnthropicProvider {
.messages
.iter()
.map(|m| AnthropicMsg {
- role: match m.role {
- Role::User => "user",
- Role::Assistant => "assistant",
- },
+ role: m.role.as_ref(),
content: &m.content,
})
.collect();
@@ -240,13 +266,15 @@ impl AnthropicProvider {
),
None => (None, None),
};
- // Newer models reject ai-memory's non-default `temperature` with a
- // 400; omit the field so the API applies its own default.
- let temperature = if model_rejects_temperature(&self.model) {
- None
- } else {
- request.temperature
- };
+ let claude = ClaudeId::parse(&self.model);
+ let temperature = request
+ .temperature
+ .filter(|_| !claude.is_some_and(ClaudeId::rejects_temperature));
+ let (output_config, thinking) = self
+ .reasoning_effort
+ .zip(claude)
+ .map(|(effort, claude)| claude.reasoning_fields(effort))
+ .unwrap_or((None, None));
AnthropicRequest {
model: &self.model,
max_tokens: request.max_tokens,
@@ -255,6 +283,8 @@ impl AnthropicProvider {
temperature,
tools,
tool_choice,
+ output_config,
+ thinking,
}
}
@@ -300,77 +330,163 @@ impl AnthropicProvider {
}
}
-/// Models that reject ai-memory's non-default `temperature`.
-///
-/// Anthropic deprecated sampling parameters on the newer models: sending
-/// `temperature` to Claude 4.7+ or to Claude Mythos Preview returns a
-/// 400 with `` `temperature` is deprecated for this model. `` Every structured
-/// call site — bootstrap, consolidation, lint, auto-improve — passes 0.1-0.2,
-/// so without this the whole LLM pipeline is unusable on those models.
-/// Omitting the field lets the API apply its own default, the same escape
-/// hatch `openai.rs::model_requires_default_temperature` uses for gpt-5 /
-/// o-series.
+/// Modern `claude-<family>-<major>[-<minor>]` id, or dateless Mythos Preview.
///
-/// Anything we can't parse as a modern `claude-<family>-<major>[-<minor>]` id
-/// keeps the caller's value: the legacy `claude-3-5-sonnet-…` ordering and the
-/// whole Claude 4.0-4.6 line still accept sampling parameters, and a gateway
-/// proxying a non-Claude model behind this wire format must not be silently
-/// stripped either.
-fn model_rejects_temperature(model: &str) -> bool {
- if is_mythos_preview(model) {
- return true;
- }
- match claude_family_version(model) {
- Some((major, minor)) => major >= 5 || (major == 4 && minor >= 7),
- None => false,
- }
+/// Legacy family-last ids (`claude-3-5-sonnet-…`) and unversioned aliases
+/// (`claude-opus-latest`) stay `None` so we leave those requests alone.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum ClaudeId {
+ Released {
+ family: ClaudeFamily,
+ major: u32,
+ minor: u32,
+ },
+ MythosPreview,
}
-/// Match the dateless preview id, including vendor-prefixed variants.
-fn is_mythos_preview(model: &str) -> bool {
- let lower = model.to_ascii_lowercase();
- let Some(rest) = lower
- .find("claude-")
- .map(|start| &lower[start + "claude-".len()..])
- else {
- return false;
- };
- let mut parts = rest.split(|c: char| !c.is_ascii_alphanumeric());
- matches!(
- (parts.next(), parts.next()),
- (Some("mythos"), Some("preview"))
- )
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
+#[cognomen(lower)]
+enum ClaudeFamily {
+ Opus,
+ Sonnet,
+ Haiku,
+ Fable,
+ Mythos,
}
-/// Parse the `<major>[-<minor>]` version following the family name of a modern
-/// Claude id (`claude-opus-5`, `claude-sonnet-4-6`, `claude-opus-5@20260115`,
-/// `anthropic.claude-opus-5-v1:0`). Returns `None` for the legacy
-/// family-last ordering (`claude-3-5-sonnet-20241022`) and for ids that carry
-/// no numeric version (`claude-opus-latest`).
-fn claude_family_version(model: &str) -> Option<(u32, u32)> {
- let lower = model.to_ascii_lowercase();
- // Bedrock/Vertex ids carry a vendor prefix and a snapshot suffix around
- // the same `claude-<family>-<version>` core.
- let rest = &lower[lower.find("claude-")? + "claude-".len()..];
- let mut parts = rest.split(|c: char| !c.is_ascii_alphanumeric());
- if !matches!(
- parts.next()?,
- "opus" | "sonnet" | "haiku" | "fable" | "mythos"
- ) {
- return None;
+impl ClaudeFamily {
+ fn effort_since(self) -> Option<(u32, u32)> {
+ match self {
+ Self::Opus => Some((4, 5)),
+ Self::Sonnet => Some((4, 6)),
+ Self::Fable | Self::Mythos => Some((5, 0)),
+ Self::Haiku => None,
+ }
+ }
+
+ fn adaptive_since(self) -> Option<(u32, u32)> {
+ match self {
+ Self::Opus | Self::Sonnet => Some((4, 6)),
+ Self::Fable | Self::Mythos => Some((5, 0)),
+ Self::Haiku => None,
+ }
}
- let major = version_segment(parts.next()?)?;
- let minor = parts.next().and_then(version_segment).unwrap_or(0);
- Some((major, minor))
}
-/// A version segment is one or two digits; a longer digit run is a date
-/// snapshot (`claude-opus-4-20250514`), not a minor version.
-fn version_segment(segment: &str) -> Option<u32> {
- if segment.is_empty() || segment.len() > 2 || !segment.bytes().all(|b| b.is_ascii_digit()) {
- return None;
+impl ClaudeId {
+ fn parse(model: &str) -> Option<Self> {
+ let lower = model.to_ascii_lowercase();
+ // Bedrock/Vertex wrap the same `claude-<family>-…` core in a prefix
+ // and snapshot suffix.
+ let rest = lower.split_once("claude-")?.1;
+ let mut parts = rest.split(|c: char| !c.is_ascii_alphanumeric());
+ let family = parts.next()?.parse().ok()?;
+ match parts.next()? {
+ "preview" if family == ClaudeFamily::Mythos => Some(Self::MythosPreview),
+ major => Some(Self::Released {
+ family,
+ major: version_segment(major)?,
+ minor: parts.next().and_then(version_segment).unwrap_or(0),
+ }),
+ }
}
- segment.parse().ok()
+
+ fn family(self) -> ClaudeFamily {
+ match self {
+ Self::MythosPreview => ClaudeFamily::Mythos,
+ Self::Released { family, .. } => family,
+ }
+ }
+
+ fn meets(self, floor: Option<(u32, u32)>) -> bool {
+ match self {
+ Self::MythosPreview => true,
+ Self::Released { major, minor, .. } => floor.is_some_and(|min| (major, minor) >= min),
+ }
+ }
+
+ /// Claude 4.7+ and Mythos Preview 400 if we send a non-default
+ /// `temperature`. Unparsed ids keep the caller's value.
+ fn rejects_temperature(self) -> bool {
+ self.meets(Some((4, 7)))
+ }
+
+ fn supports_effort(self) -> bool {
+ self.meets(self.family().effort_since())
+ }
+
+ fn uses_adaptive_thinking(self) -> bool {
+ self.meets(self.family().adaptive_since())
+ }
+
+ /// Fable 5, Mythos 5, and Mythos Preview reject `thinking.type=disabled`.
+ fn thinking_always_on(self) -> bool {
+ match self {
+ Self::MythosPreview => true,
+ Self::Released {
+ family: ClaudeFamily::Fable | ClaudeFamily::Mythos,
+ major,
+ ..
+ } => major >= 5,
+ _ => false,
+ }
+ }
+
+ fn accepts_thinking_disabled(self) -> bool {
+ self.supports_effort() && !self.thinking_always_on()
+ }
+
+ /// Official effort availability: Opus 4.5 is `high` and below; Opus/Sonnet
+ /// 4.6 and Mythos Preview accept `max` but not `xhigh`; later models take
+ /// the full set.
+ fn clamp_output_effort(self, effort: ReasoningEffort) -> Option<ReasoningEffort> {
+ let mapped = effort.anthropic_output_effort()?;
+ Some(match (self, mapped) {
+ (
+ Self::Released {
+ family: ClaudeFamily::Opus,
+ major: 4,
+ minor: 5,
+ },
+ ReasoningEffort::XHigh | ReasoningEffort::Max,
+ ) => ReasoningEffort::High,
+ (
+ Self::MythosPreview
+ | Self::Released {
+ family: ClaudeFamily::Opus | ClaudeFamily::Sonnet,
+ major: 4,
+ minor: 6,
+ },
+ ReasoningEffort::XHigh,
+ ) => ReasoningEffort::Max,
+ (_, mapped) => mapped,
+ })
+ }
+
+ fn reasoning_fields(
+ self,
+ effort: ReasoningEffort,
+ ) -> (Option<AnthropicOutputConfig>, Option<AnthropicThinking>) {
+ match effort {
+ ReasoningEffort::None => (
+ None,
+ self.accepts_thinking_disabled()
+ .then_some(AnthropicThinking::Disabled),
+ ),
+ effort if self.supports_effort() => (
+ self.clamp_output_effort(effort)
+ .map(|effort| AnthropicOutputConfig { effort }),
+ self.uses_adaptive_thinking()
+ .then_some(AnthropicThinking::Adaptive),
+ ),
+ _ => (None, None),
+ }
+ }
+}
+
+/// One or two digits. Longer runs are date snapshots (`…-4-20250514`).
+fn version_segment(s: &str) -> Option<u32> {
+ s.parse().ok().filter(|_| (1..=2).contains(&s.len()))
}
#[cfg(test)]
@@ -378,7 +494,8 @@ mod tests {
use secrecy::SecretString;
use serde_json::json;
- use crate::types::ChatMessage;
+ use crate::types::{ChatMessage, ReasoningEffort};
+ use rstest::rstest;
use super::*;
@@ -444,10 +561,7 @@ mod tests {
fn chat_request() -> ChatRequest {
ChatRequest {
system: None,
- messages: vec![ChatMessage {
- role: Role::User,
- content: "x".into(),
- }],
+ messages: vec![ChatMessage::user("x")],
max_tokens: 256,
temperature: Some(0.2),
}
@@ -519,6 +633,56 @@ mod tests {
let plain = body_for("claude-opus-5", None);
assert!(plain.get("tools").is_none());
assert!(plain.get("tool_choice").is_none());
+ assert!(plain.get("output_config").is_none());
+ assert!(plain.get("thinking").is_none());
+ }
+
+ fn body_for_effort(model: &str, effort: ReasoningEffort) -> serde_json::Value {
+ let provider = AnthropicProvider::new(SecretString::from("sk-ant-test"), model)
+ .unwrap()
+ .with_reasoning_effort(Some(effort));
+ serde_json::to_value(provider.build_request(&chat_request(), None)).unwrap()
+ }
+
+ #[rstest]
+ #[case::sonnet_46_adaptive(
+ "claude-sonnet-4-6",
+ ReasoningEffort::Low,
+ Some("low"),
+ Some("adaptive")
+ )]
+ #[case::opus_5_disabled("claude-opus-5", ReasoningEffort::None, None, Some("disabled"))]
+ #[case::haiku_45_omits("claude-haiku-4-5", ReasoningEffort::Low, None, None)]
+ #[case::opus_45_effort_only("claude-opus-4-5", ReasoningEffort::High, Some("high"), None)]
+ #[case::mythos_preview_none_omits_disabled(
+ "claude-mythos-preview",
+ ReasoningEffort::None,
+ None,
+ None
+ )]
+ #[case::fable_5_none_omits_disabled("claude-fable-5", ReasoningEffort::None, None, None)]
+ #[case::sonnet_46_xhigh_clamps_max(
+ "claude-sonnet-4-6",
+ ReasoningEffort::XHigh,
+ Some("max"),
+ Some("adaptive")
+ )]
+ #[case::opus_45_max_clamps_high("claude-opus-4-5", ReasoningEffort::Max, Some("high"), None)]
+ fn maps_effort_to_native_thinking_fields(
+ #[case] model: &str,
+ #[case] effort: ReasoningEffort,
+ #[case] output_effort: Option<&str>,
+ #[case] thinking: Option<&str>,
+ ) {
+ let body = body_for_effort(model, effort);
+ match output_effort {
+ Some(expected) => assert_eq!(body["output_config"]["effort"], json!(expected)),
+ None => assert!(body.get("output_config").is_none()),
+ }
+ match thinking {
+ Some(expected) => assert_eq!(body["thinking"]["type"], json!(expected)),
+ None => assert!(body.get("thinking").is_none()),
+ }
}
#[test]
diff --git a/crates/ai-memory-llm/src/copilot.rs b/crates/ai-memory-llm/src/copilot.rs
index 81ca4b20..797e270f 100644
--- a/crates/ai-memory-llm/src/copilot.rs
+++ b/crates/ai-memory-llm/src/copilot.rs
@@ -20,7 +20,7 @@ use crate::error::{LlmError, LlmResult};
use crate::openai::{STRUCTURED_OUTPUT_SCHEMA_NAME, enforce_strict_object_schemas};
use crate::provider::LlmProvider;
use crate::response::{provider_error_body, response_json_limited};
-use crate::types::{ChatRequest, ChatResponse, Role, Usage};
+use crate::types::{ChatRequest, ChatResponse, Usage};
/// GitHub Copilot's public OAuth client id used by Copilot clients.
pub const GITHUB_COPILOT_CLIENT_ID: &str = "Iv1.b507a08c87ecfe98";
@@ -409,10 +409,7 @@ fn build_chat_request<'a>(
}
for m in &request.messages {
messages.push(CopilotMsg {
- role: match m.role {
- Role::User => "user",
- Role::Assistant => "assistant",
- },
+ role: m.role.as_ref(),
content: &m.content,
});
}
@@ -813,10 +810,7 @@ mod tests {
fn chat_request_uses_openai_compatible_shape() {
let request = ChatRequest {
system: Some("sys".into()),
- messages: vec![crate::types::ChatMessage {
- role: Role::User,
- content: "hello".into(),
- }],
+ messages: vec![crate::types::ChatMessage::user("hello")],
temperature: Some(0.2),
max_tokens: 123,
};
diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rs
index 89c1511d..0028bafd 100644
--- a/crates/ai-memory-llm/src/factory.rs
+++ b/crates/ai-memory-llm/src/factory.rs
@@ -103,6 +103,12 @@ pub struct ProviderConfig {
/// Sourced once from `AI_MEMORY_LLM_TIMEOUT_SECS` by `Config::load`;
/// defaults to [`crate::DEFAULT_REQUEST_TIMEOUT_SECS`].
pub request_timeout_secs: u64,
+ /// Optional reasoning / thinking effort. Each provider maps this to
+ /// its native request field (OpenAI `reasoning_effort`, OpenRouter
+ /// `reasoning`, xAI Grok `reasoning_effort`, Anthropic
+ /// `output_config.effort`, Codex `reasoning.effort`). `None` omits
+ /// the field so the model default applies. Gemini and Copilot ignore it.
+ pub reasoning_effort: Option<crate::ReasoningEffort>,
}
/// Embedding providers available to ai-memory.
@@ -236,13 +242,17 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>
ProviderChoice::Anthropic => {
let key = config.auth.require_api_key()?;
Ok(Arc::new(
- AnthropicProvider::new(key, config.model)?.with_timeout_secs(timeout),
+ AnthropicProvider::new(key, config.model)?
+ .with_timeout_secs(timeout)
+ .with_reasoning_effort(config.reasoning_effort),
))
}
ProviderChoice::OpenAi => {
let key = config.auth.require_api_key()?;
Ok(Arc::new(
- OpenAiProvider::new(key, config.model)?.with_timeout_secs(timeout),
+ OpenAiProvider::new(key, config.model)?
+ .with_timeout_secs(timeout)
+ .with_reasoning_effort(config.reasoning_effort),
))
}
ProviderChoice::Gemini => {
@@ -260,13 +270,16 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>
Ok(Arc::new(
OpenAiCompatProvider::new(base, config.auth.optional_api_key(), config.model)?
.with_strict(config.compat_strict)
- .with_timeout_secs(timeout),
+ .with_timeout_secs(timeout)
+ .with_reasoning_effort(config.reasoning_effort),
))
}
ProviderChoice::OpenAiOAuth => {
let path = config.auth.require_openai_oauth_token_file()?.to_path_buf();
Ok(Arc::new(
- OpenAiOAuthProvider::new(path, config.model)?.with_timeout_secs(timeout),
+ OpenAiOAuthProvider::new(path, config.model)?
+ .with_timeout_secs(timeout)
+ .with_reasoning_effort(config.reasoning_effort),
))
}
ProviderChoice::Copilot => {
@@ -281,12 +294,18 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>
if let Some(url) = config.base_url {
provider = provider.with_base_url(url);
}
- Ok(Arc::new(provider.with_timeout_secs(timeout)))
+ Ok(Arc::new(
+ provider
+ .with_timeout_secs(timeout)
+ .with_reasoning_effort(config.reasoning_effort),
+ ))
}
ProviderChoice::OpenCode => {
let key = config.auth.require_api_key()?;
Ok(Arc::new(
- OpenCodeProvider::new(key, config.model)?.with_timeout_secs(timeout),
+ OpenCodeProvider::new(key, config.model)?
+ .with_timeout_secs(timeout)
+ .with_reasoning_effort(config.reasoning_effort),
))
}
}
@@ -345,6 +364,7 @@ mod tests {
base_url: None,
compat_strict: false,
request_timeout_secs: crate::DEFAULT_REQUEST_TIMEOUT_SECS,
+ reasoning_effort: None,
};
let err = match build_provider(cfg) {
diff --git a/crates/ai-memory-llm/src/health.rs b/crates/ai-memory-llm/src/health.rs
index 30659d19..03e16dd5 100644
--- a/crates/ai-memory-llm/src/health.rs
+++ b/crates/ai-memory-llm/src/health.rs
@@ -6,6 +6,7 @@
use std::sync::{Arc, Mutex};
use async_trait::async_trait;
+use cognomen::Cognomen;
use jiff::Timestamp;
use serde::{Deserialize, Serialize};
@@ -63,8 +64,8 @@ impl ProviderHealth {
}
/// Wire-format provider-health status.
-#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "kebab-case")]
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Cognomen)]
+#[cognomen(kebab)]
pub enum ProviderHealthStatus {
/// The role has no provider configured.
#[default]
diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rs
index 2166a9e0..61bff084 100644
--- a/crates/ai-memory-llm/src/lib.rs
+++ b/crates/ai-memory-llm/src/lib.rs
@@ -95,4 +95,4 @@ pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_ZEN_BASE_URL, OpenCodeProvid
pub use provider::{LlmProvider, complete_structured};
pub use reranker::{LlmReranker, RerankCandidate, RerankScore, Reranker};
pub use stored_token::StoredOAuthToken;
-pub use types::{ChatMessage, ChatRequest, ChatResponse, Role, Usage};
+pub use types::{ChatMessage, ChatRequest, ChatResponse, ReasoningEffort, Role, Usage};
diff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rs
index da1e6b16..fdf532aa 100644
--- a/crates/ai-memory-llm/src/openai.rs
+++ b/crates/ai-memory-llm/src/openai.rs
@@ -11,7 +11,7 @@ use tracing::debug;
use crate::error::{LlmError, LlmResult};
use crate::provider::LlmProvider;
use crate::response::{provider_error_body, response_json_limited};
-use crate::types::{ChatRequest, ChatResponse, Role, Usage};
+use crate::types::{ChatRequest, ChatResponse, ReasoningEffort, Usage};
/// Default OpenAI API base.
pub const DEFAULT_BASE_URL: &str = "https://api.openai.com";
@@ -90,6 +90,7 @@ pub struct OpenAiProvider {
model: String,
dialect: RequestDialect,
timeout: Duration,
+ reasoning_effort: Option<ReasoningEffort>,
}
impl OpenAiProvider {
@@ -108,6 +109,7 @@ impl OpenAiProvider {
model: model.into(),
dialect: RequestDialect::Official,
timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
+ reasoning_effort: None,
})
}
@@ -142,6 +144,15 @@ impl OpenAiProvider {
self.dialect = dialect;
self
}
+
+ /// Set reasoning effort. `None` omits the field so the model default
+ /// applies. Official Chat Completions send `reasoning_effort`; OpenRouter
+ /// and xAI hosts use their native shapes.
+ #[must_use]
+ pub fn with_reasoning_effort(mut self, effort: Option<ReasoningEffort>) -> Self {
+ self.reasoning_effort = effort;
+ self
+ }
}
#[derive(Debug, Serialize)]
@@ -156,6 +167,19 @@ struct OpenAiRequest<'a> {
temperature: Option<f32>,
#[serde(skip_serializing_if = "Option::is_none")]
response_format: Option<OpenAiResponseFormat>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ reasoning_effort: Option<ReasoningEffort>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ reasoning: Option<OpenAiReasoning>,
+}
+
+#[derive(Debug, Serialize)]
+struct OpenAiReasoning {
+ effort: ReasoningEffort,
+ /// OpenRouter: keep thinking tokens out of `message.content` so
+ /// structured-output parse is not polluted.
+ #[serde(skip_serializing_if = "std::ops::Not::not")]
+ exclude: bool,
}
#[derive(Debug, Serialize)]
@@ -261,10 +285,7 @@ impl OpenAiProvider {
}
for m in &request.messages {
messages.push(OpenAiMsg {
- role: match m.role {
- Role::User => "user",
- Role::Assistant => "assistant",
- },
+ role: m.role.as_ref(),
content: &m.content,
});
}
@@ -296,6 +317,7 @@ impl OpenAiProvider {
(mt, mct, temp)
}
};
+ let (reasoning_effort, reasoning) = self.chat_reasoning_fields();
OpenAiRequest {
model: &self.model,
messages,
@@ -303,9 +325,23 @@ impl OpenAiProvider {
max_completion_tokens,
temperature,
response_format,
+ reasoning_effort,
+ reasoning,
}
}
+ /// Native reasoning payload for this host / dialect.
+ ///
+ /// Official OpenAI and generic openai-compat send top-level
+ /// `reasoning_effort`. OpenRouter's Chat Completions docs use
+ /// `reasoning: { effort, exclude }`. xAI Grok Chat Completions uses
+ /// `reasoning_effort` with a clamped value set (cannot disable).
+ fn chat_reasoning_fields(&self) -> (Option<ReasoningEffort>, Option<OpenAiReasoning>) {
+ self.reasoning_effort
+ .map(|effort| ReasoningHost::detect(self.dialect, &self.base_url).fields(effort))
+ .unwrap_or((None, None))
+ }
+
fn to_chat_response(&self, response: OpenAiResponse) -> ChatResponse {
let text = response
.choices
@@ -450,6 +486,47 @@ fn model_requires_default_temperature(model: &str) -> bool {
model_requires_max_completion_tokens(model)
}
+fn is_openrouter_base(url: &str) -> bool {
+ url.to_ascii_lowercase().contains("openrouter.ai")
+}
+
+fn is_xai_base(url: &str) -> bool {
+ let lower = url.to_ascii_lowercase();
+ lower.contains("api.x.ai") || lower.contains("://x.ai/") || lower.contains(".x.ai/")
+}
+
+/// Which reasoning object this Chat Completions host expects.
+#[derive(Debug, Clone, Copy)]
+enum ReasoningHost {
+ OpenAi,
+ OpenRouter,
+ Grok,
+}
+
+impl ReasoningHost {
+ fn detect(dialect: RequestDialect, base_url: &str) -> Self {
+ match dialect {
+ RequestDialect::Compat if is_openrouter_base(base_url) => Self::OpenRouter,
+ RequestDialect::Compat if is_xai_base(base_url) => Self::Grok,
+ RequestDialect::Official | RequestDialect::Compat => Self::OpenAi,
+ }
+ }
+
+ fn fields(self, effort: ReasoningEffort) -> (Option<ReasoningEffort>, Option<OpenAiReasoning>) {
+ match self {
+ Self::OpenRouter => (
+ None,
+ Some(OpenAiReasoning {
+ effort: effort.openai_wire_effort(),
+ exclude: true,
+ }),
+ ),
+ Self::Grok => (Some(effort.grok_chat_effort()), None),
+ Self::OpenAi => (Some(effort.openai_wire_effort()), None),
+ }
+ }
+}
+
/// Per-model output-token ceiling for the `Official` dialect.
///
/// OpenAI rejects requests above the model's published limit with
@@ -484,7 +561,8 @@ mod tests {
OpenAiProvider, RequestDialect, enforce_strict_object_schemas,
model_requires_max_completion_tokens, normalize_openai_base,
};
- use crate::types::{ChatMessage, ChatRequest, Role};
+ use crate::types::{ChatMessage, ChatRequest, ReasoningEffort, Role};
+ use rstest::rstest;
use schemars::JsonSchema;
use secrecy::SecretString;
use serde::{Deserialize, Serialize};
@@ -931,6 +1009,78 @@ mod tests {
assert_eq!(json["max_completion_tokens"], json!(64_000));
}
+ fn chat_reasoning_json(
+ dialect: RequestDialect,
+ base_url: Option<&str>,
+ model: &str,
+ effort: Option<ReasoningEffort>,
+ ) -> serde_json::Value {
+ let mut provider = OpenAiProvider::new(SecretString::new("test-key".into()), model)
+ .unwrap()
+ .with_dialect(dialect)
+ .with_reasoning_effort(effort);
+ if let Some(url) = base_url {
+ provider = provider.with_base_url(url);
+ }
+ serde_json::to_value(provider.build_request(&chat_request(), None)).unwrap()
+ }
+
+ #[rstest]
+ #[case::official_low(
+ RequestDialect::Official,
+ None,
+ "gpt-5.4-mini",
+ Some(ReasoningEffort::Low),
+ Some("low"),
+ None
+ )]
+ #[case::official_unset(RequestDialect::Official, None, "gpt-5.4-mini", None, None, None)]
+ #[case::openrouter_excludes_content(
+ RequestDialect::Compat,
+ Some("https://openrouter.ai/api/v1"),
+ "anthropic/claude-sonnet-4.6",
+ Some(ReasoningEffort::High),
+ None,
+ Some("high")
+ )]
+ #[case::xai_none_clamps_low(
+ RequestDialect::Compat,
+ Some("https://api.x.ai/v1"),
+ "grok-4.6",
+ Some(ReasoningEffort::None),
+ Some("low"),
+ None
+ )]
+ #[case::official_ultra_clamps_max(
+ RequestDialect::Official,
+ None,
+ "gpt-5.4-mini",
+ Some(ReasoningEffort::Ultra),
+ Some("max"),
+ None
+ )]
+ fn chat_request_uses_native_reasoning_shape(
+ #[case] dialect: RequestDialect,
+ #[case] base_url: Option<&str>,
+ #[case] model: &str,
+ #[case] effort: Option<ReasoningEffort>,
+ #[case] reasoning_effort: Option<&str>,
+ #[case] reasoning_object: Option<&str>,
+ ) {
+ let json = chat_reasoning_json(dialect, base_url, model, effort);
+ match reasoning_effort {
+ Some(expected) => assert_eq!(json["reasoning_effort"], json!(expected)),
+ None => assert!(json.get("reasoning_effort").is_none()),
+ }
+ match reasoning_object {
+ Some(expected) => {
+ assert_eq!(json["reasoning"]["effort"], json!(expected));
+ assert_eq!(json["reasoning"]["exclude"], json!(true));
+ }
+ None => assert!(json.get("reasoning").is_none()),
+ }
+ }
+
#[test]
fn normalize_openai_base_chat_completions() {
let ep = "chat/completions";
diff --git a/crates/ai-memory-llm/src/openai_compat.rs b/crates/ai-memory-llm/src/openai_compat.rs
index 21c63e2c..9a19f261 100644
--- a/crates/ai-memory-llm/src/openai_compat.rs
+++ b/crates/ai-memory-llm/src/openai_compat.rs
@@ -107,6 +107,14 @@ impl OpenAiCompatProvider {
self.inner = self.inner.with_timeout_secs(secs);
self
}
+
+ /// Forward reasoning effort to the inner Chat Completions client.
+ /// OpenRouter and xAI hosts use their native request shapes.
+ #[must_use]
+ pub fn with_reasoning_effort(mut self, effort: Option<crate::ReasoningEffort>) -> Self {
+ self.inner = self.inner.with_reasoning_effort(effort);
+ self
+ }
}
#[async_trait]
diff --git a/crates/ai-memory-llm/src/openai_oauth.rs b/crates/ai-memory-llm/src/openai_oauth.rs
index 79c1a64b..1b44bf11 100644
--- a/crates/ai-memory-llm/src/openai_oauth.rs
+++ b/crates/ai-memory-llm/src/openai_oauth.rs
@@ -22,7 +22,7 @@ use crate::provider::LlmProvider;
use crate::response::{provider_error_body, response_json_limited, response_text_limited};
use crate::stored_token::{StoredOAuthToken, refresh_grant};
use crate::text::truncate_with_ellipsis;
-use crate::types::{ChatRequest, ChatResponse, Role, Usage};
+use crate::types::{ChatRequest, ChatResponse, ReasoningEffort, Usage};
/// OpenAI OAuth issuer used by Codex/OpenCode.
pub const OPENAI_OAUTH_ISSUER: &str = "https://auth.openai.com";
@@ -139,6 +139,7 @@ pub struct OpenAiOAuthProvider {
token_path: PathBuf,
token: Mutex<OpenAiOAuthToken>,
timeout: Duration,
+ reasoning_effort: Option<ReasoningEffort>,
}
impl OpenAiOAuthProvider {
@@ -160,6 +161,7 @@ impl OpenAiOAuthProvider {
token_path,
token: Mutex::new(token),
timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
+ reasoning_effort: None,
})
}
@@ -171,6 +173,14 @@ impl OpenAiOAuthProvider {
self
}
+ /// Set Responses API `reasoning.effort`. `None` omits the field so the
+ /// model default applies.
+ #[must_use]
+ pub fn with_reasoning_effort(mut self, effort: Option<ReasoningEffort>) -> Self {
+ self.reasoning_effort = effort;
+ self
+ }
+
async fn current_token(&self) -> LlmResult<OpenAiOAuthToken> {
let mut guard = self.token.lock().await;
if guard.needs_refresh() {
@@ -238,7 +248,12 @@ impl LlmProvider for OpenAiOAuthProvider {
async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
let response = self
- .post(&build_request(&self.model, &request, None))
+ .post(&build_request(
+ &self.model,
+ &request,
+ None,
+ self.reasoning_effort,
+ ))
.await?;
Ok(into_chat_response(response))
}
@@ -257,7 +272,12 @@ impl LlmProvider for OpenAiOAuthProvider {
},
};
let response = self
- .post(&build_request(&self.model, &request, Some(response_format)))
+ .post(&build_request(
+ &self.model,
+ &request,
+ Some(response_format),
+ self.reasoning_effort,
+ ))
.await?;
let text = extract_output_text(&response).unwrap_or_default();
serde_json::from_str::<serde_json::Value>(&text).map_err(LlmError::from)
@@ -292,15 +312,13 @@ fn build_request<'a>(
model: &'a str,
request: &'a ChatRequest,
text: Option<CodexText>,
+ reasoning_effort: Option<ReasoningEffort>,
) -> CodexResponsesRequest<'a> {
let input = request
.messages
.iter()
.map(|msg| CodexInputMessage {
- role: match msg.role {
- Role::User => "user",
- Role::Assistant => "assistant",
- },
+ role: msg.role.as_ref(),
content: vec![CodexInputContent {
kind: "input_text",
text: &msg.content,
@@ -322,6 +340,9 @@ fn build_request<'a>(
store: false,
stream: true,
text,
+ reasoning: reasoning_effort.map(|effort| CodexReasoning {
+ effort: effort.openai_wire_effort(),
+ }),
}
}
@@ -444,6 +465,13 @@ struct CodexResponsesRequest<'a> {
stream: bool,
#[serde(skip_serializing_if = "Option::is_none")]
text: Option<CodexText>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ reasoning: Option<CodexReasoning>,
+}
+
+#[derive(Debug, Serialize)]
+struct CodexReasoning {
+ effort: ReasoningEffort,
}
#[derive(Debug, Serialize)]
@@ -566,6 +594,7 @@ fn extract_account_id_from_jwt(token: &str) -> Option<String> {
#[cfg(test)]
mod tests {
+ use rstest::rstest;
use serde_json::json;
use super::*;
@@ -699,22 +728,36 @@ mod tests {
fn codex_request_moves_system_to_instructions_and_omits_gpt5_temperature() {
let request = ChatRequest {
system: Some("sys".into()),
- messages: vec![crate::types::ChatMessage {
- role: Role::User,
- content: "hello".into(),
- }],
+ messages: vec![crate::types::ChatMessage::user("hello")],
temperature: Some(0.2),
max_tokens: 123,
};
- let value = serde_json::to_value(build_request("gpt-5.5", &request, None)).unwrap();
+ let value = serde_json::to_value(build_request("gpt-5.5", &request, None, None)).unwrap();
assert_eq!(value["instructions"], "sys");
assert_eq!(value["input"][0]["content"][0]["type"], "input_text");
assert!(value.get("max_output_tokens").is_none());
assert!(value.get("temperature").is_none());
+ assert!(value.get("reasoning").is_none());
assert_eq!(value["store"], false);
assert_eq!(value["stream"], true);
}
+ #[rstest]
+ #[case::omitted(None, None)]
+ #[case::low(Some(ReasoningEffort::Low), Some("low"))]
+ #[case::persistent_clamps_max(Some(ReasoningEffort::Persistent), Some("max"))]
+ fn codex_request_reasoning_effort(
+ #[case] effort: Option<ReasoningEffort>,
+ #[case] expected: Option<&str>,
+ ) {
+ let request = ChatRequest::user_prompt("hello");
+ let value = serde_json::to_value(build_request("gpt-5.5", &request, None, effort)).unwrap();
+ match expected {
+ Some(effort) => assert_eq!(value["reasoning"]["effort"], effort),
+ None => assert!(value.get("reasoning").is_none()),
+ }
+ }
+
#[test]
fn parse_sse_response_reconstructs_completed_payload() {
let body = concat!(
@@ -861,7 +904,8 @@ mod tests {
strict: true,
},
};
- let value = serde_json::to_value(build_request("gpt-5.5", &request, Some(text))).unwrap();
+ let value =
+ serde_json::to_value(build_request("gpt-5.5", &request, Some(text), None)).unwrap();
assert_eq!(value["text"]["format"]["type"], "json_schema");
assert_eq!(value["text"]["format"]["name"], "Result");
assert_eq!(value["text"]["format"]["strict"], true);
diff --git a/crates/ai-memory-llm/src/opencode.rs b/crates/ai-memory-llm/src/opencode.rs
index f1aa10c0..88d0efd9 100644
--- a/crates/ai-memory-llm/src/opencode.rs
+++ b/crates/ai-memory-llm/src/opencode.rs
@@ -45,6 +45,13 @@ impl OpenCodeProvider {
self.inner = self.inner.with_timeout_secs(secs);
self
}
+
+ /// Forward reasoning effort to the OpenAI-compatible Zen/Go client.
+ #[must_use]
+ pub fn with_reasoning_effort(mut self, effort: Option<crate::ReasoningEffort>) -> Self {
+ self.inner = self.inner.with_reasoning_effort(effort);
+ self
+ }
}
#[async_trait]
diff --git a/crates/ai-memory-llm/src/types.rs b/crates/ai-memory-llm/src/types.rs
index 58619fdd..ca53fd28 100644
--- a/crates/ai-memory-llm/src/types.rs
+++ b/crates/ai-memory-llm/src/types.rs
@@ -1,10 +1,11 @@
//! Provider-neutral request/response types.
+use cognomen::{Cognomen, Label};
use serde::{Deserialize, Serialize};
/// Message role in a chat turn.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "lowercase")]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
+#[cognomen(lower)]
pub enum Role {
/// Message from the user.
User,
@@ -93,3 +94,166 @@ pub struct ChatResponse {
/// Model identifier echoed by the provider.
pub model: String,
}
+
+/// Operator-facing reasoning / thinking effort.
+///
+/// Serde rejects unknown values at config load so a typo does not become a
+/// 400 on first consolidation. Each provider maps this onto its native
+/// request field:
+///
+/// - OpenAI Chat Completions / generic openai-compat: `reasoning_effort`
+/// (`ultra`/`persistent` clamp to `max`; those strings are not in the
+/// official Chat Completions enum)
+/// - OpenRouter: `reasoning.effort` (and excludes reasoning from `content`)
+/// - xAI Grok Chat Completions: `reasoning_effort` (`low`/`medium`/`high`/
+/// `xhigh`; reasoning cannot be disabled)
+/// - Anthropic Messages: `output_config.effort` plus adaptive/disabled
+/// `thinking` on models that accept those fields
+/// - ChatGPT/Codex Responses: `reasoning.effort` (same OpenAI wire clamp)
+///
+/// Gemini and Copilot ignore the key.
+///
+/// Omitting the config key (Rust `None`) leaves the model default;
+/// [`Self::None`] is the wire value `none` (disable reasoning where the
+/// backend allows it).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Cognomen)]
+#[cognomen(lower)]
+pub enum ReasoningEffort {
+ /// Disable reasoning (`none`).
+ None,
+ /// Lowest billed reasoning (`minimal`).
+ Minimal,
+ /// Low reasoning effort.
+ Low,
+ /// Medium reasoning effort.
+ Medium,
+ /// High reasoning effort.
+ High,
+ /// Extra-high reasoning effort (`xhigh`).
+ XHigh,
+ /// Maximum reasoning effort (`max`).
+ Max,
+ /// Codex-advertised `ultra` effort.
+ Ultra,
+ /// Codex-advertised `persistent` effort.
+ Persistent,
+}
+
+impl ReasoningEffort {
+ /// Canonical wire-format string.
+ #[must_use]
+ pub fn as_str(self) -> &'static str {
+ Label::as_str(&self)
+ }
+
+ /// xAI Grok Chat Completions only accepts `low`/`medium`/`high`/`xhigh`
+ /// and cannot disable reasoning. Closest supported value is used.
+ #[must_use]
+ pub const fn grok_chat_effort(self) -> Self {
+ match self {
+ Self::None | Self::Minimal => Self::Low,
+ Self::Max | Self::Ultra | Self::Persistent => Self::XHigh,
+ other => other,
+ }
+ }
+
+ /// OpenAI Chat Completions / Responses and OpenRouter accept
+ /// `none`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`. `ultra` and
+ /// `persistent` are not in that enum.
+ #[must_use]
+ pub const fn openai_wire_effort(self) -> Self {
+ match self {
+ Self::Ultra | Self::Persistent => Self::Max,
+ other => other,
+ }
+ }
+
+ /// Anthropic `output_config.effort` is `low`/`medium`/`high`/`xhigh`/
+ /// `max`. `none` is represented by disabling thinking instead.
+ #[must_use]
+ pub const fn anthropic_output_effort(self) -> Option<Self> {
+ match self {
+ Self::None => None,
+ Self::Minimal => Some(Self::Low),
+ Self::Ultra | Self::Persistent => Some(Self::Max),
+ other => Some(other),
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::ReasoningEffort;
+ use cognomen::Variants;
+ use rstest::rstest;
+
+ #[test]
+ fn reasoning_effort_roundtrips() {
+ assert_eq!(
+ ReasoningEffort::LABELS,
+ &[
+ "none",
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh",
+ "max",
+ "ultra",
+ "persistent",
+ ]
+ );
+ for &effort in ReasoningEffort::VARIANTS {
+ let raw = effort.as_str();
+ let parsed: ReasoningEffort = serde_json::from_value(serde_json::json!(raw)).unwrap();
+ assert_eq!(parsed, effort);
+ assert_eq!(effort, raw);
+ assert_eq!(
+ serde_json::to_value(effort).unwrap(),
+ serde_json::json!(raw)
+ );
+ }
+ }
+
+ #[rstest]
+ #[case::uppercase("HIGH")]
+ #[case::unknown("ludicrous")]
+ fn reasoning_effort_rejects_invalid(#[case] raw: &str) {
+ assert!(serde_json::from_value::<ReasoningEffort>(serde_json::json!(raw)).is_err());
+ }
+
+ #[rstest]
+ #[case::none(ReasoningEffort::None, ReasoningEffort::Low)]
+ #[case::minimal(ReasoningEffort::Minimal, ReasoningEffort::Low)]
+ #[case::max(ReasoningEffort::Max, ReasoningEffort::XHigh)]
+ #[case::ultra(ReasoningEffort::Ultra, ReasoningEffort::XHigh)]
+ fn grok_clamps_unsupported_effort(
+ #[case] input: ReasoningEffort,
+ #[case] expected: ReasoningEffort,
+ ) {
+ assert_eq!(input.grok_chat_effort(), expected);
+ }
+
+ #[rstest]
+ #[case::none(ReasoningEffort::None, None)]
+ #[case::minimal(ReasoningEffort::Minimal, Some(ReasoningEffort::Low))]
+ #[case::ultra(ReasoningEffort::Ultra, Some(ReasoningEffort::Max))]
+ #[case::high(ReasoningEffort::High, Some(ReasoningEffort::High))]
+ fn anthropic_maps_output_effort(
+ #[case] input: ReasoningEffort,
+ #[case] expected: Option<ReasoningEffort>,
+ ) {
+ assert_eq!(input.anthropic_output_effort(), expected);
+ }
+
+ #[rstest]
+ #[case::ultra(ReasoningEffort::Ultra, ReasoningEffort::Max)]
+ #[case::persistent(ReasoningEffort::Persistent, ReasoningEffort::Max)]
+ #[case::xhigh(ReasoningEffort::XHigh, ReasoningEffort::XHigh)]
+ fn openai_clamps_non_enum_effort(
+ #[case] input: ReasoningEffort,
+ #[case] expected: ReasoningEffort,
+ ) {
+ assert_eq!(input.openai_wire_effort(), expected);
+ }
+}
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index cd997219..38a1d15a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -576,6 +576,14 @@ ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / LLM_API_KEY
AI_MEMORY_LLM_BASE_URL for openai-compat (Ollama, vLLM)
AI_MEMORY_LLM_COMPAT_STRICT true by default; false disables response_format=json_schema
AI_MEMORY_LLM_TIMEOUT_SECS per-request timeout for chat providers; 300 by default
+AI_MEMORY_LLM_REASONING_EFFORT optional reasoning/thinking effort
+ (none|minimal|low|medium|high|xhigh|max|ultra|persistent)
+ mapped per provider: OpenAI `reasoning_effort`,
+ OpenRouter `reasoning.effort`, xAI Grok
+ `reasoning_effort`, Anthropic `output_config.effort`,
+ Codex `reasoning.effort`. Gemini and Copilot
+ ignore the key. Host-unsupported values are
+ clamped to each provider's published enum.
AI_MEMORY_RERANKER optional `llm`; reranks project/scopes query candidates
COPILOT_GITHUB_TOKEN optional GitHub token for copilot
GITHUB_COPILOT_API_TOKEN optional pre-minted Copilot API token
diff --git a/docs/install.md b/docs/install.md
index 9b58f787..005efc29 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1484,7 +1484,7 @@ If you set only the provider, ai-memory picks a sensible default:
| `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=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. |
+| `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=copilot` | `gpt-5.5` | GitHub Copilot Chat backend. ai-memory stores a GitHub user token in `<data_dir>/auth.json`, exchanges it for a short-lived Copilot API token, and refreshes before expiry. |
| `AI_MEMORY_LLM_PROVIDER=gemini` | `gemini-3.5-flash` | Google's hosted option with a generous free tier. ai-memory disables Gemini 3.5 Flash's default dynamic thinking so hidden thought tokens do not truncate strict JSON. Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`). |
| `AI_MEMORY_LLM_PROVIDER=opencode` | `claude-sonnet-4-6` | [OpenCode Zen/Go](https://opencode.ai) cloud API — OpenAI-compatible endpoint at `opencode.ai/zen/go/v1`. Set `OPENCODE_API_KEY` (key from `opencode.ai/auth`). Alias: `opencode-zen`. |
@@ -1626,8 +1626,10 @@ Use `ai-memory auth status` to check whether a token is present and
> 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). Reserve the high-effort reasoning models for
-> your coding agent.
+> 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
+> coding agent.
### GitHub Copilot
@@ -1685,6 +1687,17 @@ required. For OpenRouter (Kimi, DeepSeek, etc.):
-e LLM_API_KEY=sk-or-v1-...
```
+`AI_MEMORY_LLM_REASONING_EFFORT` is honoured on this path: OpenRouter hosts
+send `reasoning: { effort, exclude: true }`; `https://api.x.ai` (Grok)
+sends Chat Completions `reasoning_effort` (clamped to `low`/`medium`/`high`/
+`xhigh`, because Grok cannot disable reasoning); other compat endpoints send
+OpenAI-style `reasoning_effort`. Anthropic and Anthropic-OAuth map the same
+key to `output_config.effort` and adaptive/disabled thinking on models that
+accept those fields (Haiku 4.5 omits them so the default model does not 400;
+Fable 5 / Mythos 5 / Mythos Preview omit `thinking: disabled` because those
+models reject it). `ultra` and `persistent` clamp to `max` on OpenAI-style
+hosts. Gemini and Copilot ignore the key.
+
[Atlas Cloud](https://www.atlascloud.ai/models/qwen/qwen3.5-flash) uses the
same provider; no Atlas-specific ai-memory provider is needed. Pass its API key
through the generic compatibility credential:
diff --git a/evals/src/main.rs b/evals/src/main.rs
index 5c00b4f7..41a86753 100644
--- a/evals/src/main.rs
+++ b/evals/src/main.rs
@@ -372,6 +372,7 @@ impl From<ResolvedConfig> for ProviderConfig {
// same schema-constrained path operators receive.
compat_strict: true,
request_timeout_secs: ai_memory_llm::DEFAULT_REQUEST_TIMEOUT_SECS,
+ reasoning_effort: None,
}
}
}
diff --git a/packaging/env/ai-memory.env b/packaging/env/ai-memory.env
index 1944e8b5..db7bae48 100644
--- a/packaging/env/ai-memory.env
+++ b/packaging/env/ai-memory.env
@@ -8,5 +8,6 @@
# AI_MEMORY_ALLOWED_HOSTS=localhost,127.0.0.1,::1
# AI_MEMORY_LLM_PROVIDER=anthropic
# ANTHROPIC_API_KEY=sk-ant-...
+# AI_MEMORY_LLM_REASONING_EFFORT=low
# AI_MEMORY_EMBEDDING_PROVIDER=openai
# OPENAI_API_KEY=sk-...