memories-lite 0.9.0

package/src/vectorstores/lite.ts

@@ -0,0 +1,402 @@
+// vector persistence
+import path from 'path';
+import sqlite3 from 'sqlite3';  
+
+import { VectorStore } from "./base";
+import { SearchFilters, VectorStoreConfig, VectorStoreResult, MemoryPayload, MemoryScoringConfig, MemoryType } from "../types";
+import { createHash } from 'crypto';
+
+
+// Define interface for database rows
+interface MemoryVector {
+  id: string;
+  vector: number[];
+  payload: Record<string, any>;
+}
+/**
+ * LiteVectorStore provides a simple vector storage implementation.
+ * 
+ * This class manages user-sensitive vector data, with each instance tied to a specific user.
+ * Data is stored in a local SQLite database with appropriate isolation between users.
+ * The user's identity is hashed for privacy and security purposes.
+ * ⚠️ User memories are typically small (usually <1000 vectors), therefore database optimization is not a priority.
+ * 
+ * @implements {VectorStore}
+ */
+export class LiteVectorStore implements VectorStore {
+  private db: sqlite3.Database;
+  private isSecure: boolean;
+  private dimension: number;
+  private currentUserId: string;
+  private scoringConfig: MemoryScoringConfig;
+  private cleanupThreshold?: number; // Store the threshold
+  private static cache: Map<string, LiteVectorStore>;
+  constructor(config: VectorStoreConfig, currentUserId: string) {
+    if (!config.scoring) {
+      throw new Error("Scoring configuration is missing in VectorStoreConfig");
+    }
+    this.dimension = config.dimension || 1536;
+    this.currentUserId = currentUserId;
+    this.isSecure = config.secure || false;
+    this.scoringConfig = config.scoring;
+    this.cleanupThreshold = config.recencyCleanupThreshold; // Store threshold
+    config.rootPath = config.rootPath || process.cwd();
+    const filename = this.isSecure ? `memories-lite-${currentUserId}.db` : `memories-lite-global.db`;
+    const dbPath = (config.rootPath == ':memory:') ? ':memory:' : path.join(config.rootPath, filename);
+
+    // Add error handling callback for the database connection
+    this.db = new sqlite3.Database(dbPath);
+  }
+
+
+  private async init() {
+    await this.run(`
+      CREATE TABLE IF NOT EXISTS vectors (
+        id TEXT PRIMARY KEY,
+        vector BLOB NOT NULL,
+        payload TEXT NOT NULL
+      )
+    `);
+
+    await this.run(`
+      CREATE TABLE IF NOT EXISTS memory_migrations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id TEXT NOT NULL UNIQUE
+      )
+    `);
+  }
+
+  private async run(sql: string, params: any[] = []): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.db.run(sql, params, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    });
+  }
+
+  private async all(sql: string, params: any[] = []): Promise<any[]> {
+    return new Promise((resolve, reject) => {
+      this.db.all(sql, params, (err, rows) => {
+        if (err) reject(err);
+        else resolve(rows);
+      });
+    });
+  }
+
+  private async getOne(sql: string, params: any[] = []): Promise<any> {
+    return new Promise((resolve, reject) => {
+      this.db.get(sql, params, (err, row) => {
+        if (err) reject(err);
+        else resolve(row);
+      });
+    });
+  }  
+
+
+  //
+  // TODO: Memory Decay & Hybrid Scoring (α·cosSim + β·when + γ·1 [+ δ·tag])
+  // scoreTotal = α·cos + β·recency + γ·1 + δ·tag
+  // https://chatgpt.com/g/g-p-677932764d20819181f8805995ddab8b-the-coder/c/68121341-7fdc-800b-8734-af49719eb5e1
+  private cosineSimilarity(a: number[], b: number[]): number {
+    if (a.length !== b.length) {
+      throw new Error("Vectors must have the same dimension for cosine similarity.");
+    }
+    if (a.length === 0) {
+      return 0;
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+      dotProduct += a[i] * b[i];
+      normA += a[i] * a[i];
+      normB += b[i] * b[i];
+    }
+    const magnitudeA = Math.sqrt(normA);
+    const magnitudeB = Math.sqrt(normB);
+    if (magnitudeA === 0 || magnitudeB === 0) {
+      return 0;
+    }
+    return dotProduct / (magnitudeA * magnitudeB);
+  }
+
+  private filterVector(vector: MemoryVector, filters?: SearchFilters): boolean {
+    if (!filters) return true;
+    return Object.entries(filters).every(
+      ([key, value]) => vector.payload && vector.payload[key] === value,
+    );
+  }
+
+  // by default, the userId is the SHA256 derivation 
+  getInstanceId(): string {
+    return this.currentUserId;
+  }
+
+  static async from(userId: string, config: VectorStoreConfig): Promise<LiteVectorStore> {
+    if (!userId) {
+      throw new Error("userId is required");
+    }
+    if (!config.scoring) {
+      throw new Error("Scoring configuration is missing in VectorStoreConfig");
+    }
+
+    const hashedUserId = createHash('sha256').update(userId).digest('hex');
+
+    if (!LiteVectorStore.cache) {
+      LiteVectorStore.cache = new Map<string, LiteVectorStore>();
+    }
+
+    const cachedStore = LiteVectorStore.cache.get(hashedUserId);
+    if (cachedStore) {
+      Object.setPrototypeOf(cachedStore, LiteVectorStore.prototype);
+      cachedStore.currentUserId = hashedUserId;
+      // Ensure scoring config and threshold are updated if config object changed
+      cachedStore.scoringConfig = config.scoring;
+      cachedStore.cleanupThreshold = config.recencyCleanupThreshold;
+      return cachedStore;
+    }
+
+    // Pass the full config (including scoring) to the constructor
+    const newStore = new LiteVectorStore(config, hashedUserId);
+
+    await newStore.init();
+    LiteVectorStore.cache.set(hashedUserId, newStore);
+    return newStore;
+  }
+
+  async insert(
+    vectors: number[][],
+    ids: string[],
+    payloads: Record<string, any>[],
+  ): Promise<void> {
+    for (let i = 0; i < vectors.length; i++) {
+      if (vectors[i].length !== this.dimension) {
+        throw new Error(
+          `Vector dimension mismatch. Expected ${this.dimension}, got ${vectors[i].length}`,
+        );
+      }
+      //
+      // remove the userId from the payload as sensitive data
+      this.isSecure && delete payloads[i].userId;
+      const vectorBuffer = Buffer.from(new Float32Array(vectors[i]).buffer);
+      await this.run(
+        `INSERT OR REPLACE INTO vectors (id, vector, payload) VALUES (?, ?, ?)`,
+        [ids[i], vectorBuffer, JSON.stringify(payloads[i])],
+      );
+    }
+
+  }
+
+  async search(
+    query: number[],
+    limit: number = 10,
+    filters?: SearchFilters,
+  ): Promise<VectorStoreResult[]> {
+    if (query.length !== this.dimension) {
+      throw new Error(
+        `Query dimension mismatch. Expected ${this.dimension}, got ${query.length}`,
+      );
+    }
+
+    const results: VectorStoreResult[] = [];
+    const rows = await this.all(`SELECT * FROM vectors`);
+
+    for (const row of rows) {
+      const vector = Array.from(new Float32Array(row.vector.buffer)); // Convert buffer to number array
+      const payload: MemoryPayload = JSON.parse(row.payload);
+      const memoryVector: MemoryVector = {
+        id: row.id,
+        vector: vector,
+        payload,
+      };
+
+      if (this.filterVector(memoryVector, filters)) {
+        const cosineScore = this.cosineSimilarity(query, vector);
+        const hybridScore = this.calculateHybridScore(cosineScore, payload);
+
+        results.push({
+          id: memoryVector.id,
+          payload: memoryVector.payload,
+          score: hybridScore,
+        });
+      }
+    }
+
+    results.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const finalResults = results.slice(0, limit);
+
+    // Trigger cleanup after search, if threshold is set
+    if (this.cleanupThreshold !== undefined && this.cleanupThreshold >= 0) {
+      // Run cleanup asynchronously in the background (fire and forget)
+      // to avoid delaying the search response.
+      // Consider adding mutex or debouncing in high-frequency scenarios.
+      this._cleanupByRecency(this.cleanupThreshold).catch(err => {
+        console.error("Error during background recency cleanup:", err);
+      });
+    }
+
+    return finalResults;
+  }
+
+  async get(vectorId: string): Promise<VectorStoreResult | null> {
+    const row = await this.getOne(`SELECT * FROM vectors WHERE id = ?`, [
+      vectorId,
+    ]);
+    if (!row) return null;
+
+    const payload = JSON.parse(row.payload);
+    return {
+      id: row.id,
+      payload,
+    };
+  }
+
+  async update(
+    vectorId: string,
+    vector: number[],
+    payload: Record<string, any>,
+  ): Promise<void> {
+    if (vector.length !== this.dimension) {
+      throw new Error(
+        `Vector dimension mismatch. Expected ${this.dimension}, got ${vector.length}`,
+      );
+    }
+    //
+    // remove the userId from the payload as sensitive data
+    this.isSecure && delete payload.userId;
+    const vectorBuffer = Buffer.from(new Float32Array(vector).buffer);
+    await this.run(`UPDATE vectors SET vector = ?, payload = ? WHERE id = ?`, [
+      vectorBuffer,
+      JSON.stringify(payload),
+      vectorId,
+    ]);
+  }
+
+  async delete(vectorId: string): Promise<void> {
+    await this.run(`DELETE FROM vectors WHERE id = ?`, [vectorId]);
+  }
+
+  async deleteCol(): Promise<void> {
+    await this.run(`DROP TABLE IF EXISTS vectors`);
+    await this.init();
+  }
+
+
+  async list(
+    filters?: SearchFilters,
+    limit: number = 100,
+  ): Promise<[VectorStoreResult[], number]> {
+    const rows = await this.all(`SELECT * FROM vectors`);
+    const results: VectorStoreResult[] = [];
+
+    for (const row of rows) {
+      const memoryVector: MemoryVector = {
+        id: row.id,
+        vector: Array.from(new Float32Array(row.vector.buffer)),
+        payload: {},
+      };
+
+      if (this.filterVector(memoryVector, filters)) {
+        // load payload at the end
+        results.push({
+          id: memoryVector.id,
+          payload: JSON.parse(row.payload),
+        });
+      }
+    }
+
+    return [results.slice(0, limit), results.length];
+  }
+
+  // Calculate recency score using exponential decay
+  private calculateRecencyScore(createdAt: string, halfLifeDays: number): number {
+    if (halfLifeDays === Infinity || !createdAt) {
+      return 1.0; // No decay or no date
+    }
+    if (halfLifeDays <= 0) {
+      return 0.0; // Instant decay
+    }
+
+    const createdAtDate = new Date(createdAt);
+    if (isNaN(createdAtDate.getTime())) {
+        console.warn('Invalid createdAt date format:', createdAt);
+        return 0.5; // Neutral score if date is invalid
+    }
+
+    const now = new Date();
+    const ageInMilliseconds = now.getTime() - createdAtDate.getTime();
+    const ageInDays = ageInMilliseconds / (1000 * 60 * 60 * 24);
+
+    if (ageInDays < 0) {
+      console.warn('createdAt date is in the future:', createdAt);
+      return 1.0; // Treat future dates as brand new
+    }
+
+    const lambda = Math.log(2) / halfLifeDays;
+    return Math.exp(-lambda * ageInDays);
+  }
+
+  // Hybrid Scoring: Combines Cosine Similarity, Recency, and Base Importance
+  private calculateHybridScore(cosineScore: number, payload: MemoryPayload): number {
+    const memoryType: MemoryType | undefined = payload.type;
+    const createdAt = payload.createdAt; // Expecting ISO string
+
+    // Get scoring parameters for the memory type or use default
+    const typeConfig = memoryType ? this.scoringConfig[memoryType] : this.scoringConfig.default;
+    const { alpha, beta, gamma, halfLifeDays } = typeConfig || this.scoringConfig.default;
+
+    const recencyScore = this.calculateRecencyScore(createdAt, halfLifeDays);
+
+    // Calculate final score
+    // scoreTotal = α * cosSim + β * recency + γ * baseImportance (using 1 as base)
+    const hybridScore = alpha * cosineScore + beta * recencyScore + gamma;
+
+    // Ensure score is within a reasonable range (e.g., 0 to alpha+beta+gamma)
+    return Math.max(0, hybridScore);
+  }
+
+  // Internal method to clean up vectors based on recency score threshold
+  private async _cleanupByRecency(threshold: number): Promise<number> {
+    const rows = await this.all(`SELECT id, payload FROM vectors`);
+    let deletedCount = 0;
+    const idsToDelete: string[] = [];
+
+    for (const row of rows) {
+      try {
+        const payload: MemoryPayload = JSON.parse(row.payload);
+        const memoryType: MemoryType | undefined = payload.type;
+        const createdAt = payload.createdAt;
+
+        // Get halfLifeDays for the type or use default
+        const typeConfig = memoryType ? this.scoringConfig[memoryType] : this.scoringConfig.default;
+        const { halfLifeDays } = typeConfig || this.scoringConfig.default;
+
+        // Calculate current recency score
+        const recencyScore = this.calculateRecencyScore(createdAt, halfLifeDays);
+
+        // Mark for deletion if score is below threshold
+        // Add extra check for halfLifeDays > 0 to avoid deleting permanent items instantly if threshold is 0
+        if (recencyScore < threshold && halfLifeDays > 0) {
+            // Optional: Add type-specific exceptions (e.g., never delete 'factual')
+            // if (payload.type !== 'factual') {
+                 idsToDelete.push(row.id);
+            // }
+        }
+      } catch (error) {
+        console.error(`Error processing vector ${row.id} for cleanup:`, error);
+        // Optionally delete vectors with bad payload/date based on policy
+      }
+    }
+
+    if (idsToDelete.length > 0) {
+      const placeholders = idsToDelete.map(() => '?').join(',');
+      await this.run(`DELETE FROM vectors WHERE id IN (${placeholders})`, idsToDelete);
+      deletedCount = idsToDelete.length;
+      console.log(`Recency Cleanup: Removed ${deletedCount} vectors with score < ${threshold}.`);
+    }
+
+    return deletedCount;
+  }
+
+}

