@amemhq/core 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -16,6 +16,19 @@ declare function configure(opts: {
 declare const DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
 /** Which model this process embeds with. */
 declare function getEmbeddingModel(): string;
+/** How token embeddings are collapsed into one sentence vector. */
+type PoolingMode = 'mean' | 'cls';
+/**
+ * Which pooling this process uses: `AMEM_EMBED_POOLING`, else the model's known
+ * mode, else `mean`.
+ *
+ * Getting this wrong does not fail. `encode()` returns a normalized vector of the
+ * right width either way, and search keeps working because notes and queries are
+ * embedded by the same function — it just retrieves worse than the model can,
+ * with nothing to indicate it. That is why the mode is resolved rather than
+ * assumed.
+ */
+declare function getEmbeddingPooling(): PoolingMode;
 /**
  * The vector width this model produces, measured rather than looked up.
  *
@@ -499,4 +512,4 @@ declare function llmCrudDecision(userText: string, assistantText: string, existi
     content: string;
 }>): Promise<MemoryOperation[]>;
 
-export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };
+export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type PoolingMode, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getEmbeddingPooling, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };

package/dist/index.d.ts

@@ -16,6 +16,19 @@ declare function configure(opts: {
 declare const DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
 /** Which model this process embeds with. */
 declare function getEmbeddingModel(): string;
+/** How token embeddings are collapsed into one sentence vector. */
+type PoolingMode = 'mean' | 'cls';
+/**
+ * Which pooling this process uses: `AMEM_EMBED_POOLING`, else the model's known
+ * mode, else `mean`.
+ *
+ * Getting this wrong does not fail. `encode()` returns a normalized vector of the
+ * right width either way, and search keeps working because notes and queries are
+ * embedded by the same function — it just retrieves worse than the model can,
+ * with nothing to indicate it. That is why the mode is resolved rather than
+ * assumed.
+ */
+declare function getEmbeddingPooling(): PoolingMode;
 /**
  * The vector width this model produces, measured rather than looked up.
  *
@@ -499,4 +512,4 @@ declare function llmCrudDecision(userText: string, assistantText: string, existi
     content: string;
 }>): Promise<MemoryOperation[]>;
 
-export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };
+export { type AgentAmemConfig, type AmemPluginConfig, type ConflictMode, type ConflictSweepResult, DEFAULT_CRUD_UPDATE_MIN_SIM, DEFAULT_EMBEDDING_MODEL, EmbeddingDimensionMismatchError, type EvolutionEntry, type LlmConfig, type LowQualityItem, type LowQualityReason, type MemoryNote, type MemoryOperation, type MigrateResult, type PoolingMode, type QueryResult, type SearchResult, type StorageContext, addEpisodic, addMemory, canRead, canWrite, checkQuality, configure, configureLlm, conflictSweep, consolidateMemories, createStorageContext, deleteNote, encode, ensureCollection, generateReviewBatch, getEmbeddingDim, getEmbeddingModel, getEmbeddingPooling, getNote, invalidateNote, isModelLoaded, isPlausibleUpdateTarget, listMemories, listNotes, llmCrudDecision, loadModel, mergeSimilarNotes, migrateCollection, patchNotePayload, pingQdrant, resolveCrudUpdateMinSim, scanLowQuality, searchMemory, updateNote };

package/dist/index.js

@@ -18,6 +18,25 @@ var DEFAULT_EMBEDDING_MODEL = "Xenova/paraphrase-multilingual-MiniLM-L12-v2";
 function getEmbeddingModel() {
   return process.env.AMEM_EMBED_MODEL?.trim() || DEFAULT_EMBEDDING_MODEL;
 }
+var CLS_POOLED_MODELS = /* @__PURE__ */ new Set([
+  "bge-m3",
+  "bge-base-zh-v1.5",
+  "bge-small-zh-v1.5",
+  "bge-base-en-v1.5",
+  "bge-small-en-v1.5",
+  "bge-large-en-v1.5",
+  "gte-multilingual-base",
+  "gte-modernbert-base",
+  "gte-large-en-v1.5",
+  "snowflake-arctic-embed-m",
+  "snowflake-arctic-embed-l"
+]);
+function getEmbeddingPooling() {
+  const explicit = process.env.AMEM_EMBED_POOLING?.trim().toLowerCase();
+  if (explicit === "mean" || explicit === "cls") return explicit;
+  const basename2 = getEmbeddingModel().split("/").pop()?.toLowerCase() ?? "";
+  return CLS_POOLED_MODELS.has(basename2) ? "cls" : "mean";
+}
 async function getExtractor() {
   const wanted = getEmbeddingModel();
   if (extractor && loadedModelName === wanted) return extractor;
@@ -38,21 +57,25 @@ async function getEmbeddingDim() {
   cachedDim = probe.length;
   return cachedDim;
 }
-function meanPoolingNormalize(output, attentionMask) {
+function poolNormalize(output, attentionMask, mode) {
   const seqLen = output.length;
   const dim = output[0].length;
   const pooled = new Array(dim).fill(0);
-  let maskSum = 0;
-  for (let i = 0; i < seqLen; i++) {
-    const m = attentionMask[i];
-    maskSum += m;
+  if (mode === "cls") {
+    for (let j = 0; j < dim; j++) pooled[j] = output[0][j];
+  } else {
+    let maskSum = 0;
+    for (let i = 0; i < seqLen; i++) {
+      const m = attentionMask[i];
+      maskSum += m;
+      for (let j = 0; j < dim; j++) {
+        pooled[j] += output[i][j] * m;
+      }
+    }
     for (let j = 0; j < dim; j++) {
-      pooled[j] += output[i][j] * m;
+      pooled[j] /= Math.max(maskSum, 1e-9);
     }
   }
-  for (let j = 0; j < dim; j++) {
-    pooled[j] /= Math.max(maskSum, 1e-9);
-  }
   let norm = 0;
   for (const v of pooled) norm += v * v;
   norm = Math.sqrt(norm);
@@ -60,7 +83,8 @@ function meanPoolingNormalize(output, attentionMask) {
 }
 async function encode(text) {
   const ext = await getExtractor();
-  const result = await ext(text, { pooling: "mean", normalize: true });
+  const pooling = getEmbeddingPooling();
+  const result = await ext(text, { pooling, normalize: true });
   if (result && result.data) {
     return Array.from(result.data);
   }
@@ -76,7 +100,7 @@ async function encode(text) {
       }
       raw.push(row);
     }
-    return meanPoolingNormalize(raw, new Array(seqLen).fill(1));
+    return poolNormalize(raw, new Array(seqLen).fill(1), pooling);
   }
   throw new Error("Unexpected embedding output shape");
 }
@@ -2278,6 +2302,7 @@ export {
   generateReviewBatch,
   getEmbeddingDim,
   getEmbeddingModel,
+  getEmbeddingPooling,
   getNote,
   invalidateNote,
   isModelLoaded,