Entity Consolidation

Rewrite entity descriptions, summarize each entity type from its members, and write searchable is_a edge text

A minimal guide to consolidating entity descriptions in an existing knowledge graph. After ingestion, entity descriptions can be fragmented or repetitive because each one is derived from a single chunk — this lower-level Memify pipeline rewrites them using the LLM and the entity’s full neighborhood context. Use improve() for the standard self-improvement flow; use this guide when you specifically want entity-description consolidation.

consolidate_entity_descriptions_pipeline() is deprecated and emits a DeprecationWarning when called. For Entity descriptions, cognee now recommends improve(review_conflicts=True), which reviews each entity’s facts against the documents and dates they came from instead of rewriting its description. See the review_conflicts.py example.

The pipeline runs in three stages:

1. Rewrite entities — each Entity description is regenerated from that entity’s neighbors and edges.
2. Summarize types — each EntityType description is regenerated from its actual member entities (their rewritten descriptions and the total member count), not from the type name alone.
3. Write is_a edge text — every member gets one short line blending its own facts with the finished type summary, stored as edge_text on its is_a edge.

This pipeline only rewrites text — it never creates or deletes nodes. It updates Entity descriptions, EntityType descriptions, and the text on existing is_a edges, all in place. To merge near-duplicate Entity nodes into one, see Entity Deduplication.

Before You Start

• Complete Quickstart to understand basic operations
• Ensure you have LLM Providers configured
• Have an existing knowledge graph with Entity nodes — the script below builds one with remember()

Code in Action

import asyncio
from os import path

import cognee
from cognee import visualize_graph
from cognee.memify_pipelines.consolidate_entity_descriptions import (
    consolidate_entity_descriptions_pipeline,
)

custom_prompt = """
Extract only people and cities as entities.
Connect people to cities with whatever relationship the text actually
describes (e.g. born_in, lives_in, resides_in, settled_in, visited).
Ignore all other entities.
"""

graph_visualization_path_before_enrichment = path.join(
    path.dirname(__file__), ".artifacts", "before_consolidate_enrichment_entity_descriptions.html"
)
graph_visualization_path_after_enrichment = path.join(
    path.dirname(__file__), ".artifacts", "after_consolidate_enrichment_entity_descriptions.html"
)


async def main():
    # Prune data and system metadata before running, only if we want "fresh" state.
    await cognee.forget(everything=True)
    await cognee.remember(
        [
            "Alice moved to Paris in 2010, while Bob has always lived in New York.",
            "Bob visited Paris in 2015 to see Alice.",
            "Andreas was born in Venice, but later settled in Lisbon.",
            "Diana and Tom were born and raised in Helsinki. Diana currently resides in Berlin, while Tom never moved.",
        ],
        custom_prompt=custom_prompt,
        self_improvement=False,
    )

    await visualize_graph(graph_visualization_path_before_enrichment)

    await consolidate_entity_descriptions_pipeline()

    await visualize_graph(graph_visualization_path_after_enrichment)

    # Only recall() can prove the new EntityType/is_a text is actually used in
    # retrieval - the description and edge text themselves are visible in the
    # graph visualization above.
    answer = await cognee.recall(
        "How many Person entities are in this graph, and what do they have in common?"
    )
    print(answer)


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

What Just Happened

Step 1: Clear Existing Data

await cognee.forget(everything=True)

Start from a clean state so the before-and-after visualizations only reflect this example run.

Step 2: Build and Visualize the Graph

custom_prompt = """
Extract only people and cities as entities.
Connect people to cities with whatever relationship the text actually
describes (e.g. born_in, lives_in, resides_in, settled_in, visited).
Ignore all other entities.
"""

await cognee.remember(
    [
        "Alice moved to Paris in 2010, while Bob has always lived in New York.",
        "Bob visited Paris in 2015 to see Alice.",
        "Andreas was born in Venice, but later settled in Lisbon.",
        "Diana and Tom were born and raised in Helsinki. Diana currently resides in Berlin, while Tom never moved.",
    ],
    custom_prompt=custom_prompt,
    self_improvement=False,
)
await visualize_graph(graph_visualization_path_before_enrichment)

Create a focused graph with only people and cities, letting the extraction name whatever relationship each sentence describes, then save a visualization of the graph before consolidation. Varied relationship names and a second sentence about Bob give the consolidation stage real neighborhood context to work with — an entity reached by two different edges contributes one prompt line per edge, not one per neighbor.

The entities and types from a real run, before consolidation. Hover a node: every description is a single-chunk fragment such as “Person mentioned in the text.”, and every is_a edge says only “alice is a person.”

Only the Entity and EntityType nodes and the edges between them are shown — the document, chunk, and summary nodes are not touched by this pipeline.

Step 3: Consolidate and Visualize Again

await consolidate_entity_descriptions_pipeline()
await visualize_graph(graph_visualization_path_after_enrichment)

The pipeline runs its three stages against the existing graph — no nodes are created or deleted:

