Episodes¶

Episodes are the fundamental unit of knowledge ingestion in Aletheia. Each episode is a markdown document that Graphiti processes to extract entities and relationships.

What is an Episode?¶

An episode is:

• A markdown document describing one logical unit of information
• The input to Graphiti's extraction pipeline
• Optimized for LLM entity and relationship extraction

Episode Builder¶

Each use case provides an episode builder that converts parsed entities to markdown:

def build_episode(entity: MyEntity) -> str:
    """Convert entity to markdown episode."""
    return f"""
# Entity: {entity.name}

## Properties
- **Type**: {entity.type}
- **Created**: {entity.created_at}

## Description
{entity.description}

## Relationships
{format_relationships(entity.relationships)}
"""

Episode Structure Best Practices¶

1. Clear Entity Identification¶

Start with a clear header identifying the main entity:

# FollowTheMoney Entity: al-Shabaab

2. Structured Properties¶

Use markdown lists for structured data:

## Properties
- **Alias**: al-Hijra
- **Program Id**: US-FTO219
- **Topics**: sanction, crime.terror

3. Relationship Context¶

Include relationship context for edge extraction:

## Relationships
- SANCTIONED BY: US State Department
- ALLIED WITH: al-Qaeda

4. Natural Language Context¶

Add natural language for semantic understanding:

## Entity Context
This is a designated terrorist organization based in Somalia.
It has been sanctioned by multiple international authorities.

Registration¶

Episode builders are registered in the use case's __init__.py:

from aletheia.core.episodes import register_episode_builder
from .episode_builder import build_episode

register_episode_builder(
    "my_case",
    build_episode,
    source_description="My data source",
)

Graphiti Processing¶

When Graphiti processes an episode:

1. Entity Extraction: LLM identifies entities in the text
2. Relationship Extraction: LLM identifies relationships between entities
3. Entity Resolution: Similar entities are merged
4. Graph Update: Nodes and edges are created/updated

Learn More¶

• Use Cases - Use case architecture
• Graphiti Integration - How Graphiti processes episodes