memorix 1.6.0 → 1.6.2

package/src/embedding/provider.ts

@@ -173,14 +173,30 @@ let provider: EmbeddingProvider | null = null;
 let initPromise: Promise<EmbeddingProvider | null> | null = null;
 
 type EmbeddingMode = 'off' | 'fastembed' | 'transformers' | 'api' | 'auto';
+let cachedEmbeddingMode: EmbeddingMode | null = null;
+let cachedEmbeddingModeToken: string | null = null;
 type ProviderKind = 'api' | 'fastembed' | 'transformers' | 'unknown';
 
+export type EmbeddingRuntimeStatus = 'disabled' | 'uninitialized' | 'ready' | 'degraded';
+export type EmbeddingFailureKind = 'authorization' | 'billing' | 'timeout' | 'upstream';
+
+export interface EmbeddingRuntimeHealth {
+  status: EmbeddingRuntimeStatus;
+  provider?: { name: string; dimensions: number };
+  failure?: {
+    kind: EmbeddingFailureKind;
+    occurredAt: string;
+    retryAfterMs: number;
+  };
+}
+
 /**
  * Tracks whether the last init attempt resulted in a temporary failure
  * (mode != 'off' but provider returned null). When true, the next
  * getEmbeddingProvider() call will retry instead of returning cached null.
  */
 let lastInitWasTemporaryFailure = false;
+let lastEmbeddingFailure: { kind: EmbeddingFailureKind; occurredAt: number } | null = null;
 let lastEmbeddingWarning = '';
 let lastEmbeddingWarningAt = 0;
 const WARNING_COOLDOWN_MS = 30_000;
@@ -199,7 +215,13 @@ function warnOnce(message: string): void {
  * Get configured embedding mode from environment.
  * Default is 'off' to minimize resource usage.
  */
+function embeddingModeToken(): string {
+  return process.env.MEMORIX_EMBEDDING?.toLowerCase()?.trim() ?? '';
+}
+
 function getEmbeddingMode(): EmbeddingMode {
+  const token = embeddingModeToken();
+  if (cachedEmbeddingMode && cachedEmbeddingModeToken === token) return cachedEmbeddingMode;
   // Unified: env vars > config.json > 'off'
   try {
     let cfg: { getEmbeddingMode: () => EmbeddingMode };
@@ -209,11 +231,18 @@ function getEmbeddingMode(): EmbeddingMode {
       cfg = require('../config.js');
     }
     const { getEmbeddingMode: cfgMode } = cfg;
-    return cfgMode();
+    cachedEmbeddingMode = cfgMode();
+    cachedEmbeddingModeToken = token;
+    return cachedEmbeddingMode;
   } catch {
     // Fallback if config module not available
-    const env = process.env.MEMORIX_EMBEDDING?.toLowerCase()?.trim();
-    if (env === 'fastembed' || env === 'transformers' || env === 'api' || env === 'auto') return env;
+    if (token === 'fastembed' || token === 'transformers' || token === 'api' || token === 'auto') {
+      cachedEmbeddingMode = token;
+      cachedEmbeddingModeToken = token;
+      return token;
+    }
+    cachedEmbeddingMode = 'off';
+    cachedEmbeddingModeToken = token;
     return 'off';
   }
 }
@@ -271,13 +300,38 @@ function isTemporaryEmbeddingFailure(error: unknown): boolean {
   );
 }
 
