squish-memory 1.1.5 → 1.2.0

package/core/session/entity-tracker.ts

@@ -0,0 +1,363 @@
+/**
+ * Session Entity Tracker
+ * 
+ * Tracks "active" entities in conversation sessions to enable
+ * reference resolution (e.g., resolving "she" to "Alice").
+ */
+
+import { eq, and, desc, sql } from 'drizzle-orm';
+import { getDb } from '../../db/index.js';
+import { getSchema } from '../../db/schema.js';
+import { logger } from '../logger.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface SessionEntity {
+  entityId: string;
+  entityName: string;
+  entityType: string;
+  mentionCount: number;
+  lastMentionedAt: Date;
+  salience: number; // 0-1, higher = more relevant
+}
+
+export interface SessionEntityMap {
+  sessionId: string;
+  entities: Map<string, SessionEntity>;
+  updatedAt: Date;
+}
+
+// ─── In-Memory Session Cache ─────────────────────────────────────────────────
+
+const sessionCache = new Map<string, SessionEntityMap>();
+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: string,
+  entityId: string,
+  entityName: string,
+  entityType: string
+): void {
+  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: string,
+  options?: {
+    limit?: number;
+    minSalience?: number;
+    entityTypes?: string[];
+  }
+): SessionEntity[] {
+  const { limit = 10, minSalience = 0.1, entityTypes } = options || {};
+
+  const session = sessionCache.get(sessionId);
+  if (!session) return [];
+
+  const now = Date.now();
+  const entities: SessionEntity[] = [];
+
+  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: string,
+  reference: string
+): SessionEntity | null {
+  const session = sessionCache.get(sessionId);
+  if (!session) return null;
+
+  const lowerRef = reference.toLowerCase();
+
+  // Pronoun mapping
+  const pronounMap: Record<string, string[]> = {
+    '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: Array<{ pattern: RegExp; types: string[] }> = [
+    { 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: string): void {
+  sessionCache.delete(sessionId);
+}
+
+/**
+ * Get all active sessions.
+ */
+export function getActiveSessions(): string[] {
+  return [...sessionCache.keys()];
+}
+
+/**
+ * Decay all session entities (call periodically).
+ * Reduces salience of all entities across all sessions.
+ */
+export function decayAllSessionEntities(): void {
+  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: string): Promise<void> {
+  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 as any)
+      .select()
+      .from(schema.contextSessions)
+      .where(eq(schema.contextSessions.id, sessionId))
+      .limit(1);
+
+    if (existing.length > 0) {
+      await (db as any)
+        .update(schema.contextSessions)
+        .set({
+          metadata: { entities: entityData } as any,
+          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 as Error });
+  }
+}
+
+/**
+ * Load session entities from the database.
+ * Called when a session starts.
+ */
+export async function loadSessionEntities(sessionId: string): Promise<void> {
+  try {
+    const db = await getDb();
+    const schema = await getSchema();
+
+    const session = await (db as any)
+      .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 as Record<string, unknown>;
+    const entityData = metadata.entities as Array<{
+      id: string;
+      name: string;
+      type: string;
+      salience: number;
+      mentionCount: number;
+    }>;
+
+    if (!Array.isArray(entityData)) return;
+
+    const sessionMap: SessionEntityMap = {
+      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 as Error });
+  }
+}

package/core/session/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Session Module
+ * Session management and auto-load
+ */
+
+export * from './types.js';
+export * from './auto-load.js';

package/core/session/reference-resolver.ts

@@ -0,0 +1,158 @@
+/**
+ * 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, getActiveSessionEntities } from './entity-tracker.js';
+import { extractEntitiesAndRelations } from '../graph/llm-entity-extractor.js';
+import { logger } from '../logger.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ReferenceResolution {
+  original: string;
+  resolved: string;
+  resolvedEntity: string | null;
+  entityType: string | null;
+  confidence: number;
+  method: 'pronoun' | 'definite_reference' | 'name_match' | 'none';
+}
+
+// ─── 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: string,
+  sessionId: string
+): Promise<ReferenceResolution> {
+  const words = query.split(/\s+/);
+  let resolved = query;
+  let bestResolution: ReferenceResolution = {
+    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: string): boolean {
+  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;