genesis-ai-cli 7.4.5

package/dist/src/memory/episodic.js

@@ -0,0 +1,394 @@
+"use strict";
+/**
+ * Genesis 6.0 - Episodic Memory Store
+ *
+ * Stores autobiographical memories - events with context.
+ * "What happened, when, where, who was involved"
+ *
+ * Key features:
+ * - Temporal ordering and sequencing
+ * - Context binding (where, who)
+ * - Emotional coloring
+ * - Forgetting curve integration
+ *
+ * Reference: Tulving, E. (1972). Episodic and semantic memory.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EpisodicStore = void 0;
+exports.createEpisodicStore = createEpisodicStore;
+const crypto_1 = require("crypto");
+const forgetting_js_1 = require("./forgetting.js");
+// ============================================================================
+// Episodic Store
+// ============================================================================
+class EpisodicStore {
+    memories = new Map();
+    config;
+    // Indexes for efficient querying
+    byTime = []; // Sorted by when.timestamp
+    byLocation = new Map();
+    byAgent = new Map();
+    byTag = new Map();
+    constructor(config = {}) {
+        this.config = {
+            maxSize: 10000,
+            autoForget: true,
+            forgetThreshold: forgetting_js_1.FORGETTING_THRESHOLDS.FORGET,
+            defaultStability: forgetting_js_1.FORGETTING_THRESHOLDS.DEFAULT_STABILITY,
+            ...config,
+        };
+    }
+    // ============================================================================
+    // Store
+    // ============================================================================
+    store(input) {
+        const now = new Date();
+        const id = (0, crypto_1.randomUUID)();
+        const memory = {
+            ...input,
+            id,
+            created: now,
+            lastAccessed: now,
+            accessCount: 1,
+        };
+        this.memories.set(id, memory);
+        this.updateIndexes(memory);
+        this.maintainSize();
+        return memory;
+    }
+    /**
+     * Convenience method to create an episodic memory from options
+     */
+    createEpisode(options) {
+        const now = new Date();
+        const params = (0, forgetting_js_1.calculateInitialParams)({
+            importance: options.importance,
+            emotionalValence: options.feeling?.valence,
+        });
+        return this.store({
+            type: 'episodic',
+            content: {
+                what: options.what,
+                details: options.details || {},
+            },
+            when: {
+                timestamp: options.when || now,
+                duration: options.duration,
+            },
+            where: options.where,
+            who: options.who ? {
+                agents: options.who.agents,
+                roles: options.who.roles || {},
+            } : undefined,
+            feeling: options.feeling,
+            R0: params.R0,
+            S: params.S,
+            importance: options.importance || 0.5,
+            emotionalValence: options.feeling?.valence || 0,
+            associations: options.associations || [],
+            tags: options.tags || [],
+            consolidated: false,
+            source: options.source,
+        });
+    }
+    // ============================================================================
+    // Get / Update / Delete
+    // ============================================================================
+    get(id) {
+        const memory = this.memories.get(id);
+        if (memory) {
+            this.accessMemory(memory);
+        }
+        return memory;
+    }
+    /**
+     * Get without updating access (for internal use)
+     */
+    peek(id) {
+        return this.memories.get(id);
+    }
+    update(id, updates) {
+        const memory = this.memories.get(id);
+        if (!memory)
+            return undefined;
+        // Remove from indexes before update
+        this.removeFromIndexes(memory);
+        // Apply updates
+        Object.assign(memory, updates);
+        // Re-add to indexes
+        this.updateIndexes(memory);
+        return memory;
+    }
+    delete(id) {
+        const memory = this.memories.get(id);
+        if (!memory)
+            return false;
+        this.removeFromIndexes(memory);
+        this.memories.delete(id);
+        return true;
+    }
+    // ============================================================================
+    // Query
+    // ============================================================================
+    query(filter) {
+        let results = this.getAll();
+        if (filter.minImportance !== undefined) {
+            results = results.filter((m) => m.importance >= filter.minImportance);
+        }
+        if (filter.maxAge !== undefined) {
+            const cutoff = Date.now() - filter.maxAge * 24 * 60 * 60 * 1000;
+            results = results.filter((m) => m.created.getTime() >= cutoff);
+        }
+        if (filter.minRetention !== undefined) {
+            results = results.filter((m) => {
+                const retention = (0, forgetting_js_1.calculateRetention)({ R0: m.R0, S: m.S }, m.lastAccessed.getTime());
+                return retention >= filter.minRetention;
+            });
+        }
+        if (filter.tags && filter.tags.length > 0) {
+            results = results.filter((m) => filter.tags.some((t) => m.tags.includes(t)));
+        }
+        if (filter.consolidated !== undefined) {
+            results = results.filter((m) => m.consolidated === filter.consolidated);
+        }
+        if (filter.custom) {
+            results = results.filter(filter.custom);
+        }
+        return results;
+    }
+    /**
+     * Search by keyword in content
+     */
+    search(queryStr, limit = 10) {
+        const keywords = queryStr.toLowerCase().split(/\s+/);
+        const results = this.getAll().filter((m) => {
+            const contentStr = JSON.stringify(m.content).toLowerCase();
+            return keywords.some((k) => contentStr.includes(k));
+        });
+        // Sort by retention (strongest first)
+        results.sort((a, b) => {
+            const retA = (0, forgetting_js_1.calculateRetention)({ R0: a.R0, S: a.S }, a.lastAccessed.getTime());
+            const retB = (0, forgetting_js_1.calculateRetention)({ R0: b.R0, S: b.S }, b.lastAccessed.getTime());
+            return retB - retA;
+        });
+        return results.slice(0, limit);
+    }
+    // ============================================================================
+    // Time-based Queries
+    // ============================================================================
+    /**
+     * Get episodes in a time range
+     */
+    getByTimeRange(start, end) {
+        return this.byTime.filter((m) => m.when.timestamp >= start && m.when.timestamp <= end);
+    }
+    /**
+     * Get recent episodes
+     */
+    getRecent(limit = 10) {
+        return this.byTime.slice(-limit).reverse();
+    }
+    /**
+     * Get episodes from today
+     */
+    getToday() {
+        const today = new Date();
+        today.setHours(0, 0, 0, 0);
+        const tomorrow = new Date(today);
+        tomorrow.setDate(tomorrow.getDate() + 1);
+        return this.getByTimeRange(today, tomorrow);
+    }
+    /**
+     * Get episodes involving a specific agent
+     */
+    getByAgent(agentId) {
+        const ids = this.byAgent.get(agentId);
+        if (!ids)
+            return [];
+        return Array.from(ids)
+            .map((id) => this.memories.get(id))
+            .filter((m) => m !== undefined);
+    }
+    /**
+     * Get episodes at a location
+     */
+    getByLocation(location) {
+        const ids = this.byLocation.get(location);
+        if (!ids)
+            return [];
+        return Array.from(ids)
+            .map((id) => this.memories.get(id))
+            .filter((m) => m !== undefined);
+    }
+    // ============================================================================
+    // Bulk Operations
+    // ============================================================================
+    getAll() {
+        return Array.from(this.memories.values());
+    }
+    clear() {
+        this.memories.clear();
+        this.byTime = [];
+        this.byLocation.clear();
+        this.byAgent.clear();
+        this.byTag.clear();
+    }
+    count() {
+        return this.memories.size;
+    }
+    // ============================================================================
+    // Stats
+    // ============================================================================
+    stats() {
+        const all = this.getAll();
+        let totalRetention = 0;
+        let totalImportance = 0;
+        let consolidated = 0;
+        let oldest;
+        let newest;
+        for (const memory of all) {
+            totalRetention += (0, forgetting_js_1.calculateRetention)({ R0: memory.R0, S: memory.S }, memory.lastAccessed.getTime());
+            totalImportance += memory.importance;
+            if (memory.consolidated)
+                consolidated++;
+            if (!oldest || memory.created < oldest)
+                oldest = memory.created;
+            if (!newest || memory.created > newest)
+                newest = memory.created;
+        }
+        return {
+            total: all.length,
+            byType: {
+                episodic: all.length,
+                semantic: 0,
+                procedural: 0,
+            },
+            consolidated,
+            avgRetention: all.length > 0 ? totalRetention / all.length : 0,
+            avgImportance: all.length > 0 ? totalImportance / all.length : 0,
+            oldestMemory: oldest,
+            newestMemory: newest,
+        };
+    }
+    // ============================================================================
+    // Forgetting Integration
+    // ============================================================================
+    /**
+     * Get episodes that should be forgotten
+     */
+    getForgotten() {
+        return this.getAll().filter((m) => (0, forgetting_js_1.shouldForget)(m, this.config.forgetThreshold));
+    }
+    /**
+     * Get episodes ready for consolidation (strong retention, not yet consolidated)
+     */
+    getReadyForConsolidation(threshold = 0.7) {
+        return this.getAll().filter((m) => {
+            if (m.consolidated)
+                return false;
+            const retention = (0, forgetting_js_1.calculateRetention)({ R0: m.R0, S: m.S }, m.lastAccessed.getTime());
+            return retention >= threshold;
+        });
+    }
+    /**
+     * Run forgetting cycle - remove memories below threshold
+     */
+    runForgetting() {
+        const toForget = this.getForgotten();
+        const ids = toForget.map((m) => m.id);
+        for (const id of ids) {
+            this.delete(id);
+        }
+        return { forgotten: ids.length, ids };
+    }
+    // ============================================================================
+    // Private Methods
+    // ============================================================================
+    accessMemory(memory) {
+        memory.lastAccessed = new Date();
+        memory.accessCount++;
+        memory.S = (0, forgetting_js_1.updateStabilityOnRecall)(memory, true);
+    }
+    updateIndexes(memory) {
+        // Time index
+        this.byTime.push(memory);
+        this.byTime.sort((a, b) => a.when.timestamp.getTime() - b.when.timestamp.getTime());
+        // Location index
+        if (memory.where) {
+            if (!this.byLocation.has(memory.where.location)) {
+                this.byLocation.set(memory.where.location, new Set());
+            }
+            this.byLocation.get(memory.where.location).add(memory.id);
+        }
+        // Agent index
+        if (memory.who) {
+            for (const agent of memory.who.agents) {
+                if (!this.byAgent.has(agent)) {
+                    this.byAgent.set(agent, new Set());
+                }
+                this.byAgent.get(agent).add(memory.id);
+            }
+        }
+        // Tag index
+        for (const tag of memory.tags) {
+            if (!this.byTag.has(tag)) {
+                this.byTag.set(tag, new Set());
+            }
+            this.byTag.get(tag).add(memory.id);
+        }
+    }
+    removeFromIndexes(memory) {
+        // Time index
+        const timeIndex = this.byTime.findIndex((m) => m.id === memory.id);
+        if (timeIndex !== -1) {
+            this.byTime.splice(timeIndex, 1);
+        }
+        // Location index
+        if (memory.where) {
+            this.byLocation.get(memory.where.location)?.delete(memory.id);
+        }
+        // Agent index
+        if (memory.who) {
+            for (const agent of memory.who.agents) {
+                this.byAgent.get(agent)?.delete(memory.id);
+            }
+        }
+        // Tag index
+        for (const tag of memory.tags) {
+            this.byTag.get(tag)?.delete(memory.id);
+        }
+    }
+    maintainSize() {
+        if (!this.config.autoForget)
+            return;
+        if (this.memories.size <= this.config.maxSize)
+            return;
+        // First, forget memories below threshold
+        this.runForgetting();
+        // If still over limit, remove weakest memories
+        while (this.memories.size > this.config.maxSize) {
+            let weakest = null;
+            let weakestRetention = Infinity;
+            for (const memory of this.memories.values()) {
+                const retention = (0, forgetting_js_1.calculateRetention)({ R0: memory.R0, S: memory.S }, memory.lastAccessed.getTime());
+                if (retention < weakestRetention) {
+                    weakestRetention = retention;
+                    weakest = memory;
+                }
+            }
+            if (weakest) {
+                this.delete(weakest.id);
+            }
+            else {
+                break;
+            }
+        }
+    }
+}
+exports.EpisodicStore = EpisodicStore;
+// ============================================================================
+// Factory
+// ============================================================================
+function createEpisodicStore(config) {
+    return new EpisodicStore(config);
+}

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

