squish-memory 1.1.5 → 1.2.0

package/dist/core/session/entity-tracker.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Session Entity Tracker
+ *
+ * Tracks "active" entities in conversation sessions to enable
+ * reference resolution (e.g., resolving "she" to "Alice").
+ */
+export interface SessionEntity {
+    entityId: string;
+    entityName: string;
+    entityType: string;
+    mentionCount: number;
+    lastMentionedAt: Date;
+    salience: number;
+}
+export interface SessionEntityMap {
+    sessionId: string;
+    entities: Map<string, SessionEntity>;
+    updatedAt: Date;
+}
+/**
+ * Track an entity mention in a session.
+ * Updates salience based on recency and frequency.
+ */
+export declare function trackEntityInSession(sessionId: string, entityId: string, entityName: string, entityType: string): void;
+/**
+ * Get active entities for a session, sorted by salience.
+ * Applies time-based decay to salience scores.
+ */
+export declare function getActiveSessionEntities(sessionId: string, options?: {
+    limit?: number;
+    minSalience?: number;
+    entityTypes?: string[];
+}): SessionEntity[];
+/**
+ * Resolve a reference (pronoun, definite reference) to an entity in the session.
+ * Returns the most salient entity matching the reference type.
+ */
+export declare function resolveReference(sessionId: string, reference: string): SessionEntity | null;
+/**
+ * Clear session entities (e.g., when a session ends).
+ */
+export declare function clearSessionEntities(sessionId: string): void;
+/**
+ * Get all active sessions.
+ */
+export declare function getActiveSessions(): string[];
+/**
+ * Decay all session entities (call periodically).
+ * Reduces salience of all entities across all sessions.
+ */
+export declare function decayAllSessionEntities(): void;
+/**
+ * Persist session entities to the database for durability.
+ * Called periodically or on session end.
+ */
+export declare function persistSessionEntities(sessionId: string): Promise<void>;
+/**
+ * Load session entities from the database.
+ * Called when a session starts.
+ */
+export declare function loadSessionEntities(sessionId: string): Promise<void>;
+//# sourceMappingURL=entity-tracker.d.ts.map

package/dist/core/session/entity-tracker.js

