squish-memory 1.2.0 → 1.2.1

package/dist/core/memory/hooks.js

@@ -1,174 +0,0 @@
-/**
- * Memory Lifecycle Hooks
- *
- * Provides event hooks for memory operations:
-  * - memoryCreated: When a memory is stored (DB or markdown files)
- * - memoryUpdated: When a memory is updated
- * - memoryDeleted: When a memory is deleted
- * - tierChange: When memory tier changes (hot/warm/cold)
- * - decayApplied: When decay score is updated
- *
- * Each hook can have sync and async handlers.
- * Usage: Register handlers to auto-capture, sync to external systems, etc.
- */
-import { logger } from '../logger.js';
-// Global hook registry
-const hooks = [];
-/**
- * Register a hook handler for a specific event
- */
-export function registerHook(event, handler, priority = 100) {
-    hooks.push({ event, handler, priority });
-    hooks.sort((a, b) => b.priority - a.priority);
-    logger.info('[Hooks] Registered handler for: ' + event + ' (priority: ' + priority + ')');
-}
-/**
- * Unregister a hook handler
- */
-export function unregisterHook(event, handler) {
-    const idx = hooks.findIndex(h => h.event === event && h.handler === handler);
-    if (idx !== -1) {
-        hooks.splice(idx, 1);
-        logger.info('[Hooks] Unregistered handler for: ' + event);
-    }
-}
-/**
- * Clear all hooks for an event
- */
-export function clearHooks(event) {
-    if (event) {
-        const before = hooks.length;
-        const filtered = hooks.filter(h => h.event !== event);
-        hooks.length = 0;
-        hooks.push(...filtered);
-        logger.info('[Hooks] Cleared ' + (before - filtered.length) + ' hooks for: ' + event);
-    }
-    else {
-        const count = hooks.length;
-        hooks.length = 0;
-        logger.info('[Hooks] Cleared all ' + count + ' hooks');
-    }
-}
-/**
- * Get registered hooks for an event
- */
-export function getHooks(event) {
-    return hooks.filter(h => h.event === event).map(h => h.handler);
-}
-/**
- * List all registered hooks (for debugging)
- */
-export function listHooks() {
-    return hooks.map(h => ({ event: h.event, priority: h.priority }));
-}
-// --- Trigger functions ---
-/**
- * Trigger memoryCreated hooks
- * Called when a memory is stored in DB or markdown files
- */
-export async function triggerMemoryCreated(context) {
-    const handlers = getHooks('memoryCreated');
-    for (const handler of handlers) {
-        try {
-            const result = handler(context);
-            if (result instanceof Promise) {
-                await result;
-            }
-        }
-        catch (error) {
-            logger.error('[Hooks] Error in memoryCreated handler: ' + error);
-        }
-    }
-}
-/**
- * Trigger memoryUpdated hooks
- * Called when a memory content/tags/etc changes
- */
-export async function triggerMemoryUpdated(context, oldContent) {
-    const handlers = getHooks('memoryUpdated');
-    for (const handler of handlers) {
-        try {
-            const result = handler({ ...context, oldContent: oldContent || '' });
-            if (result instanceof Promise) {
-                await result;
-            }
-        }
-        catch (error) {
-            logger.error('[Hooks] Error in memoryUpdated handler: ' + error);
-        }
-    }
-}
-/**
- * Trigger memoryDeleted hooks
- * Called when a memory is deleted
- */
-export async function triggerMemoryDeleted(context) {
-    const handlers = getHooks('memoryDeleted');
-    for (const handler of handlers) {
-        try {
-            const result = handler(context);
-            if (result instanceof Promise) {
-                await result;
-            }
-        }
-        catch (error) {
-            logger.error('[Hooks] Error in memoryDeleted handler: ' + error);
-        }
-    }
-}
-/**
- * Trigger tierChange hooks
- * Called when memory tier changes
- */
-export async function triggerTierChange(context) {
-    const handlers = getHooks('tierChange');
-    for (const handler of handlers) {
-        try {
-            const result = handler(context);
-            if (result instanceof Promise) {
-                await result;
-            }
-        }
-        catch (error) {
-            logger.error('[Hooks] Error in tierChange handler: ' + error);
-        }
-    }
-}
-/**
- * Trigger decayApplied hooks
- * Called when memory decay score changes
- */
-export async function triggerDecayApplied(context) {
-    const handlers = getHooks('decayApplied');
-    for (const handler of handlers) {
-        try {
-            const result = handler(context);
-            if (result instanceof Promise) {
-                await result;
-            }
-        }
-        catch (error) {
-            logger.error('[Hooks] Error in decayApplied handler: ' + error);
-        }
-    }
-}
-/**
- * Built-in hook: Auto-save to memory files when storing to DB
- * Use this to have dual storage (DB + markdown files)
- */
-export function createMarkdownAutoSyncHook() {
-    return async function markdownAutoSync(context) {
-        if (context.tier === 'hot') {
-            const { saveToMarkdown } = await import('./markdown/markdown-storage.js');
-            await saveToMarkdown({
-                content: context.content,
-                type: context.type,
-                tags: context.tags,
-                project: context.project,
-                source: context.source,
-            });
-            logger.info('[Hooks] Auto-synced memory to markdown: ' + context.memoryId);
-        }
-    };
-}
-//# sourceMappingURL=hooks.js.map

