Facts

Overview

Facts are precise and time-stamped information stored on edges that capture detailed relationships about specific events. They include valid_at and invalid_at timestamps, ensuring temporal accuracy and preserving a clear history of changes over time.

How Zep updates facts

When incorporating new data, Zep looks for existing nodes and edges in the graph and decides whether to add new nodes/edges or to update existing ones. An update could mean updating an edge (for example, indicating the previous fact is no longer valid).

Here’s an example of how Zep might extract graph data from a chat message, and then update the graph once new information is available:

As shown in the example above, when Kendra initially loves Adidas shoes but later is angry that the shoes broke and states a preference for Puma shoes, Zep attempts to invalidate the fact that Kendra loves Adidas shoes and creates two new facts: “Kendra’s Adidas shoes broke” and “Kendra likes Puma shoes”.

Zep also looks for dates in all ingested data, such as the timestamp on a chat message or an article’s publication date, informing how Zep sets the edge attributes. This assists your agent in reasoning with time.

The four fact timestamps

Each fact stored on an edge includes four different timestamp attributes that track the lifecycle of that information:

The valid_at and invalid_at attributes for each fact are then included in Zep’s Context Block which is given to your agent:

# format: FACT (Date range: from - to)
User account Emily0e62 has a suspended status due to payment failure. (2024-11-14 02:03:58+00:00 - present)

Edge names

In addition to the fact body and timestamps, each edge has a name that identifies the relationship type. Edge names are SCREAMING_SNAKE_CASE labels like WORKS_AT, LIVES_IN, OWNS, or PURCHASED. Zep generates a name for each edge it extracts from your data.

If you use Zep’s custom ontology feature to define custom edge types, the custom edge type is expressed through the edge name: when Zep classifies an edge as one of your custom types, the edge’s name is set to the type key you registered. For example, if you register an edge type with key RESTAURANT_VISIT, every edge classified as that type will have name = "RESTAURANT_VISIT". This is how you can tell — given an edge — whether it was matched to a custom type and which one.

Adding or deleting facts

Facts are generated as part of the ingestion process. If you follow the directions for adding data to the graph, new facts will be created.

Deleting facts is handled by deleting data from the graph. Facts will be deleted when you delete the edge they exist on.

Retrieving facts

Facts live on edges, so the SDK exposes them under graph.edge. List edges for a user or graph, fetch an edge by UUID, or search a graph specifically for facts.

List and fetch

1
from zep_cloud.client import Zep
2
3
client = Zep(api_key=API_KEY)
4
5
# List the most recent edges (facts) on a user's graph.
6
edges = client.graph.edge.get_by_user_id(user_id="emily-painter")
7
8
for edge in edges:
9
    print(f"[{edge.name}] {edge.fact}")
10
11
# Fetch a single edge by UUID.
12
single = client.graph.edge.get(uuid_=edges[0].uuid_)

Search

Facts are the default search target for graph search. Calling graph.search without a scope returns the facts most relevant to your query:

1
results = client.graph.search(
2
    user_id="emily-painter",
3
    query="payment failures",
4
    limit=5,
5
)
6
7
for edge in results.edges or []:
8
    print(edge.name, edge.fact, edge.score)

Related context types

Facts are one of several types of context Zep produces from a user’s graph. Each fact lives on an edge between two entities and is extracted from one or more episodes. For durable, cross-entity patterns derived from many facts, see observations.