> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memmachine.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Episodic Memory

> Server-side implementation of session-based conversational memory.

The **Episodic Memory** module manages the "stream" of interactions for a specific session. It orchestrates the flow of data between the incoming API requests and the underlying vector and relational databases.

## The Ingestion Pipeline

When the server receives an `AddMemoriesSpec` from the SDK, it triggers a transformation pipeline within the service layer.

### Data Mapping: SDK to Server

The server maps the high-level `MemoryMessage` from the client into a persistent **`EpisodeEntry`**. This process includes:

* **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

The server allows for granular control over how episodic data is handled through two distinct sub-modules:

### 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`

This dataclass defines the environment for a memory instance.

| Attribute           | Type              | Description                                                |
| :------------------ | :---------------- | :--------------------------------------------------------- |
| `session_key`       | `str`             | The `{org_id}/{project_id}` unique identifier.             |
| `long_term_memory`  | `LongTermMemory`  | The backend vector store instance for this session.        |
| `short_term_memory` | `ShortTermMemory` | The backend relational/cache store for the context window. |
| `metrics_factory`   | `MetricsFactory`  | Telemetry provider for monitoring ingestion rates.         |

### `EpisodeEntry` (Internal Model)

Unlike the SDK's `Episode`, the server's `EpisodeEntry` includes internal tracking fields:

```python theme={null}
# 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

Episodic memory instances are **stateful** but **cached**.

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.