cognitive-core 0.2.4 → 0.3.1

package/src/memory/experience.ts

@@ -1,682 +0,0 @@
-import type { Experience } from '../types/index.js';
-import type { SqlitePersistence, ExperienceRow } from '../persistence/index.js';
-import { fromISO, fromInt, fromJSON, blobToEmbedding } from '../persistence/index.js';
-import { InvertedIndex } from '../embeddings/inverted-index.js';
-import { findTopK } from '../utils/similarity.js';
-import type { ReasoningBank } from './reasoning-bank.js';
-import { getCandidates, type ItemResolver } from './candidate-retrieval.js';
-
-/**
- * Result of pruning operation
- */
-export interface PruneResult {
-  /** IDs of pruned experiences */
-  prunedIds: string[];
-  /** IDs organized by pruning reason */
-  prunedByReason: {
-    age: string[];
-    usage: string[];
-    capacity: string[];
-    redundancy: string[];
-    failedOld: string[];
-  };
-  /** Total number pruned */
-  totalPruned: number;
-  /** Count remaining after pruning */
-  remainingCount: number;
-}
-
-/**
- * Convert an ExperienceRow (SQLite representation) back to an Experience (domain type).
- */
-function rowToExperience(row: ExperienceRow): Experience {
-  return {
-    id: row.id,
-    taskInput: row.task_input,
-    solutionOutput: row.solution_output,
-    feedback: row.feedback,
-    success: fromInt(row.success),
-    domain: row.domain,
-    embedding: blobToEmbedding(row.embedding),
-    trajectoryId: row.trajectory_id,
-    usageCount: row.usage_count,
-    accessScore: row.access_score,
-    retrievalCount: row.retrieval_count,
-    tier: row.tier as 'hot' | 'warm' | 'cold',
-    compressed: fromJSON(row.compressed),
-    metadata: fromJSON(row.metadata, {}),
-    createdAt: fromISO(row.created_at) ?? new Date(),
-    lastAccessedAt: fromISO(row.last_accessed_at),
-  };
-}
-
-/**
- * Experience Memory - ReMem-style task-level retrieval
- * Stores complete (task, solution, feedback) tuples
- *
- * Uses SqlitePersistence for storage and InvertedIndex
- * for fast candidate narrowing before similarity scoring.
- */
-export class ExperienceMemory {
-  private persistence: SqlitePersistence;
-  private _index: InvertedIndex = new InvertedIndex();
-  private initialized = false;
-  private _reasoningBank: ReasoningBank | null = null;
-
-  /**
-   * ItemResolver adapter for getCandidates().
-   * Resolves items by ID from SQLite and returns all values.
-   */
-  private _resolver: ItemResolver<Experience>;
-
-  constructor(persistence: SqlitePersistence) {
-    this.persistence = persistence;
-    this._resolver = {
-      get: (id: string) => {
-        const row = this.persistence.getExperience(id);
-        return row ? rowToExperience(row) : undefined;
-      },
-      values: () => this.getAllSync(),
-    };
-  }
-
-  async init(): Promise<void> {
-    if (this.initialized) return;
-
-    // Build inverted index from all experiences in DB
-    const ids = this.persistence.getExperienceIds();
-    for (const { id, task_input } of ids) {
-      this._index.add(id, task_input);
-    }
-
-    this.initialized = true;
-  }
-
-  /**
-   * Set the reasoning bank for cluster-augmented retrieval.
-   * Called externally when ReasoningBank is initialized.
-   */
-  setReasoningBank(bank: ReasoningBank): void {
-    this._reasoningBank = bank;
-  }
-
-  /**
-   * Get the reasoning bank (if set).
-   */
-  getReasoningBank(): ReasoningBank | null {
-    return this._reasoningBank;
-  }
-
-  /**
-   * Store a new experience
-   */
-  async add(experience: Experience): Promise<void> {
-    await this.init();
-    this.persistence.insertExperience(experience);
-    this._index.add(experience.id, experience.taskInput);
-  }
-
-  /**
-   * Retrieve an experience by ID
-   */
-  async get(id: string): Promise<Experience | undefined> {
-    await this.init();
-    const row = this.persistence.getExperience(id);
-    return row ? rowToExperience(row) : undefined;
-  }
-
-  /**
-   * Find similar experiences
-   * Uses inverted index for candidate narrowing, then embedding/text similarity scoring.
-   * Bumps accessScore on returned results.
-   */
-  async findSimilar(
-    query: string | number[],
-    options?: {
-      k?: number;
-      domain?: string;
-      minScore?: number;
-      successOnly?: boolean;
-    }
-  ): Promise<Array<{ experience: Experience; score: number }>> {
-    await this.init();
-
-    const k = options?.k ?? 4; // ReMem default
-
-    // Get candidate pool
-    const domainFallback = options?.domain
-      ? [
-          ...this.persistence.getExperiencesByDomain(options.domain).map(rowToExperience),
-          // Include '_global' domain items too
-          ...this.persistence.getExperiencesByDomain('_global').map(rowToExperience),
-        ]
-      : undefined;
-
-    let experiences: Experience[];
-
-    if (typeof query === 'string') {
-      experiences = getCandidates(query, this._index, this._resolver, { k }, domainFallback);
-    } else {
-      // Embedding query — inverted index doesn't help, use fallback
-      experiences = domainFallback ?? this.getAllSync();
-    }
-
-    // Apply domain filter (for cases where inverted index returned cross-domain results)
-    if (options?.domain) {
-      experiences = experiences.filter((e) => e.domain === options.domain);
-    }
-
-    // Filter by success if specified
-    if (options?.successOnly) {
-      experiences = experiences.filter((e) => e.success);
-    }
-
-    // Find similar experiences
-    const results = findTopK(
-      query,
-      experiences,
-      (e) => (Array.isArray(query) ? e.embedding : e.taskInput),
-      k
-    ).map(({ item, score }) => ({
-      experience: item,
-      score,
-    }));
-
-    // Filter by minimum score
-    const filtered = options?.minScore !== undefined
-      ? results.filter((r) => r.score >= options.minScore!)
-      : results;
-
-    // Merge with ReasoningBank results if available (string queries only)
-    let merged = filtered;
-    if (this._reasoningBank && typeof query === 'string') {
-      const clusterResults = this._reasoningBank.findInCluster(query, {
-        k,
-        domain: options?.domain,
-      });
-
-      // Merge: deduplicate by experience ID, keep higher score
-      const seenIds = new Map<string, number>();
-      for (const r of merged) {
-        seenIds.set(r.experience.id, r.score);
-      }
-      for (const cr of clusterResults) {
-        const existing = seenIds.get(cr.experience.id);
-        if (existing === undefined) {
-          merged.push({ experience: cr.experience, score: cr.score });
-          seenIds.set(cr.experience.id, cr.score);
-        }
-        // If already present, keep the higher score — existing is already in merged
-      }
-
-      // Re-sort by score after merge
-      merged.sort((a, b) => b.score - a.score);
-      merged = merged.slice(0, k);
-    }
-
-    // Bump access scores on returned results
-    for (const result of merged) {
-      const exp = result.experience;
-      const newRetrievalCount = (exp.retrievalCount ?? 0) + 1;
-      const newAccessScore = (exp.accessScore ?? 0) * 0.95 + 0.1;
-      const newLastAccessedAt = new Date();
-
-      this.persistence.updateExperience(exp.id, {
-        retrievalCount: newRetrievalCount,
-        accessScore: newAccessScore,
-        lastAccessedAt: newLastAccessedAt,
-      });
-
-      // Update in-memory reference too so caller sees updated values
-      exp.retrievalCount = newRetrievalCount;
-      exp.accessScore = newAccessScore;
-      exp.lastAccessedAt = newLastAccessedAt;
-    }
-
-    return merged;
-  }
-
-  /**
-   * Update an experience (e.g., after refinement)
-   */
-  async update(
-    id: string,
-    updates: Partial<Experience>
-  ): Promise<Experience | undefined> {
-    await this.init();
-    const row = this.persistence.getExperience(id);
-    if (!row) return undefined;
-
-    const existing = rowToExperience(row);
-    const updated = {
-      ...existing,
-      ...updates,
-      id: existing.id, // Preserve ID
-    };
-
-    // Write-through: full replace via INSERT OR REPLACE
-    this.persistence.insertExperience(updated);
-
-    // Update inverted index if taskInput changed
-    if (updates.taskInput) {
-      this._index.add(id, updates.taskInput);
-    }
-
-    return updated;
-  }
-
-  /**
-   * Increment usage count
-   */
-  async recordUsage(id: string): Promise<void> {
-    await this.init();
-    const row = this.persistence.getExperience(id);
-    if (row) {
-      this.persistence.updateExperience(id, {
-        usageCount: row.usage_count + 1,
-        lastAccessedAt: new Date(),
-      });
-    }
-  }
-
-  /**
-   * Get all experiences
-   */
-  async getAll(): Promise<Experience[]> {
-    await this.init();
-    return this.getAllSync();
-  }
-
-  /**
-   * Delete an experience by ID
-   */
-  async delete(id: string): Promise<boolean> {
-    await this.init();
-    this._index.remove(id);
-    return this.persistence.deleteExperience(id);
-  }
-
-  /**
-   * Get experiences by trajectory
-   */
-  async getByTrajectory(trajectoryId: string): Promise<Experience[]> {
-    await this.init();
-    return this.persistence.getExperiencesByTrajectory(trajectoryId).map(rowToExperience);
-  }
-
-  /**
-   * Prune low-value experiences.
-   * Uses accessScore as primary value signal when available.
-   */
-  async prune(options?: {
-    maxCount?: number;
-    minUsageCount?: number;
-    maxAgeDays?: number;
-    removeFailedOlderThanDays?: number;
-    similarityThreshold?: number;
-    preserveDomainCoverage?: boolean;
-  }): Promise<PruneResult> {
-    await this.init();
-    const pruned: string[] = [];
-    const prunedByReason: PruneResult['prunedByReason'] = {
-      age: [],
-      usage: [],
-      capacity: [],
-      redundancy: [],
-      failedOld: [],
-    };
-    let experiences = this.getAllSync();
-
-    // 1. Prune by age
-    if (options?.maxAgeDays) {
-      const cutoff = Date.now() - options.maxAgeDays * 24 * 60 * 60 * 1000;
-      const oldExperiences = experiences.filter(
-        (e) => e.createdAt.getTime() < cutoff
-      );
-      for (const exp of oldExperiences) {
-        this.persistence.deleteExperience(exp.id);
-        this._index.remove(exp.id);
-        pruned.push(exp.id);
-        prunedByReason.age.push(exp.id);
-      }
-      experiences = experiences.filter((e) => e.createdAt.getTime() >= cutoff);
-    }
-
-    // 2. Prune failed experiences older than threshold
-    if (options?.removeFailedOlderThanDays) {
-      const cutoff =
-        Date.now() - options.removeFailedOlderThanDays * 24 * 60 * 60 * 1000;
-      const failedOld = experiences.filter(
-        (e) => !e.success && e.createdAt.getTime() < cutoff
-      );
-      for (const exp of failedOld) {
-        this.persistence.deleteExperience(exp.id);
-        this._index.remove(exp.id);
-        pruned.push(exp.id);
-        prunedByReason.failedOld.push(exp.id);
-      }
-      experiences = experiences.filter(
-        (e) => e.success || e.createdAt.getTime() >= cutoff
-      );
-    }
-
-    // 3. Prune by minimum usage count
-    if (options?.minUsageCount !== undefined) {
-      const lowUsage = experiences.filter(
-        (e) => e.usageCount < options.minUsageCount!
-      );
-      // Only prune low-usage if they're also old (>7 days)
-      const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
-      for (const exp of lowUsage) {
-        if (exp.createdAt.getTime() < sevenDaysAgo) {
-          this.persistence.deleteExperience(exp.id);
-          this._index.remove(exp.id);
-          pruned.push(exp.id);
-          prunedByReason.usage.push(exp.id);
-        }
-      }
-      experiences = this.getAllSync(); // Refresh
-    }
-
-    // 4. Prune redundant/similar experiences
-    if (options?.similarityThreshold) {
-      const redundant = await this.findRedundant(
-        experiences,
-        options.similarityThreshold,
-        options.preserveDomainCoverage
-      );
-      for (const exp of redundant) {
-        this.persistence.deleteExperience(exp.id);
-        this._index.remove(exp.id);
-        pruned.push(exp.id);
-        prunedByReason.redundancy.push(exp.id);
-      }
-      experiences = this.getAllSync(); // Refresh
-    }
-
-    // 5. Prune by count (keep most valuable)
-    if (options?.maxCount && experiences.length > options.maxCount) {
-      // Sort by value (uses accessScore when available)
-      experiences.sort((a, b) => {
-        const scoreA = this.computeValue(a);
-        const scoreB = this.computeValue(b);
-        return scoreB - scoreA;
-      });
-
-      // If preserving domain coverage, ensure each domain keeps some
-      if (options.preserveDomainCoverage) {
-        const kept = this.selectWithDomainCoverage(
-          experiences,
-          options.maxCount
-        );
-        const keptIds = new Set(kept.map((e) => e.id));
-        for (const exp of experiences) {
-          if (!keptIds.has(exp.id)) {
-            this.persistence.deleteExperience(exp.id);
-            this._index.remove(exp.id);
-            pruned.push(exp.id);
-            prunedByReason.capacity.push(exp.id);
-          }
-        }
-      } else {
-        const toRemove = experiences.slice(options.maxCount);
-        for (const exp of toRemove) {
-          this.persistence.deleteExperience(exp.id);
-          this._index.remove(exp.id);
-          pruned.push(exp.id);
-          prunedByReason.capacity.push(exp.id);
-        }
-      }
-    }
-
-    return {
-      prunedIds: pruned,
-      prunedByReason,
-      totalPruned: pruned.length,
-      remainingCount: this.persistence.getExperienceCount(),
-    };
-  }
-
-  /**
-   * Find redundant experiences (similar to others, lower value)
-   */
-  private async findRedundant(
-    experiences: Experience[],
-    threshold: number,
-    preserveDomainCoverage = true
-  ): Promise<Experience[]> {
-    const redundant: Experience[] = [];
-    const kept = new Set<string>();
-    const domainCounts: Record<string, number> = {};
-
-    // Sort by value (highest first)
-    const sorted = [...experiences].sort((a, b) => {
-      return this.computeValue(b) - this.computeValue(a);
-    });
-
-    for (const exp of sorted) {
-      // Check if similar to any kept experience
-      let isDuplicate = false;
-      for (const keptId of kept) {
-        const keptExp = experiences.find((e) => e.id === keptId);
-        if (keptExp && this.computeSimilarity(exp, keptExp) > threshold) {
-          isDuplicate = true;
-          break;
-        }
-      }
-
-      if (isDuplicate) {
-        // Check domain coverage
-        if (preserveDomainCoverage) {
-          const domainCount = domainCounts[exp.domain] ?? 0;
-          if (domainCount < 3) {
-            // Keep at least 3 per domain
-            kept.add(exp.id);
-            domainCounts[exp.domain] = domainCount + 1;
-            continue;
-          }
-        }
-        redundant.push(exp);
-      } else {
-        kept.add(exp.id);
-        domainCounts[exp.domain] = (domainCounts[exp.domain] ?? 0) + 1;
-      }
-    }
-
-    return redundant;
-  }
-
-  /**
-   * Compute similarity between two experiences
-   */
-  private computeSimilarity(a: Experience, b: Experience): number {
-    // If both have embeddings, use cosine similarity
-    if (a.embedding && b.embedding) {
-      let dot = 0;
-      let normA = 0;
-      let normB = 0;
-      for (let i = 0; i < a.embedding.length; i++) {
-        dot += a.embedding[i] * b.embedding[i];
-        normA += a.embedding[i] * a.embedding[i];
-        normB += b.embedding[i] * b.embedding[i];
-      }
-      return dot / (Math.sqrt(normA) * Math.sqrt(normB) || 1);
-    }
-
-    // Fall back to Jaccard similarity on task input words
-    const wordsA = new Set(a.taskInput.toLowerCase().split(/\s+/));
-    const wordsB = new Set(b.taskInput.toLowerCase().split(/\s+/));
-    const intersection = new Set([...wordsA].filter((x) => wordsB.has(x)));
-    const union = new Set([...wordsA, ...wordsB]);
-    return intersection.size / union.size;
-  }
-
-  /**
-   * Select experiences while preserving domain coverage
-   */
-  private selectWithDomainCoverage(
-    experiences: Experience[],
-    maxCount: number
-  ): Experience[] {
-    const selected: Experience[] = [];
-    const domainCounts: Record<string, number> = {};
-    const domains = [...new Set(experiences.map((e) => e.domain))];
-    const minPerDomain = Math.max(1, Math.floor(maxCount / (domains.length * 2)));
-
-    // First pass: ensure minimum per domain
-    for (const domain of domains) {
-      const domainExps = experiences
-        .filter((e) => e.domain === domain)
-        .sort((a, b) => this.computeValue(b) - this.computeValue(a));
-
-      for (let i = 0; i < Math.min(minPerDomain, domainExps.length); i++) {
-        if (selected.length < maxCount) {
-          selected.push(domainExps[i]);
-          domainCounts[domain] = (domainCounts[domain] ?? 0) + 1;
-        }
-      }
-    }
-
-    // Second pass: fill remaining slots with highest value
-    const selectedIds = new Set(selected.map((e) => e.id));
-    const remaining = experiences
-      .filter((e) => !selectedIds.has(e.id))
-      .sort((a, b) => this.computeValue(b) - this.computeValue(a));
-
-    for (const exp of remaining) {
-      if (selected.length >= maxCount) break;
-      selected.push(exp);
-    }
-
-    return selected;
-  }
-
-  /**
-   * Compute value score for an experience.
-   * Uses accessScore as primary signal when available, falls back to
-   * the original recency + usage heuristic for backward compatibility.
-   */
-  private computeValue(exp: Experience): number {
-    // If accessScore is populated (> 0), use it as primary signal
-    if (exp.accessScore && exp.accessScore > 0) {
-      return (
-        exp.accessScore *
-        (exp.success ? 1 : 0.3)
-      );
-    }
-
-    // Backward compat: original heuristic for experiences without accessScore
-    const ageMs = Date.now() - exp.createdAt.getTime();
-    const ageDays = ageMs / (1000 * 60 * 60 * 24);
-    const recencyScore = Math.exp(-ageDays / 30); // Decay over ~30 days
-
-    // Access recency bonus
-    const accessAgeMs = exp.lastAccessedAt
-      ? Date.now() - exp.lastAccessedAt.getTime()
-      : ageMs;
-    const accessAgeDays = accessAgeMs / (1000 * 60 * 60 * 24);
-    const accessRecencyScore = Math.exp(-accessAgeDays / 14); // Decay over ~14 days
-
-    return (
-      (exp.success ? 1 : 0.3) * // Success bonus
-      (1 + Math.log(exp.usageCount + 1)) * // Usage bonus (log scale)
-      (recencyScore * 0.5 + accessRecencyScore * 0.5) // Combined recency
-    );
-  }
-
-  /**
-   * Get pruning statistics
-   */
-  async getPruningStats(): Promise<{
-    total: number;
-    byDomain: Record<string, number>;
-    bySuccess: { success: number; failure: number };
-    oldestDate: Date | null;
-    newestDate: Date | null;
-    averageUsage: number;
-    suggestedPrunes: {
-      lowUsage: number;
-      old: number;
-      failedOld: number;
-    };
-  }> {
-    await this.init();
-    const experiences = this.getAllSync();
-
-    const byDomain: Record<string, number> = {};
-    let successCount = 0;
-    let totalUsage = 0;
-    let oldestDate: Date | null = null;
-    let newestDate: Date | null = null;
-
-    const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
-    const thirtyDaysAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
-    let lowUsageCount = 0;
-    let oldCount = 0;
-    let failedOldCount = 0;
-
-    for (const exp of experiences) {
-      // Domain counts
-      byDomain[exp.domain] = (byDomain[exp.domain] ?? 0) + 1;
-
-      // Success counts
-      if (exp.success) successCount++;
-
-      // Usage sum
-      totalUsage += exp.usageCount;
-
-      // Date tracking
-      const createdAt = exp.createdAt;
-      if (!oldestDate || createdAt < oldestDate) oldestDate = createdAt;
-      if (!newestDate || createdAt > newestDate) newestDate = createdAt;
-
-      // Suggested prunes
-      if (exp.usageCount === 0 && createdAt.getTime() < sevenDaysAgo) {
-        lowUsageCount++;
-      }
-      if (createdAt.getTime() < thirtyDaysAgo) {
-        oldCount++;
-        if (!exp.success) failedOldCount++;
-      }
-    }
-
-    return {
-      total: experiences.length,
-      byDomain,
-      bySuccess: {
-        success: successCount,
-        failure: experiences.length - successCount,
-      },
-      oldestDate,
-      newestDate,
-      averageUsage: experiences.length > 0 ? totalUsage / experiences.length : 0,
-      suggestedPrunes: {
-        lowUsage: lowUsageCount,
-        old: oldCount,
-        failedOld: failedOldCount,
-      },
-    };
-  }
-
-  /**
-   * Get count
-   */
-  async count(): Promise<number> {
-    await this.init();
-    return this.persistence.getExperienceCount();
-  }
-
-  /**
-   * Close the store (no-op — SqlitePersistence lifecycle is managed externally)
-   */
-  async close(): Promise<void> {
-    // SqlitePersistence lifecycle is managed by MemorySystem/Atlas
-  }
-
-  /**
-   * Synchronous helper: get all experiences from SQLite.
-   */
-  private getAllSync(): Experience[] {
-    return this.persistence.getAllExperiences().map(rowToExperience);
-  }
-}