Nodes and Edges - Graphiti

Graph Schema Overview

Graphiti’s knowledge graph is composed of nodes (entities, episodes, communities, sagas) and edges (relationships between nodes). Understanding this schema is essential for working with Graphiti effectively.

Node Types

EntityNode

Represents real-world entities extracted from episodes—people, organizations, concepts, events, etc.

class EntityNode(Node):
    uuid: str                          # Unique identifier
    name: str                          # Entity name
    name_embedding: list[float] | None # Vector embedding of the name
    summary: str                       # Aggregated summary from relationships
    labels: list[str]                  # Entity types (e.g., ["Person", "Employee"])
    attributes: dict[str, Any]         # Custom attributes
    group_id: str                      # Partition identifier
    created_at: datetime               # When first added to graph

Example

EntityNode(
    uuid="550e8400-e29b-41d4-a716-446655440000",
    name="Kamala Harris",
    labels=["Person", "Politician"],
    summary="Kamala Harris served as Attorney General of California from 2011-2017 and became Vice President in 2021.",
    attributes={
        "birth_year": 1964,
        "education": "Howard University, UC Hastings"
    },
    group_id="default",
    created_at=datetime(2024, 3, 15, tzinfo=timezone.utc)
)

Key Fields

name: The canonical name of the entity

Graphiti deduplicates entities by name similarity
Used for entity resolution across episodes

name_embedding: Vector representation for semantic search

Generated by your configured embedder (e.g., OpenAI, Voyage)
Enables similarity-based entity retrieval

# Generate embedding
await entity_node.generate_name_embedding(embedder)

summary: Automatically generated from connected edges

Aggregates facts from all EntityEdges connected to this node
Updated as new information is added
Useful for quick entity context

labels: Entity types for classification

Can be a single type: ["Person"]
Or multiple types: ["Person", "Executive", "Founder"]
Used with custom entity types (see Custom Entity Types guide)

attributes: Flexible key-value properties

Store domain-specific data
Defined by custom entity type schemas
Extracted by LLM during processing

# Custom entity type with attributes
from pydantic import BaseModel, Field

class Employee(BaseModel):
    department: str = Field(description="Department name")
    start_date: str = Field(description="Employment start date")
    role: str = Field(description="Job title")

entity_types = {"Employee": Employee}

Working with EntityNodes

# Get by UUID
node = await EntityNode.get_by_uuid(driver, uuid="...")

# Get by group IDs
nodes = await EntityNode.get_by_group_ids(
    driver,
    group_ids=["user_123"],
    limit=100
)

# Save a node
await node.save(driver)

# Delete a node (and connected edges)
await node.delete(driver)

EpisodicNode

Stores raw input episodes with temporal metadata. See Episodes for detailed information.

class EpisodicNode(Node):
    uuid: str
    name: str
    content: str                   # Raw episode data
    source: EpisodeType           # message | json | text
    source_description: str        # Metadata about the source
    valid_at: datetime            # When content occurred
    created_at: datetime          # When ingested
    entity_edges: list[str]       # UUIDs of extracted EntityEdges
    group_id: str

Example

EpisodicNode(
    uuid="660e8400-e29b-41d4-a716-446655440001",
    name="Customer Support Chat 2024-03-15",
    content="user: My order is delayed\nassistant: Let me check that",
    source=EpisodeType.message,
    source_description="support_ticket_5678",
    valid_at=datetime(2024, 3, 15, 10, 30, tzinfo=timezone.utc),
    created_at=datetime(2024, 3, 15, 10, 35, tzinfo=timezone.utc),
    entity_edges=["edge-uuid-1", "edge-uuid-2"],
    group_id="customer_123"
)

CommunityNode

Represents clusters of related entities discovered through graph analysis. See Communities for details.

class CommunityNode(Node):
    uuid: str
    name: str                         # Auto-generated description
    name_embedding: list[float] | None
    summary: str                      # Aggregate summary of member entities
    group_id: str
    created_at: datetime

Example

CommunityNode(
    uuid="770e8400-e29b-41d4-a716-446655440002",
    name="California Political Leadership",
    summary="Community of political figures who have served in California government positions including Governor, Attorney General, and Lieutenant Governor.",
    group_id="default",
    created_at=datetime(2024, 3, 15, tzinfo=timezone.utc)
)

SagaNode

