AI Agent Memory Architecture: Designing Long-Term Memory

interface Memory {
  id: string;
  type: 'episodic' | 'semantic' | 'procedural';
  content: string;
  embedding: number[];      // vector representation
  importance: number;       // 0.0 to 1.0
  timestamp: Date;
  lastAccessed: Date;
  accessCount: number;
  metadata: {
    userId?: string;
    sessionId?: string;
    tags: string[];
    source: string;
  };
}

class MemoryManager {
  private vectorStore: VectorDatabase;
  private db: PostgreSQLDatabase;
  private embedder: EmbeddingModel;
 
  async storeMemory(
    content: string,
    type: Memory['type'],
    metadata: Partial<Memory['metadata']>
  ): Promise<Memory> {
    // 1. Convert text to vector
    const embedding = await this.embedder.embed(content);
    
    // 2. Calculate importance (from length, emotion, reference count, etc.)
    const importance = await this.calculateImportance(content, metadata);
    
    // 3. Create memory object
    const memory: Memory = {
      id: generateUUID(),
      type,
      content,
      embedding,
      importance,
      timestamp: new Date(),
      lastAccessed: new Date(),
      accessCount: 0,
      metadata: {
        tags: [],
        source: 'agent',
        ...metadata
      }
    };
    
    // 4. Store in both vector DB and relational DB
    await Promise.all([
      this.vectorStore.upsert(memory.id, embedding, { type, importance }),
      this.db.insert('memories', memory)
    ]);
    
    return memory;
  }
}

async recallMemories(
  query: string,
  options: {
    types?: Memory['type'][];
    limit?: number;
    minImportance?: number;
    maxAge?: number;  // days
  } = {}
): Promise<Memory[]> {
  // Convert query to vector
  const queryEmbedding = await this.embedder.embed(query);
  
  // Build filter conditions
  const filter = {
    type: options.types ? { $in: options.types } : undefined,
    importance: options.minImportance ? { $gte: options.minImportance } : undefined,
    timestamp: options.maxAge ? {
      $gte: new Date(Date.now() - options.maxAge * 24 * 60 * 60 * 1000)
    } : undefined
  };
  
  // Vector similarity search
  const results = await this.vectorStore.query(
    queryEmbedding,
    options.limit ?? 10,
    filter
  );
  
  // Update access count to reinforce recalled memories
  await this.reinforceMemories(results.map(r => r.id));
  
  return results;
}

async calculateImportance(
  content: string,
  metadata: Partial<Memory['metadata']>
): Promise<number> {
  let score = 0.5;  // base score
  
  // Emotional content is more important
  const emotionalKeywords = ['critical', 'urgent', 'error', 'success', 'failure', 'warning'];
  const emotionalScore = emotionalKeywords.filter(k => content.toLowerCase().includes(k)).length * 0.1;
  score += Math.min(emotionalScore, 0.3);
  
  // Longer content carries more information
  const lengthScore = Math.min(content.length / 1000, 0.2);
  score += lengthScore;
  
  // User explicitly asked to remember this
  if (metadata.tags?.includes('explicit_remember')) {
    score += 0.3;
  }
  
  return Math.min(score, 1.0);
}

async maintainMemoryHealth(): Promise<void> {
  const now = new Date();
  const allMemories = await this.db.query('SELECT * FROM memories');
  
  for (const memory of allMemories) {
    const daysSinceAccess = 
      (now.getTime() - memory.lastAccessed.getTime()) / (1000 * 60 * 60 * 24);
    
    // Forgetting curve: importance = initial_importance * e^(-decay_rate * days)
    const decayRate = memory.type === 'procedural' ? 0.005 : 0.02;
    const decayedImportance = memory.importance * Math.exp(-decayRate * daysSinceAccess);
    
    if (decayedImportance < 0.1) {
      // Archive low-importance memories
      await this.archiveMemory(memory.id);
    } else if (decayedImportance !== memory.importance) {
      // Update importance score
      await this.db.update('memories', memory.id, { importance: decayedImportance });
    }
  }
}

async consolidateMemories(): Promise<void> {
  // Cluster similar memories
  const episodicMemories = await this.db.query(
    'SELECT * FROM memories WHERE type = ? AND importance > ?',
    ['episodic', 0.5]
  );
  
  const clusters = await this.clusterSimilarMemories(episodicMemories);
  
  for (const cluster of clusters) {
    if (cluster.length >= 3) {
      // Generate semantic memory from multiple similar episodes
      const summary = await this.generateSemanticMemory(cluster);
      
      await this.storeMemory(
        summary,
        'semantic',
        { tags: ['consolidated', ...extractTags(cluster)], source: 'consolidation' }
      );
      
      // Reduce importance of source episodic memories
      for (const memory of cluster) {
        await this.db.update('memories', memory.id, { importance: memory.importance * 0.5 });
      }
    }
  }
}

async buildContextWithMemory(
  userMessage: string,
  userId: string
): Promise<string> {
  // 1. Retrieve relevant memories
  const relevantMemories = await this.recallMemories(userMessage, {
    limit: 10,
    minImportance: 0.3
  });
  
  // 2. Organize by memory type
  const episodicContext = relevantMemories
    .filter(m => m.type === 'episodic')
    .map(m => `[Past event] ${m.content}`)
    .join('\n');
    
  const semanticContext = relevantMemories
    .filter(m => m.type === 'semantic')
    .map(m => `[Learned knowledge] ${m.content}`)
    .join('\n');
    
  const proceduralContext = relevantMemories
    .filter(m => m.type === 'procedural')
    .map(m => `[Effective procedure] ${m.content}`)
    .join('\n');
  
  // 3. Embed context into system prompt
  return `
You have the following memories available:
 
## Relevant Past Events
${episodicContext || '(none)'}
 
## Learned Knowledge
${semanticContext || '(none)'}
 
## Effective Patterns and Procedures
${proceduralContext || '(none)'}
 
Using these memories as context, respond to the following:
${userMessage}
  `.trim();
}

async processConversationEnd(
  conversation: ConversationTurn[],
  userId: string
): Promise<void> {
  // Use LLM to extract important information from the conversation
  const extractionPrompt = `
Extract information from the following conversation that would be useful in future interactions.
For each piece of information, determine its type (episodic/semantic/procedural) and importance (0-1).
 
Conversation:
${conversation.map(t => `${t.role}: ${t.content}`).join('\n')}
 
Output in JSON format:
{
  "memories": [
    {"content": "...", "type": "...", "importance": 0.x}
  ]
}
  `;
  
  const extracted = await this.llm.complete(extractionPrompt);
  const { memories } = JSON.parse(extracted);
  
  for (const memory of memories) {
    await this.storeMemory(memory.content, memory.type, {
      userId,
      tags: ['auto_extracted']
    });
  }
}