squish-memory 1.0.2 → 1.2.0

package/dist/core/lib/utils.js

@@ -0,0 +1,145 @@
+/**
+ * Shared utility functions for the squish codebase
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { config } from '../../config.js';
+import { toSqliteJson } from '../memory/serialization.js';
+export function normalizeTimestamp(value) {
+    if (!value)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === 'number') {
+        try {
+            // Handle different timestamp formats using magnitude thresholds
+            // Microseconds: > 100000000000000 (e.g., 1700000000000000)
+            // Milliseconds: > 1000000000000 (e.g., 1700000000000)
+            // Seconds: <= 1000000000000 (e.g., 1700000000)
+            if (value > 100000000000000) {
+                return new Date(value / 1000).toISOString();
+            }
+            else if (value > 1000000000000) {
+                return new Date(value).toISOString();
+            }
+            else if (value >= 0) {
+                return new Date(value * 1000).toISOString();
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof value === 'string') {
+        try {
+            const parsed = new Date(value);
+            if (!isNaN(parsed.getTime()))
+                return parsed.toISOString();
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+export function now() {
+    return new Date().toISOString();
+}
+export function isDatabaseUnavailableError(error) {
+    const message = error?.message || '';
+    return [
+        'Database unavailable',
+        'not a valid Win32 application',
+        'invalid ELF header',
+        'bun:',
+        'sql.js wasm asset not found',
+        'SQLite database initialization failed',
+        'working local SQLite driver',
+    ].some((pattern) => message.includes(pattern));
+}
+export async function withDatabaseErrorHandling(operation, errorMessage) {
+    try {
+        return await operation();
+    }
+    catch (dbError) {
+        if (isDatabaseUnavailableError(dbError)) {
+            throw new McpError(ErrorCode.InternalError, errorMessage);
+        }
+        throw dbError;
+    }
+}
+export function clampLimit(value, defaultValue, min = 1, max = 100) {
+    return Math.min(Math.max(value ?? defaultValue, min), max);
+}
+export function prepareEmbedding(embedding) {
+    if (config.isTeamMode) {
+        return { embedding: embedding ?? null };
+    }
+    return { embeddingJson: toSqliteJson(embedding ?? null) };
+}
+export function determineOverallStatus(dbStatus, redisOk) {
+    if ((dbStatus === 'ok' || dbStatus === 'unavailable') && redisOk) {
+        return 'ok';
+    }
+    if (dbStatus === 'unavailable') {
+        return 'degraded';
+    }
+    return 'error';
+}
+// Date parsing utilities - shared between CLI and MCP
+// ============================================================================
+export function parseDate(input) {
+    if (!input)
+        return null;
+    const now = new Date();
+    const lower = input.toLowerCase().trim();
+    // Direct date parse
+    const parsed = new Date(input);
+    if (!isNaN(parsed.getTime()))
+        return parsed;
+    // Relative parsing
+    const dayMatch = lower.match(/(\d+)\s*day/i);
+    const weekMatch = lower.match(/(\d+)\s*week/i);
+    const monthMatch = lower.match(/(\d+)\s*month/i);
+    if (lower === 'today') {
+        const d = new Date(now);
+        d.setHours(0, 0, 0, 0);
+        return d;
+    }
+    if (lower === 'yesterday')
+        return new Date(now.getTime() - 86400000);
+    if (lower === 'thisweek' || lower === 'this week') {
+        const d = new Date(now);
+        d.setDate(d.getDate() - d.getDay());
+        d.setHours(0, 0, 0, 0);
+        return d;
+    }
+    if (lower === 'lastweek' || lower === 'last week') {
+        const d = new Date(now);
+        d.setDate(d.getDate() - d.getDay() - 7);
+        return d;
+    }
+    if (dayMatch)
+        return new Date(now.getTime() - parseInt(dayMatch[1]) * 86400000);
+    if (weekMatch)
+        return new Date(now.getTime() - parseInt(weekMatch[1]) * 604800000);
+    if (monthMatch)
+        return new Date(now.getTime() - parseInt(monthMatch[1]) * 2592000000);
+    return null;
+}
+export function filterByDateRange(items, since, until) {
+    const sinceDate = parseDate(since || '');
+    const untilDate = parseDate(until || '');
+    return items.filter(item => {
+        if (!item.createdAt)
+            return true;
+        const created = new Date(item.createdAt);
+        if (sinceDate && created < sinceDate)
+            return false;
+        if (untilDate && created > untilDate)
+            return false;
+        return true;
+    });
+}
+//# sourceMappingURL=utils.js.map

package/dist/core/lib/validation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Input validation utilities for Squish
+ * Consolidates scattered validation patterns into a unified module
+ */
+import { normalizeTags } from '../memory/serialization.js';
+/**
+ * Validate and normalize a limit value with bounds checking
+ */
+export declare function validateLimit(value: number | string | undefined, defaultValue?: number, min?: number, max?: number): number;
+/**
+ * Parse an integer with bounds checking
+ */
+export declare function parseIntBounded(value: number | string | undefined, defaultValue: number, min: number, max: number): number;
+/**
+ * Validate a project path
+ */
+export declare function validateProjectPath(path: string | undefined, options?: {
+    createIfMissing?: boolean;
+    require?: boolean;
+}): Promise<string>;
+/**
+ * Validate a UUID
+ */
+export declare function validateUuid(id: string): boolean;
+/**
+ * Require a valid UUID, throws if invalid
+ */
+export declare function requireUuid(id: string): string;
+/**
+ * Validate a date value
+ *
+ * @param value - The date to validate (string, Date, number, or undefined)
+ * @returns Date object if valid, null otherwise
+ */
+export declare function validateDate(value: string | Date | number | undefined): Date | null;
+export { normalizeTags };
+export { clampLimit } from './utils.js';
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/lib/validation.js

