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

# Advanced Session Distillation

> Replay a scripted session with hybrid vector recall over its QA turns, then distill the learned guidance into the knowledge graph

A guide to the two halves of session memory in one script: while a session runs, its QA turns are indexed for vector recall and stated guidance is kept as active working memory; after it ends, `distill_session()` writes the surviving lessons into the graph. Use it when a conversation is long enough that a plain recency window drops relevant turns, and you want what was learned to outlive the session.

## Before You Start

* Complete [Quickstart](/getting-started/quickstart) to understand basic operations
* Ensure you have [LLM Providers](/setup-configuration/llm-providers) configured
* Read [Sessions and Caching](/core-concepts/sessions-and-caching) for the short-term memory model this builds on
* [Make sure caching is enabled](/core-concepts/sessions-and-caching#cache-adapters) (`CACHING=true`, the default) so session QA history is retained between turns
* Read [Session Distillation](/guides/session-distillation) first — this guide is the advanced companion to that minimal before/after example

<Note>
  `search_session_qa_ids` and `select_hybrid_qa_entries` are internal helpers used here to show what hybrid history selection picks. Recall performs this selection for you; you do not normally call them yourself.
</Note>

## Code in Action

```python theme={null}
import asyncio
import os
import sys

os.environ["AUTO_FEEDBACK"] = "true"
os.environ.setdefault("LOG_LEVEL", "ERROR")

import cognee
from cognee import SearchType
from cognee.infrastructure.session.get_session_manager import get_session_manager
from cognee.infrastructure.session.session_embeddings import (
    search_session_qa_ids,
    select_hybrid_qa_entries,
)
from cognee.modules.users.methods import get_default_user

DATASET_NAME = "aurora_robotics_distillation_demo"
SESSION_ID = "aurora_distillation_session"

DOCUMENTS = [
    "Aurora Robotics builds two products: the VoltaArm industrial gripper and the "
    "TerraScout warehouse rover.",
    "The VoltaArm gripper uses firmware version 4 and a calibration routine that maps "
    "joint torque to grip strength.",
    "The TerraScout rover navigates warehouses using lidar maps and charging dock beacons.",
    "Aurora Robotics releases firmware through the HALT test suite, a hardware abuse "
    "test that runs overnight.",
    "Dana Voss leads the VoltaArm firmware team at Aurora Robotics.",
    "Calibration data for the VoltaArm gripper is stored in a battery-backed memory bank.",
]

MESSAGES = [
    # Orientation question.
    "What products does Aurora Robotics build and who leads VoltaArm firmware?",
    # Durable lesson.
    "Flashing VoltaArm firmware wipes calibration data, so calibration must be re-run.",
    # Durable rule.
    "Always run the HALT test suite before a VoltaArm firmware release.",
    # Session-local preference.
    "For the rest of this chat, keep answers under three bullet points.",
    # Reworded lesson; exact-only active guidance keeps it separate.
    "After a VoltaArm firmware flash, redo calibration because the flash erases it.",
    # Ordinary question; helps push the VoltaArm lesson out of the recency window.
    "How does the TerraScout rover navigate warehouses?",
    # Ordinary question; helps vector recall stand apart from recency.
    "What is the HALT test suite and when does it run?",
    # Application question.
    "Draft the steps a technician should follow for a VoltaArm firmware update.",
]


def progress(message: str):
    print(f"[distillation-demo] {message}", file=sys.stderr, flush=True)


async def setup_demo_data():
    progress("Clearing previous demo state.")
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)
    progress(f"Ingesting {len(DOCUMENTS)} Aurora Robotics facts.")
    await cognee.remember(DOCUMENTS, dataset_name=DATASET_NAME, self_improvement=False)
    progress("Ingestion complete.")


async def reset_demo_session(user):
    deleted = await get_session_manager().delete_session(
        user_id=str(user.id), session_id=SESSION_ID
    )
    progress("Old demo session deleted." if deleted else "No previous demo session found.")


async def ask(message: str, user):
    return await cognee.recall(
        query_text=message,
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET_NAME],
        session_id=SESSION_ID,
        user=user,
    )


async def print_session_evidence(user):
    """Show that QA turns and exact active-guidance entries are stored."""
    session_manager = get_session_manager()
    qa_entries = await cognee.session.get_session(session_id=SESSION_ID, user=user)
    context_rows = await session_manager.get_session_context_entries(
        user_id=str(user.id), session_id=SESSION_ID
    )
    guidance = [row for row in context_rows if row.get("kind", "context") == "context"]

    print(f"  qa_count={len(qa_entries)}", file=sys.stderr)
    print(f"  guidance_entries={len(guidance)}", file=sys.stderr)
    for row in guidance:
        merged_sources = len(row.get("source_feedback_ids") or [])
        print(
            f"    [{row.get('section')}] {row.get('content')!r} (sources={merged_sources})",
            file=sys.stderr,
        )


async def show_vector_recall(user):
    """Show hybrid history selection: an old on-topic turn outside the recency window is
    recalled by vector search, while older off-topic turns are not."""
    qa_entries = await cognee.session.get_session(session_id=SESSION_ID, user=user)
    query = "What happens to VoltaArm calibration when firmware is flashed?"
    vector_qa_ids = await search_session_qa_ids(
        user_id=str(user.id),
        session_id=SESSION_ID,
        query_text=query,
    )
    selected = select_hybrid_qa_entries(qa_entries, vector_qa_ids, last_n=2)

    selected_qa_ids = {entry.qa_id for entry in selected}
    recent_qa_ids = {entry.qa_id for entry in qa_entries[-2:]}
    progress(f"Hybrid history for {query!r} with a recency window of 2:")
    for entry in qa_entries:
        if entry.qa_id in recent_qa_ids:
            verdict = "recent"
        else:
            recalled = entry.qa_id in selected_qa_ids
            verdict = "vector recalled" if recalled else "not recalled"
        print(f"  [{verdict}] {entry.question[:90]}", file=sys.stderr)


async def run_scripted_session(user):
    for index, message in enumerate(MESSAGES, start=1):
        progress(f"Message {index}")
        await ask(message, user)
        await print_session_evidence(user)


async def distill_and_verify(user):
    progress("Distilling the session into the knowledge graph.")
    result = await cognee.session.distill_session(SESSION_ID, dataset=DATASET_NAME, user=user)
    progress(f"Distillation status={result.status} documents={len(result.documents)}")
    if result.documents:
        print(
            f"\n----- {len(result.documents)} distilled lesson documents -----\n", file=sys.stderr
        )
        for doc in result.documents:
            print(doc, file=sys.stderr)
            print("---", file=sys.stderr)

    progress("Asking the graph (fresh session) what it now knows about the lesson.")
    answer = await cognee.recall(
        query_text="What must be done after flashing VoltaArm firmware, and why?",
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET_NAME],
        session_id="verification_session",
        user=user,
    )
    print("\n----- Post-distillation graph answer -----\n", file=sys.stderr)
    print(answer, file=sys.stderr)


async def main():
    await setup_demo_data()

    user = await get_default_user()
    await reset_demo_session(user)

    await run_scripted_session(user)
    await show_vector_recall(user)
    await distill_and_verify(user)


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

## What Just Happened

### Step 1: Turn On Guidance Capture

```python theme={null}
import asyncio
import os
import sys

os.environ["AUTO_FEEDBACK"] = "true"
os.environ.setdefault("LOG_LEVEL", "ERROR")

import cognee
from cognee import SearchType
from cognee.infrastructure.session.get_session_manager import get_session_manager
from cognee.infrastructure.session.session_embeddings import (
    search_session_qa_ids,
    select_hybrid_qa_entries,
)
from cognee.modules.users.methods import get_default_user
```

`AUTO_FEEDBACK` controls whether what the user states is captured as learned guidance — active working memory that distillation later gates. It is on by default; the script sets it explicitly so a local override can't silently turn guidance capture off.

### Step 2: Ingest the Facts the Session Talks About

```python theme={null}
DATASET_NAME = "aurora_robotics_distillation_demo"
SESSION_ID = "aurora_distillation_session"

DOCUMENTS = [
    "Aurora Robotics builds two products: the VoltaArm industrial gripper and the "
    "TerraScout warehouse rover.",
    "The VoltaArm gripper uses firmware version 4 and a calibration routine that maps "
    "joint torque to grip strength.",
    "The TerraScout rover navigates warehouses using lidar maps and charging dock beacons.",
    "Aurora Robotics releases firmware through the HALT test suite, a hardware abuse "
    "test that runs overnight.",
    "Dana Voss leads the VoltaArm firmware team at Aurora Robotics.",
    "Calibration data for the VoltaArm gripper is stored in a battery-backed memory bank.",
]
```

```python theme={null}
async def setup_demo_data():
    progress("Clearing previous demo state.")
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)
    progress(f"Ingesting {len(DOCUMENTS)} Aurora Robotics facts.")
    await cognee.remember(DOCUMENTS, dataset_name=DATASET_NAME, self_improvement=False)
    progress("Ingestion complete.")
