@memrosetta/core 0.2.18 → 0.2.19

package/dist/index.d.ts

@@ -160,6 +160,21 @@ declare function rrfMergeWeighted(ftsResults: readonly {
     readonly memory: Memory;
     readonly rank: number;
 }[], k?: number, limit?: number, ftsWeight?: number, vecWeight?: number): readonly SearchResult[];
+/**
+ * Generative Agents-inspired 3-factor reranking.
+ * final_score = w_recency * recency + w_importance * importance + w_relevance * relevance
+ *
+ * - recency: exponential decay from learnedAt (0.995^hours)
+ * - importance: memory.salience (0-1)
+ * - relevance: original search score (from FTS/vector/RRF)
+ *
+ * All three are min-max normalized before combining.
+ */
+declare function applyThreeFactorReranking(results: readonly SearchResult[], weights?: {
+    recency?: number;
+    importance?: number;
+    relevance?: number;
+}): readonly SearchResult[];
 /**
  * Remove duplicate search results based on content identity.
  * Keeps the first (highest-scored) occurrence when duplicates exist.
@@ -231,6 +246,14 @@ declare class SqliteMemoryEngine implements IMemoryEngine {
      * swallowed so that memory storage is never blocked.
      */
     private checkContradictions;
+    /**
+     * Check for near-duplicate memories after storing.
+     * Uses direct cosine similarity (not the combined search score) to avoid
+     * false positives from the multi-factor reranking.
+     * If cosine similarity > 0.95, auto-create an 'updates' relation (new supersedes old).
+     * Only runs for single store() calls, not storeBatch() (too slow for bulk).
+     */
+    private checkDuplicates;
     private ensureInitialized;
 }
 declare function createEngine(options: SqliteEngineOptions): SqliteMemoryEngine;
@@ -257,19 +280,30 @@ declare function createEngine(options: SqliteEngineOptions): SqliteMemoryEngine;
  * @returns activation score in [0, 1]
  */
 declare function computeActivation(accessTimestamps: readonly string[], salience: number, now?: Date): number;
+/**
+ * Ebbinghaus forgetting curve: R = e^(-t/S)
+ * R = retention (0-1)
+ * t = days since last access
+ * S = strength (access_count, minimum 1)
+ *
+ * Works with existing fields (access_count, last_accessed_at) without
+ * needing an access history table like ACT-R does.
+ */
+declare function computeEbbinghaus(accessCount: number, lastAccessedAt: string | null, now?: Date): number;
 
 declare const DEFAULT_TIER_CONFIG: TierConfig;
 /**
  * Determine the appropriate tier for a memory based on its properties.
  *
- * - hot: manually promoted memories stay hot
- * - warm: memories within warmDays of creation
- * - cold: older than warmDays
+ * - hot: manually promoted memories stay hot, OR auto-promoted via high access count (>= 10)
+ * - warm: memories within warmDays of creation, OR old but with high activation
+ * - cold: older than warmDays AND low activation
  */
 declare function determineTier(memory: {
     readonly learnedAt: string;
     readonly activationScore: number;
     readonly tier: string;
+    readonly accessCount?: number;
 }, config?: TierConfig, now?: Date): MemoryTier;
 /**
  * Estimate token count from content length.
@@ -277,4 +311,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, bruteForceVectorSearch, buildFtsQuery, buildSearchSql, computeActivation, createEngine, createPreparedStatements, createRelation, createRelationStatements, deduplicateResults, 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, createEngine, createPreparedStatements, createRelation, createRelationStatements, deduplicateResults, 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

@@ -871,14 +871,41 @@ function cosineSimilarity(a, b) {
   const denom = Math.sqrt(normA) * Math.sqrt(normB);
   return denom === 0 ? 0 : dot / denom;
 }
-function applyActivationWeighting(results) {
-  return results.map((r) => {
-    const activationWeight = 0.5 + 0.5 * r.memory.activationScore;
-    return {
-      ...r,
-      score: r.score * activationWeight
-    };
-  }).sort((a, b) => b.score - a.score);
+function applyThreeFactorReranking(results, weights) {
+  if (results.length === 0) return results;
+  const w = {
+    recency: weights?.recency ?? 1,
+    importance: weights?.importance ?? 1,
+    relevance: weights?.relevance ?? 1
+  };
+  const now = Date.now();
+  const scored = results.map((r) => {
+    const hoursSince = (now - new Date(r.memory.learnedAt).getTime()) / (1e3 * 60 * 60);
+    const recency = Math.pow(0.995, Math.max(0, hoursSince));
+    const importance = r.memory.salience ?? 1;
+    const relevance = r.score;
+    return { ...r, recency, importance, relevance };
+  });
+  const NORM_EPSILON = 0.01;
+  const safeNormalize = (values) => {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of values) {
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+    const range = max - min;
+    if (range < NORM_EPSILON) return values.map(() => 1);
+    return values.map((v) => (v - min) / range);
+  };
+  const recencies = safeNormalize(scored.map((s) => s.recency));
+  const importances = safeNormalize(scored.map((s) => s.importance));
+  const relevances = safeNormalize(scored.map((s) => s.relevance));
+  return scored.map((s, i) => ({
+    memory: s.memory,
+    score: w.recency * recencies[i] + w.importance * importances[i] + w.relevance * relevances[i],
+    matchType: s.matchType
+  })).sort((a, b) => b.score - a.score);
 }
 function deduplicateResults(results) {
   const seen = /* @__PURE__ */ new Set();
