AI Agent Memory: From Session Context to Long-Term Knowledge

npm install openai uuid
npm install -D typescript @types/node

interface Message {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: Date;
}
 
class WorkingMemory {
  private messages: Message[] = [];
  private maxMessages: number;
 
  constructor(maxMessages: number = 20) {
    this.maxMessages = maxMessages;
  }
 
  add(message: Message): void {
    this.messages.push(message);
    // Evict oldest messages when buffer is full
    if (this.messages.length > this.maxMessages) {
      this.messages = this.messages.slice(-this.maxMessages);
    }
  }
 
  getContext(): Message[] {
    return [...this.messages];
  }
 
  getTokenEstimate(): number {
    // Rough estimate: 1 token ≈ 4 characters
    return this.messages.reduce(
      (sum, m) => sum + Math.ceil(m.content.length / 4), 0
    );
  }
 
  clear(): void {
    this.messages = [];
  }
}

import { randomUUID } from 'crypto';
 
interface Episode {
  id: string;
  userId: string;
  sessionId: string;
  event: string;           // What happened
  context: string;         // Surrounding circumstances
  outcome?: string;        // How it resolved
  importance: number;      // 1-10 scale
  timestamp: Date;
  tags: string[];
  embedding?: number[];    // For semantic search (added later)
}
 
class EpisodicMemory {
  private episodes: Map<string, Episode[]> = new Map();
 
  async store(episode: Omit<Episode, 'id'>): Promise<string> {
    const id = randomUUID();
    const stored: Episode = { ...episode, id };
 
    const userEpisodes = this.episodes.get(episode.userId) || [];
    userEpisodes.push(stored);
    this.episodes.set(episode.userId, userEpisodes);
 
    return id;
  }
 
  // Retrieve by recency — most recent episodes first
  getRecent(userId: string, limit: number = 10): Episode[] {
    const episodes = this.episodes.get(userId) || [];
    return episodes
      .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime())
      .slice(0, limit);
  }
 
  // Retrieve by importance — highest importance first
  getMostImportant(userId: string, limit: number = 5): Episode[] {
    const episodes = this.episodes.get(userId) || [];
    return episodes
      .sort((a, b) => b.importance - a.importance)
      .slice(0, limit);
  }
 
  // Combined retrieval: weighted score of recency + importance
  getRelevant(
    userId: string,
    limit: number = 5,
    recencyWeight: number = 0.4,
    importanceWeight: number = 0.6
  ): Episode[] {
    const episodes = this.episodes.get(userId) || [];
    if (episodes.length === 0) return [];
 
    const now = Date.now();
    const maxAge = Math.max(
      ...episodes.map(e => now - e.timestamp.getTime())
    );
 
    return episodes
      .map(episode => {
        const age = now - episode.timestamp.getTime();
        const recencyScore = 1 - (age / (maxAge || 1));
        const importanceScore = episode.importance / 10;
        const score =
          recencyWeight * recencyScore +
          importanceWeight * importanceScore;
        return { episode, score };
      })
      .sort((a, b) => b.score - a.score)
      .slice(0, limit)
      .map(({ episode }) => episode);
  }
}

import OpenAI from 'openai';
 
interface SemanticMemory {
  id: string;
  userId: string;
  fact: string;              // The distilled knowledge
  confidence: number;        // 0-1, how certain we are
  source: string;            // Which episode(s) this came from
  category: string;          // preference, fact, behavior, relationship
  lastAccessed: Date;
  accessCount: number;
  createdAt: Date;
  updatedAt: Date;
}
 
class SemanticMemoryExtractor {
  private openai: OpenAI;
  private memories: Map<string, SemanticMemory[]> = new Map();
 
  constructor(apiKey: string) {
    this.openai = new OpenAI({ apiKey });
  }
 
