Detecting Patterns

Introduction

Zep’s pattern detection analyzes the structure of your knowledge graph to discover recurring patterns: frequent relationship types, multi-hop paths, co-occurring entities, highly connected hubs, and tightly interconnected clusters. Unlike graph search, which retrieves content matching a query, pattern detection reveals the shape of your data — surfacing structural insights that aren’t visible from individual nodes or edges.

Pattern detection supports two modes:

• Seed mode: Provide explicit seed nodes, labels, or edge types to analyze patterns around specific parts of the graph
• Query mode: Provide a natural-language query to automatically discover relevant nodes and return relationship patterns with relevance-scored edges

What It Finds

Use Cases

• Knowledge graph auditing: Understand what types of information your graph captures most frequently
• Schema discovery: Identify dominant relationship patterns to inform ontology design
• Anomaly context: Establish baselines of normal graph structure to help detect anomalies
• Data quality: Find unexpected patterns that may indicate ingestion issues
• Agent-driven Q&A: Use query mode to find relevant graph context for answering questions (e.g., “clothing purchases” returns scored edge facts about purchase patterns)

Basic Usage

Seed mode

Provide seeds to focus analysis around specific nodes, node labels, or edge types. At least one seed field (node_uuids, node_labels, or edge_types) is required.

1
from zep_cloud import Zep
2
3
client = Zep(
4
    api_key=API_KEY,
5
)
6
7
result = client.graph.detect_patterns(
8
    user_id="alice",
9
    seeds={
10
        "node_labels": ["Decision"],
11
    },
12
)
13
14
for pattern in result.patterns:
15
    print(f"{pattern.type}: {pattern.description} ({pattern.occurrences}x)")

Query mode

Provide a query string to let Zep automatically discover relevant nodes and detect relationship patterns. The response includes relevance-scored edges per pattern and a deduplicated nodes array.

1
result = client.graph.detect_patterns(
2
    user_id="alice",
3
    query="clothing purchases",
4
)
5
6
for pattern in result.patterns:
7
    print(f"{pattern.description} ({pattern.occurrences}x)")
8
    for edge in pattern.edges:
9
        print(f"  {edge.fact} (score: {edge.score:.2f})")
10
11
# Deduplicated nodes referenced by pattern edges
12
for node in result.nodes:
13
    print(f"  Node: {node.name} ({node.labels})")

Configurable Parameters

*Either user_id or graph_id is required

Either query or seeds is required, but not both

Selecting Pattern Types

Use the detect parameter to choose which pattern types to find. Each key enables that type; its value provides type-specific configuration. Omit detect entirely to run all types with defaults.

1
result = client.graph.detect_patterns(
2
    user_id="alice",
3
    seeds={
4
        "node_labels": ["Person"],
5
    },
6
    detect={
7
        "relationships": {},
8
        "paths": {"max_hops": 4},
9
        "hubs": {"min_degree": 5},
10
    },
11
)

Type-Specific Configuration

Seed Nodes

Use seeds to specify the starting points for pattern detection in seed mode. At least one seed field is required. When multiple seed fields are provided, seeds are combined (union). Seeds cannot be used together with query.

1
# Focus on patterns around Decision nodes
2
result = client.graph.detect_patterns(
3
    user_id="alice",
4
    seeds={
5
        "node_labels": ["Decision"],
6
    },
7
    detect={
8
        "relationships": {},
9
        "paths": {"max_hops": 3},
10
    },
11
)

Seed Options

Recency Weighting

Apply temporal decay to favor recently created edges. The recency_weight value sets the exponential decay half-life applied to each edge’s created_at timestamp.

When recency weighting is enabled, the weighted_score in each result reflects the decayed sum, while occurrences always reports the raw unweighted count.

1
result = client.graph.detect_patterns(
2
    user_id="alice",
3
    seeds={
4
        "node_labels": ["Decision"],
5
    },
6
    recency_weight="30_days",
7
)
8
9
for pattern in result.patterns:
10
    print(f"{pattern.description}: {pattern.occurrences} occurrences, weighted score {pattern.weighted_score:.1f}")

Search Filters

Use search_filters to restrict which nodes and edges participate in pattern detection. This uses the same filter format as graph search.

1
result = client.graph.detect_patterns(
2
    user_id="alice",
3
    seeds={
4
        "node_labels": ["Decision"],
5
    },
6
    search_filters={
7
        "node_labels": ["Decision", "Person"],
8
        "edge_types": ["CHOSE", "REJECTED"],
9
        "created_at": [[{">": "2025-01-01T00:00:00Z"}]],
10
    },
11
)

Response Structure

Each pattern in the response contains:

The top-level response also includes:

The metadata object contains:

Patterns are sorted by weighted_score in descending order.