@@ -0,0 +1,287 @@
+/**
+ * Session Entity Tracker
+ *
+ * Tracks "active" entities in conversation sessions to enable
+ * reference resolution (e.g., resolving "she" to "Alice").
+ */
+import { eq } from 'drizzle-orm';
+import { getDb } from '../../db/index.js';
+import { getSchema } from '../../db/schema.js';
+import { logger } from '../logger.js';
+// ─── In-Memory Session Cache ─────────────────────────────────────────────────
+const sessionCache = new Map();
+const MAX_SESSIONS = 100;
+const ENTITY_SALIENCE_DECAY = 0.85; // Per mention, older mentions decay
+const MAX_SESSION_ENTITIES = 50;
+/**
+ * Track an entity mention in a session.
+ * Updates salience based on recency and frequency.
+ */
+export function trackEntityInSession(sessionId, entityId, entityName, entityType) {
+    let session = sessionCache.get(sessionId);
+    if (!session) {
+        session = {
+            sessionId,
+            entities: new Map(),
+            updatedAt: new Date(),
+        };
+        sessionCache.set(sessionId, session);
+    }
+    // Evict old sessions if cache is full
+    if (sessionCache.size > MAX_SESSIONS) {
+        const oldestKey = [...sessionCache.entries()]
+            .sort(([, a], [, b]) => a.updatedAt.getTime() - b.updatedAt.getTime())[0][0];
+        sessionCache.delete(oldestKey);
+    }
+    const existing = session.entities.get(entityId);
+    const now = new Date();
+    if (existing) {
+        // Update existing entity: increase salience, update mention count
+        existing.mentionCount += 1;
+        existing.lastMentionedAt = now;
+        // Salience increases with each mention, but decays for older mentions
+        existing.salience = Math.min(1.0, existing.salience + 0.2);
+    }
+    else {
+        // New entity for this session
+        session.entities.set(entityId, {
+            entityId,
+            entityName,
+            entityType,
+            mentionCount: 1,
+            lastMentionedAt: now,
+            salience: 0.5, // Start at medium salience
+        });
+    }
+    // Evict least salient entities if session has too many
+    if (session.entities.size > MAX_SESSION_ENTITIES) {
+        const leastSalient = [...session.entities.entries()]
+            .sort(([, a], [, b]) => a.salience - b.salience)[0];
+        if (leastSalient) {
+            session.entities.delete(leastSalient[0]);
+        }
+    }
+    session.updatedAt = now;
+}
+/**
+ * Get active entities for a session, sorted by salience.
+ * Applies time-based decay to salience scores.
+ */
+export function getActiveSessionEntities(sessionId, options) {
+    const { limit = 10, minSalience = 0.1, entityTypes } = options || {};
+    const session = sessionCache.get(sessionId);
+    if (!session)
+        return [];
+    const now = Date.now();
+    const entities = [];
+    for (const [id, entity] of session.entities) {
+        // Apply time-based decay
+        const timeSinceMention = now - entity.lastMentionedAt.getTime();
+        const minutesSinceMention = timeSinceMention / (1000 * 60);
+        const timeDecay = Math.pow(ENTITY_SALIENCE_DECAY, minutesSinceMention / 5); // Decay every 5 minutes
+        const adjustedSalience = entity.salience * timeDecay;
+        // Filter by minimum salience
+        if (adjustedSalience < minSalience)
+            continue;
+        // Filter by entity type
+        if (entityTypes && entityTypes.length > 0 && !entityTypes.includes(entity.entityType))
+            continue;
+        entities.push({
+            ...entity,
+            salience: adjustedSalience,
+        });
+    }
+    // Sort by salience (most salient first)
+    entities.sort((a, b) => b.salience - a.salience);
+    return entities.slice(0, limit);
+}
+/**
+ * Resolve a reference (pronoun, definite reference) to an entity in the session.
+ * Returns the most salient entity matching the reference type.
+ */
+export function resolveReference(sessionId, reference) {
+    const session = sessionCache.get(sessionId);
+    if (!session)
+        return null;
+    const lowerRef = reference.toLowerCase();
+    // Pronoun mapping
+    const pronounMap = {
+        'he': ['person'],
+        'him': ['person'],
+        'his': ['person'],
+        'she': ['person'],
+        'her': ['person'],
+        'hers': ['person'],
+        'it': ['tool', 'concept', 'file', 'function', 'class'],
+        'they': ['person', 'concept', 'tool'],
+        'them': ['person', 'concept', 'tool'],
+        'their': ['person', 'concept', 'tool'],
+        'this': [], // Any type
+        'that': [], // Any type
+        'these': [],
+        'those': [],
+    };
+    // Definite reference patterns
+    const definitePatterns = [
+        { pattern: /\bthe (?:project|app|application)\b/i, types: ['concept'] },
+        { pattern: /\bthe (?:team|group)\b/i, types: ['concept'] },
+        { pattern: /\bthe (?:database|db)\b/i, types: ['tool'] },
+        { pattern: /\bthe (?:server|service|api)\b/i, types: ['tool'] },
+        { pattern: /\bthe (?:issue|bug|problem|outage)\b/i, types: ['concept'] },
+        { pattern: /\bthe (?:file|module|component)\b/i, types: ['file'] },
+    ];
+    // Check pronouns first
+    const allowedTypes = pronounMap[lowerRef];
+    if (allowedTypes !== undefined) {
+        const candidates = getActiveSessionEntities(sessionId, {
+            limit: 3,
+            minSalience: 0.2,
+            entityTypes: allowedTypes.length > 0 ? allowedTypes : undefined,
+        });
+        // For pronouns, return the most salient entity of the right type
+        return candidates.length > 0 ? candidates[0] : null;
+    }
+    // Check definite references
+    for (const { pattern, types } of definitePatterns) {
+        if (pattern.test(reference)) {
+            const candidates = getActiveSessionEntities(sessionId, {
+                limit: 3,
+                minSalience: 0.2,
+                entityTypes: types,
+            });
+            return candidates.length > 0 ? candidates[0] : null;
+        }
+    }
+    // Try to match by name (partial match)
+    const nameMatch = [...session.entities.values()]
+        .filter(e => e.entityName.toLowerCase().includes(lowerRef))
+        .sort((a, b) => b.salience - a.salience)[0];
+    return nameMatch || null;
+}
+/**
+ * Clear session entities (e.g., when a session ends).
+ */
+export function clearSessionEntities(sessionId) {
+    sessionCache.delete(sessionId);
+}
+/**
+ * Get all active sessions.
+ */
+export function getActiveSessions() {
+    return [...sessionCache.keys()];
+}
+/**
+ * Decay all session entities (call periodically).
+ * Reduces salience of all entities across all sessions.
+ */
+export function decayAllSessionEntities() {
+    const now = Date.now();
+    for (const [sessionId, session] of sessionCache) {
+        for (const [entityId, entity] of session.entities) {
+            const timeSinceMention = now - entity.lastMentionedAt.getTime();
+            const minutesSinceMention = timeSinceMention / (1000 * 60);
+            entity.salience *= Math.pow(ENTITY_SALIENCE_DECAY, minutesSinceMention / 5);
+        }
+        // Remove entities with very low salience
+        for (const [entityId, entity] of session.entities) {
+            if (entity.salience < 0.01) {
+                session.entities.delete(entityId);
+            }
+        }
+        // Remove empty sessions
+        if (session.entities.size === 0) {
+            sessionCache.delete(sessionId);
+        }
+    }
+}
+/**
+ * Persist session entities to the database for durability.
+ * Called periodically or on session end.
+ */
+export async function persistSessionEntities(sessionId) {
+    const session = sessionCache.get(sessionId);
+    if (!session || session.entities.size === 0)
+        return;
+    try {
+        const db = await getDb();
+        const schema = await getSchema();
+        // Store session context in the context_sessions table
+        const entities = [...session.entities.values()];
+        const entityData = entities.map(e => ({
+            id: e.entityId,
+            name: e.entityName,
+            type: e.entityType,
+            salience: e.salience,
+            mentionCount: e.mentionCount,
+        }));
+        // Check if session exists
+        const existing = await db
+            .select()
+            .from(schema.contextSessions)
+            .where(eq(schema.contextSessions.id, sessionId))
+            .limit(1);
+        if (existing.length > 0) {
+            await db
+                .update(schema.contextSessions)
+                .set({
+                metadata: { entities: entityData },
+                updatedAt: new Date(),
+            })
+                .where(eq(schema.contextSessions.id, sessionId));
+        }
+        // If session doesn't exist, we don't create it here
+        // (it will be created by the normal session flow)
+        logger.debug('Persisted session entities', {
+            sessionId,
+            entityCount: entities.length,
+        });
+    }
+    catch (error) {
+        logger.warn('Failed to persist session entities', { error: error });
+    }
+}
+/**
+ * Load session entities from the database.
+ * Called when a session starts.
+ */
+export async function loadSessionEntities(sessionId) {
+    try {
+        const db = await getDb();
+        const schema = await getSchema();
+        const session = await db
+            .select()
+            .from(schema.contextSessions)
+            .where(eq(schema.contextSessions.id, sessionId))
+            .limit(1);
+        if (session.length === 0 || !session[0].metadata)
+            return;
+        const metadata = session[0].metadata;
+        const entityData = metadata.entities;
+        if (!Array.isArray(entityData))
+            return;
+        const sessionMap = {
+            sessionId,
+            entities: new Map(),
+            updatedAt: new Date(),
+        };
+        for (const e of entityData) {
+            sessionMap.entities.set(e.id, {
+                entityId: e.id,
+                entityName: e.name,
+                entityType: e.type,
+                mentionCount: e.mentionCount,
+                lastMentionedAt: new Date(), // Reset since we just loaded
+                salience: e.salience * 0.8, // Decay on load
+            });
+        }
+        sessionCache.set(sessionId, sessionMap);
+        logger.debug('Loaded session entities', {
+            sessionId,
+            entityCount: entityData.length,
+        });
+    }
+    catch (error) {
+        logger.warn('Failed to load session entities', { error: error });
+    }
+}
+//# sourceMappingURL=entity-tracker.js.map

