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

<Note>
  **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.
</Note>

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.

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

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

<Accordion title="Parameters">
  * **`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.
</Accordion>

<Accordion title="Troubleshooting">
  * **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).
</Accordion>

## Additional Information

* A runnable end-to-end guide ships with the feature at
  `examples/guides/truth_subspace_reranking.py`. Built entirely on the public API, it
  ingests a small two-theme corpus (coffee vs. tea), remembers a couple of session
  learnings into the `session_learnings` node set, builds the subspace, and then runs the
  same ambiguous query twice — `use_truth_weight=False`, then `True` — printing both
  retrieval contexts so the reordering is visible.
* An advanced script showing the machinery under that reordering is on our
  [GitHub](https://github.com/topoteretes/cognee/blob/dev/examples/advanced_guides/truth_centroid_slots_demo.py).
  Where the guide script stops at the changed ordering, this one prints the deterministic
  centroid slots themselves — each slot's count and epoch, the nearest accepted learning,
  and the `truth_alignment` coordinates stored on every `DocumentChunk` node — then adds a
  second batch of learnings and rebuilds, so you can watch the anchors and the epoch move
  as new lessons arrive. It reads those internals through APIs that are not part of the
  public surface (`load_centroids`, `get_node_truth_state`, `align.cosine`), so treat it as
  a look inside the feature rather than a pattern to build on.

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

<Columns cols={3}>
  <Card title="Self-Improvement Quickstart" icon="brain" href="/guides/self-improvement-quickstart">
    Bridge and enrich memory with improve()
  </Card>

  <Card title="Feedback System" icon="brain-circuit" href="/guides/feedback-system">
    The complementary per-element feedback signal
  </Card>

  <Card title="Improve" icon="sparkles" href="/core-concepts/main-operations/improve">
    The operation that builds the subspace
  </Card>
</Columns>