Observations: Patterns and Insights from the Context Graph

Today we're announcing Observations, a new context type that captures patterns and insights across your Context Graphs. They surface what no single fact or entity captures: behaviors, decisions, and preferences that emerge across many episodes. Zep discovers and creates Observations automatically. You can then retrieve Observations via the new observations graph search scope, or as a Context Template variable. Observations are available now on Flex Plus and Enterprise.

What Observations are

An Observation is a derived node in the Context Graph that represents a pattern across a coherent neighborhood of entities, relationships, and episodes. The patterns and insights it captures include decisions and commitments, constraints and preferences, state transitions, recurring behaviors, and stable relationships.

Here's an Observation from a real-estate-agent graph. After Jane Doe spent three sessions narrowing down a home purchase, an Observation captured her decision (Maple Street over Oak Avenue, planned offer) as a single retrievable claim:

The Observation captures three sessions' worth of evidence (the viewings, the stated preference, the offer plan) as a single retrievable claim instead of scattered facts.

Why Observations matter

Zep extracts facts and entities from narrow, local windows of episodes. Patterns that emerge across sessions, or episodes that are temporally distant, aren't easily captured. Observations surface these patterns and insights from across the Context Graph. The Context Graph is the ideal substrate for this: it encodes them as locally coherent neighborhoods, making them discoverable as a user's history accumulates.

The lift shows up on LongMemEval, a benchmark that probes the kinds of aggregation and reasoning questions agents typically struggle with. While evaluating Zep against it, we saw Observations doing exactly what we'd hoped on questions like "How many Crash Course videos have I watched in the past few weeks?" The user mentioned individual videos across many sessions but never stated a total. An Observation had rolled the count up to '15' at ingestion, so the agent retrieved the answer directly instead of counting across raw messages at query time.

How to use Observations

Zep discovers and synthesizes them in the background — no setup required. You can retrieve them in two ways.

Graph search

Use the new observations scope on graph search alongside the existing edges, nodes, and episodes scopes:

from zep_cloud import Zep

client = Zep(api_key="YOUR_API_KEY")

results = client.graph.search(
    user_id="user_123",
    query="What does this user typically do when traveling?",
    scope="observations",
    limit=5,
)

Context Templates

You can also reference Observations in Context Templates, so they appear in the output of thread.get_user_context():

client.context.create_context_template(
    template_id="customer-support",
    template="""# CUSTOMER PROFILE
%{user_summary}

# OBSERVATIONS
# Patterns and insights about this user.
%{observations limit=10}

# FACTS
%{edges limit=10}

# KEY ENTITIES
%{entities limit=5}""",
)

Then retrieve the output by passing the template ID:

user_context = client.thread.get_user_context(
    thread_id="thread_id",
    template_id="customer-support",
)
context_block = user_context.context

Getting started

Read the Observations docs for the full reference. Observations are available now on Flex Plus and Enterprise.