@amemhq/core 1.1.0 → 2.1.0

package/README.md

@@ -17,7 +17,7 @@ Unlike a flat vector store, A-MEM maintains memory as a living, self-evolving se
 1. **Note Construction** — an LLM extracts keywords, tags, and a context summary; categorizes the note; and classifies it as `memory` (episodic) or `knowledge` (durable), extracting 1–5 `topics` for knowledge notes.
 2. **Link Generation** — retrieves top-6 candidates; the LLM judges whether to link bidirectionally (similarity > 0.3).
 3. **Memory Evolution** — up to 3 linked notes have their attributes evolved from the new context, possibly triggering further links.
-4. **Hybrid Retrieval** — fuses dense vectors (Transformers.js `paraphrase-multilingual-MiniLM-L12-v2`, 384-dim) and BM25 via Reciprocal Rank Fusion (RRF), boosted by retrieval heat.
+4. **Hybrid Retrieval** — fuses dense vectors (Transformers.js `bge-m3`, 1024-dim) and BM25 via Reciprocal Rank Fusion (RRF), boosted by retrieval heat.
 5. **2-hop BFS Graph Expansion** — after RRF top-K, BFS walks the link graph up to 2 hops, admitting up to 8 graph-connected notes that pass an embedding relevance gate (cos-sim ≥ 0.25). This is the key advantage over flat vector systems.
 
 ## Features
@@ -47,7 +47,7 @@ host (OpenClaw plugin / amem-api / game agent)
      ▼
   @amemhq/core (TypeScript)
      ├── LLM (Anthropic)        note construction · link judgment · CRUD · evolution
-     ├── Transformers.js (ONNX) 384-dim local embeddings + Jieba BM25
+     ├── Transformers.js (ONNX) local embeddings + Jieba BM25
      └── Qdrant :6333           vector store · owner/readers/writers · agent_id isolation
 ```
 

package/dist/{chunk-B2NS7WAM.js → chunk-XEMQZNLD.js}

@@ -1,4 +1,5 @@
 // src/auth.ts
+var SYSTEM_ACTOR = "__amem_system__";
 function canWrite(note, callerAgentId) {
   return note.owner === callerAgentId || note.writers.includes(callerAgentId) || note.writers.includes("*");
 }
@@ -11,9 +12,22 @@ var pipeline = null;
 var extractor = 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 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",
@@ -40,6 +54,27 @@ function getEmbeddingDevice() {
 function getEmbeddingDtype() {
   return process.env.AMEM_EMBED_DTYPE?.trim() || void 0;
 }
+function applyModelPaths(env) {
+  const cache = process.env.AMEM_MODEL_CACHE?.trim();
+  if (cache) env.cacheDir = cache;
+  const local = process.env.AMEM_MODEL_DIR?.trim();
+  if (local) {
+    env.localModelPath = local;
+    env.allowLocalModels = true;
+  }
+}
+function makeProgressReporter() {
+  const lastPct = /* @__PURE__ */ new Map();
+  return (e) => {
+    if (e.status !== "progress" || !e.file || typeof e.progress !== "number") return;
+    if (!e.file.endsWith(".onnx") && !e.file.endsWith(".onnx_data")) return;
+    const pct = Math.floor(e.progress / 10) * 10;
+    if (lastPct.get(e.file) === pct) return;
+    lastPct.set(e.file, pct);
+    const size = e.total ? ` of ${(e.total / 1e9).toFixed(2)} GB` : "";
+    console.log(`[amem] downloading ${e.file}: ${pct}%${size}`);
+  };
+}
 function extractorKey() {
   return `${getEmbeddingModel()}|${getEmbeddingDevice() ?? ""}|${getEmbeddingDtype() ?? ""}`;
 }
@@ -49,11 +84,13 @@ async function getExtractor() {
   if (!pipeline) {
     const mod = await import("@huggingface/transformers");
     pipeline = mod.pipeline;
+    applyModelPaths(mod.env);
   }
   const device = getEmbeddingDevice();
   const dtype = getEmbeddingDtype();
   extractor = await pipeline("feature-extraction", getEmbeddingModel(), {
     revision: "main",
+    progress_callback: makeProgressReporter(),
     // Omitted entirely when unset, so an unconfigured install gets exactly the
     // library defaults it got before these existed.
     ...device ? { device } : {},
@@ -149,12 +186,12 @@ Either set AMEM_EMBED_MODEL back to the model this collection was built with, or
   model;
 };
 function migrationHint(collection, targetModel) {
-  return `migrate to a new collection:
+  return `migrate onto it:
 
   AMEM_EMBED_MODEL=${targetModel} \\
-    npx --package=@amemhq/core amem-migrate --to ${collection}_v2
+    npx --package=@amemhq/core amem-migrate --from-collection ${collection}
 
-That is a dry run; add --apply to write. "${collection}" is only read, so nothing is lost either way. When it looks right, point whatever names this collection at the new one \u2014 AMEM_COLLECTION, or the plugin's "collection" setting if this agent has its own. See https://amem.owo.lc/reference/embedding-models.`;
+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) {
@@ -171,6 +208,25 @@ Either set AMEM_EMBED_MODEL back to "${collectionModel}", or ` + migrationHint(c
   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 } });
@@ -213,18 +269,38 @@ 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 recorded = existing.config?.metadata?.embedding_model;
     const current = getEmbeddingModel();
     if (typeof recorded === "string" && recorded !== current) {
       throw new EmbeddingModelMismatchError(col, recorded, current);
     }
-    if (recorded === void 0) {
+    if (recorded === void 0 && !inferLegacy) {
       await recordCollectionModel(col, current);
     }
     markReady();
@@ -238,7 +314,9 @@ async function ensureCollection(collectionName) {
   } catch (err) {
     if (!(err instanceof Error) || !err.message.includes("already exists")) throw err;
   }
-  await recordCollectionModel(col, getEmbeddingModel());
+  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"
@@ -292,6 +370,47 @@ 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 snapshotCollectionRaw(collection) {
+  const r = await qdrant("POST", `/collections/${collection}/snapshots`);
+  return { name: r.name, size: r.size ?? 0 };
+}
+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,
@@ -436,12 +555,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`, {
@@ -451,7 +573,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;
@@ -489,19 +611,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 }]
@@ -589,11 +714,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 },
@@ -659,8 +784,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);
@@ -671,8 +796,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);
@@ -1441,7 +1566,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(
@@ -1513,7 +1638,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)}`);
@@ -1526,7 +1651,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)}`);
@@ -1679,7 +1804,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])
@@ -1702,6 +1827,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;
@@ -1712,10 +1838,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;
@@ -1731,7 +1856,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({
@@ -1742,8 +1871,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"
     });
