Edge Types
Graphiti uses five edge types to represent different kinds of relationships in the knowledge graph. All edges inherit from the baseEdge class and share common fields for identification, grouping, and timestamps.
Base Edge
The abstract base class that all edge types inherit from.str
required
Unique identifier for the edge. Automatically generated using UUID4 if not provided.
str
required
Partition identifier for the graph. Used to organize edges into logical groups or namespaces.
str
required
UUID of the source node in this relationship.
str
required
UUID of the target node in this relationship.
datetime
required
Timestamp of when the edge was created.
EntityEdge
Represents aRELATES_TO relationship between two entity nodes, containing a fact about their relationship.
Fields
Inherits all fields fromEdge, plus:
str
required
Name of the edge, describing the relation type (e.g., “works_at”, “located_in”, “friend_of”).
str
required
A factual statement representing the edge and the nodes it connects. This is the semantic content of the relationship.
list[float] | None
Vector embedding of the fact, used for semantic similarity searches. Generated using the configured embedder client.
list[str]
List of episode UUIDs that reference or mention this entity edge. Default: empty list.
datetime | None
Timestamp of when the edge was invalidated or marked as expired.
datetime | None
Timestamp of when the fact became true or valid.
datetime | None
Timestamp of when the fact stopped being true.
dict[str, Any]
Additional attributes of the edge. Content depends on the edge name and can store custom properties. Default: empty dict.
Methods
async method
Generates and stores the fact embedding for this edge.Parameters:
embedder: EmbedderClient- The embedder client to use for generating embeddings
list[float] - The generated embedding vectorasync method
Loads the fact embedding from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
EdgeNotFoundError if the edge doesn’t existasync method
Persists the entity edge to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
async classmethod
Retrieves a single entity edge by UUID.Parameters:
driver: GraphDriveruuid: str
EntityEdgeRaises: EdgeNotFoundError if not foundasync classmethod
Retrieves multiple entity edges by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[EntityEdge]async classmethod
Retrieves all entity edges between two specific nodes.Parameters:
driver: GraphDriversource_node_uuid: str- UUID of the source entity nodetarget_node_uuid: str- UUID of the target entity node
list[EntityEdge]async classmethod
Retrieves all entity edges connected to a specific node.Parameters:
driver: GraphDrivernode_uuid: str- UUID of the entity node
list[EntityEdge]async classmethod
Retrieves entity edges by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)with_embeddings: bool- Whether to include embeddings (default: False)
list[EntityEdge]Raises: GroupsEdgesNotFoundError if no edges foundEpisodicEdge
Represents aMENTIONS relationship from an episodic node to an entity node, indicating that the episode mentions the entity.
Fields
Inherits all fields fromEdge with no additional fields.
Methods
async method
Persists the episodic edge to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
async classmethod
Retrieves a single episodic edge by UUID.Parameters:
driver: GraphDriveruuid: str
EpisodicEdgeRaises: EdgeNotFoundError if not foundasync classmethod
Retrieves multiple episodic edges by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[EpisodicEdge]Raises: EdgeNotFoundError if not foundasync classmethod
Retrieves episodic edges by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[EpisodicEdge]Raises: GroupsEdgesNotFoundError if no edges foundCommunityEdge
Represents aHAS_MEMBER relationship from a community node to an entity node, indicating that the entity is a member of the community.
Fields
Inherits all fields fromEdge with no additional fields.
Methods
async method
Persists the community edge to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
async classmethod
Retrieves a single community edge by UUID.Parameters:
driver: GraphDriveruuid: str
CommunityEdgeasync classmethod
Retrieves multiple community edges by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[CommunityEdge]async classmethod
Retrieves community edges by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[CommunityEdge]HasEpisodeEdge
Represents aHAS_EPISODE relationship from a saga node to an episodic node, indicating that the episode is part of the saga.
Fields
Inherits all fields fromEdge with no additional fields.
Methods
async method
Persists the has-episode edge to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
async method
Deletes the has-episode edge from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
async classmethod
Retrieves a single has-episode edge by UUID.Parameters:
driver: GraphDriveruuid: str
HasEpisodeEdgeRaises: EdgeNotFoundError if not foundasync classmethod
Retrieves multiple has-episode edges by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[HasEpisodeEdge]async classmethod
Retrieves has-episode edges by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[HasEpisodeEdge]NextEpisodeEdge
Represents aNEXT_EPISODE relationship from one episodic node to another, forming a sequential chain of episodes.
Fields
Inherits all fields fromEdge with no additional fields.
Methods
async method
Persists the next-episode edge to the graph database.Parameters:
driver: GraphDriver- The graph driver instance
async method
Deletes the next-episode edge from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
Class Methods
async classmethod
Retrieves a single next-episode edge by UUID.Parameters:
driver: GraphDriveruuid: str
NextEpisodeEdgeRaises: EdgeNotFoundError if not foundasync classmethod
Retrieves multiple next-episode edges by UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
list[NextEpisodeEdge]async classmethod
Retrieves next-episode edges by group IDs with optional pagination.Parameters:
driver: GraphDrivergroup_ids: list[str]limit: int | None- Maximum number of results (optional)uuid_cursor: str | None- UUID cursor for pagination (optional)
list[NextEpisodeEdge]Common Edge Operations
All edge types support the following operations:Delete Operations
async method
Deletes the edge from the graph database.Parameters:
driver: GraphDriver- The graph driver instance
async classmethod
Deletes multiple edges by their UUIDs.Parameters:
driver: GraphDriveruuids: list[str]
Helper Functions
async function
Batch generates embeddings for multiple entity edges.Parameters:
embedder: EmbedderClientedges: list[EntityEdge]
Graph Relationship Types
The following relationship types are used in the graph database:- RELATES_TO - EntityEdge connecting two entity nodes
- MENTIONS - EpisodicEdge from an episode to an entity it mentions
- HAS_MEMBER - CommunityEdge from a community to a member entity
- HAS_EPISODE - HasEpisodeEdge from a saga to an episode
- NEXT_EPISODE - NextEpisodeEdge linking sequential episodes
Related
- Node Types - Learn about node types in the graph
- Episodes - Learn about episode types and processing
- Search - Search across edges in the knowledge graph