  async extractFromConversation(
    userId: string,
    conversation: string,
    sessionId: string
  ): Promise<SemanticMemory[]> {
    const existing = this.memories.get(userId) || [];
    const existingFacts = existing.map(m => m.fact).join('\n');
 
    const response = await this.openai.chat.completions.create({
      model: 'gpt-4o',
      temperature: 0.1,
      response_format: { type: 'json_object' },
      messages: [
        {
          role: 'system',
          content: `Extract factual knowledge about the user from this conversation.
Return JSON: { "memories": [{ "fact": "...", "confidence": 0.0-1.0, "category": "preference|fact|behavior|relationship" }] }
 
Rules:
- Only extract information explicitly stated or strongly implied
- Confidence 0.9+ for direct statements, 0.5-0.8 for inferences
- Skip transient information (current mood, one-time requests)
- If a fact contradicts existing knowledge, include it with the updated information
 
Existing knowledge about this user:
${existingFacts || 'None yet'}`
        },
        { role: 'user', content: conversation }
      ]
    });
 
    const parsed = JSON.parse(
      response.choices[0].message.content || '{"memories":[]}'
    );
 
    const newMemories: SemanticMemory[] = parsed.memories.map(
      (m: { fact: string; confidence: number; category: string }) => ({
        id: randomUUID(),
        userId,
        fact: m.fact,
        confidence: m.confidence,
        source: sessionId,
        category: m.category,
        lastAccessed: new Date(),
        accessCount: 0,
        createdAt: new Date(),
        updatedAt: new Date(),
      })
    );
 
    // Merge with existing — update if contradicting, add if new
    this.mergeMemories(userId, newMemories);
 
    return newMemories;
  }
 
  private mergeMemories(
    userId: string,
    newMemories: SemanticMemory[]
  ): void {
    const existing = this.memories.get(userId) || [];
 
    for (const newMem of newMemories) {
      const conflict = existing.findIndex(
        e => e.category === newMem.category &&
             this.isContradiction(e.fact, newMem.fact)
      );
 
      if (conflict >= 0 && newMem.confidence > existing[conflict].confidence) {
        // Replace lower-confidence memory with higher-confidence one
        existing[conflict] = { ...newMem, updatedAt: new Date() };
      } else if (conflict < 0) {
        existing.push(newMem);
      }
    }
 
    this.memories.set(userId, existing);
  }
 
  private isContradiction(a: string, b: string): boolean {
    // Simplified — production systems use embedding similarity
    // to detect semantic overlap, then LLM to judge contradiction
    const normalize = (s: string) => s.toLowerCase().trim();
    return normalize(a).includes(normalize(b).split(' ')[0]);
  }
 
  getMemories(
    userId: string,
    category?: string
  ): SemanticMemory[] {
    const all = this.memories.get(userId) || [];
    if (category) {
      return all.filter(m => m.category === category);
    }
    return all;
  }
}

interface Procedure {
  id: string;
  name: string;
  description: string;
  steps: ProcedureStep[];
  successRate: number;
  timesUsed: number;
  context: string;         // When to apply this procedure
  lastUsed: Date;
  createdAt: Date;
}
 
interface ProcedureStep {
  action: string;
  parameters?: Record<string, unknown>;
  expectedOutcome: string;
  fallback?: string;       // What to do if this step fails
}
 
class ProceduralMemory {
  private procedures: Procedure[] = [];
 
  // Record a successful action sequence as a procedure
  recordProcedure(
    name: string,
    description: string,
    steps: ProcedureStep[],
    context: string
  ): Procedure {
    const existing = this.procedures.find(p => p.name === name);
 
    if (existing) {
      // Reinforce existing procedure
      existing.timesUsed++;
      existing.successRate =
        (existing.successRate * (existing.timesUsed - 1) + 1) /
        existing.timesUsed;
      existing.lastUsed = new Date();
      return existing;
    }
 
    const procedure: Procedure = {
      id: randomUUID(),
      name,
      description,
      steps,
      successRate: 1.0,
      timesUsed: 1,
      context,
      lastUsed: new Date(),
      createdAt: new Date(),
    };
 
    this.procedures.push(procedure);
    return procedure;
  }
 
