squish-memory 1.1.5 → 1.2.1

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

@@ -1,63 +0,0 @@
-/**
- * Importance Scoring System
- * Calculates and manages memory importance scores (0-100) with temporal decay
- */
-import type { Memory } from '../../db/drizzle/schema.js';
-import { cosineSimilarity as vectorCosineSimilarity } from '../utils/vector-operations.js';
-export interface ImportanceScore {
-    score: number;
-    components: {
-        base: number;
-        recency: number;
-        accessFrequency: number;
-        typeWeight: number;
-        userFlags: number;
-    };
-    explanation: string;
-}
-/**
- * Calculate importance score for a memory
- *
- * Formula: base + recency + accessFrequency + typeWeight + userFlags
- * All values are clamped to 0-100 range
- */
-export declare function calculateImportance(memory: Partial<Memory>): ImportanceScore;
-/**
- * Update importance score for a memory
- * Used when memory is accessed or modified
- */
-export declare function updateImportanceScore(memoryId: string, incrementAccess?: boolean): Promise<number>;
-/**
- * Decay importance scores for old memories
- * Should be run periodically (e.g., daily) to reduce scores of stale memories
- *
- * This function applies exponential decay to all memories that haven't been
- * recalculated recently, keeping the system's importance scores current.
- *
- * Fixed: Uses batch update instead of N+1 individual queries
- */
-export declare function decayImportanceScores(projectId?: string): Promise<number>;
-/**
- * Get low-importance memories that are candidates for consolidation
- * These are old, rarely accessed memories with low importance scores
- */
-export declare function getLowImportanceMemories(projectId: string, options?: {
-    minAge?: number;
-    maxImportance?: number;
-    limit?: number;
-}): Promise<any[]>;
-/**
- * Set importance score manually (for user override)
- */
-export declare function setImportanceScore(memoryId: string, score: number): Promise<void>;
-/**
- * Pin a memory to prevent decay and consolidation
- */
-export declare function pinMemory(memoryId: string, pinned?: boolean): Promise<void>;
-/**
- * Calculate cosine similarity between two vectors
- * Re-exported from core/utils/vector-operations.ts for backward compatibility.
- * This will be removed in v1.2.0 - import directly from core/utils/vector-operations.ts
- */
-export declare const cosineSimilarity: typeof vectorCosineSimilarity;
-//# sourceMappingURL=importance.d.ts.map

package/dist/core/memory/importance.js

