Session Distillation

Turn guidance stated in a session into permanent lessons in the knowledge graph so future recalls respect it

Guidance a user states during a session — preferences, corrections, durable instructions — is short-term by default: it lives in the session cache and expires with it. Session distillation bridges that guidance into long-term memory by turning a session’s accepted, gated guidance into permanent lesson documents in the knowledge graph, tagged with the session_learnings node set. A brand-new session with no memory of the original conversation will then recall and respect what was learned.

Before you start:

• Complete Quickstart or have Cognee installed and configured
• Ensure you have LLM Providers configured
• Be familiar with Sessions and the remember() / recall() workflow
• Caching must be enabled so session Q&A history is retained

How to Distill a Session

Sessions can be bridged into the knowledge graph with improve(), which can persist cached Q&A, persist agent traces, and distill accepted session guidance into session_learnings:

await cognee.improve(
    dataset="project_memory",
    session_ids=["conversation_1"],
)

If you only want to distill one finished session’s gated guidance, call cognee.session.distill_session() directly:

result = await cognee.session.distill_session(
    "conversation_1",
    dataset="project_memory",
)

The direct result includes status and documents. A completed run writes accepted lesson documents back into the dataset; statuses such as no_gated_entries or no_accepted_lessons mean there was nothing durable enough to persist.

Example: Learning a Snack Preference

A minimal end-to-end demo of session distillation: state a preference in one session, distill that session into the knowledge graph, then confirm that a fresh session’s recall now reflects the learned preference. Setting AUTO_FEEDBACK=true lets the session capture the user’s stated preference as learned guidance during distillation.

How It Works

1. Remember two neutral snack facts. The graph starts with one sweet and one savory snack — and no preference:

await cognee.remember(
    [
        "Oreos are a sweet snack: chocolate cookies with a sugary cream filling.",
        "Doritos are a savory snack: salty, cheesy, seasoned tortilla chips.",
    ],
    dataset_name="snack_preference_demo",
)

2. Ask before distillation. With no known preference, recall() (RAG_COMPLETION) makes an arbitrary pick:

before = await cognee.recall(
    query_text="I want a snack. Should I get Oreos or Doritos? Recommend one.",
    query_type=SearchType.RAG_COMPLETION,
    datasets=["snack_preference_demo"],
    session_id="snack_session",
)

3. State the opposite preference in the same session so the answer has to flip. Here the model picked Oreos first, so the user states a savory preference — the full example below detects the first pick and states the opposite preference for either case:

await cognee.recall(
    query_text="Just so you know, I always prefer savory snacks over sweet ones.",
    query_type=SearchType.RAG_COMPLETION,
    datasets=["snack_preference_demo"],
    session_id="snack_session",
)

4. Distill the session into long-term memory. The curated preference lesson becomes a retrievable chunk in the graph:

result = await cognee.session.distill_session(
    "snack_session", dataset="snack_preference_demo"
)

5. Ask again in a fresh session. A brand-new session with no memory of the conversation still recalls the preference, so the recommendation now respects it:

after = await cognee.recall(
    query_text="I want a snack. Should I get Oreos or Doritos? Recommend one.",
    query_type=SearchType.RAG_COMPLETION,
    datasets=["snack_preference_demo"],
    session_id="snack_verification_session",
)

Full Example

The complete runnable script is on GitHub: examples/guides/session_distillation.py. It picks the opposite of the model’s first pick as the stated preference and then asserts the recommendation flips — a self-checking way to prove distillation changed the outcome.

Full example script

import asyncio
import os
import sys

# Let the session capture the user's stated preference as learned guidance.
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.modules.users.methods import get_default_user

SESSION_ID = "snack_session"

# flavor -> (snack that has it, statement of the preference)
SNACK_FOR_FLAVOR = {"savory": "Doritos", "sweet": "Oreos"}


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


def answer_text(result) -> str:
    """recall() returns a list of response entries; join their text for parsing/printing."""
    if isinstance(result, str):
        return result
    parts = []
    for entry in result or []:
        parts.append(getattr(entry, "text", None) or str(entry))
    return " ".join(parts)


