squish-memory 1.0.2 → 1.1.5

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;
@@ -11,6 +17,7 @@ export interface LifecycleStats {
         warm: number;
         cold: number;
     };
+    expired: number;
 }
 /**
  * Run full lifecycle maintenance on all memories

package/dist/core/lifecycle.js

@@ -1,19 +1,43 @@
 /**
  * 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 = {
+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
+ */
+const SECTOR_DECAY_INTERVAL_DAYS = {
     episodic: 30,
     semantic: 90,
     procedural: 180,
     autobiographical: 365,
     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 },
@@ -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, warm: 0, cold: 0 }, expired: 0 };
     }
     const stats = {
         decayed: 0,
         evicted: 0,
         promoted: 0,
         tierChanges: { hot: 0, warm: 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;
             }
-            else {
-                where = and(eq(schema.memories.sector, sector), lt(schema.memories.lastDecayAt, decayThreshold), eq(schema.memories.isProtected, false));
+            // 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 });
             }
-            // Decay: reduce relevance score by 10%
-            const result = await db.update(schema.memories)
+            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);
+                }
+            }
+        }
+        // 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 {
@@ -146,6 +241,31 @@ 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;

package/dist/core/local-embeddings.d.ts

@@ -2,5 +2,10 @@
  * Utility functions for local embeddings
  * Note: Actual embedding generation is in core/embeddings.ts
  */
-export declare function cosineSimilarity(a: number[], b: number[]): number;
+import { cosineSimilarity as vectorCosineSimilarity } from './utils/vector-operations.js';
+/**
+ * @deprecated Use cosineSimilarity from core/utils/vector-operations.ts directly.
+ *   This re-export is for backward compatibility and will be removed in v1.2.0.
+ */
+export declare const cosineSimilarity: typeof vectorCosineSimilarity;
 //# sourceMappingURL=local-embeddings.d.ts.map

package/dist/core/local-embeddings.js

@@ -2,19 +2,10 @@
  * Utility functions for local embeddings
  * Note: Actual embedding generation is in core/embeddings.ts
  */
-export function cosineSimilarity(a, b) {
-    if (a.length !== b.length) {
-        throw new Error('Embeddings must have same dimensions');
-    }
-    let dotProduct = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        dotProduct += a[i] * b[i];
-        normA += a[i] * a[i];
-        normB += b[i] * b[i];
-    }
-    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
-    return denominator === 0 ? 0 : dotProduct / denominator;
-}
+import { cosineSimilarity as vectorCosineSimilarity } from './utils/vector-operations.js';
+/**
+ * @deprecated Use cosineSimilarity from core/utils/vector-operations.ts directly.
+ *   This re-export is for backward compatibility and will be removed in v1.2.0.
+ */
+export const cosineSimilarity = vectorCosineSimilarity;
 //# sourceMappingURL=local-embeddings.js.map

package/dist/core/logger.js