```

Six facts about Aurora Robotics give the session something to answer from. `self_improvement=False` keeps ingestion plain, so anything the graph knows at the end about firmware flashing came from the session, not from this step.

### Step 3: Replay an Eight-Message Session

```python theme={null}
MESSAGES = [
    # Orientation question.
    "What products does Aurora Robotics build and who leads VoltaArm firmware?",
    # Durable lesson.
    "Flashing VoltaArm firmware wipes calibration data, so calibration must be re-run.",
    # Durable rule.
    "Always run the HALT test suite before a VoltaArm firmware release.",
    # Session-local preference.
    "For the rest of this chat, keep answers under three bullet points.",
    # Reworded lesson; exact-only active guidance keeps it separate.
    "After a VoltaArm firmware flash, redo calibration because the flash erases it.",
    # Ordinary question; helps push the VoltaArm lesson out of the recency window.
    "How does the TerraScout rover navigate warehouses?",
    # Ordinary question; helps vector recall stand apart from recency.
    "What is the HALT test suite and when does it run?",
    # Application question.
    "Draft the steps a technician should follow for a VoltaArm firmware update.",
]
```

```python theme={null}
async def ask(message: str, user):
    return await cognee.recall(
        query_text=message,
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET_NAME],
        session_id=SESSION_ID,
        user=user,
    )
