Importance Weight

Boost or dampen stored memories in retrieval ranking with the importance_weight argument to remember()

A minimal guide to biasing retrieval with importance_weight. Pass it to remember() when some of what you ingest matters more than the rest — a curated policy document should outrank a passing remark — and you want that preference applied every time the data is ranked, not re-stated in each query.

Before You Start

• Complete Quickstart to understand basic operations
• Ensure you have LLM Providers configured
• Read Remember for a conceptual overview of ingestion
• Set LLM_API_KEY in your environment
• No data is required up front — the script ingests its own text, but it starts with cognee.forget(everything=True), which wipes all existing Cognee data; run it against a setup you can afford to reset

Code in Action

import asyncio
import os

import cognee
from cognee import visualize_graph


async def main():
    await cognee.forget(everything=True)

    await cognee.remember(
        "Diana and Tom were born and raised in Helsinki. Diana currently resides in Berlin, while Tom never moved.",
        dataset_name="importance_demo",
        self_improvement=False,
    )
    await cognee.remember(
        "Alice moved to Paris in 2010, while Bob has always lived in New York.",
        dataset_name="importance_demo",
        importance_weight=0.7,
        self_improvement=False,
    )
    await cognee.remember(
        "Andreas was born in Venice, but later settled in Lisbon.",
        dataset_name="importance_demo",
        importance_weight=0.3,
        self_improvement=False,
    )

    visualize_graph_path = os.path.join(
        os.path.dirname(__file__), ".artifacts", "importance_weight.html"
    )
    await visualize_graph(visualize_graph_path)

    result = await cognee.recall(
        "In which cities did Andreas live?",
        datasets=["importance_demo"],
    )
    print(result)


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

What Just Happened

Step 1: Ingest Facts at Different Weights

await cognee.forget(everything=True)

await cognee.remember(
    "Diana and Tom were born and raised in Helsinki. Diana currently resides in Berlin, while Tom never moved.",
    dataset_name="importance_demo",
    self_improvement=False,
)
await cognee.remember(
    "Alice moved to Paris in 2010, while Bob has always lived in New York.",
    dataset_name="importance_demo",
    importance_weight=0.7,
    self_improvement=False,
)
await cognee.remember(
    "Andreas was born in Venice, but later settled in Lisbon.",
    dataset_name="importance_demo",
    importance_weight=0.3,
    self_improvement=False,
)

forget(everything=True) clears the store, so these three facts are all it holds. They land in the same dataset with three different weights: the first omits the argument and keeps the default of 0.5, the second is boosted to 0.7, and the third is dampened to 0.3. The weight is stored on the ingested data record and carried onto everything derived from it — the chunks, their summaries, and the entities extracted from them — so it is a property of the memory rather than of the query. This holds for every built-in chunker, not just the default TextChunker; a chunker you write yourself has to copy the weight onto its chunks explicitly. Step 2 shows that propagation on the graph itself.

Step 2: Render the Graph

visualize_graph_path = os.path.join(
    os.path.dirname(__file__), ".artifacts", "importance_weight.html"
)
await visualize_graph(visualize_graph_path)

The three ingests produce one graph, and weighting does not change its shape — only how its elements rank during retrieval. Weight is stored, not drawn, so the graph below carries it in the hover text: every node is from a real run of this script, and hovering one shows the importance_weight it actually ended up with.

The graph the three remember() calls build, from a real run. One chunk and summary per call, plus the entities extracted from each, meeting only at the shared type nodes. Hover a node to read the importance_weight stored on it.

Reading the weights off the graph shows how far one argument reaches. Each remember() call stamps its weight — 0.5, 0.7, 0.3 — on the document it ingests, and that value is handed down to the document’s chunk, that chunk’s summary, and every entity extracted from it. The dampened branch is present and connected exactly like the others; only its stored weight differs.

The EntityType nodes are the exception, and the graph is the easiest place to notice it. They are shared rather than per-document, and each ingest rewrites the one it uses, so person and place hold 0.3 — the weight of the last of the three calls to touch them — while date holds 0.7 because only the second call produced it. A type node’s weight therefore reflects ingestion order, not importance; if that matters for your data, weight the documents rather than relying on the types.

Step 3: Recall the Dampened Fact

result = await cognee.recall(
    "In which cities did Andreas live?",
    datasets=["importance_demo"],
)
print(result)

A low weight biases ranking; it does not hide data. Asking directly about the 0.3-weighted fact still answers from it, because nothing else in the dataset is a closer match to the question.

Advanced Usage

How the Weight Enters Ranking

importance_weight is a float on a 0.0–1.0 scale that defaults to 0.5. Data ingested without the argument is ranked as if it were 0.5, which is also the fallback for any record whose stored weight is missing.

Graph retrieval folds the weight into a triplet element’s distance as (2 - importance_weight): 1.0 leaves the distance untouched while 0.0 doubles it, so a higher weight means a shorter effective distance and a better rank. Two further signals can adjust that distance: feedback_weight, which is ignored unless feedback_influence is raised above its default of 0, and a personal preference weight, which applies only to elements the user has rated. importance_weight is the one that always counts — Search walks through the full ranking stage. Hybrid retrieval instead multiplies the ranking score by a factor derived from the weight, and accepts retriever_specific_config={"use_importance_weight": False} to ignore stored weights for a single query — see Search Types.

Which Search Types Use the Weight

importance_weight affects ranking in these search types:

• HYBRID_COMPLETION
• GRAPH_COMPLETION
• GRAPH_COMPLETION_COT
• GRAPH_COMPLETION_CONTEXT_EXTENSION
• GRAPH_COMPLETION_DECOMPOSITION
• GRAPH_SUMMARY_COMPLETION

It has no effect in RAG_COMPLETION, CHUNKS, or TRIPLET_COMPLETION, which rank by vector similarity alone.

When you omit query_type, recall() picks a search type automatically and may pick one that ignores the weight, so pass one of the types above as query_type whenever the weight must shape the answer. See Search Types for what each type retrieves.

Weighting Existing Data

The weight is set at ingestion time, so it applies to the records written by that remember() call, and nothing rewrites it afterwards. Ingesting the same text again does not change it either: the existing record keeps its stored weight and is skipped as already processed. To re-weight content, forget() the item and ingest it again at the new weight.

improve() is not that mechanism. It moves a separate feedback_weight on the graph elements that scored answers used, based on how those answers were rated. That weight is a different field and is ignored by graph ranking entirely unless you raise feedback_influence above its default of 0; even then it is blended alongside the importance weight rather than replacing it. improve() never changes the importance_weight you stored.

Chunks written by TextChunkerWithOverlap or CsvChunker before PR #5231 carry the 0.5 default regardless of the weight you set, because those two chunkers used to drop it. Upgrading only fixes chunks written from then on; to correct older content, forget the item and ingest it again.

remember()

Full parameter reference for the ingestion call.

Inspecting Hybrid Retrieval Context

See the ranked context a query actually retrieves.

Graph Visualization

More ways to render and seed the graph you just built.