> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Reading the Global Context Index
> See exactly what include_global_context_index adds to GRAPH_COMPLETION retrieval
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](/getting-started/quickstart) to understand basic operations
* Ensure you have [LLM Providers](/setup-configuration/llm-providers) configured
* Complete [Building the Global Context Index](/guides/global-context-index) first — this guide assumes an index already exists and does not re-explain how it's built
* Be familiar with [`recall()`](/core-concepts/main-operations/recall)
## Code in Action
```python theme={null}
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
```python theme={null}
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
```python theme={null}
await cognee.improve(dataset=DATASET, build_global_context_index=True)
```
Same mechanism as [Building the Global Context Index](/guides/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
```python theme={null}
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](/core-concepts/further-concepts/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
```python theme={null}
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
* **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.
The full concept, configuration options, and when to use it
Build the index and see it update incrementally
Understand recall()'s full parameter surface and auto-routing behavior