Entities

Overview

An entity is one of the nouns that appear in the data Zep ingests — a person, an account, a product, a place, a concept. Zep extracts entities from the episodes you add to a graph, links them with facts, and exposes them as nodes you can list, fetch, and search.

Each entity has two pieces of information that matter most:

• A name — a short, human-readable label like Emily Painter, Adidas shoes, or Account Emily0e62.
• A summary — a narrative description of everything the graph knows about this entity, regenerated as new facts arrive.

Deduplication

Zep automatically deduplicates and merges entities when it determines that two refer to the same thing. This happens transparently as new data is ingested — there is no developer-facing knob to tune or disable.

Entity summaries

The summary on an entity is a narrative version of all the facts involving that entity. Every time a new fact is added to the graph, the summary for each affected entity is updated using the previous summary plus the new information. This incremental update process keeps summaries current and contextually relevant as the graph evolves.

Summaries vs. facts

Entities and facts capture different kinds of information, and Zep’s Context Block includes both:

• Facts are granular knowledge snippets. Each one captures a specific, discrete claim with precise temporal validity.
• Entity summaries are aggregated narratives. They roll up an entity’s involvement across many facts and relationships into a single description.

Using both gives an agent granular dated claims and an aggregated history. This context can support the task, but it does not guarantee the agent’s answer or behavior.

For durable patterns that span multiple entities — recurring loops, decisions, commitments — see observations.

Retrieving entities

Use the SDK to list the entities of a graph, fetch a single entity by UUID, or search a graph for entities.

Each call takes the UUID of a graph. For a user graph, use the graph_uuid that user.create returns. Store this UUID in your application database next to your own user ID.

List and fetch

from zep_cloud.client import Zep
client = Zep(api_key=API_KEY)
# The graph_uuid of the user, from your application database.
graph_uuid = zep_graph_uuid
# List the entities Zep has extracted into a user's graph.
# The pager fetches the next page when you iterate.
entities = client.graph.node.list(graph_uuid, limit=20)
for entity in entities:
    print(f"{entity.name}: {entity.summary}")
# Fetch a single item by UUID.
item = client.graph.node.get(graph_uuid, node_uuid)

List methods use cursor pagination. The SDK pager fetches the next page when you iterate. Set limit to control the page size. For a graph that you create with graph.create, pass the uuid that graph.create returns.

Search

To search a graph for entities, use graph.search_nodes. The call returns one page of results:

results = client.graph.search_nodes(
    graph_uuid,
    query="favorite running shoes",
    limit=5,
)
for entity in results.items or []:
    print(entity.name, entity.score)

See Searching the Graph for the full search API.

Entities and the Context Block

Entities are included in the default Context Block: the entities most relevant to the user’s recent messages are rendered alongside facts and episodes. To customize which entities appear or how they are formatted, define a context template that uses the %{entities} variable, or build a custom block via advanced context block construction.