squish-memory 1.2.0 → 1.2.1

package/dist/core/memory/telemetry.js

@@ -1,313 +0,0 @@
-/**
- * Retrieval Quality Telemetry
- * Tracks memory usage patterns (echo/fizzle) to improve retrieval quality
- * Echo: memory was retrieved and used
- * Fizzle: memory was retrieved but not used
- */
-import { eq, desc } from 'drizzle-orm';
-import { getDb } from '../../db/index.js';
-import { getSchema } from '../../db/schema.js';
-import { logger } from '../logger.js';
-// In-memory cache for recent retrieval events (flushed periodically)
-const retrievalEvents = [];
-const MAX_CACHE_SIZE = 1000;
-/**
- * Record a retrieval event
- */
-export function recordRetrieval(memoryId, query, position, score, sessionId) {
-    const event = {
-        memoryId,
-        query,
-        position,
-        score,
-        wasUsed: false, // Initially false, updated when echoed
-        sessionId,
-        timestamp: new Date(),
-    };
-    retrievalEvents.push(event);
-    // Flush if cache is full
-    if (retrievalEvents.length >= MAX_CACHE_SIZE) {
-        flushRetrievalEvents().catch(err => {
-            logger.error('Failed to flush retrieval events', err);
-        });
-    }
-}
-/**
- * Mark a retrieval as "echoed" (memory was actually used)
- */
-export function recordEcho(memoryId, sessionId) {
-    // Find the most recent retrieval for this memory
-    const recentIndex = retrievalEvents.findIndex((e, i) => e.memoryId === memoryId &&
-        !e.wasUsed &&
-        (sessionId ? e.sessionId === sessionId : true));
-    if (recentIndex !== -1) {
-        retrievalEvents[recentIndex].wasUsed = true;
-    }
-    else {
-        // Add a new echo event if not found in cache
-        retrievalEvents.push({
-            memoryId,
-            query: '',
-            position: 0,
-            score: 0,
-            wasUsed: true,
-            sessionId,
-            timestamp: new Date(),
-        });
-    }
-    // Update memory's echo count directly
-    incrementMemoryEcho(memoryId).catch(err => {
-        logger.debug('Failed to increment echo count', err);
-    });
-}
-/**
- * Mark retrievals as "fizzled" (memory was not used)
- * Call this at the end of a session for non-echoed retrievals
- */
-export function recordFizzle(memoryId, sessionId) {
-    incrementMemoryFizzle(memoryId).catch(err => {
-        logger.debug('Failed to increment fizzle count', err);
-    });
-}
-/**
- * Flush cached retrieval events to database
- */
-export async function flushRetrievalEvents() {
-    if (retrievalEvents.length === 0)
-        return;
-    const events = [...retrievalEvents];
-    retrievalEvents.length = 0; // Clear cache
-    try {
-        const db = await getDb();
-        const schema = await getSchema();
-        // Group by memoryId for batch updates
-        const byMemory = new Map();
-        for (const event of events) {
-            const existing = byMemory.get(event.memoryId) || [];
-            existing.push(event);
-            byMemory.set(event.memoryId, existing);
-        }
-        // Update each memory's telemetry
-        for (const [memoryId, memEvents] of byMemory.entries()) {
-            const echoCount = memEvents.filter(e => e.wasUsed).length;
-            const fizzleCount = memEvents.filter(e => !e.wasUsed).length;
-            // Get current stats
-            const memories = await db
-                .select()
-                .from(schema.memories)
-                .where(eq(schema.memories.id, memoryId))
-                .limit(1);
-            if (memories.length > 0) {
-                const current = memories[0];
-                const newEchoCount = (current.echoCount || 0) + echoCount;
-                const newFizzleCount = (current.fizzleCount || 0) + fizzleCount;
-                const newRetrievalCount = (current.retrievalCount || 0) + memEvents.length;
-                await db
-                    .update(schema.memories)
-                    .set({
-                    echoCount: newEchoCount,
-                    fizzleCount: newFizzleCount,
-                    retrievalCount: newRetrievalCount,
-                    lastRetrievedAt: new Date(),
-                    updatedAt: new Date(),
-                })
-                    .where(eq(schema.memories.id, memoryId));
-            }
-        }
-        logger.debug('Flushed retrieval events', { count: events.length });
-    }
-    catch (error) {
-        logger.error('Error flushing retrieval events', error);
-        // Re-add events to cache on failure
-        retrievalEvents.push(...events);
-    }
-}
-/**
- * Increment memory's echo count directly
- */
-async function incrementMemoryEcho(memoryId) {
-    try {
-        const db = await getDb();
-        const schema = await getSchema();
-        const memories = await db
-            .select()
-            .from(schema.memories)
-            .where(eq(schema.memories.id, memoryId))
-            .limit(1);
-        if (memories.length > 0) {
-            const current = memories[0];
-            await db
-                .update(schema.memories)
-                .set({
-                echoCount: (current.echoCount || 0) + 1,
-                lastEchoedAt: new Date(),
-                coactivationScore: (current.coactivationScore || 0) + 1,
-                updatedAt: new Date(),
-            })
-                .where(eq(schema.memories.id, memoryId));
-        }
-    }
-    catch (error) {
-        logger.debug('Error incrementing echo count', { error });
-    }
-}
-/**
- * Increment memory's fizzle count directly
- */
-async function incrementMemoryFizzle(memoryId) {
-    try {
-        const db = await getDb();
-        const schema = await getSchema();
-        const memories = await db
-            .select()
-            .from(schema.memories)
-            .where(eq(schema.memories.id, memoryId))
-            .limit(1);
-        if (memories.length > 0) {
-            const current = memories[0];
-            await db
-                .update(schema.memories)
-                .set({
-                fizzleCount: (current.fizzleCount || 0) + 1,
-                updatedAt: new Date(),
-            })
-                .where(eq(schema.memories.id, memoryId));
-        }
-    }
-    catch (error) {
-        logger.debug('Error incrementing fizzle count', { error });
-    }
-}
-/**
- * Get telemetry for a specific memory
- */
-export async function getMemoryTelemetry(memoryId) {
-    try {
-        const db = await getDb();
-        const schema = await getSchema();
-        const memories = await db
-            .select()
-            .from(schema.memories)
-            .where(eq(schema.memories.id, memoryId))
-            .limit(1);
-        if (memories.length === 0)
-            return null;
-        const m = memories[0];
-        const echoCount = m.echoCount || 0;
-        const fizzleCount = m.fizzleCount || 0;
-        const total = echoCount + fizzleCount;
-        return {
-            memoryId: m.id,
-            retrievalCount: m.retrievalCount || 0,
-            echoCount,
-            fizzleCount,
-            echoRate: total > 0 ? echoCount / total : 0,
-            avgPosition: 0, // Would need to calculate from retrieval events
-            lastRetrieved: m.lastRetrievedAt,
-            lastEchoed: m.lastEchoedAt,
-        };
-    }
-    catch (error) {
-        logger.error('Error getting memory telemetry', error);
-        return null;
-    }
-}
-/**
- * Get overall retrieval statistics
- */
-export async function getRetrievalStats(projectId) {
-    try {
-        const db = await getDb();
-        const schema = await getSchema();
-        const whereClause = projectId
-            ? eq(schema.memories.projectId, projectId)
-            : undefined;
-        const memories = await db
-            .select()
-            .from(schema.memories)
-            .where(whereClause)
-            .orderBy(desc(schema.memories.retrievalCount))
-            .limit(1000);
-        let totalRetrievals = 0;
-        let totalEchoes = 0;
-        let totalFizzles = 0;
-        const topMemories = [];
-        const underperforming = [];
-        for (const m of memories) {
-            const echoes = m.echoCount || 0;
-            const fizzles = m.fizzleCount || 0;
-            const retrievals = m.retrievalCount || 0;
-            totalRetrievals += retrievals;
-            totalEchoes += echoes;
-            totalFizzles += fizzles;
-            // Top performers (high echo rate with sufficient data)
-            if (echoes >= 3 && (echoes / (echoes + fizzles)) >= 0.8) {
-                topMemories.push(m.id);
-            }
-            // Underperformers (high fizzle rate with sufficient data)
-            if (fizzles >= 5 && (fizzles / (echoes + fizzles)) >= 0.7) {
-                underperforming.push(m.id);
-            }
-        }
-        const echoRate = (totalEchoes + totalFizzles) > 0
-            ? totalEchoes / (totalEchoes + totalFizzles)
-            : 0;
-        return {
-            totalRetrievals,
-            echoes: totalEchoes,
-            fizzles: totalFizzles,
-            echoRate,
-            avgPosition: 0, // Would need more detailed tracking
-            topMemories: topMemories.slice(0, 10),
-            underperformingMemories: underperforming.slice(0, 10),
-        };
-    }
-    catch (error) {
-        logger.error('Error getting retrieval stats', error);
-        return {
-            totalRetrievals: 0,
-            echoes: 0,
-            fizzles: 0,
-            echoRate: 0,
-            avgPosition: 0,
-            topMemories: [],
-            underperformingMemories: [],
-        };
-    }
-}
-/**
- * Adjust retrieval boosting based on echo/fizzle history
- * Returns a boost factor (0.5 - 2.0) for a memory
- */
-export function calculateTelemetryBoost(telemetry) {
-    if (!telemetry || telemetry.retrievalCount < 3) {
-        return 1.0; // Not enough data
-    }
-    const echoRate = telemetry.echoRate;
-    // High echo rate = boost
-    if (echoRate >= 0.8) {
-        return 1.5;
-    }
-    else if (echoRate >= 0.6) {
-        return 1.2;
-    }
-    else if (echoRate >= 0.4) {
-        return 1.0;
-    }
-    else if (echoRate >= 0.2) {
-        return 0.8;
-    }
-    else {
-        return 0.5; // Low echo rate = penalize
-    }
-}
-/**
- * Periodic cleanup job for telemetry data
- */
-export async function cleanupOldTelemetry(daysToKeep = 90) {
-    // This would typically clean up a dedicated telemetry_events table
-    // For now, we just flush the in-memory cache
-    await flushRetrievalEvents();
-    return 0;
-}
-//# sourceMappingURL=telemetry.js.map