@@ -929,7 +956,7 @@ function searchMemories(db, query, queryVec, useVecTable = true) {
   const ftsResults = ftsSearch(db, query);
   let finalResults;
   if (!queryVec) {
-    const weighted = applyActivationWeighting(ftsResults);
+    const weighted = applyThreeFactorReranking(ftsResults);
     const boosted = applyKeywordBoost(weighted, queryTokens);
     finalResults = deduplicateResults(boosted);
     updateAccessTracking(db, finalResults.map((r) => r.memory.memoryId));
@@ -955,11 +982,11 @@ function searchMemories(db, query, queryVec, useVecTable = true) {
       // Convert distance back to similarity
       matchType: "vector"
     }));
-    const weighted = applyActivationWeighting(vecOnly);
+    const weighted = applyThreeFactorReranking(vecOnly);
     const boosted = applyKeywordBoost(weighted, queryTokens);
     finalResults = deduplicateResults(boosted);
   } else if (vecResults.length === 0) {
-    const weighted = applyActivationWeighting(ftsResults);
+    const weighted = applyThreeFactorReranking(ftsResults);
     const boosted = applyKeywordBoost(weighted, queryTokens);
     finalResults = deduplicateResults(boosted);
   } else {
@@ -972,7 +999,7 @@ function searchMemories(db, query, queryVec, useVecTable = true) {
         score: r.score * (vecIds.has(r.memory.memoryId) ? 1.3 : 1)
       }));
       reranked.sort((a, b) => b.score - a.score);
-      const weighted = applyActivationWeighting(reranked);
+      const weighted = applyThreeFactorReranking(reranked);
       const boosted = applyKeywordBoost(weighted, queryTokens);
       finalResults = deduplicateResults(boosted);
     } else {
@@ -988,7 +1015,7 @@ function searchMemories(db, query, queryVec, useVecTable = true) {
           matchType: "hybrid"
         });
       }
-      const weighted = applyActivationWeighting(ftsItems);
+      const weighted = applyThreeFactorReranking(ftsItems);
       const boosted = applyKeywordBoost(weighted, queryTokens);
       finalResults = deduplicateResults(boosted);
     }
@@ -1024,6 +1051,16 @@ function computeActivation(accessTimestamps, salience, now) {
   const activation = sum > 0 ? Math.log(sum) + beta : beta * 0.1;
   return sigmoid(activation);
 }
+function computeEbbinghaus(accessCount, lastAccessedAt, now) {
+  const currentTime = now ?? /* @__PURE__ */ new Date();
+  if (!lastAccessedAt) {
+    return 0.1;
+  }
+  const S = Math.max(1, accessCount);
+  const t = (currentTime.getTime() - new Date(lastAccessedAt).getTime()) / MS_PER_DAY;
+  if (t <= 0) return 1;
+  return Math.exp(-t / S);
+}
 function sigmoid(x) {
   return 1 / (1 + Math.exp(-x));
 }