@@ -1,298 +0,0 @@
-/**
- * Importance Scoring System
- * Calculates and manages memory importance scores (0-100) with temporal decay
- */
-import { eq } from 'drizzle-orm';
-import { cosineSimilarity as vectorCosineSimilarity } from '../utils/vector-operations.js';
-import { getDbClient } from '../lib/db-client.js';
-/**
- * Type weights for importance scoring
- * Higher values = more important memory types
- */
-const TYPE_WEIGHTS = {
-    decision: 15,
-    fact: 10,
-    preference: 8,
-    context: 5,
-    observation: 0,
-};
-/**
- * Calculate importance score for a memory
- *
- * Formula: base + recency + accessFrequency + typeWeight + userFlags
- * All values are clamped to 0-100 range
- */
-export function calculateImportance(memory) {
-    const components = {
-        base: 50, // Neutral starting point
-        recency: calculateRecencyComponent(memory),
-        accessFrequency: calculateAccessFrequencyComponent(memory),
-        typeWeight: calculateTypeWeightComponent(memory),
-        userFlags: calculateUserFlagsComponent(memory),
-    };
-    // Calculate total score (clamped to 0-100)
-    const score = Math.min(100, Math.max(0, components.base +
-        components.recency +
-        components.accessFrequency +
-        components.typeWeight +
-        components.userFlags));
-    return {
-        score,
-        components,
-        explanation: generateImportanceExplanation(components, memory),
-    };
-}
-/**
- * Calculate recency component (0-30 points)
- * Uses exponential decay based on memory age
- */
-function calculateRecencyComponent(memory) {
-    if (!memory.createdAt)
-        return 0;
-    const now = Date.now();
-    const createdAt = new Date(memory.createdAt).getTime();
-    const ageDays = (now - createdAt) / (1000 * 60 * 60 * 24);
-    // Decay rate: default 30 days half-life
-    const decayRate = memory.importanceDecayRate ?? 30;
-    // Exponential decay: 30 * (0.5 ^ (age / halfLife))
-    // Maximum 30 points for very recent memories
-    const recencyScore = 30 * Math.pow(0.5, ageDays / decayRate);
-    return Math.max(0, Math.min(30, recencyScore));
-}
-/**
- * Calculate access frequency component (0-15 points)
- * More frequently accessed memories are more important
- */
-function calculateAccessFrequencyComponent(memory) {
-    const accessCount = memory.accessCount ?? 0;
-    const usageCount = memory.usageCount ?? 0;
-    // Combined access count (from both fields)
-    const totalAccess = accessCount + usageCount;
-    // Logarithmic scaling: 15 * log10(totalAccess + 1)
-    // This gives diminishing returns for high access counts
-    const accessScore = 15 * Math.log10(totalAccess + 1);
-    return Math.min(15, accessScore);
-}
-/**
- * Calculate type weight component (0-15 points)
- * Different memory types have different inherent importance
- */
-function calculateTypeWeightComponent(memory) {
-    const type = memory.type ?? 'observation';
-    return TYPE_WEIGHTS[type] ?? 0;
-}
-/**
- * Calculate user flags component (0 or +20 points)
- * Pinned or protected memories get maximum importance
- */
-function calculateUserFlagsComponent(memory) {
-    // Pinned memories get maximum boost
-    if (memory.isPinned)
-        return 20;
-    // Protected memories also get significant boost
-    if (memory.isProtected)
-        return 15;
-    // Immutable memories are important but not as much
-    if (memory.isImmutable)
-        return 10;
-    return 0;
-}
-/**
- * Generate human-readable explanation for importance score
- */
-function generateImportanceExplanation(components, memory) {
-    const parts = [];
-    // Base score
-    parts.push(`base: ${components.base}`);
-    // Recency
-    if (components.recency > 20) {
-        parts.push('very recent');
-    }
-    else if (components.recency > 10) {
-        parts.push('recent');
-    }
-    else if (components.recency > 0) {
-        parts.push('somewhat recent');
-    }
-    // Access frequency
-    const totalAccess = (memory.accessCount ?? 0) + (memory.usageCount ?? 0);
-    if (totalAccess > 10) {
-        parts.push('frequently accessed');
-    }
-    else if (totalAccess > 3) {
-        parts.push('occasionally accessed');
-    }
-    // Type
-    const type = memory.type ?? 'observation';
-    if (type !== 'observation') {
-        parts.push(`${type} type`);
-    }
-    // User flags
-    if (memory.isPinned) {
-        parts.push('pinned by user');
-    }
-    else if (memory.isProtected) {
-        parts.push('protected');
-    }
-    return parts.join(', ');
-}
-/**
- * Update importance score for a memory
- * Used when memory is accessed or modified
- */
-export async function updateImportanceScore(memoryId, incrementAccess = false) {
-    const { db, schema } = await getDbClient();
-    // Get current memory
-    const memories = await db
-        .select()
-        .from(schema.memories)
-        .where(eq(schema.memories.id, memoryId))
-        .limit(1);
-    if (memories.length === 0) {
-        throw new Error(`Memory not found: ${memoryId}`);
-    }
-    const memory = memories[0];
-    // Calculate new importance score
-    const importance = calculateImportance(memory);
-    // Update memory with new score
-    const updateData = {
-        importanceScore: importance.score,
-        lastImportanceRecalc: new Date(),
-    };
-    // Increment access count if requested
-    if (incrementAccess) {
-        updateData.accessCount = (memory.accessCount ?? 0) + 1;
-        updateData.lastAccessedAt = new Date();
-    }
-    await db
-        .update(schema.memories)
-        .set(updateData)
-        .where(eq(schema.memories.id, memoryId));
-    return importance.score;
-}
-/**
- * Decay importance scores for old memories
- * Should be run periodically (e.g., daily) to reduce scores of stale memories
- *
- * This function applies exponential decay to all memories that haven't been
- * recalculated recently, keeping the system's importance scores current.
- *
- * Fixed: Uses batch update instead of N+1 individual queries
- */
-export async function decayImportanceScores(projectId) {
-    const { db, schema, raw } = await getDbClient();
-    // Get memories that need recalculation
-    // (those not recalculated in the last 24 hours or never)
-    const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
-    // Use raw SQL for bulk update - avoids N+1 queries - let's use raw SQL for efficiency
-    // Build a single UPDATE that sets importance to base 50 (neutral) minus decay
-    // The JS calculation is too complex to port to SQL, but we can at least
-    // use a simpler approach: just reset to default and let individual recalc happen on access
-    // For now, use a more efficient approach: bulk update with raw SQL
-    // This avoids N+1 queries while still using the JS calculation logic
-    const clientType = raw.$clientType || 'sqlite';
-    const now = new Date().toISOString();
-    if (clientType === 'sqlite') {
-        const sqliteClient = raw.$client;
-        // Single SQL update - set all non-pinned/consolidated memories to base decay
-        // Note: We can't fully replicate the JS calculation in SQL, so we apply
-        // a simple decay multiplier. Full recalculation happens on access.
-        const result = sqliteClient.prepare(`
-      UPDATE memories
-      SET importance_score = MAX(0, importance_score - 1),
-          last_importance_recalc = ?
-      WHERE (is_pinned = 0 AND is_protected = 0 AND is_consolidated = 0)
-        AND (last_importance_recalc IS NULL OR last_importance_recalc < ?)
-        ${projectId ? 'AND project_id = ?' : ''}
-    `).run(now, oneDayAgo.toISOString(), ...(projectId ? [projectId] : []));
-        return result.changes;
-    }
-    else {
-        // PostgreSQL
-        const pgClient = raw.$client;
-        const result = await pgClient.query(`
-      UPDATE memories
-      SET importance_score = GREATEST(0, importance_score - 1),
-          last_importance_recalc = $1
-      WHERE (is_pinned = FALSE AND is_protected = FALSE AND is_consolidated = FALSE)
-        AND (last_importance_recalc IS NULL OR last_importance_recalc < $2)
-        ${projectId ? 'AND project_id = $3' : ''}
-    `, [now, oneDayAgo.toISOString(), ...(projectId ? [projectId] : [])]);
-        return result.rowCount || 0;
-    }
-}
-/**
- * Get low-importance memories that are candidates for consolidation
- * These are old, rarely accessed memories with low importance scores
- */
-export async function getLowImportanceMemories(projectId, options = {}) {
-    const { db, schema } = await getDbClient();
-    const { minAge = 90, // 90 days old by default
-    maxImportance = 30, // importance score below 30
-    limit = 100, } = options;
-    const minAgeTimestamp = new Date(Date.now() - minAge * 24 * 60 * 60 * 1000);
-    const memories = await db
-        .select()
-        .from(schema.memories)
-        .where(eq(schema.memories.projectId, projectId))
-        .all();
-    // Filter by criteria
-    return memories
-        .filter((m) => {
-        // Skip pinned/protected/consolidated
-        if (m.isPinned || m.isProtected || m.isConsolidated) {
-            return false;
-        }
-        // Check age
-        if (m.createdAt) {
-            const createdAt = new Date(m.createdAt).getTime();
-            if (createdAt > minAgeTimestamp.getTime()) {
-                return false;
-            }
-        }
-        // Check importance
-        if ((m.importanceScore ?? 50) > maxImportance) {
-            return false;
-        }
-        return true;
-    })
-        .slice(0, limit);
-}
-/**
- * Set importance score manually (for user override)
- */
-export async function setImportanceScore(memoryId, score) {
-    if (score < 0 || score > 100) {
-        throw new Error('Importance score must be between 0 and 100');
-    }
-    const { db, schema } = await getDbClient();
-    await db
-        .update(schema.memories)
-        .set({
-        importanceScore: Math.round(score),
-        lastImportanceRecalc: new Date(),
-    })
-        .where(eq(schema.memories.id, memoryId));
-}
-/**
- * Pin a memory to prevent decay and consolidation
- */
-export async function pinMemory(memoryId, pinned = true) {
-    const { db, schema } = await getDbClient();
-    await db
-        .update(schema.memories)
-        .set({
-        isPinned: pinned ? 1 : 0,
-        // When pinning, set max importance; when unpinning, recalculate
-        importanceScore: pinned ? 100 : undefined,
-        lastImportanceRecalc: new Date(),
-    })
-        .where(eq(schema.memories.id, memoryId));
-}
-/**
- * Calculate cosine similarity between two vectors
- * Re-exported from core/utils/vector-operations.ts for backward compatibility.
- * This will be removed in v1.2.0 - import directly from core/utils/vector-operations.ts
- */
-export const cosineSimilarity = vectorCosineSimilarity;
-//# sourceMappingURL=importance.js.map

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

