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.mdindex 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.0editor-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 totell 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 workon real stores. Both read the entity index, which was populated onlyfrom an LLM consolidator's `entities:` frontmatter — absent on thediff --git a/README.md b/README.mdindex 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 providerupgrades 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), andany OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supportedfor consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatibleendpoints for embeddings. Configuration lives indiff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex 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.rsindex 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_urldiff --git a/crates/ai-memory-llm/src/factory.rs b/crates/ai-memory-llm/src/factory.rsindex 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.rsindex 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.rsindex 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_headersdiff --git a/crates/ai-memory-llm/src/openai_compat.rs b/crates/ai-memory-llm/src/openai_compat.rsindex 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.rsindex 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.rsindex 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 wirediff --git a/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rs b/crates/ai-memory-llm/tests/extra_headers_on_the_wire.rsindex 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.exampleindex 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.mdindex 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 | opencodeAI_MEMORY_LLM_MODEL optional when the provider has a default; e.g. claude-haiku-4-5, gpt-5.4-miniANTHROPIC_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_schemaAI_MEMORY_LLM_TIMEOUT_SECS per-request timeout for chat providers; 300 by defaultAI_MEMORY_LLM_REASONING_EFFORT optional reasoning/thinking effortdiff --git a/docs/install.md b/docs/install.mdindex 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 = [...]` instartup 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 askscallers for `x-opencode-session`, so that provider generates one per processunless `AI_MEMORY_LLM_HEADERS` supplies it. Set it explicitly when severalai-memory instances should be distinguishable, or should stay stable acrossdiff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 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. |