  // Record a failure to adjust success rate
  recordFailure(procedureId: string): void {
    const proc = this.procedures.find(p => p.id === procedureId);
    if (proc) {
      proc.timesUsed++;
      proc.successRate =
        (proc.successRate * (proc.timesUsed - 1)) / proc.timesUsed;
    }
  }
 
  // Find the best procedure for a given context
  findProcedure(context: string): Procedure | null {
    // Simple keyword matching — production uses embedding similarity
    const candidates = this.procedures.filter(p =>
      context.toLowerCase().includes(p.context.toLowerCase()) ||
      p.context.toLowerCase().includes(context.toLowerCase())
    );
 
    if (candidates.length === 0) return null;
 
    // Prefer high success rate, then recency
    return candidates.sort((a, b) => {
      const scoreA = a.successRate * 0.7 +
        (a.lastUsed.getTime() / Date.now()) * 0.3;
      const scoreB = b.successRate * 0.7 +
        (b.lastUsed.getTime() / Date.now()) * 0.3;
      return scoreB - scoreA;
    })[0];
  }
 
  // Format procedure as instructions for the LLM
  toPromptInstructions(procedure: Procedure): string {
    const steps = procedure.steps
      .map((s, i) => `${i + 1}. ${s.action}${
        s.fallback ? ` (if this fails: ${s.fallback})` : ''
      }`)
      .join('\n');
 
    return `Recommended approach (${Math.round(procedure.successRate * 100)}% success rate, used ${procedure.timesUsed} times):
${procedure.description}
 
Steps:
${steps}`;
  }
}

class TokenAwareBuffer {
  private messages: Message[] = [];
  private maxTokens: number;
 
  constructor(maxTokens: number = 4000) {
    this.maxTokens = maxTokens;
  }
 
  add(message: Message): void {
    this.messages.push(message);
    this.trim();
  }
 
  private trim(): void {
    let totalTokens = this.estimateTokens(this.messages);
    while (totalTokens > this.maxTokens && this.messages.length > 1) {
      this.messages.shift();
      totalTokens = this.estimateTokens(this.messages);
    }
  }
 
  private estimateTokens(msgs: Message[]): number {
    return msgs.reduce(
      (sum, m) => sum + Math.ceil(m.content.length / 4) + 4, // +4 for role tokens
      0
    );
  }
 
  getMessages(): Message[] {
    return [...this.messages];
  }
}

class SummaryMemory {
  private recentMessages: Message[] = [];
  private summary: string = '';
  private maxRecentMessages: number;
  private openai: OpenAI;
 
  constructor(apiKey: string, maxRecentMessages: number = 10) {
    this.openai = new OpenAI({ apiKey });
    this.maxRecentMessages = maxRecentMessages;
  }
 
  async add(message: Message): Promise<void> {
    this.recentMessages.push(message);
 
    if (this.recentMessages.length > this.maxRecentMessages) {
      // Take the oldest messages and summarize them
      const toSummarize = this.recentMessages.splice(
        0,
        Math.floor(this.maxRecentMessages / 2)
      );
      await this.updateSummary(toSummarize);
    }
  }
 
  private async updateSummary(messages: Message[]): Promise<void> {
    const conversation = messages
      .map(m => `${m.role}: ${m.content}`)
      .join('\n');
 
    const response = await this.openai.chat.completions.create({
      model: 'gpt-4o-mini',  // Cheaper model for summarization
      temperature: 0,
      messages: [
        {
          role: 'system',
          content: `Progressively summarize the conversation, adding to the existing summary.
Include: key facts, user preferences, unresolved issues, action items, and any commitments made.
Be concise but don't drop important details.`
        },
        {
          role: 'user',
          content: `Existing summary:\n${this.summary || '(none yet)'}\n\nNew messages:\n${conversation}`
        }
      ]
    });
 
    this.summary = response.choices[0].message.content || this.summary;
  }
 