• Each Entity node’s description is rewritten in place from that entity’s neighbors and edges, so descriptions become more coherent than the single-chunk text they came from.
• Each EntityType node’s description is rewritten from its member entities. The summary always states the total member count; at or below 5 members it names them individually, above that it deliberately does not (see type_max_named_members below).
• Each member’s is_a edge gets edge_text in the form {Name} is a {Type}: {facts placing that member against the type summary}.

The before and after HTML files make all three changes easy to inspect, and so does the same graph after the run:

The same 13 nodes and 23 edges after consolidation. Nothing was added or removed; hover a node to see the rewritten description, and hover person or city to see the type summary built from its members.

Bob’s description now reads as one coherent sentence about a lifelong New York resident who visited Paris, the person type states that it has five members and names each with a distinguishing fact, and Bob’s is_a edge carries “bob is a person: the lifelong New York resident who has always lived in New York and visited Paris in 2015.”

Step 4: Recall Against the Enriched Graph

answer = await cognee.recall(
    "How many Person entities are in this graph, and what do they have in common?"
)
print(answer)

The graphs above show the new text; recall() shows it being used. Graph retrieval indexes an edge’s edge_text and surfaces it alongside the relationship label, so the is_a lines written in stage 3 — and the member-count and shared-facts claims in the type summary — become part of the retrieved context instead of the bare token is_a.

Example output

There are five Person entities: Alice, Bob, Diana, Tom, and Andreas. They are all people (Person entities) and each is associated with a city (a birthplace and/or a residence).

Wording varies by provider and model, but the member count comes straight from the person type summary written in stage 2.

Advanced Usage

• Runnable guide script available on our GitHub
• Pipeline implementation: consolidate_entity_descriptions.py

Under the hood

The tasks live in cognee.tasks.memify.consolidate_entity_descriptions. Four run in sequence:

1. get_entities_with_neighborhood (extraction) — loads all Entity nodes and fetches their incident edges, edge text, and neighbor nodes. An entity’s types are the outgoing is_a edges that land on an EntityType node; an entity can have more than one.
2. generate_consolidated_entities — sends each entity plus its neighborhood to the LLM, which returns a refined description.
3. generate_type_descriptions — groups the rewritten entities by type, summarizes each group, then writes the is_a edge text for every member. The summary and the is_a lines are separate LLM calls: above the naming threshold the summary must not name members, while every is_a line must start with one.
4. add_data_points — writes the updated Entity and EntityType objects, and the is_a edge text, back to the graph and vector DB.

Failures are contained rather than fatal, because add_data_points runs last and raising would discard the whole run: an entity whose rewrite call fails keeps the description it already had (so its type’s member count stays accurate), and a type whose calls fail is left unsummarized while every other type still lands.

A type with more members than fit in one prompt is summarized in batches, and the partial summaries are then merged by a further LLM call into the single final summary. Batching is internal — you always pass the full graph, never the batches.

Tuning

consolidate_entity_descriptions_pipeline() takes no required arguments. Beyond user, dataset, and run_in_background (all forwarded to memify()), every size and budget cap is overridable per call:

Parameter	Default	What it caps
entity_max_concurrent_calls	10	Concurrent LLM calls while rewriting entity descriptions
entity_max_neighbor_lines	20	Neighborhood lines in one entity’s prompt — a neighbor linked by several edges contributes one line per edge
entity_max_neighbor_text_chars	500	Characters of text shown per neighbor
entity_description_max_completion_tokens	2250	Output budget for the entity description call
type_max_concurrent_calls	10	Concurrent LLM calls while summarizing types — bounds every individual call, not just how many types run at once
type_max_members_per_batch	50	Members shown in one type-summary prompt before batching and merging kick in
type_max_named_members	5	At or below this member count the summary names members individually; above it, it must not
type_max_persisted_is_a_chars	500	Characters of is_a edge text actually written to the graph
type_description_max_completion_tokens	2250	Output budget for the type-summary and merge calls
type_tokens_per_is_a_line	60	Per-member output budget for the is_a call, which returns one line per member rather than a paragraph

These are defensive backstops against pathological inputs — an unusually long description, an over-connected entity, a huge type — not per-model token budgets. Cognee is model-agnostic, so override them at the call site if your data or model needs something different, rather than editing the module constants.

The completion-token defaults deliberately carry headroom well above the ~250-token content portion of each call’s budget: reasoning models (including cognee’s default gpt-5.6-luna) spend hidden reasoning tokens out of the same budget, and a tight budget intermittently returns empty content.

Troubleshooting

• No entities found — the graph must already contain Entity nodes. Run cognee.remember() first.
• LLM errors — verify that your LLM provider is configured. See LLM Providers.
• Permission errors — the user must have write access to the target dataset. See Permissions.

Entity Deduplication

Merge near-duplicate entity nodes into one canonical node

Improve

Understand the current improvement workflow

Self-Improving Memory Quickstart

Bridge session memory and enrich a dataset

Search

Query the enriched graph with specialized search types