@@ -0,0 +1,151 @@
+/**
+ * Input validation utilities for Squish
+ * Consolidates scattered validation patterns into a unified module
+ */
+import { normalizeTags } from '../memory/serialization.js';
+/**
+ * Validate and normalize a limit value with bounds checking
+ */
+export function validateLimit(value, defaultValue = 20, min = 1, max = 100) {
+    // Handle undefined, null, empty string
+    if (value === undefined || value === null || value === '') {
+        return defaultValue;
+    }
+    // Convert string to number, truncate decimals
+    let num;
+    if (typeof value === 'string') {
+        const parsed = parseInt(value, 10);
+        if (isNaN(parsed)) {
+            return NaN;
+        }
+        num = parsed;
+    }
+    else {
+        // Truncate decimals for numbers
+        num = Math.trunc(value);
+    }
+    // Handle NaN
+    if (isNaN(num)) {
+        return NaN;
+    }
+    // Clamp to bounds
+    return Math.min(Math.max(num, min), max);
+}
+/**
+ * Parse an integer with bounds checking
+ */
+export function parseIntBounded(value, defaultValue, min, max) {
+    return validateLimit(value, defaultValue, min, max);
+}
+/**
+ * Validate a project path
+ */
+export async function validateProjectPath(path, options) {
+    const { createIfMissing = false, require: requireProject = false } = options || {};
+    // If path is undefined, throw if required or return current directory
+    if (path === undefined || path === '') {
+        if (requireProject) {
+            throw new Error('Project path is required');
+        }
+        return process.cwd();
+    }
+    // Resolve to absolute path
+    const absolutePath = path.startsWith('/') || /^[a-zA-Z]:\\/.test(path)
+        ? path
+        : path.startsWith('~')
+            ? path.replace(/^~/, process.env.HOME || process.env.USERPROFILE || '')
+            : path.startsWith('.')
+                ? path
+                : path;
+    // Check if project exists in database
+    const { getProjectByPath } = await import('../projects.js');
+    const existingProject = await getProjectByPath(absolutePath);
+    if (existingProject) {
+        return absolutePath;
+    }
+    // Project doesn't exist
+    if (requireProject) {
+        throw new Error(`Project not found: ${absolutePath}`);
+    }
+    if (createIfMissing) {
+        const { ensureProject } = await import('../projects.js');
+        await ensureProject(absolutePath);
+        return absolutePath;
+    }
+    // Return the path even if it doesn't exist in database (for non-db validation)
+    return absolutePath;
+}
+/**
+ * Validate a UUID
+ */
+export function validateUuid(id) {
+    if (typeof id !== 'string' || !id) {
+        return false;
+    }
+    // UUID v4/v5 regex pattern (8-4-4-4-12 hex digits)
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(id);
+}
+/**
+ * Require a valid UUID, throws if invalid
+ */
+export function requireUuid(id) {
+    if (!validateUuid(id)) {
+        throw new Error('Invalid UUID');
+    }
+    return id;
+}
+/**
+ * Validate a date value
+ *
+ * @param value - The date to validate (string, Date, number, or undefined)
+ * @returns Date object if valid, null otherwise
+ */
+export function validateDate(value) {
+    if (!value) {
+        return null;
+    }
+    try {
+        let date;
+        if (value instanceof Date) {
+            date = value;
+        }
+        else if (typeof value === 'number') {
+            // Handle both milliseconds and seconds timestamps
+            if (value > 100000000000000) {
+                // Microseconds, convert to milliseconds
+                date = new Date(value / 1000);
+            }
+            else if (value > 1000000000000) {
+                // Milliseconds
+                date = new Date(value);
+            }
+            else if (value >= 0) {
+                // Seconds
+                date = new Date(value * 1000);
+            }
+            else {
+                return null;
+            }
+        }
+        else if (typeof value === 'string') {
+            date = new Date(value);
+        }
+        else {
+            return null;
+        }
+        // Check if date is valid
+        if (isNaN(date.getTime())) {
+            return null;
+        }
+        return date;
+    }
+    catch {
+        return null;
+    }
+}
+// Re-export normalizeTags for tag validation
+export { normalizeTags };
+// Re-export clampLimit for backward compatibility
+export { clampLimit } from './utils.js';
+//# sourceMappingURL=validation.js.map

