@memrosetta/core 0.2.21 → 0.2.22

package/dist/index.d.ts

@@ -169,6 +169,17 @@ declare function rrfMergeWeighted(ftsResults: readonly {
     readonly memory: Memory;
     readonly rank: number;
 }[], k?: number, limit?: number, ftsWeight?: number, vecWeight?: number): readonly SearchResult[];
+/**
+ * Score-level fusion: alpha * normalizedVecSim + (1 - alpha) * normalizedFtsSim.
+ *
+ * Unlike RRF (which discards score magnitude), this preserves score information.
+ * Both FTS and vector scores are min-max normalized within the result set so
+ * neither modality dominates due to scale differences.
+ *
+ * Items found by both sources get the combined score (strongest signal).
+ * Items found by only one source get at most alpha or (1-alpha) of max.
+ */
+declare function convexCombinationMerge(ftsResults: readonly SearchResult[], vecResults: readonly VectorSearchResult[], alpha?: number, limit?: number): readonly SearchResult[];
 /**
  * Generative Agents-inspired 3-factor reranking.
  * final_score = w_recency * recency + w_importance * importance + w_relevance * relevance
@@ -209,7 +220,7 @@ declare function updateAccessTracking(db: Database.Database, memoryIds: readonly
  *
  * When queryVec is not provided, performs FTS-only search (backward compatible).
  * When queryVec is provided, performs hybrid search combining FTS + vector
- * results via Reciprocal Rank Fusion.
+ * results via convex combination score fusion.
  *
  * Results are weighted by activation score and access tracking is updated.
  */
@@ -331,4 +342,4 @@ declare function determineTier(memory: {
  */
 declare function estimateTokens(content: string): number;
 
-export { DEFAULT_TIER_CONFIG, type MemoryRow, type PreparedStatements, type RelationStatements, type SchemaOptions, type SearchSqlResult, type SqliteEngineOptions, SqliteMemoryEngine, type VectorSearchResult, applyKeywordBoost, applyThreeFactorReranking, bruteForceVectorSearch, buildFtsQuery, buildSearchSql, computeActivation, computeEbbinghaus, createEngine, createPreparedStatements, createRelation, createRelationStatements, deduplicateResults, deriveMemoryState, determineTier, ensureSchema, estimateTokens, extractQueryTokens, ftsSearch, generateMemoryId, getRelationsByMemory, keywordsToString, normalizeScores, nowIso, rowToMemory, rrfMerge, rrfMergeWeighted, searchMemories, serializeEmbedding, storeBatchAsync, storeBatchInTransaction, storeMemory, storeMemoryAsync, stringToKeywords, updateAccessTracking, vectorSearch };
+export { DEFAULT_TIER_CONFIG, type MemoryRow, type PreparedStatements, type RelationStatements, type SchemaOptions, type SearchSqlResult, type SqliteEngineOptions, SqliteMemoryEngine, type VectorSearchResult, applyKeywordBoost, applyThreeFactorReranking, bruteForceVectorSearch, buildFtsQuery, buildSearchSql, computeActivation, computeEbbinghaus, convexCombinationMerge, createEngine, createPreparedStatements, createRelation, createRelationStatements, deduplicateResults, deriveMemoryState, determineTier, ensureSchema, estimateTokens, extractQueryTokens, ftsSearch, generateMemoryId, getRelationsByMemory, keywordsToString, normalizeScores, nowIso, rowToMemory, rrfMerge, rrfMergeWeighted, searchMemories, serializeEmbedding, storeBatchAsync, storeBatchInTransaction, storeMemory, storeMemoryAsync, stringToKeywords, updateAccessTracking, vectorSearch };

package/dist/index.js

@@ -934,6 +934,42 @@ function rrfMergeWeighted(ftsResults, vecResults, k = 20, limit = 10, ftsWeight
     matchType: "hybrid"
   }));
 }
