memorix 1.8.8 → 1.9.0

package/dist/vector-backfill-runner.d.ts

@@ -10,11 +10,14 @@ interface VectorBackfillLauncherOptions {
     runnerPath?: string;
     exists?: (path: string) => boolean;
     spawn?: typeof spawn;
+    lockPath?: string;
 }
 /** Resolve the standalone worker next to either the library or CLI bundle. */
 declare function resolveVectorBackfillRunnerPath(moduleUrl?: string): string;
 /** Parse the internal request passed from a short-lived CLI process. */
 declare function parseVectorBackfillRequest(raw: string): VectorBackfillRequest;
+declare function vectorBackfillLockPath(dataDir: string): string;
+declare function releaseVectorBackfillLock(lockPath?: string | undefined): void;
 /**
  * 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
@@ -28,4 +31,4 @@ declare function executeVectorBackfill(request: VectorBackfillRequest): Promise<
 }>;
 declare function main(): Promise<void>;
 
-export { type VectorBackfillLauncherOptions, type VectorBackfillRequest, executeVectorBackfill, launchDetachedVectorBackfill, main, parseVectorBackfillRequest, resolveVectorBackfillRunnerPath };
+export { type VectorBackfillLauncherOptions, type VectorBackfillRequest, executeVectorBackfill, launchDetachedVectorBackfill, main, parseVectorBackfillRequest, releaseVectorBackfillLock, resolveVectorBackfillRunnerPath, vectorBackfillLockPath };

package/dist/vector-backfill-runner.js

@@ -5993,6 +5993,14 @@ __export(orama_store_exports, {
   updateObservationMetadata: () => updateObservationMetadata
 });
 import { create, insert as insert2, insertMultiple, search, remove as remove2, update, count, getByID } from "@orama/orama";
+function rememberSearchMode(key, value) {
+  if (!lastSearchModeByProject.has(key) && lastSearchModeByProject.size >= MAX_SEARCH_MODE_KEYS) {
+    const oldest = lastSearchModeByProject.keys().next().value;
+    if (oldest !== void 0) lastSearchModeByProject.delete(oldest);
+  }
+  lastSearchModeByProject.delete(key);
+  lastSearchModeByProject.set(key, value);
+}
 function getLastSearchMode(projectId) {
   return lastSearchModeByProject.get(projectId ?? SEARCH_MODE_DEFAULT_KEY) ?? "fulltext";
 }
@@ -6005,9 +6013,6 @@ function makeEntryKey(projectId, observationId2) {
 function rememberObservationDoc(doc) {
   const publicDoc = { ...doc };
   delete publicDoc.embedding;
-  if (doc.projectId && typeof doc.observationId === "number") {
-    docByObservationKey.set(makeEntryKey(doc.projectId, doc.observationId), publicDoc);
-  }
   return publicDoc;
 }
 function isCommandLikeQuery(query) {
@@ -6111,7 +6116,6 @@ async function resetDb() {
   indexEmbeddingProvider = null;
   deferredCachedVectorHydration = null;
   lastSearchModeByProject.clear();
-  docByObservationKey.clear();
 }
 function isEmbeddingEnabled() {
   return embeddingEnabled;
@@ -6174,78 +6178,72 @@ function isCompatibleCachedVector(vector) {
     vector && embeddingDimensions !== null && vector.length === embeddingDimensions && vector.every(Number.isFinite)
   );
 }
-async function attachCachedVectors(database, candidates) {
-  const cachedVectors = await getCachedEmbeddings(
-    candidates.map(({ observation }) => observationEmbeddingText(observation))
-  );
-  if (db !== database) return;
-  for (let index = 0; index < candidates.length; index++) {
-    const vector = cachedVectors[index];
-    if (!isCompatibleCachedVector(vector)) continue;
-    const existing = getByID(database, candidates[index].id);
-    if (!existing || documentEmbeddingText(existing) !== observationEmbeddingText(candidates[index].observation)) continue;
-    try {
-      await update(database, candidates[index].id, { ...existing, embedding: vector });
-    } catch {
-    }
-    if (index % 50 === 0) {
-      await new Promise((resolve2) => setImmediate(resolve2));
+async function attachCachedVectors(database, observations2) {
+  const batchSize = 200;
+  for (let start = 0; start < observations2.length; start += batchSize) {
+    const batch = observations2.slice(start, start + batchSize);
+    const cachedVectors = await getCachedEmbeddings(batch.map(observationEmbeddingText));
+    if (db !== database) return;
+    for (let index = 0; index < batch.length; index++) {
+      const vector = cachedVectors[index];
+      if (!isCompatibleCachedVector(vector)) continue;
+      const id = makeOramaObservationId(batch[index].projectId, batch[index].id);
+      const existing = getByID(database, id);
+      if (!existing || documentEmbeddingText(existing) !== observationEmbeddingText(batch[index])) continue;
+      try {
+        await update(database, id, { ...existing, embedding: vector });
+      } catch {
+      }
     }
+    await new Promise((resolve2) => setImmediate(resolve2));
   }
 }
 async function hydrateIndex(observations2, options = {}) {
   const database = await getDb({ allowNetworkProbe: options.allowNetworkProbe });
-  const candidates = [];
-  for (const observation of observations2) {
-    if (!observation || !observation.id || !observation.projectId) continue;
-    const id = makeOramaObservationId(observation.projectId, observation.id);
-    if (getByID(database, id)) continue;
-    candidates.push({ observation, id });
-  }
   const deferCachedVectors = options.deferCachedVectors === true && Boolean(indexEmbeddingProvider?.getCachedEmbeddings);
-  const cachedVectors = deferCachedVectors ? candidates.map(() => null) : await getCachedEmbeddings(candidates.map(({ observation }) => observationEmbeddingText(observation)));
-  const documents = [];
-  for (let index = 0; index < candidates.length; index++) {
-    const { observation: obs, id } = candidates[index];
-    try {
-      const vector = cachedVectors[index];
-      const compatibleVector = isCompatibleCachedVector(vector) ? vector : null;
-      const doc = {
-        id,
-        observationId: obs.id,
-        entityName: obs.entityName || "",
-        type: obs.type || "discovery",
-        title: obs.title || "",
-        narrative: obs.narrative || "",
-        facts: Array.isArray(obs.facts) ? obs.facts.join(" ") : "",
-        filesModified: Array.isArray(obs.filesModified) ? obs.filesModified.join(" ") : "",
-        concepts: Array.isArray(obs.concepts) ? obs.concepts.join(" ") : "",
-        tokens: obs.tokens ?? 0,
-        createdAt: obs.createdAt || "",
-        projectId: obs.projectId,
-        accessCount: obs.accessCount ?? 0,
-        lastAccessedAt: obs.lastAccessedAt || "",
-        status: obs.status ?? "active",
-        source: obs.source || "agent",
-        sourceDetail: obs.sourceDetail ?? "",
-        valueCategory: obs.valueCategory ?? "",
-        admissionState: obs.admissionState ?? "",
-        admissionReason: obs.admissionReason ?? "",
-        visibility: obs.visibility ?? "project",
-        createdByAgentId: obs.createdByAgentId ?? "",
-        sharedWithAgentIds: JSON.stringify(obs.sharedWithAgentIds ?? []),
-        documentType: "observation",
-        knowledgeLayer: resolveKnowledgeLayer("observation", obs.sourceDetail, obs.source),
-        ...compatibleVector ? { embedding: compatibleVector } : {}
-      };
-      documents.push(doc);
-    } catch {
-    }
-  }
   let inserted = 0;
   const hydrationBatchSize = 200;
-  for (let start = 0; start < documents.length; start += hydrationBatchSize) {
-    const batch = documents.slice(start, start + hydrationBatchSize);
+  for (let start = 0; start < observations2.length; start += hydrationBatchSize) {
+    const batchObservations = observations2.slice(start, start + hydrationBatchSize).filter((observation) => observation && observation.id && observation.projectId).filter((observation) => !getByID(database, makeOramaObservationId(observation.projectId, observation.id)));
+    if (batchObservations.length === 0) continue;
+    const cachedVectors = deferCachedVectors || options.skipCachedVectors ? batchObservations.map(() => null) : await getCachedEmbeddings(batchObservations.map(observationEmbeddingText));
+    const batch = [];
+    for (let index = 0; index < batchObservations.length; index++) {
+      const obs = batchObservations[index];
+      try {
+        const compatibleVector = isCompatibleCachedVector(cachedVectors[index]) ? cachedVectors[index] : null;
+        batch.push({
+          id: makeOramaObservationId(obs.projectId, obs.id),
+          observationId: obs.id,
+          entityName: obs.entityName || "",
+          type: obs.type || "discovery",
+          title: obs.title || "",
+          narrative: obs.narrative || "",
+          facts: Array.isArray(obs.facts) ? obs.facts.join(" ") : "",
+          filesModified: Array.isArray(obs.filesModified) ? obs.filesModified.join(" ") : "",
+          concepts: Array.isArray(obs.concepts) ? obs.concepts.join(" ") : "",
+          tokens: obs.tokens ?? 0,
+          createdAt: obs.createdAt || "",
+          projectId: obs.projectId,
+          accessCount: obs.accessCount ?? 0,
+          lastAccessedAt: obs.lastAccessedAt || "",
+          status: obs.status ?? "active",
+          source: obs.source || "agent",
+          sourceDetail: obs.sourceDetail ?? "",
+          valueCategory: obs.valueCategory ?? "",
+          admissionState: obs.admissionState ?? "",
+          admissionReason: obs.admissionReason ?? "",
+          visibility: obs.visibility ?? "project",
+          createdByAgentId: obs.createdByAgentId ?? "",
+          sharedWithAgentIds: JSON.stringify(obs.sharedWithAgentIds ?? []),
+          documentType: "observation",
+          knowledgeLayer: resolveKnowledgeLayer("observation", obs.sourceDetail, obs.source),
+          ...compatibleVector ? { embedding: compatibleVector } : {}
+        });
+      } catch {
+      }
+    }
+    if (batch.length === 0) continue;
     try {
       await insertMultiple(database, batch, batch.length);
       for (const doc of batch) rememberObservationDoc(doc);
@@ -6267,7 +6265,7 @@ async function hydrateIndex(observations2, options = {}) {
     }
     await new Promise((resolve2) => setImmediate(resolve2));
   }
-  deferredCachedVectorHydration = options.skipCachedVectors ? null : deferCachedVectors ? attachCachedVectors(database, candidates).catch(() => {
+  deferredCachedVectorHydration = options.skipCachedVectors ? null : deferCachedVectors ? attachCachedVectors(database, observations2).catch(() => {
   }) : null;
   return inserted;
 }
@@ -6304,12 +6302,6 @@ async function updateObservationMetadata(projectId, observationId2, patch) {
 async function removeObservation(oramaId) {
   const database = await getDb();
   await remove2(database, oramaId);
-  for (const [key, doc] of docByObservationKey.entries()) {
-    if (doc.id === oramaId) {
-      docByObservationKey.delete(key);
-      break;
-    }
-  }
 }
 async function searchObservations(options) {
   const perf = !!process.env.MEMORIX_PERF;
@@ -6324,7 +6316,7 @@ async function searchObservations(options) {
   const modeKey = options.projectId ?? SEARCH_MODE_DEFAULT_KEY;
   const quality = options.quality ?? "balanced";
   const database = await getDb();
-  lastSearchModeByProject.set(
+  rememberSearchMode(
     modeKey,
     quality === "fast" ? "fulltext (fast profile)" : embeddingEnabled ? "hybrid" : "fulltext"
   );
@@ -6391,7 +6383,7 @@ async function searchObservations(options) {
       if (provider2) {
         const activeVectorDimensions = getVectorDimensions();
         if (activeVectorDimensions !== null && provider2.dimensions !== activeVectorDimensions) {
-          lastSearchModeByProject.set(
+          rememberSearchMode(
             modeKey,
             `fulltext (embedding dimension mismatch: provider ${provider2.dimensions}d vs index ${activeVectorDimensions}d)`
           );
@@ -6416,7 +6408,7 @@ async function searchObservations(options) {
           mark("embedding");
           const cjkRatio = (originalQuery.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g) || []).length / originalQuery.length;
           const isCJKHeavy = cjkRatio > 0.3;
-          lastSearchModeByProject.set(modeKey, "hybrid");
+          rememberSearchMode(modeKey, "hybrid");
           searchParams = {
             ...searchParams,
             mode: "hybrid",
@@ -6432,7 +6424,7 @@ async function searchObservations(options) {
         }
       }
     } catch (error) {
-      lastSearchModeByProject.set(modeKey, "fulltext (embedding unavailable)");
+      rememberSearchMode(modeKey, "fulltext (embedding unavailable)");
       console.error("[memorix] Embedding failed or timed out, falling back to fulltext search");
     }
   }
@@ -6442,7 +6434,7 @@ async function searchObservations(options) {
     results = await search(database, searchParams);
   } catch (error) {
     if (queryVector && isVectorDimensionMismatchError(error)) {
-      lastSearchModeByProject.set(modeKey, "fulltext (embedding dimension mismatch)");
+      rememberSearchMode(modeKey, "fulltext (embedding dimension mismatch)");
       console.error("[memorix] Vector search dimension mismatch detected, retrying without embeddings");
       results = await search(database, stripVectorSearchParams(searchParams));
     } else {
@@ -6464,7 +6456,7 @@ async function searchObservations(options) {
         },
         similarity: 0.25
       };
-      lastSearchModeByProject.set(modeKey, "vector-only (hybrid empty fallback)");
+      rememberSearchMode(modeKey, "vector-only (hybrid empty fallback)");
       results = await search(database, vectorOnlyParams);
     } catch {
     }
@@ -6705,7 +6697,7 @@ async function searchObservations(options) {
           const rerankedTop = neural.map((row) => candidateMap.get(row.id)).filter((entry) => entry != null);
           if (rerankedTop.length > 0) {
             intermediate = [...rerankedTop, ...intermediate.slice(RERANK_TOP_K)];
-            lastSearchModeByProject.set(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + neural rerank");
+            rememberSearchMode(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + neural rerank");
             mark("rerank(usedNeural=true)");
           }
         }
@@ -6722,7 +6714,7 @@ async function searchObservations(options) {
         );
         mark(`rerank(usedLLM=${usedLLM})`);
         if (usedLLM) {
-          lastSearchModeByProject.set(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + LLM rerank");
+          rememberSearchMode(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + LLM rerank");
           const rerankedTop = reranked.map((row) => candidateMap.get(row.id)).filter((entry) => entry != null);
           if (rerankedTop.length > 0) {
             intermediate = [...rerankedTop, ...intermediate.slice(RERANK_TOP_K)];
@@ -6795,13 +6787,6 @@ async function getObservationsByIds(ids, projectId) {
   const database = await getDb();
   const results = [];
   for (const id of ids) {
-    if (projectId) {
-      const cached = docByObservationKey.get(makeEntryKey(projectId, id));
-      if (cached) {
-        results.push(cached);
-        continue;
-      }
-    }
     const searchResult = await search(database, {
       term: "",
       includeVectors: true,
@@ -6901,7 +6886,7 @@ function formatTime(isoDate) {
     return isoDate;
   }
 }
-var db, dbInitPromise, dbGeneration, embeddingEnabled, embeddingDimensions, indexEmbeddingProvider, deferredCachedVectorHydration, docByObservationKey, NON_CJK_HYBRID_SIMILARITY, lastSearchModeByProject, SEARCH_MODE_DEFAULT_KEY, COMMAND_LOG_TITLE, COMMAND_STYLE_TITLE, COMMAND_LIKE_QUERY2, COMMAND_INTENT_QUERY, NATURAL_LANGUAGE_MARKERS;
+var db, dbInitPromise, dbGeneration, embeddingEnabled, embeddingDimensions, indexEmbeddingProvider, deferredCachedVectorHydration, NON_CJK_HYBRID_SIMILARITY, lastSearchModeByProject, SEARCH_MODE_DEFAULT_KEY, MAX_SEARCH_MODE_KEYS, COMMAND_LOG_TITLE, COMMAND_STYLE_TITLE, COMMAND_LIKE_QUERY2, COMMAND_INTENT_QUERY, NATURAL_LANGUAGE_MARKERS;
 var init_orama_store = __esm({
   "src/store/orama-store.ts"() {
     "use strict";
@@ -6922,10 +6907,10 @@ var init_orama_store = __esm({
     embeddingDimensions = null;
     indexEmbeddingProvider = null;
     deferredCachedVectorHydration = null;
-    docByObservationKey = /* @__PURE__ */ new Map();
     NON_CJK_HYBRID_SIMILARITY = 0.45;
     lastSearchModeByProject = /* @__PURE__ */ new Map();
     SEARCH_MODE_DEFAULT_KEY = "__global__";