Organizes sequences of related episodes (e.g., conversation threads, event timelines).

class SagaNode(Node):
    uuid: str
    name: str          # Saga identifier
    group_id: str
    created_at: datetime

Example

SagaNode(
    uuid="880e8400-e29b-41d4-a716-446655440003",
    name="customer_support_conversation_123",
    group_id="customer_456",
    created_at=datetime(2024, 3, 15, tzinfo=timezone.utc)
)

Edge Types

EntityEdge (RELATES_TO)

Represents semantic relationships between entities, with temporal validity tracking.

class EntityEdge(Edge):
    uuid: str
    source_node_uuid: str         # Source EntityNode UUID
    target_node_uuid: str         # Target EntityNode UUID
    name: str                     # Relationship name
    fact: str                     # Natural language fact
    fact_embedding: list[float] | None
    episodes: list[str]           # Episode UUIDs that mention this edge
    group_id: str
    
    # Temporal fields
    created_at: datetime          # When edge was first created
    expired_at: datetime | None   # When edge was invalidated by new info
    valid_at: datetime | None     # When the fact became true
    invalid_at: datetime | None   # When the fact stopped being true
    
    # Custom attributes
    attributes: dict[str, Any]

Example

EntityEdge(
    uuid="990e8400-e29b-41d4-a716-446655440004",
    source_node_uuid="kamala-harris-uuid",
    target_node_uuid="california-ag-uuid",
    name="held_position",
    fact="Kamala Harris served as Attorney General of California from January 2011 to January 2017.",
    fact_embedding=[0.123, -0.456, ...],  # 1536-dim vector
    episodes=["episode-uuid-1", "episode-uuid-2"],
    group_id="default",
    created_at=datetime(2024, 3, 15, tzinfo=timezone.utc),
    expired_at=None,  # Still current in the graph
    valid_at=datetime(2011, 1, 3, tzinfo=timezone.utc),
    invalid_at=datetime(2017, 1, 3, tzinfo=timezone.utc),
    attributes={"position_type": "elected_official"}
)

Key Fields

name: The relationship type

Examples: "works_at", "knows", "located_in", "married_to"
Can be customized with edge types (see Custom Edge Types guide)

fact: Human-readable description of the relationship

Used for search and retrieval
Embedded for semantic similarity

fact="Alice Chen joined Acme Corp as Senior Engineer in March 2024."

fact_embedding: Vector representation for semantic search

Generated from the fact text
Enables similarity-based edge retrieval

episodes: Provenance tracking

Lists all episodes that mentioned this relationship
Enables tracing back to original sources

# Find episodes that mention an edge
episode_uuids = edge.episodes
episodes = await EpisodicNode.get_by_uuids(driver, episode_uuids)

Temporal fields: See Temporal Model

valid_at: When the fact became true in the real world
invalid_at: When the fact stopped being true
created_at: When Graphiti learned about it
expired_at: When superseded by newer information

Working with EntityEdges

# Get by UUID
edge = await EntityEdge.get_by_uuid(driver, uuid="...")

# Get edges connected to a node
edges = await EntityEdge.get_by_node_uuid(driver, node_uuid="...")

# Get edges between two nodes
edges = await EntityEdge.get_between_nodes(
    driver,
    source_node_uuid="alice-uuid",
    target_node_uuid="acme-uuid"
)

# Save an edge
await edge.save(driver)

# Delete an edge
await edge.delete(driver)

EpisodicEdge (MENTIONS)

Links episodes to the entities they mention.

class EpisodicEdge(Edge):
    uuid: str
    source_node_uuid: str  # EpisodicNode UUID
    target_node_uuid: str  # EntityNode UUID
    group_id: str
    created_at: datetime

Purpose

EpisodicEdges provide provenance—you can always trace which episodes mentioned which entities.

# Find all episodes that mention "Alice"
episodes = await EpisodicNode.get_by_entity_node_uuid(
    driver,
    entity_node_uuid=alice.uuid
)

CommunityEdge (HAS_MEMBER)

Links communities to their member entities.

class CommunityEdge(Edge):
    uuid: str
    source_node_uuid: str  # CommunityNode UUID
    target_node_uuid: str  # EntityNode UUID
    group_id: str
    created_at: datetime

Usage