package/dist/core/lifecycle.d.ts

@@ -1,6 +1,12 @@
 /**
  * Memory Lifecycle Management
  * Implements sector-based decay, tier classification, and eviction policies
+ *
+ * Decay Formula: newScore = importanceScore * (1 - decayRate/100)^days
+ * - decayRate: per-memory integer (e.g., 30 = 30% decay per decay cycle)
+ * - days: days since lastDecayAt
+ * - Tier demotion occurs when score drops below decayThreshold
+ * - Cold memories below threshold get status = 'expired'
  */
 export interface LifecycleStats {
     decayed: number;
@@ -8,9 +14,9 @@ export interface LifecycleStats {
     promoted: number;
     tierChanges: {
         hot: number;
-        warm: number;
         cold: number;
     };
+    expired: number;
 }
 /**
  * Run full lifecycle maintenance on all memories

package/dist/core/lifecycle.js

@@ -1,22 +1,46 @@
 /**
  * Memory Lifecycle Management
  * Implements sector-based decay, tier classification, and eviction policies
+ *
+ * Decay Formula: newScore = importanceScore * (1 - decayRate/100)^days
+ * - decayRate: per-memory integer (e.g., 30 = 30% decay per decay cycle)
+ * - days: days since lastDecayAt
+ * - Tier demotion occurs when score drops below decayThreshold
+ * - Cold memories below threshold get status = 'expired'
  */
 import { and, eq, lt, inArray } from 'drizzle-orm';
 import { getDb } from '../db/index.js';
 import { getSchema } from '../db/schema.js';
 import { config } from '../config.js';
 import { logger } from './logger.js';
-const SECTOR_DECAY_RATES = {
-    episodic: 30,
-    semantic: 90,
-    procedural: 180,
-    autobiographical: 365,
-    working: 7,
+import { triggerTierChange, triggerDecayApplied } from './memory/hooks.js';
+/**
+ * Default decay intervals by sector (days until decay check)
+ * These determine how often memories in each sector are evaluated for decay
+ * Can be configured via config.sectorDecayIntervals
+ */
+const SECTOR_DECAY_INTERVAL_DAYS = {
+    episodic: config.sectorDecayIntervals?.episodic || 30,
+    semantic: config.sectorDecayIntervals?.semantic || 90,
+    procedural: config.sectorDecayIntervals?.procedural || 180,
+    autobiographical: config.sectorDecayIntervals?.autobiographical || 365,
+    working: config.sectorDecayIntervals?.working || 7,
+};
+/**
+ * Default decay rates by memory type (percentage per decay cycle)
+ * Used as fallback when memory.decayRate is not set
+ */
+const DEFAULT_DECAY_RATES = {
+    observation: 5,
+    fact: 3,
+    decision: 2,
+    context: 4,
+    preference: 3,
+    note: 5,
+    reflection: 2,
 };
 const TIER_THRESHOLDS = {
     hot: { recency: 7, coactivation: 10, salience: 70 },
-    warm: { recency: 30, coactivation: 5, salience: 50 },
     cold: { recency: Infinity, coactivation: 0, salience: 0 },
 };
 /**
@@ -24,13 +48,14 @@ const TIER_THRESHOLDS = {
  */
 export async function runLifecycleMaintenance(projectId) {
     if (!config.lifecycleEnabled) {
-        return { decayed: 0, evicted: 0, promoted: 0, tierChanges: { hot: 0, warm: 0, cold: 0 } };
+        return { decayed: 0, evicted: 0, promoted: 0, tierChanges: { hot: 0, cold: 0 }, expired: 0 };
     }
     const stats = {
         decayed: 0,
         evicted: 0,
         promoted: 0,
-        tierChanges: { hot: 0, warm: 0, cold: 0 },
+        tierChanges: { hot: 0, cold: 0 },
+        expired: 0,
     };
     try {
         await applyDecay(projectId, stats);
@@ -43,34 +68,105 @@ export async function runLifecycleMaintenance(projectId) {
     return stats;
 }
 /**
- * Apply decay to memories based on sector
+ * Apply decay to memories using per-memory decay rate formula
+ *
+ * Formula: newScore = importanceScore * (1 - decayRate/100)^days
+ * - Uses per-memory decayRate (stored as integer percentage, e.g., 30 = 30%)
+ * - Calculates days since lastDecayAt
+ * - Demotes tier when score drops below decayThreshold
+ * - Sets status = 'expired' for cold memories below threshold
  */
 async function applyDecay(projectId, stats) {
     try {
         const db = await getDb();
         const schema = await getSchema();
         const now = new Date();
-        // For each sector, apply decay
-        for (const [sector, decayDays] of Object.entries(SECTOR_DECAY_RATES)) {
-            const decayThreshold = new Date(now.getTime() - decayDays * 24 * 60 * 60 * 1000);
-            // Build where clause
-            let where;
-            if (projectId) {
-                where = and(eq(schema.memories.sector, sector), eq(schema.memories.projectId, projectId), lt(schema.memories.lastDecayAt, decayThreshold), eq(schema.memories.isProtected, false));
+        const decayThreshold = config.decayThreshold || 0.1;
+        // Fetch memories that need decay processing (not protected, not expired)
+        let whereClause;
+        const conditions = [
+            eq(schema.memories.isProtected, false),
+            eq(schema.memories.status, 'active'),
+        ];
+        if (projectId) {
+            conditions.push(eq(schema.memories.projectId, projectId));
+        }
+        whereClause = and(...conditions);
+        const memories = await db
+            .select()
+            .from(schema.memories)
+            .where(whereClause)
+            .limit(10000);
+        let decayed = 0;
+        let expired = 0;
+        const expiredIds = [];
+        for (const memory of memories) {
+            // Get decay rate for this memory (fallback to type-based default)
+            const decayRate = memory.decayRate || DEFAULT_DECAY_RATES[memory.type] || 5;
+            // Calculate days since last decay
+            const lastDecayAt = memory.lastDecayAt ? new Date(memory.lastDecayAt) : new Date(memory.createdAt);
+            const daysSinceDecay = Math.max(0, (now.getTime() - lastDecayAt.getTime()) / (24 * 60 * 60 * 1000));
+            // Skip if not enough time has passed for this sector
+            const sectorInterval = SECTOR_DECAY_INTERVAL_DAYS[memory.sector] || 30;
+            if (daysSinceDecay < sectorInterval) {
+                continue;
+            }
+            // Apply decay formula: newScore = oldScore * (1 - decayRate/100)^days
+            const currentScore = memory.importanceScore || memory.relevanceScore || 50;
+            const decayMultiplier = Math.pow(1 - decayRate / 100, daysSinceDecay / sectorInterval);
+            const newScore = Math.max(0, Math.round(currentScore * decayMultiplier));
+            // Check if memory should expire (cold tier + below threshold)
+            const shouldExpire = memory.tier === 'cold' && newScore < (decayThreshold * 100);
+            if (shouldExpire) {
+                expiredIds.push(memory.id);
+                expired++;
+                logger.debug('Memory expiring', { id: memory.id, score: newScore, tier: memory.tier });
             }
-            else {
-                where = and(eq(schema.memories.sector, sector), lt(schema.memories.lastDecayAt, decayThreshold), eq(schema.memories.isProtected, false));
+            else if (newScore !== currentScore) {
+                // Only update if score changed
+                await db
+                    .update(schema.memories)
+                    .set({
+                    importanceScore: newScore,
+                    relevanceScore: newScore,
+                    lastDecayAt: now,
+                    updatedAt: now,
+                })
+                    .where(eq(schema.memories.id, memory.id));
+                decayed++;
+                // Trigger decay applied hook
+                try {
+                    await triggerDecayApplied({
+                        memoryId: memory.id,
+                        content: memory.content,
+                        type: memory.type,
+                        tags: typeof memory.tags === 'string' ? memory.tags.split(',') : [],
+                        project: memory.projectId || undefined,
+                        source: memory.source || undefined,
+                        tier: memory.tier,
+                        importance: newScore,
+                        oldScore: currentScore,
+                        newScore: newScore,
+                    });
+                }
+                catch (hookError) {
+                    logger.error('Error triggering decayApplied hook', hookError);
+                }
             }
-            // Decay: reduce relevance score by 10%
-            const result = await db.update(schema.memories)
+        }
+        // Batch expire memories
+        if (expiredIds.length > 0) {
+            await db
+                .update(schema.memories)
                 .set({
-                relevanceScore: Math.max(0, schema.memories.relevanceScore * 0.9),
-                lastDecayAt: now,
+                status: 'expired',
+                updatedAt: now,
             })
-                .where(where);
-            const rowCount = result?.rowCount || 0;
-            stats.decayed += rowCount;
+                .where(inArray(schema.memories.id, expiredIds));
         }
+        stats.decayed += decayed;
+        stats.expired += expired;
+        logger.info('Decay applied', { decayed, expired, total: memories.length });
     }
     catch (error) {
         logger.error('Error applying decay', error);
@@ -78,7 +174,6 @@ async function applyDecay(projectId, stats) {
 }
 /**
  * Update memory tiers based on recency, coactivation, and salience
- * OPTIMIZED: Uses batched updates instead of individual UPDATE queries
  */
 async function updateTiers(projectId, stats) {
     try {
@@ -92,9 +187,9 @@ async function updateTiers(projectId, stats) {
             .from(schema.memories)
             .where(where)
             .limit(10000); // Process larger batches now
-        // Calculate tiers in memory
+        // Calculate tiers in memory (simplified: hot or cold only)
         const tierAssignments = new Map();
-        const tierCounts = { hot: 0, warm: 0, cold: 0 };
+        const tierCounts = { hot: 0, cold: 0 };
         for (const memory of memories) {
             const recencyDays = (now.getTime() - new Date(memory.createdAt).getTime()) / (24 * 60 * 60 * 1000);
             const coactivation = memory.coactivationScore || 0;
@@ -105,11 +200,6 @@ async function updateTiers(projectId, stats) {
                 salience >= TIER_THRESHOLDS.hot.salience) {
                 newTier = 'hot';
             }
-            else if (recencyDays <= TIER_THRESHOLDS.warm.recency &&
-                coactivation >= TIER_THRESHOLDS.warm.coactivation &&
-                salience >= TIER_THRESHOLDS.warm.salience) {
-                newTier = 'warm';
-            }
             if (newTier !== memory.tier) {
                 tierAssignments.set(memory.id, newTier);
                 tierCounts[newTier]++;
@@ -121,9 +211,6 @@ async function updateTiers(projectId, stats) {
         const hotIds = Array.from(tierAssignments.entries())
             .filter(([_, tier]) => tier === 'hot')
             .map(([id]) => id);
-        const warmIds = Array.from(tierAssignments.entries())
-            .filter(([_, tier]) => tier === 'warm')
-            .map(([id]) => id);
         const coldIds = Array.from(tierAssignments.entries())
             .filter(([_, tier]) => tier === 'cold')
             .map(([id]) => id);
@@ -134,11 +221,11 @@ async function updateTiers(projectId, stats) {
                 .set({ tier: 'hot', updatedAt: now })
                 .where(inArray(schema.memories.id, hotIds));
         }
-        if (warmIds.length > 0) {
+        if (coldIds.length > 0) {
             await db
                 .update(schema.memories)
-                .set({ tier: 'warm', updatedAt: now })
-                .where(inArray(schema.memories.id, warmIds));
+                .set({ tier: 'cold', updatedAt: now })
+                .where(inArray(schema.memories.id, coldIds));
         }
         if (coldIds.length > 0) {
             await db
@@ -146,13 +233,36 @@ async function updateTiers(projectId, stats) {
                 .set({ tier: 'cold', updatedAt: now })
                 .where(inArray(schema.memories.id, coldIds));
         }
+        // Trigger tier change hooks for each memory that changed tier
+        if (tierAssignments.size > 0) {
+            for (const memory of memories) {
+                const newTier = tierAssignments.get(memory.id);
+                if (newTier && newTier !== memory.tier) {
+                    try {
+                        await triggerTierChange({
+                            memoryId: memory.id,
+                            content: memory.content,
+                            type: memory.type,
+                            tags: typeof memory.tags === 'string' ? memory.tags.split(',') : [],
+                            project: memory.projectId || undefined,
+                            source: memory.source || undefined,
+                            tier: newTier,
+                            importance: memory.importanceScore || memory.relevanceScore || 50,
+                            oldTier: memory.tier,
+                            newTier: newTier,
+                        });
+                    }
+                    catch (hookError) {
+                        logger.error('Error triggering tierChange hook', hookError);
+                    }
+                }
+            }
+        }
         // Update stats
         stats.tierChanges.hot = tierCounts.hot;
-        stats.tierChanges.warm = tierCounts.warm;
         stats.tierChanges.cold = tierCounts.cold;
         logger.debug('Tier updates complete', {
             hot: tierCounts.hot,
-            warm: tierCounts.warm,
             cold: tierCounts.cold,
         });
     }

package/dist/core/logger.d.ts

@@ -6,6 +6,7 @@ declare class Logger {
     private debugEnabled;
     constructor(prefix?: string);
     private format;
+    private isQuiet;
     info(message: string, context?: LogContext): void;
     warn(message: string, context?: LogContext): void;
     error(message: string, error?: Error | any, context?: LogContext): void;

package/dist/core/logger.js

@@ -10,13 +10,25 @@ class Logger {
         const ctx = context ? ` ${JSON.stringify(context)}` : '';
         return `[${this.prefix}:${level}] ${message}${ctx}`;
     }
+    isQuiet() {
+        return process.env.SQUISH_QUIET === 'true' || process.env.SQUISH_QUIET === '1';
+    }
     info(message, context) {
+        if (this.isQuiet()) {
+            return;
+        }
         console.error(this.format('info', message, context));
     }
     warn(message, context) {
+        if (this.isQuiet()) {
+            return;
+        }
         console.error(this.format('warn', message, context));
     }
     error(message, error, context) {
+        if (this.isQuiet()) {
+            return;
+        }
         const errorMsg = error instanceof Error ? error.message : error;
         const ctx = { ...context, error: errorMsg };
         console.error(this.format('error', message, ctx));
@@ -25,7 +37,7 @@ class Logger {
         }
     }
     debug(message, context) {
-        if (this.debugEnabled) {
+        if (this.debugEnabled && !this.isQuiet()) {
             console.error(this.format('debug', message, context));
         }
     }