@@ -1800,7 +1930,7 @@ async function mergeSimilarNotes(agentId, storageCtx) {
       const mergedContent = judgment.mergedContent || pendingNote.content;
       const newEmbedding = await encode(buildEmbedText({ ...bestNeighbor, content: mergedContent }));
       const newHash = 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"
@@ -1824,7 +1954,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 = 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"
@@ -1864,7 +1994,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 = 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++;
@@ -1973,7 +2103,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);
@@ -2086,8 +2216,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);
@@ -2096,9 +2237,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;
@@ -2112,6 +2261,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);
@@ -2127,7 +2277,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();
@@ -2135,16 +2285,60 @@ 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`);
+  let snap;
+  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}"`);
+    if (opts.snapshot !== false) {
+      snap = await snapshotCollectionRaw(name);
+      log(`[switch] snapshotted "${name}" \u2192 ${snap.name} (${(snap.size / 1e6).toFixed(0)} MB)`);
+    }
+    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, snapshot: snap };
 }
 
 export {
+  SYSTEM_ACTOR,
   canWrite,
   canRead,
   DEFAULT_EMBEDDING_MODEL,
+  LEGACY_DEFAULT_EMBEDDING_MODEL,
+  LEGACY_DEFAULT_DIM,
   getEmbeddingModel,
   getEmbeddingPooling,
   getEmbeddingDevice,
@@ -2157,8 +2351,13 @@ export {
   getCollection,
   EmbeddingDimensionMismatchError,
   EmbeddingModelMismatchError,
+  MixedEmbeddingModelsError,
   pingQdrant,
   ensureCollection,
+  countPointsRaw,
+  collectionDimRaw,
+  scrollIdsRaw,
+  resolveAliasRaw,
   createStorageContext,
   getNote,
   updateNote,
@@ -2177,6 +2376,7 @@ export {
   mergeSimilarNotes,
   consolidateMemories,
   conflictSweep,
-  migrateCollection
+  migrateCollection,
+  switchToMigrated
 };
-//# sourceMappingURL=chunk-B2NS7WAM.js.map
+//# sourceMappingURL=chunk-XEMQZNLD.js.map