memorix 1.2.10 → 1.3.0

package/plugins/copilot/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/cursor/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/gemini/memorix/GEMINI.md

@@ -11,6 +11,8 @@ Use Memorix when prior workspace context, decisions, fixes, or handoff state wou
 - Use `memorix_search` for focused lookup.
 - Use `memorix_detail` before relying on a specific memory.
 - Use `memorix_store` for durable workspace knowledge.
+- Use `longTerm` on `memorix_store` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Use `memorix_store_reasoning` for the reason behind a technical decision.
 - Use `memorix_resolve` when completed or outdated memories should stop surfacing.
 

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.2.10",
+  "version": "1.3.0",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/pi/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.2.10",
+  "version": "1.3.0",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.2.10",
+      "version": "1.3.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/command-guide.ts

@@ -15,8 +15,16 @@ const GUIDES: Record<string, CliCommandGuide> = {
       'memorix memory resolve --ids 42,43 [--status resolved|archived]',
       'memorix memory consolidate --action preview|execute',
       'memorix memory promote --ids 42,43 [--trigger "..."] [--instruction "..."]',
+      'memorix memory long-term list [--all]',
+      'memorix memory long-term add --kind semantic --scope user --portability portable --title "..." --text "..." [--tags "..."] [--applicability "..."]',
+      'memorix memory long-term promote --from-observation 42 --kind procedural --scope project',
+      'memorix memory long-term qualify|approve|archive --id <id> --reason "..."',
+      'memorix memory long-term supersede --id <old-id> --superseded-by <qualified-id> --reason "..."',
+    ],
+    notes: [
+      'Personal and team visibility require `memorix identity join` or `memorix identity use` first.',
+      'Candidates never enter a task Workset. Only manual or user-confirmed `user + portable` memory may cross local projects.',
     ],
