> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Types

> Core node types for representing entities, episodes, communities, and sagas in Graphiti knowledge graphs

# Node Types

Graphiti uses four primary node types to represent different elements in the knowledge graph. All nodes inherit from the base `Node` class and share common fields for identification, grouping, and timestamps.

## Base Node

The abstract base class that all node types inherit from.

<ParamField path="uuid" type="str" required>
  Unique identifier for the node. Automatically generated using UUID4 if not provided.
</ParamField>

<ParamField path="name" type="str" required>
  Name of the node.
</ParamField>

<ParamField path="group_id" type="str" required>
  Partition identifier for the graph. Used to organize nodes into logical groups or namespaces.
</ParamField>

<ParamField path="labels" type="list[str]">
  List of labels applied to the node. Default: empty list.
</ParamField>

<ParamField path="created_at" type="datetime">
  Timestamp of when the node was created. Automatically set to current UTC time if not provided.
</ParamField>

## EntityNode

Represents entities extracted from episodes, such as people, places, organizations, or concepts.

### Fields

Inherits all fields from `Node`, plus:

<ParamField path="name_embedding" type="list[float] | None">
  Vector embedding of the entity name, used for semantic similarity searches. Generated using the configured embedder client.
</ParamField>

<ParamField path="summary" type="str">
  Regional summary of surrounding edges and relationships. Default: empty string.
</ParamField>

<ParamField path="attributes" type="dict[str, Any]">
  Additional attributes of the node. Content depends on node labels and can store custom properties extracted from episodes.
</ParamField>

### Methods

<ResponseField name="generate_name_embedding" type="async method">
  Generates and stores the name embedding for this entity.

  **Parameters:**

  * `embedder: EmbedderClient` - The embedder client to use for generating embeddings

  **Returns:** `list[float]` - The generated embedding vector
</ResponseField>

<ResponseField name="load_name_embedding" type="async method">
  Loads the name embedding from the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance

  **Raises:** `NodeNotFoundError` if the node doesn't exist
</ResponseField>

<ResponseField name="save" type="async method">
  Persists the entity node to the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance
</ResponseField>

### Class Methods

<ResponseField name="get_by_uuid" type="async classmethod">
  Retrieves a single entity node by UUID.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuid: str`

  **Returns:** `EntityNode`

  **Raises:** `NodeNotFoundError` if not found
</ResponseField>

<ResponseField name="get_by_uuids" type="async classmethod">
  Retrieves multiple entity nodes by UUIDs.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuids: list[str]`

  **Returns:** `list[EntityNode]`
</ResponseField>

<ResponseField name="get_by_group_ids" type="async classmethod">
  Retrieves entity nodes by group IDs with optional pagination.

  **Parameters:**

  * `driver: GraphDriver`
  * `group_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)

  **Returns:** `list[EntityNode]`
</ResponseField>

## EpisodicNode

Represents raw episodes (events or documents) that have been processed into the knowledge graph.

### Fields

Inherits all fields from `Node`, plus:

<ParamField path="source" type="EpisodeType" required>
  The type/source of the episode. See [EpisodeType](#episodetype-enum) for available values.
</ParamField>

<ParamField path="source_description" type="str" required>
  Description of the data source for this episode.
</ParamField>

<ParamField path="content" type="str" required>
  Raw episode data/content.
</ParamField>

<ParamField path="valid_at" type="datetime" required>
  Timestamp of when the original document was created or when the event occurred.
</ParamField>

<ParamField path="entity_edges" type="list[str]">
  List of entity edge UUIDs referenced in this episode. Default: empty list.
</ParamField>

### Methods

<ResponseField name="save" type="async method">
  Persists the episodic node to the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance
</ResponseField>

### Class Methods

<ResponseField name="get_by_uuid" type="async classmethod">
  Retrieves a single episodic node by UUID.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuid: str`

  **Returns:** `EpisodicNode`

  **Raises:** `NodeNotFoundError` if not found
</ResponseField>

