memorix 1.9.5 → 1.9.7

package/src/server.ts

@@ -253,7 +253,9 @@ export async function createMemorixServer(
   graphManager: KnowledgeGraphManager;
   projectId: string;
   deferredInit: () => Promise<void>;
-  switchProject: (newCwd: string) => Promise<boolean>;
+  activateProjectRuntime: () => Promise<void>;
+  switchProject: (newCwd: string, source?: ProjectBindingSource) => Promise<boolean>;
+  getProjectDataDir: () => string;
   isExplicitlyBound: () => boolean;
   getRequestContext: () => import('./server/request-context.js').MemorixRequestContext;
   handleTransportClose: () => void;
@@ -497,6 +499,31 @@ export async function createMemorixServer(
     await projectRuntimeInitPromise;
   };
 
+  /**
+   * Restore process-wide stores/config before a pooled modern runtime handles
+   * a tool call. The durable database is shared, but project-root config and
+   * the in-memory observation facade are process-global legacy state.
+   */
+  const activateProjectRuntime = async (): Promise<void> => {
+    if (!projectResolved) return;
+
+    await initObservationStore(projectDir);
+    await initMiniSkillStore(projectDir);
+    await initSessionStore(projectDir);
+    await initObservations(projectDir, { skipCorpusLoad: true });
+
+    try {
+      const { initProjectRoot } = await import('./config/yaml-loader.js');
+      const { resetDotenv, loadDotenv } = await import('./config/dotenv-loader.js');
+      initProjectRoot(project.rootPath);
+      resetDotenv();
+      loadDotenv(project.rootPath);
+    } catch {
+      // Config activation is best-effort; durable project scoping remains explicit.
+    }
+    initLLM({ projectRoot: project.rootPath });
+  };
+
   let maintenanceWorker: { stop(): void } | null = null;
   const startProjectMaintenanceWorker = async (autoCleanup = false): Promise<void> => {
     maintenanceWorker?.stop();
@@ -838,8 +865,9 @@ export async function createMemorixServer(
           currentFormationStage = event.stage;
           if (event.stageDurationMs !== undefined) {
             completedFormationStages[event.stage] = event.stageDurationMs;
-          }
-        };
+    }
+  };
+
         try {
           const formationConfig: FormationConfig = {
             mode: 'active',
@@ -1593,6 +1621,7 @@ export async function createMemorixServer(
         'reliable code-bound memories, stale/suspect cautions, and verification hints. Use this at the start of a new coding turn or after switching tasks.',
       inputSchema: {
         task: z.string().optional().describe('Current coding task or question'),
+        taskId: z.string().max(120).optional().describe('Optional task continuity ledger id to include in the brief'),
         refresh: z.enum(['auto', 'always', 'never']).optional().default('auto').describe(
           'Code Memory refresh policy. auto refreshes only when missing or stale.',
         ),
@@ -1606,7 +1635,7 @@ export async function createMemorixServer(
         limit: z.number().optional().describe('Reserved for future source limits; current prompt stays compact by default.'),
       },
     },
-    async ({ task, refresh, format, agent }) => {
+    async ({ task, taskId, refresh, format, agent }) => {
       const unresolved = requireResolvedProject('build project context for the current project');
       if (unresolved) return unresolved;
 
@@ -1637,6 +1666,7 @@ export async function createMemorixServer(
         dataDir: projectDir,
         observations,
         task,
+        taskId,
         agent,
         refresh: refresh ?? 'auto',
         reader: getObservationReader(),
@@ -4594,6 +4624,99 @@ export async function createMemorixServer(
     },
   );
 
+  server.registerTool(
+    'memorix_continuity',
+    {
+      title: 'Task Continuity Ledger',
+      description:
+        'Maintain a bounded, append-only continuity ledger for a coding task. ' +
+        'Use start for requirements, record for decisions/verification/risks, ' +
+        'show or list to inspect, and close for the final outcome. Pass the returned taskId ' +
+        'to memorix_project_context so the current brief includes this ledger.',
+      inputSchema: {
+        action: z.enum(['start', 'record', 'show', 'list', 'close']).describe('Continuity operation'),
+        taskId: z.string().max(120).optional().describe('Continuity task id'),
+        task: z.string().max(1_000).optional().describe('Task description for start'),
+        requirements: z.array(z.string().max(2_000)).max(8).optional().describe('Requirements for start'),
+        kind: z.enum(['requirement', 'decision', 'verification', 'risk']).optional().describe('Entry kind for record'),
+        content: z.string().max(2_000).optional().describe('Requirement, decision, verification, risk, or outcome text'),
+        verificationStatus: z.enum(['pending', 'passed', 'failed', 'skipped']).optional(),
+        verificationId: z.string().max(120).optional().describe('Stable verification obligation id; reuse it to move pending to passed/failed'),
+        idempotencyKey: z.string().max(200).optional().describe('Stable retry key; repeating the same operation returns the original event'),
+        status: z.enum(['completed', 'blocked', 'abandoned']).optional().describe('Outcome status for close'),
+        sourceRef: z.string().max(500).optional().describe('Evidence or source reference'),
+        evidenceRefs: z.array(z.string().max(500)).max(8).optional(),
+        actor: z.string().max(200).optional(),
+        limit: z.number().int().positive().max(100).optional().default(20),
+      },
+    },
+    async ({ action, taskId, task, requirements, kind, content, verificationStatus, verificationId, idempotencyKey, status, sourceRef, evidenceRefs, actor, limit }) => {
+      const unresolved = requireResolvedProject('manage task continuity for the current project');
+      if (unresolved) return unresolved;
+      const { TaskContinuityStore } = await import('./knowledge/task-continuity.js');
+      const continuity = new TaskContinuityStore();
+      await continuity.init(projectDir);
+      const effectiveActor = actor ?? currentAgentId;
+      try {
+        if (action === 'start') {
+          if (!task?.trim()) return { content: [{ type: 'text' as const, text: 'task is required for continuity start.' }], isError: true };
+          const result = continuity.start({
+            projectId: project.id,
+            task,
+            ...(taskId ? { taskId } : {}),
+            requirements,
+            ...(effectiveActor ? { actor: effectiveActor } : {}),
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+          });
+          return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, ...result }, null, 2) }] };
+        }
+        if (action === 'list') {
+          return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, ledgers: continuity.list(project.id, limit), }, null, 2) }] };
+        }
+        if (!taskId?.trim()) return { content: [{ type: 'text' as const, text: 'taskId is required for this continuity action.' }], isError: true };
+        if (action === 'show') {
+          const ledger = continuity.get(project.id, taskId);
+          if (!ledger) return { content: [{ type: 'text' as const, text: 'Task continuity ledger not found.' }], isError: true };
+          return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, ledger }, null, 2) }] };
+        }
+        if (action === 'record') {
+          if (!kind || !content?.trim()) {
+            return { content: [{ type: 'text' as const, text: 'record requires kind and content.' }], isError: true };
+          }
+          const result = continuity.record({
+            projectId: project.id,
+            taskId,
+            kind,
+            content,
+            ...(verificationStatus ? { verificationStatus } : {}),
+            ...(sourceRef ? { sourceRef } : {}),
+            ...(evidenceRefs ? { evidenceRefs } : {}),
+            ...(effectiveActor ? { actor: effectiveActor } : {}),
+            ...(verificationId ? { verificationId } : {}),
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+          });
+          return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, ...result }, null, 2) }] };
+        }
+        if (!status || !content?.trim()) {
+          return { content: [{ type: 'text' as const, text: 'close requires status and content.' }], isError: true };
+        }
+        const result = continuity.close({
+          projectId: project.id,
+          taskId,
+          status,
+          content,
+          ...(sourceRef ? { sourceRef } : {}),
+          ...(evidenceRefs ? { evidenceRefs } : {}),
+          ...(effectiveActor ? { actor: effectiveActor } : {}),
+          ...(idempotencyKey ? { idempotencyKey } : {}),
+        });
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, ...result }, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }], isError: true };
+      }
+    },
+  );
+
   // Use shared TeamStore (from HTTP server) or create new one (stdio mode).
   // All team state is canonical in SQLite — no JSON persistence, no sync/flush.
   if (teamFeaturesEnabled) {
@@ -5725,7 +5848,8 @@ export async function createMemorixServer(
   };
 
   return {
-    server, graphManager, projectId: project.id, deferredInit, switchProject,
+    server, graphManager, projectId: project.id, deferredInit, activateProjectRuntime, switchProject,
+    getProjectDataDir: () => projectDir,
     isExplicitlyBound: () => projectBinding.isExplicit(),
     getRequestContext,
     handleTransportClose,

package/src/store/orama-store.ts

@@ -909,6 +909,11 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
   // Fast-tier queries skip embedding entirely (fulltext is sufficient)
   let queryVector: number[] | null = null;
   let embeddingProviderForSearch: EmbeddingProvider | null = null;
+  // Distinct from `embeddingEnabled` (static config): this tracks whether the
+  // current query can use embeddings (provider unavailable, incompatible
+  // dimensions, TLS, network, or timeout). `canUsePersistentLexical` below
+  // must fall back whenever this is true.
+  let embeddingUnavailable = false;
   if (quality !== 'fast' && embeddingEnabled && hasQuery && tier !== 'fast') {
     try {
       const provider = await getEmbeddingProvider();
@@ -916,6 +921,7 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
         embeddingProviderForSearch = provider;
         const activeVectorDimensions = getVectorDimensions();
         if (activeVectorDimensions !== null && provider.dimensions !== activeVectorDimensions) {
+          embeddingUnavailable = true;
           rememberSearchMode(
             modeKey,
             `fulltext (embedding dimension mismatch: provider ${provider.dimensions}d vs index ${activeVectorDimensions}d)`,
@@ -961,9 +967,12 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
               : { text: 0.6, vector: 0.4 },
           };
         }
+      } else {
+        embeddingUnavailable = true;
       }
     } catch (error) {
       // Fallback to fulltext if embedding fails or times out
+      embeddingUnavailable = true;
       rememberSearchMode(modeKey, 'fulltext (embedding unavailable)');
       console.error('[memorix] Embedding failed or timed out, falling back to fulltext search');
     }
@@ -972,8 +981,14 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
   mark('preSearch');
   let results: SearchResultLike | Awaited<ReturnType<typeof search>>;
   const persistentCorpusEligible = await shouldUsePersistentSearch(projectIds, options.projectId);
+  // `embeddingEnabled` alone misses the common case: embedding is configured
+  // (enabled) but the current provider is unavailable, has incompatible
+  // dimensions, or failed at runtime. Without this per-query state, those
+  // failures leave queryVector null AND canUsePersistentLexical false, so
+  // neither the semantic nor lexical persistent path runs — a silent,
+  // deterministic empty result despite the FTS5 index having real matches.
   const canUsePersistentLexical = persistentCorpusEligible && Boolean(hasQuery) && !queryVector &&
-    (quality === 'fast' || tier === 'fast' || !embeddingEnabled);
+    (quality === 'fast' || tier === 'fast' || !embeddingEnabled || embeddingUnavailable);
   let persistent = persistentCorpusEligible && queryVector && embeddingProviderForSearch
     ? await searchPersistentSemantically(options, projectIds, requestLimit, queryVector, embeddingProviderForSearch)
     : canUsePersistentLexical

package/src/store/sqlite-db.ts

@@ -821,6 +821,45 @@ CREATE TABLE IF NOT EXISTS memory_feedback_events (
 );
 `;
 
+const CREATE_TASK_CONTINUITY_EVENTS_TABLE = `
+CREATE TABLE IF NOT EXISTS task_continuity_events (
+  id              TEXT PRIMARY KEY,
+  project_id      TEXT NOT NULL,
+  task_id         TEXT NOT NULL,
+  task            TEXT NOT NULL,
+  kind            TEXT NOT NULL,
+  content         TEXT NOT NULL,
+  item_status     TEXT,
+  source_ref      TEXT,
+  evidence_json   TEXT NOT NULL DEFAULT '[]',
+  actor           TEXT,
+  created_at      TEXT NOT NULL,
+  event_key       TEXT,
+  item_key        TEXT,
+  supersedes_id   TEXT
+);
+`;
+
+const CREATE_AGENT_EFFECTS_TABLE = `
+CREATE TABLE IF NOT EXISTS agent_effects (
+  id                TEXT PRIMARY KEY,
+  pipeline_id       TEXT NOT NULL,
+  task_id           TEXT NOT NULL,
+  attempt           INTEGER NOT NULL,
+  effect_key        TEXT NOT NULL,
+  tool              TEXT NOT NULL,
+  risk_tier         TEXT NOT NULL,
+  replay_policy     TEXT NOT NULL,
+  status            TEXT NOT NULL,
+  call_id           TEXT,
+  idempotency_key   TEXT NOT NULL,
+  input_fingerprint TEXT,
+  detail            TEXT,
+  started_at        INTEGER NOT NULL,
+  finished_at       INTEGER
+);
+`;
+
 const CREATE_MCP_BINDINGS_TABLE = `
 CREATE TABLE IF NOT EXISTS mcp_bindings (
   handle_id    TEXT PRIMARY KEY,
@@ -899,7 +938,18 @@ CREATE INDEX IF NOT EXISTS idx_evidence_cards_candidate ON evidence_cards(projec
 CREATE INDEX IF NOT EXISTS idx_evidence_card_events_card ON evidence_card_events(card_id, created_at);
 CREATE INDEX IF NOT EXISTS idx_memory_feedback_states_project ON memory_feedback_states(project_id, candidate_kind, updated_at DESC);
 CREATE INDEX IF NOT EXISTS idx_memory_feedback_events_candidate ON memory_feedback_events(project_id, candidate_kind, candidate_id, observed_at DESC);
+CREATE INDEX IF NOT EXISTS idx_task_continuity_project_task ON task_continuity_events(project_id, task_id, created_at ASC);
+CREATE INDEX IF NOT EXISTS idx_task_continuity_project_recent ON task_continuity_events(project_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_task_continuity_item ON task_continuity_events(project_id, task_id, kind, item_key, created_at DESC);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_task_continuity_event_key
+  ON task_continuity_events(project_id, task_id, event_key)
+  WHERE event_key IS NOT NULL;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agent_effect_identity
+  ON agent_effects(pipeline_id, task_id, attempt, effect_key);
+CREATE INDEX IF NOT EXISTS idx_agent_effect_pipeline ON agent_effects(pipeline_id, started_at ASC);
 CREATE INDEX IF NOT EXISTS idx_mcp_bindings_project ON mcp_bindings(project_id, last_used_at DESC);
+CREATE INDEX IF NOT EXISTS idx_mcp_bindings_root ON mcp_bindings(project_root, last_used_at DESC);
+CREATE INDEX IF NOT EXISTS idx_mcp_bindings_expiry ON mcp_bindings(expires_at);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_maintenance_jobs_active_dedupe
   ON maintenance_jobs(project_id, kind, dedupe_key)
   WHERE status IN ('pending', 'running', 'retry');
@@ -1078,6 +1128,8 @@ const SCHEMA_MIGRATIONS: SchemaMigration[] = [
       db.exec('CREATE INDEX IF NOT EXISTS idx_memory_feedback_states_project ON memory_feedback_states(project_id, candidate_kind, updated_at DESC)');
       db.exec('CREATE INDEX IF NOT EXISTS idx_memory_feedback_events_candidate ON memory_feedback_events(project_id, candidate_kind, candidate_id, observed_at DESC)');
       db.exec('CREATE INDEX IF NOT EXISTS idx_mcp_bindings_project ON mcp_bindings(project_id, last_used_at DESC)');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_mcp_bindings_root ON mcp_bindings(project_root, last_used_at DESC)');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_mcp_bindings_expiry ON mcp_bindings(expires_at)');
     },
   },
   {
@@ -1089,6 +1141,18 @@ const SCHEMA_MIGRATIONS: SchemaMigration[] = [
       addColumnIfMissing(db, 'code_edges', 'source', 'source TEXT');
     },
   },
+  {
+    id: '1.9-continuity-v2',
+    apply: (db) => {
+      addColumnIfMissing(db, 'task_continuity_events', 'event_key', 'event_key TEXT');
+      addColumnIfMissing(db, 'task_continuity_events', 'item_key', 'item_key TEXT');
+      addColumnIfMissing(db, 'task_continuity_events', 'supersedes_id', 'supersedes_id TEXT');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_task_continuity_item ON task_continuity_events(project_id, task_id, kind, item_key, created_at DESC)');
+      db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_task_continuity_event_key
+        ON task_continuity_events(project_id, task_id, event_key)
+        WHERE event_key IS NOT NULL`);
+    },
+  },
 ];
 
 function applySchemaMigrations(db: any): void {
@@ -1110,6 +1174,28 @@ function applySchemaMigrations(db: any): void {
 // ── Singleton cache ─────────────────────────────────────────────────
 
 const _dbCache = new Map<string, any>();
+const _dbLeases = new Map<string, number>();
+
+export interface DatabaseLease {
+  dataDir: string;
+  db: any;
+  release: () => void;
+}
+
+export interface DatabaseStats {
+  cached: number;
+  leased: number;
+  leasedDataDirs: number;
+}
+
+function normalizeDataDir(dataDir: string): string {
+  return path.resolve(dataDir);
+}
+
+function touchDatabase(normalized: string, db: any): void {
+  _dbCache.delete(normalized);
+  _dbCache.set(normalized, db);
+}
 
 /**
  * Get or create a shared SQLite database handle for the given data directory.
@@ -1120,10 +1206,13 @@ const _dbCache = new Map<string, any>();
  * Callers must NOT close the returned handle directly — use closeDatabase().
  */
 export function getDatabase(dataDir: string): any {
-  const normalized = path.resolve(dataDir);
+  const normalized = normalizeDataDir(dataDir);
   assertNotHomeDataDir(normalized);
   const existing = _dbCache.get(normalized);
-  if (existing) return existing;
+  if (existing) {
+    touchDatabase(normalized, existing);
+    return existing;
+  }
 
   loadBetterSqlite3();
   fs.mkdirSync(dataDir, { recursive: true });
@@ -1161,6 +1250,8 @@ export function getDatabase(dataDir: string): any {
   db.exec(CREATE_MAINTENANCE_JOBS_TABLE);
   db.exec(CREATE_MAINTENANCE_TARGETS_TABLE);
   db.exec(CREATE_COMPACTION_CHECKPOINTS_TABLE);
+  db.exec(CREATE_TASK_CONTINUITY_EVENTS_TABLE);
+  db.exec(CREATE_AGENT_EFFECTS_TABLE);
 
   // Phase 3a migration: add sourceSnapshot + updatedAt to mini_skills
   // Idempotent — ALTER TABLE ADD COLUMN throws if column already exists
@@ -1194,7 +1285,7 @@ export function getDatabase(dataDir: string): any {
   db.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('next_id', '1')`).run();
   db.prepare(`INSERT OR IGNORE INTO meta (key, value) VALUES ('mini_skills_generation', '0')`).run();
 
-    _dbCache.set(normalized, db);
+    touchDatabase(normalized, db);
     return db;
   } catch (error) {
     // A schema/migration/FTS failure must not leave an uncached connection
@@ -1204,12 +1295,60 @@ export function getDatabase(dataDir: string): any {
   }
 }
 
+/**
+ * Hold a database handle across an HTTP/session lifetime. Idle eviction only
+ * closes handles with no active leases, so cache pressure cannot invalidate a
+ * store that is still serving a request.
+ */
+export function acquireDatabase(dataDir: string): DatabaseLease {
+  const normalized = normalizeDataDir(dataDir);
+  const db = getDatabase(normalized);
+  _dbLeases.set(normalized, (_dbLeases.get(normalized) ?? 0) + 1);
+  let released = false;
+  return {
+    dataDir: normalized,
+    db,
+    release: () => {
+      if (released) return;
+      released = true;
+      const count = (_dbLeases.get(normalized) ?? 0) - 1;
+      if (count > 0) _dbLeases.set(normalized, count);
+      else _dbLeases.delete(normalized);
+    },
+  };
+}
+
+/** Return bounded resource information for health and diagnostics. */
+export function getDatabaseStats(): DatabaseStats {
+  let leased = 0;
+  for (const count of _dbLeases.values()) leased += count;
+  return { cached: _dbCache.size, leased, leasedDataDirs: _dbLeases.size };
+}
+
+/**
+ * Evict least-recently-used unleased handles until the cache is within its
+ * target. Stores that need a handle across awaits must hold a lease first.
+ */
+export function evictIdleDatabases(maxCached: number): number {
+  const target = Math.max(0, Math.floor(maxCached));
+  let evicted = 0;
+  for (const [normalized, db] of [..._dbCache]) {
+    if (_dbCache.size <= target) break;
+    if ((_dbLeases.get(normalized) ?? 0) > 0) continue;
+    try { db.close(); } catch { /* best-effort */ }
+    _dbCache.delete(normalized);
+    evicted++;
+  }
+  return evicted;
+}
+
 /**
  * Close and remove a cached database handle for the given data directory.
  * Safe to call even if no handle exists.
  */
 export function closeDatabase(dataDir: string): void {
-  const normalized = path.resolve(dataDir);
+  const normalized = normalizeDataDir(dataDir);
+  if ((_dbLeases.get(normalized) ?? 0) > 0) return;
   const db = _dbCache.get(normalized);
   if (db) {
     try { db.close(); } catch { /* best-effort */ }
@@ -1225,6 +1364,7 @@ export function closeAllDatabases(): void {
     try { db.close(); } catch { /* best-effort */ }
     _dbCache.delete(key);
   }
+  _dbLeases.clear();
 }
 
 /**

package/src/store/sqlite-fts.ts

@@ -1,4 +1,5 @@
 import type { Observation } from '../types.js';
+import { isTransientSqliteError } from './sqlite-reliability.js';
 
 /** Rows returned by the derived FTS5 index before normal Observation parsing. */
 export interface SqliteLexicalHit {
@@ -56,31 +57,52 @@ export function buildFtsQuery(query: string): string | null {
   return unique.map((token) => `"${normalizeFtsToken(token)}"`).join(' OR ');
 }
 
+/**
+ * initializeObservationLexicalIndex runs exactly once per db handle (called
+ * from getDatabase's synchronous setup), so a transient cross-process BUSY
+ * here would otherwise be cached as a permanent "unavailable" for that
+ * handle's entire lifetime, with no other call site ever re-checking it.
+ */
+const FTS_INIT_MAX_ATTEMPTS = 3;
+
 /**
  * Create and reconcile the external-content FTS5 index for one SQLite handle.
- * FTS5 is an optional SQLite capability, so an unavailable extension is a
- * normal fallback rather than a reason to make the durable store unusable.
+ * FTS5 is an optional SQLite capability, so a genuinely unavailable extension
+ * is a normal fallback rather than a reason to make the durable store
+ * unusable. Cross-process lock contention (SQLITE_BUSY) is not that case —
+ * it is retried a few times, mirroring the retry already applied to the
+ * write paths in sqlite-store.ts / session-store.ts / mini-skill-store.ts,
+ * since the caller here is synchronous and cannot await retrySqliteBusy.
  */
 export function initializeObservationLexicalIndex(db: any): boolean {
   const known = ftsAvailability.get(db);
   if (known !== undefined) return known;
 
-  try {
-    db.exec(CREATE_OBSERVATION_FTS);
-    const observationCount = Number(db.prepare('SELECT COUNT(*) AS count FROM observations').get()?.count ?? 0);
-    const indexedCount = Number(db.prepare(`SELECT COUNT(*) AS count FROM ${FTS_TABLE}`).get()?.count ?? 0);
-    if (observationCount !== indexedCount) {
-      db.exec(`INSERT INTO ${FTS_TABLE}(${FTS_TABLE}) VALUES ('rebuild')`);
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= FTS_INIT_MAX_ATTEMPTS; attempt++) {
+    try {
+      db.exec(CREATE_OBSERVATION_FTS);
+      const observationCount = Number(db.prepare('SELECT COUNT(*) AS count FROM observations').get()?.count ?? 0);
+      const indexedCount = Number(db.prepare(`SELECT COUNT(*) AS count FROM ${FTS_TABLE}`).get()?.count ?? 0);
+      if (observationCount !== indexedCount) {
+        db.exec(`INSERT INTO ${FTS_TABLE}(${FTS_TABLE}) VALUES ('rebuild')`);
+      }
+      ftsAvailability.set(db, true);
+      return true;
+    } catch (error) {
+      lastError = error;
+      if (!isTransientSqliteError(error) || attempt === FTS_INIT_MAX_ATTEMPTS) break;
+      // better-sqlite3 is synchronous, so there is no await-able delay here;
+      // re-entering db.exec/prepare re-enters SQLite's own busy_timeout wait
+      // (already configured in sqlite-db.ts), which is the retry itself.
     }
-    ftsAvailability.set(db, true);
-    return true;
-  } catch (error) {
-    ftsAvailability.set(db, false);
-    console.warn(
-      `[memorix] SQLite FTS5 unavailable; using the existing search fallback: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return false;
   }
+
+  ftsAvailability.set(db, false);
+  console.warn(
+    `[memorix] SQLite FTS5 unavailable; using the existing search fallback: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+  );
+  return false;
 }
 
 export function isObservationLexicalIndexEnabled(db: any): boolean {