  getContext(): { summary: string; recentMessages: Message[] } {
    return {
      summary: this.summary,
      recentMessages: [...this.recentMessages],
    };
  }
 
  // Format for injection into LLM prompt
  toPromptContext(): string {
    const parts: string[] = [];
 
    if (this.summary) {
      parts.push(`Previous conversation summary:\n${this.summary}`);
    }
 
    if (this.recentMessages.length > 0) {
      parts.push('Recent messages:');
      for (const msg of this.recentMessages) {
        parts.push(`${msg.role}: ${msg.content}`);
      }
    }
 
    return parts.join('\n\n');
  }
}

class VectorMemoryStore {
  private entries: Array<{
    id: string;
    text: string;
    embedding: number[];
    metadata: Record<string, unknown>;
    timestamp: Date;
  }> = [];
  private openai: OpenAI;
 
  constructor(apiKey: string) {
    this.openai = new OpenAI({ apiKey });
  }
 
  async store(
    text: string,
    metadata: Record<string, unknown> = {}
  ): Promise<string> {
    const embedding = await this.embed(text);
    const id = randomUUID();
 
    this.entries.push({
      id,
      text,
      embedding,
      metadata,
      timestamp: new Date(),
    });
 
    return id;
  }
 
  async search(
    query: string,
    topK: number = 5,
    filter?: (meta: Record<string, unknown>) => boolean
  ): Promise<Array<{ text: string; score: number; metadata: Record<string, unknown> }>> {
    const queryEmbedding = await this.embed(query);
 
    let candidates = this.entries;
    if (filter) {
      candidates = candidates.filter(e => filter(e.metadata));
    }
 
    const scored = candidates.map(entry => ({
      text: entry.text,
      score: this.cosineSimilarity(queryEmbedding, entry.embedding),
      metadata: entry.metadata,
    }));
 
    return scored
      .sort((a, b) => b.score - a.score)
      .slice(0, topK);
  }
 
  private async embed(text: string): Promise<number[]> {
    const response = await this.openai.embeddings.create({
      model: 'text-embedding-3-small',
      input: text,
    });
    return response.data[0].embedding;
  }
 
  private cosineSimilarity(a: number[], b: number[]): number {
    let dot = 0, normA = 0, normB = 0;
    for (let i = 0; i < a.length; i++) {
      dot += a[i] * b[i];
      normA += a[i] * a[i];
      normB += b[i] * b[i];
    }
    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
  }
 
  // Decay old memories — reduce their retrieval priority over time
  applyDecay(halfLifeDays: number = 30): void {
    const now = Date.now();
    for (const entry of this.entries) {
      const ageDays =
        (now - entry.timestamp.getTime()) / (1000 * 60 * 60 * 24);
      const decayFactor = Math.pow(0.5, ageDays / halfLifeDays);
      // Store decay factor in metadata for retrieval scoring
      entry.metadata._decayFactor = decayFactor;
    }
  }
}

interface MemoryContext {
  workingMemory: Message[];
  relevantEpisodes: Episode[];
  semanticFacts: SemanticMemory[];
  suggestedProcedure: Procedure | null;
  summary: string;
}
 
class UnifiedMemoryManager {
  private working: WorkingMemory;
  private episodic: EpisodicMemory;
  private semantic: SemanticMemoryExtractor;
  private procedural: ProceduralMemory;
  private vectorStore: VectorMemoryStore;
  private summaryMemory: SummaryMemory;
 
  constructor(apiKey: string) {
    this.working = new WorkingMemory(20);
    this.episodic = new EpisodicMemory();
    this.semantic = new SemanticMemoryExtractor(apiKey);
    this.procedural = new ProceduralMemory();
    this.vectorStore = new VectorMemoryStore(apiKey);
    this.summaryMemory = new SummaryMemory(apiKey);
  }
 