package/dist/core/session/reference-resolver.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reference Resolver
+ *
+ * Resolves pronouns and references in queries to specific entities
+ * using session context. Enables queries like:
+ * "Was her project affected?" -> "Was Alice's project affected?"
+ */
+export interface ReferenceResolution {
+    original: string;
+    resolved: string;
+    resolvedEntity: string | null;
+    entityType: string | null;
+    confidence: number;
+    method: 'pronoun' | 'definite_reference' | 'name_match' | 'none';
+}
+/**
+ * Resolve pronouns and references in a query using session context.
+ * Returns the original query with pronouns replaced by entity names.
+ */
+export declare function resolvePronouns(query: string, sessionId: string): Promise<ReferenceResolution>;
+/**
+ * Check if a query should trigger reference resolution.
+ */
+export declare function shouldResolveReferences(query: string): boolean;
+export declare const wouldBenefitFromReferenceResolution: typeof shouldResolveReferences;
+//# sourceMappingURL=reference-resolver.d.ts.map

package/dist/core/session/reference-resolver.js

@@ -0,0 +1,121 @@
+/**
+ * Reference Resolver
+ *
+ * Resolves pronouns and references in queries to specific entities
+ * using session context. Enables queries like:
+ * "Was her project affected?" -> "Was Alice's project affected?"
+ */
+import { trackEntityInSession, resolveReference } from './entity-tracker.js';
+import { extractEntitiesAndRelations } from '../graph/llm-entity-extractor.js';
+import { logger } from '../logger.js';
+// ─── Pronoun Patterns ─────────────────────────────────────────────────────────
+const PRONOUNS = new Set([
+    'he', 'him', 'his', 'she', 'her', 'hers',
+    'it', 'its', 'they', 'them', 'their', 'theirs',
+    'this', 'that', 'these', 'those',
+]);
+const POSSESSIVE_PRONOUNS = new Set([
+    'his', 'her', 'hers', 'its', 'their', 'theirs', 'my', 'your', 'our',
+]);
+// ─── Main Resolution Function ────────────────────────────────────────────────
+/**
+ * Resolve pronouns and references in a query using session context.
+ * Returns the original query with pronouns replaced by entity names.
+ */
+export async function resolvePronouns(query, sessionId) {
+    const words = query.split(/\s+/);
+    let resolved = query;
+    let bestResolution = {
+        original: query,
+        resolved: query,
+        resolvedEntity: null,
+        entityType: null,
+        confidence: 0,
+        method: 'none',
+    };
+    // Step 1: Extract entities from the query itself
+    const extraction = await extractEntitiesAndRelations(query, { preferLLM: false });
+    for (const entity of extraction.entities) {
+        trackEntityInSession(sessionId, entity.name, entity.name, entity.type);
+    }
+    // Step 2: Check each word for pronouns
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i].toLowerCase().replace(/[.,!?;:]/g, '');
+        if (PRONOUNS.has(word)) {
+            const entity = resolveReference(sessionId, words[i]);
+            if (entity) {
+                // Replace the pronoun with the entity name
+                const originalWord = words[i];
+                words[i] = entity.entityName;
+                resolved = words.join(' ');
+                bestResolution = {
+                    original: query,
+                    resolved,
+                    resolvedEntity: entity.entityName,
+                    entityType: entity.entityType,
+                    confidence: entity.salience,
+                    method: 'pronoun',
+                };
+                logger.debug('Resolved pronoun', {
+                    pronoun: originalWord,
+                    entity: entity.entityName,
+                    type: entity.entityType,
+                    salience: entity.salience,
+                });
+            }
+        }
+    }
+    // Step 3: Check for definite references ("the project", "the database")
+    if (bestResolution.method === 'none') {
+        const definiteRefPatterns = [
+            { pattern: /\bthe (project|app|application)\b/i, types: ['concept'] },
+            { pattern: /\bthe (team|group)\b/i, types: ['concept'] },
+            { pattern: /\bthe (database|db)\b/i, types: ['tool'] },
+            { pattern: /\bthe (server|service|api)\b/i, types: ['tool'] },
+            { pattern: /\bthe (issue|bug|problem|outage)\b/i, types: ['concept'] },
+            { pattern: /\bthe (file|module|component)\b/i, types: ['file'] },
+        ];
+        for (const { pattern, types } of definiteRefPatterns) {
+            if (pattern.test(query)) {
+                const entity = resolveReference(sessionId, query.match(pattern)[0]);
+                if (entity) {
+                    // Replace "the X" with "the X (EntityName)"
+                    resolved = query.replace(pattern, `$1 (${entity.entityName})`);
+                    bestResolution = {
+                        original: query,
+                        resolved,
+                        resolvedEntity: entity.entityName,
+                        entityType: entity.entityType,
+                        confidence: entity.salience * 0.9, // Slightly lower confidence than direct pronoun
+                        method: 'definite_reference',
+                    };
+                    break;
+                }
+            }
+        }
+    }
+    // Step 4: If we resolved something, also track the resolved entity
+    if (bestResolution.resolvedEntity) {
+        trackEntityInSession(sessionId, bestResolution.resolvedEntity, bestResolution.resolvedEntity, bestResolution.entityType || 'unknown');
+    }
+    return bestResolution;
+}
+/**
+ * Check if a query should trigger reference resolution.
+ */
+export function shouldResolveReferences(query) {
+    const words = query.split(/\s+/);
+    for (const word of words) {
+        const clean = word.toLowerCase().replace(/[.,!?;:]/g, '');
+        if (PRONOUNS.has(clean))
+            return true;
+    }
+    // Check for definite references
+    const definitePatterns = [
+        /\bthe (project|app|application|team|group|database|db|server|service|api|issue|bug|problem|outage|file|module|component)\b/i,
+    ];
+    return definitePatterns.some(p => p.test(query));
+}
+// Backward compatibility
+export const wouldBenefitFromReferenceResolution = shouldResolveReferences;
+//# sourceMappingURL=reference-resolver.js.map

package/dist/core/session/self-iteration-job.d.ts

@@ -3,6 +3,7 @@
  * Processes conversations to extract memories and generate summaries
  */
 import { type JobHandler } from '../scheduler/cron-scheduler.js';
+import type { MemoryType } from '../lib/types.js';
 export interface SelfIterationConfig {
     enabled: boolean;
     extractFacts: boolean;
@@ -12,6 +13,20 @@ export interface SelfIterationConfig {
     maxMessagesToProcess: number;
 }
 declare const DEFAULT_CONFIG: SelfIterationConfig;
+export interface MessageRow {
+    id: string;
+    conversationId: string;
+    role: string;
+    content: string;
+    createdAt: Date;
+}
+interface ExtractedFact {
+    content: string;
+    type: ExtractableMemoryType;
+    confidence: number;
+}
+type ExtractableMemoryType = Extract<MemoryType, 'fact' | 'decision' | 'preference'>;
+export declare function extractDurableSelfIterationFacts(messages: MessageRow[]): ExtractedFact[];
 /**
  * Register self-iteration job handler
  */