Skip to content

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

Rust

fix(llm): let the opencode provider reach Zen, not just Go

Lucas Oliveiraccdea09f95db
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d57b06d7..b697f54d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,13 +32,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
editor-plugin agent GitHub's Copilot API expects.
- The `opencode` provider now sends `x-opencode-session` on every request,
defaulting to one id per process when `AI_MEMORY_LLM_HEADERS` does not
- supply one. OpenCode Zen/Go documents third-party access to its endpoints
- and asks callers to identify themselves and to send that header for
- request correlation; traffic without it is reported as unattributable.
+ supply one. OpenCode's Go documentation covers third-party access to its
+ endpoints and asks callers to identify themselves; both Go and Zen
+ correlate requests by that header, and traffic without it is reported as
+ unattributable.
Set the header explicitly to keep the value stable across restarts or to
tell several ai-memory instances apart.
### Fixed
+- `AI_MEMORY_LLM_BASE_URL` now works with `AI_MEMORY_LLM_PROVIDER=opencode`.
+ The provider hardcoded OpenCode's **Go** endpoint and the factory dropped
+ the configured base URL without a word, so Zen's general catalogue at
+ `https://opencode.ai/zen/v1` was unreachable through it — Zen and Go are
+ separate products, not two spellings of one. Go remains the default, so
+ existing setups are unaffected; an override keeps the `x-opencode-session`
+ default and the user agent, since both endpoints correlate requests the
+ same way. Model ids are per catalogue, so set `AI_MEMORY_LLM_MODEL`
+ explicitly when overriding. `OPENCODE_ZEN_BASE_URL` is deprecated in
+ favour of `OPENCODE_GO_BASE_URL`: the constant named Zen but has always
+ held Go's URL. It keeps its value, so code compiled against it is
+ unaffected.
- `as_of` time-travel queries and the entity retrieval stream now work
on real stores. Both read the entity index, which was populated only
from an LLM consolidator's `entities:` frontmatter — absent on the
diff --git a/README.md b/README.md
index 331e441b..beaf73ba 100644
--- a/README.md
+++ b/README.md
@@ -286,7 +286,7 @@ The full model is in [`docs/security.md`](docs/security.md),
Optional. Everything works with zero LLM calls; adding a provider
upgrades session summaries and enables semantic search. Anthropic,
-OpenAI (incl. OAuth/Codex), GitHub Copilot, Gemini, OpenCode Zen, and
+OpenAI (incl. OAuth/Codex), GitHub Copilot, Gemini, OpenCode (Go and Zen), and
any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supported
for consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatible
endpoints for embeddings. Configuration lives in
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 77d16862..518c0ffd 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -1649,7 +1649,7 @@ pub enum LlmProviderChoice {
OpenaiOauth,
/// GitHub Copilot Chat backend.
Copilot,
- /// OpenCode Zen/Go cloud API.
+ /// OpenCode cloud API (Go by default; AI_MEMORY_LLM_BASE_URL selects Zen).
Opencode,
}
diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rs
index c358642f..aac387e3 100644
--- a/crates/ai-memory-cli/src/config.rs
+++ b/crates/ai-memory-cli/src/config.rs
@@ -182,7 +182,7 @@ pub struct Config {
/// `Name: Value` (or `Name=Value`) entries. Empty by default.
///
/// Exists for gateways that require a caller-identifying header:
- /// OpenCode Zen/Go asks callers for `x-opencode-session` plus a specific
+ /// OpenCode asks callers for `x-opencode-session` plus a specific
/// `User-Agent` and reports traffic carrying neither as an unknown
/// client. Set with
/// `AI_MEMORY_LLM_HEADERS=x-opencode-session=…,user-agent=…` (comma
@@ -1376,7 +1376,9 @@ impl Config {
}
}
- /// Base URL fallback for `llm-test --provider openai-compat`.
+ /// Base URL fallback for `llm-test`. Resolves exactly as
+ /// [`Self::provider_config`] does, so `llm-test` exercises the endpoint
+ /// `serve` will use — including an `opencode` override onto Zen.
#[must_use]
pub fn llm_test_base_url(&self) -> Option<String> {
self.llm_base_url
diff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rs
index ebc4f74f..f8603845 100644
--- a/crates/ai-memory-llm/src/factory.rs
+++ b/crates/ai-memory-llm/src/factory.rs
@@ -37,7 +37,8 @@ pub enum ProviderChoice {
Copilot,
/// Anthropic Messages API via a Claude-subscription OAuth token.
AnthropicOAuth,
- /// OpenCode Zen/Go cloud API (OpenAI-compatible endpoint).
+ /// OpenCode cloud API (OpenAI-compatible endpoint). Defaults to the Go
+ /// endpoint; `base_url` selects Zen's general catalogue instead.
OpenCode,
}
@@ -110,7 +111,7 @@ pub struct ProviderConfig {
/// the field so the model default applies. Gemini and Copilot ignore it.
pub reasoning_effort: Option<crate::ReasoningEffort>,
/// Operator-supplied HTTP headers sent on every chat request. Gateways
- /// that require a caller-identifying header (OpenCode Zen/Go asks for
+ /// that require a caller-identifying header (OpenCode asks for
/// `x-opencode-session` and a specific `User-Agent`) are configured
/// through this rather than per-provider special cases. Parsed once from
/// `AI_MEMORY_LLM_HEADERS` by `Config::load`; empty by default.
@@ -366,8 +367,16 @@ pub fn build_provider(config: ProviderConfig) -> LlmResult<Arc<dyn LlmProvider>>
}
ProviderChoice::OpenCode => {
let key = config.auth.require_api_key()?;
+ // Defaults to Go; an operator reaches Zen's general catalogue
+ // through AI_MEMORY_LLM_BASE_URL. Silently dropping the override
+ // (as this arm used to) left `provider=opencode` unable to speak
+ // to anything but Go.
+ let mut provider = OpenCodeProvider::new(key, config.model)?;
+ if let Some(url) = config.base_url {
+ provider = provider.with_base_url(url);
+ }
Ok(Arc::new(
- OpenCodeProvider::new(key, config.model)?
+ provider
.with_timeout_secs(timeout)
.with_reasoning_effort(config.reasoning_effort)
.with_extra_headers(extra_headers),
diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rs
index 8ed69944..62e1a72c 100644
--- a/crates/ai-memory-llm/src/lib.rs
+++ b/crates/ai-memory-llm/src/lib.rs
@@ -40,7 +40,7 @@ pub const DEFAULT_REQUEST_TIMEOUT_SECS: u64 = 300;
///
/// `reqwest` sends no `User-Agent` at all unless one is configured, so every
/// ai-memory provider request used to arrive anonymous. Gateways increasingly
-/// require callers to identify themselves — OpenCode Zen/Go asks for a
+/// require callers to identify themselves — OpenCode asks for a
/// specific agent ("no broad user agents") and reports traffic without one as
/// an unknown client — and an unattributable request is the one a rate
/// limiter throttles first.
@@ -111,7 +111,9 @@ pub use openai_oauth::{
OPENAI_OAUTH_TOKEN_URL, OpenAiExtras, OpenAiOAuthProvider, OpenAiOAuthToken,
OpenAiOAuthTokenResponse,
};
-pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_ZEN_BASE_URL, OpenCodeProvider};
+#[allow(deprecated)]
+pub use opencode::OPENCODE_ZEN_BASE_URL;
+pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_GO_BASE_URL, OpenCodeProvider};
pub use provider::{LlmProvider, complete_structured};
pub use reranker::{LlmReranker, RerankCandidate, RerankScore, Reranker};
pub use stored_token::StoredOAuthToken;
diff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rs
index 7ba9c32d..3a98512a 100644
--- a/crates/ai-memory-llm/src/openai.rs
+++ b/crates/ai-memory-llm/src/openai.rs
@@ -166,6 +166,13 @@ impl OpenAiProvider {
/// Headers this provider will send. Test-visible so the wrapper tests
/// (`OpenAiCompatProvider`, `OpenCodeProvider`) can assert delegation.
+ /// Endpoint the client will call. Test-visible so wrappers that default
+ /// the base URL and let it be overridden can assert which one is set.
+ #[cfg(test)]
+ pub(crate) fn base_url(&self) -> &str {
+ &self.base_url
+ }
+
#[cfg(test)]
pub(crate) fn extra_headers(&self) -> &ExtraHeaders {
&self.extra_headers
diff --git a/crates/ai-memory-llm/src/openai_compat.rs b/crates/ai-memory-llm/src/openai_compat.rs
index 136b5954..838f2cab 100644
--- a/crates/ai-memory-llm/src/openai_compat.rs
+++ b/crates/ai-memory-llm/src/openai_compat.rs
@@ -99,6 +99,18 @@ impl OpenAiCompatProvider {
self
}
+ /// Repoint the wrapped [`OpenAiProvider`] at another base URL.
+ ///
+ /// For a wrapper that constructs with a product default and lets the
+ /// operator override it — [`crate::OpenCodeProvider`] defaults to Go and
+ /// accepts Zen this way. `new` already takes a base URL, so a direct
+ /// caller has no need for this.
+ #[must_use]
+ pub fn with_base_url(mut self, url: impl Into<String>) -> Self {
+ self.inner = self.inner.with_base_url(url);
+ self
+ }
+
/// Override the per-request timeout on the wrapped
/// [`OpenAiProvider`]. The factory calls this with
/// `ProviderConfig::request_timeout_secs`.
@@ -125,9 +137,17 @@ impl OpenAiCompatProvider {
self
}
+ /// Endpoint the inner client will call. Test-visible so
+ /// [`crate::OpenCodeProvider`]'s tests can assert Go stays the default
+ /// and a Zen override takes effect.
+ #[cfg(test)]
+ pub(crate) fn base_url(&self) -> &str {
+ self.inner.base_url()
+ }
+
/// Headers the inner client will send. Test-visible so the
- /// [`crate::OpenCodeProvider`] tests can assert its Zen/Go defaults
- /// survive delegation.
+ /// [`crate::OpenCodeProvider`] tests can assert its Go defaults survive
+ /// delegation.
#[cfg(test)]
pub(crate) fn extra_headers(&self) -> &crate::ExtraHeaders {
self.inner.extra_headers()
diff --git a/crates/ai-memory-llm/src/opencode.rs b/crates/ai-memory-llm/src/opencode.rs
index e148b971..cb02c2a1 100644
--- a/crates/ai-memory-llm/src/opencode.rs
+++ b/crates/ai-memory-llm/src/opencode.rs
@@ -1,16 +1,23 @@
-//! OpenCode Zen/Go provider.
+//! OpenCode provider — Go by default, Zen on request.
//!
-//! Thin wrapper around [`OpenAiCompatProvider`] that bakes in the OpenCode
-//! Zen API base URL (`https://opencode.ai/zen/go/v1`) and names the provider
-//! `"opencode"`. Accepts an `sk-...` API key from `OPENCODE_API_KEY`.
+//! Thin wrapper around [`OpenAiCompatProvider`] that names the provider
+//! `"opencode"` and accepts an `sk-...` API key from `OPENCODE_API_KEY`.
//!
-//! Zen/Go documents third-party access to these endpoints and asks every
-//! tool using them to (1) not generate abusive traffic and (2) "properly
-//! identify itself (no broad user agents)". The agent string is
+//! OpenCode serves two endpoints, and they are different products rather
+//! than two names for one: **Go** ([`OPENCODE_GO_BASE_URL`]) is a smaller,
+//! cost-optimised model set, while **Zen** (`https://opencode.ai/zen/v1`)
+//! serves the full catalogue. Go is the default here; an operator selects
+//! Zen with `AI_MEMORY_LLM_BASE_URL`, which the factory passes to
+//! [`OpenCodeProvider::with_base_url`]. Model ids are per catalogue, so an
+//! override wants an explicit `AI_MEMORY_LLM_MODEL` too.
+//!
+//! Go's documentation covers third-party access and asks every tool using
+//! it to (1) not generate abusive traffic and (2) "properly identify itself
+//! (no broad user agents)". The agent string is
//! [`crate::DEFAULT_USER_AGENT`], applied to every provider; what is
-//! specific to this one is `x-opencode-session`, which Zen/Go correlates
-//! requests by and which this provider defaults under anything the operator
-//! set through `AI_MEMORY_LLM_HEADERS`.
+//! specific to this one is `x-opencode-session`, which both endpoints
+//! correlate requests by and which this provider defaults under anything
+//! the operator set through `AI_MEMORY_LLM_HEADERS`.
use async_trait::async_trait;
use reqwest::header::{HeaderName, HeaderValue};
@@ -21,17 +28,38 @@ use crate::openai_compat::OpenAiCompatProvider;
use crate::provider::LlmProvider;
use crate::types::{ChatRequest, ChatResponse, ExtraHeaders};
-/// Public OpenCode Zen/Go OpenAI-compatible base URL.
-pub const OPENCODE_ZEN_BASE_URL: &str = "https://opencode.ai/zen/go/v1";
+/// Public OpenCode **Go** OpenAI-compatible base URL, and this provider's
+/// default endpoint.
+///
+/// Go is a distinct product from Zen's general catalogue, not another
+/// spelling of it: Go serves a smaller, cost-optimised model set under
+/// `zen/go/v1`, while Zen serves the full catalogue at
+/// `https://opencode.ai/zen/v1`. Both authenticate with the same
+/// `OPENCODE_API_KEY` and both correlate requests by
+/// [`OPENCODE_SESSION_HEADER`], so reaching Zen is a base-URL override —
+/// see [`OpenCodeProvider::with_base_url`].
+pub const OPENCODE_GO_BASE_URL: &str = "https://opencode.ai/zen/go/v1";
+
+/// Misnomer for [`OPENCODE_GO_BASE_URL`], kept so the released public API
+/// keeps compiling: the value has always been Go's endpoint, never Zen's
+/// general one.
+#[deprecated(
+ since = "2.1.0",
+ note = "names Zen but holds Go's endpoint; use OPENCODE_GO_BASE_URL"
+)]
+pub const OPENCODE_ZEN_BASE_URL: &str = OPENCODE_GO_BASE_URL;
-/// Default model when `AI_MEMORY_LLM_MODEL` is not set.
+/// Default model when `AI_MEMORY_LLM_MODEL` is not set. Taken from Go's
+/// catalogue, so an operator overriding the base URL should set the model
+/// explicitly rather than assume this id exists on the other endpoint.
pub const OPENCODE_DEFAULT_MODEL: &str = "claude-sonnet-4-6";
-/// Session-correlation header Zen/Go asks callers to send. Requests arriving
-/// without it are reported as unattributable and may be rejected.
+/// Session-correlation header OpenCode asks callers to send, on Zen and Go
+/// alike. Requests arriving without it are reported as unattributable and
+/// may be rejected.
pub const OPENCODE_SESSION_HEADER: &str = "x-opencode-session";
-/// OpenCode Zen/Go LLM provider.
+/// OpenCode LLM provider, pointed at Go unless repointed at Zen.
///
/// Routes through `https://opencode.ai/zen/go/v1` using the OpenAI chat
/// completions wire format. Authenticate with the `sk-...` key obtained
@@ -41,22 +69,36 @@ pub struct OpenCodeProvider {
/// Sent as `x-opencode-session` unless the operator configured that
/// header. Generated once per provider instance — the provider is built
/// once per `serve` process, so a run's requests correlate to one id,
- /// which is what Zen/Go's metrics key on.
+ /// which is what OpenCode's metrics key on.
session: HeaderValue,
}
impl OpenCodeProvider {
- /// Construct an OpenCode Zen/Go provider.
+ /// Construct an OpenCode provider against Go, the default endpoint.
+ /// Call [`Self::with_base_url`] for Zen.
///
/// # Errors
/// Returns a `reqwest::Error` if the HTTP client cannot be built.
pub fn new(api_key: SecretString, model: impl Into<String>) -> LlmResult<Self> {
let session = new_session_id();
- let inner = OpenAiCompatProvider::new(OPENCODE_ZEN_BASE_URL, Some(api_key), model.into())?
+ let inner = OpenAiCompatProvider::new(OPENCODE_GO_BASE_URL, Some(api_key), model.into())?
.with_extra_headers(with_session_default(&session, ExtraHeaders::default()));
Ok(Self { inner, session })
}
+ /// Point the provider at a different OpenCode endpoint — Zen's general
+ /// catalogue (`https://opencode.ai/zen/v1`) instead of Go's default.
+ ///
+ /// The factory calls this with `ProviderConfig::base_url`
+ /// (`AI_MEMORY_LLM_BASE_URL`). The session header and user agent are
+ /// unaffected: both endpoints correlate requests the same way, so the
+ /// override changes where requests go, not how they identify themselves.
+ #[must_use]
+ pub fn with_base_url(mut self, url: impl Into<String>) -> Self {
+ self.inner = self.inner.with_base_url(url);
+ self
+ }
+
/// Override the per-request timeout on the wrapped
/// [`OpenAiCompatProvider`]. The factory calls this with
/// `ProviderConfig::request_timeout_secs`.
@@ -66,7 +108,7 @@ impl OpenCodeProvider {
self
}
- /// Forward reasoning effort to the OpenAI-compatible Zen/Go client.
+ /// Forward reasoning effort to the OpenAI-compatible OpenCode client.
#[must_use]
pub fn with_reasoning_effort(mut self, effort: Option<crate::ReasoningEffort>) -> Self {
self.inner = self.inner.with_reasoning_effort(effort);
@@ -83,7 +125,7 @@ impl OpenCodeProvider {
}
}
-/// A fresh session id. Prefixed so the value is self-describing in Zen/Go's
+/// A fresh session id. Prefixed so the value is self-describing in OpenCode's
/// metrics rather than a bare UUID.
fn new_session_id() -> HeaderValue {
HeaderValue::try_from(format!("ai-memory-{}", uuid::Uuid::new_v4()))
@@ -136,13 +178,52 @@ mod tests {
assert_eq!(provider.model(), "model-x");
}
+ /// Go and Zen are different endpoints; the default is Go's.
#[test]
- fn public_constants_point_at_zen_base_url() {
- assert_eq!(OPENCODE_ZEN_BASE_URL, "https://opencode.ai/zen/go/v1");
+ fn the_default_base_url_is_gos_endpoint() {
+ assert_eq!(OPENCODE_GO_BASE_URL, "https://opencode.ai/zen/go/v1");
assert!(!OPENCODE_DEFAULT_MODEL.is_empty());
}
- /// Zen/Go reports a request without this header as unattributable, so a
+ /// The deprecated name kept its value, so code compiled against v2.0
+ /// keeps hitting the endpoint it already hit.
+ #[test]
+ #[allow(deprecated)]
+ fn the_deprecated_alias_still_resolves_to_go() {
+ assert_eq!(OPENCODE_ZEN_BASE_URL, OPENCODE_GO_BASE_URL);
+ }
+
+ /// Zen's general catalogue is reachable, and is not the default — the
+ /// bug this pair pins is a base URL that could not be overridden.
+ #[test]
+ fn with_base_url_repoints_the_provider_at_zen() {
+ let go = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x").unwrap();
+ assert_eq!(go.inner.base_url(), OPENCODE_GO_BASE_URL);
+
+ let zen = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x")
+ .unwrap()
+ .with_base_url("https://opencode.ai/zen/v1");
+ assert_eq!(zen.inner.base_url(), "https://opencode.ai/zen/v1");
+ }
+
+ /// Overriding the endpoint must not cost the caller its identity: both
+ /// endpoints correlate by the same header.
+ #[test]
+ fn a_zen_override_keeps_the_session_header() {
+ let provider = OpenCodeProvider::new(SecretString::from("sk-test"), "model-x")
+ .unwrap()
+ .with_base_url("https://opencode.ai/zen/v1");
+ assert!(
+ provider
+ .inner
+ .extra_headers()
+ .get(OPENCODE_SESSION_HEADER)
+ .is_some_and(|v| v.starts_with("ai-memory-")),
+ "session header lost when the base URL was overridden"
+ );
+ }
+
+ /// OpenCode reports a request without this header as unattributable, so a
/// zero-config `opencode` provider must supply one.
#[test]
fn zero_config_provider_sends_a_session_header() {
diff --git a/crates/ai-memory-llm/src/types.rs b/crates/ai-memory-llm/src/types.rs
index efae28e4..ac6e19cc 100644
--- a/crates/ai-memory-llm/src/types.rs
+++ b/crates/ai-memory-llm/src/types.rs
@@ -203,7 +203,7 @@ impl ReasoningEffort {
/// Operator-supplied HTTP headers attached to every chat request.
///
-/// Some gateways require a caller-identifying header: OpenCode Zen/Go asks
+/// Some gateways require a caller-identifying header: OpenCode asks
/// every tool on its endpoint to send `x-opencode-session` and to identify
/// itself with a specific `User-Agent`, and flags accounts whose traffic
/// carries neither. Rather than teach each provider one gateway's wire
diff --git a/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs b/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs
index a7c5bfa6..d180c129 100644
--- a/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs
+++ b/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs
@@ -13,6 +13,7 @@ use ai_memory_llm::types::ChatRequest;
use ai_memory_llm::{
DEFAULT_USER_AGENT, ExtraHeaders, ProviderAuth, ProviderChoice, ProviderConfig, build_provider,
};
+use secrecy::SecretString;
use serde_json::json;
use wiremock::matchers::{method, path};
use wiremock::{Mock, MockServer, Request, ResponseTemplate};
@@ -119,3 +120,54 @@ async fn provider_owned_headers_survive_alongside_operator_headers() {
"provider auth must be sent exactly once"
);
}
+
+/// The `opencode` provider defaults to Go, so a base URL an operator sets
+/// must actually redirect it — this is the regression the silently-dropped
+/// `ProviderConfig::base_url` caused. Driving it against a mock is the only
+/// way to see *where* the request went.
+#[tokio::test]
+async fn an_operator_base_url_redirects_the_opencode_provider() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/v1/chat/completions"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(ok_body()))
+ .mount(&server)
+ .await;
+
+ let provider = build_provider(ProviderConfig {
+ provider: ProviderChoice::OpenCode,
+ model: "mistral-nemo".into(),
+ auth: ProviderAuth::required_api_key_from_env(
+ "OPENCODE_API_KEY",
+ Some(SecretString::from("sk-test")),
+ ),
+ base_url: Some(server.uri()),
+ compat_strict: false,
+ request_timeout_secs: 30,
+ reasoning_effort: None,
+ extra_headers: ExtraHeaders::default(),
+ })
+ .expect("provider builds");
+
+ provider
+ .complete(ChatRequest::user_prompt("hi"))
+ .await
+ .expect("the override must reach the mock, not opencode.ai");
+
+ let received = server
+ .received_requests()
+ .await
+ .expect("mock recorded requests");
+ assert_eq!(received.len(), 1, "request did not reach the override");
+
+ // Redirecting must not cost the caller its identity: Zen and Go
+ // correlate requests by the same header.
+ let request = &received[0];
+ assert!(
+ values(request, "x-opencode-session")
+ .first()
+ .is_some_and(|v| v.starts_with("ai-memory-")),
+ "session header lost when the base URL was overridden"
+ );
+ assert_eq!(values(request, "user-agent"), vec![DEFAULT_USER_AGENT]);
+}
diff --git a/docker/.env.production.example b/docker/.env.production.example
index 78330c03..c18ffee5 100644
--- a/docker/.env.production.example
+++ b/docker/.env.production.example
@@ -27,9 +27,13 @@
# openai-compat -> Any OpenAI-compatible endpoint: Ollama, vLLM,
# LM Studio, OpenRouter, Together, etc. Set
# AI_MEMORY_LLM_BASE_URL + LLM_API_KEY.
-# opencode -> OpenCode Zen/Go cloud (https://opencode.ai/zen/go/v1).
+# opencode -> OpenCode cloud. Defaults to the Go endpoint
+# (https://opencode.ai/zen/go/v1), a cost-optimised
+# subset. For Zen's full catalogue set
+# AI_MEMORY_LLM_BASE_URL=https://opencode.ai/zen/v1 and
+# an AI_MEMORY_LLM_MODEL from that catalogue.
# Get your key at opencode.ai/auth. Set OPENCODE_API_KEY.
-# Default model: claude-sonnet-4-6.
+# Default model: claude-sonnet-4-6 (a Go model id).
#
# Without AI_MEMORY_LLM_PROVIDER set, consolidation falls back to
# rule-based summaries (no LLM cost; lower-signal handoffs).
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index b6f6ba5b..782e3bc4 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -595,7 +595,9 @@ AI_MEMORY_LLM_PROVIDER anthropic | anthropic-oauth | openai | openai-oauth |
gemini | openai-compat | opencode
AI_MEMORY_LLM_MODEL optional when the provider has a default; e.g. claude-haiku-4-5, gpt-5.4-mini
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_BASE_URL required for openai-compat (Ollama, vLLM); optional override for
+ opencode (defaults to the Go endpoint, set
+ https://opencode.ai/zen/v1 for Zen's catalogue)
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
diff --git a/docs/install.md b/docs/install.md
index 44bf453e..4b3d25c7 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1499,7 +1499,7 @@ If you set only the provider, ai-memory picks a sensible default:
| `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`. |
+| `AI_MEMORY_LLM_PROVIDER=opencode` | `claude-sonnet-4-6` | [OpenCode](https://opencode.ai) cloud API. Defaults to the **Go** endpoint, `opencode.ai/zen/go/v1` — a cost-optimised model subset. For **Zen**'s full catalogue, set `AI_MEMORY_LLM_BASE_URL=https://opencode.ai/zen/v1` plus an `AI_MEMORY_LLM_MODEL` from it; the default model id is Go's. Both take `OPENCODE_API_KEY` (key from `opencode.ai/auth`) and both get `x-opencode-session`. Alias: `opencode-zen` — historical, and it selects Go like the others; the endpoint is chosen by the base URL, not the alias. |
| `AI_MEMORY_EMBEDDING_PROVIDER=openai` | `text-embedding-3-small` (1536-dim) | 5× cheaper than `-3-large` with marginal recall loss. |
| `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1` | `openai/text-embedding-3-small` via [OpenRouter](https://openrouter.ai) | Uses `EMBEDDING_API_KEY`, else reuses `LLM_API_KEY` or `OPENAI_API_KEY`, with the OpenAI-compatible embedding client. |
| `AI_MEMORY_EMBEDDING_PROVIDER=openai` + `AI_MEMORY_EMBEDDING_BASE_URL=https://api.orcarouter.ai/v1` | `openai/text-embedding-3-small` via [OrcaRouter](https://www.orcarouter.ai) | Uses `EMBEDDING_API_KEY`, else reuses `LLM_API_KEY`, with the OpenAI-compatible embedding client. |
@@ -1781,7 +1781,7 @@ cannot contain a comma through the env var; use `llm_headers = [...]` in
startup rather than duplicated onto the request. An entry for `user-agent`
overrides the default. Values are never logged.
-The `opencode` provider needs no configuration for this: OpenCode Zen/Go asks
+The `opencode` provider needs no configuration for this: OpenCode asks
callers for `x-opencode-session`, so that provider generates one per process
unless `AI_MEMORY_LLM_HEADERS` supplies it. Set it explicitly when several
ai-memory instances should be distinguishable, or should stay stable across
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 30ce3174..e6deae35 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -34,5 +34,5 @@
| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
| Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. |
| Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. |
-| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
+| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
| Embedding providers | Supported | OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM. |