om-memory-system 3.5.0-next.34 → 3.5.0

package/dist/adapters/opencode/auto-capture-summary.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { CONFIG } from "../../config.js";
 import { resolveOpencodeHostModel } from "../../services/ai/live-model-choice.js";
 import { buildBoundedSummaryPrompt } from "../../core/capture-context.js";
+import { errorHttpStatus, errorRetryAfterMs } from "../../core/capture-retry-policy.js";
 import { classifyCaptureReply, normalizeStopReason, parseCaptureSummary, } from "../../core/extraction.js";
 import { log } from "../../services/logger.js";
 import { loadOpencodeProvider } from "./opencode-provider-loader.js";
@@ -98,6 +99,8 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
         catch (error) {
             opencodeProviderError = error;
             diagnostics.failureReason = hostModelFailureReason(error);
+            diagnostics.httpStatus = errorHttpStatus(error);
+            diagnostics.retryAfterMs = errorRetryAfterMs(error);
             log("auto-capture: opencode provider failed, falling back to external API", {
                 error: String(error),
             });
@@ -122,6 +125,7 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
     }
     const { AIProviderFactory } = await import("../../services/ai/ai-provider-factory.js");
     const { buildMemoryProviderConfig } = await import("../../services/ai/provider-config.js");
+    const { toolCallFailureReason } = await import("../../services/ai/providers/base-provider.js");
     const { detectLanguage, getLanguageName } = await import("../../services/language-detector.js");
     const providerConfig = buildMemoryProviderConfig(CONFIG);
     const provider = AIProviderFactory.createProvider(CONFIG.memoryProvider, providerConfig);
@@ -168,6 +172,8 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
         blockTypes: undefined,
         rawReply: undefined,
         failureReason: undefined,
+        httpStatus: undefined,
+        retryAfterMs: undefined,
     });
     let result;
     try {
@@ -178,8 +184,10 @@ export async function generateOpenCodeAutoCaptureSummary(request, notify) {
         throw error;
     }
     diagnostics.stopReason = normalizeStopReason(result.stopReason);
+    diagnostics.httpStatus = result.httpStatus;
+    diagnostics.retryAfterMs = result.retryAfterMs;
     if (!result.success || !result.data) {
-        diagnostics.failureReason = diagnostics.stopReason === "length" ? "truncated" : "call-error";
+        diagnostics.failureReason = toolCallFailureReason(result, diagnostics.stopReason === "length");
         throw new Error(result.error || "Failed to generate summary");
     }
     const rawReply = JSON.stringify(result.data);

package/dist/adapters/opencode/backfill-startup.d.ts

@@ -1,3 +1,4 @@
+import type { AutoCaptureHost } from "../../core/host.js";
 /** Start after connected providers load, without delaying plugin initialisation. */
 export declare function startOpencodeBackfill(input: {
     directory: string;
@@ -13,3 +14,5 @@ export declare function registerOpencodeBackfillModels(input: {
 }): void;
 /** Let web imports, Health, and Settings in this process use OpenCode's signed-in models. */
 export declare function registerOpencodeImportModels(): void;
+/** Let triggers and Retry now in this process retry OpenCode's queued turns. */
+export declare function registerOpencodeCaptureRetryDrain(host: AutoCaptureHost, directory: string): void;

package/dist/adapters/opencode/backfill-startup.js

@@ -2,6 +2,8 @@ import { CONFIG } from "../../config.js";
 import { scheduleAutoBackfill } from "../../importer/auto-backfill.js";
 import { registerHostBackfillModels, registerOpencodeHostModels, } from "../../importer/backfill-controls.js";
 import { listOpencodeClientModels } from "../../importer/settings-models.js";
+import { drainOpencodeCaptureRetries } from "../../services/auto-capture.js";
+import { registerCaptureRetryDrain } from "../../services/capture-retry-drain.js";
 import { resolveOpencodeBackfillModels } from "./backfill-models.js";
 import { createOpencodeImportModels } from "./opencode-import-models.js";
 import { getV2Client, isProviderConnected } from "./opencode-provider.js";
@@ -29,3 +31,7 @@ export function registerOpencodeImportModels() {
         },
     });
 }
+/** Let triggers and Retry now in this process retry OpenCode's queued turns. */
+export function registerOpencodeCaptureRetryDrain(host, directory) {
+    registerCaptureRetryDrain("opencode", () => drainOpencodeCaptureRetries(host, directory));
+}

package/dist/adapters/opencode/opencode-diagnostics.js