@@ -1,3 +1,8 @@
+function isQuietMode() {
+    return process.env.SQUISH_QUIET !== 'false' &&
+        process.env.DEBUG !== 'true' &&
+        process.env.DEBUG !== '1';
+}
 class Logger {
     prefix;
     debugEnabled;
@@ -11,7 +16,8 @@ class Logger {
         return `[${this.prefix}:${level}] ${message}${ctx}`;
     }
     info(message, context) {
-        console.error(this.format('info', message, context));
+        if (!isQuietMode())
+            console.error(this.format('info', message, context));
     }
     warn(message, context) {
         console.error(this.format('warn', message, context));

package/dist/core/mcp/tools.js

@@ -1,5 +1,5 @@
 import { hybridSearch } from '../memory/hybrid-retrieval.js';
-import { rememberMemory, getMemoryById } from '../memory/memories.js';
+import { rememberMemory, getMemory } from '../memory/memories.js';
 import { getEmbedding } from '../embeddings.js';
 import { getQMDClient } from '../embeddings/qmd-client.js';
 import { logger } from '../logger.js';
@@ -83,13 +83,39 @@ export const squishRememberTool = {
                     type: 'string',
                     description: 'Project path',
                 },
+                // Rich context fields (Agent 4 feedback)
+                source: {
+                    type: 'string',
+                    description: 'Source of this memory (e.g., "voice", "chat", "document")',
+                },
+                reasoning: {
+                    type: 'string',
+                    description: 'Why this memory is important',
+                },
+                context: {
+                    type: 'string',
+                    description: 'What triggered this memory',
+                },
+                examples: {
+                    type: 'string',
+                    description: 'When to apply this knowledge',
+                },
+                exceptions: {
+                    type: 'string',
+                    description: 'When NOT to apply this',
+                },
+                tier: {
+                    type: 'string',
+                    description: 'Memory tier: hot (active) or cold (archived)',
+                    enum: ['hot', 'cold'],
+                },
             },
             required: ['content'],
         },
     },
     handler: async (args) => {
         try {
-            const { content, type = 'observation', tags = [], project } = args;
+            const { content, type = 'observation', tags = [], project, source, reasoning, context, examples, exceptions, tier = 'hot' } = args;
             if (!content) {
                 return errorResult('Content is required');
             }
@@ -98,6 +124,12 @@ export const squishRememberTool = {
                 type,
                 tags,
                 project,
+                source,
+                reasoning,
+                memoryContext: context,
+                examples,
+                exceptions,
+                tier,
             });
             return textResult(`Memory stored: ${memory.id}`);
         }
