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.

Steering observations

By default, Zep decides how each observation is worded and assigns it a generic type. With observation steering, you can guide that generation — shaping the wording and relevance of new observations and assigning custom types you can filter on during search. Steering changes how observations are generated, not the evidence behind them.

Retrieving observations

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

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 observations Zep has materialized for a user's graph.
# The pager fetches the next page when you iterate.
observations = client.graph.observation.list(graph_uuid, limit=20)
for obs in observations:
    print(f"{obs.name}: {obs.summary}")
# Fetch a single item by UUID.
item = client.graph.observation.get(graph_uuid, observation_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 observations, use graph.search_observations. The call returns one page of results:

results = client.graph.search_observations(
    graph_uuid,
    query="account suspension and recovery",
    limit=5,
)
for obs in results.items or []:
    print(obs.name, obs.score)

Observations and the Context Block

The default Context Block can include observations when Smart Context Assembly selects them. Use a context template to always include observations or set a limit.

Retrieve observations directly or use advanced Context Block construction when you need full control.

Related

• Steering observations — guide how Zep words and categorizes new observations.
• Facts — granular, edge-level claims that often serve as evidence for observations.
• Entities — entity-level summaries on the Context Graph.
• Episodes — the supporting evidence that observations are grounded in.
• Searching the graph — how to retrieve observations with graph search.
• Context types — overview of the other context types.