@@ -1,8 +0,0 @@
-export * from './memories.js';
-export * from './memory-manager.js';
-export * from './serialization.js';
-export * from './temporal-parser.js';
-export * from './entity-extractor.js';
-export * from './hybrid-scorer.js';
-export * from './bridge-discovery.js';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,31 +0,0 @@
-/**
- * Memory Loading Abstraction
- * Unified utilities for loading memories by ID with configurable options
- */
-import { type MemoryRecord } from './normalization.js';
-export interface LoadMemoryOptions {
-    incrementAccess?: boolean;
-    decrypt?: boolean;
-    normalize?: boolean;
-    includeSensitive?: boolean;
-}
-/**
- * Load a single memory by ID with configurable options
- */
-export declare function loadMemory(id: string, options?: LoadMemoryOptions): Promise<MemoryRecord | any | null>;
-/**
- * Load multiple memories by IDs efficiently
- * Returns a Map keyed by memory ID
- */
-export declare function loadMemories(ids: string[], options?: LoadMemoryOptions): Promise<Map<string, any>>;
-/**
- * Load a memory by ID with raw database access, no processing.
- *
- * This is for special cases that need the raw database row without
- * normalization, decryption, or access count updates.
- *
- * @param id - Memory UUID
- * @returns Raw database row or null if not found
- */
-export declare function loadMemoryRaw(id: string): Promise<any | null>;
-//# sourceMappingURL=loader.d.ts.map

