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:

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

The index groups TextSummary nodes, not raw DocumentChunk nodes directly.

What retrieval adds

Two search types read the index: GRAPH_COMPLETION and HYBRID_COMPLETION. 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:

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:

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.

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

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.

How the summaries are generated

Each bucket and root summary is written by one structured-output call to the main configured LLM (LLM_MODEL), which receives the child summaries as input. LLM_SUMMARIZATION_* does not change the model that writes them. Every summary is expected to have two sections: a category list headed This dataset is about: (This area of the dataset is about: for buckets), followed by a Facts: list.

The root summary contains model commentary instead of a summary

If the root or a bucket holds text such as [No explicit summary needed; we just need to produce the final answer] instead of the This dataset is about: and Facts: sections, the model wrote its own reasoning or commentary into the summary.

Point LLM_MODEL at a model that returns clean structured output (see LLM Providers). Then regenerate the index. Running improve() again does not fix it, because the root is only regenerated when new TextSummary nodes are placed below it. To rebuild every bucket and the root from scratch, call the lower-level index pipeline directly. Pass bucketing_strategy="graph" and max_bucket_size=4 to match what improve() uses; the pipeline’s own defaults differ, and later improve() runs cannot extend an index built with a different strategy:

from cognee.memify_pipelines.global_context_index import global_context_index_pipeline
from cognee.modules.users.methods import get_default_user

await global_context_index_pipeline(
    user=await get_default_user(),
    dataset="product_docs",
    rebuild=True,
    bucketing_strategy="graph",
    max_bucket_size=4,
)

Use it during search

Enable it through retriever_specific_config on graph completion search:

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 to the LLM, use only_context=True — for a completion search type the result’s text is the full user prompt, with the World summary: and Relevant areas: prelude inside it:

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

Scope to a dataset

Each index belongs to exactly one dataset. improve(dataset=...) builds it for that dataset only, and every GlobalContextSummary node it writes stores that dataset’s dataset_id.

To choose which dataset’s summary retrieval uses, pass that dataset in datasets=[...] on recall(). Each listed dataset is searched in its own database context, so the World summary and Relevant areas come from that dataset’s root and buckets. This scoping relies on backend access control, which gives each dataset its own graph and vector stores. It is on by default when your databases support it. When ENABLE_BACKEND_ACCESS_CONTROL=false, all datasets share one graph and one GlobalContextSummary_text collection, and retrieval does not filter by dataset.

To read one dataset’s root summary directly, enter that dataset’s database context and filter its graph nodes:

import cognee
from cognee.context_global_variables import set_database_global_context_variables
from cognee.infrastructure.databases.graph import get_graph_engine

datasets = await cognee.datasets.list_datasets()
dataset = next(d for d in datasets if d.name == "product_docs")

async with set_database_global_context_variables(dataset.id, dataset.owner_id):
    graph_engine = await get_graph_engine()
    nodes, _edges = await graph_engine.get_graph_data()

root_text = next(
    (
        props.get("text")
        for _node_id, props in nodes
        if props.get("type") == "GlobalContextSummary"
        and str(props.get("is_root")).lower() == "true"
        and props.get("dataset_id") == str(dataset.id)
    ),
    None,
)

Unlike recall(), this dataset_id filter still returns the right root when access control is off and datasets share one graph.

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.

Building the Global Context Index

A runnable guide: build the index, inspect its root/bucket structure, and see it update incrementally as new data arrives.

Reading the Global Context Index

A runnable guide: see exactly what include_global_context_index adds to GRAPH_COMPLETION retrieval, and what stays the same.