Searching the Graph
Custom Context Strings
Graph search results should be used in conjunction with Custom Context Strings to create rich, contextual prompts for AI models. Custom context strings allow you to format and structure the retrieved graph information, combining search results with conversation history and other relevant data to provide comprehensive context for your AI applications.
Learn how to integrate graph search results into your context generation workflow for more effective AI interactions.
Introduction
Zep’s graph search provides powerful hybrid search capabilities that combine semantic similarity with BM25 full-text search to find relevant information across your knowledge graph. This approach leverages the best of both worlds: semantic understanding for conceptual matches and full-text search for exact term matching. Additionally, you can optionally enable breadth-first search to bias results toward information connected to specific starting points in your graph.
How It Works
- Semantic similarity: Converts queries into embeddings to find conceptually similar content
- BM25 full-text search: Performs traditional keyword-based search for exact matches
- Breadth-first search (optional): Biases results toward information connected to specified starting nodes, useful for contextual relevance
- Hybrid results: Combines and reranks results using sophisticated algorithms
Graph Concepts
- Nodes: Connection points representing entities (people, places, concepts) discussed in conversations or added via the Graph API
- Edges: Relationships between nodes containing specific facts and interactions
The example below demonstrates a simple search:
Best Practices
Keep queries short: they are truncated at 8,192 tokens. Long queries may increase latency without improving search quality. Break down complex searches into smaller, targeted queries. Use precise, contextual queries rather than generic ones
Configurable Parameters
Zep provides extensive configuration options to fine-tune search behavior and optimize results for your specific use case:
*Either user_id
OR group_id
is required
†Required when using mmr
reranker
‡Required when using node_distance
reranker
Search Scopes
Zep supports three different search scopes, each optimized for different types of information retrieval:
Edges (Default)
Edges represent individual relationships and facts between entities in your graph. They contain specific interactions, conversations, and detailed information. Edge search is ideal for:
- Finding specific details or conversations
- Retrieving precise facts about relationships
- Getting granular information about interactions
Nodes
Nodes are connection points in the graph that represent entities. Each node maintains a summary of facts from its connections (edges), providing a comprehensive overview. Node search is useful for:
- Understanding broader context around entities
- Getting entity summaries and overviews
- Finding all information related to a specific person, place, or concept
Episodes
Episodes represent individual messages or chunks of data sent to Zep. Episode search allows you to find relevant episodes based on their content, making it ideal for:
- Finding specific messages or data chunks related to your query
- Discovering when certain topics were mentioned
- Retrieving relevant individual interactions
- Understanding the context of specific messages
Rerankers
Zep provides multiple reranking algorithms to optimize search results for different use cases. Each reranker applies a different strategy to prioritize and order results:
RRF (Reciprocal Rank Fusion)
Reciprocal Rank Fusion is the default reranker that intelligently combines results from both semantic similarity and BM25 full-text search. It merges the two result sets by considering the rank position of each result in both searches, creating a unified ranking that leverages the strengths of both approaches.
When to use: RRF is ideal for most general-purpose search scenarios where you want balanced results combining conceptual understanding with exact keyword matching.
MMR (Maximal Marginal Relevance)
Maximal Marginal Relevance addresses a common issue in similarity searches: highly similar top results that don’t add diverse information to your context. MMR reranks results to balance relevance with diversity, promoting varied but still relevant results over redundant similar ones.
When to use: Use MMR when you need diverse information for comprehensive context, such as generating summaries, answering complex questions, or avoiding repetitive results.
Required parameter: mmr_lambda
(0.0-1.0) - Controls the balance between relevance (1.0) and diversity (0.0). A value of 0.5 provides balanced results.
Cross Encoder
cross_encoder
uses a specialized neural model that jointly analyzes the query and each search result together, rather than analyzing them separately. This provides more accurate relevance scoring by understanding the relationship between the query and potential results in a single model pass.
When to use: Use cross encoder when you need the highest accuracy in relevance scoring and are willing to trade some performance for better results. Ideal for critical searches where precision is paramount.
Trade-offs: Higher accuracy but slower performance compared to other rerankers.
Episode Mentions
episode_mentions
reranks search results based on how frequently nodes or edges have been mentioned across all episodes, including both conversational episodes (chat history) and episodes created via graph.add
. Results that appear more often across these episodes are prioritized, reflecting their importance and relevance.
When to use: Use episode mentions when you want to surface information that has been frequently referenced across conversations or data uploads. Useful for understanding recurring themes, important topics, or frequently mentioned entities across all your graph data.
Node Distance
node_distance
reranks search results based on graph proximity, prioritizing results that are closer (fewer hops) to a specified center node. This spatial approach to relevance is useful for finding information contextually related to a specific entity or concept.
When to use: Use node distance when you want to find information specifically related to a particular entity, person, or concept in your graph. Ideal for exploring the immediate context around a known entity.
Required parameter: center_node_uuid
- The UUID of the node to use as the center point for distance calculations.
Search Filters
Zep allows you to filter search results by specific entity types or edge types, enabling more targeted searches within your graph.
Entity Type Filtering
Filter search results to only include nodes of specific entity types. This is useful when you want to focus on particular kinds of entities (e.g., only people, only companies, only locations).
Edge Type Filtering
Filter search results to only include edges of specific relationship types. This helps you find particular kinds of relationships or interactions between entities.
Breadth-First Search (BFS)
The bfs_origin_node_uuids
parameter enables breadth-first searches starting from specified nodes, which helps make search results more relevant to recent context. This is particularly useful when combined with recent episode IDs to bias search results toward information connected to recent conversations. You can pass episode IDs as BFS node IDs because episodes are represented as nodes under the hood.
When to use: Use BFS when you want to find information that’s contextually connected to specific starting points in your graph, such as recent episodes or important entities.