package/dist/core/memory/loader.js

@@ -1,141 +0,0 @@
-/**
- * Memory Loading Abstraction
- * Unified utilities for loading memories by ID with configurable options
- */
-import { eq, inArray } from 'drizzle-orm';
-import { getDbClient } from '../lib/db-client.js';
-import { decrypt } from '../security/encrypt.js';
-import { normalizeMemory } from './normalization.js';
-import { requireUuid } from '../lib/validation.js';
-/**
- * Load a single memory by ID with configurable options
- */
-export async function loadMemory(id, options = {}) {
-    const { incrementAccess = true, decrypt: shouldDecrypt = true, normalize = true, includeSensitive = false } = options;
-    // Validate UUID
-    requireUuid(id);
-    const { db, schema } = await getDbClient();
-    // Query the memory
-    const rows = await db.select().from(schema.memories).where(eq(schema.memories.id, id)).limit(1);
-    const row = rows[0];
-    if (!row)
-        return null;
-    // Increment access count if needed
-    if (incrementAccess) {
-        await db.update(schema.memories)
-            .set({
-            accessCount: (row.accessCount ?? 0) + 1,
-            lastAccessedAt: new Date(),
-        })
-            .where(eq(schema.memories.id, id));
-    }
-    // Determine content: decrypt if needed
-    let content = row.content;
-    let encryptedContent = row.encrypted_content;
-    let encryptionNonce = row.encryption_nonce;
-    if (shouldDecrypt && row.is_encrypted) {
-        try {
-            content = decrypt(encryptedContent, encryptionNonce);
-        }
-        catch (e) {
-            console.warn('Failed to decrypt memory', e);
-            content = row.content; // fallback to stored content (encrypted)
-        }
-    }
-    // Build result object
-    let result = { ...row, content };
-    // If not decrypting and includeSensitive, keep encrypted fields
-    if (!shouldDecrypt && includeSensitive) {
-        result.encrypted_content = encryptedContent;
-        result.encryption_nonce = encryptionNonce;
-    }
-    // If normalize, convert to MemoryRecord shape
-    if (normalize) {
-        return normalizeMemory(result);
-    }
-    // Otherwise return raw-ish row (with content possibly decrypted)
-    return result;
-}
-/**
- * Load multiple memories by IDs efficiently
- * Returns a Map keyed by memory ID
- */
-export async function loadMemories(ids, options = {}) {
-    const { incrementAccess = true, decrypt: shouldDecrypt = true, normalize = true, includeSensitive = false } = options;
-    if (ids.length === 0) {
-        return new Map();
-    }
-    // Validate all UUIDs
-    for (const id of ids) {
-        requireUuid(id);
-    }
-    const { db, schema } = await getDbClient();
-    // Batch query using IN operator
-    const rows = await db
-        .select()
-        .from(schema.memories)
-        .where(inArray(schema.memories.id, ids));
-    // Create a map from id to row
-    const rowMap = new Map();
-    for (const row of rows) {
-        rowMap.set(row.id, row);
-    }
-    // Increment access counts if needed
-    if (incrementAccess) {
-        const now = new Date();
-        for (const row of rows) {
-            await db.update(schema.memories)
-                .set({
-                accessCount: (row.accessCount ?? 0) + 1,
-                lastAccessedAt: now,
-            })
-                .where(eq(schema.memories.id, row.id));
-        }
-    }
-    // Process each row according to options
-    const resultMap = new Map();
-    for (const row of rows) {
-        let content = row.content;
-        let encryptedContent = row.encrypted_content;
-        let encryptionNonce = row.encryption_nonce;
-        if (shouldDecrypt && row.is_encrypted) {
-            try {
-                content = decrypt(encryptedContent, encryptionNonce);
-            }
-            catch (e) {
-                console.warn('Failed to decrypt memory', e);
-                content = row.content;
-            }
-        }
-        let result = { ...row, content };
-        if (!shouldDecrypt && includeSensitive) {
-            result.encrypted_content = encryptedContent;
-            result.encryption_nonce = encryptionNonce;
-        }
-        if (normalize) {
-            resultMap.set(row.id, normalizeMemory(result));
-        }
-        else {
-            resultMap.set(row.id, result);
-        }
-    }
-    return resultMap;
-}
-/**
- * Load a memory by ID with raw database access, no processing.
- *
- * This is for special cases that need the raw database row without
- * normalization, decryption, or access count updates.
- *
- * @param id - Memory UUID
- * @returns Raw database row or null if not found
- */
-export async function loadMemoryRaw(id) {
-    // Validate UUID
-    requireUuid(id);
-    const { db, schema } = await getDbClient();
-    // Direct query without any processing
-    const rows = await db.select().from(schema.memories).where(eq(schema.memories.id, id)).limit(1);
-    return rows[0] || null;
-}
-//# sourceMappingURL=loader.js.map

