Reading the Global Context Index

This guide shows you what changes in recall()’s output when include_global_context_index=True is set — both in the retrieved context and in the final generated answer.

Before You Start

Complete Quickstart to understand basic operations
Ensure you have LLM Providers configured
Complete Building the Global Context Index first — this guide assumes an index already exists and does not re-explain how it’s built
Be familiar with recall()

Code in Action

import asyncio

import cognee
from cognee import SearchType

DATASET = "global_context_index_recall_demo"

FACTS = [
    "Alice hiked a new trail near Lake Como in winter.",
    "Alice reached the summit of the peak she'd trained for all year in summer.",
    "Bob sailed to a small island he had never visited in winter.",
    "Bob completed his first solo overnight crossing in summer.",
    "Alice started a sourdough starter in winter.",
    "Alice baked her first focaccia for a dinner party in summer.",
    "Bob took his first watercolor class in winter.",
    "Bob sold a painting at a local market in summer.",
    "Alice began German lessons in winter.",
    "Alice had her first full conversation in German in summer.",
]

QUERY = "What changed across all of Alice and Bob's hobbies between winter and summer?"


async def main():
    await cognee.remember(
        FACTS,
        dataset_name=DATASET,
        self_improvement=False,
    )
    await cognee.improve(dataset=DATASET, build_global_context_index=True)

    context_without = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET],
        top_k=4,
        only_context=True,
        retriever_specific_config={"include_global_context_index": False},
    )
    context_with = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET],
        top_k=4,
        only_context=True,
        retriever_specific_config={
            "include_global_context_index": True,
            "global_context_index_top_k": 3,
        },
    )

    print("Context WITHOUT global context index:\n")
    print(context_without[0].text)
    print("\nContext WITH global context index:\n")
    print(context_with[0].text)

    answer_without = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET],
        top_k=4,
        retriever_specific_config={"include_global_context_index": False},
    )
    answer_with = await cognee.recall(
        query_text=QUERY,
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET],
        top_k=4,
        retriever_specific_config={
            "include_global_context_index": True,
            "global_context_index_top_k": 3,
        },
    )

    print("\nAnswer WITHOUT global context index:\n")
    print(answer_without[0].text)
    print("\nAnswer WITH global context index:\n")
    print(answer_with[0].text)


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

What Just Happened

Step 1: Ingest a Multi-Hobby Dataset

await cognee.remember(
    FACTS,
    dataset_name=DATASET,
    self_improvement=False,
)

Ten facts, two per hobby across five hobbies (hiking, sailing, baking, watercolor painting, German lessons) shared between Alice and Bob, each with a winter and a summer update. This is enough that a single retrieval pass can’t hold every hobby’s triplets at once — exactly the condition where the global context index has real work to do.

Step 2: Build the Index

await cognee.improve(dataset=DATASET, build_global_context_index=True)

Same mechanism as Building the Global Context Index — see that guide for how the per-document buckets and the root are built, without an LLM call. This guide only needs the finished index.

Step 3: Compare the Retrieval Context in the Prompt

context_without = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=[DATASET],
    top_k=4,
    only_context=True,
    retriever_specific_config={"include_global_context_index": False},
)
context_with = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=[DATASET],
    top_k=4,
    only_context=True,
    retriever_specific_config={
        "include_global_context_index": True,
        "global_context_index_top_k": 3,
    },
)

top_k=4 deliberately restricts local retrieval to fewer triplets than the dataset has hobbies — low enough that local retrieval cannot reach every hobby. only_context=True skips the LLM call and returns what the LLM would have received: each result’s .text is the user prompt — the conversation history, then the question and the retrieval context rendered through the retriever’s template, then the session guidance block — while the system prompt sits on the result’s separate system_prompt field, which the script never prints. (Nothing in this script writes to a session before Step 3, so the history and guidance layers have nothing to contribute and what you see is effectively the question and the context — which is why the script’s Context WITHOUT … print labels still read sensibly.) Inside the prompt, both calls carry the exact same Nodes: / Connections: block: include_global_context_index never changes which local triplets get selected, only what gets prepended before them. The only difference here is that World summary: and Relevant areas: appear only in the second call. See Inspecting the LLM input for the full shape. As Global Context Index explains, this feature is meant for datasets large enough that local retrieval genuinely can’t hold everything relevant — long documents, project memory spanning many updates, policy corpora with many sections. Ten facts across five hobbies is nowhere near that scale on its own; the only reason it behaves like a large dataset here is that we’ve deliberately shrunk top_k to 4, well below what a real deployment would use. That’s an artificial constraint chosen to make the effect visible in a guide-sized example, not a recommendation to run production workloads with top_k this low. The root itself isn’t a way around this at any scale, either: World summary is a capped list of names — at most 20 entity types, the 40 names that appear in the most documents, and 40 document names — so on a genuinely large dataset it can’t list every fact. At real scale, expect the root to preserve which topics and widely shared names exist, while document-specific details are more likely to show up in Relevant areas instead — each bucket names its own document’s most distinctive entities and the relations among them.

