Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt

Use this file to discover all available pages before exploring further.

Graphiti provides powerful search capabilities to retrieve relevant information from your knowledge graph, combining semantic similarity, full-text search, and graph-based reranking. The simplest way to search is using the search() method, which returns relationship edges: 
from graphiti_core import Graphiti

graphiti = Graphiti(
    uri="bolt://localhost:7687",
    user="neo4j",
    password="password"
)

# Search for information
results = await graphiti.search("Who was the California Attorney General?")

# Display results
for result in results:
    print(f"Fact: {result.fact}")
    print(f"UUID: {result.uuid}")
    if result.valid_at:
        print(f"Valid from: {result.valid_at}")
    if result.invalid_at:
        print(f"Valid until: {result.invalid_at}")
    print("---")

​
Search Methods

Graphiti uses hybrid search combining multiple retrieval methods:

Semantic Similarity

Finds results based on meaning using vector embeddings

BM25 Full-Text

Finds results based on keyword matching

Graph Traversal (BFS)

Explores connected nodes in the graph

Reranking

Combines and reorders results for optimal relevance

​
Search Parameters

ParameterTypeDefaultDescription
querystrRequiredThe search query
center_node_uuidstrNoneUUID of node to rerank by graph distance
group_idslist[str]NoneFilter results to specific graph partitions
num_resultsint10Maximum number of results to return
search_filterSearchFiltersNoneAdvanced filtering options

​
Center Node Reranking

Rerank results based on their graph distance from a specific node: 
# Initial search
results = await graphiti.search("Who was the California Attorney General?")

if results:
    # Use the top result's source node as the center
    center_node_uuid = results[0].source_node_uuid
    
    # Rerank based on graph proximity
    reranked_results = await graphiti.search(
        "Who was the California Attorney General?",
        center_node_uuid=center_node_uuid
    )
    
    # Results are now ordered by relevance to the center node
    for result in reranked_results:
        print(f"Fact: {result.fact}")
This is useful for finding contextually related information around a specific entity.

​
Advanced Search with Configurations

For more control, use the search_() method with custom search configurations: 
from graphiti_core.search.search_config_recipes import (
    NODE_HYBRID_SEARCH_RRF,
    EDGE_HYBRID_SEARCH_CROSS_ENCODER,
    COMBINED_HYBRID_SEARCH_RRF
)

# Search for nodes instead of edges
node_search_config = NODE_HYBRID_SEARCH_RRF.model_copy(deep=True)
node_search_config.limit = 5

results = await graphiti.search_(
    query="California Governor",
    config=node_search_config
)

# Access node results
for node in results.nodes:
    print(f"Node: {node.name}")
    print(f"Summary: {node.summary}")
    print(f"Labels: {', '.join(node.labels)}")
    if node.attributes:
        print(f"Attributes: {node.attributes}")
    print("---")

​
Search Configuration Recipes

Graphiti provides pre-configured search recipes optimized for different scenarios:

​
Edge Search Recipes

Search for relationships between entities: 
from graphiti_core.search.search_config_recipes import (
    EDGE_HYBRID_SEARCH_RRF,           # Reciprocal Rank Fusion
    EDGE_HYBRID_SEARCH_MMR,            # Maximal Marginal Relevance
    EDGE_HYBRID_SEARCH_NODE_DISTANCE,  # Graph distance based
    EDGE_HYBRID_SEARCH_EPISODE_MENTIONS, # Episode frequency based
    EDGE_HYBRID_SEARCH_CROSS_ENCODER   # Neural reranking
)

results = await graphiti.search_(
    query="relationships between people",
    config=EDGE_HYBRID_SEARCH_CROSS_ENCODER
)

​
Node Search Recipes

Search for entities: 
from graphiti_core.search.search_config_recipes import (
    NODE_HYBRID_SEARCH_RRF,           # Reciprocal Rank Fusion
    NODE_HYBRID_SEARCH_MMR,            # Maximal Marginal Relevance
    NODE_HYBRID_SEARCH_NODE_DISTANCE,  # Graph distance based
    NODE_HYBRID_SEARCH_EPISODE_MENTIONS, # Episode frequency based
    NODE_HYBRID_SEARCH_CROSS_ENCODER   # Neural reranking
)

results = await graphiti.search_(
    query="engineers in San Francisco",
    config=NODE_HYBRID_SEARCH_RRF
)

​
Combined Search Recipes

Search across nodes, edges, episodes, and communities: 
from graphiti_core.search.search_config_recipes import (
    COMBINED_HYBRID_SEARCH_RRF,
    COMBINED_HYBRID_SEARCH_MMR,
    COMBINED_HYBRID_SEARCH_CROSS_ENCODER
)

