Memory Tiers

Overview

Raven organizes memory into conceptual tiers based on access patterns, retention requirements, and storage characteristics. This tiered approach optimizes for both performance and cost.

Tier 1: Context Window

The context window is the LLM's active working memory. It's ephemeral and exists only during a single request/response cycle.

Tier 2: Core Memory

Fast-access storage for user profiles, session state, and frequently accessed data. Stored in Redis for sub-millisecond access.

// Buffer key pattern
tenant:{tenant_id}:user:{user_id}:conversation:{conv_id}:buffer

// Example: Store pending interaction
await redis.rpush(bufferKey, JSON.stringify(interaction));

// Example: Get buffer size
const size = await redis.llen(bufferKey);

Tier 3: Episodic Memory

Long-term storage of conversation history. Episodic memories are specific events - individual interactions between users and agents.

interface EpisodicMemory {
  blob_type: 'episodic';
  conversations: Array<{
    conversation_id: string;
    timestamp: string;
    user_message: string;
    agent_response: string;
    metadata?: Record<string, unknown>;
  }>;
}

Tier 4: Semantic Memory

Derived knowledge extracted from episodic memories. Includes facts, patterns, preferences, and vector embeddings for semantic search.

interface SemanticMemory {
  blob_type: 'semantic';
  extracted_facts: string[];       // "User prefers TypeScript"
  patterns: Array<{
    pattern: string;
    frequency: number;
    confidence: number;
  }>;
}

interface EmbeddingMemory {
  blob_type: 'embeddings';
  embeddings: Array<{
    text: string;
    vector: number[];
    metadata?: Record<string, unknown>;
  }>;
}

Storage Comparison

Memory Query Flow

When an agent queries for context, Raven searches across tiers:

Query: "What programming language does the user prefer?"
      ↓
1. Check Tier 2 (Core Memory)
   └─ Look for user preferences in Redis
      ↓
2. Search Tier 4 (Semantic Memory)
   └─ Query extracted facts: "User prefers TypeScript"
   └─ Semantic search on embeddings for similar concepts
      ↓
3. Search Tier 3 (Episodic Memory)
   └─ Find relevant conversation snippets
   └─ Rank by relevance and recency
      ↓
4. Assemble Context
   └─ Combine facts + relevant episodes
   └─ Return for injection into Tier 1 (Context Window)