genesis-ai-cli 7.4.5

package/dist/src/memory/forgetting.js

@@ -0,0 +1,324 @@
+"use strict";
+/**
+ * Genesis 6.0 - Forgetting Module
+ *
+ * Implements Ebbinghaus forgetting curve: R(t) = R0 * e^(-t/S)
+ *
+ * Where:
+ * - R = retention (0-1)
+ * - R0 = initial retention strength
+ * - t = time elapsed (days)
+ * - S = stability (days until 50% forgotten)
+ *
+ * Enhanced with FSRS-style stability updates on recall.
+ *
+ * References:
+ * - Ebbinghaus, H. (1885). Memory: A Contribution to Experimental Psychology
+ * - Wozniak, P. (2020). Free Spaced Repetition Scheduler (FSRS)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STABILITY_MULTIPLIERS = exports.FORGETTING_THRESHOLDS = void 0;
+exports.calculateRetention = calculateRetention;
+exports.getRetentionDetails = getRetentionDetails;
+exports.shouldForget = shouldForget;
+exports.getMemoriesToForget = getMemoriesToForget;
+exports.updateStabilityOnRecall = updateStabilityOnRecall;
+exports.calculateOptimalReviewTime = calculateOptimalReviewTime;
+exports.getReviewSchedule = getReviewSchedule;
+exports.calculateInitialParams = calculateInitialParams;
+exports.simulateDecay = simulateDecay;
+exports.compareDecayCurves = compareDecayCurves;
+exports.batchCalculateRetention = batchCalculateRetention;
+exports.sortByRetention = sortByRetention;
+exports.getMemoriesNeedingReview = getMemoriesNeedingReview;
+exports.calculateForgettingStats = calculateForgettingStats;
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Forgetting thresholds
+ */
+exports.FORGETTING_THRESHOLDS = {
+    /** Below this retention, memory is effectively forgotten */
+    FORGET: 0.01,
+    /** Below this, memory is weak and at risk */
+    WEAK: 0.3,
+    /** Above this, memory is strong */
+    STRONG: 0.7,
+    /** Default initial stability (days) */
+    DEFAULT_STABILITY: 1.0,
+    /** Maximum stability (years worth of days) */
+    MAX_STABILITY: 3650,
+};
+/**
+ * Stability multipliers for reinforcement
+ */
+exports.STABILITY_MULTIPLIERS = {
+    /** Base multiplier on successful recall */
+    RECALL_SUCCESS: 2.5,
+    /** Bonus for high importance memories */
+    IMPORTANCE_HIGH: 1.5,
+    /** Bonus for emotionally charged memories */
+    EMOTIONAL: 2.0,
+    /** Decay factor for failed recall */
+    RECALL_FAILURE: 0.5,
+    /** Bonus for repeated access within short time */
+    SPACED_REPETITION: 1.2,
+};
+// ============================================================================
+// Core Forgetting Functions
+// ============================================================================
+/**
+ * Calculate current retention using Ebbinghaus formula
+ * R(t) = R0 * e^(-t/S)
+ *
+ * @param params - Forgetting parameters (R0, S)
+ * @param lastAccessedMs - Timestamp of last access (ms)
+ * @param nowMs - Current timestamp (ms), defaults to now
+ * @returns Current retention value (0-1)
+ */
+function calculateRetention(params, lastAccessedMs, nowMs = Date.now()) {
+    const elapsedDays = (nowMs - lastAccessedMs) / (1000 * 60 * 60 * 24);
+    if (elapsedDays <= 0) {
+        return params.R0;
+    }
+    const retention = params.R0 * Math.exp(-elapsedDays / params.S);
+    return Math.max(0, Math.min(1, retention));
+}
+/**
+ * Calculate detailed retention result for a memory
+ */
+function getRetentionDetails(memory, nowMs = Date.now()) {
+    const lastAccessedMs = memory.lastAccessed.getTime();
+    const elapsedDays = (nowMs - lastAccessedMs) / (1000 * 60 * 60 * 24);
+    const retention = calculateRetention({ R0: memory.R0, S: memory.S }, lastAccessedMs, nowMs);
+    // Calculate half-life: when R = R0/2
+    // R0/2 = R0 * e^(-t/S)
+    // 0.5 = e^(-t/S)
+    // ln(0.5) = -t/S
+    // t = -S * ln(0.5) = S * ln(2)
+    const predictedHalfLife = memory.S * Math.LN2;
+    return {
+        retention,
+        elapsedDays,
+        predictedHalfLife,
+        shouldForget: retention < exports.FORGETTING_THRESHOLDS.FORGET,
+    };
+}
+/**
+ * Check if a memory should be forgotten
+ */
+function shouldForget(memory, threshold = exports.FORGETTING_THRESHOLDS.FORGET) {
+    const retention = calculateRetention({ R0: memory.R0, S: memory.S }, memory.lastAccessed.getTime());
+    return retention < threshold;
+}
+/**
+ * Get memories that should be forgotten from a list
+ */
+function getMemoriesToForget(memories, threshold = exports.FORGETTING_THRESHOLDS.FORGET) {
+    return memories.filter((m) => shouldForget(m, threshold));
+}
+// ============================================================================
+// Stability Updates (FSRS-inspired)
+// ============================================================================
+/**
+ * Update stability after successful recall
+ * Stability increases, making the memory more resistant to forgetting
+ */
+function updateStabilityOnRecall(memory, success = true) {
+    let newStability = memory.S;
+    if (success) {
+        // Base increase
+        newStability *= exports.STABILITY_MULTIPLIERS.RECALL_SUCCESS;
+        // Importance bonus
+        if (memory.importance > 0.7) {
+            newStability *= exports.STABILITY_MULTIPLIERS.IMPORTANCE_HIGH;
+        }
+        // Emotional bonus
+        if (Math.abs(memory.emotionalValence) > 0.5) {
+            newStability *= exports.STABILITY_MULTIPLIERS.EMOTIONAL;
+        }
+    }
+    else {
+        // Failed recall decreases stability
+        newStability *= exports.STABILITY_MULTIPLIERS.RECALL_FAILURE;
+    }
+    // Clamp to max
+    return Math.min(newStability, exports.FORGETTING_THRESHOLDS.MAX_STABILITY);
+}
+/**
+ * Calculate optimal review time (when to access again)
+ * Returns the time in days when retention will drop to target level
+ */
+function calculateOptimalReviewTime(memory, targetRetention = 0.9) {
+    // Solve: targetRetention = R0 * e^(-t/S)
+    // t = -S * ln(targetRetention / R0)
+    const t = -memory.S * Math.log(targetRetention / memory.R0);
+    return Math.max(0, t);
+}
+/**
+ * Get spaced repetition schedule for a memory
+ * Returns array of review times (days from now)
+ */
+function getReviewSchedule(memory, targetRetention = 0.9, numReviews = 5) {
+    const schedule = [];
+    let currentStability = memory.S;
+    let totalDays = 0;
+    for (let i = 0; i < numReviews; i++) {
+        // Time until next review
+        const interval = -currentStability * Math.log(targetRetention / memory.R0);
+        totalDays += interval;
+        schedule.push(totalDays);
+        // Simulate stability increase after review
+        currentStability *= exports.STABILITY_MULTIPLIERS.RECALL_SUCCESS;
+        currentStability = Math.min(currentStability, exports.FORGETTING_THRESHOLDS.MAX_STABILITY);
+    }
+    return schedule;
+}
+// ============================================================================
+// Initial Parameters
+// ============================================================================
+/**
+ * Calculate initial forgetting parameters for a new memory
+ */
+function calculateInitialParams(options) {
+    const { importance = 0.5, emotionalValence = 0, complexity = 0.5, priorKnowledge = false, } = options;
+    // Base initial retention
+    let R0 = 1.0;
+    // Importance affects initial strength
+    R0 += importance * 0.3;
+    // Emotional memories are stronger
+    R0 += Math.abs(emotionalValence) * 0.2;
+    // Normalize to 0-1
+    R0 = Math.min(1, R0);
+    // Base stability
+    let S = exports.FORGETTING_THRESHOLDS.DEFAULT_STABILITY;
+    // Complex memories decay faster initially
+    S *= 1 - complexity * 0.5;
+    // Prior knowledge helps
+    if (priorKnowledge) {
+        S *= 2;
+    }
+    // Emotional memories are more stable
+    S *= 1 + Math.abs(emotionalValence) * 0.5;
+    return { R0, S };
+}
+// ============================================================================
+// Decay Simulation
+// ============================================================================
+/**
+ * Simulate retention over time
+ * Useful for visualization and analysis
+ */
+function simulateDecay(params, days, intervalHours = 24) {
+    const points = [];
+    const intervalDays = intervalHours / 24;
+    for (let day = 0; day <= days; day += intervalDays) {
+        const retention = params.R0 * Math.exp(-day / params.S);
+        points.push({ day, retention });
+    }
+    return points;
+}
+/**
+ * Compare decay curves for multiple memories
+ */
+function compareDecayCurves(memories, days = 30) {
+    const curves = new Map();
+    for (const memory of memories) {
+        curves.set(memory.id, simulateDecay({ R0: memory.R0, S: memory.S }, days));
+    }
+    return curves;
+}
+// ============================================================================
+// Batch Operations
+// ============================================================================
+/**
+ * Calculate retention for multiple memories efficiently
+ */
+function batchCalculateRetention(memories, nowMs = Date.now()) {
+    const retentions = new Map();
+    for (const memory of memories) {
+        const retention = calculateRetention({ R0: memory.R0, S: memory.S }, memory.lastAccessed.getTime(), nowMs);
+        retentions.set(memory.id, retention);
+    }
+    return retentions;
+}
+/**
+ * Sort memories by retention (weakest first)
+ */
+function sortByRetention(memories, ascending = true) {
+    const nowMs = Date.now();
+    return [...memories].sort((a, b) => {
+        const retentionA = calculateRetention({ R0: a.R0, S: a.S }, a.lastAccessed.getTime(), nowMs);
+        const retentionB = calculateRetention({ R0: b.R0, S: b.S }, b.lastAccessed.getTime(), nowMs);
+        return ascending ? retentionA - retentionB : retentionB - retentionA;
+    });
+}
+/**
+ * Get memories that need review (retention below threshold)
+ */
+function getMemoriesNeedingReview(memories, threshold = exports.FORGETTING_THRESHOLDS.WEAK) {
+    return sortByRetention(memories.filter((m) => {
+        const retention = calculateRetention({ R0: m.R0, S: m.S }, m.lastAccessed.getTime());
+        return retention < threshold && retention >= exports.FORGETTING_THRESHOLDS.FORGET;
+    }), true // weakest first
+    );
+}
+// ============================================================================
+// Statistics
+// ============================================================================
+/**
+ * Calculate forgetting statistics for a set of memories
+ */
+function calculateForgettingStats(memories) {
+    if (memories.length === 0) {
+        return {
+            total: 0,
+            forgotten: 0,
+            weak: 0,
+            strong: 0,
+            avgRetention: 0,
+            avgStability: 0,
+            avgAge: 0,
+            needsReview: 0,
+        };
+    }
+    const nowMs = Date.now();
+    let totalRetention = 0;
+    let totalStability = 0;
+    let totalAge = 0;
+    let forgotten = 0;
+    let weak = 0;
+    let strong = 0;
+    let needsReview = 0;
+    for (const memory of memories) {
+        const retention = calculateRetention({ R0: memory.R0, S: memory.S }, memory.lastAccessed.getTime(), nowMs);
+        const ageDays = (nowMs - memory.created.getTime()) / (1000 * 60 * 60 * 24);
+        totalRetention += retention;
+        totalStability += memory.S;
+        totalAge += ageDays;
+        if (retention < exports.FORGETTING_THRESHOLDS.FORGET) {
+            forgotten++;
+        }
+        else if (retention < exports.FORGETTING_THRESHOLDS.WEAK) {
+            weak++;
+            needsReview++;
+        }
+        else if (retention > exports.FORGETTING_THRESHOLDS.STRONG) {
+            strong++;
+        }
+        else {
+            needsReview++;
+        }
+    }
+    return {
+        total: memories.length,
+        forgotten,
+        weak,
+        strong,
+        avgRetention: totalRetention / memories.length,
+        avgStability: totalStability / memories.length,
+        avgAge: totalAge / memories.length,
+        needsReview,
+    };
+}