package/src/vectorstores/llm.ts

@@ -0,0 +1,126 @@
+// Linter errors exist because './base' or '../types' might be incorrect paths or lack expected exports.
+// Ensure VectorStore is exported from './base.ts'
+// Ensure MemoryVector, SearchResult, SearchFilters, VectorStoreConfig are exported from '../types.ts'
+import { VectorStore } from './base';
+import { SearchFilters, VectorStoreConfig, VectorStoreResult } from '../types';
+
+
+export interface FakeVectorStore extends VectorStore {
+  lookup(query: string, limit?: number, filters?: SearchFilters): Promise<VectorStoreResult[]>;
+  dump(filePath?: string, userId?: string): Promise<void> ;
+  load(filePath?: string, userId?: string): Promise<void>;
+}
+
+interface MemoryVector {
+  id: string;
+  vector: number[];
+  payload: Record<string, any>;
+}
+
+// Removed fs and path imports as they are not needed for empty methods
+
+export class LLMVectorStore implements FakeVectorStore {
+
+  constructor(config?: VectorStoreConfig) {
+    console.log('LLMVectorStore initialized', config);
+    // Initialization logic based on config, if any
+  }
+
+
+  async dump(filePath?: string, userId?: string): Promise<void> {
+    // TODO: Implement LLMVectorStore dump logic
+    console.log('LLMVectorStore dump called for:', userId || 'all users', 'to path:', filePath);
+    // Placeholder implementation
+  }
+
+  async load(filePath?: string, userId?: string): Promise<void> {
+    // TODO: Implement LLMVectorStore load logic
+    console.log('LLMVectorStore load called for:', userId || 'all users', 'from path:', filePath);
+    // Placeholder implementation
+  }
+
+
+  async add(record: MemoryVector, userId?: string): Promise<string> {
+    // TODO: Implement LLMVectorStore add logic
+    console.log('LLMVectorStore add called with:', record, userId);
+    return 'placeholder-id'; // Placeholder return
+  }
+
+  async search(query: number[], limit?: number, filters?: SearchFilters): Promise<VectorStoreResult[]> {
+    return [];
+  }
+
+
+  async lookup(query: string, limit?: number, filters?: SearchFilters): Promise<VectorStoreResult[]> {
+    // TODO: Implement LLMVectorStore search logic using query vector
+    // Note: userId parameter is removed as it's not in the base interface signature.
+    // If userId is needed, it might have to be passed via filters or managed differently.
+    console.log('LLMVectorStore search called with vector query:', query, 'limit:', limit, 'filters:', filters);
+    // Linter error on VectorStoreResult likely means its definition in ../types.ts needs checking/creation.
+    return []; // Placeholder return
+  }
+
+  async get(id: string, userId?: string): Promise<MemoryVector | null> {
+    // TODO: Implement LLMVectorStore get logic
+    console.log('LLMVectorStore get called with:', id, userId);
+    return null; // Placeholder return
+  }
+
+  async update(vectorId: string, vector: number[], payload: Record<string, any>): Promise<void> {
+    // TODO: Implement LLMVectorStore update logic matching the base interface
+    console.log('LLMVectorStore update called with:', vectorId, vector, payload);
+    // Placeholder implementation
+  }
+
+  async delete(id: string, userId?: string): Promise<void> {
+    // TODO: Implement LLMVectorStore delete logic
+    console.log('LLMVectorStore delete called with:', id, userId);
+    // Placeholder implementation
+  }
+
+  async reset(userId?: string): Promise<void> {
+    // TODO: Implement LLMVectorStore reset logic
+    console.log('LLMVectorStore reset called for:', userId || 'all users');
+    // Placeholder implementation
+  }
+
+  // TODO: Implement other missing methods from base VectorStore interface if needed
+
+  // Placeholder for missing method from VectorStore interface
+  async insert(vectors: number[][], ids: string[],payloads: Record<string, any>[],): Promise<void> {
+      // TODO: Implement LLMVectorStore insert logic
+  }
+
+  // Placeholder for missing method from VectorStore interface
+  async deleteCol(userId?: string): Promise<void> {
+      // TODO: Implement LLMVectorStore deleteCol logic
+      console.log('LLMVectorStore deleteCol called for:', userId || 'default collection');
+  }
+
+  // Placeholder for missing method from VectorStore interface
+  async list(filters?: SearchFilters,limit?: number): Promise<[VectorStoreResult[], number]>{
+      // TODO: Implement LLMVectorStore list logic
+      return [[],0];
+  }
+
+  // Placeholder for missing method from VectorStore interface
+  getInstanceId(): string {
+      // TODO: Implement LLMVectorStore getUserId logic (if applicable to this store)
+      console.log('LLMVectorStore getUserId called');
+      return 'placeholder-user-id'; // Or null if not managed per-user this way
+  }
+
+  // Placeholder for missing method from VectorStore interface
+  async setUserId(userId: string): Promise<void> {
+    // TODO: Implement LLMVectorStore setUserId logic (if applicable)
+    console.log('LLMVectorStore setUserId called with:', userId);
+  }
+
+  // Placeholder for missing method from VectorStore interface
+  async initialize(): Promise<void> {
+    // TODO: Implement LLMVectorStore initialize logic (if needed)
+    console.log('LLMVectorStore initialize called');
+  }
+
+  // Add any other methods required by the VectorStore interface or custom methods
+}