-    notes: ['Personal and team visibility require `memorix identity join` or `memorix identity use` first.'],
   },
   identity: {
     summary: 'Select the active local actor for private memory and coordination commands.',

package/src/cli/commands/codegraph.ts

@@ -217,6 +217,7 @@ export default defineCommand({
             ...(external.caution
               ? { runtimeCautions: [{ kind: 'external-codegraph-fallback' as const, message: external.caution }] }
               : {}),
+            reader,
           });
           emitResult({ project, pack, providerQuality: external.quality }, buildContextPackPrompt(pack), asJson);
           return;

package/src/cli/commands/memory.ts

@@ -51,17 +51,30 @@ export default defineCommand({
     instruction: { type: 'string', description: 'Custom instruction for promoted mini-skills' },
     tags: { type: 'string', description: 'Comma-separated extra tags for promoted mini-skills' },
     skillId: { type: 'string', description: 'Mini-skill ID for list/delete actions' },
+    kind: { type: 'string', description: 'Long-term memory kind: episodic, semantic, or procedural' },
+    scope: { type: 'string', description: 'Long-term memory scope: project, user, or team' },
+    portability: { type: 'string', description: 'Long-term memory portability: project-bound or portable' },
+    applicability: { type: 'string', description: 'When a long-term memory applies' },
+    fromObservation: { type: 'string', description: 'Observation ID to promote into long-term memory' },
+    supersededBy: { type: 'string', description: 'Qualified or approved long-term memory that replaces the current record' },
+    'superseded-by': { type: 'string', description: 'Kebab-case alias for --supersededBy' },
+    reason: { type: 'string', description: 'Evidence review reason for qualify, approve, or archive' },
+    all: { type: 'boolean', description: 'Include archived and superseded long-term memories in list output' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
   },
   run: async ({ args }) => {
     const action = (args._ as string[])?.[0] || '';
     const positional = ((args._ as string[]) ?? []).slice(1);
+    const longTermAction = action === 'long-term'
+      ? (positional[0] || (args.action as string | undefined) || 'list').trim().toLowerCase()
+      : undefined;
     const asJson = !!args.json;
 
     try {
       const readOnlyActions = new Set(['', 'search', 'graph-context', 'recent', 'suggest-topic-key', 'detail', 'timeline']);
       const needsSearchIndex = action === 'search' || action === 'detail' || action === 'timeline';
-      const context = readOnlyActions.has(action)
+      const longTermReadOnly = longTermAction === 'list' || longTermAction === 'show';
+      const context = readOnlyActions.has(action) || longTermReadOnly
         ? await getCliReadContext({ searchIndex: needsSearchIndex })
         : await getCliProjectContext({ searchIndex: true });
       const { project, dataDir, reader, identity } = context;
@@ -425,6 +438,178 @@ export default defineCommand({
           return;
         }
 
+        case 'long-term': {
+          const resolvedLongTermAction = longTermAction ?? 'list';
+          const longTermPositional = positional.slice(1);
+          const {
+            archiveLongTermMemory,
+            approveLongTermMemory,
+            createManualLongTermMemory,
+            getLongTermMemoryDetail,
+            listLongTermMemories,
+            promoteObservationToLongTermMemory,
+            qualifyLongTermMemory,
+            supersedeLongTermMemory,
+          } = await import('../../memory/long-term.js');
+          const { resolveLocalMemoryOwner } = await import('../../memory/owner.js');
+          const owner = await resolveLocalMemoryOwner(dataDir, { create: false });
+          const longTermReader = {
+            projectId: project.id,
+            ...(owner ? { ownerId: owner.id } : {}),
+            ...(reader.agentId ? { agentId: reader.agentId } : {}),
+            ...(reader.isTeamMember ? { isTeamMember: true } : {}),
+          };
+
+          const memoryId = (): string => {
+            const id = (args.id as string | undefined)?.trim()
+              || (args.fromObservation as string | undefined)?.trim()
+              || longTermPositional[0]?.trim();
+            if (!id) throw new Error('long-term memory id is required.');
+            return id;
+          };
+          const scope = () => longTermScope(args.scope as string | undefined);
+          const kind = () => longTermKind(args.kind as string | undefined);
+          const portability = () => longTermPortability(args.portability as string | undefined);
+          const reason = () => requiredLongTermReason(args.reason as string | undefined);
+
+          switch (resolvedLongTermAction) {
+            case 'list': {
+              const memories = await listLongTermMemories({
+                dataDir,
+                reader: longTermReader,
+                includeInactive: !!args.all,
+                limit: parsePositiveInt(args.limit as string | undefined, 50),
+              });
+              emitResult(
+                { project, memories },
+                memories.length === 0
+                  ? 'No long-term memories are visible in the active scope.'
+                  : memories.map(item => `- ${item.memory.id} [${item.memory.state}/${item.memory.kind}/${item.memory.scope}] ${item.memory.title}`).join('\n'),
+                asJson,
+              );
+              return;
+            }
+
+            case 'show': {
+              const detail = await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              emitResult(
+                { project, ...detail },
+                [
+                  `${detail.memory.id} [${detail.memory.state}/${detail.memory.kind}/${detail.memory.scope}]`,
+                  detail.memory.title,
+                  detail.memory.content,
+                  `Evidence: ${detail.evidence.length}`,
+                  `Audit events: ${detail.events.length}`,
+                ].join('\n'),
+                asJson,
+              );
+              return;
+            }
+
+            case 'add': {
+              const content = getStringArg(args.text as string | undefined, longTermPositional);
+              if (!content) {
+                emitError('text is required for "memorix memory long-term add"', asJson);
+                return;
+              }
+              const result = await createManualLongTermMemory({
+                dataDir,
+                projectId: project.id,
+                scope: scope(),
+                kind: kind(),
+                title: (args.title as string | undefined)?.trim() || content.slice(0, 100),
+                content,
+                facts: parseCsvList(args.facts as string | undefined),
+                tags: parseCsvList(args.tags as string | undefined),
+                applicability: (args.applicability as string | undefined)?.trim(),
+                portability: portability(),
+                reader: longTermReader,
+              });
+              emitResult(
+                { project, ...result },
+                `Created long-term memory candidate ${result.memory.id}. Qualify it after checking its evidence.`,
+                asJson,
+              );
+              return;
+            }
+
+            case 'promote': {
+              const rawId = (args.fromObservation as string | undefined)?.trim()
+                || (args.id as string | undefined)?.trim()
+                || longTermPositional[0]?.trim();
+              const observationId = Number.parseInt(rawId || '', 10);
+              if (!Number.isFinite(observationId)) {
+                emitError('fromObservation or id must be an observation ID for "memorix memory long-term promote"', asJson);
+                return;
+              }
+              const observation = getObservation(observationId, project.id);
+              if (!observation || !canManageObservation(observation, reader)) {
+                emitError('Observation was not found or is outside the active write scope.', asJson);
+                return;
+              }
+              const result = await promoteObservationToLongTermMemory({
+                dataDir,
+                observation,
+                scope: scope(),
+                kind: kind(),
+                tags: parseCsvList(args.tags as string | undefined),
+                applicability: (args.applicability as string | undefined)?.trim(),
+                reader: longTermReader,
+              });
+              emitResult(
+                { project, sourceObservationId: observation.id, ...result },
+                `Promoted observation #${observation.id} to long-term memory candidate ${result.memory.id}.`,
+                asJson,
+              );
+              return;
+            }
+
+            case 'qualify': {
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              const memory = await qualifyLongTermMemory({ dataDir, id: memoryId(), reason: reason() });
+              emitResult({ project, memory }, `Qualified long-term memory ${memory.id}.`, asJson);
+              return;
+            }
+
+            case 'approve': {
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              const memory = await approveLongTermMemory({ dataDir, id: memoryId(), reason: reason() });
+              emitResult({ project, memory }, `Approved long-term memory ${memory.id}.`, asJson);
+              return;
+            }
+
+            case 'archive': {
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              const memory = await archiveLongTermMemory({ dataDir, id: memoryId(), reason: reason() });
+              emitResult({ project, memory }, `Archived long-term memory ${memory.id}.`, asJson);
+              return;
+            }
+
+            case 'supersede': {
+              const supersededBy = (args.supersededBy as string | undefined)?.trim()
+                || (args['superseded-by'] as string | undefined)?.trim();
+              if (!supersededBy) {
+                emitError('supersededBy is required for "memorix memory long-term supersede"', asJson);
+                return;
+              }
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              await getLongTermMemoryDetail({ dataDir, id: supersededBy, reader: longTermReader });
+              const memory = await supersedeLongTermMemory({
+                dataDir,
+                id: memoryId(),
+                supersededBy,
+                reason: reason(),
+              });
+              emitResult({ project, memory }, `Superseded long-term memory ${memory.id} with ${supersededBy}.`, asJson);
+              return;
+            }
+
+            default:
+              emitError('long-term action must be list, show, add, promote, qualify, approve, archive, or supersede.', asJson);
+          }
+          return;
+        }
+
         default:
           console.log('Memorix Memory Commands');
           console.log('');
@@ -440,6 +625,13 @@ export default defineCommand({
           console.log('  memorix memory deduplicate [--query "..."] [--dryRun]');
           console.log('  memorix memory consolidate [--action preview|execute] [--threshold 0.45]');
           console.log('  memorix memory promote --ids 42,43 [--trigger "..."] [--instruction "..."]');
+          console.log('  memorix memory long-term list [--all]');
+          console.log('  memorix memory long-term add --kind semantic --scope user --portability portable --title "..." --text "..." [--tags "..."] [--applicability "..."]');
+          console.log('  memorix memory long-term promote --fromObservation 42 --kind procedural --scope project');
+          console.log('  memorix memory long-term qualify --id <id> --reason "verified against evidence"');
+          console.log('  memorix memory long-term approve --id <id> --reason "reviewed by operator"');
+          console.log('  memorix memory long-term archive --id <id> --reason "no longer current"');
+          console.log('  memorix memory long-term supersede --id <old-id> --superseded-by <qualified-id> --reason "replaced"');
       }
     } catch (error) {
       emitError(error instanceof Error ? error.message : String(error), asJson);
@@ -459,3 +651,27 @@ function getIdArg(args: Record<string, unknown>, positional: string[]): string {
     positional.join(',')
   );
 }
+
+function longTermKind(value: string | undefined): 'episodic' | 'semantic' | 'procedural' {
+  const normalized = (value ?? 'semantic').trim().toLowerCase();
+  if (normalized === 'episodic' || normalized === 'semantic' || normalized === 'procedural') return normalized;
+  throw new Error('long-term kind must be episodic, semantic, or procedural.');
+}
+
+function longTermScope(value: string | undefined): 'project' | 'user' | 'team' {
+  const normalized = (value ?? 'project').trim().toLowerCase();
+  if (normalized === 'project' || normalized === 'user' || normalized === 'team') return normalized;
+  throw new Error('long-term scope must be project, user, or team.');
+}
+
+function longTermPortability(value: string | undefined): 'project-bound' | 'portable' {
+  const normalized = (value ?? 'project-bound').trim().toLowerCase();
+  if (normalized === 'project-bound' || normalized === 'portable') return normalized;
+  throw new Error('long-term portability must be project-bound or portable.');
+}
+
+function requiredLongTermReason(value: string | undefined): string {
+  const reason = value?.trim();
+  if (!reason) throw new Error('reason is required for this long-term memory transition.');
+  return reason;
+}

package/src/codegraph/auto-context.ts

@@ -388,6 +388,7 @@ export async function buildAutoProjectContext(input: {
       stale: overview.freshness.stale,
     },
     runtimeCautions,
+    ...(input.reader ? { reader: input.reader } : {}),
     ...(input.deliveryTarget ? { deliveryTarget: input.deliveryTarget } : {}),
   });
 
@@ -601,6 +602,16 @@ export function formatAutoProjectContextSummary(context: AutoProjectContext): st
       : '- none yet',
   );
 
+  if (context.workset.durableMemory.length > 0) {
+    lines.push('', 'Durable memory');
+    for (const memory of context.workset.durableMemory.slice(0, 3)) {
+      lines.push(
+        '- ' + memory.kind + ' (' + memory.scope + ', ' + memory.state + '): '
+          + compactContinuationText(memory.summary, 28),
+      );
+    }
+  }
+
   const continuation = context.workset.continuation;
   if (continuation?.previousSession || continuation?.memories.length || continuation?.compactCheckpoint) {
     lines.push('', 'Resume from prior work');

package/src/codegraph/context-pack.ts

@@ -10,6 +10,7 @@ import type {
 } from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
+import type { ObservationReader } from '../types.js';
 
 export interface ContextPackMemory {
   id: number;
@@ -276,6 +277,7 @@ export async function attachTaskWorkset(input: {
   semanticCode?: ExternalCodeGraphOutline;
   providerQuality?: CodeGraphProviderQuality;
   runtimeCautions?: WorksetCaution[];
+  reader?: ObservationReader;
 }): Promise<ContextPack> {
   const semanticStartHere = input.semanticCode
     ? [...input.semanticCode.relatedFiles, ...input.semanticCode.entryPoints.map(entry => entry.path)]
@@ -316,6 +318,7 @@ export async function attachTaskWorkset(input: {
       stale: input.pack.warnings.filter(warning => warning.status === 'stale').length,
     },
     runtimeCautions: input.runtimeCautions,
+    ...(input.reader ? { reader: input.reader } : {}),
     deliveryTarget: 'context-pack',
   });
   return { ...input.pack, workset };

package/src/embedding/api-provider.ts

@@ -9,7 +9,7 @@ import { createHash } from 'node:crypto';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
-import type { EmbeddingProvider } from './provider.js';
+import type { EmbeddingProvider, EmbeddingRequestOptions } from './provider.js';
 
 const CACHE_DIR = process.env.MEMORIX_DATA_DIR || join(homedir(), '.memorix', 'data');
 const CACHE_FILE = join(CACHE_DIR, '.embedding-api-cache.json');
@@ -306,6 +306,10 @@ export interface APIEmbeddingProviderCreateOptions {
    * the provider. This keeps startup/cache hydration off the remote API path.
    */
   allowNetworkProbe?: boolean;
+  /** Bound the one-off remote dimension probe used on a cold API start. */
+  requestTimeoutMs?: number;
+  /** Disable retries for a bounded, best-effort API initialization. */
+  retry?: boolean;
 }
 
 function resolveEnvEmbeddingApiKey(): string | undefined {
@@ -370,7 +374,10 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
       }
     } else {
       if (!allowNetworkProbe) return null;
-      probeDimensions = await APIEmbeddingProvider.probeAPI(config);
+      probeDimensions = await APIEmbeddingProvider.probeAPI(config, {
+        timeoutMs: options.requestTimeoutMs,
+        retry: options.retry,
+      });
       console.error(`[memorix] API embedding: ${config.model} @ ${config.baseUrl} (${probeDimensions}d)`);
       // Persist for next cold start
       saveCachedDims(config, probeDimensions).catch(() => {});
@@ -430,7 +437,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return { apiKey, baseUrl, model, requestedDimensions };
   }
 
-  private static async probeAPI(config: APIEmbeddingConfig): Promise<number> {
+  private static async probeAPI(config: APIEmbeddingConfig, options?: EmbeddingRequestOptions): Promise<number> {
     const body: Record<string, unknown> = {
       model: config.model,
       input: 'dimension probe',
@@ -443,6 +450,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
       `${config.baseUrl}/embeddings`,
       config.apiKey,
       body,
+      options,
     );
 
     if (response.data.length === 0 || !response.data[0].embedding) {
@@ -452,7 +460,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return response.data[0].embedding.length;
   }
 
-  async embed(text: string): Promise<number[]> {
+  async embed(text: string, options?: EmbeddingRequestOptions): Promise<number[]> {
     const normalized = normalizeText(text);
     const hash = textHash(normalized, this.cacheKeyNamespace);
 
@@ -477,6 +485,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
         `${this.config.baseUrl}/embeddings`,
         this.config.apiKey,
         body,
+        options,
       );
       const embedding = response.data[0].embedding;
       if (embedding.length !== this.dimensions) {
@@ -521,7 +530,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return embedding;
   }
 
-  async embedBatch(texts: string[]): Promise<number[][]> {
+  async embedBatch(texts: string[], options?: EmbeddingRequestOptions): Promise<number[][]> {
     await ensureDiskCacheLoaded();
     const normalizedTexts = texts.map(normalizeText);
     const results: number[][] = new Array(texts.length);
@@ -562,6 +571,7 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
           `${this.config.baseUrl}/embeddings`,
           this.config.apiKey,
           body,
+          options,
         );
 
         this.trackUsage(response);
@@ -638,10 +648,14 @@ async function fetchWithRetry(
   url: string,
   apiKey: string,
   body: Record<string, unknown>,
+  options: EmbeddingRequestOptions = {},
   attempt = 0,
 ): Promise<EmbeddingAPIResponse> {
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 10_000);
+  const timeoutMs = typeof options.timeoutMs === 'number' && Number.isFinite(options.timeoutMs)
+    ? Math.max(100, Math.min(Math.floor(options.timeoutMs), 60_000))
+    : 10_000;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   let response: Response;
   try {
     response = await fetch(url, {
@@ -656,7 +670,7 @@ async function fetchWithRetry(
   } catch (err: unknown) {
     clearTimeout(timeout);
     if (err instanceof Error && err.name === 'AbortError') {
-      throw new Error(`Embedding API timeout after 10s: ${url}`);
+      throw new Error(`Embedding API timeout after ${timeoutMs}ms: ${url}`);
     }
     throw err;
   }
@@ -666,13 +680,13 @@ async function fetchWithRetry(
     return response.json() as Promise<EmbeddingAPIResponse>;
   }
 
-  if ((response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
+  if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
     const delay = BASE_DELAY_MS * Math.pow(2, attempt);
     const retryAfter = response.headers.get('retry-after');
     const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : delay;
     console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES} in ${waitMs}ms`);
     await new Promise(resolve => setTimeout(resolve, waitMs));
-    return fetchWithRetry(url, apiKey, body, attempt + 1);
+    return fetchWithRetry(url, apiKey, body, options, attempt + 1);
   }
 
   const errorText = await response.text().catch(() => 'unknown error');