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 bucket/root hierarchy actually forms. This guide only needs the finished index.

Step 3: Compare the Retrieved Context

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 to make the effect in Step 4 obvious. Both calls retrieve 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. 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 capped at a fixed token budget (the prompt that generates it caps output at 500 tokens), so on a genuinely large dataset it can’t just list every fact losslessly — it has to compress. At real scale, expect the root to reliably preserve which hobbies and topics exist (cheap to list) while individual details, like a specific summer milestone, are more likely to survive in Relevant areas instead — the vector-matched, topic-specific bucket summaries have their own budget per bucket, so they carry more per-topic detail than one root summary stretched across everything.

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,
    },
)

This is where the difference stops being cosmetic. With top_k=4, the local retrieval in Step 3 can only surface a fraction of the dataset’s triplets — and since that local set is identical either way, the generated answer without the index inherits that gap directly:

	Without the index	With the index
Hobbies covered (of 5)	2	5
Hobbies missing entirely	German lessons, baking, sailing	none

The answer without the index only mentions hiking and watercolor painting — it never mentions Alice’s German lessons, never mentions her sourdough baking, and never mentions Bob’s sailing, three of the five hobbies vanish. The answer with the index names all five and still tracks each one’s winter-to-summer progression, because World summary is built once over every TextSummary in the dataset — it doesn’t compete for a spot in top_k the way local triplets do.

This is real output from one run against an LLM, so if you run it yourself, expect the wording and the exact count of missing hobbies to differ — LLM generation isn’t deterministic, and top_k=4 is a hard cutoff on vector similarity scores, so a hobby hovering right at that boundary can land on either side of it from one call to the next. The pattern is what’s stable and worth taking away: some hobbies reliably vanish without the index, and none do with it — not the specific count above. Raising top_k high enough eventually closes this particular gap on its own; the index is what keeps working when you can’t or don’t want to raise it that far.

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, embedded when it was created. 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 exactly why the index keeps covering every hobby in Step 4 even as local retrieval covers fewer and fewer.
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

Examples

CLI

Rust SDK

TypeScript SDK

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 Retrieved Context

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 Retrieved Context

​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 Retrieved Context

Step 4: Compare the Generated Answers

Under the Hood