@@ -1038,9 +1075,12 @@ var DEFAULT_TIER_CONFIG = {
 function determineTier(memory, config, now) {
   const cfg = config ?? DEFAULT_TIER_CONFIG;
   if (memory.tier === "hot") return "hot";
+  const accessCount = memory.accessCount ?? 0;
+  if (accessCount >= 10) return "hot";
   const currentTime = now ?? /* @__PURE__ */ new Date();
   const age = (currentTime.getTime() - new Date(memory.learnedAt).getTime()) / MS_PER_DAY2;
   if (age <= cfg.warmDays) return "warm";
+  if (memory.activationScore >= cfg.coldActivationThreshold) return "warm";
   return "cold";
 }
 function estimateTokens(content) {
@@ -1048,6 +1088,19 @@ function estimateTokens(content) {
 }
 
 // src/engine.ts
+function cosineSim(a, b) {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
 var SqliteMemoryEngine = class {
   db = null;
   stmts = null;
@@ -1102,14 +1155,26 @@ var SqliteMemoryEngine = class {
     if (this.options.contradictionDetector && this.options.embedder) {
       await this.checkContradictions(memory);
     }
+    await this.checkDuplicates(memory);
     return memory;
   }
   async storeBatch(inputs) {
     this.ensureInitialized();
+    let memories;
     if (this.options.embedder) {
-      return storeBatchAsync(this.db, this.stmts, inputs, this.options.embedder);
+      memories = await storeBatchAsync(this.db, this.stmts, inputs, this.options.embedder);
+    } else {
+      memories = storeBatchInTransaction(this.db, this.stmts, inputs);
+    }
+    if (this.options.contradictionDetector && this.options.embedder && memories.length <= 50) {
+      for (const memory of memories) {
+        try {
+          await this.checkContradictions(memory);
+        } catch {
+        }
+      }
     }
-    return storeBatchInTransaction(this.db, this.stmts, inputs);
+    return memories;
   }
   async getById(memoryId) {
     this.ensureInitialized();
@@ -1315,10 +1380,11 @@ var SqliteMemoryEngine = class {
     );
     const activationTransaction = db.transaction(() => {
       for (const mem of memories) {
-        const timestamps = [mem.learned_at, mem.last_accessed_at].filter(
-          (t) => t != null
+        const ebbinghaus = computeEbbinghaus(
+          mem.access_count ?? 0,
+          mem.last_accessed_at ?? null
         );
-        const score = computeActivation(timestamps, mem.salience);
+        const score = ebbinghaus * 0.8 + (mem.salience ?? 1) * 0.2;
         updateActivation.run(score, mem.memory_id);
         activationUpdated++;
       }
@@ -1336,7 +1402,8 @@ var SqliteMemoryEngine = class {
         const newTier = determineTier({
           learnedAt: mem.learned_at,
           activationScore: mem.activation_score ?? 1,
-          tier: mem.tier ?? "warm"
+          tier: mem.tier ?? "warm",
+          accessCount: mem.access_count ?? 0
         });
         if (newTier !== (mem.tier ?? "warm")) {
           updateTier.run(newTier, mem.memory_id);
@@ -1405,6 +1472,48 @@ var SqliteMemoryEngine = class {
     } catch {
     }
   }
+  /**
+   * Check for near-duplicate memories after storing.
+   * Uses direct cosine similarity (not the combined search score) to avoid
+   * false positives from the multi-factor reranking.
+   * If cosine similarity > 0.95, auto-create an 'updates' relation (new supersedes old).
+   * Only runs for single store() calls, not storeBatch() (too slow for bulk).
+   */
+  async checkDuplicates(newMemory) {
+    if (!this.options.embedder) return;
+    try {
+      const queryVec = await this.options.embedder.embed(newMemory.content);
+      const similar = searchMemories(
+        this.db,
+        {
+          userId: newMemory.userId,
+          query: newMemory.content,
+          limit: 5,
+          filters: { onlyLatest: true }
+        },
+        queryVec,
+        this.vectorEnabled
+      );
+      for (const result of similar.results) {
+        if (result.memory.memoryId === newMemory.memoryId) continue;
+        if (!result.memory.embedding || result.memory.embedding.length === 0) continue;
+        const embB = new Float32Array(result.memory.embedding);
+        const similarity = cosineSim(queryVec, embB);
+        if (similarity > 0.95) {
+          try {
+            await this.relate(
+              newMemory.memoryId,
+              result.memory.memoryId,
+              "updates",
+              `Auto-detected duplicate: cosine similarity ${similarity.toFixed(3)}`
+            );
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
   ensureInitialized() {
     if (!this.db || !this.stmts || !this.relStmts) {
       throw new Error("Engine not initialized. Call initialize() first.");
@@ -1418,10 +1527,12 @@ export {
   DEFAULT_TIER_CONFIG,
   SqliteMemoryEngine,
   applyKeywordBoost,
+  applyThreeFactorReranking,
   bruteForceVectorSearch,
   buildFtsQuery,
   buildSearchSql,
   computeActivation,
+  computeEbbinghaus,
   createEngine,
   createPreparedStatements,
   createRelation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memrosetta/core",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "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.18"
+    "@memrosetta/types": "0.2.19"
   },
   "optionalDependencies": {
-    "@memrosetta/embeddings": "0.2.18"
+    "@memrosetta/embeddings": "0.2.19"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",