@theihtisham/ai-agent-starter-kit 1.0.0

package/src/lib/agents/memory/long-term.ts

@@ -0,0 +1,241 @@
+/**
+ * Long-Term Memory — Persistent key-value store with cosine similarity search.
+ *
+ * Stores memories with optional embeddings. When no embeddings are provided,
+ * falls back to keyword-based matching. Supports eviction of the least-recently-used
+ * entries when capacity is reached.
+ */
+
+import type { MemoryEntry, MemoryConfig, RecallOptions } from './types';
+import { DEFAULT_MEMORY_CONFIG } from './types';
+
+export class LongTermMemory {
+  private store: Map<string, MemoryEntry> = new Map();
+  private readonly config: MemoryConfig;
+  private idCounter = 0;
+
+  constructor(config: Partial<MemoryConfig> = {}) {
+    this.config = { ...DEFAULT_MEMORY_CONFIG, ...config };
+  }
+
+  /** Store a new memory entry */
+  store_entry(
+    key: string,
+    value: string,
+    embedding?: number[],
+    metadata?: Record<string, unknown>,
+  ): MemoryEntry {
+    const entry: MemoryEntry = {
+      id: `ltm_${++this.idCounter}_${Date.now()}`,
+      content: value,
+      role: 'observation',
+      timestamp: Date.now(),
+      embedding,
+      metadata: { ...metadata, key },
+    };
+
+    this.store.set(key, entry);
+
+    // Evict least-recently-accessed entries if over capacity
+    this.evictIfNeeded();
+
+    return entry;
+  }
+
+  /** Retrieve a specific entry by key */
+  retrieve(key: string): MemoryEntry | undefined {
+    const entry = this.store.get(key);
+    if (entry) {
+      // Update timestamp to mark as recently accessed
+      entry.timestamp = Date.now();
+    }
+    return entry;
+  }
+
+  /** Search for memories matching a query using cosine similarity or keyword fallback */
+  recall(query: string, options?: RecallOptions): MemoryEntry[] {
+    const allEntries = Array.from(this.store.values());
+
+    let results: Array<{ entry: MemoryEntry; score: number }>;
+
+    // Check if query has an embedding (passed via metadata) or use keyword matching
+    const queryEmbedding = options?.minSimilarity !== undefined
+      ? undefined
+      : undefined;
+
+    if (queryEmbedding) {
+      results = this.searchByEmbedding(queryEmbedding, allEntries, options);
+    } else {
+      results = this.searchByKeywords(query, allEntries);
+    }
+
+    // Apply filters
+    if (options?.role) {
+      results = results.filter((r) => r.entry.role === options.role);
+    }
+    if (options?.since) {
+      results = results.filter((r) => r.entry.timestamp >= options.since!);
+    }
+    if (options?.until) {
+      results = results.filter((r) => r.entry.timestamp <= options.until!);
+    }
+
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+
+    const topK = options?.topK ?? 5;
+    return results.slice(0, topK).map((r) => r.entry);
+  }
+
+  /** Remove a specific memory by key */
+  forget(key: string): boolean {
+    return this.store.delete(key);
+  }
+
+  /** Clear all long-term memories */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Get the number of stored entries */
+  get count(): number {
+    return this.store.size;
+  }
+
+  /** Get all stored entries */
+  getAll(): MemoryEntry[] {
+    return Array.from(this.store.values());
+  }
+
+  /** Get all keys */
+  keys(): string[] {
+    return Array.from(this.store.keys());
+  }
+
+  /** Search entries by embedding similarity */
+  searchByEmbedding(
+    queryEmbedding: number[],
+    entries: MemoryEntry[],
+    options?: RecallOptions,
+  ): Array<{ entry: MemoryEntry; score: number }> {
+    const threshold = options?.minSimilarity ?? this.config.similarityThreshold;
+
+    return entries
+      .filter((e) => e.embedding !== undefined)
+      .map((entry) => ({
+        entry,
+        score: cosineSimilarity(queryEmbedding, entry.embedding!),
+      }))
+      .filter((r) => r.score >= threshold);
+  }
+
+  /** Search entries by keyword matching */
+  private searchByKeywords(
+    query: string,
+    entries: MemoryEntry[],
+  ): Array<{ entry: MemoryEntry; score: number }> {
+    const queryLower = query.toLowerCase();
+    const terms = queryLower.split(/\s+/).filter(Boolean);
+
+    return entries
+      .map((entry) => {
+        const contentLower = entry.content.toLowerCase();
+        const keyLower = (entry.metadata?.key as string | undefined)?.toLowerCase() ?? '';
+
+        // Score: count of matching terms + recency bonus
+        let score = 0;
+        for (const term of terms) {
+          if (contentLower.includes(term)) score += 1;
+          if (keyLower.includes(term)) score += 0.5;
+        }
+
+        // Normalize by query length
+        if (terms.length > 0) {
+          score = score / terms.length;
+        }
+
+        // Small recency bonus (0-0.2 range)
+        const ageMs = Date.now() - entry.timestamp;
+        const ageHours = ageMs / (1000 * 60 * 60);
+        const recencyBonus = Math.max(0, 0.2 - ageHours * 0.001);
+        score += recencyBonus;
+
+        return { entry, score };
+      })
+      .filter((r) => r.score > 0);
+  }
+
+  /** Evict least-recently-accessed entries when over capacity */
+  private evictIfNeeded(): void {
+    while (this.store.size > this.config.longTermMaxEntries) {
+      let oldestKey: string | null = null;
+      let oldestTime = Infinity;
+
+      this.store.forEach((entry, key) => {
+        if (entry.timestamp < oldestTime) {
+          oldestTime = entry.timestamp;
+          oldestKey = key;
+        }
+      });
+
+      if (oldestKey) {
+        this.store.delete(oldestKey);
+      } else {
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Compute cosine similarity between two vectors.
+ * Returns a value between -1 and 1, where 1 means identical direction.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denominator === 0) return 0;
+
+  return dotProduct / denominator;
+}
+
+/**
+ * Generate a simple embedding from text using a bag-of-words approach.
+ * This is a placeholder — in production, use OpenAI embeddings or similar.
+ */
+export function simpleEmbedding(text: string, dimensions: number = 128): number[] {
+  const vector = new Array(dimensions).fill(0);
+  const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+
+  for (let i = 0; i < words.length; i++) {
+    const word = words[i]!;
+    // Simple hash to spread across dimensions
+    let hash = 0;
+    for (let j = 0; j < word.length; j++) {
+      hash = ((hash << 5) - hash + word.charCodeAt(j)) | 0;
+    }
+    const dim = Math.abs(hash) % dimensions;
+    vector[dim]! += 1;
+  }
+
+  // Normalize
+  const norm = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+  if (norm > 0) {
+    for (let i = 0; i < vector.length; i++) {
+      vector[i] = vector[i]! / norm;
+    }
+  }
+
+  return vector;
+}

package/src/lib/agents/memory/manager.ts

@@ -0,0 +1,154 @@
+/**
+ * Memory Manager — Orchestrates short-term and long-term memory.
+ *
+ * Provides a unified interface for the agent memory system:
+ * - Automatic promotion of short-term entries to long-term
+ * - Summarization of short-term memory when it fills up
+ * - Combined recall across both memory layers
+ */
+
+import { ShortTermMemory } from './short-term';
+import { LongTermMemory, simpleEmbedding } from './long-term';
+import type {
+  MemoryEntry,
+  MemoryConfig,
+  RecallOptions,
+  MemoryStats,
+  MemorySummary,
+} from './types';
+import { DEFAULT_MEMORY_CONFIG } from './types';
+
+export class MemoryManager {
+  public readonly shortTerm: ShortTermMemory;
+  public readonly longTerm: LongTermMemory;
+  private readonly config: MemoryConfig;
+
+  constructor(config: Partial<MemoryConfig> = {}) {
+    this.config = { ...DEFAULT_MEMORY_CONFIG, ...config };
+    this.shortTerm = new ShortTermMemory(config);
+    this.longTerm = new LongTermMemory(config);
+  }
+
+  /**
+   * Remember a piece of content.
+   * Stores in short-term memory. When short-term is near capacity,
+   * older entries are promoted to long-term memory.
+   */
+  remember(
+    content: string,
+    role: MemoryEntry['role'] = 'observation',
+    metadata?: Record<string, unknown>,
+  ): MemoryEntry {
+    const entry = this.shortTerm.add({ content, role, metadata });
+
+    // Check if short-term is getting full — promote older entries
+    if (this.shortTerm.count >= this.config.shortTermMaxEntries * 0.8) {
+      this.promoteToLongTerm();
+    }
+
+    return entry;
+  }
+
+  /**
+   * Recall relevant memories from both short-term and long-term stores.
+   * Returns results merged and ranked by relevance.
+   */
+  recall(query: string, options?: RecallOptions): MemoryEntry[] {
+    const topK = options?.topK ?? 5;
+
+    // Search both stores
+    const shortTermResults = this.shortTerm.recall(query, { ...options, topK });
+    const longTermResults = this.longTerm.recall(query, { ...options, topK });
+
+    // Merge and deduplicate by ID
+    const seen = new Set<string>();
+    const merged: MemoryEntry[] = [];
+
+    // Prefer short-term results (more recent context)
+    for (const entry of shortTermResults) {
+      if (!seen.has(entry.id)) {
+        seen.add(entry.id);
+        merged.push(entry);
+      }
+    }
+
+    // Add long-term results
+    for (const entry of longTermResults) {
+      if (!seen.has(entry.id)) {
+        seen.add(entry.id);
+        merged.push(entry);
+      }
+    }
+
+    return merged.slice(0, topK);
+  }
+
+  /**
+   * Generate a summary of the current short-term memory.
+   * Also stores the summary in long-term memory for future reference.
+   */
+  summarize(): MemorySummary {
+    const summary = this.shortTerm.summarize();
+
+    // Store the summary in long-term memory
+    this.longTerm.store_entry(
+      `summary_${summary.id}`,
+      summary.summary,
+      simpleEmbedding(summary.summary),
+      {
+        type: 'summary',
+        entryCount: summary.entryCount,
+        fromTimestamp: summary.fromTimestamp,
+        toTimestamp: summary.toTimestamp,
+      },
+    );
+
+    return summary;
+  }
+
+  /** Clear all memory (both short-term and long-term) */
+  clear(): void {
+    this.shortTerm.clear();
+    this.longTerm.clear();
+  }
+
+  /** Get statistics about the memory system */
+  getStats(): MemoryStats {
+    const stEntries = this.shortTerm.getAll();
+    const ltEntries = this.longTerm.getAll();
+
+    const allTimestamps = [...stEntries, ...ltEntries].map((e) => e.timestamp);
+
+    return {
+      shortTermCount: stEntries.length,
+      longTermCount: ltEntries.length,
+      summaryCount: this.shortTerm.getSummaries().length,
+      oldestEntry: allTimestamps.length > 0 ? Math.min(...allTimestamps) : null,
+      newestEntry: allTimestamps.length > 0 ? Math.max(...allTimestamps) : null,
+    };
+  }
+
+  /**
+   * Promote the oldest short-term entries to long-term memory.
+   * Called automatically when short-term memory approaches capacity.
+   */
+  private promoteToLongTerm(): void {
+    const promoteCount = Math.floor(this.config.shortTermMaxEntries * 0.3);
+    const evicted = this.shortTerm.evictOldest(promoteCount);
+
+    for (const entry of evicted) {
+      const embedding = entry.embedding ?? simpleEmbedding(entry.content);
+      this.longTerm.store_entry(
+        `promoted_${entry.id}`,
+        entry.content,
+        embedding,
+        {
+          ...entry.metadata,
+          originalId: entry.id,
+          role: entry.role,
+          promotedAt: Date.now(),
+        },
+      );
+    }
+  }
+}

package/src/lib/agents/memory/short-term.ts

@@ -0,0 +1,155 @@
+/**
+ * Short-Term Memory — Sliding window of recent conversation context.
+ *
+ * Keeps the most recent N messages in memory. When the window is full,
+ * the oldest entries are evicted (and optionally summarized first).
+ */
+
+import type { MemoryEntry, MemorySummary, RecallOptions, MemoryConfig } from './types';
+import { DEFAULT_MEMORY_CONFIG } from './types';
+
+export class ShortTermMemory {
+  private entries: MemoryEntry[] = [];
+  private summaries: MemorySummary[] = [];
+  private readonly config: MemoryConfig;
+  private idCounter = 0;
+
+  constructor(config: Partial<MemoryConfig> = {}) {
+    this.config = { ...DEFAULT_MEMORY_CONFIG, ...config };
+  }
+
+  /** Add a new entry to short-term memory */
+  add(entry: Omit<MemoryEntry, 'id' | 'timestamp'>): MemoryEntry {
+    const fullEntry: MemoryEntry = {
+      ...entry,
+      id: `stm_${++this.idCounter}_${Date.now()}`,
+      timestamp: Date.now(),
+    };
+
+    this.entries.push(fullEntry);
+
+    // Evict oldest entries if over capacity
+    while (this.entries.length > this.config.shortTermMaxEntries) {
+      const evicted = this.entries.shift();
+      if (evicted && this.config.autoSummarize) {
+        // The MemoryManager handles transferring evicted entries to long-term
+      }
+    }
+
+    return fullEntry;
+  }
+
+  /** Recall entries matching the given options */
+  recall(query: string, options?: RecallOptions): MemoryEntry[] {
+    let results = [...this.entries];
+
+    // Filter by role
+    if (options?.role) {
+      results = results.filter((e) => e.role === options.role);
+    }
+
+    // Filter by time range
+    if (options?.since) {
+      results = results.filter((e) => e.timestamp >= options.since!);
+    }
+    if (options?.until) {
+      results = results.filter((e) => e.timestamp <= options.until!);
+    }
+
+    // Simple keyword matching for non-vector search
+    if (query.trim()) {
+      const queryLower = query.toLowerCase();
+      const terms = queryLower.split(/\s+/).filter(Boolean);
+
+      results = results.filter((entry) => {
+        const contentLower = entry.content.toLowerCase();
+        return terms.some((term) => contentLower.includes(term));
+      });
+
+      // Score by number of matching terms and recency
+      results.sort((a, b) => {
+        const scoreA = terms.filter((t) => a.content.toLowerCase().includes(t)).length;
+        const scoreB = terms.filter((t) => b.content.toLowerCase().includes(t)).length;
+        if (scoreA !== scoreB) return scoreB - scoreA;
+        return b.timestamp - a.timestamp;
+      });
+    } else {
+      // No query — return most recent first
+      results.sort((a, b) => b.timestamp - a.timestamp);
+    }
+
+    // Apply topK limit
+    const topK = options?.topK ?? 5;
+    return results.slice(0, topK);
+  }
+
+  /** Get all entries in chronological order */
+  getAll(): MemoryEntry[] {
+    return [...this.entries];
+  }
+
+  /** Generate a summary of all current entries */
+  summarize(): MemorySummary {
+    const summary: MemorySummary = {
+      id: `sum_${++this.idCounter}_${Date.now()}`,
+      summary: this.generateSummaryText(),
+      entryCount: this.entries.length,
+      fromTimestamp: this.entries[0]?.timestamp ?? Date.now(),
+      toTimestamp: this.entries[this.entries.length - 1]?.timestamp ?? Date.now(),
+      createdAt: Date.now(),
+    };
+
+    this.summaries.push(summary);
+    return summary;
+  }
+
+  /** Clear all short-term memory */
+  clear(): void {
+    this.entries = [];
+  }
+
+  /** Get the number of entries currently stored */
+  get count(): number {
+    return this.entries.length;
+  }
+
+  /** Get all summaries */
+  getSummaries(): MemorySummary[] {
+    return [...this.summaries];
+  }
+
+  /** Evict and return the oldest N entries */
+  evictOldest(count: number): MemoryEntry[] {
+    const evicted: MemoryEntry[] = [];
+    for (let i = 0; i < count && this.entries.length > 0; i++) {
+      const entry = this.entries.shift();
+      if (entry) evicted.push(entry);
+    }
+    return evicted;
+  }
+
+  private generateSummaryText(): string {
+    if (this.entries.length === 0) return 'No entries to summarize.';
+
+    const userMessages = this.entries
+      .filter((e) => e.role === 'user')
+      .map((e) => e.content);
+
+    const assistantMessages = this.entries
+      .filter((e) => e.role === 'assistant')
+      .map((e) => e.content);
+
+    const parts: string[] = [];
+
+    if (userMessages.length > 0) {
+      parts.push(`User discussed: ${userMessages.map((m) => `"${m.slice(0, 80)}"`).join(', ')}`);
+    }
+    if (assistantMessages.length > 0) {
+      parts.push(
+        `Assistant covered: ${assistantMessages.map((m) => `"${m.slice(0, 80)}"`).join(', ')}`,
+      );
+    }
+
+    return parts.join('. ') + `. (${this.entries.length} messages total)`;
+  }
+}

package/src/lib/agents/memory/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Agent Memory System Types
+ *
+ * Dual-layer memory: short-term sliding window + long-term persistent store
+ * with optional embedding-based similarity search.
+ */
+
+/** A single memory entry stored in the system */
+export interface MemoryEntry {
+  id: string;
+  content: string;
+  role: 'user' | 'assistant' | 'system' | 'observation';
+  timestamp: number;
+  embedding?: number[];
+  metadata?: Record<string, unknown>;
+}
+
+/** Configuration for the memory store */
+export interface MemoryConfig {
+  /** Maximum entries in short-term memory (default: 50) */
+  shortTermMaxEntries: number;
+  /** Maximum entries to keep in long-term memory before eviction (default: 1000) */
+  longTermMaxEntries: number;
+  /** Whether to auto-summarize when short-term memory is full (default: true) */
+  autoSummarize: boolean;
+  /** Similarity threshold for embedding-based recall (0-1, default: 0.7) */
+  similarityThreshold: number;
+}
+
+export const DEFAULT_MEMORY_CONFIG: MemoryConfig = {
+  shortTermMaxEntries: 50,
+  longTermMaxEntries: 1000,
+  autoSummarize: true,
+  similarityThreshold: 0.7,
+};
+
+/** Options for recalling memories */
+export interface RecallOptions {
+  /** Maximum number of results to return (default: 5) */
+  topK?: number;
+  /** Only recall entries after this timestamp */
+  since?: number;
+  /** Only recall entries before this timestamp */
+  until?: number;
+  /** Filter by role */
+  role?: MemoryEntry['role'];
+  /** Minimum similarity score for embedding-based search (0-1) */
+  minSimilarity?: number;
+}
+
+/** A summarized version of recent conversation */
+export interface MemorySummary {
+  id: string;
+  summary: string;
+  entryCount: number;
+  fromTimestamp: number;
+  toTimestamp: number;
+  createdAt: number;
+}
+
+/** Stats about the memory system */
+export interface MemoryStats {
+  shortTermCount: number;
+  longTermCount: number;
+  summaryCount: number;
+  oldestEntry: number | null;
+  newestEntry: number | null;
+}