@@ -0,0 +1,134 @@
+/**
+ * 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)
+ */
+import { BaseMemory, ForgettingParams, RetentionResult } from './types.js';
+/**
+ * Forgetting thresholds
+ */
+export declare const FORGETTING_THRESHOLDS: {
+    /** Below this retention, memory is effectively forgotten */
+    FORGET: number;
+    /** Below this, memory is weak and at risk */
+    WEAK: number;
+    /** Above this, memory is strong */
+    STRONG: number;
+    /** Default initial stability (days) */
+    DEFAULT_STABILITY: number;
+    /** Maximum stability (years worth of days) */
+    MAX_STABILITY: number;
+};
+/**
+ * Stability multipliers for reinforcement
+ */
+export declare const STABILITY_MULTIPLIERS: {
+    /** Base multiplier on successful recall */
+    RECALL_SUCCESS: number;
+    /** Bonus for high importance memories */
+    IMPORTANCE_HIGH: number;
+    /** Bonus for emotionally charged memories */
+    EMOTIONAL: number;
+    /** Decay factor for failed recall */
+    RECALL_FAILURE: number;
+    /** Bonus for repeated access within short time */
+    SPACED_REPETITION: number;
+};
+/**
+ * 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)
+ */
+export declare function calculateRetention(params: ForgettingParams, lastAccessedMs: number, nowMs?: number): number;
+/**
+ * Calculate detailed retention result for a memory
+ */
+export declare function getRetentionDetails(memory: BaseMemory, nowMs?: number): RetentionResult;
+/**
+ * Check if a memory should be forgotten
+ */
+export declare function shouldForget(memory: BaseMemory, threshold?: number): boolean;
+/**
+ * Get memories that should be forgotten from a list
+ */
+export declare function getMemoriesToForget<T extends BaseMemory>(memories: T[], threshold?: number): T[];
+/**
+ * Update stability after successful recall
+ * Stability increases, making the memory more resistant to forgetting
+ */
+export declare function updateStabilityOnRecall(memory: BaseMemory, success?: boolean): number;
+/**
+ * Calculate optimal review time (when to access again)
+ * Returns the time in days when retention will drop to target level
+ */
+export declare function calculateOptimalReviewTime(memory: BaseMemory, targetRetention?: number): number;
+/**
+ * Get spaced repetition schedule for a memory
+ * Returns array of review times (days from now)
+ */
+export declare function getReviewSchedule(memory: BaseMemory, targetRetention?: number, numReviews?: number): number[];
+/**
+ * Calculate initial forgetting parameters for a new memory
+ */
+export declare function calculateInitialParams(options: {
+    importance?: number;
+    emotionalValence?: number;
+    complexity?: number;
+    priorKnowledge?: boolean;
+}): ForgettingParams;
+/**
+ * Simulate retention over time
+ * Useful for visualization and analysis
+ */
+export declare function simulateDecay(params: ForgettingParams, days: number, intervalHours?: number): Array<{
+    day: number;
+    retention: number;
+}>;
+/**
+ * Compare decay curves for multiple memories
+ */
+export declare function compareDecayCurves(memories: BaseMemory[], days?: number): Map<string, Array<{
+    day: number;
+    retention: number;
+}>>;
+/**
+ * Calculate retention for multiple memories efficiently
+ */
+export declare function batchCalculateRetention(memories: BaseMemory[], nowMs?: number): Map<string, number>;
+/**
+ * Sort memories by retention (weakest first)
+ */
+export declare function sortByRetention<T extends BaseMemory>(memories: T[], ascending?: boolean): T[];
+/**
+ * Get memories that need review (retention below threshold)
+ */
+export declare function getMemoriesNeedingReview<T extends BaseMemory>(memories: T[], threshold?: number): T[];
+/**
+ * Calculate forgetting statistics for a set of memories
+ */
+export declare function calculateForgettingStats(memories: BaseMemory[]): {
+    total: number;
+    forgotten: number;
+    weak: number;
+    strong: number;
+    avgRetention: number;
+    avgStability: number;
+    avgAge: number;
+    needsReview: number;
+};