package/dist/core/memory/temporal-facts.d.ts

@@ -1,41 +0,0 @@
-/**
- * Temporal Facts Lifecycle
- * Manages temporal fact validity, supersession, and expiration
- * Integrates with the memory pipeline to automatically supersede outdated facts
- */
-export interface TemporalValidityCheck {
-    isValid: boolean;
-    supersededBy?: string;
-    expiresAt?: Date;
-    confidence: number;
-}
-export interface SupersessionResult {
-    supersededCount: number;
-    newValidFrom: Date;
-    newValidTo?: Date;
-}
-/**
- * Check temporal validity of a memory
- * Returns whether the memory is still valid based on temporal facts
- */
-export declare function checkTemporalValidity(memoryId: string): Promise<TemporalValidityCheck>;
-/**
- * Auto-supersede temporal facts that have been updated
- * Call this when storing a new memory that may supersede old temporal facts
- */
-export declare function supersedeOldTemporalFacts(newMemoryId: string, content: string, projectId?: string): Promise<SupersessionResult>;
-/**
- * Clean up expired temporal facts
- * Can be run as a background job
- */
-export declare function cleanupExpiredTemporalFacts(projectId?: string): Promise<number>;
-/**
- * Get temporal fact statistics for a project
- */
-export declare function getTemporalFactsStats(projectId?: string): Promise<{
-    totalTemporalFacts: number;
-    validFacts: number;
-    expiredFacts: number;
-    supersededFacts: number;
-}>;
-//# sourceMappingURL=temporal-facts.d.ts.map

