@memrosetta/core 0.2.21 → 0.3.0

package/dist/index.d.ts

@@ -2,6 +2,14 @@ import Database from 'better-sqlite3';
 import { Memory, MemoryState, MemoryInput, RelationType, MemoryRelation, SearchResult, SearchFilters, SearchQuery, SearchResponse, IMemoryEngine, CompressResult, MaintenanceResult, MemoryTier, MemoryQuality, TierConfig } from '@memrosetta/types';
 import { Embedder, ContradictionDetector } from '@memrosetta/embeddings';
 
+/**
+ * Thrown when a memory ID referenced in an operation does not exist.
+ */
+declare class MemoryNotFoundError extends Error {
+    readonly memoryId: string;
+    constructor(memoryId: string);
+}
+
 interface SchemaOptions {
     readonly vectorEnabled?: boolean;
     readonly embeddingDimension?: number;
@@ -169,6 +177,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 +228,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 +350,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, MemoryNotFoundError, 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

@@ -1,3 +1,13 @@
+// src/errors.ts
+var MemoryNotFoundError = class extends Error {
+  memoryId;
+  constructor(memoryId) {
+    super(`Memory not found: ${memoryId}`);
+    this.name = "MemoryNotFoundError";
+    this.memoryId = memoryId;
+  }
+};
+
 // src/schema.ts
 var SCHEMA_V1 = `
 -- memories table
@@ -443,11 +453,11 @@ function createRelationStatements(db) {
 function createRelation(db, stmts, srcMemoryId, dstMemoryId, relationType, reason) {
   const srcExists = stmts.checkMemoryExists.get(srcMemoryId);
   if (!srcExists) {
-    throw new Error(`Source memory not found: ${srcMemoryId}`);
+    throw new MemoryNotFoundError(srcMemoryId);
   }
   const dstExists = stmts.checkMemoryExists.get(dstMemoryId);
   if (!dstExists) {
-    throw new Error(`Destination memory not found: ${dstMemoryId}`);
+    throw new MemoryNotFoundError(dstMemoryId);
   }
   const createdAt = nowIso();
   stmts.insertRelation.run(
@@ -792,7 +802,7 @@ function vectorSearch(db, queryVec, userId, limit, filters, useVecTable = true)
   if (!useVecTable) {
     return bruteForceVectorSearch(db, queryVec, userId, limit, filters);
   }
-  const candidateLimit = Math.min(limit * 5, 200);
+  const candidateLimit = Math.min(limit * 10, 500);
   const vecBuf = Buffer.from(queryVec.buffer, queryVec.byteOffset, queryVec.byteLength);
   let candidates;
   try {
@@ -802,7 +812,10 @@ function vectorSearch(db, queryVec, userId, limit, filters, useVecTable = true)
       WHERE embedding MATCH ?
       AND k = ?
     `).all(vecBuf, candidateLimit);
-  } catch {
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[memrosetta] vec_memories KNN unavailable, using brute-force fallback: ${msg}
+`);
     return bruteForceVectorSearch(db, queryVec, userId, limit, filters);
   }
   if (candidates.length === 0) return [];
@@ -863,6 +876,9 @@ function vectorSearch(db, queryVec, userId, limit, filters, useVecTable = true)
     params.push(filters.eventDateRange.end);
   }
   const rows = db.prepare(sql).all(...params);
+  if (rows.length < limit) {
+    return bruteForceVectorSearch(db, queryVec, userId, limit, filters);
+  }
   return rows.map((row) => ({
     memory: rowToMemory(row),
     distance: distanceMap.get(row.id) ?? Infinity
@@ -934,6 +950,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 +1124,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 {
@@ -1714,6 +1742,7 @@ function createEngine(options) {
 }
 export {
   DEFAULT_TIER_CONFIG,
+  MemoryNotFoundError,
   SqliteMemoryEngine,
   applyKeywordBoost,
   applyThreeFactorReranking,
@@ -1722,6 +1751,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.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,10 +20,10 @@
     "better-sqlite3": "^11.0.0",
     "nanoid": "^5.0.0",
     "sqlite-vec": "^0.1.7",
-    "@memrosetta/types": "0.2.21"
+    "@memrosetta/types": "0.3.0"
   },
   "optionalDependencies": {
-    "@memrosetta/embeddings": "0.2.21"
+    "@memrosetta/embeddings": "0.3.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",