# Find all entities in a community
records, _, _ = await driver.execute_query("""
    MATCH (c:Community {uuid: $community_uuid})-[:HAS_MEMBER]->(e:Entity)
    RETURN e
""", community_uuid=community.uuid)

HasEpisodeEdge (HAS_EPISODE)

Links sagas to their episodes.

class HasEpisodeEdge(Edge):
    uuid: str
    source_node_uuid: str  # SagaNode UUID
    target_node_uuid: str  # EpisodicNode UUID
    group_id: str
    created_at: datetime

NextEpisodeEdge (NEXT_EPISODE)

Chains episodes in chronological order within a saga.

class NextEpisodeEdge(Edge):
    uuid: str
    source_node_uuid: str  # Earlier EpisodicNode UUID
    target_node_uuid: str  # Later EpisodicNode UUID
    group_id: str
    created_at: datetime

Usage

# Traverse a conversation thread
records, _, _ = await driver.execute_query("""
    MATCH path = (start:Episodic)-[:NEXT_EPISODE*]->(end:Episodic)
    WHERE start.uuid = $start_uuid
    RETURN path
""", start_uuid=first_episode.uuid)

Node and Edge Inheritance

All nodes and edges inherit from base classes:

class Node(BaseModel, ABC):
    uuid: str = Field(default_factory=lambda: str(uuid4()))
    name: str
    group_id: str
    labels: list[str] = Field(default_factory=list)
    created_at: datetime = Field(default_factory=lambda: utc_now())
    
    @abstractmethod
    async def save(self, driver: GraphDriver): ...
    async def delete(self, driver: GraphDriver): ...

class Edge(BaseModel, ABC):
    uuid: str = Field(default_factory=lambda: str(uuid4()))
    group_id: str
    source_node_uuid: str
    target_node_uuid: str
    created_at: datetime
    
    @abstractmethod
    async def save(self, driver: GraphDriver): ...
    async def delete(self, driver: GraphDriver): ...

This provides consistent interfaces for all graph elements.

Graph Queries

Finding Connected Information

# Get all relationships for an entity
edges = await EntityEdge.get_by_node_uuid(driver, node_uuid=alice.uuid)

# Find entities related to Alice
records, _, _ = await driver.execute_query("""
    MATCH (alice:Entity {uuid: $alice_uuid})-[:RELATES_TO]-(related:Entity)
    RETURN related
""", alice_uuid=alice.uuid)

Traversing Multi-Hop Relationships

# Find entities within 2 hops
records, _, _ = await driver.execute_query("""
    MATCH (start:Entity {uuid: $start_uuid})-[:RELATES_TO*1..2]-(connected:Entity)
    RETURN DISTINCT connected
""", start_uuid=start_node.uuid)

Temporal Queries

# Find facts valid at a specific time
records, _, _ = await driver.execute_query("""
    MATCH (n)-[e:RELATES_TO]->(m)
    WHERE e.valid_at <= $query_time
      AND (e.invalid_at > $query_time OR e.invalid_at IS NULL)
      AND e.expired_at IS NULL
    RETURN e
""", query_time=datetime(2023, 6, 1, tzinfo=timezone.utc))

Embeddings

Graphiti generates vector embeddings for semantic search:

Entity Name Embeddings

# Generate embedding for an entity
await entity_node.generate_name_embedding(embedder)
# Sets entity_node.name_embedding = [0.123, -0.456, ...]

# Batch generation for multiple entities
from graphiti_core.nodes import create_entity_node_embeddings

await create_entity_node_embeddings(embedder, entity_nodes)

Edge Fact Embeddings

# Generate embedding for an edge
await entity_edge.generate_embedding(embedder)
# Sets entity_edge.fact_embedding = [0.234, -0.567, ...]

# Batch generation for multiple edges
from graphiti_core.edges import create_entity_edge_embeddings

await create_entity_edge_embeddings(embedder, entity_edges)

Embedding Configuration

from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig

# Custom embedder
embedder = OpenAIEmbedder(
    config=OpenAIEmbedderConfig(
        embedding_model="text-embedding-3-large",
        embedding_dim=3072  # Dimension depends on model
    )
)

graphiti = Graphiti(uri, user, password, embedder=embedder)

Database Backend Differences

Graphiti supports multiple graph databases with minor schema variations:

Neo4j, FalkorDB, Neptune

-- EntityEdge as a relationship
MATCH (n:Entity)-[e:RELATES_TO]->(m:Entity)
RETURN e

