Skip to main content
Experimental, opt-in, and off by default. Truth-subspace reranking only runs when you build the subspace and pass use_truth_weight=True. With it off, retrieval behaves exactly as before.
Truth-subspace reranking turns what a finished session learned into a signal that reshapes future retrieval ordering — without re-ingesting or re-embedding your data. After a session is distilled into the session_learnings node set, Cognee builds a small set of anchor vectors (a “truth subspace”) from those lessons, projects each chunk onto them, and stores the resulting alignment coordinates on the graph node. At query time the hybrid retriever reads those coordinates and nudges its chunk ranking toward the directions the session taught it to value. Before you start:

​
How It Works

The feature uses two stores with two distinct roles:
StoreWhat it holdsBuilt whenRead when
TruthAnchor vector collectionone row per accepted lesson; its embedding is a truth directionpost-session buildquery time → gives the query’s coordinates
truth_alignment property on chunk nodeseach chunk’s cosine to every active anchorpost-session buildquery time → gives each candidate’s coordinates
The rerank score is the agreement between the two, weighted by how strongly the query itself aligns with each anchor. A chunk strongly aligned with the anchors the query cares about is boosted; a chunk with no stored coordinates is left untouched (neutral), so the feature can never penalize un-scored content.
Coordinates live on the graph node (a cheap per-property write, no re-embedding), mirroring how feedback_weight is stored. The reranker fetches them with a small batched lookup for the candidate chunks only.

​
Code in Action

​
Step 1: Build the truth subspace

Run improve() with build_truth_subspace=True. After the session’s learnings are distilled, this builds the TruthAnchor collection and writes truth_alignment coordinates onto every chunk in the dataset. 
import cognee
from cognee import SearchType

DATASET = "my_project"

await cognee.improve(
    dataset=DATASET,
    session_ids=["my_session"],
    build_truth_subspace=True,   # opt-in; default False
)

​
Step 2: Retrieve with truth weighting on

Pass use_truth_weight=True through retriever_specific_config on a HYBRID_COMPLETION search. Omit it (or set it False) for exact baseline ordering. 
results = await cognee.search(
    query_text="How should I prepare my morning drink at home?",
    query_type=SearchType.HYBRID_COMPLETION,
    datasets=[DATASET],
    retriever_specific_config={"use_truth_weight": True},
)
print(results)
The same query run with use_truth_weight off vs on returns the same candidates in a different order — chunks aligned with the session’s learnings rise.

​
Relationship to the Feedback Loop

Truth-subspace reranking is a second, complementary signal to the Feedback System:
  • feedback_weight is a per-element scalar learned from session ratings. It influences the graph/triplet retrievers via feedback_influence. Activate it by setting DEFAULT_FEEDBACK_INFLUENCE (e.g. 0.1); set it to 0.0 to restore the prior baseline.
  • truth_alignment is a per-chunk geometric signal learned from distilled lessons. It influences the hybrid retriever’s chunk lane via use_truth_weight.
Both are off (or neutral) by default and are stored on graph nodes the same way.
  • improve(..., build_truth_subspace=True) — opt-in build stage. Runs after distillation; reads session_learnings, upserts TruthAnchor rows, and writes per-chunk truth_alignment coordinates. Default False.
  • search(..., retriever_specific_config={"use_truth_weight": True}) — enables chunk-lane reranking for HYBRID_COMPLETION. Default False.
  • DEFAULT_FEEDBACK_INFLUENCE (env, default 0.1) — activates the separate feedback_weight loop; 0.0 disables it.
  • No change in ordering — confirm build_truth_subspace=True ran and reported a non-zero anchor / scored-node count, and that the session actually produced session_learnings. With no anchors, reranking is a no-op.
  • All candidates ranked equally — the subspace only reranks the hybrid chunk lane; entity ordering is unaffected in this MVP.
  • LLM/embedding errors during build — the build embeds anchors and chunk text; verify your provider is configured. See LLM Providers.

​
Additional Information

  • A runnable end-to-end demo ships with the feature at examples/python/truth_subspace_reranking_demo.py. It ingests a small two-theme corpus, teaches a preference via a session, builds the subspace, and prints a side-by-side rank diff so the reordering is visible.
This MVP reranks the hybrid chunk lane only and is not yet validated by an automatic quality measurement. Keep it opt-in until you have evaluated its effect on your data.

Self-Improvement Quickstart

Bridge and enrich memory with improve()

Feedback System

The complementary per-element feedback signal

Improve

The operation that builds the subspace