package/dist/src/memory/index.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Genesis 6.0 - Memory Module
+ *
+ * Unified memory system based on cognitive science:
+ * - Episodic: Events with context (what/when/where/who)
+ * - Semantic: Facts and concepts (knowledge)
+ * - Procedural: Skills and workflows (know-how)
+ *
+ * Features:
+ * - Ebbinghaus forgetting curve
+ * - Sleep-based consolidation (episodic → semantic)
+ * - Pattern extraction
+ * - Skill learning
+ *
+ * Usage:
+ * ```typescript
+ * import { createMemorySystem } from './memory/index.js';
+ *
+ * const memory = createMemorySystem();
+ *
+ * // Store an episode
+ * memory.remember({
+ *   what: 'User asked about AI',
+ *   when: new Date(),
+ *   tags: ['conversation', 'AI'],
+ * });
+ *
+ * // Create a fact
+ * memory.learn({
+ *   concept: 'TypeScript',
+ *   definition: 'A typed superset of JavaScript',
+ *   category: 'programming',
+ * });
+ *
+ * // Create a skill
+ * memory.learnSkill({
+ *   name: 'git-commit',
+ *   description: 'Create a git commit',
+ *   steps: [
+ *     { action: 'git add .' },
+ *     { action: 'git commit -m "message"' },
+ *   ],
+ * });
+ *
+ * // Run consolidation (sleep)
+ * await memory.sleep();
+ * ```
+ */
+export * from './types.js';
+export * from './forgetting.js';
+export * from './cache.js';
+export * from './indexer.js';
+export { EpisodicStore, createEpisodicStore, type CreateEpisodicOptions } from './episodic.js';
+export { SemanticStore, createSemanticStore, type CreateSemanticOptions } from './semantic.js';
+export { ProceduralStore, createProceduralStore, type CreateProceduralOptions } from './procedural.js';
+export { ConsolidationService, createConsolidationService } from './consolidation.js';
+export { CognitiveWorkspace, createCognitiveWorkspace, getCognitiveWorkspace, resetCognitiveWorkspace, type WorkingMemoryItem, type AnticipationContext, type CognitiveWorkspaceConfig, type MemoryReuseMetrics, DEFAULT_WORKSPACE_CONFIG, } from './cognitive-workspace.js';
+import { EpisodicStore, CreateEpisodicOptions } from './episodic.js';
+import { SemanticStore, CreateSemanticOptions } from './semantic.js';
+import { ProceduralStore, CreateProceduralOptions } from './procedural.js';
+import { ConsolidationService } from './consolidation.js';
+import { CognitiveWorkspace, CognitiveWorkspaceConfig, AnticipationContext, WorkingMemoryItem, MemoryReuseMetrics } from './cognitive-workspace.js';
+import { Memory, EpisodicMemory, SemanticMemory, ProceduralMemory, ConsolidationResult, StoreStats } from './types.js';
+import { calculateForgettingStats } from './forgetting.js';
+export interface MemorySystemConfig {
+    episodic?: {
+        maxSize?: number;
+        autoForget?: boolean;
+    };
+    semantic?: {
+        maxSize?: number;
+        autoForget?: boolean;
+        minConfidence?: number;
+    };
+    procedural?: {
+        maxSize?: number;
+        autoForget?: boolean;
+        minSuccessRate?: number;
+    };
+    consolidation?: {
+        backgroundIntervalMs?: number;
+        autoStart?: boolean;
+    };
+    workspace?: Partial<CognitiveWorkspaceConfig>;
+}
+/**
+ * Unified memory system with episodic, semantic, and procedural stores
+ */
+export declare class MemorySystem {
+    readonly episodic: EpisodicStore;
+    readonly semantic: SemanticStore;
+    readonly procedural: ProceduralStore;
+    readonly consolidation: ConsolidationService;
+    readonly workspace: CognitiveWorkspace;
+    constructor(config?: MemorySystemConfig);
+    /**
+     * Store an episodic memory (event)
+     */
+    remember(options: CreateEpisodicOptions): EpisodicMemory;
+    /**
+     * Store a semantic memory (fact)
+     */
+    learn(options: CreateSemanticOptions): SemanticMemory;
+    /**
+     * Store a procedural memory (skill)
+     */
+    learnSkill(options: CreateProceduralOptions): ProceduralMemory;
+    /**
+     * Anticipate needed memories based on context (Memory 2.0)
+     *
+     * Uses context cues to predict which memories will be needed,
+     * pre-loading them into working memory for fast access.
+     */
+    anticipate(context: AnticipationContext): Promise<WorkingMemoryItem[]>;
+    /**
+     * Get currently active memories in working memory (Memory 2.0)
+     */
+    getActive(): WorkingMemoryItem[];
+    /**
+     * Get memory reuse metrics (Memory 2.0)
+     */
+    getReuseMetrics(): MemoryReuseMetrics;
+    /**
+     * Recall memories by query
+     */
+    recall(query: string, options?: {
+        types?: ('episodic' | 'semantic' | 'procedural')[];
+        limit?: number;
+    }): Memory[];
+    /**
+     * Get a specific fact by concept name
+     */
+    getFact(concept: string): SemanticMemory | undefined;
+    /**
+     * Get a specific skill by name
+     */
+    getSkill(name: string): ProceduralMemory | undefined;
+    /**
+     * Get recent episodes
+     */
+    getRecentEpisodes(limit?: number): EpisodicMemory[];
+    /**
+     * Run consolidation (sleep mode)
+     */
+    sleep(): Promise<ConsolidationResult>;
+    /**
+     * Run quick background consolidation
+     */
+    consolidate(): Promise<ConsolidationResult>;
+    /**
+     * Calculate retention for any memory type
+     */
+    private getRetention;
+    /**
+     * Get overall memory statistics
+     */
+    getStats(): {
+        total: number;
+        episodic: StoreStats;
+        semantic: StoreStats;
+        procedural: StoreStats;
+        forgetting: {
+            episodic: ReturnType<typeof calculateForgettingStats>;
+            semantic: ReturnType<typeof calculateForgettingStats>;
+            procedural: ReturnType<typeof calculateForgettingStats>;
+        };
+        consolidation: ReturnType<ConsolidationService['getStats']>;
+        workspace: ReturnType<CognitiveWorkspace['getStats']>;
+        reuse: MemoryReuseMetrics;
+    };
+    /**
+     * Clear all memories
+     */
+    clear(): void;
+    /**
+     * Shutdown the memory system
+     */
+    shutdown(): void;
+    /**
+     * Export all memories to JSON
+     */
+    export(): {
+        episodic: EpisodicMemory[];
+        semantic: SemanticMemory[];
+        procedural: ProceduralMemory[];
+        exportedAt: string;
+    };
+    /**
+     * Import memories from JSON
+     */
+    import(data: {
+        episodic?: EpisodicMemory[];
+        semantic?: SemanticMemory[];
+        procedural?: ProceduralMemory[];
+    }): {
+        imported: number;
+    };
+}
+/**
+ * Create a new memory system
+ */
+export declare function createMemorySystem(config?: MemorySystemConfig): MemorySystem;
+/**
+ * Get or create the global memory system instance
+ * v7.0: Consolidation auto-starts by default for real memory behavior
+ */
+export declare function getMemorySystem(config?: MemorySystemConfig): MemorySystem;
+/**
+ * Reset the global memory system instance
+ */
+export declare function resetMemorySystem(): void;