@@ -1,3 +1,4 @@
+import { httpStatusError, parseRetryAfter } from "../../core/capture-retry-policy.js";
 export function diagnosticUrl(url) {
     try {
         const parsed = new URL(url);
@@ -22,7 +23,7 @@ export async function readJson(res, endpoint) {
     const text = await res.text();
     const url = diagnosticUrl(endpoint.url);
     if (!res.ok) {
-        throw new Error(`omms: opencode ${endpoint.label} failed at ${url} (${responseStatus(res)}): ${redactedBody(text)}`);
+        throw httpStatusError(`omms: opencode ${endpoint.label} failed at ${url} (${responseStatus(res)}): ${redactedBody(text)}`, res.status, parseRetryAfter(res.headers?.get?.("retry-after")));
     }
     if (!text) {
         throw new Error(`omms: opencode ${endpoint.label} at ${url} returned an empty response body`);

package/dist/adapters/opencode/opencode-provider.js

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { diagnosticUrl, readJson, responseStatus, } from "./opencode-diagnostics.js";
 import { INTERNAL_CAPTURE_SESSION_TITLE, trackInternalCaptureSession, untrackInternalCaptureSession, } from "./internal-capture-sessions.js";
 import { createLazyV2Client } from "./opencode-sdk-client.js";
+import { httpStatusError, parseRetryAfter } from "../../core/capture-retry-policy.js";
 /** Dedicated agent registered via the plugin config hook (step-capped). */
 export const STRUCTURED_OUTPUT_AGENT = "omms-structured";
 /** Hard ceiling for a single internal structured-output prompt. */
@@ -227,7 +228,7 @@ export async function generateStructuredOutput(opts) {
         reportReply(onReply, reply);
         const info = reply.info;
         if (info.error) {
-            throw new Error(`omms: opencode reported ${info.error.name}: ${formatAssistantError(info.error)}`);
+            throw assistantError(info.error);
         }
         const structuredOutput = info.structured_output ?? info.structured;
         if (structuredOutput === undefined || structuredOutput === null) {
@@ -286,7 +287,7 @@ async function generateViaSdkClient(client, args) {
         }
         reportReply(args.onReply, data);
         if (data.info.error) {
-            throw new Error(`omms: opencode reported ${data.info.error.name}: ${formatAssistantError(data.info.error)}`);
+            throw assistantError(data.info.error);
         }
         const structuredOutput = data.info.structured_output ?? data.info.structured;
         if (structuredOutput === undefined || structuredOutput === null) {
@@ -343,7 +344,10 @@ function readSdkData(response, label) {
         const status = result.response ? ` (${responseStatus(result.response)})` : "";
         const responseUrl = result.response?.url || result.request?.url;
         const url = responseUrl ? diagnosticUrl(responseUrl) : "the authenticated client";
-        throw new Error(`omms: opencode ${label} failed at ${url}${status}: <redacted response body>`);
+        const message = `omms: opencode ${label} failed at ${url}${status}: <redacted response body>`;
+        if (!result.response)
+            throw new Error(message);
+        throw httpStatusError(message, result.response.status, parseRetryAfter(result.response.headers?.get?.("retry-after")));
     }
     if (result?.data === undefined) {
         throw new Error(`omms: opencode ${label} returned no response data`);
@@ -382,6 +386,12 @@ async function createSession(base, directory) {
     trackInternalCaptureSession(body.id);
     return body.id;
 }
+/** The model's error reply, with its HTTP status when OpenCode reports one. */
+function assistantError(error) {
+    const message = `omms: opencode reported ${error.name}: ${formatAssistantError(error)}`;
+    const status = error.data?.statusCode;
+    return typeof status === "number" ? httpStatusError(message, status) : new Error(message);
+}
 function formatAssistantError(error) {
     if (!error.data)
         return error.name;

package/dist/adapters/pi/capture.js

@@ -1,11 +1,30 @@
 import { CONFIG } from "../../config.js";
 import { captureConversation } from "../../core/capture.js";
+import { quickRetryDelayMs } from "../../core/capture-retry-policy.js";
 import { log } from "../../services/logger.js";
 import { memoryClient } from "../../services/client.js";
+import { queueFailedCapture, startCaptureRetryDrain } from "../../services/capture-retry-drain.js";
 import { extractPiConversation } from "../../importer/pi-conversation.js";
 export function createPiCaptureState() {
     return { handledUserEntries: new Set(), running: false };
 }
+/** Try the turn up to `autoCaptureMaxRetries` times, as OpenCode does, before it counts as failed. */
+async function captureWithQuickRetries(unit, provider) {
+    const maxRetries = Math.max(1, CONFIG.autoCaptureMaxRetries ?? 3);
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await captureConversation(unit, provider);
+        }
+        catch (error) {
+            if (attempt >= maxRetries)
+                throw error;
+            log(`Pi auto-capture warning (attempt ${attempt}/${maxRetries})`, {
+                sessionID: unit.hostSessionId,
+            });
+            await new Promise((resolve) => setTimeout(resolve, quickRetryDelayMs(attempt)));
+        }
+    }
+}
 /**
  * Capture the work unit completed by the most recent user prompt on the
  * settled branch. Safe to call for every `agent_settled` event: a work unit is
@@ -18,6 +37,7 @@ export async function capturePiSettledWorkUnit(input) {
     if (input.state.running)
         return { status: "skipped", reason: "busy" };
     input.state.running = true;
+    let workUnit = null;
     try {
         const window = extractPiConversation(input.entries);
         if (!window)
@@ -29,7 +49,7 @@ export async function capturePiSettledWorkUnit(input) {
         if (embeddingInitError) {
             return { status: "skipped", reason: "not-ready" };
         }
-        const captureResult = await captureConversation({
+        workUnit = {
             host: "pi",
             hostSessionId: input.sessionId,
             sourceType: "live-capture",
@@ -44,10 +64,9 @@ export async function capturePiSettledWorkUnit(input) {
             textResponses: window.textResponses,
             toolCalls: window.toolCalls,
             sourceEntryIds: window.sourceEntryIds,
-            ...(window.sourceTimestamp !== undefined
-                ? { sourceTimestamp: window.sourceTimestamp }
-                : {}),
-        }, input.provider);
+            ...(window.sourceTimestamp !== undefined ? { sourceTimestamp: window.sourceTimestamp } : {}),
+        };
+        const captureResult = await captureWithQuickRetries(workUnit, input.provider);
         input.state.handledUserEntries.add(window.userEntryId);
         if (captureResult.status === "skipped") {
             log("Pi auto-capture skipped by extractor", {
@@ -63,6 +82,8 @@ export async function capturePiSettledWorkUnit(input) {
             memoryId: captureResult.memoryId,
             host: "pi",
         });
+        // The capture model answers again, so earlier failed turns may go through now.
+        startCaptureRetryDrain("pi");
         if (CONFIG.showAutoCaptureToasts && input.notify) {
             await Promise.resolve(input.notify({
                 title: "Memory Captured",
@@ -75,6 +96,9 @@ export async function capturePiSettledWorkUnit(input) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         log(`Pi auto-capture error: ${message}`, { sessionID: input.sessionId });
+        // The next prompt moves capture on to a newer turn, so keep this one for a later retry.
+        if (workUnit)
+            await queueFailedCapture(workUnit, error, CONFIG);
         if (CONFIG.showErrorToasts && input.notify) {
             const shortReason = message.length > 100 ? message.substring(0, 100) + "..." : message;
             await Promise.resolve(input.notify({

package/dist/adapters/pi/extension.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { CONFIG, initConfigWithLegacyMigration, isConfigured } from "../../config.js";
+import { CONFIG, initConfigWithLegacyMigration, isConfigured, refreshConfigIfChanged, } from "../../config.js";
 import { pruneTraces } from "../../services/capture-diagnostics.js";
 import { executeMemoryOperation } from "../../core/memory-operations.js";
 import { getLanguageName } from "../../services/language-detector.js";
@@ -111,6 +111,23 @@ export default function ommsPiExtension(pi) {
                     code: error instanceof Error ? error.name : "unknown",
                 }));
             }
+            // Retry turns whose capture failed earlier, with this session's capture model.
+            void import("../../services/capture-retry-drain.js")
+                .then(({ drainCaptureRetries, registerCaptureRetryDrain, startCaptureRetryDrain }) => {
+                registerCaptureRetryDrain("pi", () => {
+                    // A retention change in the config file applies from this pass on.
+                    refreshConfigIfChanged(ctx.cwd);
+                    return drainCaptureRetries({
+                        host: "pi",
+                        provider: createPiLiveModels(ctx, notify(ctx)).capture,
+                        config: CONFIG,
+                        isReady: () => isConfigured() && !memoryClient.getEmbeddingInitError?.(),
+                    });
+                });
+                if (isConfigured() && CONFIG.autoCaptureEnabled)
+                    startCaptureRetryDrain("pi");
+            })
+                .catch(() => { });
             // Run now on a Settings page served by this process can use Pi's signed-in models.
             void Promise.all([
                 import("../../importer/backfill-controls.js"),

package/dist/config.d.ts

@@ -42,6 +42,8 @@ interface OmmsConfig {
     captureTrace?: boolean;
     captureTraceRetentionDays?: number;
     captureAttemptRetentionDays?: number;
+    /** Hours to keep failed live captures for retry. 0 turns the queue off. Global config only. */
+    captureRetryRetentionHours?: number;
     autoBackfill?: boolean;
     opencodeBackfillModel?: string;
     piBackfillModel?: string;
@@ -98,8 +100,10 @@ interface OmmsConfig {
         injectOn?: "first" | "always";
     };
 }
-export declare const CONFIG_TEMPLATE = "{\n  // ============================================\n  // omms (Opinionated Modular Memory System) Configuration\n  // ============================================\n  \n  // Storage location for the vector database. Leave unset to use the\n  // default ~/.omms/data (a legacy ~/.opencode-mem/data store is migrated\n  // there automatically on first start; see docs/omms-migration.md).\n  // \"storagePath\": \"~/.omms/data\",\n\n  \"userEmailOverride\": \"\",\n  \"userNameOverride\": \"\",\n  \n  // ============================================\n  // Embedding Model (for similarity search)\n  // ============================================\n  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).\n  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).\n  \n  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)\n  \"embeddingModel\": \"Xenova/nomic-embed-text-v1\",\n\n  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,\n  // re-index existing memories so store and query vectors stay aligned.\n  // \"embeddingUseTaskPrefixes\": true,\n  \n  // Auto-detected dimensions (no need to set manually)\n  // \"embeddingDimensions\": 768,\n  \n  // Other recommended local models:\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-base-en\",  // 768 dims, English-only, 8192 context\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-small-en\", // 512 dims, faster, 8192 context\n  // \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",            // 384 dims, very fast, 512 context\n  // \"embeddingModel\": \"Xenova/all-mpnet-base-v2\",           // 768 dims, good quality, 512 context\n  \n  // Optional: OpenAI-compatible API for embeddings (both URL and key required)\n  // \"embeddingApiUrl\": \"https://api.openai.com/v1\",\n  // \"embeddingApiKey\": \"env://OPENAI_API_KEY\",  // or \"sk-...\" / \"file:///path/to/key\"\n  // \"embeddingModel\": \"text-embedding-3-small\",  // 1536 dims, auto-detected\n \n  // ============================================\n  // Web Server Settings\n  // ============================================\n  \n  // Start a background import of past chats on each host's next start.\n  \"autoBackfill\": true,\n  // \"piBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // Directory maps for history recorded in moved or deleted directories.\n  // \"importPathMaps\": [{ \"from\": \"~/code/app-feat-x\", \"to\": \"~/code/app\" }],\n\n  // Register the web app to start when you log in.\n  \"webServerAutoStart\": true,\n  // Enable web UI for managing memories (accessible at http://localhost:4747)\n  \"webServerEnabled\": true,\n  \n  // Port for web UI server\n  \"webServerPort\": 4747,\n  \n  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)\n  \"webServerHost\": \"127.0.0.1\",\n\n  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.\n  // \"webServerAuthPassword\": \"\",\n  // \"webServerAuthUsername\": \"\",\n\n  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).\n  // \"webServerApiToken\": \"env://OMMS_WEB_TOKEN\",\n  \n  // ============================================\n  // Database Settings\n  // ============================================\n  \n  // Maximum vectors per database shard (auto-creates new shard when limit reached)\n  \"maxVectorsPerShard\": 50000,\n  \n  // Automatically delete old memories based on retention period\n  \"autoCleanupEnabled\": true,\n  \n  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)\n  \"autoCleanupRetentionDays\": 30,\n  \n  // Automatically detect and remove duplicate memories\n  \"deduplicationEnabled\": true,\n  \n   // Similarity threshold (0-1) for detecting duplicates (higher = stricter)\n   \"deduplicationSimilarityThreshold\": 0.90,\n   \n  // ============================================\n  // Memory Scope Settings\n  // ============================================\n\n  // Default scope for memory list/search queries\n  // \"project\" keeps queries within the current project, \"all-projects\" searches across all project shards\n  \"memory\": {\n    \"defaultScope\": \"project\"\n  },\n\n  // ============================================\n  // Model for auto-capture and profile learning (same rule in OpenCode and Pi)\n  // ============================================\n\n   // Which model summarises your work, in this order:\n   //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,\n   //      piProvider/piModel in Pi. Set the model to \"inherit\" to follow\n   //      whatever model the session is using, or to \"external\" to send\n   //      every call to the external API below.\n   //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/\n   //      memoryApiKey further down).\n   //   3. If neither is set: the session's own model.\n   // If the host model fails and the external API is configured, the external\n   // API is used instead.\n   //\n   // Host models go through OpenCode's or Pi's own sign-in (OAuth like Claude\n   // Pro/Max, GitHub Copilot, ChatGPT, or your own key there), so no separate API\n   // key is needed here.\n   //\n   // Examples (OpenCode names from 'opencode providers list'; Pi names from its model list):\n   //   \"opencodeProvider\": \"anthropic\",    \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n   //   \"opencodeProvider\": \"openai\",       \"opencodeModel\": \"inherit\"\n   //   \"piProvider\": \"openai-codex\",       \"piModel\": \"gpt-5.6-luna\"\n   //\n   // \"opencodeProvider\": \"anthropic\",\n   // \"opencodeModel\": \"claude-haiku-4-5-20251001\",\n   // \"piProvider\": \"openai-codex\",\n   // \"piModel\": \"gpt-5.6-luna\",\n\n   // ============================================\n   // Auto-Capture Settings\n   // ============================================\n  \n  // Auto-capture runs in the background without blocking your main session.\n  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.\n  \n  \"autoCaptureEnabled\": true,\n  \n  // Provider type: \"openai-chat\" | \"openai-responses\" | \"anthropic\" | \"minimax\" | \"orcarouter\" | \"google-gemini\"\n  // Note: \"openai-chat\" is a generic OpenAI API-compatible mode.\n  // Any service that follows the OpenAI Chat Completions API can use it via custom \"memoryApiUrl\".\n  \"memoryProvider\": \"openai-chat\",\n  \n  // External API (step 2 above, and the fallback when a host model fails).\n  // Uncomment all 3 lines and replace memoryApiKey before use:\n  // \"memoryModel\": \"gpt-4o-mini\",\n  // \"memoryApiUrl\": \"https://api.openai.com/v1\",\n  // \"memoryApiKey\": \"sk-...\",\n\n  // API Key Formats:\n  // Direct value:        \"sk-...\"\n  // From file:           \"file://~/.config/litellm-key.txt\"\n  // From env variable:   \"env://LITELLM_API_KEY\"\n  \n  // Examples for different providers:\n  // Any OpenAI-compatible endpoint can use the \"openai-chat\" provider pattern below.\n  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),\n  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).\n\n  // OpenAI Chat Completion (default, backward compatible):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"gpt-4o-mini\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n\n  // DeepSeek (OpenAI-compatible example):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"deepseek-chat\"\n  //   \"memoryApiUrl\": \"https://api.deepseek.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // OpenAI Responses API (recommended, with session support):\n  //   \"memoryProvider\": \"openai-responses\"\n  //   \"memoryModel\": \"gpt-4o\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // Anthropic (with session support):\n  //   \"memoryProvider\": \"anthropic\"\n  //   \"memoryModel\": \"claude-3-5-haiku-20241022\"\n  //   \"memoryApiUrl\": \"https://api.anthropic.com/v1\"\n  //   \"memoryApiKey\": \"sk-ant-...\"\n\n  // MiniMax (Anthropic Messages-compatible endpoint, with session support):\n  //   \"memoryProvider\": \"minimax\"\n  //   \"memoryModel\": \"MiniMax-M3\"\n  //   \"memoryApiUrl\": \"https://api.minimax.io\"        // global endpoint\n  //   \"memoryApiKey\": \"<MiniMax API key>\"\n  //   // China endpoint: \"memoryApiUrl\": \"https://api.minimaxi.com\"\n  //   // Optional adaptive thinking for MiniMax-M3:\n  //   \"memoryExtraParams\": { \"thinking\": { \"type\": \"adaptive\" } }\n\n  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):\n  //   \"memoryProvider\": \"orcarouter\"\n  //   \"memoryApiKey\": \"<OrcaRouter API key>\"\n  //   // memoryApiUrl and memoryModel are optional \u2014 they default to\n  //   // https://api.orcarouter.ai/v1 and \"orcarouter/auto\" (a routing alias).\n  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a\n  //   // namespaced ID such as \"openai/gpt-5.5\" or \"deepseek/deepseek-v4-flash\".\n  //   \"memoryModel\": \"openai/gpt-5.5\"\n\n  // Groq (OpenAI-compatible, use openai-chat provider):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"llama-3.3-70b-versatile\"\n  //   \"memoryApiUrl\": \"https://api.groq.com/openai/v1\"\n  //   \"memoryApiKey\": \"gsk_...\"\n  \n  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)\n  \"autoCaptureMaxIterations\": 5,\n   \n  // Timeout per iteration in milliseconds (30 seconds default)\n  \"autoCaptureIterationTimeout\": 30000,\n\n  // Maximum number of times to retry capturing a prompt if it fails (due to network, API errors, etc.)\n  \"autoCaptureMaxRetries\": 3,\n\n  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.\n  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).\n  // Rough guide: tokens \u2248 bytes / 4 for mixed code/prose.\n  \"autoCaptureMaxContextBytes\": 131072,\n   \n  // Days to keep AI session history before cleanup\n  \"aiSessionRetentionDays\": 7,\n\n  // Capture diagnostics: every capture attempt always writes one metadata line\n  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no\n  // conversation text. Set captureTrace to true to also write each attempt's\n  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain\n  // conversation content: <private> text and common API key formats are\n  // redacted, files are readable only by you, and they are deleted after\n  // captureTraceRetentionDays. Only this global file can turn tracing on.\n  // \"captureTrace\": false,\n  // \"captureTraceRetentionDays\": 7,\n  // \"captureAttemptRetentionDays\": 30,\n\n  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)\n  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter\n  // Set to false and add \"memoryTemperature\": false in config when using such models\n  \"memoryTemperature\": 0.3,\n\n  // Extra parameters to include in API request body\n  // Useful for local inference servers (e.g. llama-server with --jinja) that support\n  // additional parameters like disabling thinking/reasoning mode\n  // Example for Qwen3 models: { \"enable_thinking\": false }\n  // \"memoryExtraParams\": {},\n\n  // Language for auto-capture summaries (default: \"auto\" for auto-detection)\n  // Options: \"auto\", \"en\", \"id\", \"zh\", \"ja\", \"es\", \"fr\", \"de\", \"ru\", \"pt\", \"ar\", \"ko\"\n  // \"autoCaptureLanguage\": \"auto\",\n\n  // ============================================\n  // Toast Notifications\n  // ============================================\n\n  // Show toast when memory is auto-captured\n  \"showAutoCaptureToasts\": true,\n\n  // Show toast when user profile is updated\n  \"showUserProfileToasts\": true,\n\n  // Show toast for error messages\n  \"showErrorToasts\": true,\n\n  // ============================================\n  // User Profile System\n  // ============================================\n\n  // Analyze user prompts every N prompts to build/update your user profile\n  // When N uncaptured prompts accumulate, AI will analyze them to identify:\n  // - User preferences (code style, communication style, tool preferences)\n  // - User patterns (recurring topics, problem domains, technical interests)\n  // - User workflows (development habits, sequences, learning style)\n  // - Skill level (overall and per-domain assessment)\n  \"userProfileAnalysisInterval\": 10,\n\n  // Days before inactive items (all types) are eligible for removal\n  \"userProfileStaleDays\": 2,\n\n  // Number of preferences shown in UI\n  \"userProfileDisplayPreferences\": 20,\n  \n  // Number of patterns shown in UI\n  \"userProfileDisplayPatterns\": 15,\n  \n  // Number of workflows shown in UI\n  \"userProfileDisplayWorkflows\": 10,\n  \n  // Number of preferences injected into LLM conversation context\n  // Keep this small \u2014 the strongest signals are enough; more dilute LLM attention\n  \"userProfileInjectPreferences\": 5,\n  \n  // Number of patterns injected into LLM conversation context\n  \"userProfileInjectPatterns\": 5,\n  \n  // Number of workflows injected into LLM conversation context\n  \"userProfileInjectWorkflows\": 3,\n  \n  // Days before preference confidence starts to decay (if not reinforced)\n  // Preferences that aren't seen again will gradually lose confidence and be removed\n  \"userProfileConfidenceDecayDays\": 30,\n  \n  // Number of profile versions to keep in changelog (for rollback/debugging)\n  // Older versions are automatically cleaned up\n  \"userProfileChangelogRetentionCount\": 5,\n\n  // Minimum evidence count for a preference/pattern to survive confidence decay\n  // Items confirmed fewer times are more likely to be pruned when confidence decays\n  \"userProfileMinEvidenceForRetention\": 3,\n\n  // Periodically merge duplicate or irrelevant profile items with the configured AI provider\n  \"userProfileAutoCleanupEnabled\": true,\n  // Number of analyzed user prompts between automatic AI cleanup runs\n  \"userProfileAutoCleanupInterval\": 100,\n\n  // Enable LLM validation of existing preferences against recent behavior.\n  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.\n  // Experimental \u2014 disabled by default.\n  \"userProfileValidationEnabled\": false,\n\n  // ============================================\n  // Search Settings\n  // ============================================\n  \n  // Minimum similarity score (0-1) for memory search results\n  \"similarityThreshold\": 0.6,\n\n  // Maximum number of memories to return in search results\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Advanced Settings\n  // ============================================\n  \n  // Inject user profile into AI context (preferences, patterns, workflows)\n  \"injectProfile\": true\n}\n";
+export declare const CONFIG_TEMPLATE = "{\n  // ============================================\n  // omms (Opinionated Modular Memory System) Configuration\n  // ============================================\n  \n  // Storage location for the vector database. Leave unset to use the\n  // default ~/.omms/data (a legacy ~/.opencode-mem/data store is migrated\n  // there automatically on first start; see docs/omms-migration.md).\n  // \"storagePath\": \"~/.omms/data\",\n\n  \"userEmailOverride\": \"\",\n  \"userNameOverride\": \"\",\n  \n  // ============================================\n  // Embedding Model (for similarity search)\n  // ============================================\n  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).\n  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).\n  \n  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)\n  \"embeddingModel\": \"Xenova/nomic-embed-text-v1\",\n\n  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,\n  // re-index existing memories so store and query vectors stay aligned.\n  // \"embeddingUseTaskPrefixes\": true,\n  \n  // Auto-detected dimensions (no need to set manually)\n  // \"embeddingDimensions\": 768,\n  \n  // Other recommended local models:\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-base-en\",  // 768 dims, English-only, 8192 context\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-small-en\", // 512 dims, faster, 8192 context\n  // \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",            // 384 dims, very fast, 512 context\n  // \"embeddingModel\": \"Xenova/all-mpnet-base-v2\",           // 768 dims, good quality, 512 context\n  \n  // Optional: OpenAI-compatible API for embeddings (both URL and key required)\n  // \"embeddingApiUrl\": \"https://api.openai.com/v1\",\n  // \"embeddingApiKey\": \"env://OPENAI_API_KEY\",  // or \"sk-...\" / \"file:///path/to/key\"\n  // \"embeddingModel\": \"text-embedding-3-small\",  // 1536 dims, auto-detected\n \n  // ============================================\n  // Web Server Settings\n  // ============================================\n  \n  // Start a background import of past chats on each host's next start.\n  \"autoBackfill\": true,\n  // \"piBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // Directory maps for history recorded in moved or deleted directories.\n  // \"importPathMaps\": [{ \"from\": \"~/code/app-feat-x\", \"to\": \"~/code/app\" }],\n\n  // Register the web app to start when you log in.\n  \"webServerAutoStart\": true,\n  // Enable web UI for managing memories (accessible at http://localhost:4747)\n  \"webServerEnabled\": true,\n  \n  // Port for web UI server\n  \"webServerPort\": 4747,\n  \n  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)\n  \"webServerHost\": \"127.0.0.1\",\n\n  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.\n  // \"webServerAuthPassword\": \"\",\n  // \"webServerAuthUsername\": \"\",\n\n  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).\n  // \"webServerApiToken\": \"env://OMMS_WEB_TOKEN\",\n  \n  // ============================================\n  // Database Settings\n  // ============================================\n  \n  // Maximum vectors per database shard (auto-creates new shard when limit reached)\n  \"maxVectorsPerShard\": 50000,\n  \n  // Automatically delete old memories based on retention period\n  \"autoCleanupEnabled\": true,\n  \n  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)\n  \"autoCleanupRetentionDays\": 30,\n  \n  // Automatically detect and remove duplicate memories\n  \"deduplicationEnabled\": true,\n  \n   // Similarity threshold (0-1) for detecting duplicates (higher = stricter)\n   \"deduplicationSimilarityThreshold\": 0.90,\n   \n  // ============================================\n  // Memory Scope Settings\n  // ============================================\n\n  // Default scope for memory list/search queries\n  // \"project\" keeps queries within the current project, \"all-projects\" searches across all project shards\n  \"memory\": {\n    \"defaultScope\": \"project\"\n  },\n\n  // ============================================\n  // Model for auto-capture and profile learning (same rule in OpenCode and Pi)\n  // ============================================\n\n   // Which model summarises your work, in this order:\n   //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,\n   //      piProvider/piModel in Pi. Set the model to \"inherit\" to follow\n   //      whatever model the session is using, or to \"external\" to send\n   //      every call to the external API below.\n   //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/\n   //      memoryApiKey further down).\n   //   3. If neither is set: the session's own model.\n   // If the host model fails and the external API is configured, the external\n   // API is used instead.\n   //\n   // Host models go through OpenCode's or Pi's own sign-in (OAuth like Claude\n   // Pro/Max, GitHub Copilot, ChatGPT, or your own key there), so no separate API\n   // key is needed here.\n   //\n   // Examples (OpenCode names from 'opencode providers list'; Pi names from its model list):\n   //   \"opencodeProvider\": \"anthropic\",    \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n   //   \"opencodeProvider\": \"openai\",       \"opencodeModel\": \"inherit\"\n   //   \"piProvider\": \"openai-codex\",       \"piModel\": \"gpt-5.6-luna\"\n   //\n   // \"opencodeProvider\": \"anthropic\",\n   // \"opencodeModel\": \"claude-haiku-4-5-20251001\",\n   // \"piProvider\": \"openai-codex\",\n   // \"piModel\": \"gpt-5.6-luna\",\n\n   // ============================================\n   // Auto-Capture Settings\n   // ============================================\n  \n  // Auto-capture runs in the background without blocking your main session.\n  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.\n  \n  \"autoCaptureEnabled\": true,\n  \n  // Provider type: \"openai-chat\" | \"openai-responses\" | \"anthropic\" | \"minimax\" | \"orcarouter\" | \"google-gemini\"\n  // Note: \"openai-chat\" is a generic OpenAI API-compatible mode.\n  // Any service that follows the OpenAI Chat Completions API can use it via custom \"memoryApiUrl\".\n  \"memoryProvider\": \"openai-chat\",\n  \n  // External API (step 2 above, and the fallback when a host model fails).\n  // Uncomment all 3 lines and replace memoryApiKey before use:\n  // \"memoryModel\": \"gpt-4o-mini\",\n  // \"memoryApiUrl\": \"https://api.openai.com/v1\",\n  // \"memoryApiKey\": \"sk-...\",\n\n  // API Key Formats:\n  // Direct value:        \"sk-...\"\n  // From file:           \"file://~/.config/litellm-key.txt\"\n  // From env variable:   \"env://LITELLM_API_KEY\"\n  \n  // Examples for different providers:\n  // Any OpenAI-compatible endpoint can use the \"openai-chat\" provider pattern below.\n  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),\n  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).\n\n  // OpenAI Chat Completion (default, backward compatible):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"gpt-4o-mini\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n\n  // DeepSeek (OpenAI-compatible example):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"deepseek-chat\"\n  //   \"memoryApiUrl\": \"https://api.deepseek.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // OpenAI Responses API (recommended, with session support):\n  //   \"memoryProvider\": \"openai-responses\"\n  //   \"memoryModel\": \"gpt-4o\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // Anthropic (with session support):\n  //   \"memoryProvider\": \"anthropic\"\n  //   \"memoryModel\": \"claude-3-5-haiku-20241022\"\n  //   \"memoryApiUrl\": \"https://api.anthropic.com/v1\"\n  //   \"memoryApiKey\": \"sk-ant-...\"\n\n  // MiniMax (Anthropic Messages-compatible endpoint, with session support):\n  //   \"memoryProvider\": \"minimax\"\n  //   \"memoryModel\": \"MiniMax-M3\"\n  //   \"memoryApiUrl\": \"https://api.minimax.io\"        // global endpoint\n  //   \"memoryApiKey\": \"<MiniMax API key>\"\n  //   // China endpoint: \"memoryApiUrl\": \"https://api.minimaxi.com\"\n  //   // Optional adaptive thinking for MiniMax-M3:\n  //   \"memoryExtraParams\": { \"thinking\": { \"type\": \"adaptive\" } }\n\n  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):\n  //   \"memoryProvider\": \"orcarouter\"\n  //   \"memoryApiKey\": \"<OrcaRouter API key>\"\n  //   // memoryApiUrl and memoryModel are optional \u2014 they default to\n  //   // https://api.orcarouter.ai/v1 and \"orcarouter/auto\" (a routing alias).\n  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a\n  //   // namespaced ID such as \"openai/gpt-5.5\" or \"deepseek/deepseek-v4-flash\".\n  //   \"memoryModel\": \"openai/gpt-5.5\"\n\n  // Groq (OpenAI-compatible, use openai-chat provider):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"llama-3.3-70b-versatile\"\n  //   \"memoryApiUrl\": \"https://api.groq.com/openai/v1\"\n  //   \"memoryApiKey\": \"gsk_...\"\n  \n  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)\n  \"autoCaptureMaxIterations\": 5,\n   \n  // Timeout per iteration in milliseconds (30 seconds default)\n  \"autoCaptureIterationTimeout\": 30000,\n\n  // Tries for one turn's capture, on Pi and OpenCode, 2 and 4 seconds apart. After the\n  // last one fails, a turn the model could not reach goes to the capture retry queue.\n  \"autoCaptureMaxRetries\": 3,\n\n  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.\n  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).\n  // Rough guide: tokens \u2248 bytes / 4 for mixed code/prose.\n  \"autoCaptureMaxContextBytes\": 131072,\n   \n  // Days to keep AI session history before cleanup\n  \"aiSessionRetentionDays\": 7,\n\n  // Capture diagnostics: every capture attempt always writes one metadata line\n  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no\n  // conversation text. Set captureTrace to true to also write each attempt's\n  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain\n  // conversation content: <private> text and common API key formats are\n  // redacted, files are readable only by you, and they are deleted after\n  // captureTraceRetentionDays. Only this global file can turn tracing on.\n  // \"captureTrace\": false,\n  // \"captureTraceRetentionDays\": 7,\n  // \"captureAttemptRetentionDays\": 30,\n\n  // Capture retry queue: when a live capture fails because the model cannot be\n  // reached (network error, timeout, HTTP 408, 429 or 5xx), OMMS keeps a copy of\n  // the turn in ~/.omms/data and tries it again later. The copy has <private>\n  // text and common API key formats removed. Turns are deleted when the retry\n  // ends or after captureRetryRetentionHours (0 to 720). 0 turns the queue off.\n  // Only this global file can set it.\n  // \"captureRetryRetentionHours\": 72,\n\n  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)\n  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter\n  // Set to false and add \"memoryTemperature\": false in config when using such models\n  \"memoryTemperature\": 0.3,\n\n  // Extra parameters to include in API request body\n  // Useful for local inference servers (e.g. llama-server with --jinja) that support\n  // additional parameters like disabling thinking/reasoning mode\n  // Example for Qwen3 models: { \"enable_thinking\": false }\n  // \"memoryExtraParams\": {},\n\n  // Language for auto-capture summaries (default: \"auto\" for auto-detection)\n  // Options: \"auto\", \"en\", \"id\", \"zh\", \"ja\", \"es\", \"fr\", \"de\", \"ru\", \"pt\", \"ar\", \"ko\"\n  // \"autoCaptureLanguage\": \"auto\",\n\n  // ============================================\n  // Toast Notifications\n  // ============================================\n\n  // Show toast when memory is auto-captured\n  \"showAutoCaptureToasts\": true,\n\n  // Show toast when user profile is updated\n  \"showUserProfileToasts\": true,\n\n  // Show toast for error messages\n  \"showErrorToasts\": true,\n\n  // ============================================\n  // User Profile System\n  // ============================================\n\n  // Analyze user prompts every N prompts to build/update your user profile\n  // When N uncaptured prompts accumulate, AI will analyze them to identify:\n  // - User preferences (code style, communication style, tool preferences)\n  // - User patterns (recurring topics, problem domains, technical interests)\n  // - User workflows (development habits, sequences, learning style)\n  // - Skill level (overall and per-domain assessment)\n  \"userProfileAnalysisInterval\": 10,\n\n  // Days before inactive items (all types) are eligible for removal\n  \"userProfileStaleDays\": 2,\n\n  // Number of preferences shown in UI\n  \"userProfileDisplayPreferences\": 20,\n  \n  // Number of patterns shown in UI\n  \"userProfileDisplayPatterns\": 15,\n  \n  // Number of workflows shown in UI\n  \"userProfileDisplayWorkflows\": 10,\n  \n  // Number of preferences injected into LLM conversation context\n  // Keep this small \u2014 the strongest signals are enough; more dilute LLM attention\n  \"userProfileInjectPreferences\": 5,\n  \n  // Number of patterns injected into LLM conversation context\n  \"userProfileInjectPatterns\": 5,\n  \n  // Number of workflows injected into LLM conversation context\n  \"userProfileInjectWorkflows\": 3,\n  \n  // Days before preference confidence starts to decay (if not reinforced)\n  // Preferences that aren't seen again will gradually lose confidence and be removed\n  \"userProfileConfidenceDecayDays\": 30,\n  \n  // Number of profile versions to keep in changelog (for rollback/debugging)\n  // Older versions are automatically cleaned up\n  \"userProfileChangelogRetentionCount\": 5,\n\n  // Minimum evidence count for a preference/pattern to survive confidence decay\n  // Items confirmed fewer times are more likely to be pruned when confidence decays\n  \"userProfileMinEvidenceForRetention\": 3,\n\n  // Periodically merge duplicate or irrelevant profile items with the configured AI provider\n  \"userProfileAutoCleanupEnabled\": true,\n  // Number of analyzed user prompts between automatic AI cleanup runs\n  \"userProfileAutoCleanupInterval\": 100,\n\n  // Enable LLM validation of existing preferences against recent behavior.\n  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.\n  // Experimental \u2014 disabled by default.\n  \"userProfileValidationEnabled\": false,\n\n  // ============================================\n  // Search Settings\n  // ============================================\n  \n  // Minimum similarity score (0-1) for memory search results\n  \"similarityThreshold\": 0.6,\n\n  // Maximum number of memories to return in search results\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Advanced Settings\n  // ============================================\n  \n  // Inject user profile into AI context (preferences, patterns, workflows)\n  \"injectProfile\": true\n}\n";
 export declare function normalizeAutoCaptureMaxContextBytes(value: number): number;
+/** Whole hours from 0 to 720. A value that is not a number gives the default. */
+export declare function normalizeCaptureRetryRetentionHours(value: unknown): number;
 export declare function normalizeAutoCleanupRetentionDays(value: number): number;
 declare function buildConfig(fileConfig: OmmsConfig): {
     storagePath: string;
@@ -136,6 +140,7 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     captureTrace: boolean;
     captureTraceRetentionDays: number;
     captureAttemptRetentionDays: number;
+    captureRetryRetentionHours: number;
     autoBackfill: boolean;
     opencodeBackfillModel: string;
     piBackfillModel: string;
@@ -229,6 +234,7 @@ export declare let CONFIG: {
     captureTrace: boolean;
     captureTraceRetentionDays: number;
     captureAttemptRetentionDays: number;
+    captureRetryRetentionHours: number;
     autoBackfill: boolean;
     opencodeBackfillModel: string;
     piBackfillModel: string;

package/dist/config.js

@@ -53,6 +53,7 @@ const DEFAULTS = {
     captureTrace: false,
     captureTraceRetentionDays: 7,
     captureAttemptRetentionDays: 30,
+    captureRetryRetentionHours: 72,
     autoBackfill: true,
     opencodeBackfillModel: "inherit",
     piBackfillModel: "inherit",
@@ -365,7 +366,8 @@ export const CONFIG_TEMPLATE = `{
   // Timeout per iteration in milliseconds (30 seconds default)
   "autoCaptureIterationTimeout": 30000,
 
-  // Maximum number of times to retry capturing a prompt if it fails (due to network, API errors, etc.)
+  // Tries for one turn's capture, on Pi and OpenCode, 2 and 4 seconds apart. After the
+  // last one fails, a turn the model could not reach goes to the capture retry queue.
   "autoCaptureMaxRetries": 3,
 
   // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.
@@ -387,6 +389,14 @@ export const CONFIG_TEMPLATE = `{
   // "captureTraceRetentionDays": 7,
   // "captureAttemptRetentionDays": 30,
 
+  // Capture retry queue: when a live capture fails because the model cannot be
+  // reached (network error, timeout, HTTP 408, 429 or 5xx), OMMS keeps a copy of
+  // the turn in ~/.omms/data and tries it again later. The copy has <private>
+  // text and common API key formats removed. Turns are deleted when the retry
+  // ends or after captureRetryRetentionHours (0 to 720). 0 turns the queue off.
+  // Only this global file can set it.
+  // "captureRetryRetentionHours": 72,
+
   // Temperature for AI API requests (set to false to omit parameter for models that don't support it)
   // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter
   // Set to false and add "memoryTemperature": false in config when using such models
@@ -553,6 +563,13 @@ export function normalizeAutoCaptureMaxContextBytes(value) {
     }
     return value;
 }
+/** Whole hours from 0 to 720. A value that is not a number gives the default. */
+export function normalizeCaptureRetryRetentionHours(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULTS.captureRetryRetentionHours;
+    }
+    return Math.min(720, Math.max(0, Math.floor(value)));
+}
 export function normalizeAutoCleanupRetentionDays(value) {
     if (!Number.isSafeInteger(value) || value <= 0) {
         throw new Error(`Invalid autoCleanupRetentionDays config: ${value}`);
@@ -641,6 +658,7 @@ function buildConfig(fileConfig) {
         captureTrace: fileConfig.captureTrace === true,
         captureTraceRetentionDays: Math.max(1, Math.floor(fileConfig.captureTraceRetentionDays ?? DEFAULTS.captureTraceRetentionDays)),
         captureAttemptRetentionDays: normalizeAutoCleanupRetentionDays(fileConfig.captureAttemptRetentionDays ?? DEFAULTS.captureAttemptRetentionDays),
+        captureRetryRetentionHours: normalizeCaptureRetryRetentionHours(fileConfig.captureRetryRetentionHours),
         autoBackfill: fileConfig.autoBackfill ?? DEFAULTS.autoBackfill,
         opencodeBackfillModel: fileConfig.opencodeBackfillModel ?? DEFAULTS.opencodeBackfillModel,
         piBackfillModel: fileConfig.piBackfillModel ?? DEFAULTS.piBackfillModel,
@@ -796,6 +814,8 @@ export function initConfig(directory, options = {}) {
         delete projectOverrides.captureTrace;
     }
     delete projectOverrides.captureTraceRetentionDays;
+    // The queue holds conversation text, so only the global file sets how long.
+    delete projectOverrides.captureRetryRetentionHours;
     delete projectOverrides.autoBackfill;
     delete projectOverrides.opencodeBackfillModel;
     delete projectOverrides.piBackfillModel;

package/dist/core/capture-retry-policy.d.ts

@@ -0,0 +1,36 @@
+import type { CaptureFailureReason } from "./host.js";
+/** What the capture pipeline knows about a failed attempt. */
+export interface CaptureFailureInfo {
+    reason: CaptureFailureReason;
+    httpStatus?: number;
+    retryAfterMs?: number;
+}
+export type CaptureRetryClass = "retryable" | "permanent";
+/**
+ * A retry can fix a model call that never got an answer, a timeout, a rate
+ * limit, a server error, or a busy local store. Anything else would send the
+ * same input to the same model for the same bad result, and each try costs.
+ */
+export declare function classifyCaptureFailure(failure: CaptureFailureInfo): CaptureRetryClass;
+/** The wait inside a turn after quick try `attempt` fails: 2 s, then 4 s, doubling. */
+export declare function quickRetryDelayMs(attempt: number): number;
+/** Waits after the first to fourth failed tries; every later try waits 12 hours. */
+export declare const CAPTURE_RETRY_WAITS_MS: readonly [60000, number, number, number];
+export declare const CAPTURE_RETRY_LATER_WAIT_MS: number;
+/**
+ * The wait before the next try, after `failedTries` failed tries (the live
+ * attempt counts as the first). Adds up to 20 % random extra wait, and never
+ * returns less than a `Retry-After` value the API sent.
+ */
+export declare function captureRetryDelayMs(failedTries: number, retryAfterMs?: number, random?: () => number): number;
+/** Read an HTTP `Retry-After` header: seconds or an HTTP date. */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** The HTTP status a provider attached to a thrown error, if any. */
+export declare function errorHttpStatus(error: unknown): number | undefined;
+/** The `Retry-After` wait a provider attached to a thrown error, if any. */
+export declare function errorRetryAfterMs(error: unknown): number | undefined;
+/** An error that carries the HTTP status of the reply that caused it. */
+export declare function httpStatusError(message: string, httpStatus: number, retryAfterMs?: number): Error & {
+    httpStatus: number;
+    retryAfterMs?: number;
+};

package/dist/core/capture-retry-policy.js

@@ -0,0 +1,77 @@
+/**
+ * A retry can fix a model call that never got an answer, a timeout, a rate
+ * limit, a server error, or a busy local store. Anything else would send the
+ * same input to the same model for the same bad result, and each try costs.
+ */
+export function classifyCaptureFailure(failure) {
+    if (failure.reason === "persist-error")
+        return "retryable";
+    if (failure.reason !== "call-error")
+        return "permanent";
+    const status = failure.httpStatus;
+    if (status === undefined)
+        return "retryable";
+    if (status === 408 || status === 429 || status >= 500)
+        return "retryable";
+    return "permanent";
+}
+const QUICK_RETRY_BASE_MS = 2000;
+/** The wait inside a turn after quick try `attempt` fails: 2 s, then 4 s, doubling. */
+export function quickRetryDelayMs(attempt) {
+    return QUICK_RETRY_BASE_MS * Math.pow(2, attempt - 1);
+}
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+/** Waits after the first to fourth failed tries; every later try waits 12 hours. */
+export const CAPTURE_RETRY_WAITS_MS = [MINUTE, 5 * MINUTE, 30 * MINUTE, 2 * HOUR];
+export const CAPTURE_RETRY_LATER_WAIT_MS = 12 * HOUR;
+const JITTER = 0.2;
+/**
+ * The wait before the next try, after `failedTries` failed tries (the live
+ * attempt counts as the first). Adds up to 20 % random extra wait, and never
+ * returns less than a `Retry-After` value the API sent.
+ */
+export function captureRetryDelayMs(failedTries, retryAfterMs, random = Math.random) {
+    const index = Math.max(1, Math.floor(failedTries)) - 1;
+    const base = CAPTURE_RETRY_WAITS_MS[index] ?? CAPTURE_RETRY_LATER_WAIT_MS;
+    const delay = Math.round(base * (1 + JITTER * random()));
+    return retryAfterMs !== undefined && retryAfterMs > delay ? retryAfterMs : delay;
+}
+/** Read an HTTP `Retry-After` header: seconds or an HTTP date. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    const date = Date.parse(trimmed);
+    if (Number.isNaN(date))
+        return undefined;
+    return Math.max(0, date - now);
+}
+function numberField(error, key) {
+    let current = error;
+    // Follow a short cause chain: providers wrap errors once or twice.
+    for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
+        const value = current[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+        current = current.cause;
+    }
+    return undefined;
+}
+/** The HTTP status a provider attached to a thrown error, if any. */
+export function errorHttpStatus(error) {
+    return numberField(error, "httpStatus");
+}
+/** The `Retry-After` wait a provider attached to a thrown error, if any. */
+export function errorRetryAfterMs(error) {
+    return numberField(error, "retryAfterMs");
+}
+/** An error that carries the HTTP status of the reply that caused it. */
+export function httpStatusError(message, httpStatus, retryAfterMs) {
+    return Object.assign(new Error(message), {
+        httpStatus,
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+    });
+}

package/dist/core/capture.d.ts

@@ -1,3 +1,4 @@
+import { type CaptureFailureInfo } from "./capture-retry-policy.js";
 import type { CaptureConversation, CapturePromptContext, CaptureProvenance, CaptureSummaryProvider } from "./host.js";
 export interface CaptureWorkUnit extends CaptureProvenance, CaptureConversation {
     projectDirectory: string;
@@ -12,6 +13,14 @@ export type CaptureResult = {
     status: "skipped";
     type?: string;
 };
+/**
+ * Thrown by `captureConversation` for a failed attempt. Keeps the original
+ * message and cause, and adds what the retry queue needs to classify it.
+ */
+export declare class CaptureAttemptError extends Error {
+    readonly failure: CaptureFailureInfo;
+    constructor(error: unknown, failure: CaptureFailureInfo);
+}
 /**
  * Run one capture attempt and write exactly one diagnostics record for it,
  * whether it is saved, skipped, or fails.

package/dist/core/capture.js

@@ -3,6 +3,19 @@ import { buildCaptureAttemptRecord, emitCaptureAttempt } from "../services/captu
 import { memoryClient } from "../services/client.js";
 import { getTags } from "../services/tags.js";
 import { buildMarkdownContext, getAutoCaptureMarkdownBudget } from "./capture-context.js";
+import { errorHttpStatus, errorRetryAfterMs, } from "./capture-retry-policy.js";
+/**
+ * Thrown by `captureConversation` for a failed attempt. Keeps the original
+ * message and cause, and adds what the retry queue needs to classify it.
+ */
+export class CaptureAttemptError extends Error {
+    failure;
+    constructor(error, failure) {
+        super(error instanceof Error ? error.message : String(error), { cause: error });
+        this.name = "CaptureAttemptError";
+        this.failure = failure;
+    }
+}
 async function getLatestProjectMemory(containerTag) {
     try {
         const result = await memoryClient.listMemories(containerTag, 1);
@@ -31,6 +44,13 @@ export async function captureConversation(workUnit, provider) {
         outcome = result.status === "captured" ? "saved" : "skipped";
         return result;
     }
+    catch (error) {
+        throw new CaptureAttemptError(error, {
+            reason: diagnostics.failureReason ?? "call-error",
+            httpStatus: diagnostics.httpStatus ?? errorHttpStatus(error),
+            retryAfterMs: diagnostics.retryAfterMs ?? errorRetryAfterMs(error),
+        });
+    }
     finally {
         const record = buildCaptureAttemptRecord({
             host: workUnit.host,

package/dist/core/host.d.ts

@@ -40,6 +40,10 @@ export interface CaptureAttemptDiagnostics {
     userPrompt?: string;
     rawReply?: string;
     failureReason?: CaptureFailureReason;
+    /** HTTP status of a failed model call, when the path knows it. */
+    httpStatus?: number;
+    /** The wait a failed model call asked for in its `Retry-After` header. */
+    retryAfterMs?: number;
 }
 export interface CaptureSummaryRequest {
     context: string;