Inspecting Hybrid Retrieval Context

See exactly what HYBRID_COMPLETION sends to the completion step, and shape it with retriever_specific_config

This guide shows you how to look inside SearchType.HYBRID_COMPLETION — the default search type — before it turns into a final answer, and how to shape which parts of that context are included.

Before You Start

• Be familiar with the main concepts of Recall.
• Complete the Understand Recall with RAG Completion guide to see the shared recall() parameters this guide builds on (query_text, datasets, only_context) in action.

Code in Action

import asyncio

import cognee
from cognee import SearchType

QUERY = "What did Alice and Bob work on together?"


async def main():
    await cognee.remember(
        [
            "Alice and Bob were PhD students in Berlin from 2021 to 2024.",
            "Alice and Bob worked on a paper together in 2023.",
            "Alice joined Cognee as a backend engineer in 2025.",
            "Bob joined Cognee as a data scientist in 2026.",
            "Alice and Bob worked together on some sections of the documentation of Cognee in 2026.",
            "New sections of the documentation are available since July 2026.",
        ],
        self_improvement=False,
    )

    context_passage_focused = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION,
        only_context=True,
        retriever_specific_config={
            "chunks_top_k": 5,
            "entities_top_k": 0,
            "facts_top_k": 0,
        },
    )
    print(context_passage_focused)

    context_entity_focused = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION,
        only_context=True,
        retriever_specific_config={
            "chunks_top_k": 0,
            "entities_top_k": 5,
            "max_edges_per_entity": 5,
            "facts_top_k": 0,
        },
    )
    print(context_entity_focused)

    context_fact_focused = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION,
        only_context=True,
        retriever_specific_config={
            "chunks_top_k": 0,
            "entities_top_k": 5,
            "max_edges_per_entity": 0,
            "facts_top_k": 5,
        },
    )
    print(context_fact_focused)

    context_balanced = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION,
        only_context=True,
        retriever_specific_config={
            "chunks_top_k": 2,
            "entities_top_k": 2,
            "max_edges_per_entity": 3,
            "facts_top_k": 2,
        },
    )
    print(context_balanced)

    answer = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.HYBRID_COMPLETION,
        retriever_specific_config={
            "chunks_top_k": 2,
            "entities_top_k": 2,
            "max_edges_per_entity": 3,
            "facts_top_k": 2,
        },
    )
    print(answer)


if __name__ == "__main__":
    asyncio.run(main())

The complete runnable script is on GitHub: examples/guides/hybrid_retrieval_recall.py.

What Just Happened

Each recall() call below sets only_context=True, and Steps 2-4 also set one or two retriever_specific_config limits to 0. A section’s *_top_k at 0 removes that section from the context entirely; a non-zero limit controls how many items of that section are included — a larger number produces a more detailed (and larger) context.

Step 1: Ingest the Example Dataset

await cognee.remember(
    [
        "Alice and Bob were PhD students in Berlin from 2021 to 2024.",
        "Alice and Bob worked on a paper together in 2023.",
        "Alice joined Cognee as a backend engineer in 2025.",
        "Bob joined Cognee as a data scientist in 2026.",
        "Alice and Bob worked together on some sections of the documentation of Cognee in 2026.",
        "New sections of the documentation are available since July 2026.",
    ],
    self_improvement=False,
)

A handful of sentences about Alice and Bob gives hybrid retrieval something to find — entities, a relationship between them, and the passages they come from.

Step 2: Passage-Focused Context

context_passage_focused = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION,
    only_context=True,
    retriever_specific_config={
        "chunks_top_k": 5,
        "entities_top_k": 0,
        "facts_top_k": 0,
    },
)
print(context_passage_focused)

With entities_top_k and facts_top_k at 0, context_passage_focused contains only matched passages — the raw text chunks that matched the query, combining lexical (keyword) and semantic (embedding) search, with no graph entities or derived facts.

Use this when you want to see raw supporting text without any graph-derived summarization — for example, to quote source text verbatim, or to debug retrieval quality without graph-derived noise in the way.

Step 3: Entity-Focused Context

context_entity_focused = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION,
    only_context=True,
    retriever_specific_config={
        "chunks_top_k": 0,
        "entities_top_k": 5,
        "max_edges_per_entity": 5,
        "facts_top_k": 0,
    },
)
print(context_entity_focused)

With chunks_top_k and facts_top_k at 0, context_entity_focused contains only matched entities — nodes from the graph (like Alice, Bob, Cognee) — and the edges connected to each one (capped by max_edges_per_entity), rendered as short sentences such as Alice contributed to documentation.

Use this when you care about which entities are connected and how, more than the exact wording of the source text.

Step 4: Fact-Focused Context

context_fact_focused = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION,
    only_context=True,
    retriever_specific_config={
        "chunks_top_k": 0,
        "entities_top_k": 5,
        "max_edges_per_entity": 0,
        "facts_top_k": 5,
    },
)
print(context_fact_focused)

The fact budget is tied to the entity lane, so the lane has to stay on for facts_top_k to apply — with entities_top_k at 0 no facts are returned. Keeping entities_top_k at 5 and setting max_edges_per_entity to 0 drops the per-entity edge bullets from Step 3, so context_fact_focused contains the matched entity names plus the compact, fact-style statements derived from graph edges, with no raw passages.

Use this when you want a small context — for example to get a quick relationship summary without the full passage text or the per-entity edge listings.

Step 5: Balanced Context

context_balanced = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION,
    only_context=True,
    retriever_specific_config={
        "chunks_top_k": 2,
        "entities_top_k": 2,
        "max_edges_per_entity": 3,
        "facts_top_k": 2,
    },
)
print(context_balanced)

All three sections are present in context_balanced, each capped at a small limit. This mirrors the default behavior, just with tighter limits — useful when you want a compact context that still draws on passages, entities, and facts together.

Generating the Final Answer

Every call above passes only_context=True, so recall() stops after assembling the context and never reaches the completion step. Drop only_context=True and recall() sends the assembled context to the LLM to generate a real answer instead:

answer = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.HYBRID_COMPLETION,
    retriever_specific_config={
        "chunks_top_k": 2,
        "entities_top_k": 2,
        "max_edges_per_entity": 3,
        "facts_top_k": 2,
    },
)
print(answer)

A typical result:

They worked on a paper in 2023 and on some sections of the Cognee documentation in 2026.

(The exact wording depends on the LLM provider you use.) This works the same way with any of the retriever_specific_config shapes from Steps 2-5 above — passage-focused, entity-focused, fact-focused, or balanced. The *_top_k limits keep their meaning in both cases: they are the per-section caps on what ends up in the context.

One difference between the two calls: dropping only_context=True also lets the call run as a full session turn. In the default concurrent session-search mode a session turn retrieves twice — once with your raw query_text and once with a rewrite that prefixes the last couple of question/answer turns in the session — and merges the two result sets per section under the same chunks_top_k / entities_top_k / facts_top_k caps. So on a follow-up question in an ongoing session, the answer’s context can differ from what the equivalent only_context=True call would have surfaced; on the first turn of a session — as in this guide — the two calls retrieve identically. See Session-context guidance for the full merge behavior and how to switch back to sequential.

Recall

Understand recall()‘s full parameter surface and auto-routing behavior

SearchType

See every search type and its retriever_specific_config options