claude-memory-layer 1.0.0

package/src/core/graduation.ts

@@ -0,0 +1,365 @@
+/**
+ * Memory Graduation Pipeline - AXIOMMIND L0→L1→L2→L3→L4
+ *
+ * L0: EventStore (raw events, append-only)
+ * L1: Structured JSON (session summaries, patterns)
+ * L2: Type Candidates (Idris2-inspired, validated schemas)
+ * L3: Verified Knowledge (cross-session validated)
+ * L4: Active/Searchable (indexed, readily available)
+ */
+
+import { EventStore } from './event-store.js';
+import type {
+  MemoryEvent,
+  MemoryLevel,
+  GraduationResult,
+  Insight,
+  InsightType
+} from './types.js';
+
+export interface GraduationCriteria {
+  minAccessCount: number;
+  minConfidence: number;
+  minCrossSessionRefs: number;
+  maxAgeDays: number;
+}
+
+export interface LevelCriteria {
+  L0toL1: GraduationCriteria;
+  L1toL2: GraduationCriteria;
+  L2toL3: GraduationCriteria;
+  L3toL4: GraduationCriteria;
+}
+
+const DEFAULT_CRITERIA: LevelCriteria = {
+  L0toL1: {
+    minAccessCount: 1,
+    minConfidence: 0.5,
+    minCrossSessionRefs: 0,
+    maxAgeDays: 30
+  },
+  L1toL2: {
+    minAccessCount: 3,
+    minConfidence: 0.7,
+    minCrossSessionRefs: 1,
+    maxAgeDays: 60
+  },
+  L2toL3: {
+    minAccessCount: 5,
+    minConfidence: 0.85,
+    minCrossSessionRefs: 2,
+    maxAgeDays: 90
+  },
+  L3toL4: {
+    minAccessCount: 10,
+    minConfidence: 0.92,
+    minCrossSessionRefs: 3,
+    maxAgeDays: 180
+  }
+};
+
+export interface EventMetrics {
+  eventId: string;
+  accessCount: number;
+  lastAccessed: Date;
+  crossSessionRefs: number;
+  confidence: number;
+}
+
+export class GraduationPipeline {
+  private readonly eventStore: EventStore;
+  private readonly criteria: LevelCriteria;
+  private readonly metrics: Map<string, EventMetrics> = new Map();
+
+  constructor(
+    eventStore: EventStore,
+    criteria: Partial<LevelCriteria> = {}
+  ) {
+    this.eventStore = eventStore;
+    this.criteria = {
+      L0toL1: { ...DEFAULT_CRITERIA.L0toL1, ...criteria.L0toL1 },
+      L1toL2: { ...DEFAULT_CRITERIA.L1toL2, ...criteria.L1toL2 },
+      L2toL3: { ...DEFAULT_CRITERIA.L2toL3, ...criteria.L2toL3 },
+      L3toL4: { ...DEFAULT_CRITERIA.L3toL4, ...criteria.L3toL4 }
+    };
+  }
+
+  /**
+   * Record an access to an event (used for graduation scoring)
+   */
+  recordAccess(eventId: string, fromSessionId: string, confidence: number = 1.0): void {
+    const existing = this.metrics.get(eventId);
+
+    if (existing) {
+      existing.accessCount++;
+      existing.lastAccessed = new Date();
+      existing.confidence = Math.max(existing.confidence, confidence);
+      // Track cross-session references
+      // This would need more sophisticated tracking in production
+    } else {
+      this.metrics.set(eventId, {
+        eventId,
+        accessCount: 1,
+        lastAccessed: new Date(),
+        crossSessionRefs: 0,
+        confidence
+      });
+    }
+  }
+
+  /**
+   * Evaluate if an event should graduate to the next level
+   */
+  async evaluateGraduation(eventId: string, currentLevel: MemoryLevel): Promise<GraduationResult> {
+    const metrics = this.metrics.get(eventId);
+
+    if (!metrics) {
+      return {
+        eventId,
+        fromLevel: currentLevel,
+        toLevel: currentLevel,
+        success: false,
+        reason: 'No metrics available for event'
+      };
+    }
+
+    const nextLevel = this.getNextLevel(currentLevel);
+    if (!nextLevel) {
+      return {
+        eventId,
+        fromLevel: currentLevel,
+        toLevel: currentLevel,
+        success: false,
+        reason: 'Already at maximum level'
+      };
+    }
+
+    const criteria = this.getCriteria(currentLevel, nextLevel);
+    const evaluation = this.checkCriteria(metrics, criteria);
+
+    if (evaluation.passed) {
+      // Update level in event store
+      await this.eventStore.updateMemoryLevel(eventId, nextLevel);
+
+      return {
+        eventId,
+        fromLevel: currentLevel,
+        toLevel: nextLevel,
+        success: true
+      };
+    }
+
+    return {
+      eventId,
+      fromLevel: currentLevel,
+      toLevel: currentLevel,
+      success: false,
+      reason: evaluation.reason
+    };
+  }
+
+  /**
+   * Run graduation evaluation for all events at a given level
+   */
+  async graduateBatch(level: MemoryLevel): Promise<GraduationResult[]> {
+    const results: GraduationResult[] = [];
+
+    for (const [eventId, metrics] of this.metrics) {
+      const result = await this.evaluateGraduation(eventId, level);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /**
+   * Extract insights from graduated events (L1+)
+   */
+  extractInsights(events: MemoryEvent[]): Insight[] {
+    const insights: Insight[] = [];
+
+    // Pattern detection: Look for repeated themes
+    const patterns = this.detectPatterns(events);
+    for (const pattern of patterns) {
+      insights.push({
+        id: crypto.randomUUID(),
+        insightType: 'pattern',
+        content: pattern.description,
+        canonicalKey: pattern.key,
+        confidence: pattern.confidence,
+        sourceEvents: pattern.eventIds,
+        createdAt: new Date(),
+        lastUpdated: new Date()
+      });
+    }
+
+    // Preference detection: Look for user preferences
+    const preferences = this.detectPreferences(events);
+    for (const pref of preferences) {
+      insights.push({
+        id: crypto.randomUUID(),
+        insightType: 'preference',
+        content: pref.description,
+        canonicalKey: pref.key,
+        confidence: pref.confidence,
+        sourceEvents: pref.eventIds,
+        createdAt: new Date(),
+        lastUpdated: new Date()
+      });
+    }
+
+    return insights;
+  }
+
+  /**
+   * Get the next level in the graduation pipeline
+   */
+  private getNextLevel(current: MemoryLevel): MemoryLevel | null {
+    const levels: MemoryLevel[] = ['L0', 'L1', 'L2', 'L3', 'L4'];
+    const currentIndex = levels.indexOf(current);
+
+    if (currentIndex === -1 || currentIndex >= levels.length - 1) {
+      return null;
+    }
+
+    return levels[currentIndex + 1];
+  }
+
+  /**
+   * Get criteria for level transition
+   */
+  private getCriteria(from: MemoryLevel, to: MemoryLevel): GraduationCriteria {
+    const key = `${from}to${to}` as keyof LevelCriteria;
+    return this.criteria[key] || DEFAULT_CRITERIA.L0toL1;
+  }
+
+  /**
+   * Check if metrics meet criteria
+   */
+  private checkCriteria(
+    metrics: EventMetrics,
+    criteria: GraduationCriteria
+  ): { passed: boolean; reason?: string } {
+    if (metrics.accessCount < criteria.minAccessCount) {
+      return {
+        passed: false,
+        reason: `Access count ${metrics.accessCount} < ${criteria.minAccessCount}`
+      };
+    }
+
+    if (metrics.confidence < criteria.minConfidence) {
+      return {
+        passed: false,
+        reason: `Confidence ${metrics.confidence} < ${criteria.minConfidence}`
+      };
+    }
+
+    if (metrics.crossSessionRefs < criteria.minCrossSessionRefs) {
+      return {
+        passed: false,
+        reason: `Cross-session refs ${metrics.crossSessionRefs} < ${criteria.minCrossSessionRefs}`
+      };
+    }
+
+    const ageDays = (Date.now() - metrics.lastAccessed.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageDays > criteria.maxAgeDays) {
+      return {
+        passed: false,
+        reason: `Event too old: ${ageDays.toFixed(1)} days > ${criteria.maxAgeDays}`
+      };
+    }
+
+    return { passed: true };
+  }
+
+  /**
+   * Detect patterns in events
+   */
+  private detectPatterns(events: MemoryEvent[]): Array<{
+    key: string;
+    description: string;
+    confidence: number;
+    eventIds: string[];
+  }> {
+    // Simple pattern detection: group by canonical key and look for repeats
+    const keyGroups = new Map<string, MemoryEvent[]>();
+
+    for (const event of events) {
+      const existing = keyGroups.get(event.canonicalKey) || [];
+      existing.push(event);
+      keyGroups.set(event.canonicalKey, existing);
+    }
+
+    const patterns: Array<{
+      key: string;
+      description: string;
+      confidence: number;
+      eventIds: string[];
+    }> = [];
+
+    for (const [key, groupEvents] of keyGroups) {
+      if (groupEvents.length >= 2) {
+        patterns.push({
+          key,
+          description: `Repeated topic: ${key.slice(0, 50)}`,
+          confidence: Math.min(1.0, groupEvents.length / 5),
+          eventIds: groupEvents.map(e => e.id)
+        });
+      }
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Detect user preferences from events
+   */
+  private detectPreferences(events: MemoryEvent[]): Array<{
+    key: string;
+    description: string;
+    confidence: number;
+    eventIds: string[];
+  }> {
+    // Simple preference detection: look for keywords
+    const preferenceKeywords = ['prefer', 'like', 'want', 'always', 'never', 'favorite'];
+    const preferences: Array<{
+      key: string;
+      description: string;
+      confidence: number;
+      eventIds: string[];
+    }> = [];
+
+    for (const event of events) {
+      if (event.eventType !== 'user_prompt') continue;
+
+      const lowerContent = event.content.toLowerCase();
+      for (const keyword of preferenceKeywords) {
+        if (lowerContent.includes(keyword)) {
+          preferences.push({
+            key: `preference_${keyword}_${event.id.slice(0, 8)}`,
+            description: `User preference: ${event.content.slice(0, 100)}`,
+            confidence: 0.7,
+            eventIds: [event.id]
+          });
+          break;
+        }
+      }
+    }
+
+    return preferences;
+  }
+
+  /**
+   * Get graduation statistics
+   */
+  async getStats(): Promise<{ level: string; count: number }[]> {
+    return this.eventStore.getLevelStats();
+  }
+}
+
+/**
+ * Create graduation pipeline with default settings
+ */
+export function createGraduationPipeline(eventStore: EventStore): GraduationPipeline {
+  return new GraduationPipeline(eventStore);
+}

package/src/core/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Core module exports
+ * AXIOMMIND Memory Graduation Pipeline
+ */
+
+// Types
+export * from './types.js';
+
+// Canonical Key (identity)
+export * from './canonical-key.js';
+
+// Storage
+export * from './event-store.js';
+export * from './entity-repo.js';
+export * from './edge-repo.js';
+
+// Vector
+export * from './vector-store.js';
+export * from './embedder.js';
+export * from './vector-worker.js';
+export * from './vector-outbox.js';
+
+// Matching & Alignment
+export * from './matcher.js';
+export * from './evidence-aligner.js';
+
+// Retrieval & Graduation
+export * from './retriever.js';
+export * from './graduation.js';
+
+// Task Entity System
+export * from './task/index.js';

package/src/core/matcher.ts

@@ -0,0 +1,210 @@
+/**
+ * AXIOMMIND Matcher - Weighted scoring with confidence classification
+ * Implements matching thresholds: high (≥0.92), suggested (≥0.75), none (<0.75)
+ */
+
+import type {
+  MemoryEvent,
+  MemoryMatch,
+  MatchResult,
+  MatchConfidence,
+  MATCH_THRESHOLDS
+} from './types.js';
+import { SearchResult } from './vector-store.js';
+
+export interface MatchWeights {
+  semanticSimilarity: number;
+  ftsScore: number;
+  recencyBonus: number;
+  statusWeight: number;
+}
+
+export interface MatcherConfig {
+  weights: MatchWeights;
+  minCombinedScore: number;
+  minGap: number;
+  suggestionThreshold: number;
+}
+
+const DEFAULT_CONFIG: MatcherConfig = {
+  weights: {
+    semanticSimilarity: 0.4,
+    ftsScore: 0.25,
+    recencyBonus: 0.2,
+    statusWeight: 0.15
+  },
+  minCombinedScore: 0.92,
+  minGap: 0.03,
+  suggestionThreshold: 0.75
+};
+
+export class Matcher {
+  private readonly config: MatcherConfig;
+
+  constructor(config: Partial<MatcherConfig> = {}) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      weights: { ...DEFAULT_CONFIG.weights, ...config.weights }
+    };
+  }
+
+  /**
+   * Calculate combined score using AXIOMMIND weighted formula
+   */
+  calculateCombinedScore(
+    semanticScore: number,
+    ftsScore: number = 0,
+    recencyDays: number = 0,
+    isActive: boolean = true
+  ): number {
+    const { weights } = this.config;
+
+    // Recency bonus: decays over 30 days
+    const recencyBonus = Math.max(0, 1 - recencyDays / 30);
+
+    // Status weight: active events get full weight
+    const statusMultiplier = isActive ? 1.0 : 0.7;
+
+    const combinedScore =
+      weights.semanticSimilarity * semanticScore +
+      weights.ftsScore * ftsScore +
+      weights.recencyBonus * recencyBonus +
+      weights.statusWeight * statusMultiplier;
+
+    return Math.min(1.0, combinedScore);
+  }
+
+  /**
+   * Classify match confidence based on AXIOMMIND thresholds
+   */
+  classifyConfidence(
+    topScore: number,
+    secondScore: number | null
+  ): MatchConfidence {
+    const { minCombinedScore, minGap, suggestionThreshold } = this.config;
+
+    // Calculate gap (infinity if no second match)
+    const gap = secondScore !== null ? topScore - secondScore : Infinity;
+
+    // High confidence: score ≥ 0.92 AND gap ≥ 0.03
+    if (topScore >= minCombinedScore && gap >= minGap) {
+      return 'high';
+    }
+
+    // Suggested: score ≥ 0.75
+    if (topScore >= suggestionThreshold) {
+      return 'suggested';
+    }
+
+    // No match
+    return 'none';
+  }
+
+  /**
+   * Match search results to find best memory
+   */
+  matchSearchResults(
+    results: SearchResult[],
+    getEventAge: (eventId: string) => number
+  ): MatchResult {
+    if (results.length === 0) {
+      return {
+        match: null,
+        confidence: 'none'
+      };
+    }
+
+    // Calculate combined scores
+    const scoredResults = results.map(result => {
+      const ageDays = getEventAge(result.eventId);
+      const combinedScore = this.calculateCombinedScore(
+        result.score,
+        0, // FTS score - would need to be passed in
+        ageDays,
+        true // Assume active
+      );
+
+      return {
+        result,
+        combinedScore
+      };
+    });
+
+    // Sort by combined score
+    scoredResults.sort((a, b) => b.combinedScore - a.combinedScore);
+
+    const topResult = scoredResults[0];
+    const secondScore = scoredResults.length > 1 ? scoredResults[1].combinedScore : null;
+
+    // Classify confidence
+    const confidence = this.classifyConfidence(topResult.combinedScore, secondScore);
+
+    // Build match result
+    const match: MemoryMatch = {
+      event: {
+        id: topResult.result.eventId,
+        eventType: topResult.result.eventType as 'user_prompt' | 'agent_response' | 'session_summary',
+        sessionId: topResult.result.sessionId,
+        timestamp: new Date(topResult.result.timestamp),
+        content: topResult.result.content,
+        canonicalKey: '', // Would need to be fetched
+        dedupeKey: ''     // Would need to be fetched
+      },
+      score: topResult.combinedScore
+    };
+
+    const gap = secondScore !== null ? topResult.combinedScore - secondScore : undefined;
+
+    // Build alternatives for suggested matches
+    const alternatives = confidence === 'suggested'
+      ? scoredResults.slice(1, 4).map(sr => ({
+          event: {
+            id: sr.result.eventId,
+            eventType: sr.result.eventType as 'user_prompt' | 'agent_response' | 'session_summary',
+            sessionId: sr.result.sessionId,
+            timestamp: new Date(sr.result.timestamp),
+            content: sr.result.content,
+            canonicalKey: '',
+            dedupeKey: ''
+          },
+          score: sr.combinedScore
+        }))
+      : undefined;
+
+    return {
+      match: confidence !== 'none' ? match : null,
+      confidence,
+      gap,
+      alternatives
+    };
+  }
+
+  /**
+   * Calculate days between two dates
+   */
+  static calculateAgeDays(timestamp: Date): number {
+    const now = new Date();
+    const diffMs = now.getTime() - timestamp.getTime();
+    return diffMs / (1000 * 60 * 60 * 24);
+  }
+
+  /**
+   * Get current configuration
+   */
+  getConfig(): Readonly<MatcherConfig> {
+    return { ...this.config };
+  }
+}
+
+/**
+ * Default matcher instance
+ */
+let defaultMatcher: Matcher | null = null;
+
+export function getDefaultMatcher(): Matcher {
+  if (!defaultMatcher) {
+    defaultMatcher = new Matcher();
+  }
+  return defaultMatcher;
+}