openclaw-amem 1.4.3 → 2.0.0

package/README.md

@@ -29,7 +29,7 @@ Requires a local [Qdrant](https://qdrant.tech). Implements [A-MEM](https://arxiv
 - 🧠 **Knowledge vs episodic** — durable knowledge notes skip consolidation & time-decay; topic tags for precise recall.
 - 🧹 **Self-consolidating** — daily 02:30 in-process merge of semantic duplicates with link cascading.
 - 🔐 **Per-agent isolation** — private by default; explicit `owner`/`readers`/`writers`; Mode A (shared collection) or Mode B (dedicated collection).
-- 🀄 **Chinese-optimized** & local embeddings (Transformers.js, 384-dim) — no Python, no external embedding API.
+- 🀄 **Chinese-optimized** & local embeddings (Transformers.js) — no Python, no external embedding API.
 
 → Full feature list & internals: **[@amemhq/core README](../amem-core)** · **[docs](https://amem.owo.lc)**.
 
@@ -39,6 +39,7 @@ Requires a local [Qdrant](https://qdrant.tech). Implements [A-MEM](https://arxiv
 - Node.js 24 (18+ works; 24/26 supported)
 - Qdrant running on `:6333`
 - An LLM: `ANTHROPIC_API_KEY` by default, or any OpenAI-compatible provider — see [LLM provider](#llm-provider)
+- ~1.1 GB of disk for the embedding model, downloaded once on first run
 
 ## Installation
 
@@ -88,6 +89,15 @@ Add `openclaw-amem` to your allowed plugins and hook it into the `memory` slot:
 openclaw gateway restart
 ```
 
+First run downloads the embedding model (`bge-m3`, 1.08 GB) and caches it. Later
+restarts are instant. Want something smaller? `AMEM_EMBED_MODEL=onnx-community/gte-multilingual-base`
+is about a third the size and reads text just as long — set it **before** you have
+memories, since changing it afterwards means a [migration](https://amem.owo.lc/reference/embedding-models#changing-the-model-on-a-store-you-already-have).
+
+Upgrading from 1.x downloads nothing. Your existing memories keep the model that
+built them, and the plugin says so at startup along with the one command that
+moves them.
+
 ## LLM provider
 
 The plugin calls an LLM for note construction, linking, and evolution. Pick the backend with `AMEM_LLM_PROVIDER`:

package/dist/index.js

@@ -53,8 +53,18 @@ var init_config = __esm({
 });
 
 // ../amem-core/src/embedding.ts
+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;
 }
 function getEmbeddingPooling() {
   const explicit = process.env.AMEM_EMBED_POOLING?.trim().toLowerCase();
@@ -66,7 +76,9 @@ function getEmbeddingDevice() {
   return process.env.AMEM_EMBED_DEVICE?.trim() || void 0;
 }
 function getEmbeddingDtype() {
-  return process.env.AMEM_EMBED_DTYPE?.trim() || void 0;
+  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() ?? ""}`;
@@ -155,7 +167,7 @@ function cosineSimilarity(a, b) {
   for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
   return dot;
 }
-var pipeline, extractor, loadedKey, cachedDim, DEFAULT_EMBEDDING_MODEL, CLS_POOLED_MODELS;
+var pipeline, extractor, loadedKey, cachedDim, DEFAULT_EMBEDDING_MODEL, LEGACY_DEFAULT_EMBEDDING_MODEL, LEGACY_DEFAULT_DIM, DEFAULT_MODEL_DTYPE, pinnedModel, CLS_POOLED_MODELS;
 var init_embedding = __esm({
   "../amem-core/src/embedding.ts"() {
     "use strict";
@@ -163,7 +175,11 @@ var init_embedding = __esm({
     extractor = null;
     loadedKey = null;
     cachedDim = null;
-    DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+    DEFAULT_EMBEDDING_MODEL = "Xenova/bge-m3";
+    LEGACY_DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
+    LEGACY_DEFAULT_DIM = 384;
+    DEFAULT_MODEL_DTYPE = "fp16";
+    pinnedModel = null;
     CLS_POOLED_MODELS = /* @__PURE__ */ new Set([
       "bge-m3",
       "bge-base-zh-v1.5",
@@ -187,20 +203,22 @@ function canWrite(note, callerAgentId) {
 function canRead(note, callerAgentId) {
   return note.owner === callerAgentId || note.readers.includes(callerAgentId) || note.readers.includes("*");
 }
+var SYSTEM_ACTOR;
 var init_auth = __esm({
   "../amem-core/src/auth.ts"() {
     "use strict";
+    SYSTEM_ACTOR = "__amem_system__";
   }
 });
 
 // ../amem-core/src/storage.ts
 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.`;
 }
 async function recordCollectionModel(collection, model) {
   try {
@@ -242,18 +260,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();
@@ -267,7 +305,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"
@@ -321,6 +361,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,
@@ -465,12 +542,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`, {
@@ -480,7 +560,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;
@@ -518,19 +598,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 }]
@@ -618,11 +701,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 },
@@ -688,8 +771,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);
@@ -700,13 +783,13 @@ 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);
 }
-var QDRANT_URL, getCollection, EmbeddingDimensionMismatchError, EmbeddingModelMismatchError, _collectionReady, _collectionReadyMap;
+var QDRANT_URL, getCollection, EmbeddingDimensionMismatchError, EmbeddingModelMismatchError, MixedEmbeddingModelsError, _collectionReady, _collectionReadyMap;
 var init_storage = __esm({
   "../amem-core/src/storage.ts"() {
     "use strict";
@@ -746,6 +829,25 @@ Either set AMEM_EMBED_MODEL back to "${collectionModel}", or ` + migrationHint(c
       collectionModel;
       configuredModel;
     };
+    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;
+    };
     _collectionReady = false;
     _collectionReadyMap = /* @__PURE__ */ new Map();
   }
@@ -1511,7 +1613,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(
@@ -1583,7 +1685,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)}`);
@@ -1596,7 +1698,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)}`);
@@ -1749,7 +1851,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])
@@ -1772,6 +1874,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;
@@ -1782,10 +1885,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;
@@ -1801,7 +1903,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({
@@ -1812,8 +1918,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"
     });
@@ -1870,7 +1977,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"
@@ -1894,7 +2001,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"
@@ -1934,7 +2041,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++;
@@ -2043,7 +2150,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);
@@ -2366,8 +2473,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);
@@ -2376,9 +2494,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;
@@ -2392,6 +2518,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);
@@ -2407,7 +2534,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();
@@ -2415,10 +2542,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 };
 }
 var init_migrate = __esm({
   "../amem-core/src/migrate.ts"() {
@@ -2458,6 +2621,10 @@ __export(src_exports, {
   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,
@@ -2492,6 +2659,7 @@ __export(src_exports, {
   resolveCrudUpdateMinSim: () => resolveCrudUpdateMinSim,
   scanLowQuality: () => scanLowQuality,
   searchMemory: () => searchMemory,
+  switchToMigrated: () => switchToMigrated,
   updateNote: () => updateNote
 });
 var init_src = __esm({
@@ -2609,7 +2777,7 @@ function register(api) {
     `openclaw-amem: registered (native TS, Qdrant, default agent_id=${defaultScope.agentId}, default collection=${pluginConfig.collection ?? "amem_notes (default)"}, per-agent scope resolved per call)`
   );
   ensureCollection(pluginConfig.collection).catch((e) => {
-    if (e instanceof EmbeddingDimensionMismatchError || e instanceof EmbeddingModelMismatchError) {
+    if (e instanceof EmbeddingDimensionMismatchError || e instanceof EmbeddingModelMismatchError || e instanceof MixedEmbeddingModelsError) {
       logger.error(`openclaw-amem: memory is UNUSABLE \u2014 ${e.message}`);
     } else {
       logger.warn(`openclaw-amem: ensureCollection failed \u2014 ${e.message}`);
@@ -2732,9 +2900,13 @@ function register(api) {
                   details: { count: 0 }
                 };
               }
-              const text = results.map((r, i) => `${i + 1}. ${r.content} (score: ${(r.similarity * 100).toFixed(0)}%, id: ${r.id})`).join("\n");
+              const linked = results.filter((r) => r.via === "link").length;
+              const text = results.map(
+                (r, i) => `${i + 1}. ${r.content} (similarity ${(r.similarity * 100).toFixed(0)}%${r.via === "link" ? ", linked \u2014 did not match the query itself" : ""}, id: ${r.id})`
+              ).join("\n");
+              const header = linked ? `Found ${results.length - linked} matching memories, plus ${linked} linked to them:` : `Found ${results.length} memories:`;
               return {
-                content: [{ type: "text", text: `Found ${results.length} memories:
+                content: [{ type: "text", text: `${header}
 
 ${text}${hookWarning}` }],
                 details: { count: results.length, memories: results }

package/openclaw.plugin.json

@@ -2,7 +2,8 @@
   "id": "openclaw-amem",
   "name": "amem",
   "description": "Catches memories that contradict each other. Notes rewrite themselves as new ones arrive, link into a graph, and stay separated per agent and per person. Runs on a small model. Requires a local Qdrant. 中文走 jieba 分词，提示词有中文版。",
-  "version": "1.4.3",
+  "icon": "https://amem.owo.lc/logo.png",
+  "version": "2.0.0",
   "kind": "memory",
   "openclaw": {
     "compat": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-amem",
-  "version": "1.4.3",
+  "version": "2.0.0",
   "description": "Catches memories that contradict each other. Notes rewrite themselves as new ones arrive, link into a graph, and stay separated per agent and per person. Runs on a small model. Requires a local Qdrant. 中文走 jieba 分词，提示词有中文版。",
   "license": "MIT",
   "main": "dist/index.js",