# What Is Hybrid Search in GraphRAG Agent: A Complete Technical Guide

> Explore hybrid search in GraphRAG Agent, a powerful retrieval strategy combining Cypher and vector similarity for detailed entity retrieval and broad contextual understanding. Learn how it works.

- Repository: [GLK/graph-rag-agent](https://github.com/1517005260/graph-rag-agent)
- Tags: deep-dive
- Published: 2026-02-23

---

**Hybrid search in GraphRAG Agent is a dual-mode retrieval strategy that simultaneously executes keyword-driven Cypher queries against a Neo4j knowledge graph and dense vector similarity searches to capture both granular entity details and broad contextual passages.**

The `1517005260/graph-rag-agent` repository implements this sophisticated **hybrid search** mechanism through its `HybridAgent` class and underlying `HybridSearchTool`. By merging structured knowledge graph traversal with semantic vector retrieval, the system overcomes the limitations of single-mode search architectures that rely exclusively on either symbolic or neural retrieval methods.

## How Hybrid Search Works in GraphRAG Agent

### The Three Retrieval Components

The `HybridSearchTool` class in [`graphrag_agent/search/tool/hybrid_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/hybrid_tool.py) orchestrates three distinct search paths that execute in parallel or sequence:

**1. Keyword-Driven Graph Lookup**

The `extract_keywords` method parses user queries to identify salient entities, then the `db_query` method executes Cypher queries against the Neo4j knowledge graph. This retrieves low-level entity relationships and granular facts that vector search alone often misses.

**2. Vector-Based Similarity Search**

The `_vector_search` method performs dense-embedding nearest-neighbor lookups on the document store. This surfaces high-level topical passages that capture broader contextual knowledge beyond specific entity identifiers.

**3. Fallback Full-Text Search**

When vector search returns insufficient results, the `_fallback_text_search` method executes a BM25-style text search as a safety net. This ensures comprehensive coverage even when semantic embeddings fail to align with the query intent.

### Result Merging and Ranking

After executing these parallel retrieval paths, the hybrid search pipeline merges the result sets and applies intelligent ranking—often through LLM-based re-scoring—to produce a single coherent answer set. The `HybridCacheBackend` stores both vector and graph results, accelerating repeated queries through a thread-safe in-memory store with optional disk persistence.

## System Architecture and Integration

### Agent Layer Implementation

The `HybridAgent` class in [`graphrag_agent/agents/hybrid_agent.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/agents/hybrid_agent.py) instantiates `HybridSearchTool` and forwards user prompts to it. This agent serves as the primary interface for hybrid retrieval operations, abstracting the complexity of the three-path retrieval mechanism.

### Tool Registry and Reusability

The `HybridSearchTool` is registered in [`graphrag_agent/search/tool_registry.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool_registry.py) via the `get_tool_class` function. This allows other agents—such as the DeepResearch agent—to dynamically import and reuse the keyword extraction capabilities without instantiating the full hybrid pipeline.

### Caching Infrastructure

Results are cached by the `HybridCacheBackend` in [`graphrag_agent/cache_manager/backends/hybrid.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/cache_manager/backends/hybrid.py). This backend delegates to a thread-safe in-memory store and optional disk persistence, specifically optimized to store both vector embeddings and graph query results for rapid retrieval.

### Service Endpoint

The FastAPI service in [`server/services/agent_service.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/services/agent_service.py) dispatches HTTP requests to the appropriate agent, including the hybrid variant, enabling RESTful access to the hybrid search functionality across the system.

## Practical Implementation Examples

### Using the HybridAgent Directly

```python
from graphrag_agent.agents.hybrid_agent import HybridAgent

# Initialise the agent (the base class handles cache configuration)

agent = HybridAgent()

# Simple question – the agent will run hybrid search under the hood

response = agent.run("What are the eligibility criteria for the national scholarship?")

print(response)

```

*Source*: [`graphrag_agent/agents/hybrid_agent.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/agents/hybrid_agent.py)

### Calling the HybridSearchTool Alone

```python
from graphrag_agent.search.tool.hybrid_tool import HybridSearchTool

tool = HybridSearchTool()

# Low‑level + high‑level retrieval

result = tool.search({
    "query": "Explain the process of student loan repayment in China",
    "top_k": 5
})

print(result["answer"])

```

*Source*: [`graphrag_agent/search/tool/hybrid_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/hybrid_tool.py) – `search` method

### Registering the Tool for Reuse in Other Agents

```python
from graphrag_agent.search.tool_registry import get_tool_class

HybridTool = get_tool_class("hybrid_search")
hybrid_search = HybridTool()

# Re‑use the keyword extractor in a validation routine

keywords = hybrid_search.extract_keywords("What is the policy for undergraduate leave?")
print(keywords)

```

*Source*: [`graphrag_agent/search/tool_registry.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool_registry.py)

## Summary

- **Hybrid search** in GraphRAG Agent combines keyword-driven graph queries, vector similarity search, and fallback full-text retrieval to maximize answer accuracy and coverage.
- The `HybridSearchTool` in [`graphrag_agent/search/tool/hybrid_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/hybrid_tool.py) orchestrates three retrieval paths: `extract_keywords`/`db_query` for Neo4j graph lookup, `_vector_search` for dense embeddings, and `_fallback_text_search` for BM25-style backup.
- The `HybridAgent` wraps this functionality, while the `HybridCacheBackend` accelerates repeated queries through intelligent caching of both vector and graph results.
- This dual-mode retrieval captures both granular entity relationships from the knowledge graph and broad contextual passages from vector stores, overcoming the limitations of single-mode search systems.

## Frequently Asked Questions

### What makes hybrid search different from standard RAG?

Standard RAG typically relies solely on vector similarity to retrieve context passages. **Hybrid search** augments this with structured graph traversal, using the `extract_keywords` method to pull specific entity relationships from Neo4j while the `_vector_search` method captures semantic similarity. This dual approach retrieves both precise factual details and broader topical context that pure vector search might miss.

### How does the fallback mechanism work when vector search fails?

When the `_vector_search` method in [`graphrag_agent/search/tool/hybrid_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/hybrid_tool.py) returns insufficient results, the system automatically triggers `_fallback_text_search`. This method executes a BM25-style full-text search across the document corpus, acting as a safety net to ensure comprehensive coverage even when dense embeddings fail to surface relevant passages.

### Can I use the hybrid search components independently?

Yes. While the `HybridAgent` provides a unified interface, you can import and use individual components from [`graphrag_agent/search/tool/hybrid_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/hybrid_tool.py). For example, you might call `extract_keywords` directly to power a validation routine in another agent, or invoke `_vector_search` separately for pure semantic retrieval. The `get_tool_class` function in [`graphrag_agent/search/tool_registry.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool_registry.py) facilitates dynamic component reuse across the system.

### Where are hybrid search results cached?

Results are stored by the `HybridCacheBackend` class in [`graphrag_agent/cache_manager/backends/hybrid.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/cache_manager/backends/hybrid.py). This backend maintains a thread-safe in-memory cache for hot data and optionally persists to disk for durability. It specifically handles both vector search results and graph query results, ensuring that repeated identical queries bypass the expensive retrieval pipeline and return instantly from cache.