package/dist/core/memory/hybrid-retrieval.d.ts

@@ -1,27 +0,0 @@
-import type { MemoryRecord } from '../lib/types.js';
-import type { SearchInput } from './memories.js';
-export interface HybridSearchOptions extends SearchInput {
-    candidateLimit?: number;
-    resultLimit?: number;
-}
-export interface HybridSearchResult extends MemoryRecord {
-    hybridScore: number;
-    semanticScore: number;
-    recencyScore: number;
-    importanceScore: number;
-    coactivationScore: number;
-    rank: number;
-    explanation: string;
-}
-type ScoredItem = {
-    memoryId: string;
-    memory: Record<string, unknown>;
-    totalScore: number;
-    components: Record<string, number>;
-    rank: number;
-    explanation: string;
-};
-export declare function applyEntityBoostAndRerank<T extends ScoredItem>(scored: T[]): T[];
-export declare function hybridSearch(options: HybridSearchOptions): Promise<HybridSearchResult[]>;
-export {};
-//# sourceMappingURL=hybrid-retrieval.d.ts.map

package/dist/core/memory/hybrid-retrieval.js

@@ -1,37 +0,0 @@
-import { hybridSearch as currentHybridSearch } from './hybrid-search.js';
-export function applyEntityBoostAndRerank(scored) {
-    return scored
-        .map((item) => {
-        const rawBoost = item.memory._entityBoost;
-        const entityBoost = typeof rawBoost === 'number' ? rawBoost : 0;
-        return {
-            ...item,
-            totalScore: item.totalScore + entityBoost * 20,
-        };
-    })
-        .sort((a, b) => b.totalScore - a.totalScore)
-        .map((item, index) => ({
-        ...item,
-        rank: index + 1,
-    }));
-}
-export async function hybridSearch(options) {
-    const limit = options.resultLimit ?? options.limit ?? 5;
-    const results = await currentHybridSearch(options, {
-        limit,
-        project: options.project,
-        type: options.type,
-        tags: options.tags,
-    });
-    return results.map((result, index) => ({
-        ...result,
-        hybridScore: result.similarity ?? 0,
-        semanticScore: result.similarity ?? 0,
-        recencyScore: 0,
-        importanceScore: typeof result.importance === 'number' ? result.importance : 0,
-        coactivationScore: 0,
-        rank: index + 1,
-        explanation: 'Compatibility result from current hybrid search',
-    }));
-}
-//# sourceMappingURL=hybrid-retrieval.js.map

package/dist/core/memory/hybrid-scorer.d.ts

@@ -1,40 +0,0 @@
-/** Hybrid Scorer - Multi-factor relevance scoring for memory ranking */
-export interface ScoredMemory {
-    memoryId: string;
-    memory: any;
-    totalScore: number;
-    components: {
-        semantic: number;
-        recency: number;
-        coactivation: number;
-        importance: number;
-        confidence: number;
-        feedback: number;
-    };
-    rank: number;
-    explanation: string;
-}
-export interface HybridScorerOptions {
-    weights?: {
-        semantic?: number;
-        recency?: number;
-        coactivation?: number;
-        importance?: number;
-        confidence?: number;
-        feedback?: number;
-    };
-    decayDays?: number;
-    minSemanticScore?: number;
-    includeExplanation?: boolean;
-}
-export declare function hybridScore(queryEmbedding: number[] | null, memories: any[], options?: HybridScorerOptions): Promise<ScoredMemory[]>;
-export declare function scoreAndRankMemories(queryEmbedding: number[] | null, memories: any[], topK?: number, options?: HybridScorerOptions): Promise<ScoredMemory[]>;
-export declare function getScoreDistribution(scored: ScoredMemory[]): {
-    min: number;
-    max: number;
-    avg: number;
-    median: number;
-    p95: number;
-    p99: number;
-};
-//# sourceMappingURL=hybrid-scorer.d.ts.map

