@vellumai/assistant 0.3.5 → 0.3.7

package/src/memory/items-extractor.ts

@@ -1,15 +1,16 @@
-import Anthropic from '@anthropic-ai/sdk';
 import { and, eq, sql } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import { getConfig } from '../config/loader.js';
 import type { MemoryExtractionConfig } from '../config/types.js';
 import { getLogger } from '../util/logger.js';
 import { truncate } from '../util/truncate.js';
+import { getConfiguredProvider, createTimeout, extractToolUse, userMessage } from '../providers/provider-send-message.js';
 import { computeMemoryFingerprint } from './fingerprint.js';
 import { enqueueMemoryJob } from './jobs-store.js';
 import { extractTextFromStoredMessageContent } from './message-content.js';
 import { getDb } from './db.js';
 import { memoryItemConflicts, memoryItems, memoryItemSources, messages } from './schema.js';
+import { clampUnitInterval } from './validation.js';
 
 const log = getLogger('memory-items-extractor');
 
@@ -114,108 +115,105 @@ async function extractItemsWithLLM(
   extractionConfig: MemoryExtractionConfig,
   scopeId: string,
 ): Promise<ExtractedItem[]> {
-  const config = getConfig();
-  const apiKey = config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    log.debug('No Anthropic API key available for LLM extraction, falling back to pattern-based');
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    log.debug('Configured provider unavailable for LLM extraction, falling back to pattern-based');
     return extractItemsPatternBased(text, scopeId);
   }
 
   try {
-    const client = new Anthropic({ apiKey });
-    const abortController = new AbortController();
-    let timer: ReturnType<typeof setTimeout>;
-    const apiCall = client.messages.create({
-      model: extractionConfig.model,
-      max_tokens: 1024,
-      system: EXTRACTION_SYSTEM_PROMPT,
-      tools: [{
-        name: 'store_memory_items',
-        description: 'Store extracted memory items from the message',
-        input_schema: {
-          type: 'object' as const,
-          properties: {
-            items: {
-              type: 'array',
+    const { signal, cleanup } = createTimeout(15000);
+
+    try {
+      const response = await provider.sendMessage(
+        [userMessage(text)],
+        [{
+          name: 'store_memory_items',
+          description: 'Store extracted memory items from the message',
+          input_schema: {
+            type: 'object' as const,
+            properties: {
               items: {
-                type: 'object',
-                properties: {
-                  kind: {
-                    type: 'string',
-                    enum: [...VALID_KINDS],
-                    description: 'Category of memory item',
-                  },
-                  subject: {
-                    type: 'string',
-                    description: 'Short label (2-8 words) for what this is about',
-                  },
-                  statement: {
-                    type: 'string',
-                    description: 'Full factual statement to remember (1-2 sentences)',
-                  },
-                  confidence: {
-                    type: 'number',
-                    description: 'Confidence that this is accurate (0.0-1.0)',
-                  },
-                  importance: {
-                    type: 'number',
-                    description: 'How valuable this is to remember (0.0-1.0)',
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    kind: {
+                      type: 'string',
+                      enum: [...VALID_KINDS],
+                      description: 'Category of memory item',
+                    },
+                    subject: {
+                      type: 'string',
+                      description: 'Short label (2-8 words) for what this is about',
+                    },
+                    statement: {
+                      type: 'string',
+                      description: 'Full factual statement to remember (1-2 sentences)',
+                    },
+                    confidence: {
+                      type: 'number',
+                      description: 'Confidence that this is accurate (0.0-1.0)',
+                    },
+                    importance: {
+                      type: 'number',
+                      description: 'How valuable this is to remember (0.0-1.0)',
+                    },
                   },
+                  required: ['kind', 'subject', 'statement', 'confidence', 'importance'],
                 },
-                required: ['kind', 'subject', 'statement', 'confidence', 'importance'],
               },
             },
+            required: ['items'],
+          },
+        }],
+        EXTRACTION_SYSTEM_PROMPT,
+        {
+          config: {
+            model: extractionConfig.model,
+            max_tokens: 1024,
+            tool_choice: { type: 'tool' as const, name: 'store_memory_items' },
           },
-          required: ['items'],
+          signal,
         },
-      }],
-      tool_choice: { type: 'tool' as const, name: 'store_memory_items' },
-      messages: [{ role: 'user' as const, content: text }],
-    }, { signal: abortController.signal });
-    // Swallow the abort rejection that fires when the timeout wins the race
-    apiCall.catch(() => {});
-    const response = await Promise.race([
-      apiCall.finally(() => clearTimeout(timer)),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          abortController.abort();
-          reject(new Error('LLM extraction timeout'));
-        }, 15000);
-      }),
-    ]);
-
-    const toolBlock = response.content.find((b) => b.type === 'tool_use');
-    if (!toolBlock || toolBlock.type !== 'tool_use') {
-      log.warn('No tool_use block in LLM extraction response, falling back to pattern-based');
-      return extractItemsPatternBased(text, scopeId);
+      );
+      cleanup();
+
+      const toolBlock = extractToolUse(response);
+      if (!toolBlock) {
+        log.warn('No tool_use block in LLM extraction response, falling back to pattern-based');
+        return extractItemsPatternBased(text, scopeId);
+      }
+
+      const input = toolBlock.input as { items?: LLMExtractedItem[] };
+      if (!Array.isArray(input.items)) {
+        log.warn('Invalid items in LLM extraction response, falling back to pattern-based');
+        return extractItemsPatternBased(text, scopeId);
+      }
+
+      const items: ExtractedItem[] = [];
+      for (const raw of input.items) {
+        if (!VALID_KINDS.has(raw.kind)) continue;
+        if (!raw.subject || !raw.statement) continue;
+        const subject = truncate(String(raw.subject), 80, '');
+        const statement = truncate(String(raw.statement), 500, '');
+        const confidence = clampUnitInterval(parseScore(raw.confidence, 0.5));
+        const importance = clampUnitInterval(parseScore(raw.importance, 0.5));
+        const fingerprint = computeMemoryFingerprint(scopeId, raw.kind, subject, statement);
+        items.push({
+          kind: raw.kind as MemoryItemKind,
+          subject,
+          statement,
+          confidence,
+          importance,
+          fingerprint,
+        });
+      }
+
+      return deduplicateItems(items);
+    } finally {
+      cleanup();
     }
-
-    const input = toolBlock.input as { items?: LLMExtractedItem[] };
-    if (!Array.isArray(input.items)) {
-      log.warn('Invalid items in LLM extraction response, falling back to pattern-based');
-      return extractItemsPatternBased(text, scopeId);
-    }
-
-    const items: ExtractedItem[] = [];
-    for (const raw of input.items) {
-      if (!VALID_KINDS.has(raw.kind)) continue;
-      if (!raw.subject || !raw.statement) continue;
-      const subject = truncate(String(raw.subject), 80, '');
-      const statement = truncate(String(raw.statement), 500, '');
-      const confidence = clamp(parseScore(raw.confidence, 0.5), 0, 1);
-      const importance = clamp(parseScore(raw.importance, 0.5), 0, 1);
-      const fingerprint = computeMemoryFingerprint(scopeId, raw.kind, subject, statement);
-      items.push({
-        kind: raw.kind as MemoryItemKind,
-        subject,
-        statement,
-        confidence,
-        importance,
-        fingerprint,
-      });
-    }
-
-    return deduplicateItems(items);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.warn({ err: message }, 'LLM extraction failed, falling back to pattern-based');
@@ -287,8 +285,8 @@ export async function extractAndUpsertMemoryItemsForMessage(messageId: string, s
       db.update(memoryItems)
         .set({
           status: effectiveStatus,
-          confidence: Math.max(existing.confidence, item.confidence),
-          importance: Math.max(existing.importance ?? 0, item.importance),
+          confidence: clampUnitInterval(Math.max(existing.confidence, item.confidence)),
+          importance: clampUnitInterval(Math.max(existing.importance ?? 0, item.importance)),
           lastSeenAt: Math.max(existing.lastSeenAt, seenAt),
           verificationState: promotedState,
         })
@@ -441,10 +439,6 @@ function parseScore(value: unknown, fallback: number): number {
   return Number.isFinite(n) ? n : fallback;
 }
 
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
 /** Returns true if the given memory item is the candidate in an unresolved conflict. */
 function hasPendingConflict(itemId: string): boolean {
   const db = getDb();

package/src/memory/job-handlers/index-maintenance.ts

@@ -1,6 +1,6 @@
 import { eq } from 'drizzle-orm';
 import { getLogger } from '../../util/logger.js';
-import { getDb } from '../db.js';
+import { getDb, rawExec } from '../db.js';
 import { enqueueMemoryJob, type MemoryJob } from '../jobs-store.js';
 import { asString, BackendUnavailableError } from '../job-utils.js';
 import { getQdrantClient } from '../qdrant-client.js';
@@ -10,8 +10,8 @@ const log = getLogger('memory-jobs-worker');
 
 export function rebuildIndexJob(): void {
   const db = getDb();
-  db.run(/*sql*/ `DELETE FROM memory_segment_fts`);
-  db.run(/*sql*/ `
+  rawExec(/*sql*/ `DELETE FROM memory_segment_fts`);
+  rawExec(/*sql*/ `
     INSERT INTO memory_segment_fts(segment_id, text)
     SELECT id, text FROM memory_segments
   `);

package/src/memory/job-handlers/media-processing.ts

@@ -7,27 +7,12 @@ import {
   type PipelineStageName,
   type StageHandler,
 } from '../../config/bundled-skills/media-processing/services/processing-pipeline.js';
-import { extractKeyframesForAsset } from '../../config/bundled-skills/media-processing/tools/extract-keyframes.js';
-import { analyzeKeyframesForAsset } from '../../config/bundled-skills/media-processing/tools/analyze-keyframes.js';
-import { generateTimeline } from '../../config/bundled-skills/media-processing/services/timeline-service.js';
-import {
-  detectEvents,
-  type DetectionConfig,
-} from '../../config/bundled-skills/media-processing/services/event-detection-service.js';
+import { preprocessForAsset } from '../../config/bundled-skills/media-processing/tools/extract-keyframes.js';
+import { mapSegmentsForAsset } from '../../config/bundled-skills/media-processing/tools/analyze-keyframes.js';
+import { reduceForAsset } from '../../config/bundled-skills/media-processing/tools/query-media-events.js';
 
 const log = getLogger('media-processing-job');
 
-const defaultDetectionConfig: DetectionConfig = {
-  eventType: 'scene_change',
-  rules: [
-    {
-      ruleType: 'segment_transition',
-      params: { field: 'segmentType' },
-      weight: 1.0,
-    },
-  ],
-};
-
 export async function mediaProcessingJob(job: MemoryJob): Promise<void> {
   const mediaAssetId = asString(job.payload.mediaAssetId);
   if (!mediaAssetId) {
@@ -50,31 +35,15 @@ export async function mediaProcessingJob(job: MemoryJob): Promise<void> {
     return;
   }
 
-  // Build detection config, allowing optional eventType override from payload
-  const eventType = asString(job.payload.eventType);
-  const detectionConfig: DetectionConfig = eventType
-    ? { ...defaultDetectionConfig, eventType }
-    : defaultDetectionConfig;
-
   const handlers: Record<PipelineStageName, StageHandler> = {
-    keyframe_extraction: {
-      execute: (assetId, onProgress) =>
-        extractKeyframesForAsset(assetId, 1, onProgress),
-    },
-    vision_analysis: {
-      execute: (assetId, onProgress) =>
-        analyzeKeyframesForAsset(assetId, undefined, undefined, onProgress),
-    },
-    timeline_generation: {
-      execute: async (assetId, onProgress) => {
-        generateTimeline(assetId, { onProgress });
-      },
-    },
-    event_detection: {
-      execute: async (assetId, onProgress) => {
-        detectEvents(assetId, detectionConfig, { onProgress });
-      },
-    },
+    preprocess: { execute: async (assetId, onProgress) => { await preprocessForAsset(assetId, {}, onProgress); } },
+    map: { execute: async (assetId, onProgress) => { await mapSegmentsForAsset(assetId, {
+      systemPrompt: 'Describe what you see in these video frames. For each frame, note: subjects present, actions occurring, scene context, and any text visible.',
+      outputSchema: { type: 'object', properties: { frames: { type: 'array', items: { type: 'object', properties: { timestamp: { type: 'number' }, subjects: { type: 'array', items: { type: 'string' } }, actions: { type: 'array', items: { type: 'string' } }, scene: { type: 'string' }, text: { type: 'string' } } } } } }
+    }, onProgress); } },
+    reduce: { execute: async (assetId, onProgress) => { await reduceForAsset(assetId, {
+      systemPrompt: 'Summarize the video content based on the structured observations.',
+    }, onProgress); } },
   };
 
   const result = await runPipeline(mediaAssetId, handlers, {

package/src/memory/job-handlers/summarization.ts

@@ -1,9 +1,9 @@
-import Anthropic from '@anthropic-ai/sdk';
 import { and, desc, eq, gte, isNull, lt } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 import type { AssistantConfig } from '../../config/types.js';
 import { estimateTextTokens } from '../../context/token-estimator.js';
 import { getLogger } from '../../util/logger.js';
+import { getConfiguredProvider, createTimeout, extractText, userMessage } from '../../providers/provider-send-message.js';
 import { getConversationMemoryScopeId } from '../conversation-store.js';
 import { getDb } from '../db.js';
 import { enqueueMemoryJob, type MemoryJob } from '../jobs-store.js';
@@ -230,9 +230,9 @@ async function summarizeWithLLM(
     return buildFallbackSummary(existingSummary, newContent, label);
   }
 
-  const apiKey = config.apiKeys.anthropic ?? process.env.ANTHROPIC_API_KEY;
-  if (!apiKey) {
-    log.debug({ label }, 'No Anthropic API key available for summarization, using fallback');
+  const provider = getConfiguredProvider();
+  if (!provider) {
+    log.debug({ label }, 'Configured provider unavailable for summarization, using fallback');
     return buildFallbackSummary(existingSummary, newContent, label);
   }
 
@@ -247,30 +247,36 @@ async function summarizeWithLLM(
   userParts.push('### New Data', newContent);
 
   try {
-    const client = new Anthropic({ apiKey });
-    const response = await Promise.race([
-      client.messages.create({
-        model: summarizationConfig.model,
-        max_tokens: SUMMARY_MAX_TOKENS,
-        system: systemPrompt,
-        messages: [{ role: 'user' as const, content: userParts.join('\n') }],
-      }),
-      new Promise<never>((_, reject) =>
-        setTimeout(() => reject(new Error('Summarization LLM timeout')), SUMMARY_LLM_TIMEOUT_MS),
-      ),
-    ]);
-
-    const textBlock = response.content.find((b) => b.type === 'text');
-    if (textBlock && textBlock.type === 'text' && textBlock.text.trim().length > 0) {
-      log.debug(
-        { label, inputTokens: response.usage.input_tokens, outputTokens: response.usage.output_tokens },
-        'LLM summarization completed',
+    const { signal, cleanup } = createTimeout(SUMMARY_LLM_TIMEOUT_MS);
+    try {
+      const response = await provider.sendMessage(
+        [userMessage(userParts.join('\n'))],
+        undefined,
+        systemPrompt,
+        {
+          config: {
+            model: summarizationConfig.model,
+            max_tokens: SUMMARY_MAX_TOKENS,
+          },
+          signal,
+        },
       );
-      return textBlock.text.trim();
-    }
+      cleanup();
 
-    log.warn({ label }, 'LLM summarization returned empty text, using fallback');
-    return buildFallbackSummary(existingSummary, newContent, label);
+      const text = extractText(response);
+      if (text.length > 0) {
+        log.debug(
+          { label, inputTokens: response.usage.inputTokens, outputTokens: response.usage.outputTokens },
+          'LLM summarization completed',
+        );
+        return text;
+      }
+
+      log.warn({ label }, 'LLM summarization returned empty text, using fallback');
+      return buildFallbackSummary(existingSummary, newContent, label);
+    } finally {
+      cleanup();
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     log.warn({ err: message, label }, 'LLM summarization failed, using fallback');

package/src/memory/job-utils.ts

@@ -6,18 +6,11 @@ import { getDb } from './db.js';
 import { getQdrantClient } from './qdrant-client.js';
 import { memoryEmbeddings } from './schema.js';
 import type { AssistantConfig } from '../config/types.js';
+import { BackendUnavailableError } from '../util/errors.js';
 
-const log = getLogger('memory-jobs-worker');
-
-// ── Sentinel error ─────────────────────────────────────────────────
+export { BackendUnavailableError };
 
-/** Sentinel error: the embedding backend is not configured yet. */
-export class BackendUnavailableError extends Error {
-  constructor(reason: string) {
-    super(reason);
-    this.name = 'BackendUnavailableError';
-  }
-}
+const log = getLogger('memory-jobs-worker');
 
 // ── Error classification for LLM / API errors ─────────────────────
 

package/src/memory/jobs-store.ts

@@ -1,6 +1,6 @@
 import { and, asc, eq, lte, notInArray, inArray } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
-import { getDb } from './db.js';
+import { getDb, rawGet, rawAll } from './db.js';
 import { memoryJobs } from './schema.js';
 import { truncate } from '../util/truncate.js';
 
@@ -110,9 +110,8 @@ export function enqueueResolvePendingConflictsForMessageJob(
     throw new Error('enqueueResolvePendingConflictsForMessageJob requires a non-empty messageId');
   }
   const normalizedScopeId = scopeId.trim() || 'default';
-  // Dedup check always uses root db since tx doesn't expose $client
-  const raw = (getDb() as unknown as { $client: { query: (q: string) => { get: (...params: unknown[]) => unknown } } }).$client;
-  const existing = raw.query(`
+  // Dedup check always uses root db since tx doesn't expose raw client
+  const existing = rawGet<{ id: string }>(`
     SELECT id
     FROM memory_jobs
     WHERE type = 'resolve_pending_conflicts_for_message'
@@ -121,7 +120,7 @@ export function enqueueResolvePendingConflictsForMessageJob(
       AND COALESCE(json_extract(payload, '$.scopeId'), 'default') = ?
     ORDER BY created_at ASC
     LIMIT 1
-  `).get(normalizedMessageId, normalizedScopeId) as { id: string } | null;
+  `, normalizedMessageId, normalizedScopeId);
   if (existing?.id) return existing.id;
 
   return enqueueMemoryJob('resolve_pending_conflicts_for_message', {
@@ -366,13 +365,11 @@ export function resetRunningJobsToPending(): number {
 }
 
 export function getMemoryJobCounts(): Record<string, number> {
-  const db = getDb();
-  const raw = (db as unknown as { $client: { query: (q: string) => { all: () => unknown[] } } }).$client;
-  const rows = raw.query(`
+  const rows = rawAll<{ status: string; c: number }>(`
     SELECT status, COUNT(*) AS c
     FROM memory_jobs
     GROUP BY status
-  `).all() as Array<{ status: string; c: number }>;
+  `);
   const counts: Record<string, number> = { pending: 0, running: 0, completed: 0, failed: 0 };
   for (const row of rows) {
     counts[row.status] = row.c;

package/src/memory/jobs-worker.ts

@@ -1,7 +1,7 @@
 import type { AssistantConfig } from '../config/types.js';
 import { getConfig } from '../config/loader.js';
 import { getLogger } from '../util/logger.js';
-import { getDb } from './db.js';
+import { rawRun } from './db.js';
 import {
   claimMemoryJobs,
   completeMemoryJob,
@@ -112,38 +112,56 @@ export async function runMemoryJobsOnce(
   let processed = 0;
   const typeGroups = [...jobsByType.values()];
 
-  // Run type groups concurrently (up to workerConcurrency at a time).
-  // Within each group, jobs are processed sequentially.
-  for (let i = 0; i < typeGroups.length; i += concurrency) {
-    const groupChunk = typeGroups.slice(i, i + concurrency);
-    const groupResults = await Promise.allSettled(
-      groupChunk.map(async (group) => {
-        let groupProcessed = 0;
-        for (const job of group) {
-          try {
-            await processJob(job, config);
-            completeMemoryJob(job.id);
-            bumpMemoryVersion();
-            groupProcessed += 1;
-          } catch (err) {
-            try {
-              handleJobError(job, err);
-            } catch (handlerErr) {
-              log.error({ err: handlerErr, jobId: job.id, type: job.type }, 'handleJobError itself threw, job left in running status');
-            }
-          }
+  // Run type groups concurrently using a task pool (up to workerConcurrency
+  // active at a time). Unlike the old wave approach, a new group starts as
+  // soon as any slot frees up — no waiting for an entire wave to finish.
+  const processGroup = async (group: MemoryJob[]): Promise<number> => {
+    let groupProcessed = 0;
+    for (const job of group) {
+      try {
+        await processJob(job, config);
+        completeMemoryJob(job.id);
+        bumpMemoryVersion();
+        groupProcessed += 1;
+      } catch (err) {
+        try {
+          handleJobError(job, err);
+        } catch (handlerErr) {
+          log.error({ err: handlerErr, jobId: job.id, type: job.type }, 'handleJobError itself threw, job left in running status');
         }
-        return groupProcessed;
-      }),
-    );
-    for (const result of groupResults) {
+      }
+    }
+    return groupProcessed;
+  };
+
+  if (typeGroups.length <= concurrency) {
+    // Fast path: all groups fit within the concurrency limit
+    const results = await Promise.allSettled(typeGroups.map(processGroup));
+    for (const result of results) {
       if (result.status === 'fulfilled') {
         processed += result.value;
+      } else {
+        log.error({ err: result.reason }, 'Memory job group rejected unexpectedly — jobs in this batch may have been dropped');
       }
-      // Errors within groups are already handled per-job above;
-      // a rejected group promise would only come from an unexpected
-      // error in the loop itself, which is unlikely.
     }
+  } else {
+    // Task pool: maintain `concurrency` in-flight groups at all times
+    let nextIdx = 0;
+
+    const startNext = (): Promise<void> | undefined => {
+      if (nextIdx >= typeGroups.length) return undefined;
+      const group = typeGroups[nextIdx++]!;
+      return processGroup(group).then(
+        (count) => { processed += count; },
+        (err) => { log.error({ err }, 'Memory job group rejected unexpectedly — jobs in this batch may have been dropped'); },
+      ).then(() => startNext());
+    };
+
+    const workers = Array.from(
+      { length: Math.min(concurrency, typeGroups.length) },
+      () => startNext()!,
+    );
+    await Promise.all(workers);
   }
   if (enableScheduledCleanup) {
     maybeEnqueueScheduledCleanupJobs(config);
@@ -296,16 +314,13 @@ export function sweepStaleItems(config: AssistantConfig): number {
   if (now - lastStaleSweepMs < STALE_SWEEP_INTERVAL_MS) return 0;
   lastStaleSweepMs = now;
 
-  const db = getDb();
-  const raw = (db as unknown as { $client: { query: (q: string) => { run: (...params: unknown[]) => { changes: number } } } }).$client;
-
   let totalMarked = 0;
   for (const [kind, maxAgeDays] of Object.entries(freshness.maxAgeDays)) {
     if (maxAgeDays <= 0) continue;
     // Mark invalid if: past 2x window, no access in the shield period, and not already invalid
     const cutoffMs = now - maxAgeDays * 2 * 86_400_000;
     const shieldCutoffMs = now - freshness.reinforcementShieldDays * 86_400_000;
-    const result = raw.query(`
+    const changes = rawRun(`
       UPDATE memory_items
       SET invalid_at = ?
       WHERE kind = ?
@@ -313,10 +328,10 @@ export function sweepStaleItems(config: AssistantConfig): number {
         AND invalid_at IS NULL
         AND last_seen_at < ?
         AND (access_count = 0 OR COALESCE(last_used_at, 0) < ?)
-    `).run(now, kind, cutoffMs, shieldCutoffMs);
-    if (result.changes > 0) {
-      log.info({ kind, marked: result.changes, cutoffMs }, 'Marked stale memory items as invalid');
-      totalMarked += result.changes;
+    `, now, kind, cutoffMs, shieldCutoffMs);
+    if (changes > 0) {
+      log.info({ kind, marked: changes, cutoffMs }, 'Marked stale memory items as invalid');
+      totalMarked += changes;
     }
   }
   return totalMarked;

package/src/memory/migrations/001-job-deferrals.ts

@@ -0,0 +1,45 @@
+import { getSqliteFrom, type DrizzleDb } from '../db-connection.js';
+
+/**
+ * One-shot migration: reconcile old deferral history into the new `deferrals` column.
+ *
+ * Before the `deferrals` column was added, `deferMemoryJob` incremented `attempts`.
+ * After the column is added with DEFAULT 0, those legacy jobs still carry the old
+ * attempt count (which was really a deferral count) while `deferrals` is 0. This
+ * moves the attempt count into `deferrals` and resets `attempts` to 0.
+ *
+ * This migration MUST run only once. On subsequent startups, post-migration jobs
+ * that genuinely failed via `failMemoryJob` (attempts > 0, deferrals = 0, non-null
+ * last_error) must NOT be touched — resetting their attempts would let them bypass
+ * the configured maxAttempts budget across restarts.
+ *
+ * We use a `memory_checkpoints` row to ensure the migration runs exactly once.
+ */
+export function migrateJobDeferrals(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  const checkpoint = raw.query(
+    `SELECT 1 FROM memory_checkpoints WHERE key = 'migration_job_deferrals'`
+  ).get();
+  if (checkpoint) return;
+
+  try {
+    raw.exec(/*sql*/ `
+      BEGIN;
+      UPDATE memory_jobs
+      SET deferrals = attempts,
+          attempts = 0,
+          last_error = NULL,
+          updated_at = ${Date.now()}
+      WHERE status = 'pending'
+        AND attempts > 0
+        AND deferrals = 0
+        AND type IN ('embed_segment', 'embed_item', 'embed_summary');
+      INSERT OR IGNORE INTO memory_checkpoints (key, value, updated_at)
+      VALUES ('migration_job_deferrals', '1', ${Date.now()});
+      COMMIT;
+    `);
+  } catch (e) {
+    try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+    throw e;
+  }
+}