> ## 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.
# Truth-Subspace Reranking
> Let finished sessions reshape retrieval ordering by reranking against learned 'truth' directions
**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.
## Truth Subspace vs. Reranking
The two terms name the **two halves of one feature**, not two alternatives:
* The **truth subspace** is the *learned structure* — the small set of anchor
vectors (up to `k = 8` deterministic centroid slots) built from a session's
distilled `session_learnings`. It is built once, offline, by
[`improve(..., build_truth_subspace=True)`](/core-concepts/main-operations/improve).
* **Truth-subspace reranking** is the *query-time process* that reads that
structure and reorders the retrieval candidates. It is switched on per query with
`use_truth_weight=True` on a `HYBRID_COMPLETION` search.
You build the subspace once (and rebuild it as new sessions add learnings); you
rerank against it on every query where you opt in. Reranking has nothing to reorder
until the subspace exists, so the build step always comes first.
**Before you start:**
* Complete [Quickstart](/getting-started/quickstart) and the [Self-Improvement Quickstart](/guides/self-improvement-quickstart)
* Have an existing dataset and at least one session whose learnings have been distilled (via [`improve()`](/core-concepts/main-operations/improve) with `session_ids`)
* Ensure [LLM Providers](/setup-configuration/llm-providers) are configured (the build pass embeds anchors and chunks)
## How It Works
The feature uses **two stores with two distinct roles**:
| Store | What it holds | Built when | Read when |
| ----------------------------------------- | ----------------------------------------------------------------- | ------------------ | ----------------------------------------------- |
| `TruthAnchor` vector collection | one row per accepted lesson; its embedding is a *truth direction* | post-session build | query time → gives the query's coordinates |
| `truth_alignment` property on chunk nodes | each chunk's cosine to every active anchor | post-session build | query 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.
```python theme={null}
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.
```python theme={null}
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](/guides/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.
## When to Use It
Reach for truth-subspace reranking when **all** of the following hold:
* You have finished sessions whose distilled `session_learnings` encode a durable
preference or priority you want future retrieval to respect (a domain style, a
preferred source, a recurring correction).
* You retrieve with [`SearchType.HYBRID_COMPLETION`](/guides/search-basics) — the
subspace only reranks the hybrid chunk lane.
* You can rebuild the subspace after new sessions add learnings, so the anchors stay
current.
Skip it when there are no distilled learnings yet, when you use a non-hybrid
retriever, or when you need deterministic baseline ordering. Because the feature is
experimental and not yet validated by an automatic quality measurement, keep it
opt-in and evaluate its effect on your own data before relying on it.
* **`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.0` = off) — activates the separate
`feedback_weight` loop when set above `0` (e.g. `0.1`); `0.0` keeps the prior baseline.
* **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](/setup-configuration/llm-providers).
## Additional Information
* A runnable end-to-end demo ships with the feature at
`examples/demos/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.
Bridge and enrich memory with improve()
The complementary per-element feedback signal
The operation that builds the subspace