<ResponseField name="get_by_uuids" type="async classmethod">
  Retrieves multiple episodic nodes by UUIDs.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuids: list[str]`

  **Returns:** `list[EpisodicNode]`
</ResponseField>

<ResponseField name="get_by_group_ids" type="async classmethod">
  Retrieves episodic nodes by group IDs with optional pagination.

  **Parameters:**

  * `driver: GraphDriver`
  * `group_ids: list[str]`
  * `limit: int | None` - Maximum number of results (optional)
  * `uuid_cursor: str | None` - UUID cursor for pagination (optional)

  **Returns:** `list[EpisodicNode]`
</ResponseField>

<ResponseField name="get_by_entity_node_uuid" type="async classmethod">
  Retrieves all episodic nodes that mention a specific entity.

  **Parameters:**

  * `driver: GraphDriver`
  * `entity_node_uuid: str` - UUID of the entity node

  **Returns:** `list[EpisodicNode]`
</ResponseField>

## CommunityNode

Represents a community or cluster of related entities in the knowledge graph.

### Fields

Inherits all fields from `Node`, plus:

<ParamField path="name_embedding" type="list[float] | None">
  Vector embedding of the community name, used for semantic similarity searches.
</ParamField>

<ParamField path="summary" type="str">
  Regional summary of member nodes and their relationships. Default: empty string.
</ParamField>

### Methods

<ResponseField name="save" type="async method">
  Persists the community node to the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance
</ResponseField>

<ResponseField name="generate_name_embedding" type="async method">
  Generates and stores the name embedding for this community.

  **Parameters:**

  * `embedder: EmbedderClient` - The embedder client to use for generating embeddings

  **Returns:** `list[float]` - The generated embedding vector
</ResponseField>

<ResponseField name="load_name_embedding" type="async method">
  Loads the name embedding from the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance

  **Raises:** `NodeNotFoundError` if the node doesn't exist
</ResponseField>

### Class Methods

<ResponseField name="get_by_uuid" type="async classmethod">
  Retrieves a single community node by UUID.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuid: str`

  **Returns:** `CommunityNode`

  **Raises:** `NodeNotFoundError` if not found
</ResponseField>

<ResponseField name="get_by_uuids" type="async classmethod">
  Retrieves multiple community nodes by UUIDs.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuids: list[str]`

  **Returns:** `list[CommunityNode]`
</ResponseField>

<ResponseField name="get_by_group_ids" type="async classmethod">
  Retrieves community nodes by group IDs with optional pagination.

  **Parameters:**

  * `driver: GraphDriver`
  * `group_ids: list[str]`
  * `limit: int | None` - Maximum number of results (optional)
  * `uuid_cursor: str | None` - UUID cursor for pagination (optional)

  **Returns:** `list[CommunityNode]`
</ResponseField>

## SagaNode

Represents a saga, which is a collection of related episodes forming a narrative thread.

### Fields

Inherits all fields from `Node` with no additional fields.

### Methods

<ResponseField name="save" type="async method">
  Persists the saga node to the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance
</ResponseField>

<ResponseField name="delete" type="async method">
  Deletes the saga node from the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance
</ResponseField>

### Class Methods

<ResponseField name="get_by_uuid" type="async classmethod">
  Retrieves a single saga node by UUID.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuid: str`

  **Returns:** `SagaNode`

  **Raises:** `NodeNotFoundError` if not found
</ResponseField>

<ResponseField name="get_by_uuids" type="async classmethod">
  Retrieves multiple saga nodes by UUIDs.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuids: list[str]`

  **Returns:** `list[SagaNode]`
</ResponseField>

<ResponseField name="get_by_group_ids" type="async classmethod">
  Retrieves saga nodes by group IDs with optional pagination.

  **Parameters:**

  * `driver: GraphDriver`
  * `group_ids: list[str]`
  * `limit: int | None` - Maximum number of results (optional)
  * `uuid_cursor: str | None` - UUID cursor for pagination (optional)

  **Returns:** `list[SagaNode]`
</ResponseField>

## Common Node Operations

All node types support the following operations:

### Delete Operations

<ResponseField name="delete" type="async method">
  Deletes the node and its relationships from the graph database.

  **Parameters:**

  * `driver: GraphDriver` - The graph driver instance
</ResponseField>

<ResponseField name="delete_by_group_id" type="async classmethod">
  Deletes all nodes of this type within a group.

  **Parameters:**

  * `driver: GraphDriver`
  * `group_id: str`
  * `batch_size: int` - Number of nodes to delete per batch (default: 100)
</ResponseField>

<ResponseField name="delete_by_uuids" type="async classmethod">
  Deletes multiple nodes by their UUIDs.

  **Parameters:**

  * `driver: GraphDriver`
  * `uuids: list[str]`
  * `batch_size: int` - Number of nodes to delete per batch (default: 100)
</ResponseField>

## Helper Functions

<ResponseField name="create_entity_node_embeddings" type="async function">
  Batch generates embeddings for multiple entity nodes.

  **Parameters:**

  * `embedder: EmbedderClient`
  * `nodes: list[EntityNode]`

  Filters out nodes with empty names and generates embeddings for the remaining nodes in batch.
</ResponseField>

## Related

* [Edge Types](/api/edges) - Learn about edge types that connect nodes
* [Episodes](/api/episodes) - Learn about episode types and processing
* [Search](/api/search) - Search across nodes in the knowledge graph