Episodic Memory

​

The Ingestion Pipeline

​

Data Mapping: SDK to Server

• Producer Mapping: The SDK’s producer field is mapped to the internal producer_id.
• Role Assignment: Validates the producer_role (e.g., “user”, “assistant”).
• Timestamp Normalization: Converts various incoming date formats into a standardized AwareDatetime (UTC).
• Metadata Casting: Raw JSON payloads are cast to dict[str, JsonValue] for storage compatibility.

​

Memory Configuration

​

1. Short-Term Memory (STM)

• Responsibility: Manages the immediate context window.
• Server Logic: Controls the retrieval of the most recent N episodes to provide “sliding window” context for LLM prompts.
• Operations: configure_short_term_memory allows the server to toggle STM usage or adjust window sizes.

​

2. Long-Term Memory (LTM)

• Responsibility: Manages the persistent, vector-indexed history of a session.
• Server Logic: Handles the “summarization” loop, where older episodic memories are condensed to save space while retaining semantic meaning.
• Operations: configure_long_term_memory enables or disables the backend vector-search retrieval for historical context.

​

Internal Server Classes

​

EpisodicMemoryParams

​

EpisodeEntry (Internal Model)

# Internal server-side structure
class EpisodeEntry:
    content: str
    producer_id: str
    produced_for_id: str
    producer_role: str
    created_at: datetime
    metadata: dict[str, JsonValue]
    episode_type: EpisodeType # Defaults to MESSAGE

​

Lifecycle Management

1. Creation: When an API request arrives for a new session, the EpisodicMemoryManager instantiates the episodic sub-system.
2. Reference Counting: The server tracks how many active requests are utilizing a specific session instance.
3. Cleanup: Once the reference count drops to zero and the max_life_time is exceeded, the server flushes caches and closes database connections to conserve resources.