@memrosetta/core 0.2.18 → 0.2.20

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import Database from 'better-sqlite3';
-import { Memory, MemoryInput, RelationType, MemoryRelation, SearchResult, SearchFilters, SearchQuery, SearchResponse, IMemoryEngine, CompressResult, MaintenanceResult, MemoryTier, TierConfig } from '@memrosetta/types';
+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';
 
 interface SchemaOptions {
@@ -12,6 +12,13 @@ declare function generateMemoryId(): string;
 declare function nowIso(): string;
 declare function keywordsToString(keywords: readonly string[] | undefined): string | null;
 declare function stringToKeywords(str: string | null): readonly string[];
+/**
+ * Derive the logical state of a memory from its existing fields.
+ * - invalidated: invalidatedAt is set (takes precedence)
+ * - superseded: isLatest is false
+ * - current: isLatest is true and not invalidated
+ */
+declare function deriveMemoryState(memory: Memory): MemoryState;
 
 interface MemoryRow {
     readonly id: number;
@@ -160,6 +167,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.
@@ -189,7 +211,7 @@ declare function updateAccessTracking(db: Database.Database, memoryIds: readonly
  *
  * Results are weighted by activation score and access tracking is updated.
  */
-declare function searchMemories(db: Database.Database, query: SearchQuery, queryVec?: Float32Array, useVecTable?: boolean): SearchResponse;
+declare function searchMemories(db: Database.Database, query: SearchQuery, queryVec?: Float32Array, useVecTable?: boolean, skipAccessTracking?: boolean): SearchResponse;
 
 interface SqliteEngineOptions {
     readonly dbPath: string;
@@ -220,6 +242,7 @@ declare class SqliteMemoryEngine implements IMemoryEngine {
     compress(userId: string): Promise<CompressResult>;
     maintain(userId: string): Promise<MaintenanceResult>;
     setTier(memoryId: string, tier: MemoryTier): Promise<void>;
+    quality(userId: string): Promise<MemoryQuality>;
     /**
      * Check the newly stored memory against existing similar memories
      * for contradictions using the NLI model.
@@ -231,6 +254,23 @@ 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;
+    /**
+     * Auto-create 'extends' relations when a new memory shares keywords
+     * with existing memories. Builds graph density for future graph-based retrieval.
+     *
+     * Only runs for individual store() calls, not storeBatch().
+     * Requires at least 2 overlapping keywords to create a relation.
+     * Graceful: errors are silently swallowed.
+     */
+    private autoRelate;
     private ensureInitialized;
 }
 declare function createEngine(options: SqliteEngineOptions): SqliteMemoryEngine;
@@ -257,19 +297,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 +328,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, 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

@@ -183,6 +183,11 @@ function stringToKeywords(str) {
   if (!str || str.trim() === "") return [];
   return str.split(" ").filter((s) => s.length > 0);
 }
+function deriveMemoryState(memory) {
+  if (memory.invalidatedAt) return "invalidated";
+  if (!memory.isLatest) return "superseded";
+  return "current";
+}
 
 // src/mapper.ts
 function rowToMemory(row) {
@@ -608,9 +613,29 @@ function buildSearchSql(query) {
     whereClauses.push("m.confidence >= ?");
     params.push(filters.minConfidence);
   }
-  const onlyLatest = filters?.onlyLatest ?? true;
-  if (onlyLatest) {
-    whereClauses.push("m.is_latest = 1");
+  if (filters?.states && filters.states.length > 0) {
+    const stateConditions = [];
+    if (filters.states.includes("current")) {
+      stateConditions.push("(m.is_latest = 1 AND m.invalidated_at IS NULL)");
+    }
+    if (filters.states.includes("superseded")) {
+      stateConditions.push("(m.is_latest = 0)");
+    }
+    if (filters.states.includes("invalidated")) {
+      stateConditions.push("(m.invalidated_at IS NOT NULL)");
+    }
+    if (stateConditions.length > 0) {
+      whereClauses.push(`(${stateConditions.join(" OR ")})`);
+    }
+  } else {
+    const onlyLatest = filters?.onlyLatest ?? true;
+    if (onlyLatest) {
+      whereClauses.push("m.is_latest = 1");
+    }
+    const excludeInvalidated = filters?.excludeInvalidated ?? true;
+    if (excludeInvalidated) {
+      whereClauses.push("m.invalidated_at IS NULL");
+    }
   }
   if (filters?.eventDateRange?.start) {
     whereClauses.push("m.event_date_start >= ?");
@@ -620,10 +645,6 @@ function buildSearchSql(query) {
     whereClauses.push("m.event_date_end <= ?");
     params.push(filters.eventDateRange.end);
   }
-  const excludeInvalidated = filters?.excludeInvalidated ?? true;
-  if (excludeInvalidated) {
-    whereClauses.push("m.invalidated_at IS NULL");
-  }
   const limit = query.limit ?? DEFAULT_LIMIT;
   params.push(limit);
   const sql = [
@@ -676,9 +697,29 @@ function ftsSearch(db, query) {
 function bruteForceVectorSearch(db, queryVec, userId, limit, filters) {
   const whereClauses = ["user_id = ?", "embedding IS NOT NULL"];
   const params = [userId];
-  const onlyLatest = filters?.onlyLatest ?? true;
-  if (onlyLatest) {
-    whereClauses.push("is_latest = 1");
+  if (filters?.states && filters.states.length > 0) {
+    const stateConditions = [];
+    if (filters.states.includes("current")) {
+      stateConditions.push("(is_latest = 1 AND invalidated_at IS NULL)");
+    }
+    if (filters.states.includes("superseded")) {
+      stateConditions.push("(is_latest = 0)");
+    }
+    if (filters.states.includes("invalidated")) {
+      stateConditions.push("(invalidated_at IS NOT NULL)");
+    }
+    if (stateConditions.length > 0) {
+      whereClauses.push(`(${stateConditions.join(" OR ")})`);
+    }
+  } else {
+    const onlyLatest = filters?.onlyLatest ?? true;
+    if (onlyLatest) {
+      whereClauses.push("is_latest = 1");
+    }
+    const excludeInvalidated = filters?.excludeInvalidated ?? true;
+    if (excludeInvalidated) {
+      whereClauses.push("invalidated_at IS NULL");
+    }
   }
   if (filters?.memoryTypes && filters.memoryTypes.length > 0) {
     const mtPlaceholders = filters.memoryTypes.map(() => "?").join(",");
@@ -707,10 +748,6 @@ function bruteForceVectorSearch(db, queryVec, userId, limit, filters) {
     whereClauses.push("event_date_end <= ?");
     params.push(filters.eventDateRange.end);
   }
-  const excludeInvalidated = filters?.excludeInvalidated ?? true;
-  if (excludeInvalidated) {
-    whereClauses.push("invalidated_at IS NULL");
-  }
   const sql = `SELECT * FROM memories WHERE ${whereClauses.join(" AND ")}`;
   const rows = db.prepare(sql).all(...params);
   if (rows.length === 0) {
@@ -748,9 +785,29 @@ function vectorSearch(db, queryVec, userId, limit, filters, useVecTable = true)
   const placeholders = rowids.map(() => "?").join(",");
   let sql = `SELECT * FROM memories WHERE id IN (${placeholders}) AND user_id = ?`;
   const params = [...rowids, userId];
-  const onlyLatest = filters?.onlyLatest ?? true;
-  if (onlyLatest) {
-    sql += " AND is_latest = 1";
+  if (filters?.states && filters.states.length > 0) {
+    const stateConditions = [];
+    if (filters.states.includes("current")) {
+      stateConditions.push("(is_latest = 1 AND invalidated_at IS NULL)");
+    }
+    if (filters.states.includes("superseded")) {
+      stateConditions.push("(is_latest = 0)");
+    }
+    if (filters.states.includes("invalidated")) {
+      stateConditions.push("(invalidated_at IS NOT NULL)");
+    }
+    if (stateConditions.length > 0) {
+      sql += ` AND (${stateConditions.join(" OR ")})`;
+    }
+  } else {
+    const onlyLatest = filters?.onlyLatest ?? true;
+    if (onlyLatest) {
+      sql += " AND is_latest = 1";
+    }
+    const excludeInvalidated = filters?.excludeInvalidated ?? true;
+    if (excludeInvalidated) {
+      sql += " AND invalidated_at IS NULL";
+    }
   }
   if (filters?.memoryTypes && filters.memoryTypes.length > 0) {
     const mtPlaceholders = filters.memoryTypes.map(() => "?").join(",");
@@ -779,10 +836,6 @@ function vectorSearch(db, queryVec, userId, limit, filters, useVecTable = true)
     sql += " AND event_date_end <= ?";
     params.push(filters.eventDateRange.end);
   }
-  const excludeInvalidated = filters?.excludeInvalidated ?? true;
-  if (excludeInvalidated) {
-    sql += " AND invalidated_at IS NULL";
-  }
   const rows = db.prepare(sql).all(...params);
   return rows.map((row) => ({
     memory: rowToMemory(row),
@@ -871,14 +924,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();
@@ -923,16 +1003,18 @@ function updateAccessTracking(db, memoryIds) {
   });
   updateAll(memoryIds);
 }
-function searchMemories(db, query, queryVec, useVecTable = true) {
+function searchMemories(db, query, queryVec, useVecTable = true, skipAccessTracking = false) {
   const startTime = performance.now();
   const queryTokens = extractQueryTokens(query.query);
   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));
+    if (!skipAccessTracking) {
+      updateAccessTracking(db, finalResults.map((r) => r.memory.memoryId));
+    }
     return {
       results: finalResults,
       totalCount: finalResults.length,
@@ -955,11 +1037,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 +1054,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 +1070,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 +1106,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 +1130,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) {
@@ -1102,14 +1197,27 @@ var SqliteMemoryEngine = class {
     if (this.options.contradictionDetector && this.options.embedder) {
       await this.checkContradictions(memory);
     }
+    await this.checkDuplicates(memory);
+    await this.autoRelate(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 +1423,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 +1445,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);
@@ -1357,6 +1467,41 @@ var SqliteMemoryEngine = class {
     this.ensureInitialized();
     this.db.prepare("UPDATE memories SET tier = ? WHERE memory_id = ?").run(tier, memoryId);
   }
+  async quality(userId) {
+    this.ensureInitialized();
+    const db = this.db;
+    const total = db.prepare("SELECT COUNT(*) as c FROM memories WHERE user_id = ?").get(userId).c;
+    const fresh = db.prepare(
+      "SELECT COUNT(*) as c FROM memories WHERE user_id = ? AND is_latest = 1 AND invalidated_at IS NULL"
+    ).get(userId).c;
+    const invalidated = db.prepare(
+      "SELECT COUNT(*) as c FROM memories WHERE user_id = ? AND invalidated_at IS NOT NULL"
+    ).get(userId).c;
+    const superseded = db.prepare(
+      "SELECT COUNT(*) as c FROM memories WHERE user_id = ? AND is_latest = 0"
+    ).get(userId).c;
+    const withRelations = db.prepare(`
+        SELECT COUNT(DISTINCT mid) as c FROM (
+          SELECT src_memory_id as mid FROM memory_relations
+            WHERE src_memory_id IN (SELECT memory_id FROM memories WHERE user_id = ?)
+          UNION
+          SELECT dst_memory_id as mid FROM memory_relations
+            WHERE dst_memory_id IN (SELECT memory_id FROM memories WHERE user_id = ?)
+        )
+      `).get(userId, userId).c;
+    const avgRow = db.prepare(
+      "SELECT AVG(activation_score) as avg FROM memories WHERE user_id = ? AND is_latest = 1"
+    ).get(userId);
+    const avgActivation = avgRow.avg ?? 0;
+    return {
+      total,
+      fresh,
+      invalidated,
+      superseded,
+      withRelations,
+      avgActivation
+    };
+  }
   /**
    * Check the newly stored memory against existing similar memories
    * for contradictions using the NLI model.
@@ -1382,7 +1527,9 @@ var SqliteMemoryEngine = class {
           filters: { onlyLatest: true }
         },
         queryVec,
-        this.vectorEnabled
+        this.vectorEnabled,
+        true
+        // skipAccessTracking
       );
       for (const result of similar.results) {
         if (result.memory.memoryId === newMemory.memoryId) continue;
@@ -1405,6 +1552,91 @@ 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 candidates = bruteForceVectorSearch(
+        this.db,
+        queryVec,
+        newMemory.userId,
+        10,
+        { onlyLatest: true }
+      );
+      for (const candidate of candidates) {
+        if (candidate.memory.memoryId === newMemory.memoryId) continue;
+        const similarity = 1 - candidate.distance;
+        if (similarity > 0.95) {
+          try {
+            await this.relate(
+              newMemory.memoryId,
+              candidate.memory.memoryId,
+              "updates",
+              `Auto-detected duplicate: cosine similarity ${similarity.toFixed(3)}`
+            );
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  /**
+   * Auto-create 'extends' relations when a new memory shares keywords
+   * with existing memories. Builds graph density for future graph-based retrieval.
+   *
+   * Only runs for individual store() calls, not storeBatch().
+   * Requires at least 2 overlapping keywords to create a relation.
+   * Graceful: errors are silently swallowed.
+   */
+  async autoRelate(newMemory) {
+    if (!newMemory.keywords || newMemory.keywords.length === 0) return;
+    try {
+      const keywordList = newMemory.keywords;
+      const existing = this.db.prepare(`
+        SELECT memory_id, keywords FROM memories
+        WHERE user_id = ? AND is_latest = 1 AND memory_id != ?
+        AND invalidated_at IS NULL
+        ORDER BY learned_at DESC LIMIT 10
+      `).all(newMemory.userId, newMemory.memoryId);
+      for (const row of existing) {
+        if (!row.keywords) continue;
+        const existingKeywords = row.keywords.split(" ").map((k) => k.trim().toLowerCase());
+        const overlap = keywordList.filter((k) => existingKeywords.includes(k.toLowerCase()));
+        if (overlap.length >= 3) {
+          const existingRelation = this.db.prepare(
+            `SELECT 1 FROM memory_relations
+             WHERE (src_memory_id = ? AND dst_memory_id = ?)
+                OR (src_memory_id = ? AND dst_memory_id = ?)
+             LIMIT 1`
+          ).get(
+            newMemory.memoryId,
+            row.memory_id,
+            row.memory_id,
+            newMemory.memoryId
+          );
+          if (existingRelation) continue;
+          try {
+            await this.relate(
+              newMemory.memoryId,
+              row.memory_id,
+              "extends",
+              `Auto: ${overlap.length} shared keywords (${overlap.join(", ")})`
+            );
+          } catch {
+          }
+        }
+      }
+    } catch {
+    }
+  }
   ensureInitialized() {
     if (!this.db || !this.stmts || !this.relStmts) {
       throw new Error("Engine not initialized. Call initialize() first.");
@@ -1418,15 +1650,18 @@ export {
   DEFAULT_TIER_CONFIG,
   SqliteMemoryEngine,
   applyKeywordBoost,
+  applyThreeFactorReranking,
   bruteForceVectorSearch,
   buildFtsQuery,
   buildSearchSql,
   computeActivation,
+  computeEbbinghaus,
   createEngine,
   createPreparedStatements,
   createRelation,
   createRelationStatements,
   deduplicateResults,
+  deriveMemoryState,
   determineTier,
   ensureSchema,
   estimateTokens,

package/package.json

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