Observations

Overview

An observation is a durable, evidence-backed piece of context that Zep automatically derives from a graph. Each observation captures a meaningful change, decision, commitment, constraint, preference, state transition, recurring pattern, or stable relationship involving one or more entities.

Observations sit alongside facts and entity summaries as a derived construct on the graph, but they answer a different question:

• Facts are granular, time-stamped claims stored on a single edge between two entities.
• Entity summaries are entity-centered narratives that describe the history of a single node.
• Observations are cross-entity context that captures why something matters — the persistent decisions, behaviors, and relationships that span multiple facts and entities.

This makes observations especially useful for surfacing context that would otherwise be diluted across many facts: a user’s evolving preferences, a recurring failure mode, a long-running commitment, or the way two entities consistently interact over time.

How Zep creates observations

Observations are detected automatically by analyzing structural patterns in the graph — clusters of facts and entities that together describe the same underlying behavior or relationship. Zep then synthesizes a name and summary for each observation it detects.

Observations are deduplicated and merged: when new evidence fits an existing observation, the existing observation is regenerated with the new evidence merged in. When a newer observation supersedes an older one, the older observation is retired so the graph reflects the current state of what is known.

Observations are read-only — they cannot be created, edited, or deleted directly. They follow the evidence in the graph.

Retrieving observations

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

List and fetch

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

For graph-scoped observations, 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

1
results = client.graph.search(
2
    user_id="emily-painter",
3
    query="account suspension and recovery",
4
    scope="observations",
5
    limit=5,
6
)
7
8
for obs in results.observations or []:
9
    print(obs.name, obs.score)

Observations and the Context Block

Observations may be included in the default Context Block when Smart Context Assembly selects them as relevant to the current conversation. To always include them — or to pin a specific count — use a context template. For full control over which observations appear and how they’re formatted, retrieve them directly with the SDK methods above, or build a custom block via advanced context block construction.

Related

• Facts — granular, edge-level claims that often serve as evidence for observations.
• Entities — entity-level summaries on the knowledge graph.
• Episodes — the supporting evidence that observations are grounded in.
• Searching the Graph — how to surface observations in graph search.
• Context Types — overview of the other context types.