Skip to main content

​
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 valueRaises: NotImplementedError - If the episode type string is not recognizedExample:
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}",
    ...
)

Build docs developers (and LLMs) love

Get started for freeTalk to us