+function convexCombinationMerge(ftsResults, vecResults, alpha = 0.5, limit = 10) {
+  const vecSims = /* @__PURE__ */ new Map();
+  for (const vr of vecResults) {
+    vecSims.set(vr.memory.memoryId, {
+      sim: 1 - vr.distance,
+      memory: vr.memory
+    });
+  }
+  const vecValues = [...vecSims.values()].map((v) => v.sim);
+  const vecMin = vecValues.length > 0 ? Math.min(...vecValues) : 0;
+  const vecMax = vecValues.length > 0 ? Math.max(...vecValues) : 1;
+  const vecRange = vecMax - vecMin || 1;
+  const ftsValues = ftsResults.map((r) => r.score);
+  const ftsMin = ftsValues.length > 0 ? Math.min(...ftsValues) : 0;
+  const ftsMax = ftsValues.length > 0 ? Math.max(...ftsValues) : 1;
+  const ftsRange = ftsMax - ftsMin || 1;
+  const merged = /* @__PURE__ */ new Map();
+  for (const fr of ftsResults) {
+    const normFts = (fr.score - ftsMin) / ftsRange;
+    const vecEntry = vecSims.get(fr.memory.memoryId);
+    const normVec = vecEntry ? (vecEntry.sim - vecMin) / vecRange : 0;
+    const score = alpha * normVec + (1 - alpha) * normFts;
+    merged.set(fr.memory.memoryId, { score, memory: fr.memory });
+  }
+  for (const [id, entry] of vecSims) {
+    if (merged.has(id)) continue;
+    const normVec = (entry.sim - vecMin) / vecRange;
+    const score = alpha * normVec;
+    merged.set(id, { score, memory: entry.memory });
+  }
+  return [...merged.values()].sort((a, b) => b.score - a.score).slice(0, limit).map(({ score, memory }) => ({
+    memory,
+    score,
+    matchType: "hybrid"
+  }));
+}
 function cosineSimilarity(a, b) {
   let dot = 0;
   let normA = 0;
@@ -1072,34 +1108,10 @@ function searchMemories(db, query, queryVec, useVecTable = true, skipAccessTrack
     finalResults = deduplicateResults(boosted);
   } else {
     const limit = query.limit ?? DEFAULT_LIMIT;
-    const ftsHasEnough = ftsResults.length >= limit;
-    if (ftsHasEnough) {
-      const vecIds = new Set(vecResults.map((r) => r.memory.memoryId));
-      const reranked = ftsResults.map((r) => ({
-        ...r,
-        score: r.score * (vecIds.has(r.memory.memoryId) ? 1.3 : 1)
-      }));
-      reranked.sort((a, b) => b.score - a.score);
-      const weighted = applyThreeFactorReranking(reranked);
-      const boosted = applyKeywordBoost(weighted, queryTokens);
-      finalResults = deduplicateResults(boosted);
-    } else {
-      const ftsIds = new Set(ftsResults.map((r) => r.memory.memoryId));
-      const ftsItems = [...ftsResults];
-      for (const vr of vecResults) {
-        if (ftsItems.length >= limit) break;
-        if (ftsIds.has(vr.memory.memoryId)) continue;
-        ftsItems.push({
-          memory: vr.memory,
-          score: (1 - vr.distance) * 0.5,
-          // Lower score than FTS items
-          matchType: "hybrid"
-        });
-      }
-      const weighted = applyThreeFactorReranking(ftsItems);
-      const boosted = applyKeywordBoost(weighted, queryTokens);
-      finalResults = deduplicateResults(boosted);
-    }
+    const merged = convexCombinationMerge(ftsResults, vecResults, 0.3, limit);
+    const weighted = applyThreeFactorReranking(merged);
+    const boosted = applyKeywordBoost(weighted, queryTokens);
+    finalResults = deduplicateResults(boosted);
   }
   updateAccessTracking(db, finalResults.map((r) => r.memory.memoryId));
   return {
@@ -1722,6 +1734,7 @@ export {
   buildSearchSql,
   computeActivation,
   computeEbbinghaus,
+  convexCombinationMerge,
   createEngine,
   createPreparedStatements,
   createRelation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memrosetta/core",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",