  // Called on every user message
  async processMessage(
    userId: string,
    sessionId: string,
    message: Message
  ): Promise<void> {
    // Update working memory
    this.working.add(message);
 
    // Update summary
    await this.summaryMemory.add(message);
 
    // Store in vector memory for future retrieval
    await this.vectorStore.store(message.content, {
      userId,
      sessionId,
      role: message.role,
      timestamp: message.timestamp.toISOString(),
    });
  }
 
  // Build full context for LLM prompt
  async buildContext(
    userId: string,
    currentQuery: string
  ): Promise<MemoryContext> {
    // Parallel retrieval for speed
    const [vectorResults, episodes, facts] = await Promise.all([
      this.vectorStore.search(currentQuery, 5, (meta) =>
        meta.userId === userId
      ),
      Promise.resolve(this.episodic.getRelevant(userId, 3)),
      Promise.resolve(this.semantic.getMemories(userId)),
    ]);
 
    // Find applicable procedure
    const procedure = this.procedural.findProcedure(currentQuery);
 
    const { summary, recentMessages } = this.summaryMemory.getContext();
 
    return {
      workingMemory: recentMessages,
      relevantEpisodes: episodes,
      semanticFacts: facts,
      suggestedProcedure: procedure,
      summary,
    };
  }
 
  // Format context for injection into system prompt
  formatForPrompt(context: MemoryContext): string {
    const sections: string[] = [];
 
    if (context.summary) {
      sections.push(
        `## Conversation History\n${context.summary}`
      );
    }
 
    if (context.semanticFacts.length > 0) {
      const facts = context.semanticFacts
        .map(f => `- ${f.fact} (confidence: ${f.confidence})`)
        .join('\n');
      sections.push(`## What You Know About This User\n${facts}`);
    }
 
    if (context.relevantEpisodes.length > 0) {
      const episodes = context.relevantEpisodes
        .map(e => `- [${e.timestamp.toLocaleDateString()}] ${e.event}${
          e.outcome ? ` → ${e.outcome}` : ''
        }`)
        .join('\n');
      sections.push(`## Relevant Past Interactions\n${episodes}`);
    }
 
    if (context.suggestedProcedure) {
      sections.push(
        `## Suggested Approach\n${this.procedural.toPromptInstructions(
          context.suggestedProcedure
        )}`
      );
    }
 
    return sections.join('\n\n');
  }
 
  // End-of-session consolidation
  async consolidateSession(
    userId: string,
    sessionId: string,
    conversation: string
  ): Promise<void> {
    // Extract semantic memories from the full conversation
    await this.semantic.extractFromConversation(
      userId,
      conversation,
      sessionId
    );
 
    // Store key events as episodes
    // (In production, use LLM to identify notable events)
    await this.episodic.store({
      userId,
      sessionId,
      event: `Conversation session ${sessionId}`,
      context: conversation.slice(0, 500),
      importance: 5,
      timestamp: new Date(),
      tags: ['conversation'],
    });
 
    // Clear working memory
    this.working.clear();
  }
}

interface RetrievalResult {
  text: string;
  score: number;
  source: 'rag' | 'memory';
  metadata: Record<string, unknown>;
}
 
async function hybridRetrieval(
  query: string,
  userId: string,
  ragStore: VectorMemoryStore,
  memoryStore: VectorMemoryStore,
  options: {
    ragTopK?: number;
    memoryTopK?: number;
    ragWeight?: number;
    memoryWeight?: number;
  } = {}
): Promise<RetrievalResult[]> {
  const {
    ragTopK = 3,
    memoryTopK = 3,
    ragWeight = 0.5,
    memoryWeight = 0.5,
  } = options;
 
  const [ragResults, memResults] = await Promise.all([
    ragStore.search(query, ragTopK),
    memoryStore.search(query, memoryTopK, (meta) =>
      meta.userId === userId
    ),
  ]);
 
  const combined: RetrievalResult[] = [
    ...ragResults.map(r => ({
      ...r,
      score: r.score * ragWeight,
      source: 'rag' as const,
    })),
    ...memResults.map(r => ({
      ...r,
      score: r.score * memoryWeight,
      source: 'memory' as const,
    })),
  ];
 
  // Sort by weighted score, interleave sources
  return combined.sort((a, b) => b.score - a.score);
}