@@ -128,7 +160,7 @@ export const squishRecallTool = {
             if (!memoryId) {
                 return errorResult('Memory ID is required');
             }
-            const memory = await getMemoryById(memoryId);
+            const memory = await getMemory(memoryId);
             if (!memory) {
                 return errorResult('Memory not found');
             }

package/dist/core/memory/categorizer.js

@@ -80,6 +80,7 @@ export async function categorizeMemory(content, existingTags = []) {
         decision: 0,
         context: 0,
         preference: 0,
+        note: 0,
     };
     for (const { type, patterns, weight } of MEMORY_TYPE_PATTERNS) {
         for (const pattern of patterns) {

package/dist/core/memory/conflict-detector.js

@@ -1,7 +1,7 @@
 import { eq, and, sql } from 'drizzle-orm';
 import { getDb } from '../../db/index.js';
 import { getSchema } from '../../db/schema.js';
-import { createDatabaseClient } from '../../core/database.js';
+import { createDatabaseClient } from '../storage/database.js';
 export async function detectConflicts(memoryId, proposedContent) {
     const db = createDatabaseClient(await getDb());
     const schema = await getSchema();

package/dist/core/memory/consolidation.d.ts

@@ -1,15 +1,6 @@
 /**
  * Memory Consolidation System
- *
- * Implements experience replay and memory consolidation for Squish.
- * Based on research from ReMe (Memory Replay) and LIGHT framework.
- *
- * Consolidation process:
- * 1. Find clusters of old, low-importance memories
- * 2. Group related memories by similarity
- * 3. Summarize each cluster using extractive summarization
- * 4. Create consolidated memory with summary
- * 5. Mark originals as consolidated (not deleted - reversible)
+ * Implements experience replay and memory consolidation
  */
 export interface ConsolidationOptions {
     projectId: string;

package/dist/core/memory/consolidation.js

@@ -1,18 +1,9 @@
 /**
  * Memory Consolidation System
- *
- * Implements experience replay and memory consolidation for Squish.
- * Based on research from ReMe (Memory Replay) and LIGHT framework.
- *
- * Consolidation process:
- * 1. Find clusters of old, low-importance memories
- * 2. Group related memories by similarity
- * 3. Summarize each cluster using extractive summarization
- * 4. Create consolidated memory with summary
- * 5. Mark originals as consolidated (not deleted - reversible)
+ * Implements experience replay and memory consolidation
  */
 import { eq, inArray } from 'drizzle-orm';
-import { createDatabaseClient } from '../database.js';
+import { createDatabaseClient } from '../storage/database.js';
 import { getDb } from '../../db/index.js';
 import { getSchema } from '../../db/schema.js';
 import { cosineSimilarity } from './importance.js';

package/dist/core/memory/context-collector.js

@@ -1,7 +1,7 @@
 /** Context Collector - Collect recent conversation context for query rewriting */
 import { logger } from '../logger.js';
 import { getDb } from '../../db/index.js';
-import { messages, conversations } from '../../drizzle/schema-sqlite.js';
+import { messages, conversations } from '../../db/drizzle/schema-sqlite.js';
 import { eq, desc } from 'drizzle-orm';
 export async function collectRecentContext(sessionId, count = 5) {
     const db = await getDb();

package/dist/core/memory/edit-workflow.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'crypto';
 import { eq, and, sql } from 'drizzle-orm';
 import { getDb } from '../../db/index.js';
 import { getSchema } from '../../db/schema.js';
-import { createDatabaseClient } from '../../core/database.js';
+import { createDatabaseClient } from '../storage/database.js';
 export async function createEditProposal(memoryId, currentContent, proposedContent, reason, userId) {
     const db = createDatabaseClient(await getDb());
     const schema = await getSchema();

package/dist/core/memory/entity-resolver.js

@@ -3,13 +3,13 @@
  * NO FALLBACKS - real extraction or throw
  */
 export async function extractQueryEntities(query, callClaudeFn) {
-    const prompt = `Extract entities from this question. Return ONLY JSON:
-{
-  "primary": ["Alice", "project name"],
-  "secondary": ["team", "budget"],
-  "queryType": "factual"
-}
-
+    const prompt = `Extract entities from this question. Return ONLY JSON:
+{
+  "primary": ["Alice", "project name"],
+  "secondary": ["team", "budget"],
+  "queryType": "factual"
+}
+
 Question: ${query}`;
     const response = await callClaudeFn(prompt, 500);
     const jsonMatch = response.match(/\{[\s\S]*\}/);

package/dist/core/memory/fact-extractor.js

@@ -13,18 +13,18 @@ export async function extractFacts(text, callClaude) {
             entities: []
         };
     }
-    const prompt = `Extract atomic facts from this conversation. 
-
-Requirements:
-- Extract specific, verifiable facts (names, dates, numbers, relationships)
-- Each fact should be a standalone statement
-- Identify entities (people, organizations, projects, locations)
-- Note temporal information and relationships
-
-Return ONLY valid JSON in this exact format:
-{"facts":[{"content":"fact statement","confidence":0.95,"entities":["Name"],"relation":"optional"}],"summary":"brief summary","entities":["all","entities"]}
-
-Text to analyze:
+    const prompt = `Extract atomic facts from this conversation. 
+
+Requirements:
+- Extract specific, verifiable facts (names, dates, numbers, relationships)
+- Each fact should be a standalone statement
+- Identify entities (people, organizations, projects, locations)
+- Note temporal information and relationships
+
+Return ONLY valid JSON in this exact format:
+{"facts":[{"content":"fact statement","confidence":0.95,"entities":["Name"],"relation":"optional"}],"summary":"brief summary","entities":["all","entities"]}
+
+Text to analyze:
 ${text.substring(0, 4000)}`;
     const response = await callClaude(prompt, 2000);
     // Extract JSON - look for the first { and last }

package/dist/core/memory/feedback-tracker.js

@@ -2,7 +2,7 @@
 import { logger } from '../logger.js';
 import { config } from '../../config.js';
 import { getDb } from '../../db/index.js';
-import { memoryFeedback, memories } from '../../drizzle/schema-sqlite.js';
+import { memoryFeedback, memories } from '../../db/drizzle/schema-sqlite.js';
 import { eq, and } from 'drizzle-orm';
 import { analyzeResponseForMemoryReferences, mightContainMemoryReferences } from './response-analyzer.js';
 const injectionTracker = new Map();