package/dist/core/memory/temporal-facts.js

@@ -1,283 +0,0 @@
-/**
- * Temporal Facts Lifecycle
- * Manages temporal fact validity, supersession, and expiration
- * Integrates with the memory pipeline to automatically supersede outdated facts
- */
-import { eq, and, lt } from 'drizzle-orm';
-import { getDb } from '../../db/index.js';
-import { getSchema } from '../../db/schema.js';
-import { logger } from '../logger.js';
-import { createAssociation } from '../associations.js';
-import { parseTemporalFacts } from './temporal-parser.js';
-/**
- * Check temporal validity of a memory
- * Returns whether the memory is still valid based on temporal facts
- */
-export async function checkTemporalValidity(memoryId) {
-    try {
-        const db = await getDb();
-        if (!db) {
-            // Graceful fallback when database is unavailable
-            return { isValid: true, confidence: 0.5 };
-        }
-        const schema = await getSchema();
-        const memories = await db
-            .select()
-            .from(schema.memories)
-            .where(eq(schema.memories.id, memoryId))
-            .limit(1);
-        if (memories.length === 0) {
-            return { isValid: false, confidence: 0 };
-        }
-        const memory = memories[0];
-        const now = new Date();
-        // Check if memory has explicit validity period
-        if (memory.validTo) {
-            const validTo = new Date(memory.validTo);
-            if (validTo < now) {
-                // Find if there's a superseding memory
-                const superseding = await db
-                    .select()
-                    .from(schema.memories)
-                    .where(eq(schema.memories.supersedes, memoryId))
-                    .limit(1);
-                return {
-                    isValid: false,
-                    supersededBy: superseding[0]?.id,
-                    expiresAt: validTo,
-                    confidence: 0.95,
-                };
-            }
-        }
-        // Parse temporal facts from content
-        const temporalFacts = await parseTemporalFacts(memory.content);
-        // Check for expiration indicators
-        for (const fact of temporalFacts) {
-            if (fact.parsed.end && new Date(fact.parsed.end) < now) {
-                return {
-                    isValid: false,
-                    expiresAt: new Date(fact.parsed.end),
-                    confidence: fact.confidence,
-                };
-            }
-        }
-        return { isValid: true, confidence: 1.0 };
-    }
-    catch (error) {
-        logger.error('Error checking temporal validity', error);
-        return { isValid: true, confidence: 0.5 }; // Assume valid on error
-    }
-}
-/**
- * Auto-supersede temporal facts that have been updated
- * Call this when storing a new memory that may supersede old temporal facts
- */
-export async function supersedeOldTemporalFacts(newMemoryId, content, projectId) {
-    const result = {
-        supersededCount: 0,
-        newValidFrom: new Date(),
-    };
-    try {
-        const db = await getDb();
-        if (!db) {
-            // Graceful fallback when database is unavailable
-            return result;
-        }
-        const schema = await getSchema();
-        // Parse temporal facts from new content
-        const temporalFacts = await parseTemporalFacts(content);
-        if (temporalFacts.length === 0) {
-            return result;
-        }
-        // Find the earliest date as validFrom
-        const dates = temporalFacts
-            .filter(f => f.parsed.start)
-            .map(f => new Date(f.parsed.start));
-        if (dates.length > 0) {
-            result.newValidFrom = new Date(Math.min(...dates.map(d => d.getTime())));
-        }
-        // Find memories in same project with overlapping temporal scope
-        const whereClause = projectId
-            ? and(eq(schema.memories.projectId, projectId), eq(schema.memories.status, 'active'))
-            : eq(schema.memories.status, 'active');
-        const candidates = await db
-            .select()
-            .from(schema.memories)
-            .where(whereClause)
-            .limit(100);
-        const toSupersede = [];
-        for (const candidate of candidates) {
-            if (candidate.id === newMemoryId)
-                continue;
-            if (candidate.isProtected)
-                continue;
-            // Check for temporal overlap
-            const candidateFacts = await parseTemporalFacts(candidate.content);
-            for (const newFact of temporalFacts) {
-                for (const candidateFact of candidateFacts) {
-                    if (factsOverlap(newFact, candidateFact)) {
-                        // Check if new fact is more recent
-                        if (isMoreRecent(newFact, candidateFact)) {
-                            toSupersede.push(candidate.id);
-                            break;
-                        }
-                    }
-                }
-            }
-        }
-        // Apply supersession
-        if (toSupersede.length > 0) {
-            const now = new Date();
-            await db
-                .update(schema.memories)
-                .set({
-                status: 'superseded',
-                supersededBy: newMemoryId,
-                supersededAt: now,
-                updatedAt: now,
-            })
-                .where(eq(schema.memories.id, toSupersede[0])); // Batch for all
-            // Create associations
-            for (const oldId of toSupersede) {
-                await createAssociation(newMemoryId, oldId, 'supersedes', 0.85);
-            }
-            result.supersededCount = toSupersede.length;
-            logger.info('Superseded temporal facts', {
-                newMemoryId,
-                supersededCount: toSupersede.length,
-            });
-        }
-    }
-    catch (error) {
-        logger.error('Error superseding temporal facts', error);
-    }
-    return result;
-}
-/**
- * Check if two temporal facts overlap in time
- */
-function factsOverlap(fact1, fact2) {
-    // Both need start dates to compare
-    if (!fact1.parsed.start || !fact2.parsed.start) {
-        return false;
-    }
-    const start1 = new Date(fact1.parsed.start).getTime();
-    const end1 = fact1.parsed.end ? new Date(fact1.parsed.end).getTime() : Infinity;
-    const start2 = new Date(fact2.parsed.start).getTime();
-    const end2 = fact2.parsed.end ? new Date(fact2.parsed.end).getTime() : Infinity;
-    // Check for overlap
-    return start1 <= end2 && start2 <= end1;
-}
-/**
- * Check if fact1 is more recent than fact2
- */
-function isMoreRecent(fact1, fact2) {
-    if (!fact1.parsed.start)
-        return false;
-    if (!fact2.parsed.start)
-        return true;
-    const date1 = new Date(fact1.parsed.start).getTime();
-    const date2 = new Date(fact2.parsed.start).getTime();
-    return date1 > date2;
-}
-/**
- * Clean up expired temporal facts
- * Can be run as a background job
- */
-export async function cleanupExpiredTemporalFacts(projectId) {
-    let expiredCount = 0;
-    try {
-        const db = await getDb();
-        if (!db) {
-            // Graceful fallback when database is unavailable
-            return 0;
-        }
-        const schema = await getSchema();
-        const now = new Date();
-        const whereClause = projectId
-            ? and(eq(schema.memories.projectId, projectId), eq(schema.memories.status, 'active'), lt(schema.memories.validTo, now))
-            : and(eq(schema.memories.status, 'active'), lt(schema.memories.validTo, now));
-        const expired = await db
-            .select()
-            .from(schema.memories)
-            .where(whereClause);
-        for (const memory of expired) {
-            if (memory.isProtected)
-                continue;
-            await db
-                .update(schema.memories)
-                .set({
-                status: 'expired',
-                expiredAt: now,
-                updatedAt: now,
-            })
-                .where(eq(schema.memories.id, memory.id));
-            expiredCount++;
-        }
-        if (expiredCount > 0) {
-            logger.info('Cleaned up expired temporal facts', { expiredCount });
-        }
-    }
-    catch (error) {
-        logger.error('Error cleaning up expired temporal facts', error);
-    }
-    return expiredCount;
-}
-/**
- * Get temporal fact statistics for a project
- */
-export async function getTemporalFactsStats(projectId) {
-    try {
-        const db = await getDb();
-        if (!db) {
-            // Graceful fallback when database is unavailable
-            return {
-                totalTemporalFacts: 0,
-                validFacts: 0,
-                expiredFacts: 0,
-                supersededFacts: 0,
-            };
-        }
-        const schema = await getSchema();
-        const now = new Date();
-        const whereClause = projectId
-            ? eq(schema.memories.projectId, projectId)
-            : undefined;
-        const memories = await db
-            .select()
-            .from(schema.memories)
-            .where(whereClause);
-        let totalTemporalFacts = 0;
-        let validFacts = 0;
-        let expiredFacts = 0;
-        let supersededFacts = 0;
-        for (const memory of memories) {
-            // Check if memory has temporal facts
-            const facts = await parseTemporalFacts(memory.content);
-            if (facts.length > 0) {
-                totalTemporalFacts++;
-                if (memory.status === 'expired') {
-                    expiredFacts++;
-                }
-                else if (memory.status === 'superseded') {
-                    supersededFacts++;
-                }
-                else if (memory.status === 'active') {
-                    // Check if still valid
-                    if (memory.validTo && new Date(memory.validTo) < now) {
-                        expiredFacts++;
-                    }
-                    else {
-                        validFacts++;
-                    }
-                }
-            }
-        }
-        return { totalTemporalFacts, validFacts, expiredFacts, supersededFacts };
-    }
-    catch (error) {
-        logger.error('Error getting temporal facts stats', error);
-        return { totalTemporalFacts: 0, validFacts: 0, expiredFacts: 0, supersededFacts: 0 };
-    }
-}
-//# sourceMappingURL=temporal-facts.js.map

package/dist/core/memory/temporal-parser.d.ts

@@ -1,32 +0,0 @@
-/**
- * Temporal Parser
- * Parses temporal expressions and creates time-based relationships between memories
- * Handles absolute dates, relative times, durations, and frequencies
- */
-export type TemporalExpressionType = 'absolute' | 'relative' | 'duration' | 'frequency';
-export interface TemporalFact {
-    type: TemporalExpressionType;
-    value: string;
-    parsed: {
-        start?: Date;
-        end?: Date;
-        duration?: number;
-        frequency?: string;
-    };
-    confidence: number;
-    context: string;
-}
-export interface TemporalRelation {
-    type: 'before' | 'after' | 'during' | 'overlaps' | 'supersedes' | 'contradicts';
-    targetMemoryId: string;
-    confidence: number;
-}
-/**
- * Parse temporal expressions from content
- */
-export declare function parseTemporalFacts(content: string, referenceDate?: Date): Promise<TemporalFact[]>;
-/**
- * Link temporal relations between memories
- */
-export declare function linkTemporalRelations(memoryId: string, facts: TemporalFact[]): Promise<TemporalRelation[]>;
-//# sourceMappingURL=temporal-parser.d.ts.map