interface ConsolidationResult {
  newFacts: SemanticMemory[];
  updatedFacts: SemanticMemory[];
  episodes: Episode[];
  procedures: Procedure[];
}
 
class MemoryConsolidator {
  private openai: OpenAI;
 
  constructor(apiKey: string) {
    this.openai = new OpenAI({ apiKey });
  }
 
  async consolidate(
    userId: string,
    sessionId: string,
    transcript: string,
    existingFacts: SemanticMemory[]
  ): Promise<ConsolidationResult> {
    const response = await this.openai.chat.completions.create({
      model: 'gpt-4o',
      temperature: 0.1,
      response_format: { type: 'json_object' },
      messages: [
        {
          role: 'system',
          content: `Analyze this conversation and extract structured memory.
 
Return JSON with:
{
  "facts": [{ "text": "...", "confidence": 0-1, "category": "preference|fact|behavior", "updates": "id-of-existing-fact-if-updating|null" }],
  "episodes": [{ "event": "...", "importance": 1-10, "outcome": "..." }],
  "procedures": [{ "name": "...", "description": "...", "steps": ["step1", "step2"], "context": "when-to-use" }]
}
 
Existing facts about this user:
${existingFacts.map(f => `[${f.id}] ${f.fact}`).join('\n') || 'None'}
 
Rules:
- Update existing facts when new information supersedes them
- Only extract episodes that are noteworthy (importance >= 5)
- Only extract procedures from successful resolution patterns
- Confidence 0.9+ for explicit statements, 0.5-0.8 for inferences`
        },
        { role: 'user', content: transcript }
      ]
    });
 
    const parsed = JSON.parse(
      response.choices[0].message.content || '{}'
    );
 
    // Transform into typed results
    const result: ConsolidationResult = {
      newFacts: [],
      updatedFacts: [],
      episodes: [],
      procedures: [],
    };
 
    for (const fact of parsed.facts || []) {
      const memory: SemanticMemory = {
        id: fact.updates || randomUUID(),
        userId,
        fact: fact.text,
        confidence: fact.confidence,
        source: sessionId,
        category: fact.category,
        lastAccessed: new Date(),
        accessCount: 0,
        createdAt: new Date(),
        updatedAt: new Date(),
      };
 
      if (fact.updates) {
        result.updatedFacts.push(memory);
      } else {
        result.newFacts.push(memory);
      }
    }
 
    for (const ep of parsed.episodes || []) {
      result.episodes.push({
        id: randomUUID(),
        userId,
        sessionId,
        event: ep.event,
        context: transcript.slice(0, 200),
        outcome: ep.outcome,
        importance: ep.importance,
        timestamp: new Date(),
        tags: [],
      });
    }
 
    return result;
  }
}

interface ScoredMemory {
  content: string;
  recencyScore: number;
  importanceScore: number;
  relevanceScore: number;
  finalScore: number;
  source: 'episodic' | 'semantic' | 'vector';
}
 
function scoreMemories(
  candidates: Array<{
    content: string;
    timestamp: Date;
    importance: number;       // 1-10
    similarityScore: number;  // 0-1 (from vector search)
    source: 'episodic' | 'semantic' | 'vector';
  }>,
  weights: {
    recency: number;
    importance: number;
    relevance: number;
  } = { recency: 0.3, importance: 0.3, relevance: 0.4 }
): ScoredMemory[] {
  const now = Date.now();
 
  // Find the range of timestamps for normalization
  const timestamps = candidates.map(c => c.timestamp.getTime());
  const oldest = Math.min(...timestamps);
  const newest = Math.max(...timestamps);
  const timeRange = newest - oldest || 1;
 
  return candidates
    .map(candidate => {
      // Recency: exponential decay, most recent = 1.0
      const age = now - candidate.timestamp.getTime();
      const recencyScore = Math.exp(-age / (7 * 24 * 60 * 60 * 1000)); // 7-day half-life
 
      // Importance: normalize to 0-1
      const importanceScore = candidate.importance / 10;
 
      // Relevance: already 0-1 from vector similarity
      const relevanceScore = candidate.similarityScore;
 
      const finalScore =
        weights.recency * recencyScore +
        weights.importance * importanceScore +
        weights.relevance * relevanceScore;
 
      return {
        content: candidate.content,
        recencyScore,
        importanceScore,
        relevanceScore,
        finalScore,
        source: candidate.source,
      };
    })
    .sort((a, b) => b.finalScore - a.finalScore);
}

