Searching the Graph

Simple Hybrid Edge Search

Graph edges represent relationships between nodes and contain retrievable semantic facts. The basic search query is a text-based hybrid search against graph edges. It requires only a text string as input. Zep performs both semantic similarity search using embeddings and BM25 full-text search, and results are merged and reranked using Reciprocal Rank Fusion (RRF).

Reciprocal Rank Fusion (RRF) combines and ranks results from multiple searches based on their individual rankings.

The example below demonstrates a search against a chat session using only search text.

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.graph.search(
8
    user_id=user_id,
9
    query=query,
10
)

Read more about chat message history search.

Search Scopes

Graph search supports both edge and node scopes. Nodes represent entities discussed in chat history or business data added via the Graph API. Nodes contain summaries of relevant facts from edges adjacent to the node, providing a useful overview of a node’s context.

Group graphs can be searched by passing a group_id instead of a user_id.

The example below demonstrates a node search. All re-ranking methods are applicable to node searches as well.

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.graph.search(
8
    group_id=group_id,
9
    query=query,
10
    scope="nodes",
11
)

Maximal Marginal Relevance Re-Ranking

Zep supports Maximal Marginal Relevance (MMR) re-ranking for graph search results.

MMR balances relevance and diversity in search results. Standard similarity searches often return highly similar top results, potentially limiting the information added to a prompt. MMR addresses this by re-ranking results to promote diversity, downranking similar results in favor of relevant but distinct alternatives.

Example of MMR search:

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.graph.search(
8
    user_id=user_id,
9
    query=query,
10
    reranker="mmr",
11
    mmr_lambda=0.5, # tune diversity vs relevance
12
)

Node Distance

Node Distance re-ranks search results based on the number of hops between the search result and a center node. This can be useful for finding facts related to a specific node, such as a user or a topic.

The UUID of a node must be passed in to be used as a center node.

An example using Node Distance search.

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.graph.search(
8
    user_id=user_id,
9
    query=query,
10
    reranker="node_distance",
11
    center_node_uuid=center_node_uuid,
12
)

Episode Mentions

Episode Mentions re-ranks search results based on the number of times the node or edge has been mentioned in the chat history.

An example using Episode Mentions search.

1
from zep_cloud.client import AsyncZep
2
3
client = AsyncZep(
4
    api_key=API_KEY,
5
)
6
7
search_results = await client.graph.search(
8
    user_id=user_id,
9
    query=query,
10
    reranker="episode_mentions",
11
)