> ## 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.

# Global Context Index

> Build dataset-level summaries to improve graph completion retrieval.

The **global context index** is an optional summary layer that helps Cognee answer questions that depend on the broader shape of a dataset, not only the closest graph facts.

Normal graph retrieval is local: Cognee searches for graph edges, chunks, summaries, and entities that match the query. That works well when the answer is near a few specific facts. The global context index adds a higher-level map: semantic buckets of `TextSummary` nodes and a root summary of the dataset. A **bucket** is a generated summary that groups a handful of `TextSummary` nodes — or, at higher levels, other buckets — into one combined summary. The **root** is the single summary at the very top of that structure, covering the whole dataset.

## Why use it

Use the global context index when answers often depend on document-wide or dataset-wide context:

* long documents where important details are spread across chapters or sections
* evolving conversations where the final state depends on earlier updates
* project memory where the answer needs the overall plan, risks, and current status
* policy or research corpora where local facts need broader framing

It is most useful when you want retrieval to include both:

* **local evidence** from the graph
* **global orientation** from compact dataset summaries

## How it works

During normal ingestion and enrichment, Cognee creates `DocumentChunk` and `TextSummary` datapoints. The global context index adds the `GlobalContextSummary` layers shown inside the dashed lines:

```text theme={null}
--------------------------------------------------
root GlobalContextSummary
  -> optional higher-level GlobalContextSummary bucket
    -> GlobalContextSummary bucket
--------------------------------------------------
      -> TextSummary
        -> DocumentChunk
```

The build process is bottom-up, starting from `TextSummary` nodes. The retrieval hierarchy is top-down, starting from the root summary.

<Note>
  The index groups `TextSummary` nodes, not raw `DocumentChunk` nodes directly.
</Note>

## What retrieval adds

Two search types read the index: [`GRAPH_COMPLETION`](/python-api/search-type) and [`HYBRID_COMPLETION`](/python-api/search-type). Other search types ignore `include_global_context_index`, including the graph completion variants such as `GRAPH_COMPLETION_COT` and `GRAPH_COMPLETION_DECOMPOSITION`.

When enabled, Cognee prepends a global context prelude before the usual retrieved context:

```text theme={null}
World summary:
...

Relevant areas:
...

<normal graph context follows>
```

The **World summary** comes from the root `GlobalContextSummary`. The **Relevant areas** are the top matching non-root `GlobalContextSummary` bucket texts for the query.

This gives the model a compact map before it reads the local graph facts. `HYBRID_COMPLETION` places the same prelude under a `## Global context` heading at the top of its context block.

## Build the index

The index is opt-in. Build it after memory has been created:

```python theme={null}
await cognee.improve(
    dataset="product_docs",
    build_global_context_index=True,
)
```

`improve()` first runs the normal enrichment pass, then builds the global context index. It groups up to 4 children per bucket and uses entity-overlap (graph) bucketing for the bottom level, adding levels until the topmost level fits under the root.

Later `improve()` runs update the index incrementally: only newly added `TextSummary` nodes — ones not yet assigned to a bucket — are placed into existing buckets, and the root is regenerated whenever new placements occur below it.

<Warning>
  `build_global_context_index=True` is skipped when `run_in_background=True`, because ordered background pipeline chaining is not currently supported for this step.
</Warning>

<Note>
  If the build itself fails, `improve()` logs a warning and still returns successfully — the index is simply absent, and search falls back to normal graph context.
</Note>

## Use it during search

Enable it through `retriever_specific_config` on graph completion search:

```python theme={null}
from cognee import SearchType

results = await cognee.recall(
    query_text="What is the current state of the rollout plan?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=["product_docs"],
    retriever_specific_config={
        "include_global_context_index": True,
        "global_context_index_top_k": 3,
    },
)
```

To inspect exactly what will be sent as context, use `only_context=True`:

```python theme={null}
context = await cognee.recall(
    query_text="What changed after the second meeting?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=["product_docs"],
    only_context=True,
    retriever_specific_config={
        "include_global_context_index": True,
        "global_context_index_top_k": 3,
    },
)
```

## Configuration

| Option                         | Default | Where it is used            | What it does                                                                         |
| ------------------------------ | ------: | --------------------------- | ------------------------------------------------------------------------------------ |
| `build_global_context_index`   | `False` | `cognee.improve()`          | Builds the bucket and root summaries after enrichment.                               |
| `include_global_context_index` | `False` | `retriever_specific_config` | Prepends global context during `GRAPH_COMPLETION` and `HYBRID_COMPLETION` retrieval. |
| `global_context_index_top_k`   |     `3` | `retriever_specific_config` | Number of non-root bucket summaries to include as relevant areas.                    |

## Benefits and tradeoffs

The main benefit is better long-range coherence. The model can see a compact summary of the dataset before it reasons over the retrieved graph context. This can reduce failures where local retrieval finds a relevant fragment but misses the broader story.

The tradeoff is that the index is lossy. A bucket summary is an orientation aid, not a replacement for source chunks or graph facts. The most reliable answers still come from combining global context with precise retrieved evidence.

Building the index also adds work. Cognee makes one structured LLM call per bucket it creates or updates, at every level, plus one more for the root summary, and embeds each `GlobalContextSummary` into its own vector collection. The first build is the expensive one; because later runs only place newly added `TextSummary` nodes, incremental updates cost far less.

At search time the cost is small and fixed: one lookup for the root summary and one vector search for the top `global_context_index_top_k` buckets, plus the extra prompt tokens the prelude adds.

## When not to use it

You may not need the global context index when:

* your dataset is small enough that normal retrieval already has enough context
* queries are mostly simple fact lookups
* you need the fastest possible enrichment pass
* you want retrieval context to contain only direct local graph evidence

For small datasets, start without it. Add it when you see questions that need broader orientation or multi-part memory.

<Columns cols={2}>
  <Card title="Building the Global Context Index" icon="globe" href="/guides/global-context-index">
    A runnable guide: build the index, inspect its root/bucket structure, and see it update incrementally as new data arrives.
  </Card>

  <Card title="Reading the Global Context Index" icon="search" href="/guides/global-context-index-recall">
    A runnable guide: see exactly what include\_global\_context\_index adds to GRAPH\_COMPLETION retrieval, and what stays the same.
  </Card>
</Columns>