type MemoryTier = 'transient' | 'short-term' | 'long-term' | 'never-store';
 
interface MemoryClassification {
  tier: MemoryTier;
  retentionDays: number | null;  // null = until explicit deletion
  requiresConsent: boolean;
  piiCategory?: string;
}
 
function classifyForStorage(content: string): MemoryClassification {
  // Tier 1: Never store — sensitive PII, health, financial details
  const neverStorePatterns = [
    /\b\d{3}-?\d{2}-?\d{4}\b/,              // SSN
    /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b/, // Credit card
    /\b(?:password|ssn|social security)\b/i,
  ];
 
  if (neverStorePatterns.some(p => p.test(content))) {
    return {
      tier: 'never-store',
      retentionDays: 0,
      requiresConsent: false,
      piiCategory: 'sensitive',
    };
  }
 
  // Tier 2: Transient — current session only
  const transientPatterns = [
    /\b(?:hold on|one moment|let me check)\b/i,
    /\b(?:yes|no|okay|sure|thanks)\b/i,
  ];
 
  if (transientPatterns.some(p => p.test(content)) && content.length < 50) {
    return {
      tier: 'transient',
      retentionDays: 1,
      requiresConsent: false,
    };
  }
 
  // Tier 3: Short-term — operational retention (30-90 days)
  // Default for conversation content not matching other categories
  return {
    tier: 'short-term',
    retentionDays: 90,
    requiresConsent: false,
  };
}

class PrivacyAwareMemoryStore {
  private store: VectorMemoryStore;
 
  constructor(apiKey: string) {
    this.store = new VectorMemoryStore(apiKey);
  }
 
  async storeWithConsent(
    text: string,
    userId: string,
    consentBasis: 'explicit' | 'legitimate-interest' | 'contract',
    retentionDays: number
  ): Promise<string> {
    const classification = classifyForStorage(text);
 
    if (classification.tier === 'never-store') {
      // Log the rejection for audit, don't store the content
      console.log(`Rejected storage: sensitive content detected for user ${userId}`);
      return 'rejected';
    }
 
    const expiresAt = new Date();
    expiresAt.setDate(
      expiresAt.getDate() +
      Math.min(retentionDays, classification.retentionDays || retentionDays)
    );
 
    return this.store.store(text, {
      userId,
      consentBasis,
      retentionDays,
      expiresAt: expiresAt.toISOString(),
      storedAt: new Date().toISOString(),
    });
  }
 
  // Honor right to erasure — delete ALL memories for a user
  async deleteUserMemories(userId: string): Promise<number> {
    // In production, this queries the vector DB with a metadata filter
    // and deletes all matching entries
    let deleted = 0;
    // ... deletion logic against your vector database
    return deleted;
  }
 
  // Automated retention enforcement — run daily
  async enforceRetention(): Promise<number> {
    const now = new Date().toISOString();
    // Delete all entries where expiresAt < now
    let expired = 0;
    // ... expiration logic against your vector database
    return expired;
  }
}

interface MemoryAuditEntry {
  action: 'create' | 'read' | 'update' | 'delete';
  memoryId: string;
  userId: string;
  agentId: string;
  sessionId: string;
  timestamp: Date;
  reason: string;
  metadata?: Record<string, unknown>;
}