> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# Episodes

> Episode types and the EpisodeType enum for processing different data sources in Graphiti

# Episodes

Episodes are the fundamental units of input data in Graphiti. They represent events, messages, documents, or other temporal data that gets processed and integrated into the knowledge graph.

## EpisodeType Enum

The `EpisodeType` enum defines the various sources or formats of episodes that Graphiti can handle. The type determines how the episode content should be interpreted and processed.

### Enum Values

<ParamField path="message" type="str" value="'message'">
  Represents a standard message-type episode. The content for this type should be formatted as `"actor: content"`.

  **Examples:**

  * `"user: Hello, how are you?"`
  * `"assistant: I'm doing well, thank you for asking."`
  * `"system: User logged in at 10:30 AM"`
</ParamField>

<ParamField path="json" type="str" value="'json'">
  Represents an episode containing a JSON string object with structured data.

  **Use cases:**

  * API responses
  * Structured event data
  * Configuration snapshots
  * Telemetry data
</ParamField>

<ParamField path="text" type="str" value="'text'">
  Represents a plain text episode without special formatting requirements.

  **Use cases:**

  * Document content
  * Unstructured narratives
  * Raw text data
  * Notes or transcripts
</ParamField>

### Methods

<ResponseField name="from_str" type="static method">
  Converts a string to the corresponding EpisodeType enum value.

  **Parameters:**

  * `episode_type: str` - String representation of the episode type ("message", "json", or "text")

  **Returns:** `EpisodeType` - The corresponding enum value

  **Raises:** `NotImplementedError` - If the episode type string is not recognized

  **Example:**

  ```python theme={null}
  episode_type = EpisodeType.from_str("message")
  # Returns: EpisodeType.message
  ```
</ResponseField>

## Episode Content Formatting

### Message Type

For `EpisodeType.message`, content must follow the actor-content format:

```python theme={null}
from graphiti_core.nodes import EpisodicNode, EpisodeType
from datetime import datetime

episode = EpisodicNode(
    name="User Greeting",
    group_id="conversation-123",
    source=EpisodeType.message,
    source_description="Chat conversation",
    content="user: Hello, I need help with my account",
    valid_at=datetime.now()
)
```

### JSON Type

For `EpisodeType.json`, content should be a JSON string:

```python theme={null}
import json

event_data = {
    "event": "purchase",
    "user_id": "user-456",
    "product": "Premium Plan",
    "amount": 99.99
}

episode = EpisodicNode(
    name="Purchase Event",
    group_id="events-123",
    source=EpisodeType.json,
    source_description="E-commerce events",
    content=json.dumps(event_data),
    valid_at=datetime.now()
)
```

### Text Type

For `EpisodeType.text`, content can be any plain text:

```python theme={null}
episode = EpisodicNode(
    name="Meeting Notes",
    group_id="meetings-123",
    source=EpisodeType.text,
    source_description="Team meeting transcripts",
    content="""The team discussed the new feature roadmap.
Key decisions: prioritize mobile app, delay desktop updates.
Action items: John to create designs, Sarah to update timeline.""",
    valid_at=datetime.now()
)
```

## Episode Processing

When episodes are added to Graphiti, they undergo several processing steps:

1. **Content Extraction** - The episode content is parsed based on its type
2. **Entity Extraction** - Named entities are identified in the content
3. **Relationship Extraction** - Relationships between entities are detected
4. **Graph Integration** - New nodes and edges are created or existing ones updated
5. **Temporal Tracking** - The `valid_at` timestamp is used for temporal queries

## Working with Episodes

### Adding Episodes

Episodes are typically added through the main Graphiti interface:

```python theme={null}
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType

graphiti = Graphiti(...)

# Add a single episode
await graphiti.add_episode(
    name="User Inquiry",
    episode_body="user: What features are included in the Pro plan?",
    source_description="Customer support chat",
    episode_type=EpisodeType.message
)
```

### Retrieving Episodes

Episodes can be retrieved using the `EpisodicNode` class methods:

```python theme={null}
from graphiti_core.nodes import EpisodicNode

# Get a specific episode
episode = await EpisodicNode.get_by_uuid(driver, "episode-uuid-here")

# Get all episodes in a group
episodes = await EpisodicNode.get_by_group_ids(
    driver,
    group_ids=["conversation-123"],
    limit=10
)

# Get episodes that mention a specific entity
episodes = await EpisodicNode.get_by_entity_node_uuid(
    driver,
    entity_node_uuid="entity-uuid-here"
)
```

### Episode Relationships

Episodes form several types of relationships in the graph:

* **MENTIONS edges** - Connect episodes to the entities they reference (see `EpisodicEdge`)
* **NEXT\_EPISODE edges** - Chain episodes in temporal sequence (see `NextEpisodeEdge`)
* **HAS\_EPISODE edges** - Group episodes into sagas (see `HasEpisodeEdge`)

## Episode Metadata

Beyond the core fields, episodes track important metadata:

<ParamField path="entity_edges" type="list[str]">
  UUIDs of entity edges (relationships) that were extracted from this episode. This links the episode to the facts it contributed to the knowledge graph.
</ParamField>

<ParamField path="valid_at" type="datetime">
  The timestamp when the episode occurred or when the document was created. This is crucial for temporal queries and understanding the evolution of the knowledge graph over time.
</ParamField>

<ParamField path="source_description" type="str">
  Human-readable description of where the episode came from (e.g., "Slack conversation", "Email thread", "Meeting transcript"). Helps track data provenance.
</ParamField>

## Best Practices

### Choose the Right Type

* Use `EpisodeType.message` for conversational data where actor context is important
* Use `EpisodeType.json` for structured data that should preserve its schema
* Use `EpisodeType.text` for unstructured documents and narratives

### Provide Meaningful Timestamps

Set `valid_at` to the actual time the event occurred, not when it was ingested:

```python theme={null}
# Good: Use the actual event time
episode = EpisodicNode(
    valid_at=datetime.fromisoformat("2024-01-15T14:30:00Z"),
    ...
)

# Avoid: Using current time for historical data
episode = EpisodicNode(
    valid_at=datetime.now(),  # Wrong if processing historical data
    ...
)
```

### Use Descriptive Names and Sources

```python theme={null}
# Good: Descriptive and specific
episode = EpisodicNode(
    name="Q4 Budget Planning Discussion",
    source_description="Finance team Slack channel #budget-2024",
    ...
)

# Avoid: Vague descriptions
episode = EpisodicNode(
    name="Episode 1",
    source_description="Chat",
    ...
)
```

### Maintain Consistent Group IDs

Use consistent `group_id` values to logically partition your knowledge graph:

```python theme={null}
# Group by conversation, project, user, or domain
episode = EpisodicNode(
    group_id=f"project-{project_id}",
    ...
)
```

## Related

* [EpisodicNode](/api/nodes#episodicnode) - The node type representing episodes
* [EpisodicEdge](/api/edges#episodicedge) - Edges connecting episodes to entities
* [Adding Episodes Guide](/guides/adding-episodes) - Comprehensive guide to adding episodes
* [Temporal Model](/concepts/temporal-model) - Understanding time in Graphiti