@equationalapplications/core-llm-wiki 2.6.0 → 3.1.0

package/dist/index.mjs

@@ -18,7 +18,8 @@ async function setupDatabase(db, prefix) {
       last_accessed_at INTEGER,
       access_count INTEGER NOT NULL DEFAULT 0,
       deleted_at INTEGER,
-      embedding TEXT
+      embedding TEXT,
+      embedding_blob BLOB
     );
 
     CREATE INDEX IF NOT EXISTS ${prefix}entries_entity_idx ON ${prefix}entries(entity_id);
@@ -91,6 +92,20 @@ var MIGRATIONS = [
         await db.execAsync(`ALTER TABLE ${prefix}entries ADD COLUMN embedding TEXT`);
       }
     }
+  },
+  {
+    version: 3,
+    description: "Add embedding_blob BLOB column for Float32Array vector storage",
+    run: async (db, prefix) => {
+      const cols = await db.getAllAsync(
+        `PRAGMA table_info(${prefix}entries)`
+      );
+      if (!cols.some((c) => c.name === "embedding_blob")) {
+        await db.execAsync(
+          `ALTER TABLE ${prefix}entries ADD COLUMN embedding_blob BLOB`
+        );
+      }
+    }
   }
 ];
 for (let i = 1; i < MIGRATIONS.length; i++) {
@@ -148,6 +163,34 @@ function cosineSimilarity(a, b) {
   return denom === 0 ? 0 : dot / denom;
 }
 
+// src/utils/embedding.ts
+function parseEmbedding(blob, text) {
+  if (blob && blob.byteLength > 0) {
+    if (blob.byteLength % 4 !== 0) return null;
+    const copy = new ArrayBuffer(blob.byteLength);
+    new Uint8Array(copy).set(blob);
+    const vector = new Float32Array(copy);
+    for (const value of vector) {
+      if (!Number.isFinite(value)) return null;
+    }
+    return vector;
+  }
+  if (text) {
+    try {
+      const arr = JSON.parse(text);
+      if (!Array.isArray(arr) || !arr.every((v) => typeof v === "number" && isFinite(v))) return null;
+      const vector = new Float32Array(arr);
+      for (const value of vector) {
+        if (!Number.isFinite(value)) return null;
+      }
+      return vector;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
 // src/WikiMemory.ts
 function parseJsonResponse(text) {
   const firstBrace = text.indexOf("{");
@@ -352,7 +395,7 @@ function jaccardScore(a, b) {
 }
 var FUZZY_THRESHOLD = 0.5;
 var MIN_TOKENS_TO_QUALIFY = 3;
-var WikiMemory = class {
+var _WikiMemory = class _WikiMemory {
   constructor(db, options) {
     this.activeMaintenanceJobs = /* @__PURE__ */ new Set();
     this.activeIngestJobs = /* @__PURE__ */ new Set();
@@ -366,6 +409,7 @@ var WikiMemory = class {
       }
     });
     this.miniSearchEntryIdsByEntity = /* @__PURE__ */ new Map();
+    this.vectorCache = /* @__PURE__ */ new Map();
     this.db = db;
     this.options = options;
     this.prefix = options.config?.tablePrefix || "llm_wiki_";
@@ -432,10 +476,6 @@ var WikiMemory = class {
           `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
           [String(dim)]
         );
-      } else {
-        await this.db.runAsync(
-          `DELETE FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
-        );
       }
     } else {
       await this.db.runAsync(
@@ -454,7 +494,18 @@ var WikiMemory = class {
     const mismatch = await this.db.getFirstAsync(
       `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
     );
-    if (mismatch) {
+    if (!mismatch) return;
+    const newDim = parseInt(mismatch.value, 10);
+    const residual = await this.db.getFirstAsync(
+      `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+       WHERE deleted_at IS NULL
+         AND (
+           (embedding_blob IS NOT NULL AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?)
+           OR (embedding_blob IS NULL AND embedding IS NOT NULL)
+         )`,
+      [newDim]
+    );
+    if (!residual || residual.cnt === 0) {
       await this.db.runAsync(
         `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension', ?)`,
         [mismatch.value]
@@ -485,11 +536,29 @@ var WikiMemory = class {
         console.warn(`[WikiMemory] embedFact: embed() returned an invalid vector for ${fact.id}; skipping.`);
         return false;
       }
-      await this.storeEmbeddingDimension(vector.length);
+      const float32Vector = new Float32Array(vector);
+      let hasNonFinite = false;
+      for (let i = 0; i < float32Vector.length; i++) {
+        if (!isFinite(float32Vector[i])) {
+          hasNonFinite = true;
+          break;
+        }
+      }
+      if (hasNonFinite) {
+        console.warn(`[WikiMemory] embedFact: embed() returned values that overflow float32 for ${fact.id}; skipping.`);
+        return false;
+      }
+      await this.storeEmbeddingDimension(float32Vector.length);
+      const blob = new Uint8Array(float32Vector.buffer);
       await this.db.runAsync(
-        `UPDATE ${this.prefix}entries SET embedding = ? WHERE id = ?`,
-        [JSON.stringify(vector), fact.id]
+        `UPDATE ${this.prefix}entries SET embedding_blob = ?, embedding = NULL WHERE id = ?`,
+        [blob, fact.id]
       );
+      try {
+        await this._notifyEmbeddingPersisted(fact.entity_id, fact.id, float32Vector);
+      } catch (hookErr) {
+        console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for ${fact.id}:`, hookErr);
+      }
       return true;
     } catch (err) {
       console.warn(`[WikiMemory] embedFact failed for ${fact.id}:`, err);
@@ -505,6 +574,9 @@ var WikiMemory = class {
   _warnCrossEntityCollision(type, id, existingEntityId, targetEntityId) {
     console.warn(`[WikiMemory] importDump: ${type} id "${id}" already belongs to entity "${existingEntityId}"; skipping for entity "${targetEntityId}"`);
   }
+  async _notifyEmbeddingPersisted(entityId, factId, vector) {
+    await this.options.vectorRanker?.onEmbeddingPersisted?.({ entityId, factId, vector });
+  }
   async setup() {
     const entriesExistedBeforeSetup = await this.db.getFirstAsync(
       `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
@@ -608,9 +680,24 @@ var WikiMemory = class {
   _globalReembedKey() {
     return `${this.prefix}:reembed`;
   }
+  _importKey(entityId) {
+    return `${this.prefix}:${entityId}:import`;
+  }
+  _globalImportKey() {
+    return `${this.prefix}:import`;
+  }
+  _forgetKey(entityId) {
+    return `${this.prefix}:${entityId}:forget`;
+  }
   _isReembedActive(entityId) {
     return this.activeMaintenanceJobs.has(this._reembedKey(entityId)) || this.activeMaintenanceJobs.has(this._globalReembedKey());
   }
+  _isImportActiveFor(entityId) {
+    return this.activeMaintenanceJobs.has(this._importKey(entityId)) || this.activeMaintenanceJobs.has(this._globalImportKey());
+  }
+  _isForgetActiveFor(entityId) {
+    return this.activeMaintenanceJobs.has(this._forgetKey(entityId));
+  }
   /** Returns true if any maintenance job has the given operation suffix (e.g. ':prune'). */
   _isAnyMaintenanceActiveWithSuffix(suffix) {
     const entityKeyPrefix = `${this.prefix}:`;
@@ -653,6 +740,10 @@ var WikiMemory = class {
       blockingOperation = "reembed";
     } else if (isIngestRunning) {
       blockingOperation = "ingest";
+    } else if (this._isImportActiveFor(entityId)) {
+      blockingOperation = "import";
+    } else if (this._isForgetActiveFor(entityId)) {
+      blockingOperation = "forget";
     }
     if (blockingOperation !== null) {
       throw new WikiBusyError(blockingOperation, entityId);
@@ -668,8 +759,15 @@ var WikiMemory = class {
       let deletedEntries = 0;
       let deletedTasks = 0;
       let deletedEvents = 0;
+      const deletedEntryIds = [];
       if (retainSoftDeletedFor !== null) {
         const cutoff = now - retainSoftDeletedFor * 864e5;
+        const entriesToDelete = await this.db.getAllAsync(
+          `SELECT id FROM ${this.prefix}entries
+           WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at < ?`,
+          [entityId, cutoff]
+        );
+        deletedEntryIds.push(...entriesToDelete.map((e) => e.id));
         const entryResult = await this.db.runAsync(
           `DELETE FROM ${this.prefix}entries
            WHERE entity_id = ? AND deleted_at IS NOT NULL AND deleted_at < ?`,
@@ -697,19 +795,39 @@ var WikiMemory = class {
         await this.db.execAsync(`VACUUM`);
       }
       await this.rebuildMiniSearchIndex(entityId);
+      this.vectorCache.delete(entityId);
+      const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
+      for (const factId of uniqueDeletedIds) {
+        try {
+          await this._notifyEmbeddingPersisted(entityId, factId, null);
+        } catch (hookErr) {
+          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during prune for ${factId}:`, hookErr);
+        }
+      }
       return { entries: deletedEntries, tasks: deletedTasks, events: deletedEvents };
     } finally {
       this.activeMaintenanceJobs.delete(pruneKey);
     }
   }
-  async read(entityId, query) {
-    const maxResults = this.options.config?.maxResults ?? this.options.config?.maxFtsResults ?? 10;
+  async read(entityId, query, options) {
+    const config = this.options.config;
+    const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
+    const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
+    const rawPreFilterLimit = options?.preFilterLimit === null ? void 0 : options?.preFilterLimit ?? config?.preFilterLimit;
+    const effectivePreFilterLimit = rawPreFilterLimit === void 0 ? void 0 : Number.isFinite(rawPreFilterLimit) ? Math.max(0, Math.trunc(rawPreFilterLimit)) : void 0;
+    const hybridWeight = options?.hybridWeight ?? config?.hybridWeight;
+    const weight = hybridWeight !== void 0 && !Number.isNaN(hybridWeight) ? Math.max(0, Math.min(1, hybridWeight)) : void 0;
+    const skipEmbed = weight === 0;
     const embedFn = this.options.llmProvider.embed;
     const trimmedQuery = query.trim();
     let facts = [];
-    if (trimmedQuery) {
+    if (maxResults === 0) ; else if (trimmedQuery) {
       let usedEmbed = false;
-      if (embedFn) {
+      if (!skipEmbed && embedFn) {
+        let rankerShouldRethrow = false;
+        let pendingRankerFallbackError;
+        let usedKeywordFallback = false;
+        let scoredAlreadySortedAndLimited = false;
         try {
           const queryVec = await embedFn(trimmedQuery);
           if (queryVec.length === 0 || !queryVec.every((v) => typeof v === "number" && isFinite(v))) {
@@ -728,51 +846,350 @@ var WikiMemory = class {
               );
             }
           }
-          const scoreRows = await this.db.getAllAsync(
-            `SELECT id, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
-            [entityId]
+          const mismatchedCount = await this.db.getFirstAsync(
+            `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+             WHERE entity_id = ? AND deleted_at IS NULL
+               AND embedding_blob IS NOT NULL
+               AND (CAST(length(embedding_blob) AS INTEGER) % 4 = 0)
+               AND (CAST(length(embedding_blob) AS INTEGER) / 4) != ?`,
+            [entityId, queryVec.length]
           );
-          const scored = scoreRows.map((row) => {
-            let score = 0;
-            if (row.embedding) {
-              try {
-                const parsed = JSON.parse(row.embedding);
-                if (Array.isArray(parsed) && parsed.length === queryVec.length && parsed.every((v) => typeof v === "number" && isFinite(v))) {
-                  score = cosineSimilarity(queryVec, parsed);
+          if (mismatchedCount && mismatchedCount.cnt > 0) {
+            throw new Error(
+              `Some facts have embeddings that do not match the current model dimension. Call runReembed() to rebuild all embeddings consistently.`
+            );
+          }
+          const useRanker = Boolean(this.options.vectorRanker);
+          let candidateRows;
+          let populateCache = true;
+          let miniSearchScores;
+          if (effectivePreFilterLimit !== void 0) {
+            populateCache = false;
+            const preResults = this.miniSearch.search(trimmedQuery, {
+              filter: (r) => r.entity_id === entityId,
+              combineWith: "OR"
+            });
+            if (preResults.length === 0) {
+              candidateRows = null;
+            } else {
+              const topKResults = preResults.slice(0, effectivePreFilterLimit);
+              if (topKResults.length === 0) {
+                candidateRows = null;
+              } else {
+                const topKIds = topKResults.map((r) => r.id);
+                const inClauseChunkSize = 500;
+                if (useRanker) {
+                  const rows = [];
+                  for (let i = 0; i < topKIds.length; i += inClauseChunkSize) {
+                    const idChunk = topKIds.slice(i, i + inClauseChunkSize);
+                    const placeholders = idChunk.map(() => "?").join(",");
+                    const chunkRows = await this.db.getAllAsync(
+                      `SELECT id, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+                      idChunk
+                    );
+                    rows.push(...chunkRows);
+                  }
+                  candidateRows = rows;
+                } else {
+                  const rows = [];
+                  for (let i = 0; i < topKIds.length; i += inClauseChunkSize) {
+                    const idChunk = topKIds.slice(i, i + inClauseChunkSize);
+                    const placeholders = idChunk.map(() => "?").join(",");
+                    const chunkRows = await this.db.getAllAsync(
+                      `SELECT id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
+                      idChunk
+                    );
+                    rows.push(...chunkRows);
+                  }
+                  candidateRows = rows;
+                }
+                if (weight !== void 0 && weight < 1) {
+                  const maxMsScore = Math.max(1, topKResults[0]?.score ?? 1);
+                  miniSearchScores = new Map(topKResults.map((r) => [r.id, r.score / maxMsScore]));
                 }
-              } catch {
               }
             }
-            return { row, score };
-          });
-          scored.sort((a, b) => {
-            const scoreDiff = b.score - a.score;
-            if (scoreDiff !== 0) {
-              return scoreDiff;
+          } else {
+            if (useRanker) {
+              candidateRows = await this.db.getAllAsync(
+                `SELECT id, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
+                [entityId]
+              );
+            } else {
+              candidateRows = await this.db.getAllAsync(
+                `SELECT id, embedding_blob, embedding, updated_at, access_count FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
+                [entityId]
+              );
             }
-            const updatedAtDiff = (b.row.updated_at ?? 0) - (a.row.updated_at ?? 0);
-            if (updatedAtDiff !== 0) {
-              return updatedAtDiff;
+            if (weight !== void 0 && weight < 1) {
+              const msResults = this.miniSearch.search(trimmedQuery, {
+                filter: (r) => r.entity_id === entityId,
+                combineWith: "OR"
+              });
+              const maxMsScore = Math.max(1, msResults[0]?.score ?? 1);
+              miniSearchScores = new Map(msResults.map((r) => [r.id, r.score / maxMsScore]));
+            }
+          }
+          if (candidateRows === null) {
+            usedEmbed = true;
+          } else {
+            let scored;
+            if (useRanker) {
+              const candidateIds = effectivePreFilterLimit !== void 0 ? candidateRows.map((r) => r.id) : void 0;
+              try {
+                const oversampledLimit = Math.max(maxResults * 2, maxResults + 50);
+                scored = await this._rankWithVectorRanker({
+                  entityId,
+                  queryVec,
+                  candidateIds,
+                  weight,
+                  miniSearchScores,
+                  limit: oversampledLimit
+                });
+                if (scored.length > 0) {
+                  const scoredIds2 = new Set(scored.map((s) => s.id));
+                  const metaMap = /* @__PURE__ */ new Map();
+                  for (const r of candidateRows) {
+                    if (scoredIds2.has(r.id)) {
+                      metaMap.set(r.id, { updated_at: r.updated_at, access_count: r.access_count });
+                    }
+                  }
+                  scored = scored.map((s) => {
+                    const meta = metaMap.get(s.id);
+                    return { ...s, updated_at: meta?.updated_at ?? null, access_count: meta?.access_count ?? null };
+                  });
+                }
+                const scoredIds = new Set(scored.map((s) => s.id));
+                const isHybrid = weight !== void 0 && weight < 1;
+                const maxBackfill = isHybrid ? maxResults : Math.max(0, maxResults - scored.length);
+                if (maxBackfill > 0) {
+                  if (isHybrid) {
+                    const topK = [];
+                    for (const row of candidateRows) {
+                      if (scoredIds.has(row.id)) continue;
+                      const kwScore = miniSearchScores?.get(row.id) ?? 0;
+                      const candidate = { row, kwScore };
+                      if (topK.length < maxBackfill) {
+                        let insertIdx = topK.length;
+                        for (let i = 0; i < topK.length; i++) {
+                          const cmp = this._compareScoredRows(
+                            {
+                              id: candidate.row.id,
+                              score: candidate.kwScore,
+                              updated_at: candidate.row.updated_at,
+                              access_count: candidate.row.access_count
+                            },
+                            {
+                              id: topK[i].row.id,
+                              score: topK[i].kwScore,
+                              updated_at: topK[i].row.updated_at,
+                              access_count: topK[i].row.access_count
+                            }
+                          );
+                          if (cmp < 0) {
+                            insertIdx = i;
+                            break;
+                          }
+                        }
+                        topK.splice(insertIdx, 0, candidate);
+                      } else {
+                        const cmpWorst = this._compareScoredRows(
+                          {
+                            id: candidate.row.id,
+                            score: candidate.kwScore,
+                            updated_at: candidate.row.updated_at,
+                            access_count: candidate.row.access_count
+                          },
+                          {
+                            id: topK[maxBackfill - 1].row.id,
+                            score: topK[maxBackfill - 1].kwScore,
+                            updated_at: topK[maxBackfill - 1].row.updated_at,
+                            access_count: topK[maxBackfill - 1].row.access_count
+                          }
+                        );
+                        if (cmpWorst < 0) {
+                          let insertIdx = maxBackfill - 1;
+                          for (let i = 0; i < topK.length; i++) {
+                            const cmp = this._compareScoredRows(
+                              {
+                                id: candidate.row.id,
+                                score: candidate.kwScore,
+                                updated_at: candidate.row.updated_at,
+                                access_count: candidate.row.access_count
+                              },
+                              {
+                                id: topK[i].row.id,
+                                score: topK[i].kwScore,
+                                updated_at: topK[i].row.updated_at,
+                                access_count: topK[i].row.access_count
+                              }
+                            );
+                            if (cmp < 0) {
+                              insertIdx = i;
+                              break;
+                            }
+                          }
+                          topK.splice(insertIdx, 0, candidate);
+                          topK.pop();
+                        }
+                      }
+                    }
+                    for (const { row, kwScore } of topK) {
+                      scored.push({
+                        id: row.id,
+                        score: (1 - weight) * kwScore,
+                        updated_at: row.updated_at,
+                        access_count: row.access_count
+                      });
+                    }
+                  } else {
+                    const omitted = [];
+                    for (const row of candidateRows) {
+                      if (scoredIds.has(row.id)) continue;
+                      omitted.push({ id: row.id, score: -2, updated_at: row.updated_at, access_count: row.access_count });
+                    }
+                    if (omitted.length > 0) {
+                      this._tieBreakSort(omitted);
+                      scored.push(...omitted.slice(0, maxBackfill));
+                    }
+                  }
+                }
+              } catch (rankerErr) {
+                const rankerError = rankerErr instanceof Error ? rankerErr : new Error(String(rankerErr));
+                const policy = this.options.vectorRankerFallback ?? "js-cosine";
+                this.options.onVectorRankerFallback?.({ error: rankerError, policy });
+                if (policy === "throw") {
+                  rankerShouldRethrow = true;
+                  throw rankerError;
+                } else if (policy === "js-cosine") {
+                  let fallbackRows = candidateRows;
+                  if (fallbackRows && fallbackRows.length > 0 && !("embedding_blob" in fallbackRows[0])) {
+                    const rowIds = fallbackRows.map((r) => r.id);
+                    const embeddingsMap = /* @__PURE__ */ new Map();
+                    const chunkSize = 500;
+                    for (let i = 0; i < rowIds.length; i += chunkSize) {
+                      const idChunk = rowIds.slice(i, i + chunkSize);
+                      const placeholders = idChunk.map(() => "?").join(",");
+                      const embeddingRows = await this.db.getAllAsync(
+                        `SELECT id, embedding_blob, embedding FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
+                        [...idChunk, entityId]
+                      );
+                      for (const row of embeddingRows) {
+                        embeddingsMap.set(row.id, { embedding_blob: row.embedding_blob, embedding: row.embedding });
+                      }
+                    }
+                    fallbackRows = fallbackRows.map((r) => ({
+                      ...r,
+                      embedding_blob: embeddingsMap.get(r.id)?.embedding_blob ?? null,
+                      embedding: embeddingsMap.get(r.id)?.embedding ?? null
+                    }));
+                  }
+                  scored = await this._rankWithJsCosine({
+                    entityId,
+                    queryVec,
+                    candidateRows: fallbackRows,
+                    weight,
+                    miniSearchScores,
+                    populateCache,
+                    limit: maxResults
+                  });
+                  scoredAlreadySortedAndLimited = true;
+                } else if (policy === "keyword") {
+                  const msResults = this.miniSearch.search(trimmedQuery, {
+                    filter: (r) => r.entity_id === entityId,
+                    combineWith: "OR"
+                  });
+                  const topResults = msResults.slice(0, maxResults);
+                  const resultIds = new Set(topResults.map((r) => r.id));
+                  const candidateMap = /* @__PURE__ */ new Map();
+                  for (const r of candidateRows) {
+                    if (resultIds.has(r.id)) {
+                      candidateMap.set(r.id, { updated_at: r.updated_at, access_count: r.access_count });
+                    }
+                  }
+                  scored = topResults.map((r) => {
+                    const meta = candidateMap.get(r.id);
+                    return {
+                      id: r.id,
+                      score: r.score ?? 0,
+                      access_count: meta?.access_count ?? null,
+                      updated_at: meta?.updated_at ?? null
+                    };
+                  });
+                  usedKeywordFallback = true;
+                } else {
+                  scored = [];
+                }
+                if (this.options.propagateRankerFailureToRetrievalFallback) {
+                  const mirrored = new Error("Vector ranker failed, falling back");
+                  mirrored.cause = rankerError;
+                  pendingRankerFallbackError = mirrored;
+                }
+              }
+            } else {
+              scored = await this._rankWithJsCosine({
+                entityId,
+                queryVec,
+                candidateRows,
+                weight,
+                miniSearchScores,
+                populateCache,
+                limit: maxResults
+              });
+              scoredAlreadySortedAndLimited = true;
             }
-            const accessCountDiff = (b.row.access_count ?? 0) - (a.row.access_count ?? 0);
-            if (accessCountDiff !== 0) {
-              return accessCountDiff;
+            if (scored.length > 0) {
+              if (!usedKeywordFallback && !scoredAlreadySortedAndLimited) {
+                this._tieBreakSort(scored);
+              }
+              const topIds = (scoredAlreadySortedAndLimited ? scored : scored.slice(0, maxResults)).map((s) => s.id);
+              if (topIds.length > 0) {
+                const fullRows = [];
+                const phase2ChunkSize = 500;
+                for (let i = 0; i < topIds.length; i += phase2ChunkSize) {
+                  const idChunk = topIds.slice(i, i + phase2ChunkSize);
+                  const placeholders = idChunk.map(() => "?").join(",");
+                  const chunkRows = await this.db.getAllAsync(
+                    `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
+                    [...idChunk, entityId]
+                  );
+                  fullRows.push(...chunkRows);
+                }
+                const byId = new Map(fullRows.map((r) => [r.id, r]));
+                facts = topIds.map((id) => byId.get(id)).filter((f) => f !== void 0);
+                if (facts.length < topIds.length) {
+                  const missingIds = topIds.filter((id) => !byId.has(id));
+                  const missingCount = missingIds.length;
+                  const sample = missingIds.slice(0, 5);
+                  const sampleSuffix = sample.length > 0 ? ` Missing ID sample: ${sample.join(", ")}${missingIds.length > sample.length ? ", ..." : ""}.` : "";
+                  const error = new Error(
+                    `Phase 2 fact hydration returned ${missingCount} fewer row(s) than ranked IDs for entity ${entityId}. Rows may have been concurrently soft-deleted or filtered by deleted_at during hydration, or vector ranker output may include IDs that do not exist for this entity.` + sampleSuffix
+                  );
+                  this.options.onRetrievalFallback?.(error);
+                }
+              }
+              if (pendingRankerFallbackError) {
+                this.options.onRetrievalFallback?.(pendingRankerFallbackError);
+                pendingRankerFallbackError = void 0;
+              }
+              usedEmbed = true;
+            } else {
+              if (pendingRankerFallbackError) {
+                this.options.onRetrievalFallback?.(pendingRankerFallbackError);
+                pendingRankerFallbackError = void 0;
+              }
+              usedEmbed = true;
             }
-            return a.row.id.localeCompare(b.row.id);
-          });
-          const topIds = scored.slice(0, maxResults).map((s) => s.row.id);
-          if (topIds.length > 0) {
-            const placeholders = topIds.map(() => "?").join(",");
-            const fullRows = await this.db.getAllAsync(
-              `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
-              topIds
-            );
-            const byId = new Map(fullRows.map((r) => [r.id, r]));
-            facts = topIds.map((id) => byId.get(id)).filter((f) => f !== void 0);
           }
-          usedEmbed = true;
         } catch (err) {
           const error = err instanceof Error ? err : new Error(String(err));
+          if (rankerShouldRethrow) {
+            throw error;
+          }
+          if (pendingRankerFallbackError) {
+            error.cause = pendingRankerFallbackError;
+            pendingRankerFallbackError = void 0;
+          }
           this.options.onRetrievalFallback?.(error);
         }
       }
@@ -783,25 +1200,35 @@ var WikiMemory = class {
         });
         const topIds = results.slice(0, maxResults).map((r) => r.id);
         if (topIds.length > 0) {
-          const placeholders = topIds.map(() => "?").join(",");
-          const rows = await this.db.getAllAsync(
-            `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND deleted_at IS NULL`,
-            topIds
-          );
-          const byId = new Map(rows.map((r) => [r.id, r]));
+          const kwRows = [];
+          const kwChunkSize = 500;
+          for (let i = 0; i < topIds.length; i += kwChunkSize) {
+            const idChunk = topIds.slice(i, i + kwChunkSize);
+            const placeholders = idChunk.map(() => "?").join(",");
+            const chunkRows = await this.db.getAllAsync(
+              `SELECT * FROM ${this.prefix}entries WHERE id IN (${placeholders}) AND entity_id = ? AND deleted_at IS NULL`,
+              [...idChunk, entityId]
+            );
+            kwRows.push(...chunkRows);
+          }
+          const byId = new Map(kwRows.map((r) => [r.id, r]));
           facts = topIds.map((id) => byId.get(id)).filter((f) => f !== void 0);
         }
       }
       if (facts.length > 0) {
         const ids = facts.map((f) => f.id);
-        const placeholders = ids.map(() => "?").join(",");
         const now = Date.now();
-        await this.db.runAsync(
-          `UPDATE ${this.prefix}entries
-           SET access_count = access_count + 1, last_accessed_at = ?
-           WHERE id IN (${placeholders})`,
-          [now, ...ids]
-        );
+        const accessChunkSize = 500;
+        for (let i = 0; i < ids.length; i += accessChunkSize) {
+          const idChunk = ids.slice(i, i + accessChunkSize);
+          const placeholders = idChunk.map(() => "?").join(",");
+          await this.db.runAsync(
+            `UPDATE ${this.prefix}entries
+             SET access_count = access_count + 1, last_accessed_at = ?
+             WHERE id IN (${placeholders})`,
+            [now, ...idChunk]
+          );
+        }
       }
     } else {
       facts = await this.db.getAllAsync(
@@ -828,7 +1255,7 @@ var WikiMemory = class {
       )
     ]);
     const parsedFacts = facts.map((f) => {
-      const { embedding: _embedding, ...rest } = f;
+      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
       return {
         ...rest,
         tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
@@ -836,6 +1263,113 @@ var WikiMemory = class {
     });
     return { facts: parsedFacts, tasks, events: events.reverse() };
   }
+  /**
+   * Stable tie-break sort: score desc → access_count desc → updated_at desc → id asc.
+   */
+  _tieBreakSort(items) {
+    items.sort((a, b) => this._compareScoredRows(a, b));
+  }
+  /**
+   * Comparator for score + deterministic tie-break fields.
+   * Negative return means "a ranks ahead of b" for descending score order.
+   */
+  _compareScoredRows(a, b) {
+    const scoreDiff = b.score - a.score;
+    if (scoreDiff !== 0) return scoreDiff;
+    const accessCountDiff = (b.access_count ?? 0) - (a.access_count ?? 0);
+    if (accessCountDiff !== 0) return accessCountDiff;
+    const updatedAtDiff = (b.updated_at ?? 0) - (a.updated_at ?? 0);
+    if (updatedAtDiff !== 0) return updatedAtDiff;
+    return a.id.localeCompare(b.id);
+  }
+  /**
+   * Score candidate rows using in-process JS cosine similarity.
+   * Applies hybrid blending (if weight set) and tie-break sorting before returning.
+   */
+  async _rankWithJsCosine(args) {
+    const { entityId, queryVec, candidateRows, weight, miniSearchScores, populateCache, limit } = args;
+    let entityCache = this.vectorCache.get(entityId);
+    const tooLarge = populateCache && candidateRows.length > _WikiMemory.MAX_VECTOR_CACHE_FACTS_PER_ENTITY;
+    if (tooLarge && entityCache) {
+      this.vectorCache.delete(entityId);
+      entityCache = void 0;
+    }
+    const canCache = populateCache && !tooLarge;
+    if (canCache && !entityCache) {
+      entityCache = /* @__PURE__ */ new Map();
+    }
+    const scored = candidateRows.map((row) => {
+      let vector = entityCache?.get(row.id) ?? parseEmbedding(row.embedding_blob, row.embedding);
+      if (vector && canCache && entityCache && !entityCache.has(row.id)) {
+        entityCache.set(row.id, vector);
+      }
+      let score = 0;
+      if (vector && vector.length === queryVec.length) {
+        const cosSim = cosineSimilarity(queryVec, vector);
+        if (weight !== void 0) {
+          const kwScore = miniSearchScores?.get(row.id) ?? 0;
+          score = weight * Math.max(0, cosSim) + (1 - weight) * kwScore;
+        } else {
+          score = cosSim;
+        }
+      } else if (weight !== void 0 && weight < 1) {
+        const kwScore = miniSearchScores?.get(row.id) ?? 0;
+        score = (1 - weight) * kwScore;
+      } else {
+        score = -2;
+      }
+      return { id: row.id, score, updated_at: row.updated_at, access_count: row.access_count };
+    });
+    if (canCache && entityCache && entityCache.size > 0) {
+      if (!this.vectorCache.has(entityId)) {
+        if (this.vectorCache.size >= _WikiMemory.MAX_VECTOR_CACHE_ENTITIES) {
+          const oldestKey = this.vectorCache.keys().next().value;
+          if (oldestKey !== void 0) this.vectorCache.delete(oldestKey);
+        }
+        this.vectorCache.set(entityId, entityCache);
+      }
+    }
+    this._tieBreakSort(scored);
+    return scored.slice(0, limit);
+  }
+  /**
+   * Delegate semantic ranking to the injected VectorRanker.
+   * Caller should pass an oversampledLimit to preserve recall after re-ranking.
+   * Returns scored results ready for hybrid blending and tie-break sorting.
+   */
+  async _rankWithVectorRanker(args) {
+    const { entityId, queryVec, candidateIds, weight, miniSearchScores, limit } = args;
+    const ranker = this.options.vectorRanker;
+    if (!ranker) {
+      throw new Error("vectorRanker not configured");
+    }
+    const rankerResults = await ranker.rankBySimilarity({
+      entityId,
+      queryVec,
+      candidateIds,
+      limit
+    });
+    const allowedIds = candidateIds ? new Set(candidateIds) : void 0;
+    const seen = /* @__PURE__ */ new Set();
+    const normalized = [];
+    for (const r of rankerResults) {
+      if (normalized.length >= limit) break;
+      if (seen.has(r.id)) continue;
+      if (allowedIds && !allowedIds.has(r.id)) continue;
+      if (!Number.isFinite(r.semanticScore)) continue;
+      seen.add(r.id);
+      normalized.push(r);
+    }
+    const scored = normalized.map((r) => {
+      let score = r.semanticScore;
+      if (weight !== void 0) {
+        const kwScore = miniSearchScores?.get(r.id) ?? 0;
+        score = weight * Math.max(0, r.semanticScore) + (1 - weight) * kwScore;
+      }
+      return { id: r.id, score };
+    });
+    return scored;
+  }
   async getMemoryBundle(entityId) {
     return this._getFullBundle(entityId, { maxEvents: 10 });
   }
@@ -860,7 +1394,7 @@ var WikiMemory = class {
     if (memoryCheckpoint > count) memoryCheckpoint = 0;
     if (count - memoryCheckpoint >= threshold) {
       const jobKey = this._librarianKey(entityId);
-      if (!this.activeMaintenanceJobs.has(jobKey) && !this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
+      if (!this.activeMaintenanceJobs.has(jobKey) && !this.activeMaintenanceJobs.has(this._pruneKey(entityId)) && !this._isReembedActive(entityId) && !this._isImportActiveFor(entityId) && !this._isForgetActiveFor(entityId)) {
         this.activeMaintenanceJobs.add(jobKey);
         this.runLibrarianThenMaybeHeal(entityId, count).catch(console.error).finally(() => this.activeMaintenanceJobs.delete(jobKey));
       }
@@ -908,7 +1442,7 @@ var WikiMemory = class {
       LIMIT 100
     `, [entityId]);
     const currentFacts = currentFactsRows.map((f) => {
-      const { embedding: _embedding, ...rest } = f;
+      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
       return {
         ...rest,
         tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
@@ -952,7 +1486,7 @@ ${JSON.stringify(currentFacts, null, 2)}`;
           INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
         `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "agent_inferred", now, now]);
-        insertedFacts.push({ id, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
       }
       for (const task of validTasks) {
         const id = generateId("task_");
@@ -962,10 +1496,12 @@ ${JSON.stringify(currentFacts, null, 2)}`;
         `, [id, entityId, task.description, "pending", task.priority, now, now]);
       }
     });
+    await this.rebuildMiniSearchIndex(entityId);
+    this.vectorCache.delete(entityId);
     for (const fact of insertedFacts) {
       await this.embedFact(fact);
     }
-    await this.rebuildMiniSearchIndex(entityId);
+    this.vectorCache.delete(entityId);
   }
   async _doRunHeal(entityId) {
     const now = Date.now();
@@ -1003,7 +1539,7 @@ ${JSON.stringify(currentFacts, null, 2)}`;
     const documentAnchors = allFactsRows.filter((f) => f.source_type === "user_document").map(({ id, title, source_ref }) => ({ id, title, source_ref }));
     const userPrompt = `Heal Candidates:
 ${JSON.stringify(healCandidates.map((f) => {
-      const { embedding: _embedding, ...rest } = f;
+      const { embedding: _embedding, embedding_blob: _blob, ...rest } = f;
       return { ...rest, tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags };
     }), null, 2)}
 
@@ -1030,6 +1566,7 @@ The following document anchors are provided for contradiction detection only. Do
     const safeDeleted = deleted.filter((id) => mutableIds.has(id));
     const validNewFacts = newFacts.map(validateFact).filter((f) => f !== null);
     const insertedFacts = [];
+    const uniqueDeletedFactIds = Array.from(new Set(safeDeleted));
     await this.db.withTransactionAsync(async () => {
       for (const id of safeDowngraded) {
         await this.db.runAsync(`UPDATE ${this.prefix}entries SET confidence = 'tentative', updated_at = ? WHERE id = ? AND entity_id = ?`, [now, id, entityId]);
@@ -1043,13 +1580,22 @@ The following document anchors are provided for contradiction detection only. Do
           INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, created_at, updated_at)
           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
         `, [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "agent_inferred", now, now]);
-        insertedFacts.push({ id, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+        insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
       }
     });
+    this.vectorCache.delete(entityId);
+    await this.rebuildMiniSearchIndex(entityId);
+    for (const factId of uniqueDeletedFactIds) {
+      try {
+        await this._notifyEmbeddingPersisted(entityId, factId, null);
+      } catch (hookErr) {
+        console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during heal for ${factId}:`, hookErr);
+      }
+    }
     for (const fact of insertedFacts) {
       await this.embedFact(fact);
     }
-    await this.rebuildMiniSearchIndex(entityId);
+    this.vectorCache.delete(entityId);
   }
   async runLibrarian(entityId) {
     const jobKey = this._librarianKey(entityId);
@@ -1062,6 +1608,12 @@ The following document anchors are provided for contradiction detection only. Do
     if (this._isReembedActive(entityId)) {
       throw new WikiBusyError("reembed", entityId);
     }
+    if (this._isImportActiveFor(entityId)) {
+      throw new WikiBusyError("import", entityId);
+    }
+    if (this._isForgetActiveFor(entityId)) {
+      throw new WikiBusyError("forget", entityId);
+    }
     this.activeMaintenanceJobs.add(jobKey);
     try {
       await this._doRunLibrarian(entityId);
@@ -1080,6 +1632,12 @@ The following document anchors are provided for contradiction detection only. Do
     if (this._isReembedActive(entityId)) {
       throw new WikiBusyError("reembed", entityId);
     }
+    if (this._isImportActiveFor(entityId)) {
+      throw new WikiBusyError("import", entityId);
+    }
+    if (this._isForgetActiveFor(entityId)) {
+      throw new WikiBusyError("forget", entityId);
+    }
     this.activeMaintenanceJobs.add(jobKey);
     try {
       await this._doRunHeal(entityId);
@@ -1087,9 +1645,9 @@ The following document anchors are provided for contradiction detection only. Do
       this.activeMaintenanceJobs.delete(jobKey);
     }
   }
-  async runReembed(entityId) {
+  async runReembed(entityId, opts) {
     const embedFn = this.options.llmProvider.embed;
-    if (!embedFn) return { embedded: 0, skipped: 0 };
+    if (!embedFn) return { embedded: 0, skipped: 0, failed: 0 };
     const reembedKey = entityId ? this._reembedKey(entityId) : this._globalReembedKey();
     if (this.activeMaintenanceJobs.has(reembedKey)) {
       throw new WikiBusyError("reembed", entityId ?? "*");
@@ -1110,6 +1668,12 @@ The following document anchors are provided for contradiction detection only. Do
       if (this._isIngestActiveFor(entityId)) {
         throw new WikiBusyError("ingest", entityId);
       }
+      if (this._isImportActiveFor(entityId)) {
+        throw new WikiBusyError("import", entityId);
+      }
+      if (this._isForgetActiveFor(entityId)) {
+        throw new WikiBusyError("forget", entityId);
+      }
     } else {
       if (this._isAnyMaintenanceActiveWithSuffix(":reembed")) {
         throw new WikiBusyError("reembed", "*");
@@ -1126,6 +1690,12 @@ The following document anchors are provided for contradiction detection only. Do
       if (this.activeIngestJobs.size > 0) {
         throw new WikiBusyError("ingest", "*");
       }
+      if (this._isAnyMaintenanceActiveWithSuffix(":import")) {
+        throw new WikiBusyError("import", "*");
+      }
+      if (this._isAnyMaintenanceActiveWithSuffix(":forget")) {
+        throw new WikiBusyError("forget", "*");
+      }
     }
     this.activeMaintenanceJobs.add(reembedKey);
     try {
@@ -1135,17 +1705,64 @@ The following document anchors are provided for contradiction detection only. Do
         `SELECT * FROM ${this.prefix}entries WHERE ${where}`,
         params
       );
+      if (entityId) {
+        this.vectorCache.delete(entityId);
+      } else {
+        this.vectorCache.clear();
+      }
+      const skipExisting = opts?.skipExisting ?? false;
+      let effectiveSkip = skipExisting;
+      if (skipExisting) {
+        const mismatchRow = await this.db.getFirstAsync(
+          `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
+        );
+        if (mismatchRow) {
+          if (entityId) {
+            const mismatchDim = parseInt(mismatchRow.value, 10);
+            const staleForEntity = await this.db.getFirstAsync(
+              `SELECT COUNT(*) AS cnt FROM ${this.prefix}entries
+               WHERE entity_id = ? AND deleted_at IS NULL
+                 AND (
+                   embedding_blob IS NULL
+                   OR (CAST(length(embedding_blob) AS INTEGER) / 4) != ?
+                 )`,
+              [entityId, mismatchDim]
+            );
+            if (staleForEntity && staleForEntity.cnt > 0) effectiveSkip = false;
+          } else {
+            effectiveSkip = false;
+          }
+        }
+      }
       let embedded = 0;
       let skipped = 0;
-      for (const row of rows) {
-        const success = await this.embedFact(row);
-        if (success) embedded++;
-        else skipped++;
-      }
-      if (embedded > 0) {
-        await this._reconcileEmbeddingDimension();
+      let failed = 0;
+      try {
+        for (const row of rows) {
+          const existingBlob = row.embedding_blob;
+          const blobIsValid = !!existingBlob && existingBlob.byteLength > 0 && existingBlob.byteLength % 4 === 0;
+          if (effectiveSkip && blobIsValid) {
+            const vec = parseEmbedding(existingBlob, null);
+            if (vec !== null && vec.every((v) => Number.isFinite(v))) {
+              skipped++;
+              continue;
+            }
+          }
+          const success = await this.embedFact(row);
+          if (success) embedded++;
+          else failed++;
+        }
+        if (embedded > 0) {
+          await this._reconcileEmbeddingDimension();
+        }
+      } finally {
+        if (entityId) {
+          this.vectorCache.delete(entityId);
+        } else {
+          this.vectorCache.clear();
+        }
       }
-      return { embedded, skipped };
+      return { embedded, skipped, failed };
     } finally {
       this.activeMaintenanceJobs.delete(reembedKey);
     }
@@ -1165,6 +1782,9 @@ The following document anchors are provided for contradiction detection only. Do
       heal: this.activeMaintenanceJobs.has(this._healKey(entityId))
     };
   }
+  clearVectorCache() {
+    this.vectorCache.clear();
+  }
   async _getFullBundle(entityId, opts) {
     const maxEvents = opts?.maxEvents;
     const eventsQuery = maxEvents != null ? `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at DESC LIMIT ?` : `SELECT * FROM ${this.prefix}events WHERE entity_id = ? ORDER BY created_at ASC`;
@@ -1181,10 +1801,16 @@ The following document anchors are provided for contradiction detection only. Do
       this.db.getAllAsync(eventsQuery, eventsParams)
     ]);
     const facts = factsRaw.map((f) => {
-      const { embedding: _embedding, ...rest } = f;
+      const { embedding: _embedding, embedding_blob, ...rest } = f;
+      const safeBlobCopy = opts?.includeBlobs && embedding_blob ? (() => {
+        const c = new ArrayBuffer(embedding_blob.byteLength);
+        new Uint8Array(c).set(embedding_blob);
+        return new Uint8Array(c);
+      })() : void 0;
+      const factBase = safeBlobCopy ? { ...rest, embedding_blob: safeBlobCopy } : rest;
       return {
-        ...rest,
-        tags: typeof rest.tags === "string" ? JSON.parse(rest.tags) : rest.tags
+        ...factBase,
+        tags: typeof factBase.tags === "string" ? JSON.parse(factBase.tags) : factBase.tags
       };
     });
     const events = maxEvents != null ? eventsRaw.slice().reverse() : eventsRaw;
@@ -1211,7 +1837,7 @@ The following document anchors are provided for contradiction detection only. Do
     for (let i = 0; i < ids.length; i += BATCH) {
       const batch = ids.slice(i, i + BATCH);
       const batchResults = await Promise.all(
-        batch.map(async (id) => [id, await this._getFullBundle(id)])
+        batch.map(async (id) => [id, await this._getFullBundle(id, { includeBlobs: true })])
       );
       for (const [id, bundle] of batchResults) {
         entities[id] = bundle;
@@ -1221,172 +1847,406 @@ The following document anchors are provided for contradiction detection only. Do
   }
   async importDump(dump, opts) {
     const merge = opts?.merge ?? false;
-    for (const [entityId, bundle] of Object.entries(dump.entities)) {
-      await this.db.withTransactionAsync(async () => {
-        if (!merge) {
-          const now = Date.now();
-          await this.db.runAsync(
-            `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
-            [now, now, entityId]
-          );
-          await this.db.runAsync(
-            `UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
-            [now, now, entityId]
-          );
-          await this.db.runAsync(
-            `DELETE FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
-            [entityId]
-          );
+    const entityIds = Object.keys(dump.entities);
+    for (const entityId of entityIds) {
+      if (this.activeMaintenanceJobs.has(this._importKey(entityId))) {
+        throw new WikiBusyError("import", entityId);
+      }
+      if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) {
+        throw new WikiBusyError("librarian", entityId);
+      }
+      if (this.activeMaintenanceJobs.has(this._healKey(entityId))) {
+        throw new WikiBusyError("heal", entityId);
+      }
+      if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
+        throw new WikiBusyError("prune", entityId);
+      }
+      if (this._isReembedActive(entityId)) {
+        throw new WikiBusyError("reembed", entityId);
+      }
+      if (this._isIngestActiveFor(entityId)) {
+        throw new WikiBusyError("ingest", entityId);
+      }
+      if (this._isForgetActiveFor(entityId)) {
+        throw new WikiBusyError("forget", entityId);
+      }
+    }
+    if (this.activeMaintenanceJobs.has(this._globalImportKey())) {
+      throw new WikiBusyError("import", "*");
+    }
+    this.activeMaintenanceJobs.add(this._globalImportKey());
+    for (const entityId of entityIds) {
+      this.activeMaintenanceJobs.add(this._importKey(entityId));
+    }
+    try {
+      for (const [entityId, bundle] of Object.entries(dump.entities)) {
+        await this._doImportEntity(entityId, bundle, merge);
+      }
+    } finally {
+      this.activeMaintenanceJobs.delete(this._globalImportKey());
+      for (const entityId of entityIds) {
+        this.activeMaintenanceJobs.delete(this._importKey(entityId));
+      }
+    }
+  }
+  async _doImportEntity(entityId, bundle, merge) {
+    const upsertedFactIds = /* @__PURE__ */ new Set();
+    const upsertedDeletedFactIds = /* @__PURE__ */ new Set();
+    const factsWithPreservedBlob = /* @__PURE__ */ new Map();
+    const preservedBlobDims = /* @__PURE__ */ new Set();
+    const softDeletedFactIds = [];
+    await this.db.withTransactionAsync(async () => {
+      if (!merge) {
+        const toDelete = await this.db.getAllAsync(
+          `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
+          [entityId]
+        );
+        softDeletedFactIds.push(...toDelete.map((r) => r.id));
+        const now = Date.now();
+        await this.db.runAsync(
+          `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
+          [now, now, entityId]
+        );
+        await this.db.runAsync(
+          `UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`,
+          [now, now, entityId]
+        );
+        await this.db.runAsync(
+          `DELETE FROM ${this.prefix}checkpoints WHERE entity_id = ?`,
+          [entityId]
+        );
+      }
+      const factIds = bundle.facts.map((fact) => fact.id);
+      const existingFactsById = /* @__PURE__ */ new Map();
+      const factLookupChunkSize = 500;
+      for (let i = 0; i < factIds.length; i += factLookupChunkSize) {
+        const factIdChunk = factIds.slice(i, i + factLookupChunkSize);
+        if (factIdChunk.length === 0) continue;
+        const placeholders = factIdChunk.map(() => "?").join(", ");
+        const existingFacts = await this.db.getAllAsync(
+          `SELECT id, entity_id, updated_at FROM ${this.prefix}entries WHERE id IN (${placeholders})`,
+          factIdChunk
+        );
+        for (const existingFact of existingFacts) {
+          existingFactsById.set(existingFact.id, existingFact);
         }
-        const factIds = bundle.facts.map((fact) => fact.id);
-        const existingFactsById = /* @__PURE__ */ new Map();
-        const factLookupChunkSize = 500;
-        for (let i = 0; i < factIds.length; i += factLookupChunkSize) {
-          const factIdChunk = factIds.slice(i, i + factLookupChunkSize);
-          if (factIdChunk.length === 0) continue;
-          const placeholders = factIdChunk.map(() => "?").join(", ");
-          const existingFacts = await this.db.getAllAsync(
-            `SELECT id, entity_id, updated_at FROM ${this.prefix}entries WHERE id IN (${placeholders})`,
-            factIdChunk
-          );
-          for (const existingFact of existingFacts) {
-            existingFactsById.set(existingFact.id, existingFact);
+      }
+      for (const fact of bundle.facts) {
+        const tagsJson = JSON.stringify(Array.isArray(fact.tags) ? fact.tags : []);
+        const safeUpdatedAt = Number.isFinite(fact.updated_at) ? fact.updated_at : 0;
+        const existing = existingFactsById.get(fact.id);
+        const rawBlobRaw = fact.embedding_blob;
+        let rawBlob = null;
+        if (rawBlobRaw instanceof Uint8Array) {
+          rawBlob = rawBlobRaw;
+        } else if (rawBlobRaw !== null && rawBlobRaw !== void 0 && typeof rawBlobRaw === "object") {
+          const obj = rawBlobRaw;
+          if (obj["type"] === "Buffer" && Array.isArray(obj["data"])) {
+            rawBlob = new Uint8Array(obj["data"]);
+          } else if (!Array.isArray(rawBlobRaw)) {
+            const entries = Object.keys(obj);
+            if (entries.length > 0 && entries.every((k) => /^\d+$/.test(k))) {
+              const len = entries.length;
+              rawBlob = new Uint8Array(len);
+              for (let i = 0; i < len; i++) rawBlob[i] = obj[String(i)] ?? 0;
+            }
           }
         }
-        for (const fact of bundle.facts) {
-          const tagsJson = JSON.stringify(Array.isArray(fact.tags) ? fact.tags : []);
-          const safeUpdatedAt = Number.isFinite(fact.updated_at) ? fact.updated_at : 0;
-          const existing = existingFactsById.get(fact.id);
-          if (existing) {
-            if (existing.entity_id !== entityId) {
-              this._warnCrossEntityCollision("entry", fact.id, existing.entity_id, entityId);
-              continue;
-            }
-            if (merge) {
-              if (safeUpdatedAt <= existing.updated_at) continue;
+        let blobData = null;
+        if (rawBlob !== null && rawBlob.byteLength > 0 && rawBlob.byteLength % 4 === 0) {
+          const copy = new ArrayBuffer(rawBlob.byteLength);
+          const alignedBlob = new Uint8Array(copy);
+          alignedBlob.set(rawBlob);
+          const floats = new Float32Array(copy, 0, rawBlob.byteLength / 4);
+          let allFinite = true;
+          for (let i = 0; i < floats.length; i++) {
+            if (!isFinite(floats[i])) {
+              allFinite = false;
+              break;
             }
+          }
+          if (allFinite) {
+            blobData = alignedBlob;
+          }
+        }
+        if (existing) {
+          if (existing.entity_id !== entityId) {
+            this._warnCrossEntityCollision("entry", fact.id, existing.entity_id, entityId);
+            continue;
+          }
+          if (merge) {
+            if (safeUpdatedAt <= existing.updated_at) continue;
+          }
+          if (blobData != null) {
+            await this.db.runAsync(
+              `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ?, embedding_blob = ?, embedding = NULL WHERE id = ?`,
+              [entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData, fact.id]
+            );
+            factsWithPreservedBlob.set(fact.id, blobData);
+            if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
+          } else {
             await this.db.runAsync(
-              `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ? WHERE id = ?`,
+              `UPDATE ${this.prefix}entries SET entity_id = ?, title = ?, body = ?, tags = ?, confidence = ?, source_type = ?, source_hash = ?, source_ref = ?, created_at = ?, updated_at = ?, last_accessed_at = ?, access_count = ?, deleted_at = ?, embedding_blob = NULL, embedding = NULL WHERE id = ?`,
               [entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, fact.id]
             );
-            existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
+          }
+          existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
+          upsertedFactIds.add(fact.id);
+          if (fact.deleted_at) upsertedDeletedFactIds.add(fact.id);
+        } else {
+          if (blobData != null) {
+            await this.db.runAsync(
+              `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count, deleted_at, embedding_blob) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+              [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at, blobData]
+            );
+            factsWithPreservedBlob.set(fact.id, blobData);
+            if (!fact.deleted_at) preservedBlobDims.add(blobData.byteLength / 4);
           } else {
             await this.db.runAsync(
               `INSERT INTO ${this.prefix}entries (id, entity_id, title, body, tags, confidence, source_type, source_hash, source_ref, created_at, updated_at, last_accessed_at, access_count, deleted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
               [fact.id, entityId, fact.title, fact.body, tagsJson, fact.confidence, fact.source_type, fact.source_hash, fact.source_ref, fact.created_at, safeUpdatedAt, fact.last_accessed_at, fact.access_count, fact.deleted_at]
             );
-            existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
           }
+          existingFactsById.set(fact.id, { id: fact.id, entity_id: entityId, updated_at: safeUpdatedAt });
+          upsertedFactIds.add(fact.id);
+          if (fact.deleted_at) upsertedDeletedFactIds.add(fact.id);
         }
-        const taskIds = bundle.tasks.map((task) => task.id);
-        const existingTasksById = /* @__PURE__ */ new Map();
-        const taskLookupChunkSize = 500;
-        for (let i = 0; i < taskIds.length; i += taskLookupChunkSize) {
-          const taskIdChunk = taskIds.slice(i, i + taskLookupChunkSize);
-          if (taskIdChunk.length === 0) continue;
-          const placeholders = taskIdChunk.map(() => "?").join(", ");
-          const existingTasks = await this.db.getAllAsync(
-            `SELECT id, entity_id, updated_at FROM ${this.prefix}tasks WHERE id IN (${placeholders})`,
-            taskIdChunk
-          );
-          for (const existingTask of existingTasks) {
-            existingTasksById.set(existingTask.id, existingTask);
+      }
+      const taskIds = bundle.tasks.map((task) => task.id);
+      const existingTasksById = /* @__PURE__ */ new Map();
+      const taskLookupChunkSize = 500;
+      for (let i = 0; i < taskIds.length; i += taskLookupChunkSize) {
+        const taskIdChunk = taskIds.slice(i, i + taskLookupChunkSize);
+        if (taskIdChunk.length === 0) continue;
+        const placeholders = taskIdChunk.map(() => "?").join(", ");
+        const existingTasks = await this.db.getAllAsync(
+          `SELECT id, entity_id, updated_at FROM ${this.prefix}tasks WHERE id IN (${placeholders})`,
+          taskIdChunk
+        );
+        for (const existingTask of existingTasks) {
+          existingTasksById.set(existingTask.id, existingTask);
+        }
+      }
+      for (const task of bundle.tasks) {
+        const safeUpdatedAt = Number.isFinite(task.updated_at) ? task.updated_at : 0;
+        const existing = existingTasksById.get(task.id);
+        if (existing) {
+          if (existing.entity_id !== entityId) {
+            this._warnCrossEntityCollision("task", task.id, existing.entity_id, entityId);
+            continue;
+          }
+          if (merge) {
+            if (safeUpdatedAt <= existing.updated_at) continue;
           }
+          await this.db.runAsync(
+            `UPDATE ${this.prefix}tasks SET entity_id = ?, description = ?, status = ?, priority = ?, created_at = ?, updated_at = ?, resolved_at = ?, deleted_at = ? WHERE id = ?`,
+            [entityId, task.description, task.status, task.priority, task.created_at, safeUpdatedAt, task.resolved_at, task.deleted_at, task.id]
+          );
+          existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
+        } else {
+          await this.db.runAsync(
+            `INSERT INTO ${this.prefix}tasks (id, entity_id, description, status, priority, created_at, updated_at, resolved_at, deleted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            [task.id, entityId, task.description, task.status, task.priority, task.created_at, safeUpdatedAt, task.resolved_at, task.deleted_at]
+          );
+          existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
         }
-        for (const task of bundle.tasks) {
-          const safeUpdatedAt = Number.isFinite(task.updated_at) ? task.updated_at : 0;
-          const existing = existingTasksById.get(task.id);
-          if (existing) {
-            if (existing.entity_id !== entityId) {
-              this._warnCrossEntityCollision("task", task.id, existing.entity_id, entityId);
-              continue;
-            }
-            if (merge) {
-              if (safeUpdatedAt <= existing.updated_at) continue;
-            }
-            await this.db.runAsync(
-              `UPDATE ${this.prefix}tasks SET entity_id = ?, description = ?, status = ?, priority = ?, created_at = ?, updated_at = ?, resolved_at = ?, deleted_at = ? WHERE id = ?`,
-              [entityId, task.description, task.status, task.priority, task.created_at, safeUpdatedAt, task.resolved_at, task.deleted_at, task.id]
-            );
-            existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
-          } else {
+      }
+      for (const event of bundle.events) {
+        await this.db.runAsync(
+          `INSERT OR IGNORE INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
+             VALUES (?, ?, ?, ?, ?, ?)`,
+          [event.id, entityId, event.event_type, event.summary, event.related_entry_id ?? null, event.created_at]
+        );
+      }
+    });
+    this.vectorCache.delete(entityId);
+    await this.rebuildMiniSearchIndex(entityId);
+    for (const fact of bundle.facts) {
+      if (!fact.deleted_at && upsertedFactIds.has(fact.id) && !factsWithPreservedBlob.has(fact.id)) {
+        await this.embedFact({
+          id: fact.id,
+          entity_id: entityId,
+          // Use authoritative entityId from dump key, not fact.entity_id
+          title: fact.title,
+          body: fact.body,
+          tags: Array.isArray(fact.tags) || typeof fact.tags === "string" ? fact.tags : []
+        });
+      }
+    }
+    for (const fact of bundle.facts) {
+      const blobData = factsWithPreservedBlob.get(fact.id);
+      if (blobData && !fact.deleted_at && upsertedFactIds.has(fact.id)) {
+        try {
+          const float32Vector = new Float32Array(blobData.buffer, blobData.byteOffset, blobData.byteLength / 4);
+          await this._notifyEmbeddingPersisted(entityId, fact.id, float32Vector);
+        } catch (hookErr) {
+          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed for preserved-blob fact ${fact.id}:`, hookErr);
+        }
+      }
+    }
+    for (const factId of softDeletedFactIds) {
+      if (!upsertedFactIds.has(factId) || upsertedDeletedFactIds.has(factId)) {
+        try {
+          await this._notifyEmbeddingPersisted(entityId, factId, null);
+        } catch (hookErr) {
+          console.warn(`[WikiMemory] onEmbeddingPersisted(vector=null) hook failed for soft-deleted fact ${factId}:`, hookErr);
+        }
+      }
+    }
+    try {
+      const canonicalRow = await this.db.getFirstAsync(
+        `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension'`
+      );
+      const canonicalDim = canonicalRow ? parseInt(canonicalRow.value, 10) : null;
+      if (preservedBlobDims.size === 1) {
+        const preservedDim = [...preservedBlobDims][0];
+        if (canonicalDim === null || canonicalDim === preservedDim) {
+          await this.storeEmbeddingDimension(preservedDim);
+          const staleMismatch = await this.db.getFirstAsync(
+            `SELECT value FROM ${this.prefix}meta WHERE key = 'embedding_dimension_mismatch'`
+          );
+          if (staleMismatch && parseInt(staleMismatch.value, 10) !== preservedDim) {
             await this.db.runAsync(
-              `INSERT INTO ${this.prefix}tasks (id, entity_id, description, status, priority, created_at, updated_at, resolved_at, deleted_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-              [task.id, entityId, task.description, task.status, task.priority, task.created_at, safeUpdatedAt, task.resolved_at, task.deleted_at]
+              `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
+              [String(preservedDim)]
             );
-            existingTasksById.set(task.id, { id: task.id, entity_id: entityId, updated_at: safeUpdatedAt });
           }
-        }
-        for (const event of bundle.events) {
+          await this._reconcileEmbeddingDimension();
+        } else {
           await this.db.runAsync(
-            `INSERT OR IGNORE INTO ${this.prefix}events (id, entity_id, event_type, summary, related_entry_id, created_at)
-             VALUES (?, ?, ?, ?, ?, ?)`,
-            [event.id, entityId, event.event_type, event.summary, event.related_entry_id ?? null, event.created_at]
+            `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
+            [String(canonicalDim)]
           );
         }
-      });
-      for (const fact of bundle.facts) {
-        if (!fact.deleted_at) {
-          await this.embedFact({
-            id: fact.id,
-            title: fact.title,
-            body: fact.body,
-            tags: Array.isArray(fact.tags) || typeof fact.tags === "string" ? fact.tags : []
-          });
+      } else if (preservedBlobDims.size > 1) {
+        if (canonicalDim === null) {
+          const sortedPreservedBlobDims = [...preservedBlobDims].sort((a, b) => a - b);
+          await this.storeEmbeddingDimension(sortedPreservedBlobDims[0]);
+          await this.db.runAsync(
+            `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
+            [String(sortedPreservedBlobDims[0])]
+          );
+        } else {
+          await this.db.runAsync(
+            `INSERT OR REPLACE INTO ${this.prefix}meta (key, value) VALUES ('embedding_dimension_mismatch', ?)`,
+            [String(canonicalDim)]
+          );
         }
       }
+    } finally {
+      this.vectorCache.delete(entityId);
     }
-    await this.rebuildMiniSearchIndex();
   }
   async forget(entityId, params) {
-    const now = Date.now();
-    let deletedEntries = 0;
-    let deletedTasks = 0;
-    if (params.clearAll) {
-      const [entriesRes, tasksRes] = await Promise.all([
-        this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId]),
-        this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId])
-      ]);
-      await this.db.runAsync(`UPDATE ${this.prefix}checkpoints SET memory_checkpoint = 0, heal_checkpoint = 0 WHERE entity_id = ?`, [entityId]);
-      deletedEntries = entriesRes.changes;
-      deletedTasks = tasksRes.changes;
-    } else {
-      const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
-      const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
-      if (hasIdSelectors && hasSourceSelectors) {
-        throw new Error("forget() params are mutually exclusive: use entryId/taskId together, or sourceRef/sourceHash together, but not both in the same call");
-      }
-      const sourceRef = params.sourceRef !== void 0 ? normalizeSourceRef(params.sourceRef) : null;
-      if (params.sourceRef !== void 0 && !sourceRef) throw new Error("Invalid sourceRef");
-      const sourceHash = params.sourceHash !== void 0 ? normalizeSourceHash(params.sourceHash) : null;
-      if (params.sourceHash !== void 0 && !sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
-      const entryPromise = params.entryId ? this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.entryId, entityId]) : null;
-      const taskPromise = params.taskId ? this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.taskId, entityId]) : null;
-      let refPromise = null;
-      if (sourceRef || sourceHash) {
-        let q = `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`;
-        const args = [now, now, entityId];
-        if (sourceRef) {
-          q += ` AND source_ref = ?`;
-          args.push(sourceRef);
+    let blockingOperation = null;
+    if (this.activeMaintenanceJobs.has(this._librarianKey(entityId))) {
+      blockingOperation = "librarian";
+    } else if (this.activeMaintenanceJobs.has(this._healKey(entityId))) {
+      blockingOperation = "heal";
+    } else if (this.activeMaintenanceJobs.has(this._pruneKey(entityId))) {
+      blockingOperation = "prune";
+    } else if (this._isReembedActive(entityId)) {
+      blockingOperation = "reembed";
+    } else if (this._isIngestActiveFor(entityId)) {
+      blockingOperation = "ingest";
+    } else if (this._isImportActiveFor(entityId)) {
+      blockingOperation = "import";
+    } else if (this._isForgetActiveFor(entityId)) {
+      blockingOperation = "forget";
+    }
+    if (blockingOperation !== null) {
+      throw new WikiBusyError(blockingOperation, entityId);
+    }
+    const forgetKey = this._forgetKey(entityId);
+    this.activeMaintenanceJobs.add(forgetKey);
+    try {
+      const now = Date.now();
+      let deletedEntries = 0;
+      let deletedTasks = 0;
+      const deletedEntryIds = [];
+      if (params.clearAll) {
+        const entriesToDelete = await this.db.getAllAsync(
+          `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`,
+          [entityId]
+        );
+        deletedEntryIds.push(...entriesToDelete.map((e) => e.id));
+        const [entriesRes, tasksRes] = await Promise.all([
+          this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId]),
+          this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`, [now, now, entityId])
+        ]);
+        await this.db.runAsync(`UPDATE ${this.prefix}checkpoints SET memory_checkpoint = 0, heal_checkpoint = 0 WHERE entity_id = ?`, [entityId]);
+        deletedEntries = entriesRes.changes;
+        deletedTasks = tasksRes.changes;
+      } else {
+        const hasIdSelectors = params.entryId !== void 0 || params.taskId !== void 0;
+        const hasSourceSelectors = params.sourceRef !== void 0 || params.sourceHash !== void 0;
+        if (hasIdSelectors && hasSourceSelectors) {
+          throw new Error("forget() params are mutually exclusive: use entryId/taskId together, or sourceRef/sourceHash together, but not both in the same call");
         }
-        if (sourceHash) {
-          q += ` AND source_hash = ?`;
-          args.push(sourceHash);
+        const sourceRef = params.sourceRef !== void 0 ? normalizeSourceRef(params.sourceRef) : null;
+        if (params.sourceRef !== void 0 && !sourceRef) throw new Error("Invalid sourceRef");
+        const sourceHash = params.sourceHash !== void 0 ? normalizeSourceHash(params.sourceHash) : null;
+        if (params.sourceHash !== void 0 && !sourceHash) throw new Error("Invalid sourceHash (must be 64-char hex string)");
+        if (params.entryId) {
+          const entry = await this.db.getFirstAsync(
+            `SELECT id FROM ${this.prefix}entries WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`,
+            [params.entryId, entityId]
+          );
+          if (entry) deletedEntryIds.push(entry.id);
+        }
+        if (sourceRef || sourceHash) {
+          let q = `SELECT id FROM ${this.prefix}entries WHERE entity_id = ? AND deleted_at IS NULL`;
+          const args = [entityId];
+          if (sourceRef) {
+            q += ` AND source_ref = ?`;
+            args.push(sourceRef);
+          }
+          if (sourceHash) {
+            q += ` AND source_hash = ?`;
+            args.push(sourceHash);
+          }
+          const entriesToDelete = await this.db.getAllAsync(q, args);
+          deletedEntryIds.push(...entriesToDelete.map((e) => e.id));
+        }
+        const entryPromise = params.entryId ? this.db.runAsync(`UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.entryId, entityId]) : null;
+        const taskPromise = params.taskId ? this.db.runAsync(`UPDATE ${this.prefix}tasks SET deleted_at = ?, updated_at = ? WHERE id = ? AND entity_id = ? AND deleted_at IS NULL`, [now, now, params.taskId, entityId]) : null;
+        let refPromise = null;
+        if (sourceRef || sourceHash) {
+          let q = `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE entity_id = ? AND deleted_at IS NULL`;
+          const args = [now, now, entityId];
+          if (sourceRef) {
+            q += ` AND source_ref = ?`;
+            args.push(sourceRef);
+          }
+          if (sourceHash) {
+            q += ` AND source_hash = ?`;
+            args.push(sourceHash);
+          }
+          refPromise = this.db.runAsync(q, args);
         }
-        refPromise = this.db.runAsync(q, args);
+        const [entryResult, taskResult, refResult] = await Promise.all([
+          entryPromise ?? Promise.resolve(null),
+          taskPromise ?? Promise.resolve(null),
+          refPromise ?? Promise.resolve(null)
+        ]);
+        if (entryResult) deletedEntries += entryResult.changes;
+        if (taskResult) deletedTasks += taskResult.changes;
+        if (refResult) deletedEntries += refResult.changes;
       }
-      const [entryResult, taskResult, refResult] = await Promise.all([
-        entryPromise ?? Promise.resolve(null),
-        taskPromise ?? Promise.resolve(null),
-        refPromise ?? Promise.resolve(null)
-      ]);
-      if (entryResult) deletedEntries += entryResult.changes;
-      if (taskResult) deletedTasks += taskResult.changes;
-      if (refResult) deletedEntries += refResult.changes;
+      await this.rebuildMiniSearchIndex(entityId);
+      this.vectorCache.delete(entityId);
+      const uniqueDeletedIds = Array.from(new Set(deletedEntryIds));
+      for (const factId of uniqueDeletedIds) {
+        try {
+          await this._notifyEmbeddingPersisted(entityId, factId, null);
+        } catch (hookErr) {
+          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during forget for ${factId}:`, hookErr);
+        }
+      }
+      return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
+    } finally {
+      this.activeMaintenanceJobs.delete(forgetKey);
     }
-    await this.rebuildMiniSearchIndex(entityId);
-    return { deleted: { entries: deletedEntries, tasks: deletedTasks } };
   }
   async ingestDocument(entityId, params) {
     const sourceRef = normalizeSourceRef(params.sourceRef);
@@ -1414,6 +2274,12 @@ The following document anchors are provided for contradiction detection only. Do
     if (this._isReembedActive(entityId)) {
       throw new WikiBusyError("reembed", entityId);
     }
+    if (this._isImportActiveFor(entityId)) {
+      throw new WikiBusyError("import", entityId);
+    }
+    if (this._isForgetActiveFor(entityId)) {
+      throw new WikiBusyError("forget", entityId);
+    }
     this.activeIngestJobs.add(jobKey);
     try {
       const { chunks, truncated } = chunkText(params.documentChunk, maxChunkLength, chunkOverlap);
@@ -1446,7 +2312,15 @@ ${chunk}`;
       }
       const now = Date.now();
       const insertedFacts = [];
+      const deletedSourceFactIds = [];
       await this.db.withTransactionAsync(async () => {
+        const existingSourceFacts = await this.db.getAllAsync(
+          `SELECT id FROM ${this.prefix}entries WHERE source_ref = ? AND entity_id = ? AND deleted_at IS NULL`,
+          [sourceRef, entityId]
+        );
+        for (const row of existingSourceFacts) {
+          deletedSourceFactIds.push(row.id);
+        }
         await this.db.runAsync(
           `UPDATE ${this.prefix}entries SET deleted_at = ?, updated_at = ? WHERE source_ref = ? AND entity_id = ? AND deleted_at IS NULL`,
           [now, now, sourceRef, entityId]
@@ -1458,19 +2332,42 @@ ${chunk}`;
            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
             [id, entityId, fact.title, fact.body, JSON.stringify(fact.tags), fact.confidence, "user_document", sourceHash, sourceRef, now, now]
           );
-          insertedFacts.push({ id, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
+          insertedFacts.push({ id, entity_id: entityId, title: fact.title, body: fact.body, tags: JSON.stringify(fact.tags) });
         }
       });
+      await this.rebuildMiniSearchIndex(entityId);
+      this.vectorCache.delete(entityId);
+      const uniqueDeletedSourceFactIds = Array.from(new Set(deletedSourceFactIds));
+      for (const factId of uniqueDeletedSourceFactIds) {
+        try {
+          await this._notifyEmbeddingPersisted(entityId, factId, null);
+        } catch (hookErr) {
+          console.warn(`[WikiMemory] onEmbeddingPersisted hook failed during ingest for ${factId}:`, hookErr);
+        }
+      }
       for (const fact of insertedFacts) {
         await this.embedFact(fact);
       }
-      await this.rebuildMiniSearchIndex(entityId);
+      this.vectorCache.delete(entityId);
       return { truncated, chunks: chunks.length };
     } finally {
       this.activeIngestJobs.delete(jobKey);
     }
   }
 };
+/**
+ * Maximum number of entities whose parsed embedding vectors are held in
+ * memory. This cap is intentionally conservative so the cache remains safe
+ * on memory-constrained runtimes (e.g., mobile/Expo).
+ */
+_WikiMemory.MAX_VECTOR_CACHE_ENTITIES = 16;
+/**
+ * Maximum number of fact vectors cached per entity. Keep this high enough to
+ * preserve the parsed-embedding reuse optimization for common mid-sized
+ * entities while still maintaining a bounded memory footprint.
+ */
+_WikiMemory.MAX_VECTOR_CACHE_FACTS_PER_ENTITY = 500;
+var WikiMemory = _WikiMemory;
 
 // src/utils/formatContext.ts
 function validateMaxOption(value, name) {
@@ -1666,8 +2563,23 @@ function formatMemoryDump(dump) {
     name: formatEntityFileName(entityId),
     content: renderEntity(entityId, bundle, dump.generatedAt)
   }));
+  const manifestDump = {
+    generatedAt: dump.generatedAt,
+    entities: Object.fromEntries(
+      Object.entries(dump.entities).map(([entityId, bundle]) => [
+        entityId,
+        {
+          ...bundle,
+          facts: bundle.facts.map((f) => {
+            const { embedding_blob: _blob, ...rest } = f;
+            return rest;
+          })
+        }
+      ])
+    )
+  };
   return {
-    manifest: JSON.stringify(dump, null, 2),
+    manifest: JSON.stringify(manifestDump, null, 2),
     files
   };
 }