package/dist/core/memory/hybrid-scorer.js

@@ -1,267 +0,0 @@
-/** Hybrid Scorer - Multi-factor relevance scoring for memory ranking */
-import { logger } from '../../core/logger.js';
-import { cosineSimilarity } from '../utils/vector-operations.js';
-export async function hybridScore(queryEmbedding, memories, options = {}) {
-    const weights = {
-        semantic: options.weights?.semantic ?? 0.30,
-        recency: options.weights?.recency ?? 0.20,
-        coactivation: options.weights?.coactivation ?? 0.10,
-        importance: options.weights?.importance ?? 0.15,
-        confidence: options.weights?.confidence ?? 0.15,
-        feedback: options.weights?.feedback ?? 0.10,
-    };
-    const decayDays = options.decayDays ?? 30;
-    const minSemanticScore = options.minSemanticScore ?? 0.0;
-    const scored = [];
-    const now = new Date();
-    for (const memory of memories) {
-        if (queryEmbedding && weights.semantic > 0) {
-            const semanticScore = calculateSemanticScore(queryEmbedding, memory);
-            if (semanticScore < minSemanticScore)
-                continue;
-        }
-        const components = {
-            semantic: queryEmbedding ? calculateSemanticScore(queryEmbedding, memory) : 50,
-            recency: calculateRecencyScore(memory, now, decayDays),
-            coactivation: calculateCoactivationScore(memory),
-            importance: calculateImportanceScore(memory),
-            confidence: calculateConfidenceScore(memory),
-            feedback: calculateFeedbackScore(memory),
-        };
-        const totalScore = Math.min(100, components.semantic * weights.semantic +
-            components.recency * weights.recency +
-            components.coactivation * weights.coactivation +
-            components.importance * weights.importance +
-            components.confidence * weights.confidence +
-            components.feedback * weights.feedback);
-        scored.push({
-            memoryId: memory.id,
-            memory,
-            totalScore: Math.round(totalScore * 100) / 100,
-            components: {
-                semantic: Math.round(components.semantic * 100) / 100,
-                recency: Math.round(components.recency * 100) / 100,
-                coactivation: Math.round(components.coactivation * 100) / 100,
-                importance: Math.round(components.importance * 100) / 100,
-                confidence: Math.round(components.confidence * 100) / 100,
-                feedback: Math.round(components.feedback * 100) / 100,
-            },
-            rank: 0,
-            explanation: options.includeExplanation
-                ? generateScoreExplanation(components, weights, memory)
-                : '',
-        });
-    }
-    scored.sort((a, b) => b.totalScore - a.totalScore);
-    for (let i = 0; i < scored.length; i++) {
-        scored[i].rank = i + 1;
-    }
-    return scored;
-}
-function calculateSemanticScore(queryEmbedding, memory) {
-    if (!memory.embedding || queryEmbedding.length === 0)
-        return 50;
-    try {
-        let memoryEmbedding = null;
-        if (Array.isArray(memory.embedding)) {
-            memoryEmbedding = memory.embedding;
-        }
-        else if (typeof memory.embedding === 'string') {
-            memoryEmbedding = JSON.parse(memory.embedding);
-        }
-        if (!memoryEmbedding || memoryEmbedding.length === 0)
-            return 50;
-        const semanticScore = cosineSimilarity(queryEmbedding, memoryEmbedding);
-        return Math.max(0, Math.min(100, (semanticScore + 1) * 50));
-    }
-    catch (error) {
-        logger.error('Error calculating semantic score', error);
-        return 50;
-    }
-}
-function calculateRecencyScore(memory, now, decayDays) {
-    // Enhanced bi-temporal recency scoring: considers validity period and learning time
-    const validFromDate = memory.validFrom ? new Date(memory.validFrom) : null;
-    const validToDate = memory.validTo ? new Date(memory.validTo) : null;
-    const recordedAtDate = memory.recordedAt ? new Date(memory.recordedAt) : null;
-    const createdDate = memory.createdAt ? new Date(memory.createdAt) : null;
-    // Calculate score based on how relevant the memory is right now
-    let score = 50; // Default neutral score
-    // If we have a validity period, score based on current time's position within that period
-    if (validFromDate && validToDate) {
-        const timeInPeriod = now.getTime() - validFromDate.getTime();
-        const periodLength = validToDate.getTime() - validFromDate.getTime();
-        if (periodLength > 0) {
-            // If now is within the validity period, high score
-            if (now >= validFromDate && now <= validToDate) {
-                // Full score if right in middle, decreasing toward edges
-                const progress = timeInPeriod / periodLength;
-                const distanceFromCenter = Math.abs(0.5 - progress) * 2; // 0 at center, 1 at edges
-                score = 100 * (1 - distanceFromCenter * 0.8); // 100 at center, 40 at edges
-            }
-            else {
-                // Outside validity period - score based on how recently it expired or how far in future
-                if (now < validFromDate) {
-                    // Future validity - score based on how soon it becomes valid
-                    const daysUntilValid = (validFromDate.getTime() - now.getTime()) / (24 * 60 * 60 * 1000);
-                    score = Math.max(20, 100 - Math.min(80, daysUntilValid / decayDays * 100));
-                }
-                else {
-                    // Past validity - score based on how recently it expired
-                    const daysSinceExpired = (now.getTime() - validToDate.getTime()) / (24 * 60 * 60 * 1000);
-                    score = Math.max(10, 60 - Math.min(50, daysSinceExpired / decayDays * 100));
-                }
-            }
-        }
-    }
-    // If we only have validFrom (open-ended validity)
-    else if (validFromDate) {
-        const daysSinceValid = (now.getTime() - validFromDate.getTime()) / (24 * 60 * 60 * 1000);
-        if (now >= validFromDate) {
-            // Still valid - decay from full score over time
-            score = Math.max(30, 100 - Math.min(70, daysSinceValid / decayDays * 100));
-        }
-        else {
-            // Becomes valid in future
-            const daysUntilValid = (validFromDate.getTime() - now.getTime()) / (24 * 60 * 60 * 1000);
-            score = Math.max(20, 100 - Math.min(80, daysUntilValid / decayDays * 100));
-        }
-    }
-    // Fallback to learned/recorded time
-    else {
-        const learnedDate = recordedAtDate || createdDate;
-        if (learnedDate) {
-            const daysSinceLearned = (now.getTime() - learnedDate.getTime()) / (24 * 60 * 60 * 1000);
-            score = 100 * Math.pow(0.5, daysSinceLearned / decayDays);
-            score = Math.max(0, Math.min(100, score));
-        }
-    }
-    return Math.round(score * 10) / 10; // Return one decimal place
-}
-function calculateCoactivationScore(memory) {
-    if (!memory.coactivationScore || memory.coactivationScore === 0)
-        return 10;
-    return Math.min(100, memory.coactivationScore * 5);
-}
-function calculateImportanceScore(memory) {
-    let score = 50;
-    // Simplified: hot or cold only (warm removed)
-    if (memory.tier === 'hot')
-        score += 30;
-    // No bonus for cold - it's the fallback
-    if (memory.relevanceScore)
-        score += memory.relevanceScore * 0.2;
-    if (memory.isPinned)
-        score += 10;
-    if (memory.isProtected)
-        score += 10;
-    if (memory.isMergeable || memory.isMerged)
-        score -= 10;
-    return Math.max(0, Math.min(100, score));
-}
-function calculateConfidenceScore(memory) {
-    let score = 50;
-    const signals = memory.metadata?.memorySignals;
-    if (signals) {
-        if (signals.priority === 'high')
-            score += 25;
-        if (signals.explicitTriggers && signals.explicitTriggers.length > 0) {
-            score += 15 * Math.min(signals.explicitTriggers.length, 2);
-        }
-        if (signals.implicit) {
-            if (signals.implicit.decision)
-                score += 10;
-            if (signals.implicit.correction)
-                score += 15;
-            if (signals.implicit.preference)
-                score += 8;
-            if (signals.implicit.workflowRule)
-                score += 12;
-            if (signals.implicit.lesson)
-                score += 10;
-        }
-        if (signals.requiresConflictCheck)
-            score -= 5;
-    }
-    switch (memory.type) {
-        case 'decision':
-            score += 10;
-            break;
-        case 'preference':
-            score += 5;
-            break;
-        case 'fact':
-            score += 8;
-            break;
-        case 'context':
-            score += 3;
-            break;
-    }
-    if (memory.source === 'mcp')
-        score += 5;
-    if (memory.accessCount && memory.accessCount > 5) {
-        score += Math.min(10, memory.accessCount / 2);
-    }
-    return Math.max(0, Math.min(100, score));
-}
-function calculateFeedbackScore(memory) {
-    const retrievalPriority = memory.retrievalPriority ?? 50;
-    return Math.max(0, Math.min(100, retrievalPriority));
-}
-function generateScoreExplanation(components, weights, memory) {
-    const parts = [];
-    if (components.semantic > 70)
-        parts.push(`highly relevant (${components.semantic.toFixed(0)})`);
-    else if (components.semantic > 50)
-        parts.push(`somewhat relevant (${components.semantic.toFixed(0)})`);
-    else
-        parts.push(`low relevance (${components.semantic.toFixed(0)})`);
-    if (components.recency > 70)
-        parts.push('recent');
-    else if (components.recency > 30)
-        parts.push('moderately recent');
-    else
-        parts.push('older');
-    // Simplified: hot or cold only (warm removed)
-    if (memory.tier === 'hot')
-        parts.push('active memory');
-    else
-        parts.push('archived memory');
-    if (components.coactivation > 60)
-        parts.push('frequently associated');
-    if (components.confidence > 80)
-        parts.push('high confidence');
-    else if (components.confidence > 60)
-        parts.push('moderate confidence');
-    else if (components.confidence < 40)
-        parts.push('low confidence');
-    if (components.feedback > 70)
-        parts.push('frequently useful');
-    else if (components.feedback < 30)
-        parts.push('rarely used');
-    return parts.join(', ');
-}
-export async function scoreAndRankMemories(queryEmbedding, memories, topK = 10, options = {}) {
-    const scored = await hybridScore(queryEmbedding, memories, options);
-    logger.debug('Scored and ranked memories', {
-        total: scored.length,
-        topK,
-        topScores: scored.slice(0, topK).map((s) => ({ id: s.memoryId, score: s.totalScore })),
-    });
-    return scored.slice(0, topK);
-}
-export function getScoreDistribution(scored) {
-    if (scored.length === 0) {
-        return { min: 0, max: 0, avg: 0, median: 0, p95: 0, p99: 0 };
-    }
-    const scores = scored.map((s) => s.totalScore).sort((a, b) => a - b);
-    return {
-        min: scores[0],
-        max: scores[scores.length - 1],
-        avg: scores.reduce((a, b) => a + b, 0) / scores.length,
-        median: scores[Math.floor(scores.length / 2)],
-        p95: scores[Math.floor((95 / 100) * scores.length)],
-        p99: scores[Math.floor((99 / 100) * scores.length)],
-    };
-}
-//# sourceMappingURL=hybrid-scorer.js.map

package/dist/core/memory/hybrid-search.d.ts

@@ -1,23 +0,0 @@
-/**
- * Vector Search - Pure semantic search with optional graph boosting + multi-session support
- *
- * Uses cosine similarity on embeddings + optional graph boost
- * BM25 removed - use qmd-client for hot tier (BM25 + vectors + reranking)
- */
-import type { SearchResult, SearchInput } from './memories.js';
-export interface HybridSearchOptions {
-    limit?: number;
-    project?: string;
-    type?: string;
-    tags?: string[];
-    enableMultiSession?: boolean;
-    enableGraphTraversal?: boolean;
-    enableHeuristics?: boolean;
-    includeAssociations?: boolean;
-}
-/**
- * Main search function - vectors + graph boost + heuristics + places + sessions
- * Unified search integrating Places, Graph, and Memory
- */
-export declare function hybridSearch(input: SearchInput, options?: HybridSearchOptions): Promise<SearchResult[]>;
-//# sourceMappingURL=hybrid-search.d.ts.map