+    MAX_SEARCH_MODE_KEYS = 4096;
     COMMAND_LOG_TITLE = /^(Ran:|Command:|Executed:)\s/i;
     COMMAND_STYLE_TITLE = /(\bfindstr\b|\bSelect-String\b|\bGet-Content\b|\bnpx\s+vitest\b|\bnpx\s+tsc\b|\b2>&1\b)/i;
     COMMAND_LIKE_QUERY2 = /\b(git|npm|npx|pnpm|yarn|node|bash|powershell|curl|memorix)\b/i;
@@ -9563,11 +9548,17 @@ function resetObservationRuntime() {
   embeddingWorkerProjectRoot = void 0;
   vectorMissingIds.clear();
   vectorSchemaUpgradePromise = null;
+  embeddingFailureLogTimestamps.clear();
 }
 function logEmbeddingFailureOnce(key, message) {
   const now3 = Date.now();
   const last = embeddingFailureLogTimestamps.get(key) ?? 0;
   if (now3 - last < EMBEDDING_FAILURE_LOG_COOLDOWN_MS) return;
+  if (!embeddingFailureLogTimestamps.has(key) && embeddingFailureLogTimestamps.size >= MAX_EMBEDDING_FAILURE_KEYS) {
+    const oldest = embeddingFailureLogTimestamps.keys().next().value;
+    if (oldest !== void 0) embeddingFailureLogTimestamps.delete(oldest);
+  }
+  embeddingFailureLogTimestamps.delete(key);
   embeddingFailureLogTimestamps.set(key, now3);
   console.error(message);
 }
