Skip to content

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

Rust

fix(llm): identify OpenCode Go requests (#608)

Lucas do Amaral Saboyadc0584c958c9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa882713..8049f5c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Fixed
+- OpenCode Go requests now send `User-Agent: ai-memory/<version>` and a
+ per-operation `x-opencode-session` header. Session consolidation and
+ auto-improvement reuse the captured ai-memory session ID, while retries and
+ structured-output fallback keep the same ID instead of appearing as unrelated
+ requests (#608).
- `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/crates/ai-memory-consolidate/src/auto_improve.rs b/crates/ai-memory-consolidate/src/auto_improve.rs
index e7a19880..9895258d 100644
--- a/crates/ai-memory-consolidate/src/auto_improve.rs
+++ b/crates/ai-memory-consolidate/src/auto_improve.rs
@@ -12,7 +12,9 @@ use std::process::Stdio;
use std::time::Duration;
use ai_memory_core::{Observation, PagePath, ProjectId, SessionId, WorkspaceId};
-use ai_memory_llm::{ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured};
+use ai_memory_llm::{
+ ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured_with_operation_id,
+};
use ai_memory_store::{AutoImproveRejectionSummary, BriefingPage, ReaderPool, StoredPageBody};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize, de};
@@ -513,7 +515,8 @@ pub async fn run_auto_improve_review(
max_tokens: DEFAULT_REVIEW_MAX_TOKENS,
temperature: Some(0.1),
};
- let raw: AutoImproveLlmResponse = complete_structured(llm, request).await?;
+ let raw: AutoImproveLlmResponse =
+ complete_structured_with_operation_id(llm, request, session_id.into()).await?;
let (mut proposals, mut rejected_candidates, mut warnings) =
validate_response(raw, &cfg, &existing_index);
rejected_candidates.extend(prompt_input.rejected_candidates);
diff --git a/crates/ai-memory-consolidate/src/consolidator.rs b/crates/ai-memory-consolidate/src/consolidator.rs
index ce815eac..8c82def6 100644
--- a/crates/ai-memory-consolidate/src/consolidator.rs
+++ b/crates/ai-memory-consolidate/src/consolidator.rs
@@ -8,7 +8,9 @@
use std::sync::Arc;
use ai_memory_core::{AgentKind, Observation, PagePath, ProjectId, SessionId, Tier, WorkspaceId};
-use ai_memory_llm::{ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured};
+use ai_memory_llm::{
+ ChatMessage, ChatRequest, LlmError, LlmProvider, Role, complete_structured_with_operation_id,
+};
use ai_memory_store::{ReaderPool, WriterHandle};
use ai_memory_wiki::{AdmissionContext, AdmissionOp, Wiki, WritePageRequest};
use thiserror::Error;
@@ -187,7 +189,8 @@ impl Consolidator {
model = self.llm.model(),
"consolidating session"
);
- let page: ConsolidatedPage = complete_structured(&*self.llm, request).await?;
+ let page: ConsolidatedPage =
+ complete_structured_with_operation_id(&*self.llm, request, session_id.into()).await?;
let frontmatter = build_frontmatter(&page, session_id, agent_kind);
let id = self
@@ -481,7 +484,7 @@ impl Consolidator {
"consolidating session (multi-page)",
);
let batch: ConsolidatedBatch =
- ai_memory_llm::complete_structured(&*self.llm, request).await?;
+ complete_structured_with_operation_id(&*self.llm, request, session_id.into()).await?;
// `dry_run` is always false past the early return above, so every
// update here is a real write.
diff --git a/crates/ai-memory-llm/src/lib.rs b/crates/ai-memory-llm/src/lib.rs
index e2778e23..134266dc 100644
--- a/crates/ai-memory-llm/src/lib.rs
+++ b/crates/ai-memory-llm/src/lib.rs
@@ -96,7 +96,9 @@ pub use openai_oauth::{
OpenAiOAuthTokenResponse,
};
pub use opencode::{OPENCODE_DEFAULT_MODEL, OPENCODE_ZEN_BASE_URL, OpenCodeProvider};
-pub use provider::{LlmProvider, complete_structured};
+pub use provider::{LlmProvider, complete_structured, complete_structured_with_operation_id};
pub use reranker::{LlmReranker, RerankCandidate, RerankScore, Reranker};
pub use stored_token::StoredOAuthToken;
-pub use types::{ChatMessage, ChatRequest, ChatResponse, ReasoningEffort, Role, Usage};
+pub use types::{
+ ChatMessage, ChatRequest, ChatResponse, LlmOperationId, ReasoningEffort, Role, Usage,
+};
diff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rs
index 7b951bf5..e8b9304e 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, ReasoningEffort, Usage};
+use crate::types::{ChatRequest, ChatResponse, LlmOperationId, ReasoningEffort, Usage};
/// Default OpenAI API base.
pub const DEFAULT_BASE_URL: &str = "https://api.openai.com";
@@ -91,6 +91,13 @@ pub struct OpenAiProvider {
dialect: RequestDialect,
timeout: Duration,
reasoning_effort: Option<ReasoningEffort>,
+ client_headers: Option<ClientHeaders>,
+}
+
+#[derive(Debug, Clone, Copy)]
+struct ClientHeaders {
+ user_agent: &'static str,
+ operation_id: &'static str,
}
impl OpenAiProvider {
@@ -110,6 +117,7 @@ impl OpenAiProvider {
dialect: RequestDialect::Official,
timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
reasoning_effort: None,
+ client_headers: None,
})
}
@@ -153,6 +161,18 @@ impl OpenAiProvider {
self.reasoning_effort = effort;
self
}
+
+ pub(crate) fn with_client_headers(
+ mut self,
+ user_agent: &'static str,
+ operation_id: &'static str,
+ ) -> Self {
+ self.client_headers = Some(ClientHeaders {
+ user_agent,
+ operation_id,
+ });
+ self
+ }
}
#[derive(Debug, Serialize)]
@@ -236,14 +256,47 @@ impl LlmProvider for OpenAiProvider {
}
async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
- let response = self.post(&self.build_request(&request, None)).await?;
+ self.complete_with_operation_id(request, LlmOperationId::new())
+ .await
+ }
+
+ async fn complete_with_operation_id(
+ &self,
+ request: ChatRequest,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<ChatResponse> {
+ let response = self
+ .post(&self.build_request(&request, None), operation_id)
+ .await?;
Ok(self.to_chat_response(response))
}
async fn complete_structured_raw(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ ) -> LlmResult<serde_json::Value> {
+ self.complete_structured_raw_with_operation_id(request, schema, LlmOperationId::new())
+ .await
+ }
+
+ async fn complete_structured_raw_with_operation_id(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<serde_json::Value> {
+ self.complete_structured(request, schema, operation_id)
+ .await
+ }
+}
+
+impl OpenAiProvider {
+ async fn complete_structured(
&self,
request: ChatRequest,
mut schema: serde_json::Value,
+ operation_id: LlmOperationId,
) -> LlmResult<serde_json::Value> {
// Strict-mode normalisation is an `Official` concern — compat
// backends typically ignore `response_format` entirely and fall
@@ -259,7 +312,10 @@ impl LlmProvider for OpenAiProvider {
},
};
let response = self
- .post(&self.build_request(&request, Some(response_format)))
+ .post(
+ &self.build_request(&request, Some(response_format)),
+ operation_id,
+ )
.await?;
let text = response
.choices
@@ -268,9 +324,7 @@ impl LlmProvider for OpenAiProvider {
.unwrap_or("");
serde_json::from_str::<serde_json::Value>(text).map_err(LlmError::from)
}
-}
-impl OpenAiProvider {
fn build_request<'a>(
&'a self,
request: &'a ChatRequest,
@@ -359,18 +413,25 @@ impl OpenAiProvider {
}
}
- async fn post<B: Serialize>(&self, body: &B) -> LlmResult<OpenAiResponse> {
+ async fn post<B: Serialize>(
+ &self,
+ body: &B,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<OpenAiResponse> {
let url = normalize_openai_base(&self.base_url, "chat/completions");
debug!(url, "POST openai");
- let resp = self
+ let mut request = self
.client
.post(&url)
.timeout(self.timeout)
.bearer_auth(self.api_key.expose_secret())
.header("content-type", "application/json")
- .json(body)
- .send()
- .await?;
+ .json(body);
+ if let Some(headers) = self.client_headers {
+ request = request.header(reqwest::header::USER_AGENT, headers.user_agent);
+ request = request.header(headers.operation_id, operation_id.to_string());
+ }
+ let resp = request.send().await?;
let status = resp.status();
if !status.is_success() {
let body = provider_error_body(resp).await;
diff --git a/crates/ai-memory-llm/src/openai_compat.rs b/crates/ai-memory-llm/src/openai_compat.rs
index 9a19f261..5fa1ff6f 100644
--- a/crates/ai-memory-llm/src/openai_compat.rs
+++ b/crates/ai-memory-llm/src/openai_compat.rs
@@ -18,7 +18,7 @@ use crate::error::{LlmError, LlmResult};
use crate::openai::{OpenAiProvider, RequestDialect, enforce_strict_object_schemas};
use crate::provider::LlmProvider;
use crate::text::{suffix_within_bytes, truncate_with_ellipsis};
-use crate::types::{ChatRequest, ChatResponse};
+use crate::types::{ChatRequest, ChatResponse, LlmOperationId};
// Compiled once. Matches <think>, <thinking>, <analysis>, <reasoning> blocks
// (case-insensitive, non-greedy, DOTALL) that reasoning models emit before
@@ -115,6 +115,15 @@ impl OpenAiCompatProvider {
self.inner = self.inner.with_reasoning_effort(effort);
self
}
+
+ pub(crate) fn with_client_headers(
+ mut self,
+ user_agent: &'static str,
+ operation_id: &'static str,
+ ) -> Self {
+ self.inner = self.inner.with_client_headers(user_agent, operation_id);
+ self
+ }
}
#[async_trait]
@@ -128,13 +137,46 @@ impl LlmProvider for OpenAiCompatProvider {
}
async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
- self.inner.complete(request).await
+ self.complete_with_operation_id(request, LlmOperationId::new())
+ .await
+ }
+
+ async fn complete_with_operation_id(
+ &self,
+ request: ChatRequest,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<ChatResponse> {
+ self.inner
+ .complete_with_operation_id(request, operation_id)
+ .await
}
async fn complete_structured_raw(
&self,
request: ChatRequest,
schema: serde_json::Value,
+ ) -> LlmResult<serde_json::Value> {
+ self.complete_structured_raw_with_operation_id(request, schema, LlmOperationId::new())
+ .await
+ }
+
+ async fn complete_structured_raw_with_operation_id(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<serde_json::Value> {
+ self.complete_structured(request, schema, operation_id)
+ .await
+ }
+}
+
+impl OpenAiCompatProvider {
+ async fn complete_structured(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ operation_id: LlmOperationId,
) -> LlmResult<serde_json::Value> {
// Strict mode: modern local engines
// honour `response_format=json_schema`. Normalise the schema
@@ -164,11 +206,15 @@ impl LlmProvider for OpenAiCompatProvider {
if self.strict {
let mut strict_schema = schema.clone();
enforce_strict_object_schemas(&mut strict_schema);
- match self
+ let strict_result = self
.inner
- .complete_structured_raw(request.clone(), strict_schema)
- .await
- {
+ .complete_structured_raw_with_operation_id(
+ request.clone(),
+ strict_schema,
+ operation_id,
+ )
+ .await;
+ match strict_result {
Ok(v) if v.is_object() => return Ok(v),
Ok(_) => {
debug!("compat strict: non-object response, falling back to tolerant parser");
@@ -190,7 +236,10 @@ impl LlmProvider for OpenAiCompatProvider {
// Default (and strict fallback): most older local engines don't
// honour `response_format`. Ask for JSON and extract the first
// balanced `{…}` object from the text.
- let res = self.inner.complete(request).await?;
+ let res = self
+ .inner
+ .complete_with_operation_id(request, operation_id)
+ .await?;
// Reasoning models (DeepSeek, Qwen, MiniMax M2.7, …) prepend
// `<think>…</think>` before the JSON. Strip those blocks (and any
// surrounding markdown fences) before trying to parse — otherwise
diff --git a/crates/ai-memory-llm/src/opencode.rs b/crates/ai-memory-llm/src/opencode.rs
index 88d0efd9..ba614e0b 100644
--- a/crates/ai-memory-llm/src/opencode.rs
+++ b/crates/ai-memory-llm/src/opencode.rs
@@ -10,7 +10,7 @@ use secrecy::SecretString;
use crate::error::LlmResult;
use crate::openai_compat::OpenAiCompatProvider;
use crate::provider::LlmProvider;
-use crate::types::{ChatRequest, ChatResponse};
+use crate::types::{ChatRequest, ChatResponse, LlmOperationId};
/// Public OpenCode Zen/Go OpenAI-compatible base URL.
pub const OPENCODE_ZEN_BASE_URL: &str = "https://opencode.ai/zen/go/v1";
@@ -33,10 +33,28 @@ impl OpenCodeProvider {
/// # 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 inner = OpenAiCompatProvider::new(OPENCODE_ZEN_BASE_URL, Some(api_key), model.into())?;
+ Self::new_with_base_url(api_key, model, OPENCODE_ZEN_BASE_URL)
+ }
+
+ fn new_with_base_url(
+ api_key: SecretString,
+ model: impl Into<String>,
+ base_url: impl Into<String>,
+ ) -> LlmResult<Self> {
+ let inner = OpenAiCompatProvider::new(base_url, Some(api_key), model.into())?
+ .with_client_headers(
+ concat!("ai-memory/", env!("CARGO_PKG_VERSION")),
+ "x-opencode-session",
+ );
Ok(Self { inner })
}
+ #[cfg(test)]
+ fn with_strict(mut self, strict: bool) -> Self {
+ self.inner = self.inner.with_strict(strict);
+ self
+ }
+
/// Override the per-request timeout on the wrapped
/// [`OpenAiCompatProvider`]. The factory calls this with
/// `ProviderConfig::request_timeout_secs`.
@@ -65,7 +83,18 @@ impl LlmProvider for OpenCodeProvider {
}
async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
- self.inner.complete(request).await
+ self.complete_with_operation_id(request, LlmOperationId::new())
+ .await
+ }
+
+ async fn complete_with_operation_id(
+ &self,
+ request: ChatRequest,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<ChatResponse> {
+ self.inner
+ .complete_with_operation_id(request, operation_id)
+ .await
}
async fn complete_structured_raw(
@@ -73,13 +102,45 @@ impl LlmProvider for OpenCodeProvider {
request: ChatRequest,
schema: serde_json::Value,
) -> LlmResult<serde_json::Value> {
- self.inner.complete_structured_raw(request, schema).await
+ self.complete_structured_raw_with_operation_id(request, schema, LlmOperationId::new())
+ .await
+ }
+
+ async fn complete_structured_raw_with_operation_id(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ operation_id: LlmOperationId,
+ ) -> LlmResult<serde_json::Value> {
+ self.inner
+ .complete_structured_raw_with_operation_id(request, schema, operation_id)
+ .await
}
}
#[cfg(test)]
mod tests {
use super::*;
+ use serde_json::json;
+ use wiremock::matchers::{method, path};
+ use wiremock::{Mock, MockServer, Request, ResponseTemplate};
+
+ fn response_with_content(content: &str) -> serde_json::Value {
+ json!({
+ "model": "model-x",
+ "choices": [{
+ "message": { "content": content },
+ }],
+ "usage": { "prompt_tokens": 1, "completion_tokens": 1 },
+ })
+ }
+
+ fn header_value<'a>(request: &'a Request, name: &str) -> Option<&'a str> {
+ request
+ .headers
+ .get(name)
+ .and_then(|value| value.to_str().ok())
+ }
#[test]
fn provider_reports_opencode_name_and_configured_model() {
@@ -93,4 +154,91 @@ mod tests {
assert_eq!(OPENCODE_ZEN_BASE_URL, "https://opencode.ai/zen/go/v1");
assert!(!OPENCODE_DEFAULT_MODEL.is_empty());
}
+
+ #[tokio::test]
+ async fn completion_identifies_ai_memory_and_its_logical_operation() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/v1/chat/completions"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(response_with_content("ok")))
+ .mount(&server)
+ .await;
+
+ let provider = OpenCodeProvider::new_with_base_url(
+ SecretString::from("sk-test"),
+ "model-x",
+ server.uri(),
+ )
+ .unwrap();
+ let operation_id = LlmOperationId::new();
+ provider
+ .complete_with_operation_id(ChatRequest::user_prompt("hello"), operation_id)
+ .await
+ .unwrap();
+
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 1);
+ assert_eq!(
+ header_value(&requests[0], "user-agent"),
+ Some(concat!("ai-memory/", env!("CARGO_PKG_VERSION")))
+ );
+ assert_eq!(
+ header_value(&requests[0], "x-opencode-session"),
+ Some(operation_id.to_string().as_str())
+ );
+ }
+
+ #[tokio::test]
+ async fn structured_fallback_reuses_its_logical_operation() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST"))
+ .and(path("/v1/chat/completions"))
+ .respond_with(|request: &Request| {
+ let body: serde_json::Value =
+ serde_json::from_slice(&request.body).expect("request body is JSON");
+ if body.get("response_format").is_some() {
+ ResponseTemplate::new(400)
+ .set_body_string("unsupported parameter: response_format")
+ } else {
+ ResponseTemplate::new(200)
+ .set_body_json(response_with_content(r#"{"ok":true}"#))
+ }
+ })
+ .mount(&server)
+ .await;
+
+ let provider = OpenCodeProvider::new_with_base_url(
+ SecretString::from("sk-test"),
+ "model-x",
+ server.uri(),
+ )
+ .unwrap()
+ .with_strict(true);
+ let operation_id = LlmOperationId::new();
+ let value = provider
+ .complete_structured_raw_with_operation_id(
+ ChatRequest::user_prompt("emit JSON"),
+ json!({
+ "type": "object",
+ "properties": { "ok": { "type": "boolean" } },
+ "required": ["ok"],
+ }),
+ operation_id,
+ )
+ .await
+ .unwrap();
+
+ assert_eq!(value, json!({"ok": true}));
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 2);
+ let expected_id = operation_id.to_string();
+ assert_eq!(
+ header_value(&requests[0], "x-opencode-session"),
+ Some(expected_id.as_str())
+ );
+ assert_eq!(
+ header_value(&requests[1], "x-opencode-session"),
+ Some(expected_id.as_str())
+ );
+ }
}
diff --git a/crates/ai-memory-llm/src/provider.rs b/crates/ai-memory-llm/src/provider.rs
index e8d5b38a..63336b69 100644
--- a/crates/ai-memory-llm/src/provider.rs
+++ b/crates/ai-memory-llm/src/provider.rs
@@ -6,7 +6,7 @@ use schemars::JsonSchema;
use serde::de::DeserializeOwned;
use crate::error::LlmResult;
-use crate::types::{ChatRequest, ChatResponse};
+use crate::types::{ChatRequest, ChatResponse, LlmOperationId};
/// Provider-agnostic chat-completion + structured-output API.
///
@@ -28,6 +28,18 @@ pub trait LlmProvider: Send + Sync {
/// Plain text completion.
async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse>;
+ /// Plain text completion associated with an existing logical operation.
+ ///
+ /// Providers that do not expose operation identity on the wire use the
+ /// ordinary completion path unchanged.
+ async fn complete_with_operation_id(
+ &self,
+ request: ChatRequest,
+ _operation_id: LlmOperationId,
+ ) -> LlmResult<ChatResponse> {
+ self.complete(request).await
+ }
+
/// JSON-schema-constrained completion. Returns the unparsed
/// JSON the provider produced.
///
@@ -39,6 +51,20 @@ pub trait LlmProvider: Send + Sync {
request: ChatRequest,
schema: serde_json::Value,
) -> LlmResult<serde_json::Value>;
+
+ /// Structured completion associated with an existing logical operation.
+ ///
+ /// The default preserves existing provider behavior. Providers with
+ /// operation-aware request metadata override this method so retries and
+ /// compatibility fallbacks retain one identifier.
+ async fn complete_structured_raw_with_operation_id(
+ &self,
+ request: ChatRequest,
+ schema: serde_json::Value,
+ _operation_id: LlmOperationId,
+ ) -> LlmResult<serde_json::Value> {
+ self.complete_structured_raw(request, schema).await
+ }
}
/// Typed wrapper around [`LlmProvider::complete_structured_raw`].
@@ -59,3 +85,22 @@ where
let value = provider.complete_structured_raw(request, schema).await?;
serde_json::from_value::<T>(value).map_err(crate::LlmError::from)
}
+
+/// Typed structured completion associated with an existing logical operation.
+///
+/// # Errors
+/// Propagates any HTTP, schema, or deserialisation error.
+pub async fn complete_structured_with_operation_id<T>(
+ provider: &(dyn LlmProvider + 'static),
+ request: ChatRequest,
+ operation_id: LlmOperationId,
+) -> LlmResult<T>
+where
+ T: DeserializeOwned + JsonSchema + Send + 'static,
+{
+ let schema = serde_json::to_value(schemars::schema_for!(T))?;
+ let value = provider
+ .complete_structured_raw_with_operation_id(request, schema, operation_id)
+ .await?;
+ serde_json::from_value::<T>(value).map_err(crate::LlmError::from)
+}
diff --git a/crates/ai-memory-llm/src/types.rs b/crates/ai-memory-llm/src/types.rs
index bb7e839b..023437e4 100644
--- a/crates/ai-memory-llm/src/types.rs
+++ b/crates/ai-memory-llm/src/types.rs
@@ -1,6 +1,37 @@
//! Provider-neutral request/response types.
use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+/// Identifier shared by every HTTP attempt for one logical LLM operation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct LlmOperationId(Uuid);
+
+impl LlmOperationId {
+ /// Generate a fresh time-ordered operation identifier.
+ #[must_use]
+ pub fn new() -> Self {
+ Self(Uuid::now_v7())
+ }
+}
+
+impl Default for LlmOperationId {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+impl From<ai_memory_core::SessionId> for LlmOperationId {
+ fn from(value: ai_memory_core::SessionId) -> Self {
+ Self(value.0)
+ }
+}
+
+impl std::fmt::Display for LlmOperationId {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ self.0.fmt(f)
+ }
+}
/// Message role in a chat turn.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
diff --git a/docs/install.md b/docs/install.md
index b0243069..4bfb2032 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 Zen/Go](https://opencode.ai) cloud API at the OpenAI-compatible `opencode.ai/zen/go/v1` endpoint. Requests identify ai-memory by version and reuse one session header across related attempts. Set `OPENCODE_API_KEY` (key from `opencode.ai/auth`). Alias: `opencode-zen`. |
| `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. |