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

message · str

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"

json · str

Represents an episode containing a JSON string object with structured data.

Use cases:

• API responses
• Structured event data
• Configuration snapshots
• Telemetry data

text · str

Represents a plain text episode without special formatting requirements.

Use cases:

• Document content
• Unstructured narratives
• Raw text data
• Notes or transcripts

Methods

from_str · 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:

episode_type = EpisodeType.from_str("message")
# Returns: EpisodeType.message

Episode Content Formatting

Message Type

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

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:

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:

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:

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:

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:

entity_edges · 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.

valid_at · 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.

source_description · str

Human-readable description of where the episode came from (e.g., “Slack conversation”, “Email thread”, “Meeting transcript”). Helps track data provenance.

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:

# 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

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

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

Related

• EpisodicNode - The node type representing episodes
• EpisodicEdge - Edges connecting episodes to entities
• Adding Episodes Guide - Comprehensive guide to adding episodes
• Temporal Model - Understanding time in Graphiti