package/dist/core/memory/markdown/markdown-storage.d.ts

@@ -1,72 +0,0 @@
-/**
- * Memory Markdown Storage
- *
- * Stores memories as markdown files in .squish/memory/
- * Following Karpathy LLM Memory pattern:
- * - raw/ : Append-only memory files (never edit)
- * - processed/ : LLM-generated articles (future)
- * - outputs/ : Query responses (future)
- *
- * Each memory = one .md file with YAML frontmatter
- */
-import type { MemoryType } from '../memories.js';
-export interface MarkdownMemoryInput {
-    content: string;
-    type?: MemoryType;
-    tags?: string[];
-    reasoning?: string;
-    memoryContext?: string;
-    examples?: string;
-    exceptions?: string;
-    source?: string;
-    project?: string;
-}
-export interface MarkdownMemoryFile {
-    id: string;
-    type: MemoryType;
-    content: string;
-    tags: string[];
-    createdAt: string;
-    source?: string;
-    project?: string;
-    reasoning?: string;
-    memoryContext?: string;
-    examples?: string;
-    exceptions?: string;
-}
-/**
- * Save a memory to memory raw folder
- */
-export declare function saveToMarkdown(input: MarkdownMemoryInput): Promise<MarkdownMemoryFile>;
-/**
- * Get all memories from memory raw folder
- */
-export declare function getMarkdownMemories(options?: {
-    since?: Date;
-    until?: Date;
-    tags?: string[];
-    type?: MemoryType;
-    project?: string;
-}): Promise<MarkdownMemoryFile[]>;
-/**
- * Get a specific memory by ID
- */
-export declare function getMarkdownMemory(id: string): Promise<MarkdownMemoryFile | null>;
-/**
- * Delete a memory from memory
- */
-export declare function deleteMarkdownMemory(id: string): Promise<boolean>;
-/**
- * Get memory storage stats
- */
-export declare function getMemoryStats(): Promise<{
-    totalMemories: number;
-    byType: Record<string, number>;
-    byTag: Record<string, number>;
-    storageSizeBytes: number;
-}>;
-/**
- * Check if memory storage is available
- */
-export declare function isMemoryStorageAvailable(): boolean;
-//# sourceMappingURL=markdown-storage.d.ts.map