@@ -9597,13 +9588,14 @@ function queueVectorBackfill(projectId, options = {}) {
   const dataDir = projectDir;
   if (!dataDir) return;
   void Promise.resolve().then(() => (init_maintenance_jobs(), maintenance_jobs_exports)).then(({ MaintenanceJobStore: MaintenanceJobStore2 }) => {
-    new MaintenanceJobStore2(dataDir).enqueue({
+    const job = new MaintenanceJobStore2(dataDir).enqueue({
       projectId,
       kind: "vector-backfill",
       dedupeKey: "vector-backfill",
       payload: { limit: 12 }
     });
-    if (options.detachedWorker && options.projectRoot) {
+    const due = !job || job.status === "pending" && job.runAfter <= Date.now();
+    if (due && options.detachedWorker && options.projectRoot) {
       void Promise.resolve().then(() => (init_vector_backfill_runner(), vector_backfill_runner_exports)).then(({ launchDetachedVectorBackfill: launchDetachedVectorBackfill2 }) => {
         launchDetachedVectorBackfill2({
           projectId,
@@ -10534,7 +10526,7 @@ async function backfillVectorEmbeddings(options = {}) {
     ...lastFailure ? { lastError: lastFailure } : {}
   };
 }
-var observations, nextId, projectDir, searchIndexPrepared, embeddingWriteMode, embeddingWorkerProjectRoot, corpusLoaded, loadedObservationStore, vectorMissingIds, vectorBackfillRunning, vectorSchemaUpgradePromise, lastVectorBackfill, embeddingFailureLogTimestamps, EMBEDDING_FAILURE_LOG_COOLDOWN_MS;
+var observations, nextId, projectDir, searchIndexPrepared, embeddingWriteMode, embeddingWorkerProjectRoot, corpusLoaded, loadedObservationStore, vectorMissingIds, vectorBackfillRunning, vectorSchemaUpgradePromise, lastVectorBackfill, embeddingFailureLogTimestamps, EMBEDDING_FAILURE_LOG_COOLDOWN_MS, MAX_EMBEDDING_FAILURE_KEYS;
 var init_observations = __esm({
   "src/memory/observations.ts"() {
     "use strict";
@@ -10562,6 +10554,57 @@ var init_observations = __esm({
     lastVectorBackfill = null;
     embeddingFailureLogTimestamps = /* @__PURE__ */ new Map();
     EMBEDDING_FAILURE_LOG_COOLDOWN_MS = 3e4;
+    MAX_EMBEDDING_FAILURE_KEYS = 1024;
+  }
+});
+
+// src/runtime/maintenance-targets.ts
+function rowToTarget(row) {
+  return {
+    projectId: row.project_id,
+    projectRoot: row.project_root,
+    dataDir: row.data_dir,
+    updatedAt: Number(row.updated_at)
+  };
+}
+var MaintenanceTargetStore;
+var init_maintenance_targets = __esm({
+  "src/runtime/maintenance-targets.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_sqlite_db();
+    MaintenanceTargetStore = class {
+      db;
+      constructor(dataDir) {
+        this.db = getDatabase(dataDir);
+      }
+      register(input) {
+        if (!input.projectId.trim()) throw new Error("Maintenance target requires a project ID");
+        if (!input.projectRoot.trim()) throw new Error("Maintenance target requires a project root");
+        if (!input.dataDir.trim()) throw new Error("Maintenance target requires a data directory");
+        const now3 = input.now ?? Date.now();
+        this.db.prepare(`
+      INSERT INTO maintenance_targets (project_id, project_root, data_dir, updated_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(project_id) DO UPDATE SET
+        project_root = excluded.project_root,
+        data_dir = excluded.data_dir,
+        updated_at = excluded.updated_at
+    `).run(input.projectId, input.projectRoot, input.dataDir, now3);
+        return this.get(input.projectId);
+      }
+      get(projectId) {
+        const row = this.db.prepare(`
+      SELECT * FROM maintenance_targets WHERE project_id = ?
+    `).get(projectId);
+        return row ? rowToTarget(row) : void 0;
+      }
+      list() {
+        return this.db.prepare(`
+      SELECT * FROM maintenance_targets ORDER BY updated_at DESC
+    `).all().map(rowToTarget);
+      }
+    };
   }
 });
 
@@ -151044,10 +151087,21 @@ __export(vector_backfill_runner_exports, {
   launchDetachedVectorBackfill: () => launchDetachedVectorBackfill,
   main: () => main,
   parseVectorBackfillRequest: () => parseVectorBackfillRequest,
-  resolveVectorBackfillRunnerPath: () => resolveVectorBackfillRunnerPath
+  releaseVectorBackfillLock: () => releaseVectorBackfillLock,
+  resolveVectorBackfillRunnerPath: () => resolveVectorBackfillRunnerPath,
+  vectorBackfillLockPath: () => vectorBackfillLockPath
 });
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync11 } from "fs";
+import {
+  closeSync,
+  existsSync as existsSync11,
+  mkdirSync as mkdirSync2,
+  openSync,
+  readFileSync as readFileSync9,
+  statSync as statSync4,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "fs";
 import path20 from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 function isNonEmptyString(value) {
@@ -151074,10 +151128,104 @@ function parseVectorBackfillRequest(raw) {
     dataDir: value.dataDir
   };
 }
+function vectorBackfillLockPath(dataDir) {
+  return path20.join(dataDir, VECTOR_BACKFILL_LOCK_FILE);
+}
+function processIsAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid == null || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function readVectorBackfillLock(lockPath) {
+  try {
+    const value = JSON.parse(readFileSync9(lockPath, "utf8"));
+    if (typeof value.parentPid !== "number" || !Number.isSafeInteger(value.parentPid) || typeof value.startedAt !== "number" || !Number.isFinite(value.startedAt) || typeof value.projectId !== "string") return void 0;
+    return {
+      parentPid: value.parentPid,
+      ...typeof value.childPid === "number" ? { childPid: value.childPid } : {},
+      startedAt: value.startedAt,
+      projectId: value.projectId
+    };
+  } catch {
+    return void 0;
+  }
+}
+function writeVectorBackfillLock(lockPath, value) {
+  writeFileSync2(lockPath, `${JSON.stringify(value)}
+`, "utf8");
+}
+function acquireVectorBackfillLock(dataDir, projectId, preferredPath) {
+  const lockPath = preferredPath ?? vectorBackfillLockPath(dataDir);
+  mkdirSync2(path20.dirname(lockPath), { recursive: true });
+  const initial = {
+    parentPid: process.pid,
+    startedAt: Date.now(),
+    projectId
+  };
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      try {
+        writeFileSync2(fd, `${JSON.stringify(initial)}
+`, "utf8");
+      } finally {
+        closeSync(fd);
+      }
+      return {
+        path: lockPath,
+        setChildPid(pid) {
+          try {
+            writeVectorBackfillLock(lockPath, { ...initial, childPid: pid });
+          } catch {
+          }
+        },
+        release() {
+          try {
+            unlinkSync(lockPath);
+          } catch {
+          }
+        }
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") return void 0;
+      const existing = readVectorBackfillLock(lockPath);
+      const ownerAlive = existing && (processIsAlive(existing.childPid) || processIsAlive(existing.parentPid));
+      if (ownerAlive) return void 0;
+      let stale = false;
+      try {
+        stale = Date.now() - statSync4(lockPath).mtimeMs >= STALE_LOCK_RECOVERY_MS;
+      } catch {
+        stale = false;
+      }
+      if (!existing && !stale) return void 0;
+      try {
+        unlinkSync(lockPath);
+      } catch {
+        return void 0;
+      }
+    }
+  }
+  return void 0;
+}
+function releaseVectorBackfillLock(lockPath = process.env.MEMORIX_VECTOR_BACKFILL_LOCK) {
+  if (!lockPath) return;
+  const lock = readVectorBackfillLock(lockPath);
+  if (lock && lock.childPid !== process.pid) return;
+  try {
+    unlinkSync(lockPath);
+  } catch {
+  }
+}
 function launchDetachedVectorBackfill(request, options = {}) {
   const runnerPath = options.runnerPath ?? resolveVectorBackfillRunnerPath();
   const exists = options.exists ?? existsSync11;
   if (!exists(runnerPath)) return false;
+  const lock = acquireVectorBackfillLock(request.dataDir, request.projectId, options.lockPath);
+  if (!lock) return false;
   try {
     const child = (options.spawn ?? spawn3)(process.execPath, [runnerPath], {
       cwd: request.projectRoot,
@@ -151087,14 +151235,23 @@ function launchDetachedVectorBackfill(request, options = {}) {
       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) },
+      env: {
+        ...process.env,
+        MEMORIX_VECTOR_BACKFILL_REQUEST: JSON.stringify(request),
+        MEMORIX_VECTOR_BACKFILL_LOCK: lock.path
+      },
       windowsHide: true
     });
+    if (child.pid) lock.setChildPid(child.pid);
+    else lock.release();
     child.once?.("error", () => {
     });
+    child.once?.("close", () => lock.release());
+    if (typeof child.once !== "function") lock.release();
     child.unref();
-    return true;
+    return Boolean(child.pid);
   } catch {
+    lock.release();
     return false;
   }
 }
@@ -151106,12 +151263,32 @@ async function executeVectorBackfill(request) {
   await prepareSearchIndex();
   await getDeferredCachedVectorHydration()?.catch(() => {
   });
+  const queue = new MaintenanceJobStore(request.dataDir);
+  const targets = new MaintenanceTargetStore(request.dataDir);
+  let preparedRoot = request.projectRoot;
+  const prepareTarget = async (target) => {
+    if (target.projectRoot === preparedRoot) return;
+    initProjectRoot(target.projectRoot);
+    loadDotenv(target.projectRoot);
+    preparedRoot = target.projectRoot;
+  };
+  const handler = async (job) => {
+    const target = targets.get(job.projectId) ?? (job.projectId === request.projectId ? { projectId: request.projectId, projectRoot: request.projectRoot, dataDir: request.dataDir, updatedAt: Date.now() } : void 0);
+    if (!target) return { action: "reschedule", delayMs: 3e4 };
+    await prepareTarget(target);
+    return createProjectMaintenanceHandler(job.projectId, target.dataDir, target.projectRoot)(job);
+  };
   const worker = new MaintenanceJobWorker(
-    new MaintenanceJobStore(request.dataDir),
-    createProjectMaintenanceHandler(request.projectId, request.dataDir, request.projectRoot),
-    { projectId: request.projectId, kinds: ["vector-backfill"] }
+    queue,
+    handler,
+    { kinds: ["vector-backfill"] }
   );
-  return worker.runOnce();
+  let result = { state: "idle" };
+  while (true) {
+    result = await worker.runOnce();
+    if (result.state === "idle") break;
+  }
+  return result;
 }
 async function readStdin() {
   return new Promise((resolve2, reject) => {
@@ -151134,9 +151311,11 @@ async function main() {
 `);
     process.exitCode = 1;
   } finally {
+    releaseVectorBackfillLock();
     closeAllDatabases();
   }
 }
+var VECTOR_BACKFILL_LOCK_FILE, STALE_LOCK_RECOVERY_MS;
 var init_vector_backfill_runner = __esm({
   "src/runtime/vector-backfill-runner.ts"() {
     init_esm_shims();
@@ -151148,7 +151327,10 @@ var init_vector_backfill_runner = __esm({
     init_orama_store();
     init_sqlite_db();
     init_maintenance_jobs();
+    init_maintenance_targets();
     init_project_maintenance();
+    VECTOR_BACKFILL_LOCK_FILE = ".memorix-vector-backfill.lock";
+    STALE_LOCK_RECOVERY_MS = 24 * 60 * 60 * 1e3;
     if (process.argv[1] && process.argv[1].endsWith("vector-backfill-runner.js")) {
       void main();
     }
@@ -151160,7 +151342,9 @@ export {
   launchDetachedVectorBackfill,
   main,
   parseVectorBackfillRequest,
-  resolveVectorBackfillRunnerPath
+  releaseVectorBackfillLock,
+  resolveVectorBackfillRunnerPath,
+  vectorBackfillLockPath
 };
 /*! Bundled license information:
 

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -23,7 +23,7 @@ It supports:
 - HTTP MCP service + dashboard (`memorix background start` or `memorix serve-http --port 3211`)
 - bundled terminal agent (`memorix` or `memcode`) that uses the same shared memory pool
 - local-first project-scoped memory
-- cross-agent recall across Cursor, Claude Code, Codex, CodeBuddy Code, Windsurf, Gemini CLI, GitHub Copilot, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, and DeepSeek Harness
+- cross-agent recall across Cursor, Claude Code, Codex, CodeBuddy Code, Windsurf, Gemini CLI, GitHub Copilot, OpenCode, Grok Build, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, DeepSeek Harness, and WorkBuddy
 
 ### Current 1.4 Baseline
 
@@ -41,7 +41,7 @@ For the 1.4 release line, the visible product shape is:
 - `memorix_project_context` / `memorix context "..."` is the normal black-box entry for non-trivial coding work: it assembles a bounded task Workset instead of injecting a generic memory dump; `memorix resume "..."` is the explicit CLI continuation projection
 - Code State keeps local snapshots and freshness links; a healthy pre-existing local CodeGraph index can add a bounded semantic outline, but Memorix never initializes or synchronizes that external index itself
 - `memorix knowledge` is an explicit review path for source-backed Markdown knowledge and canonical workflows. Do not initialize a versioned workspace or apply a proposal unless the user asks for that managed artifact
-- integration surfaces are agent-specific: Claude Code, Codex, GitHub Copilot CLI, Antigravity, and Hermes receive plugin packages; OpenClaw receives a compatible bundle; Pi and Oh-my-Pi receive package entries; Gemini CLI receives an extension package; OpenCode receives a plugin file and skill; DeepSeek Harness receives an MCP patch row, AGENTS.md guidance, and skills; Cursor and other agents receive MCP/rules/hooks where supported
+- integration surfaces are agent-specific: Claude Code, Codex, GitHub Copilot CLI, Antigravity, and Hermes receive plugin packages; OpenClaw receives a compatible bundle; Pi and Oh-my-Pi receive package entries; Gemini CLI receives an extension package; OpenCode receives a plugin file and skill; Grok Build receives native hooks and `AGENTS.md` guidance while keeping MCP host-owned; DeepSeek Harness receives an MCP patch row, AGENTS.md guidance, and skills; Cursor and other agents receive MCP/rules/hooks where supported
 - privacy-safe diagnostics and receipts avoid raw chat, memory text, query text, tool payloads, and local file paths
 
 ---
@@ -245,6 +245,7 @@ memorix setup --agent opencode --global
 memorix setup --agent openclaw --global
 memorix setup --agent hermes --global
 memorix setup --agent omp --global
+memorix setup --agent grok --global
 ```
 
 What this installs depends on the target agent:
@@ -256,6 +257,7 @@ What this installs depends on the target agent:
 - Pi: user Pi package with extension-based hook capture and a Memorix skill, registered through `pi install <path> --approve`; project-local setup uses `-l`.
 - Gemini CLI: local extension package under `~/.gemini/extensions/memorix`, extension-bundled stdio MCP, `GEMINI.md` context, hooks, commands, and skills. Antigravity CLI has an official Gemini CLI migration path, but Gemini CLI remains a separate target.
 - OpenCode: local plugin file, `opencode.json` MCP config, OpenCode skill, plus `AGENTS.md` guidance.
+- Grok Build: native hooks in `~/.grok/hooks/memorix.json` and guidance in `~/.grok/AGENTS.md`. Global hooks are trusted; project hooks require Grok `/hooks-trust` or `--trust`. Memorix does not write Grok's `config.toml` or MCP entries.
 - Antigravity: native plugin under `~/.gemini/config/plugins/memorix` or `.agents/plugins/memorix`, with `plugin.json`, `mcp_config.json`, `hooks.json`, rules, and skills.
 - OpenClaw: OpenClaw-compatible bundle under `~/.openclaw/extensions/memorix`, bundled `.mcp.json`, skills, and OpenClaw `HOOK.md`/`handler.ts` hook pack.
 - Hermes Agent: Hermes plugin under Hermes home (`%LOCALAPPDATA%\hermes` on native Windows, `~/.hermes` elsewhere, or `HERMES_HOME`), enabled in `config.yaml`, with plugin hooks, slash command, CLI command, skills, and MCP config.