Kuzu

-- EntityEdge as an intermediate node
MATCH (n:Entity)-[:RELATES_TO]->(e:RelatesToNode_)-[:RELATES_TO]->(m:Entity)
RETURN e

Graphiti’s driver abstraction handles these differences automatically. You don’t need to write different queries for different backends.

Custom Attributes

Both EntityNodes and EntityEdges support custom attributes:

from pydantic import BaseModel, Field

# Define a custom entity type
class Person(BaseModel):
    age: int = Field(description="Person's age")
    occupation: str = Field(description="Job title")
    city: str = Field(description="Current city")

# Define a custom edge type
class WorksAt(BaseModel):
    start_date: str = Field(description="Employment start date")
    department: str = Field(description="Department name")

# Use in add_episode
result = await graphiti.add_episode(
    name="HR Data",
    episode_body="Alice Chen, 32, works as a Software Engineer in the Platform team. She joined on 2024-01-15 in San Francisco.",
    source=EpisodeType.text,
    reference_time=datetime.now(timezone.utc),
    entity_types={"Person": Person},
    edge_types={"WorksAt": WorksAt}
)

# Extracted EntityNode will have:
# attributes = {"age": 32, "occupation": "Software Engineer", "city": "San Francisco"}

# Extracted EntityEdge will have:
# attributes = {"start_date": "2024-01-15", "department": "Platform"}

Group IDs and Multi-Tenancy

Every node and edge has a group_id field for partitioning:

# Add data to different groups
await graphiti.add_episode(
    name="User 1 Data",
    episode_body="Alice likes hiking.",
    group_id="user_1",
    reference_time=datetime.now(timezone.utc)
)

await graphiti.add_episode(
    name="User 2 Data",
    episode_body="Bob likes coding.",
    group_id="user_2",
    reference_time=datetime.now(timezone.utc)
)

# Search within a group
results = await graphiti.search(
    "What does the user like?",
    group_ids=["user_1"]  # Only searches user_1's data
)

Schema Visualization

Here’s the complete graph schema:

Next Steps

Communities

Learn about community detection and clustering

Custom Types

Define custom entity and edge types

Search

Query nodes and edges effectively

Temporal Model

Understand temporal aspects of nodes and edges

Get Started

Core Concepts

Guides

Integrations

Advanced

​Graph Schema Overview

​Node Types

​EntityNode

​Example

​Key Fields

​Working with EntityNodes

​EpisodicNode

​Example

​CommunityNode

​Example

​SagaNode

​Example

​Edge Types

​EntityEdge (RELATES_TO)

​Example

​Key Fields

​Working with EntityEdges

​EpisodicEdge (MENTIONS)

​Purpose

​CommunityEdge (HAS_MEMBER)

​Usage

​HasEpisodeEdge (HAS_EPISODE)

​NextEpisodeEdge (NEXT_EPISODE)

​Usage

​Node and Edge Inheritance

​Graph Queries

​Finding Connected Information

​Traversing Multi-Hop Relationships

​Temporal Queries

​Embeddings

​Entity Name Embeddings

​Edge Fact Embeddings

​Embedding Configuration

​Database Backend Differences

​Neo4j, FalkorDB, Neptune

​Kuzu

​Custom Attributes

​Group IDs and Multi-Tenancy

​Schema Visualization

​Next Steps

Communities

Custom Types

Search

Temporal Model

Build docs developers (and LLMs) love

Graph Schema Overview

Node Types

EntityNode

Example

Key Fields

Working with EntityNodes

EpisodicNode

Example

CommunityNode

Example

SagaNode

Example

Edge Types

EntityEdge (RELATES_TO)

Example

Key Fields

Working with EntityEdges

EpisodicEdge (MENTIONS)

Purpose

CommunityEdge (HAS_MEMBER)

Usage

HasEpisodeEdge (HAS_EPISODE)

NextEpisodeEdge (NEXT_EPISODE)

Usage

Node and Edge Inheritance

Graph Queries

Finding Connected Information

Traversing Multi-Hop Relationships

Temporal Queries

Embeddings

Entity Name Embeddings

Edge Fact Embeddings

Embedding Configuration

Database Backend Differences

Neo4j, FalkorDB, Neptune

Kuzu

Custom Attributes

Group IDs and Multi-Tenancy

Schema Visualization

Next Steps