@amemhq/core 1.0.1 → 2.0.0

package/dist/index.cjs

@@ -33,6 +33,11 @@ __export(index_exports, {
   DEFAULT_CRUD_UPDATE_MIN_SIM: () => DEFAULT_CRUD_UPDATE_MIN_SIM,
   DEFAULT_EMBEDDING_MODEL: () => DEFAULT_EMBEDDING_MODEL,
   EmbeddingDimensionMismatchError: () => EmbeddingDimensionMismatchError,
+  EmbeddingModelMismatchError: () => EmbeddingModelMismatchError,
+  LEGACY_DEFAULT_DIM: () => LEGACY_DEFAULT_DIM,
+  LEGACY_DEFAULT_EMBEDDING_MODEL: () => LEGACY_DEFAULT_EMBEDDING_MODEL,
+  MixedEmbeddingModelsError: () => MixedEmbeddingModelsError,
+  SYSTEM_ACTOR: () => SYSTEM_ACTOR,
   addEpisodic: () => addEpisodic,
   addMemory: () => addMemory,
   canRead: () => canRead,
@@ -47,7 +52,9 @@ __export(index_exports, {
   encode: () => encode,
   ensureCollection: () => ensureCollection,
   generateReviewBatch: () => generateReviewBatch,
+  getEmbeddingDevice: () => getEmbeddingDevice,
   getEmbeddingDim: () => getEmbeddingDim,
+  getEmbeddingDtype: () => getEmbeddingDtype,
   getEmbeddingModel: () => getEmbeddingModel,
   getEmbeddingPooling: () => getEmbeddingPooling,
   getNote: () => getNote,
@@ -65,6 +72,7 @@ __export(index_exports, {
   resolveCrudUpdateMinSim: () => resolveCrudUpdateMinSim,
   scanLowQuality: () => scanLowQuality,
   searchMemory: () => searchMemory,
+  switchToMigrated: () => switchToMigrated,
   updateNote: () => updateNote
 });
 module.exports = __toCommonJS(index_exports);
@@ -83,11 +91,25 @@ function getDataDir() {
 // src/embedding.ts
 var pipeline = null;
 var extractor = null;
-var loadedModelName = null;
+var loadedKey = null;
 var cachedDim = null;
-var DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+var DEFAULT_EMBEDDING_MODEL = "Xenova/bge-m3";
+var LEGACY_DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+var LEGACY_DEFAULT_DIM = 384;
+var DEFAULT_MODEL_DTYPE = "fp16";
+var pinnedModel = null;
+function pinEmbeddingModel(model) {
+  if (pinnedModel === model) return;
+  pinnedModel = model;
+  extractor = null;
+  loadedKey = null;
+  cachedDim = null;
+}
+function getPinnedEmbeddingModel() {
+  return pinnedModel;
+}
 function getEmbeddingModel() {
-  return process.env.AMEM_EMBED_MODEL?.trim() || DEFAULT_EMBEDDING_MODEL;
+  return process.env.AMEM_EMBED_MODEL?.trim() || pinnedModel || DEFAULT_EMBEDDING_MODEL;
 }
 var CLS_POOLED_MODELS = /* @__PURE__ */ new Set([
   "bge-m3",
@@ -108,22 +130,39 @@ function getEmbeddingPooling() {
   const basename2 = getEmbeddingModel().split("/").pop()?.toLowerCase() ?? "";
   return CLS_POOLED_MODELS.has(basename2) ? "cls" : "mean";
 }
+function getEmbeddingDevice() {
+  return process.env.AMEM_EMBED_DEVICE?.trim() || void 0;
+}
+function getEmbeddingDtype() {
+  const explicit = process.env.AMEM_EMBED_DTYPE?.trim();
+  if (explicit) return explicit;
+  return getEmbeddingModel() === DEFAULT_EMBEDDING_MODEL ? DEFAULT_MODEL_DTYPE : void 0;
+}
+function extractorKey() {
+  return `${getEmbeddingModel()}|${getEmbeddingDevice() ?? ""}|${getEmbeddingDtype() ?? ""}`;
+}
 async function getExtractor() {
-  const wanted = getEmbeddingModel();
-  if (extractor && loadedModelName === wanted) return extractor;
+  const wanted = extractorKey();
+  if (extractor && loadedKey === wanted) return extractor;
   if (!pipeline) {
     const mod = await import("@huggingface/transformers");
     pipeline = mod.pipeline;
   }
-  extractor = await pipeline("feature-extraction", wanted, {
-    revision: "main"
+  const device = getEmbeddingDevice();
+  const dtype = getEmbeddingDtype();
+  extractor = await pipeline("feature-extraction", getEmbeddingModel(), {
+    revision: "main",
+    // Omitted entirely when unset, so an unconfigured install gets exactly the
+    // library defaults it got before these existed.
+    ...device ? { device } : {},
+    ...dtype ? { dtype } : {}
   });
-  loadedModelName = wanted;
+  loadedKey = wanted;
   cachedDim = null;
   return extractor;
 }
 async function getEmbeddingDim() {
-  if (cachedDim !== null && loadedModelName === getEmbeddingModel()) return cachedDim;
+  if (cachedDim !== null && loadedKey === extractorKey()) return cachedDim;
   const probe = await encode("dimension probe");
   cachedDim = probe.length;
   return cachedDim;
@@ -194,6 +233,7 @@ var fs2 = __toESM(require("fs"), 1);
 var path3 = __toESM(require("path"), 1);
 
 // src/auth.ts
+var SYSTEM_ACTOR = "__amem_system__";
 function canWrite(note, callerAgentId) {
   return note.owner === callerAgentId || note.writers.includes(callerAgentId) || note.writers.includes("*");
 }
@@ -208,7 +248,7 @@ var EmbeddingDimensionMismatchError = class extends Error {
   constructor(collection, collectionDim, modelDim, model) {
     super(
       `Collection "${collection}" stores ${collectionDim}-dimension vectors, but the embedding model "${model}" produces ${modelDim}. Qdrant fixes a collection's vector size at creation and cannot change it, so writes and searches would both fail.
-Either set AMEM_EMBED_MODEL back to the model this collection was built with, or migrate: build a new collection with the new model, backfill it, then point AMEM_COLLECTION at it. See docs/reference/embedding-models.md.`
+Either set AMEM_EMBED_MODEL back to the model this collection was built with, or ${migrationHint(collection, model)}`
     );
     this.collection = collection;
     this.collectionDim = collectionDim;
@@ -221,6 +261,54 @@ Either set AMEM_EMBED_MODEL back to the model this collection was built with, or
   modelDim;
   model;
 };
+function migrationHint(collection, targetModel) {
+  return `migrate onto it:
+
+  AMEM_EMBED_MODEL=${targetModel} \\
+    npx --package=@amemhq/core amem-migrate --from-collection ${collection}
+
+That only reports; it takes --apply to write anything, and "${collection}" is read either way. The new store ends up behind the name you already use, so there is nothing to change in your config afterwards. See https://amem.owo.lc/reference/embedding-models.`;
+}
+var EmbeddingModelMismatchError = class extends Error {
+  constructor(collection, collectionModel, configuredModel) {
+    super(
+      `Collection "${collection}" was built with the embedding model "${collectionModel}", but this process is configured for "${configuredModel}". Both produce vectors of the same width, so nothing would fail \u2014 searches would just quietly compare vectors from two different models.
+Either set AMEM_EMBED_MODEL back to "${collectionModel}", or ` + migrationHint(collection, configuredModel)
+    );
+    this.collection = collection;
+    this.collectionModel = collectionModel;
+    this.configuredModel = configuredModel;
+    this.name = "EmbeddingModelMismatchError";
+  }
+  collection;
+  collectionModel;
+  configuredModel;
+};
+var MixedEmbeddingModelsError = class extends Error {
+  constructor(collection, wanted, inUse) {
+    super(
+      `Collection "${collection}" was built with "${wanted}", but this process is already embedding with "${inUse}" for another collection. One process can only use one model.
+Migrate the remaining collections so they all agree:
+
+  npx --package=@amemhq/core amem-migrate --from-collection ${collection}
+
+Or set AMEM_EMBED_MODEL to pin every collection to one model, which is only correct if they really were all built with it.`
+    );
+    this.collection = collection;
+    this.wanted = wanted;
+    this.inUse = inUse;
+    this.name = "MixedEmbeddingModelsError";
+  }
+  collection;
+  wanted;
+  inUse;
+};
+async function recordCollectionModel(collection, model) {
+  try {
+    await qdrant("PATCH", `/collections/${collection}`, { metadata: { embedding_model: model } });
+  } catch {
+  }
+}
 async function qdrant(method, path5, body) {
   const res = await fetch(`${QDRANT_URL}${path5}`, {
     method,
@@ -257,12 +345,40 @@ async function ensureCollection(collectionName) {
   }
   if (existing) {
     const collectionDim = existing.config?.params?.vectors?.size;
+    const recorded = existing.config?.metadata?.embedding_model;
+    const explicit = process.env.AMEM_EMBED_MODEL?.trim();
+    const inferLegacy = !explicit && recorded === void 0 && collectionDim === LEGACY_DEFAULT_DIM;
+    if (!explicit) {
+      const wanted = (
+        // The collection says what built it, which outranks whatever the shipped
+        // default happens to be today. This is what keeps changing the default
+        // from breaking every install that already has data.
+        typeof recorded === "string" ? recorded : inferLegacy ? LEGACY_DEFAULT_EMBEDDING_MODEL : DEFAULT_EMBEDDING_MODEL
+      );
+      const inUse = getPinnedEmbeddingModel();
+      if (inUse !== null && inUse !== wanted) throw new MixedEmbeddingModelsError(col, wanted, inUse);
+      pinEmbeddingModel(wanted);
+      if (wanted === LEGACY_DEFAULT_EMBEDDING_MODEL) {
+        console.warn(
+          `[amem] "${col}" is on ${LEGACY_DEFAULT_EMBEDDING_MODEL} (${LEGACY_DEFAULT_DIM}-dim).
+[amem] ${DEFAULT_EMBEDDING_MODEL} reads 8192 tokens where that one stops at 128, so anything longer is being truncated before it reaches the vector.
+[amem] To move: npx --package=@amemhq/core amem-migrate --from-collection ${col}`
+        );
+      }
+    }
     if (typeof collectionDim === "number") {
       const modelDim = await getEmbeddingDim();
       if (collectionDim !== modelDim) {
         throw new EmbeddingDimensionMismatchError(col, collectionDim, modelDim, getEmbeddingModel());
       }
     }
+    const current = getEmbeddingModel();
+    if (typeof recorded === "string" && recorded !== current) {
+      throw new EmbeddingModelMismatchError(col, recorded, current);
+    }
+    if (recorded === void 0 && !inferLegacy) {
+      await recordCollectionModel(col, current);
+    }
     markReady();
     return;
   }
@@ -274,6 +390,9 @@ async function ensureCollection(collectionName) {
   } catch (err) {
     if (!(err instanceof Error) || !err.message.includes("already exists")) throw err;
   }
+  const created = getEmbeddingModel();
+  await recordCollectionModel(col, created);
+  if (!process.env.AMEM_EMBED_MODEL?.trim()) pinEmbeddingModel(created);
   await qdrant("PUT", `/collections/${col}/index`, {
     field_name: "agent_id",
     field_schema: "keyword"
@@ -319,6 +438,7 @@ async function collectionDimRaw(collection) {
 }
 async function createCollectionRaw(collection, size) {
   await qdrant("PUT", `/collections/${collection}`, { vectors: { size, distance: "Cosine" } });
+  await recordCollectionModel(collection, getEmbeddingModel());
   for (const field_name of ["agent_id", "hash", "topics", "subjects"]) {
     await qdrant("PUT", `/collections/${collection}/index`, { field_name, field_schema: "keyword" });
   }
@@ -326,6 +446,43 @@ async function createCollectionRaw(collection, size) {
 async function upsertPointsRaw(collection, points) {
   await qdrant("PUT", `/collections/${collection}/points?wait=true`, { points });
 }
+async function scrollIdsRaw(collection, limit = 1e4) {
+  const ids = /* @__PURE__ */ new Set();
+  let offset = void 0;
+  for (; ; ) {
+    const body = { with_payload: false, with_vector: false, limit };
+    if (offset !== void 0 && offset !== null) body.offset = offset;
+    const res = await qdrant("POST", `/collections/${collection}/points/scroll`, body);
+    for (const p of res.points) ids.add(String(p.id));
+    offset = res.next_page_offset;
+    if (offset === void 0 || offset === null || res.points.length === 0) break;
+  }
+  return ids;
+}
+async function deleteCollectionRaw(collection) {
+  await qdrant("DELETE", `/collections/${collection}`);
+}
+async function resolveAliasRaw(alias) {
+  try {
+    const res = await qdrant("GET", `/aliases`);
+    return res.aliases.find((a) => a.alias_name === alias)?.collection_name ?? null;
+  } catch {
+    return null;
+  }
+}
+async function createAliasRaw(alias, collection) {
+  await qdrant("POST", `/collections/aliases`, {
+    actions: [{ create_alias: { collection_name: collection, alias_name: alias } }]
+  });
+}
+async function setAliasRaw(alias, collection) {
+  await qdrant("POST", `/collections/aliases`, {
+    actions: [
+      { delete_alias: { alias_name: alias } },
+      { create_alias: { collection_name: collection, alias_name: alias } }
+    ]
+  });
+}
 function noteToPoint(note) {
   return {
     id: note.id,
@@ -470,12 +627,15 @@ function makeCrud(collectionName, modeBIsolated = false) {
     },
     /**
      * Story 36: this is the one read that bypasses the agent filter — it fetches
-     * straight by UUID. Pass `readerAgentId` to enforce `readers`; an unreadable
-     * note comes back as `null` (indistinguishable from missing, so nothing leaks,
-     * and callers already handle null). Omitting it skips the check, preserving
-     * behaviour for internal callers that only ever hold their own ids.
+     * straight by UUID. An unreadable note comes back as `null`, indistinguishable
+     * from missing, so nothing leaks and callers already handle it.
+     *
+     * `reader` is required. It used to be optional, and omitting it skipped the
+     * check — which meant the safe behaviour was the one you had to remember to
+     * ask for. Pass `SYSTEM_ACTOR` to read as the engine itself; that reads as a
+     * deliberate act at the call site, where an absent argument did not.
      */
-    async getNote(id, readerAgentId) {
+    async getNote(id, reader) {
       await ensureCollection(col);
       try {
         const result = await qdrant("POST", `/collections/${col}/points`, {
@@ -485,7 +645,7 @@ function makeCrud(collectionName, modeBIsolated = false) {
         });
         if (!result.length) return null;
         const note = pointToNote(result[0]);
-        if (readerAgentId !== void 0 && !canRead(note, readerAgentId)) return null;
+        if (reader !== SYSTEM_ACTOR && !canRead(note, reader)) return null;
         return note;
       } catch {
         return null;
@@ -523,19 +683,22 @@ function makeCrud(collectionName, modeBIsolated = false) {
       return pointToNote(result.points[0]);
     },
     /**
-     * Story 33: pass `callerAgentId` to enforce the writers policy. Callers that
-     * hold the note already should prefer checking `canWrite` themselves; this
-     * fetch-then-check path exists for callers that only have an id (the plugin's
-     * CRUD hook). Returns false — without writing — when the caller may not write.
-     * Omitting `callerAgentId` skips the check, preserving existing behaviour for
-     * internal callers that are already scoped to their own notes.
+     * Story 33: enforces the writers policy. Returns false — without writing —
+     * when the caller may not write. This fetch-then-check path exists for callers
+     * that only have an id (the plugin's CRUD hook); callers already holding the
+     * note can check `canWrite` themselves and skip a round trip.
+     *
+     * `caller` is required. Pass `SYSTEM_ACTOR` for the engine's own maintenance
+     * writes. The self-read below is a genuine `SYSTEM_ACTOR` case: it fetches the
+     * note in order to decide whether the caller may write it, and gating that
+     * fetch on the same policy it exists to evaluate would be circular.
      */
-    async updateNoteContent(id, content, embedding, hash, callerAgentId) {
+    async updateNoteContent(id, content, embedding, hash, caller) {
       await ensureCollection(col);
       let existing = null;
-      if (callerAgentId !== void 0) {
-        existing = await this.getNote(id);
-        if (existing && !canWrite(existing, callerAgentId)) return false;
+      if (caller !== SYSTEM_ACTOR) {
+        existing = await this.getNote(id, SYSTEM_ACTOR);
+        if (existing && !canWrite(existing, caller)) return false;
       }
       await qdrant("PUT", `/collections/${col}/points/vectors?wait=true`, {
         points: [{ id, vector: embedding }]
@@ -623,11 +786,11 @@ function makeCrud(collectionName, modeBIsolated = false) {
       });
     },
     /** Story 33: see `updateNoteContent` — returns false, unwritten, when denied. */
-    async invalidateNote(id, callerAgentId) {
+    async invalidateNote(id, caller) {
       await ensureCollection(col);
-      if (callerAgentId !== void 0) {
-        const existing = await this.getNote(id);
-        if (existing && !canWrite(existing, callerAgentId)) return false;
+      if (caller !== SYSTEM_ACTOR) {
+        const existing = await this.getNote(id, SYSTEM_ACTOR);
+        if (existing && !canWrite(existing, caller)) return false;
       }
       await qdrant("POST", `/collections/${col}/points/payload?wait=true`, {
         payload: { is_active: false },
@@ -693,8 +856,8 @@ function makeCrud(collectionName, modeBIsolated = false) {
 function createStorageContext(collectionName, modeBIsolated = false) {
   return makeCrud(collectionName || getCollection(), modeBIsolated);
 }
-async function getNote(id, readerAgentId) {
-  return makeCrud(getCollection()).getNote(id, readerAgentId);
+async function getNote(id, reader) {
+  return makeCrud(getCollection()).getNote(id, reader);
 }
 async function updateNote(note) {
   return makeCrud(getCollection()).updateNote(note);
@@ -705,8 +868,8 @@ async function listNotes(agentId, subject) {
 async function deleteNote(id) {
   return makeCrud(getCollection()).deleteNote(id);
 }
-async function invalidateNote(id, callerAgentId) {
-  return makeCrud(getCollection()).invalidateNote(id, callerAgentId);
+async function invalidateNote(id, caller) {
+  return makeCrud(getCollection()).invalidateNote(id, caller);
 }
 async function patchNotePayload(id, fields) {
   return makeCrud(getCollection()).patchNotePayload(id, fields);
@@ -1458,7 +1621,7 @@ async function addMemory(content, agentId = "main", opts) {
   if (topMatch.length > 0 && topMatch[0].score >= 0.85) {
     if (canWrite(topMatch[0].note, agentId)) {
       console.log(`[add] dedup: high-sim match (sim=${topMatch[0].score.toFixed(3)}), updating existing`);
-      await ctx.updateNoteContent(topMatch[0].note.id, content, embedding, hash);
+      await ctx.updateNoteContent(topMatch[0].note.id, content, embedding, hash, agentId);
       return topMatch[0].note.id;
     }
     console.log(
@@ -1530,7 +1693,7 @@ async function addMemory(content, agentId = "main", opts) {
         note.links = linkedIds;
         await ctx.updateNote(note);
         for (const lid of linkedIds) {
-          const linked = await ctx.getNote(lid);
+          const linked = await ctx.getNote(lid, agentId);
           if (linked && !linked.links.includes(note.id)) {
             if (!canWrite(linked, agentId)) {
               console.log(`[link] back-link into ${lid.slice(0, 8)} skipped \u2014 not writable by ${logSafe(agentId)}`);
@@ -1543,7 +1706,7 @@ async function addMemory(content, agentId = "main", opts) {
         if (shouldRunEvolution()) {
           console.log(`  [evo] threshold reached, running evolution for ${Math.min(linkedIds.length, 3)} linked notes`);
           for (const lid of linkedIds.slice(0, 3)) {
-            const linked = await ctx.getNote(lid);
+            const linked = await ctx.getNote(lid, agentId);
             if (!linked) continue;
             if (!canWrite(linked, agentId)) {
               console.log(`  [evo] skipping ${lid.slice(0, 8)} \u2014 not writable by ${logSafe(agentId)}`);
@@ -1696,7 +1859,7 @@ async function searchMemory(query, topK = 5, agentId = "main", opts) {
   const allNotes = await ctx.listNotes(agentId, subject);
   const bm25State = buildBM25(allNotes);
   const queryTokens = simpleTokenize(query);
-  const bm25Ranked = bm25Score(bm25State, queryTokens).slice(0, n);
+  const bm25Ranked = bm25Score(bm25State, queryTokens).filter(([, score]) => score > 0).slice(0, n);
   const merged = rrfMerge(
     embResults.map((r) => r.note.id),
     bm25Ranked.map((r) => r[0])
@@ -1719,6 +1882,7 @@ async function searchMemory(query, topK = 5, agentId = "main", opts) {
   const visitedIds = new Set(topIds);
   const bfsQueue = useBfs ? topIds.map((id) => ({ id, hop: 0 })) : [];
   const bfsExtra = [];
+  const bfsSimMap = /* @__PURE__ */ new Map();
   while (bfsQueue.length > 0 && bfsExtra.length < BFS_MAX_EXPAND) {
     const item = bfsQueue.shift();
     if (item.hop >= BFS_MAX_HOPS) continue;
@@ -1729,10 +1893,9 @@ async function searchMemory(query, topK = 5, agentId = "main", opts) {
       visitedIds.add(linkedId);
       const linked = noteMap.get(linkedId);
       if (!linked || linked.is_active === false) continue;
-      if (bfsSimThreshold > 0 && linked.embedding) {
-        const sim = cosineSimilarity(queryEmbedding, linked.embedding);
-        if (sim < bfsSimThreshold) continue;
-      }
+      const sim = cosineSimilarity(queryEmbedding, linked.embedding);
+      if (bfsSimThreshold > 0 && sim < bfsSimThreshold) continue;
+      bfsSimMap.set(linkedId, sim);
       bfsExtra.push(linkedId);
       bfsQueue.push({ id: linkedId, hop: item.hop + 1 });
       if (bfsExtra.length >= BFS_MAX_EXPAND) break;
@@ -1748,7 +1911,11 @@ async function searchMemory(query, topK = 5, agentId = "main", opts) {
   const embSimMap = new Map(embResults.map((r) => [r.note.id, r.score]));
   const rrfMap = new Map(boostedMerged.map(([id, score]) => [id, score]));
   const results = [];
-  for (const id of [...filteredTopIds, ...bfsExtra]) {
+  const ordered = [
+    ...filteredTopIds.map((id) => [id, "match"]),
+    ...bfsExtra.map((id) => [id, "link"])
+  ];
+  for (const [id, via] of ordered) {
     const note = noteMap.get(id);
     if (!note) continue;
     results.push({
@@ -1759,8 +1926,9 @@ async function searchMemory(query, topK = 5, agentId = "main", opts) {
       keywords: note.keywords,
       links: note.links,
       timestamp: note.timestamp,
-      similarity: embSimMap.get(id) ?? 0,
+      similarity: embSimMap.get(id) ?? bfsSimMap.get(id) ?? 0,
       rrf: rrfMap.get(id) ?? 0,
+      via,
       topics: note.topics ?? [],
       note_type: note.note_type ?? "memory"
     });
@@ -1817,7 +1985,7 @@ async function mergeSimilarNotes(agentId, storageCtx) {
       const mergedContent = judgment.mergedContent || pendingNote.content;
       const newEmbedding = await encode(buildEmbedText({ ...bestNeighbor, content: mergedContent }));
       const newHash = (0, import_crypto.createHash)("md5").update(mergedContent).digest("hex");
-      await ctx.updateNoteContent(bestNeighbor.id, mergedContent, newEmbedding, newHash);
+      await ctx.updateNoteContent(bestNeighbor.id, mergedContent, newEmbedding, newHash, agentId);
       await ctx.patchNotePayload(bestNeighbor.id, {
         evolution_history: JSON.stringify(oldHistory),
         evolution_type: "EVOLVE"
@@ -1841,7 +2009,7 @@ async function mergeSimilarNotes(agentId, storageCtx) {
       const mergedContent = judgment.mergedContent || `${bestNeighbor.content}\uFF1B${pendingNote.content}`;
       const newEmbedding = await encode(buildEmbedText({ ...bestNeighbor, content: mergedContent }));
       const newHash = (0, import_crypto.createHash)("md5").update(mergedContent).digest("hex");
-      await ctx.updateNoteContent(bestNeighbor.id, mergedContent, newEmbedding, newHash);
+      await ctx.updateNoteContent(bestNeighbor.id, mergedContent, newEmbedding, newHash, agentId);
       await ctx.patchNotePayload(bestNeighbor.id, {
         evolution_history: JSON.stringify(oldHistory),
         evolution_type: "EXPAND"
@@ -1881,7 +2049,7 @@ async function mergeSimilarNotes(agentId, storageCtx) {
       const [keepNote, dropNote] = noteA.content.length >= noteB.content.length ? [noteA, noteB] : [noteB, noteA];
       const newEmbedding = await encode(result.merged);
       const newHash = (0, import_crypto.createHash)("md5").update(result.merged).digest("hex");
-      await ctx.updateNoteContent(keepNote.id, result.merged, newEmbedding, newHash);
+      await ctx.updateNoteContent(keepNote.id, result.merged, newEmbedding, newHash, agentId);
       await ctx.deleteNote(dropNote.id);
       deletedIds.add(dropNote.id);
       mergedCount++;
@@ -1990,7 +2158,7 @@ async function consolidateMemories(agentId, logger, storageCtx) {
         action: "consolidate"
       });
       await ctx.updateNote(keepNote);
-      await ctx.invalidateNote(dropNote.id);
+      await ctx.invalidateNote(dropNote.id, agentId);
       await ctx.replaceLinkReferences(dropNote.id, keepNote.id, agentId);
       logMergeToFile(keepNote.id, dropNote.id, keepNote.content);
       processedIds.add(keepNote.id);
@@ -2285,8 +2453,19 @@ async function migrateCollection(opts) {
   );
   if (dryRun) {
     log("[migrate] dry run \u2014 nothing written. Pass dryRun: false to apply.");
-    return { total: notes.length, missingDerived, refreshed: 0, migrated: 0, sourceDim, targetDim, model, dryRun: true };
+    return {
+      total: notes.length,
+      missingDerived,
+      refreshed: 0,
+      migrated: 0,
+      skipped: 0,
+      sourceDim,
+      targetDim,
+      model,
+      dryRun: true
+    };
   }
+  let alreadyDone = /* @__PURE__ */ new Set();
   const existingTargetDim = await collectionDimRaw(to);
   if (existingTargetDim === null) {
     await createCollectionRaw(to, targetDim);
@@ -2295,9 +2474,17 @@ async function migrateCollection(opts) {
     if (existingTargetDim !== targetDim) {
       throw new Error(`migrate: target "${to}" exists at ${existingTargetDim}d but the model produces ${targetDim}d`);
     }
-    const existingCount = await countPointsRaw(to);
-    if (existingCount > 0) {
-      throw new Error(`migrate: target "${to}" already holds ${existingCount} point(s); use an empty collection`);
+    const present = await scrollIdsRaw(to);
+    if (present.size > 0) {
+      const sourceIds = new Set(notes.map((n) => n.id));
+      const foreign = [...present].filter((id) => !sourceIds.has(id));
+      if (foreign.length > 0) {
+        throw new Error(
+          `migrate: target "${to}" holds ${foreign.length} point(s) that are not in "${from}" (e.g. ${foreign[0]}). That is not an interrupted migration \u2014 use a different target.`
+        );
+      }
+      alreadyDone = present;
+      log(`[migrate] resuming: ${present.size} of ${notes.length} already in ${to}`);
     }
   }
   let refreshed = 0;
@@ -2311,6 +2498,7 @@ async function migrateCollection(opts) {
     buffer = [];
   };
   for (const note of notes) {
+    if (alreadyDone.has(note.id)) continue;
     if (refreshFields && missingDerivedFields(note)) {
       try {
         const built = await llmConstructNote(note.content);
@@ -2326,7 +2514,7 @@ async function migrateCollection(opts) {
     buffer.push(point);
     if (buffer.length >= BATCH) {
       await flush();
-      log(`[migrate] ${migrated}/${notes.length}`);
+      log(`[migrate] ${alreadyDone.size + migrated}/${notes.length}`);
     }
   }
   await flush();
@@ -2334,10 +2522,46 @@ async function migrateCollection(opts) {
   if (finalCount !== notes.length) {
     warn(`[migrate] target holds ${finalCount} point(s) but the source had ${notes.length} \u2014 check before switching`);
   }
-  log(
-    `[migrate] done: ${migrated} migrated, ${refreshed} re-extracted. "${from}" is untouched \u2014 switch with AMEM_COLLECTION=${to}, and keep the old one until you are satisfied.`
-  );
-  return { total: notes.length, missingDerived, refreshed, migrated, sourceDim, targetDim, model, dryRun: false };
+  log(`[migrate] done: ${migrated} written, ${alreadyDone.size} already present, ${refreshed} re-extracted.`);
+  return {
+    total: notes.length,
+    missingDerived,
+    refreshed,
+    migrated,
+    skipped: alreadyDone.size,
+    sourceDim,
+    targetDim,
+    model,
+    dryRun: false
+  };
+}
+async function switchToMigrated(opts) {
+  const { name, to } = opts;
+  const log = opts.logger?.info ?? ((m) => console.log(m));
+  if (name === to) throw new Error(`switch: "${name}" and "${to}" are the same collection`);
+  const already = await resolveAliasRaw(name);
+  if (already === to) {
+    log(`[switch] "${name}" already points at "${to}" \u2014 nothing to do`);
+    return { name, to, moved: await countPointsRaw(to) };
+  }
+  const targetCount = await countPointsRaw(to);
+  if (targetCount === 0) throw new Error(`switch: "${to}" is empty \u2014 migrate into it first`);
+  if (already === null) {
+    const sourceCount = await countPointsRaw(name);
+    if (targetCount < sourceCount) {
+      throw new Error(
+        `switch: "${to}" holds ${targetCount} point(s) but "${name}" still holds ${sourceCount}. The migration is not finished \u2014 run it again before switching.`
+      );
+    }
+    log(`[switch] verified ${targetCount} in "${to}" against ${sourceCount} in "${name}"`);
+    await deleteCollectionRaw(name);
+    log(`[switch] dropped "${name}"`);
+    await createAliasRaw(name, to);
+  } else {
+    await setAliasRaw(name, to);
+  }
+  log(`[switch] "${name}" now resolves to "${to}"`);
+  return { name, to, moved: targetCount };
 }
 
 // src/crud-guard.ts
@@ -2358,6 +2582,11 @@ function isPlausibleUpdateTarget(newEmbedding, targetEmbedding, minSimilarity) {
   DEFAULT_CRUD_UPDATE_MIN_SIM,
   DEFAULT_EMBEDDING_MODEL,
   EmbeddingDimensionMismatchError,
+  EmbeddingModelMismatchError,
+  LEGACY_DEFAULT_DIM,
+  LEGACY_DEFAULT_EMBEDDING_MODEL,
+  MixedEmbeddingModelsError,
+  SYSTEM_ACTOR,
   addEpisodic,
   addMemory,
   canRead,
@@ -2372,7 +2601,9 @@ function isPlausibleUpdateTarget(newEmbedding, targetEmbedding, minSimilarity) {
   encode,
   ensureCollection,
   generateReviewBatch,
+  getEmbeddingDevice,
   getEmbeddingDim,
+  getEmbeddingDtype,
   getEmbeddingModel,
   getEmbeddingPooling,
   getNote,
@@ -2390,6 +2621,7 @@ function isPlausibleUpdateTarget(newEmbedding, targetEmbedding, minSimilarity) {
   resolveCrudUpdateMinSim,
   scanLowQuality,
   searchMemory,
+  switchToMigrated,
   updateNote
 });
 //# sourceMappingURL=index.cjs.map