Skip to content
opencode-memHome

Auto-Capture AI Provider

Auto-capture runs a background AI request to summarize technical work and save it as memory. It needs one of the provider configurations below.

Recommended: Use a provider that is already authenticated in opencode and supports structured output:

"opencodeProvider": "anthropic",
"opencodeModel": "claude-haiku-4-5-20251001",

The plugin issues structured-output requests to opencode’s session API instead of calling provider endpoints directly, so opencode owns the auth, token refresh, and provider routing. The provider name must match an entry from opencode providers list, and the selected model must support structured JSON output through opencode.

Optionally pin a model reasoning variant with "opencodeVariant": "xhigh" (e.g. for grok-4.7). It is applied to the plugin’s internal LLM calls (auto-capture summaries, profile learning, profile cleanup), including when opencodeModel is "inherit", so background work can use a different reasoning level than the interactive session.

Slow reasoning models (or very large profile prompts) can exceed the default 90 s structured-output budget. Set "opencodeTimeoutMs" (milliseconds) to extend it for internal structured-output calls (auto-capture summaries, profile learning) — e.g. "opencodeTimeoutMs": 180000 for 3 minutes. Values are clamped to 10000..600000; the default stays 90000. Numeric strings are coerced. Profile cleanup uses a separate, longer timeout.

Supported providers: any provider listed by opencode providers list (e.g. anthropic, openai, github-copilot, openrouter, …).

Built-in Free / Zen models under provider id opencode (e.g. big-pickle) often cannot run the plugin’s internal structured-output sessions — OpenCode may reject them outside interactive chat. Prefer an authenticated provider from opencode providers list, or use "opencodeModel": "inherit" so capture follows the model you already use in the session.

If autoCaptureEnabled is true (default) but neither opencodeProvider/opencodeModel nor a complete manual fallback is configured, the plugin logs a warning and shows a startup toast (when showErrorToasts is enabled) so missing config is visible without digging through logs.

If opencodeProvider and opencodeModel are set, they take precedence over the manual memoryProvider settings below by default ("autoCaptureProviderOrder": "opencode-first"). Set "autoCaptureProviderOrder": "external-first" to prefer the manual API when both are configured (useful when the host session API is busy/slow); the other channel is used as fallback. Lower "opencodeTimeoutMs" to fail over from the opencode channel sooner.

Follow the session model: set "opencodeModel": "inherit" to use a concrete OpenCode model at call time instead of a pinned id. For auto-capture, each prompt is recorded via the chat.params hook and the capture request reuses that prompt’s provider/model. For profile learning and other structured-output paths (which are not tied to a single user message), inherit first reuses the last model the host reported on chat.params / the V2 context hook, then falls back to OpenCode’s model.json recent list when present (preferring the configured opencodeProvider). OpenCode v2 no longer writes model.json, so the in-process session model is the primary fallback there. Sending the literal model id inherit is never valid and previously caused ProviderModelNotFoundError: Model not found: <provider>/inherit on those paths. opencodeProvider is still required as the normal config gate.

Fallback: Manual API configuration (if not using opencodeProvider):

"memoryProvider": "openai-chat",
"memoryModel": "gpt-4o-mini",
"memoryApiUrl": "https://api.openai.com/v1",
"memoryApiKey": "sk-...",

API Key Formats:

"memoryApiKey": "sk-..."
"memoryApiKey": "file://~/.config/opencode/api-key.txt"
"memoryApiKey": "env://OPENAI_API_KEY"