```

Every message goes through one `recall()` on the same `session_id`, which is what indexes the turn and captures stated guidance. The messages are ordered on purpose: durable lessons come early, ordinary questions after them, so the lessons fall outside the recency window by the time the last message arrives.

### Step 4: See Which Old Turns Vector Recall Brings Back

```python theme={null}
async def show_vector_recall(user):
    """Show hybrid history selection: an old on-topic turn outside the recency window is
    recalled by vector search, while older off-topic turns are not."""
    qa_entries = await cognee.session.get_session(session_id=SESSION_ID, user=user)
    query = "What happens to VoltaArm calibration when firmware is flashed?"
    vector_qa_ids = await search_session_qa_ids(
        user_id=str(user.id),
        session_id=SESSION_ID,
        query_text=query,
    )
    selected = select_hybrid_qa_entries(qa_entries, vector_qa_ids, last_n=2)
```

Hybrid history selection combines the last `last_n` turns with turns that vector search finds relevant to the query. With a recency window of two, the calibration lesson from early in the session should still be selected — by similarity, not position — while older off-topic turns are left out.

### Step 5: Distill the Session and Ask a Fresh One

```python theme={null}
async def distill_and_verify(user):
    progress("Distilling the session into the knowledge graph.")
    result = await cognee.session.distill_session(SESSION_ID, dataset=DATASET_NAME, user=user)
    progress(f"Distillation status={result.status} documents={len(result.documents)}")
```

```python theme={null}
    answer = await cognee.recall(
        query_text="What must be done after flashing VoltaArm firmware, and why?",
        query_type=SearchType.GRAPH_COMPLETION,
        datasets=[DATASET_NAME],
        session_id="verification_session",
        user=user,
    )
```

`distill_session()` gates the session's learned guidance, curates it against the existing graph, and cognifies the surviving lessons into the dataset as long-term memory; `result.status` and `result.documents` report what was written. The final `recall()` runs in a brand-new session with no conversation history, so an answer that still knows calibration must be re-run could only have come from the graph.

<Columns cols={2}>
  <Card title="Session Distillation" icon="graduation-cap" href="/guides/session-distillation">
    The minimal before/after distillation example this one builds on
  </Card>

  <Card title="Sessions" icon="message-square" href="/guides/sessions">
    How sessions and conversation history work in Cognee
  </Card>

  <Card title="Improve" icon="sparkles" href="/core-concepts/main-operations/improve">
    Bridge whole sessions — QA, traces, and guidance — in one pass
  </Card>
</Columns>