memorix 1.1.11 → 1.1.13

package/src/embedding/api-provider.ts

@@ -14,6 +14,7 @@ import type { EmbeddingProvider } 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');
 const DIMS_CACHE_FILE = join(CACHE_DIR, '.embedding-dims-cache.json');
+const CACHE_META_FILE = join(CACHE_DIR, '.embedding-api-cache-meta.json');
 
 const cache = new Map<string, number[]>();
 const MAX_CACHE_SIZE = 10000;
@@ -82,6 +83,73 @@ function dimsCacheKey(config: Pick<APIEmbeddingConfig, 'baseUrl' | 'model' | 're
   ].join('|');
 }
 
+interface CacheMetadataEntry {
+  namespace: string;
+  dimensions: number;
+  ts: number;
+}
+
+function isValidDimension(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+
+/**
+ * The vector cache keeps a tiny, redundant namespace → dimensions map. It lets
+ * cache-first startup recover when the separate dimensions cache is missing.
+ */
+async function loadCachedVectorDimensions(
+  config: Pick<APIEmbeddingConfig, 'baseUrl' | 'model' | 'requestedDimensions'>,
+): Promise<number | null> {
+  try {
+    const raw = await readFile(CACHE_META_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    const namespace = cacheNamespace(config);
+    if (!Array.isArray(data?.entries)) return null;
+    const entry = data.entries.find((candidate: unknown) =>
+      typeof candidate === 'object' &&
+      candidate !== null &&
+      (candidate as { namespace?: unknown }).namespace === namespace &&
+      isValidDimension((candidate as { dimensions?: unknown }).dimensions),
+    ) as CacheMetadataEntry | undefined;
+    return entry?.dimensions ?? null;
+  } catch {
+    return null;
+  }
+}
+
+async function saveCachedVectorDimensions(
+  config: Pick<APIEmbeddingConfig, 'baseUrl' | 'model' | 'requestedDimensions'>,
+  dimensions: number,
+): Promise<void> {
+  if (!isValidDimension(dimensions)) return;
+  try {
+    await mkdir(CACHE_DIR, { recursive: true });
+    let entries: CacheMetadataEntry[] = [];
+    try {
+      const raw = await readFile(CACHE_META_FILE, 'utf-8');
+      const data = JSON.parse(raw);
+      if (Array.isArray(data?.entries)) {
+        entries = data.entries.filter((candidate: unknown): candidate is CacheMetadataEntry =>
+          typeof candidate === 'object' &&
+          candidate !== null &&
+          typeof (candidate as { namespace?: unknown }).namespace === 'string' &&
+          isValidDimension((candidate as { dimensions?: unknown }).dimensions) &&
+          typeof (candidate as { ts?: unknown }).ts === 'number',
+        );
+      }
+    } catch {
+      // The cache metadata is a best-effort acceleration layer.
+    }
+
+    const namespace = cacheNamespace(config);
+    entries = entries.filter((entry) => entry.namespace !== namespace);
+    entries.push({ namespace, dimensions, ts: Date.now() });
+    await writeFile(CACHE_META_FILE, JSON.stringify({ version: 1, entries }));
+  } catch {
+    // A missing or read-only cache must never block embedding requests.
+  }
+}
+
 /** Load cached probe dimensions from disk. Returns null if not cached. */
 async function loadCachedDims(config: Pick<APIEmbeddingConfig, 'baseUrl' | 'model' | 'requestedDimensions'>): Promise<number | null> {
   try {
@@ -179,6 +247,7 @@ async function saveCachedDims(config: Pick<APIEmbeddingConfig, 'baseUrl' | 'mode
 
     await writeFile(DIMS_CACHE_FILE, JSON.stringify({ entries }));
   } catch { /* best-effort */ }
+  await saveCachedVectorDimensions(config, dimensions);
 }
 
 async function saveDiskCacheNow(): Promise<void> {
@@ -231,6 +300,14 @@ interface APIEmbeddingConfig {
   requestedDimensions: number | null;
 }
 
+export interface APIEmbeddingProviderCreateOptions {
+  /**
+   * When false, only previously persisted dimension metadata may initialize
+   * the provider. This keeps startup/cache hydration off the remote API path.
+   */
+  allowNetworkProbe?: boolean;
+}
+
 function resolveEnvEmbeddingApiKey(): string | undefined {
   return process.env.MEMORIX_EMBEDDING_API_KEY;
 }
@@ -272,18 +349,27 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     this.name = `api-${config.model.replace(/\//g, '-')}`;
   }
 
-  static async create(): Promise<APIEmbeddingProvider> {
+  static async create(): Promise<APIEmbeddingProvider>;
+  static async create(options: APIEmbeddingProviderCreateOptions & { allowNetworkProbe: false }): Promise<APIEmbeddingProvider | null>;
+  static async create(options: APIEmbeddingProviderCreateOptions): Promise<APIEmbeddingProvider | null>;
+  static async create(options: APIEmbeddingProviderCreateOptions = {}): Promise<APIEmbeddingProvider | null> {
     const config = APIEmbeddingProvider.resolveConfig();
-
-    // Start loading the 45MB+ embedding cache in the background (non-blocking).
-    // It will be awaited on first embed() call if not yet ready.
-    startDiskCacheLoad();
+    const allowNetworkProbe = options.allowNetworkProbe !== false;
 
     // Try cached dimensions first to avoid a network probe on cold start
     let probeDimensions = await loadCachedDims(config);
+    let dimensionSource: 'dims-cache' | 'vector-cache' | 'probe' = 'dims-cache';
+    if (probeDimensions === null) {
+      probeDimensions = await loadCachedVectorDimensions(config);
+      if (probeDimensions !== null) dimensionSource = 'vector-cache';
+    }
     if (probeDimensions !== null) {
-      console.error(`[memorix] API embedding: ${config.model} @ ${config.baseUrl} (${probeDimensions}d) [cached dims]`);
+      console.error(`[memorix] API embedding: ${config.model} @ ${config.baseUrl} (${probeDimensions}d) [${dimensionSource}]`);
+      if (dimensionSource === 'dims-cache') {
+        void saveCachedVectorDimensions(config, probeDimensions);
+      }
     } else {
+      if (!allowNetworkProbe) return null;
       probeDimensions = await APIEmbeddingProvider.probeAPI(config);
       console.error(`[memorix] API embedding: ${config.model} @ ${config.baseUrl} (${probeDimensions}d)`);
       // Persist for next cold start
@@ -293,6 +379,11 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
       console.error(`[memorix] Dimension shortening: ${config.requestedDimensions}d requested`);
     }
 
+    // The cache can only be used after dimensions are known. In cache-only
+    // startup with no metadata, skip parsing the potentially large cache file
+    // altogether and stay lexical until a normal embedding lane is needed.
+    startDiskCacheLoad();
+
     return new APIEmbeddingProvider(config, probeDimensions);
   }
 
@@ -519,6 +610,14 @@ export class APIEmbeddingProvider implements EmbeddingProvider {
     return results;
   }
 
+  async getCachedEmbeddings(texts: string[]): Promise<(number[] | null)[]> {
+    await ensureDiskCacheLoaded();
+    return texts.map((text) => {
+      const hash = textHash(normalizeText(text), this.cacheKeyNamespace);
+      return cache.get(hash) ?? null;
+    });
+  }
+
   getStats(): { totalTokens: number; totalApiCalls: number; cacheSize: number } {
     return {
       totalTokens: this.totalTokensUsed,

package/src/embedding/provider.ts

@@ -36,6 +36,13 @@ export interface EmbeddingProvider {
   embed(text: string): Promise<number[]>;
   /** Generate embeddings for multiple texts (batch) */
   embedBatch(texts: string[]): Promise<number[][]>;
+  /** Return already-persisted embeddings without generating new vectors. */
+  getCachedEmbeddings?(texts: string[]): Promise<(number[] | null)[]>;
+}
+
+export interface GetEmbeddingProviderOptions {
+  /** Avoid remote API dimension probes while preparing a startup index. */
+  allowNetworkProbe?: boolean;
 }
 
 /** Singleton provider instance (null = not available) */
@@ -172,10 +179,10 @@ async function createTransformersProvider(): Promise<EmbeddingProvider | null> {
   }
 }
 
-async function createAPIProvider(): Promise<EmbeddingProvider | null> {
+async function createAPIProvider(options?: GetEmbeddingProviderOptions): Promise<EmbeddingProvider | null> {
   try {
     const { APIEmbeddingProvider } = await import('./api-provider.js');
-    return await APIEmbeddingProvider.create();
+    return await APIEmbeddingProvider.create(options ?? {});
   } catch (e) {
     warnOnce(`[memorix] Failed to init API embedding: ${e instanceof Error ? e.message : e}`);
     return null;
@@ -238,6 +245,13 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
         throw error;
       }
     },
+    ...(candidate.getCachedEmbeddings
+      ? {
+          async getCachedEmbeddings(texts: string[]): Promise<(number[] | null)[]> {
+            return candidate.getCachedEmbeddings!(texts);
+          },
+        }
+      : {}),
   };
 }
 
@@ -256,10 +270,24 @@ let lastFailureTimestamp = 0;
  *
  * Controlled by MEMORIX_EMBEDDING environment variable (default: off).
  */
-export async function getEmbeddingProvider(): Promise<EmbeddingProvider | null> {
+export async function getEmbeddingProvider(
+  options: GetEmbeddingProviderOptions = {},
+): Promise<EmbeddingProvider | null> {
   // If we already have a successfully initialized provider, return it immediately
   if (provider) return provider;
 
+  // Startup hydration is allowed to use API vectors already described by local
+  // dimension metadata, but it must never turn a missing cache into a network
+  // probe. A normal retrieval/write path will initialize the provider later.
+  if (options.allowNetworkProbe === false) {
+    const mode = getEmbeddingMode();
+    if (mode !== 'api' && !(mode === 'auto' && hasAPIEmbeddingConfig())) {
+      return null;
+    }
+    const cached = await createAPIProvider({ allowNetworkProbe: false });
+    return cached ? wrapProvider(cached) : null;
+  }
+
   // If a previous attempt failed temporarily, allow retry after cooldown
   if (lastInitWasTemporaryFailure) {
     const elapsed = Date.now() - lastFailureTimestamp;

package/src/hooks/handler.ts

@@ -14,7 +14,7 @@ import type { ObservationType } from '../types.js';
 import { normalizeHookInput } from './normalizer.js';
 import { detectBestPattern, patternToObservationType } from './pattern-detector.js';
 import { isSignificantKnowledge, isRetrievedResult, isTrivialCommand } from './significance-filter.js';
-import type { HookEvent, HookOutput, NormalizedHookInput } from './types.js';
+import type { AgentName, HookEvent, HookOutput, NormalizedHookInput } from './types.js';
 
 // ─── Constants ───
 
@@ -431,6 +431,55 @@ export async function handleHookEvent(input: NormalizedHookInput): Promise<{
   };
 }
 
+/**
+ * Convert Memorix's neutral hook response into the host-specific response
+ * schema expected by each supported agent.
+ */
+export function formatHookOutput(
+  agent: AgentName,
+  rawEventName: string,
+  output: HookOutput,
+): Record<string, unknown> {
+  if (agent === 'codex') {
+    const codexOutput: Record<string, unknown> = { continue: output.continue };
+    if (output.stopReason) codexOutput.stopReason = output.stopReason;
+
+    // Codex adds SessionStart additionalContext directly to developer context.
+    // Capture-only events deliberately stay quiet so automatic memory never
+    // becomes a stream of status messages in the agent's working context.
+    if (rawEventName === 'SessionStart' && output.systemMessage) {
+      codexOutput.hookSpecificOutput = {
+        hookEventName: 'SessionStart',
+        additionalContext: output.systemMessage,
+      };
+    }
+
+    return codexOutput;
+  }
+
+  const finalOutput: Record<string, unknown> = { ...output };
+  const hookSpecificOutputEvents = new Set([
+    'PreToolUse',
+    'UserPromptSubmit',
+    'PostToolUse',
+    'postToolUse',
+    'preToolUse',
+    'userPromptSubmitted',
+  ]);
+
+  if (rawEventName && hookSpecificOutputEvents.has(rawEventName)) {
+    const hookSpecificOutput: Record<string, unknown> = { hookEventName: rawEventName };
+    if (output.systemMessage) {
+      hookSpecificOutput.additionalContext = output.systemMessage;
+    } else if (rawEventName === 'UserPromptSubmit') {
+      hookSpecificOutput.additionalContext = '';
+    }
+    finalOutput.hookSpecificOutput = hookSpecificOutput;
+  }
+
+  return finalOutput;
+}
+
 // ─── Entry Point ───
 
 /**
@@ -602,23 +651,11 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
     ?? (payload.hook_event_name as string)
     ?? (payload.hookEventName as string)
     ?? '';
-  const finalOutput: Record<string, unknown> = { ...output };
   if (input.agent === 'antigravity') {
     process.stdout.write(JSON.stringify(toAntigravityHookOutput(rawEventName, output)));
     return;
   }
-
-  const HSO_EVENTS = new Set(['PreToolUse', 'UserPromptSubmit', 'PostToolUse', 'postToolUse', 'preToolUse', 'userPromptSubmitted']);
-  if (rawEventName && HSO_EVENTS.has(rawEventName)) {
-    const hso: Record<string, unknown> = { hookEventName: rawEventName };
-    // additionalContext is REQUIRED for UserPromptSubmit, optional for others
-    if (output.systemMessage) {
-      hso.additionalContext = output.systemMessage;
-    } else if (rawEventName === 'UserPromptSubmit') {
-      hso.additionalContext = '';
-    }
-    finalOutput.hookSpecificOutput = hso;
-  }
+  const finalOutput = formatHookOutput(input.agent, rawEventName, output);
   process.stdout.write(JSON.stringify(finalOutput));
 }
 

package/src/hooks/installers/index.ts

@@ -30,6 +30,35 @@ function resolveHookCommand(): string {
   return 'memorix';
 }
 
+function resolveWindowsMemorixShim(): string | null {
+  try {
+    const output = String(execSync('where.exe memorix.cmd', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    }));
+    return output
+      .split(/\r?\n/)
+      .map((candidate) => candidate.trim())
+      .find((candidate) => path.isAbsolute(candidate)) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * OpenCode starts plugins with its own environment on Windows. Resolve the npm
+ * shim while setup still has the user's normal PATH, then embed that stable
+ * path in the generated plugin instead of assuming OpenCode inherited it.
+ */
+export function resolveOpenCodeHookCommand(
+  platform = process.platform,
+  resolveWindowsShim: () => string | null = resolveWindowsMemorixShim,
+): string {
+  if (platform !== 'win32') return 'memorix';
+  return resolveWindowsShim() ?? 'memorix.cmd';
+}
+
 /**
  * Generate Claude Code hook config.
  * Format: .claude/settings.json
@@ -318,7 +347,7 @@ function generateKiroHookFiles(): Array<{ filename: string; content: string }> {
  * protocol used by all agents. spawnSync works in both Node.js and Bun
  * runtimes (OpenCode may fall back to Node.js on Windows).
  */
-const OPENCODE_PLUGIN_VERSION = 6;
+const OPENCODE_PLUGIN_VERSION = 7;
 
 const AGENT_SKILL_DIRS: Partial<Record<AgentName, { project: string; global?: string }>> = {
   cursor: { project: path.join('.cursor', 'skills'), global: path.join('.cursor', 'skills') },
@@ -368,6 +397,7 @@ async function installOfficialSkillsForAgent(
 }
 
 function generateOpenCodePlugin(): string {
+  const hookCommand = JSON.stringify(resolveOpenCodeHookCommand());
   return `/**
  * Memorix - Cross-Agent Memory Bridge Plugin for OpenCode
  * @generated-version ${OPENCODE_PLUGIN_VERSION}
@@ -386,6 +416,16 @@ export const MemorixPlugin = async ({ project, client, $, directory, worktree })
   const sessionId = \`opencode-\${Date.now().toString(36)}-\${Math.random().toString(36).slice(2, 8)}\`;
   let pendingAssistantResponse = null;
   let lastDeliveredAssistantKey = '';
+  let hookFailureReported = false;
+  const hookCommand = ${hookCommand};
+
+  function reportHookFailure(eventName, detail) {
+    // OpenCode renders console.error output inside the conversation. Delivery is
+    // best-effort, so keep normal sessions quiet while retaining opt-in diagnostics.
+    if (process.env.MEMORIX_HOOK_DEBUG !== '1' || hookFailureReported) return;
+    hookFailureReported = true;
+    console.error('[memorix-plugin] hook delivery failed:', eventName, detail);
+  }
 
   /**
    * Send event JSON to \`memorix hook\` via child_process.spawnSync.
@@ -401,8 +441,7 @@ export const MemorixPlugin = async ({ project, client, $, directory, worktree })
     const data = JSON.stringify(payload);
     const eventName = payload.hook_event_name || 'unknown';
     try {
-      const cmd = process.platform === 'win32' ? 'memorix.cmd' : 'memorix';
-      const result = spawnSync(cmd, ['hook'], {
+      const result = spawnSync(hookCommand, ['hook'], {
         input: data,
         timeout: 10_000,
         encoding: 'utf-8',
@@ -410,12 +449,14 @@ export const MemorixPlugin = async ({ project, client, $, directory, worktree })
         shell: process.platform === 'win32',
       });
       if (result.status !== 0) {
-        console.error('[memorix-plugin] hook failed:', eventName,
-          'exit=', result.status,
-          'stderr=', (result.stderr || '').slice(0, 200));
+        reportHookFailure(eventName, {
+          exit: result.status,
+          stderr: (result.stderr || '').slice(0, 200),
+          error: result.error?.message,
+        });
       }
     } catch (e) {
-      console.error('[memorix-plugin] hook delivery failed:', eventName, e?.message ?? e);
+      reportHookFailure(eventName, e?.message ?? e);
     }
   }
 

package/src/hooks/normalizer.ts

@@ -201,6 +201,10 @@ function extractEventName(payload: Record<string, unknown>, agent: AgentName): s
       return (payload.hook_event_name as string) ?? inferCursorEvent(payload);
     case 'claude':
       return (payload.hook_event_name as string) ?? '';
+    case 'codex':
+      // Codex uses the same lifecycle event field names as Claude Code, but
+      // the bundled plugin supplies an explicit agent identity.
+      return (payload.hook_event_name as string) ?? '';
     case 'antigravity':
     case 'gemini-cli':
       // Gemini CLI uses hook_event_name; Antigravity hooks.json commands pass
@@ -272,6 +276,17 @@ function normalizeClaude(payload: Record<string, unknown>, event: HookEvent): Pa
     result.userPrompt = payload.prompt as string;
   }
 
+  // Codex Stop provides the final response under last_assistant_message.
+  // Accept the adjacent field name too so hosts with the same payload shape
+  // can preserve the useful end-of-turn summary.
+  const assistantMessage = firstString(
+    payload.last_assistant_message,
+    payload.assistant_message,
+  );
+  if (assistantMessage) {
+    result.aiResponse = assistantMessage;
+  }
+
   return result;
 }
 

package/src/memory/observations.ts

@@ -16,8 +16,11 @@ import {
   resetDb,
   generateEmbedding,
   batchGenerateEmbeddings,
+  getDb,
+  getDeferredCachedVectorHydration,
   getVectorDimensions,
-  hydrateIndex,
+  hydrateIndexForStartup,
+  hasObservationVector,
   isEmbeddingEnabled,
   makeOramaObservationId,
   getLastSearchMode,
@@ -40,6 +43,7 @@ let searchIndexPrepared = false;
 // Enables observability ("how many memories lack vectors?") and backfill.
 const vectorMissingIds = new Set<number>();
 let vectorBackfillRunning = false;
+let vectorSchemaUpgradePromise: Promise<boolean> | null = null;
 let lastVectorBackfill: {
   attempted: number;
   succeeded: number;
@@ -119,7 +123,30 @@ async function bindObservationCodeRefsBestEffort(observation: Observation): Prom
 function isVectorCompatibleWithCurrentIndex(embedding: number[] | null): boolean {
   if (!embedding) return false;
   const vectorDimensions = getVectorDimensions();
-  return vectorDimensions === null || embedding.length === vectorDimensions;
+  return vectorDimensions !== null &&
+    embedding.length === vectorDimensions &&
+    embedding.every(Number.isFinite);
+}
+
+/**
+ * A cache-less API startup deliberately creates a lexical index so MCP can
+ * answer immediately. Once the background lane obtains its first vector, the
+ * in-memory index must be rebuilt with a vector field in this same process.
+ */
+async function upgradeVectorSchemaAfterFirstEmbedding(embedding: number[]): Promise<boolean> {
+  if (isVectorCompatibleWithCurrentIndex(embedding)) return true;
+  if (getVectorDimensions() !== null || !embedding.every(Number.isFinite)) return false;
+
+  const targetProjectDir = projectDir;
+  if (!vectorSchemaUpgradePromise) {
+    vectorSchemaUpgradePromise = reindexObservations()
+      .then(() => projectDir === targetProjectDir && isVectorCompatibleWithCurrentIndex(embedding))
+      .catch(() => false)
+      .finally(() => {
+        vectorSchemaUpgradePromise = null;
+      });
+  }
+  return vectorSchemaUpgradePromise;
 }
 
 /**
@@ -134,6 +161,7 @@ export async function initObservations(dir: string): Promise<void> {
   nextId = await store.loadIdCounter();
   projectDir = dir;
   searchIndexPrepared = false;
+  vectorSchemaUpgradePromise = null;
 }
 
 /**
@@ -411,6 +439,9 @@ export async function storeObservation(input: {
   const searchableText = [input.title, input.narrative, ...(input.facts ?? [])].join(' ');
   generateEmbedding(searchableText).then(async (embedding) => {
     if (embedding) {
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        await upgradeVectorSchemaAfterFirstEmbedding(embedding);
+      }
       if (!isVectorCompatibleWithCurrentIndex(embedding)) {
         const vectorDimensions = getVectorDimensions();
         console.error(
@@ -561,6 +592,13 @@ async function upsertObservation(
   vectorMissingIds.add(obsId);
   generateEmbedding(searchableText).then(async (embedding) => {
     if (embedding) {
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        await upgradeVectorSchemaAfterFirstEmbedding(embedding);
+      }
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        queueVectorBackfill(existing.projectId);
+        return;
+      }
       try {
         const { removeObservation: removeObs } = await import('../store/orama-store.js');
         await removeObs(makeOramaObservationId(existing.projectId, obsId));
@@ -778,20 +816,36 @@ export async function reindexObservations(): Promise<number> {
   searchIndexPrepared = false;
   vectorMissingIds.clear();
 
-  // Batch-generate all embeddings at once (much faster than individual calls)
+  // Prefer already-persisted vectors for remote providers. This restores semantic
+  // recall after a restart without waiting on the network; cache misses remain
+  // in the existing bounded background recovery lane.
   let embeddings: (number[] | null)[] = observations.map(() => null);
   const provider = await getEmbeddingProvider();
   const canBatchEmbedAtStartup = provider !== null && !provider.name.startsWith('api-');
 
+  // This is an explicit rebuild path. Establish the current Orama schema before
+  // accepting cached vectors so a stale cache entry cannot make an observation
+  // disappear from the lexical index on insert.
+  await getDb();
+
+  const texts = observations.map(obs =>
+    [obs.title, obs.narrative, ...obs.facts].join(' '),
+  );
+
+  if (provider?.getCachedEmbeddings) {
+    try {
+      embeddings = await provider.getCachedEmbeddings(texts);
+    } catch {
+      // Cache lookup is optional; remote cache misses continue to background recovery.
+    }
+  }
+
   if (provider && !canBatchEmbedAtStartup) {
-    console.error('[memorix] Startup reindex: skipping synchronous API embeddings; background backfill will hydrate vectors');
+    console.error('[memorix] Startup reindex: restored cached API embeddings; uncached vectors stay in background recovery');
   }
 
   if (canBatchEmbedAtStartup) {
     try {
-      const texts = observations.map(obs =>
-        [obs.title, obs.narrative, ...obs.facts].join(' '),
-      );
       embeddings = await batchGenerateEmbeddings(texts);
       // Batch embedding failed — fall back to no embeddings
     } catch {
@@ -857,20 +911,38 @@ export async function reindexObservations(): Promise<number> {
 export async function prepareSearchIndex(): Promise<number> {
   if (searchIndexPrepared) return 0;
 
-  const count = await hydrateIndex(observations as unknown as any[]);
+  const count = await hydrateIndexForStartup(observations as unknown as any[]);
   if (count === 0) {
     searchIndexPrepared = true;
     return 0;
   }
 
-  vectorMissingIds.clear();
-  if (isEmbeddingEnabled()) {
-    for (const obs of observations) {
-      // Queue ALL statuses for vector backfill — status filtering happens at query time,
-      // not at index time. Omitting non-active observations here would permanently
-      // exclude resolved/archived memories from hybrid search after restart.
-      vectorMissingIds.add(obs.id);
+  const hydratedProjectDir = projectDir;
+  const queueMissingVectors = () => {
+    if (projectDir !== hydratedProjectDir) return;
+    vectorMissingIds.clear();
+    if (!isEmbeddingExplicitlyDisabled()) {
+      const projectsWithMissingVectors = new Set<string>();
+      for (const obs of observations) {
+        // Queue ALL statuses for vector backfill — status filtering happens at query time,
+        // not at index time. Omitting non-active observations here would permanently
+        // exclude resolved/archived memories from hybrid search after restart.
+        if (!hasObservationVector(obs.projectId, obs.id)) {
+          vectorMissingIds.add(obs.id);
+          projectsWithMissingVectors.add(obs.projectId);
+        }
+      }
+      for (const projectId of projectsWithMissingVectors) queueVectorBackfill(projectId);
     }
+  };
+
+  const cacheHydration = getDeferredCachedVectorHydration();
+  if (cacheHydration) {
+    // Let the disk cache finish outside the interactive startup path. Misses are
+    // queued only after it has had a chance to restore compatible vectors.
+    void cacheHydration.finally(queueMissingVectors);
+  } else {
+    queueMissingVectors();
   }
 
   searchIndexPrepared = true;
@@ -987,6 +1059,9 @@ export async function backfillVectorEmbeddings(options: {
       try {
         const embedding = await generateEmbedding(text);
         if (embedding) {
+          if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+            await upgradeVectorSchemaAfterFirstEmbedding(embedding);
+          }
           if (!isVectorCompatibleWithCurrentIndex(embedding)) {
             const vectorDimensions = getVectorDimensions();
             console.error(