memorix 1.2.8 → 1.2.10

package/src/memory/observations.ts

@@ -49,6 +49,17 @@ let observations: Observation[] = [];
 let nextId = 1;
 let projectDir: string | null = null;
 let searchIndexPrepared = false;
+export type ObservationEmbeddingWriteMode = 'background' | 'deferred';
+
+export interface ObservationRuntimeOptions {
+  /** Defer remote/local embedding to a detached worker for short-lived CLI writes. */
+  embeddingWriteMode?: ObservationEmbeddingWriteMode;
+  /** Git root used by the detached vector worker. */
+  projectRoot?: string;
+}
+
+let embeddingWriteMode: ObservationEmbeddingWriteMode = 'background';
+let embeddingWorkerProjectRoot: string | undefined;
 
 // ── Vector-missing tracking ──────────────────────────────────────
 // Tracks observation IDs whose async embedding write failed or was skipped.
@@ -106,7 +117,10 @@ function vectorBackfillError(error: unknown): string {
   return sanitizeCredentials(normalizeEmbeddingFailure(error).message).slice(0, 1_000);
 }
 
-function queueVectorBackfill(projectId: string): void {
+function queueVectorBackfill(
+  projectId: string,
+  options: { detachedWorker?: boolean; projectRoot?: string } = {},
+): void {
   const dataDir = projectDir;
   if (!dataDir) return;
   void import('../runtime/maintenance-jobs.js')
@@ -117,6 +131,19 @@ function queueVectorBackfill(projectId: string): void {
         dedupeKey: 'vector-backfill',
         payload: { limit: 12 },
       });
+      if (options.detachedWorker && options.projectRoot) {
+        void import('../runtime/vector-backfill-runner.js')
+          .then(({ launchDetachedVectorBackfill }) => {
+            launchDetachedVectorBackfill({
+              projectId,
+              projectRoot: options.projectRoot!,
+              dataDir,
+            });
+          })
+          .catch(() => {
+            // The durable queue remains available to a later MCP session.
+          });
+      }
     })
     .catch(() => {
       // Memory writes remain durable even when the optional maintenance queue is unavailable.
@@ -199,7 +226,12 @@ async function upgradeVectorSchemaAfterFirstEmbedding(embedding: number[]): Prom
  * Initialize the observations manager with a project directory.
  * Auto-initializes the ObservationStore if not already set.
  */
-export async function initObservations(dir: string): Promise<void> {
+export async function initObservations(
+  dir: string,
+  options: ObservationRuntimeOptions = {},
+): Promise<void> {
+  embeddingWriteMode = options.embeddingWriteMode ?? 'background';
+  embeddingWorkerProjectRoot = options.projectRoot;
   if (projectDir === dir) return;
   await initObservationStore(dir);
   const store = getObservationStore();
@@ -210,6 +242,70 @@ export async function initObservations(dir: string): Promise<void> {
   vectorSchemaUpgradePromise = null;
 }
 
+function scheduleObservationEmbedding(input: {
+  observationId: number;
+  projectId: string;
+  searchableText: string;
+  doc: MemorixDocument;
+}): void {
+  const { observationId, projectId, searchableText, doc } = input;
+  vectorMissingIds.add(observationId);
+
+  // 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,
+    });
+    return;
+  }
+
+  void generateEmbedding(searchableText).then(async (embedding) => {
+    if (embedding) {
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        await upgradeVectorSchemaAfterFirstEmbedding(embedding);
+      }
+      if (!isVectorCompatibleWithCurrentIndex(embedding)) {
+        const vectorDimensions = getVectorDimensions();
+        console.error(
+          `[memorix] Embedding dimension mismatch for obs-${observationId}: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d (kept in backfill queue)`,
+        );
+        queueVectorBackfill(projectId);
+        return;
+      }
+      try {
+        await removeObservation(makeOramaObservationId(projectId, observationId));
+        await insertObservation(Object.assign({}, doc, { embedding }));
+        vectorMissingIds.delete(observationId);
+      } catch {
+        console.error(`[memorix] Embedding index update failed for obs-${observationId} (kept in backfill queue)`);
+        queueVectorBackfill(projectId);
+      }
+    } else if (isEmbeddingExplicitlyDisabled()) {
+      vectorMissingIds.delete(observationId);
+    } else {
+      queueVectorBackfill(projectId);
+      logEmbeddingFailureOnce(
+        'provider-unavailable',
+        `[memorix] Embedding provider unavailable (using BM25 until embedding recovers; queued obs-${observationId} for retry)`,
+      );
+    }
+  }).catch((err) => {
+    queueVectorBackfill(projectId);
+    const failure = normalizeEmbeddingFailure(err);
+    logEmbeddingFailureOnce(
+      failure.key,
+      `[memorix] Async embedding failed (using BM25 until embedding recovers; queued obs-${observationId} for retry): ${failure.message}`,
+    );
+  });
+}
+
 /**
  * Check cross-process freshness and reload if another process has written.
  *
@@ -507,49 +603,11 @@ export async function storeObservation(input: {
     queueClaimDerivation(observation);
   }
 
-  // Generate embedding async (fire-and-forget) — never blocks MCP response
-  // Track in vectorMissingIds until embedding is successfully written.
-  const obsId = observation.id;
-  vectorMissingIds.add(obsId);
-  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(
-          `[memorix] Embedding dimension mismatch for obs-${obsId}: provider returned ${embedding.length}d, index expects ${vectorDimensions ?? 'unknown'}d (kept in backfill queue)`,
-        );
-        queueVectorBackfill(input.projectId);
-        return;
-      }
-      try {
-        const { removeObservation: removeObs } = await import('../store/orama-store.js');
-        await removeObs(makeOramaObservationId(input.projectId, obsId));
-        await insertObservation(Object.assign({}, doc, { embedding }));
-        vectorMissingIds.delete(obsId);
-      } catch {
-        console.error(`[memorix] Embedding index update failed for obs-${obsId} (kept in backfill queue)`);
-        queueVectorBackfill(input.projectId);
-      }
-    } else if (isEmbeddingExplicitlyDisabled()) {
-      vectorMissingIds.delete(obsId);
-    } else {
-      queueVectorBackfill(input.projectId);
-      logEmbeddingFailureOnce(
-        'provider-unavailable',
-        `[memorix] Embedding provider unavailable (using BM25 until embedding recovers; queued obs-${obsId} for retry)`,
-      );
-    }
-  }).catch((err) => {
-    queueVectorBackfill(input.projectId);
-    const failure = normalizeEmbeddingFailure(err);
-    logEmbeddingFailureOnce(
-      failure.key,
-      `[memorix] Async embedding failed (using BM25 until embedding recovers; queued obs-${obsId} for retry): ${failure.message}`,
-    );
+  scheduleObservationEmbedding({
+    observationId: observation.id,
+    projectId: input.projectId,
+    searchableText: [input.title, input.narrative, ...(input.facts ?? [])].join(' '),
+    doc,
   });
 
   return { observation, upserted: false };
@@ -678,40 +736,11 @@ async function upsertObservation(
     queueClaimDerivation(existing);
   }
 
-  // Generate embedding async (fire-and-forget) — never blocks MCP response
-  const searchableText = [input.title, input.narrative, ...(input.facts ?? [])].join(' ');
-  const obsId = existing.id;
-  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));
-        await insertObservation(Object.assign({}, doc, { embedding }));
-        vectorMissingIds.delete(obsId);
-      } catch {
-        // Embedding index update failed — observation still persisted without vector
-        queueVectorBackfill(existing.projectId);
-      }
-    } else if (isEmbeddingExplicitlyDisabled()) {
-      vectorMissingIds.delete(obsId);
-    } else {
-      queueVectorBackfill(existing.projectId);
-    }
-  }).catch((err) => {
-    queueVectorBackfill(existing.projectId);
-    const failure = normalizeEmbeddingFailure(err);
-    logEmbeddingFailureOnce(
-      failure.key,
-      `[memorix] Async embedding failed (using BM25 until embedding recovers; queued obs-${obsId} for retry): ${failure.message}`,
-    );
+  scheduleObservationEmbedding({
+    observationId: existing.id,
+    projectId: existing.projectId,
+    searchableText: [input.title, input.narrative, ...(input.facts ?? [])].join(' '),
+    doc,
   });
 
   return existing;

package/src/memory/retention.ts

@@ -319,6 +319,40 @@ export interface RetentionExplanation {
   summary: string;
 }
 
+/** Access metadata maintained outside the persisted observation record. */
+export type ObservationAccessMap = ReadonlyMap<number, {
+  accessCount: number;
+  lastAccessedAt: string;
+}>;
+
+/**
+ * One canonical retention result for a persisted observation.
+ *
+ * Consumers should use this projection instead of recreating a local decay
+ * formula. That keeps the UI, HTTP control plane, and archive worker aligned
+ * on the same retention state.
+ */
+export interface RetentionProjection extends RetentionExplanation {
+  relevance: RelevanceScore;
+  /** A backwards-compatible 0-10 display value derived from relevance. */
+  displayScore: number;
+  ageHours: number;
+  accessCount: number;
+  lastAccessedAt: string;
+}
+
+export interface ObservationRetentionProjectionOptions {
+  referenceTime?: Date;
+  accessMap?: ObservationAccessMap;
+}
+
+export interface RetentionProjectionSummary {
+  active: number;
+  stale: number;
+  archiveCandidates: number;
+  immune: number;
+}
+
 /**
  * Produce a structured explanation of why an observation has its current
  * retention posture.  Designed for operator-facing reporting.
@@ -371,27 +405,16 @@ export function explainRetention(
   };
 }
 
-// ── Auto-Archive ────────────────────────────────────────────────────
-
-export interface ArchiveExpiredBatchOptions {
-  projectId: string;
-  afterId?: number;
-  limit?: number;
-  referenceTime?: Date;
-  accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>;
-  /** Omit only for trusted background maintenance. */
-  reader?: ObservationReader;
-}
-
-export interface ArchiveExpiredBatchResult {
-  archived: number;
-  scanned: number;
-  nextCursor?: number;
-}
-
-function toRetentionDocument(
+/**
+ * Convert a stored observation into the search/retention document shape.
+ *
+ * Observation fields such as concepts are arrays, while the retrieval schema
+ * intentionally stores them as strings. Centralising that conversion prevents
+ * callers from accidentally feeding raw observations into retention helpers.
+ */
+export function toRetentionDocument(
   obs: Observation,
-  accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>,
+  accessMap?: ObservationAccessMap,
 ): MemorixDocument {
   const access = accessMap?.get(obs.id);
   return {
@@ -418,6 +441,62 @@ function toRetentionDocument(
   };
 }
 
+/** Build the canonical retention result used by every Observation consumer. */
+export function projectObservationRetention(
+  observation: Observation,
+  options: ObservationRetentionProjectionOptions = {},
+): RetentionProjection {
+  const document = toRetentionDocument(observation, options.accessMap);
+  const relevance = calculateRelevance(document, options.referenceTime);
+  const explanation = explainRetention(document, options.referenceTime);
+
+  return {
+    ...explanation,
+    relevance,
+    displayScore: Math.round(Math.min(10, relevance.totalScore * 10) * 100) / 100,
+    ageHours: Math.round(relevance.ageDays * 24 * 10) / 10,
+    accessCount: document.accessCount,
+    lastAccessedAt: document.lastAccessedAt,
+  };
+}
+
+/** Summarise canonical projections without reimplementing retention thresholds. */
+export function summarizeRetentionProjections(
+  projections: readonly Pick<RetentionProjection, 'zone' | 'immune'>[],
+): RetentionProjectionSummary {
+  let active = 0;
+  let stale = 0;
+  let archiveCandidates = 0;
+  let immune = 0;
+
+  for (const projection of projections) {
+    if (projection.zone === 'active') active++;
+    else if (projection.zone === 'stale') stale++;
+    else archiveCandidates++;
+    if (projection.immune) immune++;
+  }
+
+  return { active, stale, archiveCandidates, immune };
+}
+
+// ── Auto-Archive ────────────────────────────────────────────────────
+
+export interface ArchiveExpiredBatchOptions {
+  projectId: string;
+  afterId?: number;
+  limit?: number;
+  referenceTime?: Date;
+  accessMap?: ObservationAccessMap;
+  /** Omit only for trusted background maintenance. */
+  reader?: ObservationReader;
+}
+
+export interface ArchiveExpiredBatchResult {
+  archived: number;
+  scanned: number;
+  nextCursor?: number;
+}
+
 /**
  * Archive one bounded page of a project's active memories. The caller owns the
  * cursor, which makes the operation safe to run from a durable maintenance job.
@@ -438,10 +517,10 @@ export async function archiveExpiredBatch(
   const scanned = hasMore ? page.slice(0, limit) : page;
   const candidateIds = scanned
     .filter((observation) => !options.reader || canManageObservation(observation, options.reader))
-    .filter((observation) => getRetentionZone(
-      toRetentionDocument(observation, options.accessMap),
-      options.referenceTime,
-    ) === 'archive-candidate')
+    .filter((observation) => projectObservationRetention(observation, {
+      accessMap: options.accessMap,
+      referenceTime: options.referenceTime,
+    }).zone === 'archive-candidate')
     .map((observation) => observation.id);
 
   const archived = candidateIds.length === 0
@@ -474,7 +553,7 @@ export async function archiveExpiredBatch(
 export async function archiveExpired(
   projectDir: string,
   referenceTime?: Date,
-  accessMap?: Map<number, { accessCount: number; lastAccessedAt: string }>,
+  accessMap?: ObservationAccessMap,
   projectId?: string,
   reader?: ObservationReader,
 ): Promise<{ archived: number; remaining: number }> {
@@ -512,9 +591,8 @@ export async function archiveExpired(
     const archivedIds: number[] = [];
 
     for (const obs of activeObs) {
-      const doc = toRetentionDocument(obs, accessMap);
-      const zone = getRetentionZone(doc, referenceTime);
-      if (zone === 'archive-candidate') {
+      const retention = projectObservationRetention(obs, { accessMap, referenceTime });
+      if (retention.zone === 'archive-candidate') {
         archivedIds.push(obs.id);
       }
     }

package/src/memory/session.ts

@@ -21,7 +21,18 @@ import { KnowledgeGraphManager } from './graph.js';
 import { redactCredentials, sanitizeCredentials } from './secret-filter.js';
 import { canReadObservation } from './visibility.js';
 
-const PRIORITY_TYPES = new Set(['gotcha', 'decision', 'problem-solution', 'trade-off', 'discovery']);
+// Types eligible for L2 "Key Project Memories" injection. Session requests carry
+// the original goal and change records carry the latest outcome, so both matter
+// when an agent resumes work after a handoff.
+const PRIORITY_TYPES = new Set([
+  'gotcha',
+  'decision',
+  'problem-solution',
+  'trade-off',
+  'discovery',
+  'session-request',
+  'what-changed',
+]);
 const RESUME_TYPES = new Set([
   'gotcha',
   'decision',
@@ -31,7 +42,6 @@ const RESUME_TYPES = new Set([
   'how-it-works',
   'what-changed',
   'reasoning',
-  'session-request',
 ]);
 const TYPE_EMOJI: Record<string, string> = {
   'gotcha': '[DISCOVERY]',
@@ -50,19 +60,24 @@ const TYPE_WEIGHTS: Record<string, number> = {
   'decision': 5.5,
   'problem-solution': 5.25,
   'trade-off': 4.75,
+  'session-request': 4.5,
   'discovery': 4.25,
+  'what-changed': 4,
 };
+// Markers that identify a memory as a demo/scratch artifact rather than real
+// working context. These are TITLE conventions — see isNoiseObservation.
+//
+// Deliberately excluded: 验证 / 兼容 / compat / 交接 / handoff. Those are ordinary
+// engineering vocabulary, not noise signals. Matching them silently dropped real
+// memories: any Chinese note about verification or compatibility, and any handoff
+// note that merely named a handoff tool, disappeared from session context with no
+// diagnostic. A noise filter must not veto the words its users normally write.
 const NOISE_PATTERNS = [
   /\[测试\]/i,
   /\[test\]/i,
-  /验证/i,
-  /兼容/i,
-  /\bcompat(?:ibility)?\b/i,
   /\bdemo\b/i,
   /展示/i,
   /全能力/i,
-  /handoff/i,
-  /交接/i,
   /for_memmcp_test/i,
   /\bbenchmark\b/i,
   /\bsandbox\b/i,
@@ -180,8 +195,13 @@ function isCommandTrace(obs: Observation): boolean {
 }
 
 function isNoiseObservation(obs: Observation): boolean {
-  const text = stringifyObservation(obs, false);
-  return NOISE_PATTERNS.some((pattern) => pattern.test(text)) || isCommandTrace(obs);
+  // Match the title only. Demo/scratch markers are a titling convention, so scanning
+  // the narrative/facts/concepts produced false positives on real memories that merely
+  // *mentioned* one of these words in prose — and because this filter runs before the
+  // PRIORITY_TYPES check and drops the observation outright (not a score penalty), a
+  // single unlucky word in a long narrative made the whole memory unreachable.
+  const title = obs.title ?? '';
+  return NOISE_PATTERNS.some((pattern) => pattern.test(title)) || isCommandTrace(obs);
 }
 
 function isSystemSelfObservation(obs: Observation): boolean {
@@ -321,6 +341,42 @@ export async function getSessionResumeBrief(
   };
 }
 
+const AUTO_RESUME_SUMMARY_LIMIT = 480;
+const AUTO_RESUME_TITLE_LIMIT = 180;
+
+function compactResumeText(text: string, limit: number): string {
+  const normalized = text.replace(/\s+/g, ' ').trim();
+  return normalized.length <= limit ? normalized : `${normalized.slice(0, Math.max(0, limit - 3)).trimEnd()}...`;
+}
+
+/**
+ * Render the bounded automatic delivery form of a resume brief.
+ *
+ * Full session context remains available through getSessionContext() and
+ * individual memory details remain on demand. Automatic session start gets an
+ * index, not a transcript, so it cannot crowd out the new task's context.
+ */
+export function renderSessionResumeCard(brief: SessionResumeBrief): string {
+  if (!brief.previousSession && brief.memories.length === 0) return '';
+
+  const lines = ['## Memorix Resume'];
+  if (brief.previousSession) {
+    const agent = brief.previousSession.agent ? ` (${brief.previousSession.agent})` : '';
+    lines.push(`Previous session: ${brief.previousSession.id}${agent}`);
+    lines.push(compactResumeText(brief.previousSession.summary, AUTO_RESUME_SUMMARY_LIMIT));
+  }
+
+  if (brief.memories.length > 0) {
+    lines.push('', 'Relevant memory references:');
+    for (const memory of brief.memories) {
+      lines.push(`- #${memory.id} [${memory.type}] ${compactResumeText(memory.title, AUTO_RESUME_TITLE_LIMIT)}`);
+    }
+    lines.push('Read a listed memory only when its title is relevant to the current task.');
+  }
+
+  return lines.join('\n');
+}
+
 export function scoreObservationForSessionContext(obs: Observation, projectTokens: string[], now = Date.now()): number {
   let score = TYPE_WEIGHTS[obs.type] ?? 1;
   const text = stringifyObservation(obs);
@@ -384,7 +440,7 @@ export function scoreObservationForSessionContext(obs: Observation, projectToken
  * so the agent can resume work without re-explaining everything.
  */
 export async function startSession(
-  projectDir: string,
+  _projectDir: string,
   projectId: string,
   opts?: { sessionId?: string; agent?: string; reader?: ObservationReader },
 ): Promise<{ session: Session; previousContext: string }> {
@@ -399,8 +455,11 @@ export async function startSession(
     agent: opts?.agent,
   };
 
-  // Load previous context before creating new session
-  const previousContext = await getSessionContext(projectDir, projectId, 3, opts?.reader);
+  // Automatic delivery stays intentionally small. The explicit context tool can
+  // still provide the expanded packet when an agent chooses to inspect it.
+  const previousContext = renderSessionResumeCard(
+    await getSessionResumeBrief(projectId, undefined, opts?.reader),
+  );
 
   // Atomic rollover: complete all active sessions for this project's aliases
   // and insert the new session in a single SQLite transaction.

package/src/runtime/vector-backfill-runner.ts

@@ -0,0 +1,144 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { loadDotenv } from '../config/dotenv-loader.js';
+import { initProjectRoot } from '../config/yaml-loader.js';
+import { prepareSearchIndex, initObservations } from '../memory/observations.js';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { initObservationStore } from '../store/obs-store.js';
+import { getDeferredCachedVectorHydration } from '../store/orama-store.js';
+import { closeAllDatabases } from '../store/sqlite-db.js';
+import { MaintenanceJobStore, MaintenanceJobWorker } from './maintenance-jobs.js';
+import { createProjectMaintenanceHandler } from './project-maintenance.js';
+
+export interface VectorBackfillRequest {
+  projectId: string;
+  projectRoot: string;
+  dataDir: string;
+}
+
+export interface VectorBackfillLauncherOptions {
+  runnerPath?: string;
+  exists?: (path: string) => boolean;
+  spawn?: typeof spawn;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/** Resolve the standalone worker next to either the library or CLI bundle. */
+export function resolveVectorBackfillRunnerPath(moduleUrl = import.meta.url): string {
+  const moduleDir = path.dirname(fileURLToPath(moduleUrl));
+  const distDir = path.basename(moduleDir) === 'cli'
+    ? path.dirname(moduleDir)
+    : path.basename(moduleDir) === 'runtime' && path.basename(path.dirname(moduleDir)) === 'src'
+      ? path.join(path.dirname(path.dirname(moduleDir)), 'dist')
+      : moduleDir;
+  return path.join(distDir, 'vector-backfill-runner.js');
+}
+
+/** Parse the internal request passed from a short-lived CLI process. */
+export function parseVectorBackfillRequest(raw: string): VectorBackfillRequest {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error('Vector backfill runner received invalid JSON input');
+  }
+
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    !isNonEmptyString((value as VectorBackfillRequest).projectId) ||
+    !isNonEmptyString((value as VectorBackfillRequest).projectRoot) ||
+    !isNonEmptyString((value as VectorBackfillRequest).dataDir) ||
+    !path.isAbsolute((value as VectorBackfillRequest).projectRoot) ||
+    !path.isAbsolute((value as VectorBackfillRequest).dataDir)
+  ) {
+    throw new Error('Vector backfill runner received an invalid request');
+  }
+
+  return {
+    projectId: (value as VectorBackfillRequest).projectId,
+    projectRoot: (value as VectorBackfillRequest).projectRoot,
+    dataDir: (value as VectorBackfillRequest).dataDir,
+  };
+}
+
+/**
+ * Start a detached one-shot worker. The caller has already persisted the
+ * observation and durable vector job, so failure to start is recoverable by a
+ * later MCP or control-plane session.
+ */
+export function launchDetachedVectorBackfill(
+  request: VectorBackfillRequest,
+  options: VectorBackfillLauncherOptions = {},
+): boolean {
+  const runnerPath = options.runnerPath ?? resolveVectorBackfillRunnerPath();
+  const exists = options.exists ?? existsSync;
+  if (!exists(runnerPath)) return false;
+
+  try {
+    const child = (options.spawn ?? spawn)(process.execPath, [runnerPath], {
+      cwd: request.projectRoot,
+      detached: true,
+      stdio: 'ignore',
+      // The request contains only local project metadata, never credentials.
+      // Environment transport avoids a live stdin pipe keeping the CLI alive.
+      env: { ...process.env, MEMORIX_VECTOR_BACKFILL_REQUEST: JSON.stringify(request) },
+      windowsHide: true,
+    }) as ChildProcess;
+    child.once?.('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run one durable vector-backfill job without sharing the CLI event loop. */
+export async function executeVectorBackfill(request: VectorBackfillRequest) {
+  initProjectRoot(request.projectRoot);
+  loadDotenv(request.projectRoot);
+  await initObservationStore(request.dataDir);
+  await initObservations(request.dataDir);
+  await prepareSearchIndex();
+  await getDeferredCachedVectorHydration()?.catch(() => {});
+
+  const worker = new MaintenanceJobWorker(
+    new MaintenanceJobStore(request.dataDir),
+    createProjectMaintenanceHandler(request.projectId, request.dataDir, request.projectRoot),
+    { projectId: request.projectId, kinds: ['vector-backfill'] },
+  );
+  return worker.runOnce();
+}
+
+async function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { raw += chunk; });
+    process.stdin.once('error', reject);
+    process.stdin.once('end', () => resolve(raw));
+  });
+}
+
+export async function main(): Promise<void> {
+  try {
+    const raw = process.env.MEMORIX_VECTOR_BACKFILL_REQUEST ?? await readStdin();
+    await executeVectorBackfill(parseVectorBackfillRequest(raw));
+  } catch (error) {
+    const detail = sanitizeCredentials(error instanceof Error ? error.message : String(error));
+    process.stderr.write(`[memorix] vector backfill worker failed: ${detail}\n`);
+    process.exitCode = 1;
+  } finally {
+    closeAllDatabases();
+  }
+}
+
+if (process.argv[1] && process.argv[1].endsWith('vector-backfill-runner.js')) {
+  void main();
+}