results = await graphiti.search_(
    query="California politics",
    config=COMBINED_HYBRID_SEARCH_CROSS_ENCODER
)

print(f"Edges: {len(results.edges)}")
print(f"Nodes: {len(results.nodes)}")
print(f"Episodes: {len(results.episodes)}")
print(f"Communities: {len(results.communities)}")

​
Community Search Recipes

Search for clusters of related entities: 
from graphiti_core.search.search_config_recipes import (
    COMMUNITY_HYBRID_SEARCH_RRF,
    COMMUNITY_HYBRID_SEARCH_MMR,
    COMMUNITY_HYBRID_SEARCH_CROSS_ENCODER
)

results = await graphiti.search_(
    query="technology companies",
    config=COMMUNITY_HYBRID_SEARCH_RRF
)

for community in results.communities:
    print(f"Community: {community.name}")
    print(f"Summary: {community.summary}")

​
Custom Search Configurations

Build your own search configuration: 
from graphiti_core.search.search_config import (
    SearchConfig,
    EdgeSearchConfig,
    EdgeSearchMethod,
    EdgeReranker
)

# Custom configuration
custom_config = SearchConfig(
    edge_config=EdgeSearchConfig(
        search_methods=[
            EdgeSearchMethod.bm25,
            EdgeSearchMethod.cosine_similarity
        ],
        reranker=EdgeReranker.mmr,
        sim_min_score=0.5,  # Minimum similarity threshold
        mmr_lambda=0.7      # Diversity parameter (0=diverse, 1=similar)
    ),
    limit=20,
    reranker_min_score=0.3
)

results = await graphiti.search_(
    query="product recommendations",
    config=custom_config
)

​
Search Configuration Options

​
Search Methods

  • EdgeSearchMethod.cosine_similarity - Semantic vector search
  • EdgeSearchMethod.bm25 - Full-text keyword search
  • EdgeSearchMethod.bfs - Breadth-first graph traversal

​
Reranking Methods

RRF

Reciprocal Rank Fusion - Combines multiple search methods by rank

MMR

Maximal Marginal Relevance - Balances relevance and diversity

Node Distance

Reranks by graph distance from a center node

Cross Encoder

Neural reranking for highest accuracy

Episode Mentions

Reranks by frequency across episodes

​
Search Filters

Filter results by group, time, or custom criteria: 
from graphiti_core.search.search_filters import SearchFilters
from datetime import datetime, timezone, timedelta

# Filter by time range
start_time = datetime.now(timezone.utc) - timedelta(days=30)
end_time = datetime.now(timezone.utc)

filters = SearchFilters(
    start_date=start_time,
    end_date=end_time
)

results = await graphiti.search(
    query="recent activity",
    search_filter=filters
)

​
Search Results

The search_() method returns a SearchResults object with multiple result types: 
results = await graphiti.search_(
    query="example query",
    config=COMBINED_HYBRID_SEARCH_RRF
)

# Access different result types
for edge in results.edges:
    print(f"Edge: {edge.fact} (score: {results.edge_reranker_scores[results.edges.index(edge)]})")

for node in results.nodes:
    print(f"Node: {node.name} (score: {results.node_reranker_scores[results.nodes.index(node)]})")

for episode in results.episodes:
    print(f"Episode: {episode.name}")

for community in results.communities:
    print(f"Community: {community.name}")

​
Performance Tips

Limit Results

Set appropriate limit values to reduce latency

Use Group IDs

Filter by group_ids to search specific partitions

Simple Configs

Start with RRF reranking before using cross-encoder

Min Scores

Set reranker_min_score to filter low-quality results
Combine different search strategies: 
# 1. Broad search to find relevant nodes
node_results = await graphiti.search_(
    query="product recommendations",
    config=NODE_HYBRID_SEARCH_RRF
)

if node_results.nodes:
    # 2. Use top node as center for focused edge search
    center_node = node_results.nodes[0]
    
    edge_results = await graphiti.search_(
        query="product features",
        config=EDGE_HYBRID_SEARCH_NODE_DISTANCE,
        center_node_uuid=center_node.uuid
    )
    
    # 3. Display contextual results
    print(f"Recommendations related to {center_node.name}:")
    for edge in edge_results.edges:
        print(f"  - {edge.fact}")

​
Next Steps

Adding Episodes

Learn how to add content to your knowledge graph

Custom Entities

Define domain-specific entity types for better search

Build docs developers (and LLMs) love

Get started for freeTalk to us