+function classifyEmbeddingFailure(error: unknown): EmbeddingFailureKind {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/embedding api error \(401\)|invalid_api_key|incorrect api key|unauthorized/i.test(message)) {
+    return 'authorization';
+  }
+  if (/embedding api error \(402\)|quota exceeded|account balance/i.test(message)) {
+    return 'billing';
+  }
+  if (/embedding api timeout|abort/i.test(message)) {
+    return 'timeout';
+  }
+  return 'upstream';
+}
+
 function markTemporaryFailure(reason: unknown): void {
   provider = null;
   initPromise = null;
   lastInitWasTemporaryFailure = true;
   lastFailureTimestamp = Date.now();
+  lastEmbeddingFailure = {
+    kind: classifyEmbeddingFailure(reason),
+    occurredAt: lastFailureTimestamp,
+  };
   const message = reason instanceof Error ? reason.message : String(reason);
-  warnOnce(`[memorix] Embedding provider temporarily unavailable at runtime: ${message}`);
+  warnOnce(`[memorix] Embedding provider unavailable at runtime: ${message}`);
+}
+
+function markProviderReady(candidate: EmbeddingProvider): EmbeddingProvider {
+  provider = wrapProvider(candidate);
+  lastInitWasTemporaryFailure = false;
+  lastEmbeddingFailure = null;
+  return provider;
 }
 
 async function createFastEmbedProvider(): Promise<EmbeddingProvider | null> {
@@ -438,7 +492,7 @@ export async function getEmbeddingProvider(
     if (mode === 'fastembed') {
       const initialized = await createFastEmbedProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -447,7 +501,7 @@ export async function getEmbeddingProvider(
     if (mode === 'transformers') {
       const initialized = await createTransformersProvider();
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -456,7 +510,7 @@ export async function getEmbeddingProvider(
     if (mode === 'api') {
       const initialized = await createAPIProvider(options);
       if (!initialized) return null;
-      provider = wrapProvider(initialized);
+      provider = markProviderReady(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -465,7 +519,7 @@ export async function getEmbeddingProvider(
     if (hasAPIEmbeddingConfig()) {
       const initialized = await createAPIProvider(options);
       if (initialized) {
-        provider = wrapProvider(initialized);
+        provider = markProviderReady(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
         return provider;
       }
@@ -473,7 +527,7 @@ export async function getEmbeddingProvider(
 
     const localFallback = await createLocalFallbackProvider();
     if (localFallback) {
-      provider = wrapProvider(localFallback);
+      provider = markProviderReady(localFallback);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
       return provider;
     }
@@ -507,6 +561,36 @@ export async function isVectorSearchAvailable(): Promise<boolean> {
   return p !== null;
 }
 
+/**
+ * Process-local embedding health, intentionally read-only and network-free.
+ * It lets the control plane distinguish a configured provider from one that
+ * has degraded after a live credential, billing, timeout, or upstream error.
+ */
+export function getEmbeddingRuntimeHealth(): EmbeddingRuntimeHealth {
+  const mode = getEmbeddingMode();
+  if (mode === 'off') return { status: 'disabled' };
+
+  if (lastInitWasTemporaryFailure && lastEmbeddingFailure) {
+    return {
+      status: 'degraded',
+      failure: {
+        kind: lastEmbeddingFailure.kind,
+        occurredAt: new Date(lastEmbeddingFailure.occurredAt).toISOString(),
+        retryAfterMs: Math.max(0, RETRY_COOLDOWN_MS - (Date.now() - lastEmbeddingFailure.occurredAt)),
+      },
+    };
+  }
+
+  if (provider) {
+    return {
+      status: 'ready',
+      provider: { name: provider.name, dimensions: provider.dimensions },
+    };
+  }
+
+  return { status: 'uninitialized' };
+}
+
 /**
  * Check if embedding is explicitly disabled by configuration (mode === 'off').
  *
@@ -527,8 +611,11 @@ export function isEmbeddingExplicitlyDisabled(): boolean {
 export function resetProvider(): void {
   provider = null;
   initPromise = null;
+  cachedEmbeddingMode = null;
+  cachedEmbeddingModeToken = null;
   lastInitWasTemporaryFailure = false;
   lastFailureTimestamp = 0;
+  lastEmbeddingFailure = null;
   lastEmbeddingWarning = '';
   lastEmbeddingWarningAt = 0;
 }

package/src/hooks/handler.ts

@@ -21,6 +21,11 @@ import { normalizeHookInput } from './normalizer.js';
 import { detectBestPattern, patternToObservationType } from './pattern-detector.js';
 import { isSignificantKnowledge, isRetrievedResult, isTrivialCommand } from './significance-filter.js';
 import type { AgentName, HookEvent, HookOutput, NormalizedHookInput } from './types.js';
+import {
+  hookObservationRuntimeOptions,
+  readHookStdin,
+  resolveHookStdinTimeoutMs,
+} from './lifecycle.js';
 
 type HookInjectionMode = 'full' | 'minimal' | 'silent';
 type HookContextTarget = 'hook-session-start' | 'hook-user-prompt';
@@ -762,23 +767,9 @@ export function formatHookOutput(
  * Called by the CLI: `memorix hook`
  */
 export async function runHook(agentOverride?: string, eventOverride?: string): Promise<void> {
-  // Read stdin with a timeout — some hosts (e.g. Gemini CLI) may not close
-  // stdin promptly, causing `for await` to hang until the process is killed.
-  const rawInput = await new Promise<string>((resolve) => {
-    const chunks: Buffer[] = [];
-    const finish = () => resolve(Buffer.concat(chunks).toString('utf-8').trim());
-
-    // Hard timeout: resolve with whatever we have after 3 s
-    const timer = setTimeout(() => {
-      process.stdin.removeAllListeners('data');
-      process.stdin.removeAllListeners('end');
-      finish();
-    }, 3_000);
-
-    process.stdin.on('data', (chunk: Buffer) => { chunks.push(chunk); });
-    process.stdin.on('end', () => { clearTimeout(timer); finish(); });
-    process.stdin.on('error', () => { clearTimeout(timer); finish(); });
-  });
+  // Some hosts (e.g. Gemini CLI) may not close stdin promptly. Bound the
+  // read and release the stream so an open pipe cannot keep Node alive.
+  const rawInput = await readHookStdin(process.stdin, resolveHookStdinTimeoutMs());
 
   if (!rawInput) {
     process.stdout.write(JSON.stringify({ continue: true }));
@@ -841,7 +832,7 @@ export async function runHook(agentOverride?: string, eventOverride?: string): P
       await initObservationStore(dataDir);
       await initMSStore(dataDir);
       await initSessStore(dataDir);
-      await initObservations(dataDir);
+      await initObservations(dataDir, hookObservationRuntimeOptions(rawProject.rootPath));
       await storeObservation({ ...observation, projectId, sourceDetail: 'hook' });
       // Automatic capture is deliberately quiet. Candidate state and later
       // qualification are visible through Memorix inspection, not injected as

package/src/hooks/lifecycle.ts

@@ -0,0 +1,174 @@
+/**
+ * Process-level lifecycle for `memorix hook`.
+ *
+ * Hosts invoke this command on every agent event. It must read stdin, emit
+ * one JSON object, and exit. Leftover hook processes are a bug: they reserve
+ * heap, orphan onto PID 1, and can exhaust a laptop.
+ */
+
+import type { ObservationRuntimeOptions } from '../memory/observations.js';
+
+export const DEFAULT_HOOK_TIMEOUT_MS = 20_000;
+export const MIN_HOOK_TIMEOUT_MS = 1_000;
+export const MAX_HOOK_TIMEOUT_MS = 120_000;
+
+export const DEFAULT_HOOK_STDIN_TIMEOUT_MS = 3_000;
+export const MIN_HOOK_STDIN_TIMEOUT_MS = 100;
+export const MAX_HOOK_STDIN_TIMEOUT_MS = 30_000;
+
+type EnvMap = NodeJS.ProcessEnv | Record<string, string | undefined>;
+
+function parseBoundedMs(
+  raw: string | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const value = raw?.trim();
+  if (!value) return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(parsed)));
+}
+
+export function resolveHookTimeoutMs(env: EnvMap = process.env): number {
+  return parseBoundedMs(
+    env.MEMORIX_HOOK_TIMEOUT_MS,
+    DEFAULT_HOOK_TIMEOUT_MS,
+    MIN_HOOK_TIMEOUT_MS,
+    MAX_HOOK_TIMEOUT_MS,
+  );
+}
+
+export function resolveHookStdinTimeoutMs(env: EnvMap = process.env): number {
+  return parseBoundedMs(
+    env.MEMORIX_HOOK_STDIN_TIMEOUT_MS,
+    DEFAULT_HOOK_STDIN_TIMEOUT_MS,
+    MIN_HOOK_STDIN_TIMEOUT_MS,
+    MAX_HOOK_STDIN_TIMEOUT_MS,
+  );
+}
+
+export function hookObservationRuntimeOptions(projectRoot: string): ObservationRuntimeOptions {
+  return {
+    skipCorpusLoad: true,
+    embeddingWriteMode: 'deferred',
+    projectRoot,
+  };
+}
+
+type HookStdin = NodeJS.ReadableStream & {
+  pause?: () => void;
+  destroy?: (error?: Error) => void;
+  unref?: () => void;
+  isTTY?: boolean;
+};
+
+/**
+ * Read hook JSON from a pipe. Resolves on EOF, stream error, or idle timeout.
+ * Always releases the stream so an open stdin cannot keep Node alive.
+ */
+export async function readHookStdin(stdin: HookStdin, timeoutMs: number): Promise<string> {
+  return new Promise<string>((resolve) => {
+    const chunks: Buffer[] = [];
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      stdin.removeListener('data', onData);
+      stdin.removeListener('end', finish);
+      stdin.removeListener('error', finish);
+      stdin.pause?.();
+      if (!stdin.isTTY) {
+        stdin.destroy?.();
+      } else {
+        stdin.unref?.();
+      }
+      resolve(Buffer.concat(chunks).toString('utf-8').trim());
+    };
+
+    const onData = (chunk: Buffer | string) => {
+      chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    };
+
+    const timer = setTimeout(finish, timeoutMs);
+    stdin.on('data', onData);
+    stdin.on('end', finish);
+    stdin.on('error', finish);
+  });
+}
+
+export interface HookDeadlineIo {
+  write(chunk: string): unknown;
+}
+
+export interface HookDeadlineOptions {
+  timeoutMs: number;
+  run: () => Promise<void>;
+  stdout?: HookDeadlineIo;
+  stderr?: HookDeadlineIo;
+  exit?: (code: number) => void;
+}
+
+function writeContinue(stdout: HookDeadlineIo): void {
+  try {
+    stdout.write(JSON.stringify({ continue: true }));
+  } catch {
+    // The host already closed the pipe. Exiting is still required.
+  }
+}
+
+/**
+ * Run a hook body under a hard deadline, then force-exit.
+ * `withTimeout` cannot abort in-flight fetches; process.exit is the backstop.
+ */
+export async function runHookWithDeadline(options: HookDeadlineOptions): Promise<void> {
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const exit = options.exit ?? ((code: number) => { process.exit(code); });
+
+  await new Promise<void>((resolve) => {
+    let finished = false;
+
+    const settle = () => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      resolve();
+    };
+
+    const timer = setTimeout(() => {
+      if (finished) return;
+      try {
+        stderr.write(`[memorix] hook timed out after ${options.timeoutMs}ms\n`);
+      } catch {
+        // stderr may already be closed
+      }
+      writeContinue(stdout);
+      exit(0);
+      settle();
+    }, options.timeoutMs);
+
+    options.run().then(
+      () => {
+        if (finished) return;
+        exit(0);
+        settle();
+      },
+      (error: unknown) => {
+        if (finished) return;
+        try {
+          const message = error instanceof Error ? error.message : String(error);
+          stderr.write(`[memorix] hook failed: ${message}\n`);
+        } catch {
+          // stderr may already be closed
+        }
+        writeContinue(stdout);
+        exit(0);
+        settle();
+      },
+    );
+  });
+}

package/src/memory/observations.ts

@@ -37,7 +37,7 @@ import {
   searchObservations,
   updateObservationMetadata,
 } from '../store/orama-store.js';
-import { getObservationStore, initObservationStore } from '../store/obs-store.js';
+import { getObservationStore, initObservationStore, type ObservationStore } from '../store/obs-store.js';
 import { countTextTokens } from '../compact/token-budget.js';
 import { extractEntities, enrichConcepts } from './entity-extractor.js';
 import { getEmbeddingProvider, isEmbeddingExplicitlyDisabled, validateEmbeddingInput } from '../embedding/provider.js';
@@ -57,10 +57,32 @@ export interface ObservationRuntimeOptions {
   embeddingWriteMode?: ObservationEmbeddingWriteMode;
   /** Git root used by the detached vector worker. */
   projectRoot?: string;
+  /**
+   * Open SQLite and the ID counter without materializing the full corpus.
+   * Hook writes use disk atomic() + findByTopicKey; they must not loadAll()
+   * tens of thousands of rows on every PostToolUse.
+   */
+  skipCorpusLoad?: boolean;
 }
 
 let embeddingWriteMode: ObservationEmbeddingWriteMode = 'background';
 let embeddingWorkerProjectRoot: string | undefined;
+let corpusLoaded = false;
+let loadedObservationStore: ObservationStore | null = null;
+
+/** @internal Reset in-process observation state between tests. */
+export function resetObservationRuntime(): void {
+  observations = [];
+  nextId = 1;
+  projectDir = null;
+  searchIndexPrepared = false;
+  corpusLoaded = false;
+  loadedObservationStore = null;
+  embeddingWriteMode = 'background';
+  embeddingWorkerProjectRoot = undefined;
+  vectorMissingIds.clear();
+  vectorSchemaUpgradePromise = null;
+}
 
 // ── Vector-missing tracking ──────────────────────────────────────
 // Tracks observation IDs whose async embedding write failed or was skipped.
@@ -233,14 +255,26 @@ export async function initObservations(
 ): Promise<void> {
   embeddingWriteMode = options.embeddingWriteMode ?? 'background';
   embeddingWorkerProjectRoot = options.projectRoot;
-  if (projectDir === dir) return;
   await initObservationStore(dir);
   const store = getObservationStore();
-  observations = await store.loadAll();
+
+  if (projectDir === dir && loadedObservationStore === store) {
+    if (options.skipCorpusLoad || corpusLoaded) return;
+  }
+
   nextId = await store.loadIdCounter();
   projectDir = dir;
   searchIndexPrepared = false;
   vectorSchemaUpgradePromise = null;
+  if (options.skipCorpusLoad) {
+    observations = [];
+    corpusLoaded = false;
+    loadedObservationStore = store;
+    return;
+  }
+  observations = await store.loadAll();
+  corpusLoaded = true;
+  loadedObservationStore = store;
 }
 
 function scheduleObservationEmbedding(input: {
@@ -252,14 +286,18 @@ function scheduleObservationEmbedding(input: {
   const { observationId, projectId, searchableText, doc } = input;
   vectorMissingIds.add(observationId);
 
+  // Ordinary store must not pay embedding-provider or cache I/O when vectors
+  // are disabled. Check before generateEmbedding() so MEMORIX_EMBEDDING=off
+  // stays on the lexical write path.
+  if (isEmbeddingExplicitlyDisabled()) {
+    vectorMissingIds.delete(observationId);
+    return;
+  }
+
   // A network fetch keeps Node's event loop alive even when its Promise is not
   // awaited. One-shot CLI commands therefore persist first and let a detached
   // worker consume the same durable queue.
   if (embeddingWriteMode === 'deferred') {
-    if (isEmbeddingExplicitlyDisabled()) {
-      vectorMissingIds.delete(observationId);
-      return;
-    }
     queueVectorBackfill(projectId, {
       detachedWorker: true,
       projectRoot: embeddingWorkerProjectRoot,
@@ -322,7 +360,7 @@ function scheduleObservationEmbedding(input: {
  * For DegradedBackend this is a no-op (always returns false).
  */
 export async function ensureFreshObservations(): Promise<boolean> {
-  if (!projectDir) return false;
+  if (!projectDir || !corpusLoaded) return false;
   try {
     const store = getObservationStore();
     const wasStale = await store.ensureFresh();
@@ -424,12 +462,13 @@ export async function storeObservation(input: {
 
   // Sync the local cache before using it as the topicKey fast path. This costs a
   // generation read in the normal case and only reloads when another process wrote.
+  // Write-only / hook processes skip the corpus cache; disk findByTopicKey is authoritative.
   await ensureFreshObservations();
 
   // Topic key upsert: fast-path check in-memory (optimistic, may be stale).
   // A second authoritative check happens inside the file lock to prevent TOCTOU races
   // where two concurrent calls with the same topicKey both miss this check.
-  if (input.topicKey) {
+  if (input.topicKey && corpusLoaded) {
     const existing = observations.find(
       o => o.topicKey === input.topicKey && o.projectId === input.projectId,
     );
@@ -546,14 +585,18 @@ export async function storeObservation(input: {
       observation.writeGeneration = store.getGeneration();
 
       if (upsertedInsideLock || reloadCacheAfterCommit) {
-        observations = await store.loadAll();
-        nextId = await store.loadIdCounter();
-        if (upsertedInsideLock) {
-          observation = observations.find((candidate) => candidate.id === observation.id)
-            ?? observation;
+        if (corpusLoaded) {
+          observations = await store.loadAll();
+          nextId = await store.loadIdCounter();
+          if (upsertedInsideLock) {
+            observation = observations.find((candidate) => candidate.id === observation.id)
+              ?? observation;
+          }
+        } else {
+          nextId = await store.loadIdCounter();
         }
       } else {
-        observations.push(observation);
+        if (corpusLoaded) observations.push(observation);
         nextId = observation.id + 1;
       }
 
@@ -627,7 +670,12 @@ export async function storeObservation(input: {
       sharedWithAgentIds: JSON.stringify(input.sharedWithAgentIds ?? []),
     };
 
-    await insertObservation(doc);
+    // Hook / write-only processes persist SQLite only. The control plane
+    // picks the row up via ensureFresh. Creating Orama here would load the
+    // embedding provider and the on-disk vector cache in a 10s hook budget.
+    if (corpusLoaded) {
+      await insertObservation(doc);
+    }
   };
 
   await assignAndPersist();
@@ -1163,10 +1211,12 @@ export async function reindexObservations(): Promise<number> {
  * coupled to embedding provider throughput. Missing vectors are queued for the
  * existing background backfill cycle.
  */
-export async function prepareSearchIndex(): Promise<number> {
+export async function prepareSearchIndex(options: { skipCachedVectors?: boolean } = {}): Promise<number> {
   if (searchIndexPrepared) return 0;
 
-  const count = await hydrateIndexForStartup(observations as unknown as any[]);
+  const count = await hydrateIndexForStartup(observations as unknown as any[], {
+    skipCachedVectors: options.skipCachedVectors,
+  });
   if (count === 0) {
     searchIndexPrepared = true;
     return 0;

package/src/sdk.ts

@@ -303,6 +303,14 @@ export class MemoryClient {
     } catch {
       // best-effort cleanup
     }
+    // ObservationStore.close() only detaches from the shared handle.
+    // Release this dataDir so Windows can unlink memorix.db after close().
+    try {
+      const { closeDatabase } = await import('./store/sqlite-db.js');
+      closeDatabase(this._dataDir);
+    } catch {
+      // best-effort cleanup
+    }
   }
 }
 
@@ -346,14 +354,10 @@ export async function createMemoryClient(options: MemoryClientOptions): Promise<
     );
   }
 
-  // Resolve data directory
-  const path = await import('node:path');
-  const os = await import('node:os');
-  const dataDir = path.join(os.homedir(), '.memorix', 'data', project.id.replace(/\//g, path.sep));
-
-  // Ensure data directory exists
-  const fs = await import('node:fs');
-  fs.mkdirSync(dataDir, { recursive: true });
+  // SDK, CLI, hooks, and HTTP MCP must share the same flat data directory.
+  // Project identity is stored in each row, not encoded in the directory.
+  const { getProjectDataDir } = await import('./store/persistence.js');
+  const dataDir = await getProjectDataDir(project.id);
 
   const client = new MemoryClient(project.id, projectRoot, dataDir);
   await client._init(silent);

package/src/store/orama-store.ts

@@ -331,6 +331,8 @@ export interface HydrateIndexOptions {
   allowNetworkProbe?: boolean;
   /** Attach cached vectors after lexical hydration instead of awaiting cache I/O. */
   deferCachedVectors?: boolean;
+  /** Skip cached-vector attach entirely (one-shot CLI reads). */
+  skipCachedVectors?: boolean;
 }
 
 type HydrationCandidate = { observation: any; id: string };
@@ -378,6 +380,9 @@ async function attachCachedVectors(
     } catch {
       // Vector cache hydration is best-effort. The normal backfill lane owns misses.
     }
+    if (index % 50 === 0) {
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    }
   }
 }
 
@@ -437,11 +442,20 @@ export async function hydrateIndex(
       await insert(database, doc);
       rememberObservationDoc(doc);
       inserted++;
+      // Keep the HTTP event loop alive on large corpora so /health still answers.
+      if (inserted % 50 === 0) {
+        await new Promise<void>((resolve) => setImmediate(resolve));
+      }
+      if (inserted % 200 === 0) {
+        await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      }
     } catch { /* skip malformed entries */ }
   }
 
-  deferredCachedVectorHydration = deferCachedVectors
-    ? attachCachedVectors(database, candidates).catch(() => {})
+  deferredCachedVectorHydration = options.skipCachedVectors
+    ? null
+    : deferCachedVectors
+      ? attachCachedVectors(database, candidates).catch(() => {})
     : null;
   return inserted;
 }
@@ -450,10 +464,14 @@ export async function hydrateIndex(
  * Prepare the lexical index without probing a remote embedding API. Cached
  * vectors attach after the disk cache is ready, outside the startup path.
  */
-export async function hydrateIndexForStartup(observations: any[]): Promise<number> {
+export async function hydrateIndexForStartup(
+  observations: any[],
+  options: Pick<HydrateIndexOptions, 'skipCachedVectors'> = {},
+): Promise<number> {
   return hydrateIndex(observations, {
     allowNetworkProbe: false,
     deferCachedVectors: true,
+    skipCachedVectors: options.skipCachedVectors,
   });
 }