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 breadth and depth at the same time: the precise dated claims it needs to be correct, plus the contextualized history it needs to be coherent.

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

Retrieving entities

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

List and fetch

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
# List the entities Zep has extracted into a user's graph.
6
entities = client.graph.node.get_by_user_id(
7
    user_id="emily-painter",
8
    limit=20,
9
)
10
11
for entity in entities:
12
    print(f"{entity.name}: {entity.summary}")
13
14
# Fetch a single entity by UUID.
15
single = client.graph.node.get(uuid_=entities[0].uuid_)

For graph-scoped entities, use get_by_graph_id (Python), getByGraphId (TypeScript), or GetByGraphID (Go) with a graph_id.

List endpoints support UUID-cursor pagination. Pass the UUID of the last item from the previous page as uuid_cursor to fetch the next page.

Search

To search a graph specifically for entities, pass scope="nodes" to graph.search:

1
results = client.graph.search(
2
    user_id="emily-painter",
3
    query="favorite running shoes",
4
    scope="nodes",
5
    limit=5,
6
)
7
8
for entity in results.nodes or []:
9
    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.