Summary

The bfs_max_depth parameter in BFS search configurations is completely ignored, causing BFS searches to always traverse 1-3 hops regardless of the specified depth limit.

What I was trying to do

I was attempting to perform a breadth-first search with bfs_max_depth=1 to find only direct neighbors (1-hop relationships) of a center node.

What I expected to happen

When setting bfs_max_depth=1, the BFS search should only return nodes and edges that are exactly 1 hop away from the center node.

What actually happened

The BFS search returned nodes and edges up to 3 hops away from the center node, completely ignoring the bfs_max_depth=1 setting.

Root Cause

The Cypher queries in both node_bfs_search and edge_bfs_search functions have hardcoded path lengths of {1,3} instead of using the bfs_max_depth parameter.

Code Analysis

In graphiti_core/search/search_utils.py:

Node BFS Query (line ~450):

MATCH (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,3}(n:Entity)

Edge BFS Query (line ~295):

MATCH path = (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,3}(n:Entity)

Problem: Both queries use hardcoded {1,3} instead of using the bfs_max_depth parameter.

Parameter is passed but unused:

records, _, _ = await driver.execute_query(
    query,
    params=filter_params,
    bfs_origin_node_uuids=bfs_origin_node_uuids,
    depth=bfs_max_depth,  # ← This parameter is passed but never used in the query
    group_ids=group_ids,
    limit=limit,
    routing_='r',
)

Code Sample Demonstrating the Issue

from graphiti_core.search.search_config import (
    SearchConfig, 
    NodeSearchConfig, 
    NodeSearchMethod,
    NodeReranker
)

# Configuration specifying max depth of 1
config = SearchConfig(
    node_config=NodeSearchConfig(
        search_methods=[NodeSearchMethod.bfs],
        reranker=NodeReranker.rrf,
        bfs_max_depth=1  # Should only search 1 hop
    )
)

# This search will return nodes up to 3 hops away, not 1
results = await graphiti.search(
    query="test",
    config=config,
    center_node_uuid="some-center-node-uuid",
    group_ids=["test-group"]
)

# Expected: Only direct neighbors (1 hop)
# Actual: Neighbors up to 3 hops away

Expected Fix

The Cypher queries should use the bfs_max_depth parameter:

Node BFS Query:

MATCH (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,$depth}(n:Entity)

Edge BFS Query:

MATCH path = (origin:Entity|Episodic {uuid: origin_uuid})-[:RELATES_TO|MENTIONS]->{1,$depth}(n:Entity)

Additional Context

This bug affects:

• node_bfs_search() in graphiti_core/search/search_utils.py (line ~429)
• edge_bfs_search() in graphiti_core/search/search_utils.py (line ~278)

The impact is that users cannot control the depth of BFS traversal, leading to:

1. Performance issues when expecting shallow searches
2. Incorrect results when precise depth control is needed
3. Confusion about why the bfs_max_depth parameter appears to do nothing

Environment

• Graphiti Version: Latest main branch
• Database: Neo4j (also affects FalkorDB)
• Python Version: 3.10+

Severity

Medium - Feature completely non-functional, but workarounds exist (custom queries)

Labels

• bug
• search
• bfs
• help wanted