def recommended_snack(text: str) -> str:
    """Whichever snack the model recommends first in its answer."""
    lowered = text.lower()
    oreo_at = lowered.find("oreo")
    dorito_at = lowered.find("dorito")
    if oreo_at == -1 and dorito_at == -1:
        return "Oreos"  # fallback; shouldn't happen with the snack facts in context
    if dorito_at == -1:
        return "Oreos"
    if oreo_at == -1:
        return "Doritos"
    return "Oreos" if oreo_at < dorito_at else "Doritos"


async def ask(message: str, user, session_id: str):
    # RAG_COMPLETION answers from retrieved chunks. Before distillation only the two snack
    # facts exist, so the model has no basis to prefer one. After distillation the curated
    # preference lesson is a retrievable chunk, so it steers the pick.
    return await cognee.recall(
        query_text=message,
        query_type=SearchType.RAG_COMPLETION,
        datasets=["snack_preference_demo"],
        session_id=session_id,
        user=user,
    )


async def main():
    progress("Clearing previous demo state.")
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    progress("Ingesting the two snack facts.")
    await cognee.remember(
        [
            "Oreos are a sweet snack: chocolate cookies with a sugary cream filling.",
            "Doritos are a savory snack: salty, cheesy, seasoned tortilla chips.",
        ],
        dataset_name="snack_preference_demo",
    )

    user = await get_default_user()
    await get_session_manager().delete_session(user_id=str(user.id), session_id=SESSION_ID)

    question = "I want a snack. Should I get Oreos or Doritos? Recommend one."

    # 1) Before distillation: no preference known -> arbitrary pick.
    progress("Asking BEFORE distillation (no preference known).")
    before = answer_text(await ask(question, user, SESSION_ID))
    first_pick = recommended_snack(before)
    print("\n----- BEFORE distillation -----\n", file=sys.stderr)
    print(f"picked: {first_pick}\n{before}", file=sys.stderr)

    # 2) State the OPPOSITE preference so the answer has to flip to the other snack.
    if first_pick == "Doritos":
        preferred_flavor, opposite_flavor = "sweet", "savory"
    else:
        preferred_flavor, opposite_flavor = "savory", "sweet"
    expected_after = SNACK_FOR_FLAVOR[preferred_flavor]
    progress(
        f"Model picked {first_pick}; telling it the user prefers {preferred_flavor} "
        f"(expect it to flip to {expected_after})."
    )
    await ask(
        f"Just so you know, I always prefer {preferred_flavor} snacks over {opposite_flavor} ones.",
        user,
        SESSION_ID,
    )

    # 3) Distill the session into long-term memory.
    progress("Distilling the session into the graph.")
    result = await cognee.session.distill_session(
        SESSION_ID, dataset="snack_preference_demo", user=user
    )
    progress(f"Distillation status={result.status} documents={len(result.documents)}")
    for doc in result.documents:
        print("\n----- distilled lesson -----\n", file=sys.stderr)
        print(doc, file=sys.stderr)

    # 4) After distillation, in a FRESH session, ask the same question again.
    progress("Asking AFTER distillation in a fresh session.")
    after = answer_text(await ask(question, user, "snack_verification_session"))
    second_pick = recommended_snack(after)
    print(f"\n----- AFTER distillation (expected {expected_after}) -----\n", file=sys.stderr)
    print(f"picked: {second_pick}\n{after}", file=sys.stderr)

    flipped = second_pick == expected_after and second_pick != first_pick
    progress(
        f"RESULT: {first_pick} -> {second_pick} "
        f"({'flipped as expected ✅' if flipped else 'did NOT flip ❌'})"
    )


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

Going Further

Distilled session_learnings are the foundation for other self-improvement features: improve() bridges whole sessions (Q&A, traces, and guidance) in one pass, and truth-subspace reranking builds retrieval anchors from distilled lessons.

An advanced companion script is on GitHub: examples/advanced_guides/session_distillation_demo.py. It replays an eight-message session so Q&A history accumulates, then shows which of those older turns hybrid vector recall brings back once a plain recency window would have dropped them, and distills only afterwards — covering the retrieval half of session memory that the before/after example above leaves out.

Sessions Guide

Learn how sessions and caching work in Cognee

Improve

Bridge sessions into the permanent graph with the improve pass