package/tests/lite.spec.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, jest } from '@jest/globals'; // Use Jest globals
+import { LiteVectorStore } from '../src/vectorstores/lite';
+import { VectorStoreConfig, MemoryPayload } from '../src/types';
+import { DEFAULT_MEMORY_CONFIG } from '../src/config/defaults'; // To get default scoring
+
+// Mock crypto using jest.mock
+jest.mock('crypto', () => ({
+  createHash: jest.fn().mockReturnThis(),
+  update: jest.fn().mockReturnThis(),
+  digest: jest.fn().mockReturnValue('hashed-user-id'),
+}));
+
+// Mock sqlite3 using jest.mock
+jest.mock('sqlite3', () => {
+    const mockDb = {
+        run: jest.fn((_sql: any, _params: any, callback: any) => callback(null)),
+        all: jest.fn((_sql: any, _params: any, callback: any) => callback(null, [])),
+        get: jest.fn((_sql: any, _params: any, callback: any) => callback(null, null)),
+        close: jest.fn((callback: any) => callback(null)),
+    };
+    return {
+        Database: jest.fn(() => mockDb),
+        verbose: jest.fn(() => ({ Database: jest.fn(() => mockDb) })), // Handle verbose()
+    };
+});
+
+
+describe('LiteVectorStore Private Methods', () => {
+  let store: LiteVectorStore;
+  const userId = 'test-user';
+  const mockConfig: VectorStoreConfig = {
+      ...DEFAULT_MEMORY_CONFIG.vectorStore.config, // Use defaults including scoring
+      rootPath: ':memory:', // Use in-memory for tests
+      dimension: 3, // Use smaller dimension for test vectors
+  };
+
+  beforeEach(() => {
+      // Reset mocks using Jest's API
+      jest.clearAllMocks();
+      // Create a new store instance before each test
+      store = new LiteVectorStore(mockConfig, userId);
+      // db interaction isn't needed for these calculation tests.
+  });
+
+  describe('calculateRecencyScore', () => {
+    const now = new Date();
+    const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000).toISOString();
+    const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const futureDate = new Date(now.getTime() + 1 * 24 * 60 * 60 * 1000).toISOString();
+
+    it('should return 1.0 for infinite half-life', () => {
+      const score = (store as any).calculateRecencyScore(sevenDaysAgo, Infinity);
+      expect(score).toBe(1.0);
+    });
+
+    it('should return 1.0 for missing createdAt date', () => {
+      const score = (store as any).calculateRecencyScore(undefined, 7);
+      expect(score).toBe(1.0);
+    });
+
+    it('should return 0.0 for zero half-life', () => {
+      const score = (store as any).calculateRecencyScore(sevenDaysAgo, 0);
+      expect(score).toBe(0.0);
+    });
+
+    it('should return ~0.5 for age equal to half-life (e.g., 7 days ago, HL=7)', () => {
+      const score = (store as any).calculateRecencyScore(sevenDaysAgo, 7);
+      expect(score).toBeCloseTo(0.5, 5); // Use toBeCloseTo for float comparisons
+    });
+
+    it('should return ~0.25 for age double the half-life (e.g., 4 days ago, HL=2)', () => {
+        const fourDaysAgo = new Date(now.getTime() - 4 * 24 * 60 * 60 * 1000).toISOString();
+        const score = (store as any).calculateRecencyScore(fourDaysAgo, 2);
+        expect(score).toBeCloseTo(0.25, 5);
+    });
+
+    it('should return 0.5 for invalid date format', () => {
+        const score = (store as any).calculateRecencyScore('invalid-date', 7);
+        expect(score).toBe(0.5);
+    });
+
+    it('should return 1.0 for future dates', () => {
+        const score = (store as any).calculateRecencyScore(futureDate, 7);
+        expect(score).toBe(1.0);
+    });
+
+    it('should handle negative ageInDays gracefully (treat as future)', () => {
+        // Mock Date.now() to simulate the scenario if needed, or test with future date
+        const score = (store as any).calculateRecencyScore(futureDate, 7);
+        expect(score).toBe(1.0);
+    });
+  });
+
+  describe('calculateHybridScore', () => {
+    const now = new Date();
+    const twoDaysAgo = new Date(now.getTime() - 2 * 24 * 60 * 60 * 1000).toISOString();
+    const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const veryOldDate = new Date(now.getTime() - 400 * 24 * 60 * 60 * 1000).toISOString();
+    const scoring = DEFAULT_MEMORY_CONFIG.vectorStore.config.scoring!;
+
+    it('should prioritize cosine similarity for factual memory (high alpha)', () => {
+      const payload: MemoryPayload = { memoryId: 'mem-f1', userId: userId, type: 'factual', createdAt: twoDaysAgo };
+      const cosineScore = 0.9;
+      const expectedRecency = (store as any).calculateRecencyScore(twoDaysAgo, scoring.factual.halfLifeDays);
+      const expectedScore = scoring.factual.alpha * cosineScore + scoring.factual.beta * expectedRecency + scoring.factual.gamma;
+      const hybridScore = (store as any).calculateHybridScore(cosineScore, payload);
+      expect(hybridScore).toBeCloseTo(expectedScore, 5);
+      expect(scoring.factual.alpha * cosineScore).toBeGreaterThan(scoring.factual.beta * expectedRecency);
+    });
+
+    it('should prioritize recency for episodic memory (high beta, short half-life)', () => {
+      const payload: MemoryPayload = { memoryId: 'mem-e1', userId: userId, type: 'episodic', createdAt: twoDaysAgo };
+      const cosineScore = 0.5;
+      const expectedRecency = (store as any).calculateRecencyScore(twoDaysAgo, scoring.episodic.halfLifeDays);
+      const expectedScore = scoring.episodic.alpha * cosineScore + scoring.episodic.beta * expectedRecency + scoring.episodic.gamma;
+      const hybridScore = (store as any).calculateHybridScore(cosineScore, payload);
+      expect(hybridScore).toBeCloseTo(expectedScore, 5);
+      expect(scoring.episodic.beta * expectedRecency).toBeGreaterThan(0.2);
+    });
+
+    it('should have low score for old episodic memory', () => {
+        const payload: MemoryPayload = { memoryId: 'mem-e2', userId: userId, type: 'episodic', createdAt: veryOldDate };
+        const cosineScore = 0.9;
+        const expectedRecency = (store as any).calculateRecencyScore(veryOldDate, scoring.episodic.halfLifeDays);
+        const expectedScore = scoring.episodic.alpha * cosineScore + scoring.episodic.beta * expectedRecency + scoring.episodic.gamma;
+        const hybridScore = (store as any).calculateHybridScore(cosineScore, payload);
+        expect(expectedRecency).toBeLessThan(0.01);
+        expect(hybridScore).toBeCloseTo(scoring.episodic.alpha * cosineScore + scoring.episodic.gamma, 5);
+    });
+
+    it('should handle assistant_preference with no decay (Infinity half-life)', () => {
+        const payload: MemoryPayload = { memoryId: 'mem-a1', userId: userId, type: 'assistant_preference', createdAt: veryOldDate };
+        const cosineScore = 0.7;
+        const expectedRecency = 1.0;
+        const expectedScore = scoring.assistant_preference.alpha * cosineScore + scoring.assistant_preference.beta * expectedRecency + scoring.assistant_preference.gamma;
+        const hybridScore = (store as any).calculateHybridScore(cosineScore, payload);
+        expect(hybridScore).toBeCloseTo(expectedScore, 5);
+    });
+
+    it('should use default scoring if type is missing', () => {
+        const payload: MemoryPayload = { memoryId: 'mem-d1', userId: userId, createdAt: sevenDaysAgo }; // No type specified
+        const cosineScore = 0.8;
+        const expectedRecency = (store as any).calculateRecencyScore(sevenDaysAgo, scoring.default.halfLifeDays);
+        const expectedScore = scoring.default.alpha * cosineScore + scoring.default.beta * expectedRecency + scoring.default.gamma;
+        const hybridScore = (store as any).calculateHybridScore(cosineScore, payload);
+        expect(hybridScore).toBeCloseTo(expectedScore, 5);
+    });
+
+    it('should return score >= 0 even with negative cosine similarity', () => {
+        const payload: MemoryPayload = { memoryId: 'mem-s1', userId: userId, type: 'semantic', createdAt: twoDaysAgo };
+        const cosineScore = -0.5;
+        const hybridScore = (store as any).calculateHybridScore(cosineScore, payload);
+        expect(hybridScore).toBeGreaterThanOrEqual(0);
+    });
+
+  });
+
+});