Manual memoryProvider modes:

  • openai-chat: OpenAI Chat Completions compatible API with tool/function calling. This can work with compatible proxies such as LiteLLM only when the selected upstream model and proxy preserve tool calls.
  • openai-responses: OpenAI Responses API with function-call output.
  • anthropic: Anthropic Messages API with tool use.
  • minimax: MiniMax Anthropic Messages-compatible endpoint. Set memoryApiUrl to the global endpoint (https://api.minimax.io) or the China endpoint (https://api.minimax.cn); the /anthropic/v1/messages path and x-api-key header are applied automatically. Use MiniMax-M3.1-Flash (recommended) or MiniMax-M3, both with a 1,000,000-token context. Flash always thinks; optionally set memoryExtraParams to { "output_config": { "effort": "max" } } with low, medium, high, xhigh, or max (default). Flash rejects disabled thinking and effort none, and does not support service_tier. M3 thinking is off by default on this endpoint; enable it with { "thinking": { "type": "adaptive" } }. Model IDs remain explicitly configured; existing custom or legacy IDs are passed through unchanged. See the MiniMax compatibility reference.
  • orcarouter: OpenAI-compatible model gateway with namespaced model IDs. memoryApiUrl and memoryModel are optional — they default to https://api.orcarouter.ai/v1 and orcarouter/auto (a routing alias that selects a capable model per request). If you set memoryModel, use a namespaced ID such as openai/gpt-5.5 or deepseek/deepseek-v4-flash; OrcaRouter rejects bare model names. Example: 
    "memoryProvider": "orcarouter",
    "memoryApiKey": "<OrcaRouter API key>",
    OrcaRouter also runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes.
  • atlas-cloud: OpenAI-compatible Chat Completions preset for Atlas Cloud. memoryApiUrl and memoryModel are optional — they default to https://api.atlascloud.ai/v1 and deepseek-ai/deepseek-v4-pro. If memoryApiKey is omitted, ATLASCLOUD_API_KEY from the environment is used. Example: 
    "memoryProvider": "atlas-cloud",
    "memoryApiKey": "env://ATLASCLOUD_API_KEY",
    When this provider is selected, auto-capture / profile prompts, model responses, and relevant conversation context are transmitted to https://api.atlascloud.ai.
  • cheaper-inference: OpenAI-compatible Chat Completions preset for Cheaper Inference. memoryApiUrl and memoryModel are optional — they default to https://api.cheaperinference.com/v1 and gpt-5.4-mini. If memoryApiKey is omitted, CHEAPER_INFERENCE_API_KEY from the environment is used. Example: 
    "memoryProvider": "cheaper-inference",
    "memoryApiKey": "env://CHEAPER_INFERENCE_API_KEY",
    When this provider is selected, auto-capture / profile prompts, model responses, and relevant conversation context are transmitted to https://api.cheaperinference.com.
  • api-route: OpenAI-compatible Chat Completions preset for API Route. memoryApiUrl and memoryModel are optional — they default to https://global.api-route.com/v1 and gpt-6.1-sol. If memoryApiKey is omitted, API_ROUTE_API_KEY from the environment is used. Example: 
    "memoryProvider": "api-route",
    "memoryApiKey": "env://API_ROUTE_API_KEY",
    When this provider is selected, auto-capture / profile prompts, model responses, and relevant conversation context are transmitted to https://global.api-route.com.
  • runcrate: OpenAI-compatible Chat Completions preset for Runcrate. memoryApiUrl and memoryModel are optional — they default to https://api.runcrate.ai/v1 and deepseek-ai/DeepSeek-V4.1-Flash. If memoryApiKey is omitted, RUNCRATE_API_KEY from the environment is used. Example: 
    "memoryProvider": "runcrate",
    "memoryApiKey": "env://RUNCRATE_API_KEY",
    When this provider is selected, auto-capture / profile prompts, model responses, and relevant conversation context are transmitted to https://api.runcrate.ai.
  • cloudgpu: OpenAI-compatible Chat Completions preset for CloudGPU. memoryApiUrl and memoryModel are optional — they default to https://cloudgpu.app/v1 and deepseek-v4.1-flash. If memoryApiKey is omitted, CLOUDGPU_API_KEY from the environment is used (create a key at https://cloudgpu.app/api/console; API docs: https://cloudgpu.app/api/docs). Example: 
    "memoryProvider": "cloudgpu",
    "memoryApiKey": "env://CLOUDGPU_API_KEY",
    When this provider is selected, auto-capture / profile prompts, model responses, and relevant conversation context are transmitted to https://cloudgpu.app.

Troubleshooting:

  • Auto-capture failures do not block manual memory tool usage.
  • Auto-capture preserves bounded final assistant text and terminal tool outcomes from delivered V1/V2 events before the delayed summarization runs. Normal idle capture still prefers the live host transcript; ready pending evidence is the fallback when the session is already gone (deletion or startup replay). Recovery is scoped to the same project and uses the normal capture provider and claim queue. It does not infer completed work from the request alone. Deleting an OpenCode session does not delete this pending memory evidence or already captured memories.
  • Pending evidence is private-tag redacted before persistence (including tags spanning final text parts within one assistant message); reasoning, attachments, raw provider metadata, streaming deltas, and tool arguments are excluded. Limits are 16 KiB per part, 16 parts per prompt, 256 parts globally (at most 4 MiB of text), and 64 KiB per capture. Truncation is marked; oldest parts are evicted when the budget is exceeded. Evidence expires after 24 hours and is pruned on subsequent store access. It is cleared when capture finishes/skips or its prompt is removed by existing deletion/retention paths. These are logical retention limits, not secure erasure of SQLite/WAL backups.
  • V2 events are a volatile stream: disconnected/missed events, unresolvable prompt association, and evidence lost to expiry/eviction cannot be recovered. The guarantee is capture from evidence received, saved, and checkpointed ready by an idle/deleted event, not reconstruction of unseen or previously deleted transcripts. After that checkpoint the session is sealed against late rebinds until the next authored user input (V2 session.inbox.delivered, V1 user message.updated), so buffered parts cannot flip ready evidence back to unreadiness. A disconnect before the terminal checkpoint leaves the partial evidence deferred until a later checkpoint; restart does not assume unfinished work is complete. V1 uses explicit assistant parent IDs; V2 freezes the delivered input at step start rather than guessing the latest queued prompt.
  • If the live host reports Session.NotFoundError (or deletion/startup replay has no ready evidence), capture logs skipped / session_not_found, releases its claim without backoff or consuming retries, and skips further host-dependent lookups in that batch. Later prompts with ready saved evidence still proceed. A later independent idle may retry. Already exhausted prompts are not revived. Other failures retain their existing retry behavior.
  • Auto-capture additions use a stable per-project/prompt ID so sequential crash/restart replay reuses the prior memory, including soft-deleted records, instead of inserting or resurrecting it. This does not claim distributed exactly-once semantics for optional semantic update/supersede operations or every multi-process crash interleaving.
  • If auto-capture reports that a provider is not connected, confirm the provider name with opencode providers list and configure that provider in opencode first.
  • If a proxy or custom provider returns plain text instead of structured/tool output, choose another model/provider or use one of the manual provider modes above.
  • For models that reject temperature, add "memoryTemperature": false when using manual API configuration.
  • For models that reject forced tool calls (tool_choice: "required", e.g. some thinking modes), add "forceToolChoice": false when using openai-chat / orcarouter / atlas-cloud / cheaper-inference / api-route / runcrate / cloudgpu.
  • For opencodeProvider / opencodeModel (e.g. DeepSeek V4 thinking), OpenCode still sends forced tool_choice for structured output. opencode-mem disables thinking on the internal opencode-mem-structured agent (and re-applies that in chat.params after variant merge) so auto-capture and profile learning can complete. Your interactive chat agent is unchanged. If capture still fails with a thinking/tool_choice error, pick a non-thinking model for opencodeModel or configure a complete manual fallback (memoryModel + memoryApiUrl).
  • opencode-claude-auth / Claude Code: auto-capture uses OpenCode with your authenticated anthropic provider. Forced format: json_schema often loops with Claude-auth, so opencode-mem uses an auth-preserving text-JSON path for opencodeProvider: "anthropic" (no forced StructuredOutput tools; reply is parsed with Zod). A step watchdog still aborts runaway internal sessions after 2 steps. If capture still fails, configure a complete manual Anthropic API-key fallback (memoryProvider: "anthropic" + memoryModel + memoryApiUrl + memoryApiKey) — Claude Pro/Max OAuth cannot be reused outside OpenCode.
  • Unsupported platforms: Intel Mac (darwin/x64) is not supported — @tursodatabase/database and fixed onnxruntime-node releases (pinned 1.31.1) ship no x64 native binding. Use Apple Silicon, Linux, or Windows, or a remote embedding endpoint via embeddingApiUrl + embeddingApiKey. MLX is not supported.