Step 4: Compare the Generated Answers

answer_without = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=[DATASET],
    top_k=4,
    retriever_specific_config={"include_global_context_index": False},
)
answer_with = await cognee.recall(
    query_text=QUERY,
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=[DATASET],
    top_k=4,
    retriever_specific_config={
        "include_global_context_index": True,
        "global_context_index_top_k": 3,
    },
)

With top_k=4, the local retrieval in Step 3 surfaces only a few of the ten facts, and that local set is identical either way. Two runs of this script gave:

	Without the index	With the index
Run 1: hobbies the answer mentions (of 5)	3	4
Run 2: hobbies the answer mentions (of 5)	4	4

The index changes less here than you might expect. World summary does name every hobby, including the watercolor class and the small island the local triplets miss, because the root is built once over every document and doesn’t compete for a spot in top_k. But the root lists bare entity names, not what happened to them, so the model learns that a watercolor class exists without learning when or how it changed. The season-by-season facts reach the prompt only through Relevant areas, and global_context_index_top_k=3 brings in just three documents’ buckets. In both runs those buckets were mostly Alice’s winter documents, so neither answer could describe a winter-to-summer change for most hobbies.

This is real output from two runs against an LLM, so if you run it yourself, expect the wording and the counts to differ. LLM generation isn’t deterministic, and top_k=4 is a hard cutoff on vector similarity scores, so a fact near that boundary can land on either side of it from one call to the next. The takeaway is that the index tells the model what the dataset covers; it does not carry the facts themselves. For a question that needs facts from every document, raise top_k or global_context_index_top_k.

Under the Hood

How recall() Actually Reads the Index

The root is loaded, never searched: a dataset has at most one root GlobalContextSummary, and recall() loads it straight from the graph — filtering the dataset’s GlobalContextSummary nodes for the one flagged is_root — instead of running a vector search for it. This becomes the World summary: line.
“Relevant areas” comes from one flat vector search: every non-root bucket lives in the same vector collection, re-embedded whenever a build changes its text. Finding the global_context_index_top_k “Relevant areas” is a single vector search across that whole collection, comparing every bucket directly against the query — not a walk down from the root through parent-child links.
Why top_k doesn’t affect the index: top_k only bounds the local triplet search (Step 3). The root load and the bucket vector search are separate lookups that always run in full, regardless of how restrictive top_k is — that decoupling is why World summary names every hobby in Step 4 even though local retrieval reaches only a few.
HYBRID_COMPLETION honors this too: the same include_global_context_index flag works with SearchType.HYBRID_COMPLETION, which places the same prelude under a ## Global context heading at the top of its context block instead of a World summary: line.

Global Context Index

The full concept, configuration options, and when to use it

Building the Global Context Index

Build the index and see it update incrementally

Recall

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

Getting Started

Core Concepts

Setup Configuration

Guides

Cookbooks

Examples

CLI

OSS

Before You Start

Code in Action

What Just Happened

Step 1: Ingest a Multi-Hobby Dataset

Step 2: Build the Index

Step 3: Compare the Retrieval Context in the Prompt

Step 4: Compare the Generated Answers

Under the Hood

Global Context Index

Building the Global Context Index

Recall

​Before You Start

​Code in Action

​What Just Happened

​Step 1: Ingest a Multi-Hobby Dataset

​Step 2: Build the Index

​Step 3: Compare the Retrieval Context in the Prompt

​Step 4: Compare the Generated Answers

​Under the Hood

Global Context Index

Building the Global Context Index

Recall

Before You Start

Code in Action

What Just Happened

Step 1: Ingest a Multi-Hobby Dataset

Step 2: Build the Index

Step 3: Compare the Retrieval Context in the Prompt

Step 4: Compare the Generated Answers

Under the Hood