Sessions

A minimal guide to enabling conversational memory with sessions. When you use the same session_id across recall() calls, Cognee remembers previous questions and answers, enabling contextually aware follow-up questions.

Before You Start

Complete Quickstart to understand basic operations
Ensure you have LLM Providers configured
Read Sessions and Caching for conceptual overview
Configure your cache adapter before using sessions. See Cache Adapters for Redis and Filesystem setup instructions.

Code in Action

import asyncio
import cognee
from cognee import SearchType


async def main():
    # Start clean (optional in your app)
    await cognee.forget(everything=True)

    # Prepare knowledge base
    await cognee.remember(
        [
            "Alice moved to Paris in 2010. She works as a software engineer.",
            "Bob lives in New York. He is a data scientist.",
            "Alice and Bob met at a conference in 2015.",
        ],
        self_improvement=False,
    )

    # First recall - starts a new session (default user is used when none is passed)
    result1 = await cognee.recall(
        query_text="Where does Alice live?",
        query_type=SearchType.GRAPH_COMPLETION,
        session_id="conversation_1",
    )
    print("First answer:", result1[0].text)

    # Follow-up recall - uses conversation history
    result2 = await cognee.recall(
        query_text="What does she do for work?",
        query_type=SearchType.GRAPH_COMPLETION,
        session_id="conversation_1",  # Same session
    )
    print("Follow-up answer:", result2[0].text)
    # The LLM knows "she" refers to Alice from previous context

    # Different session - no memory of previous conversation
    result3 = await cognee.recall(
        query_text="What does she do for work?",
        query_type=SearchType.GRAPH_COMPLETION,
        session_id="conversation_2",  # New session
    )
    print("New session answer:", result3[0].text)
    # Without conversation history, the LLM cannot tell who "she" refers to


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

This example works with either Redis or Filesystem adapter. Configure your chosen adapter in the Before you start section above.

What Just Happened

Step 1: Prepare Knowledge Base

await cognee.remember(
    [
        "Alice moved to Paris in 2010. She works as a software engineer.",
        "Bob lives in New York. He is a data scientist.",
        "Alice and Bob met at a conference in 2015.",
    ],
    self_improvement=False,
)

Before you can use sessions, you need data in your knowledge base. cognee.remember() ingests the texts and builds the knowledge graph in one call.

Step 2: Start a Session

result1 = await cognee.recall(
    query_text="Where does Alice live?",
    query_type=SearchType.GRAPH_COMPLETION,
    session_id="conversation_1",
)

The session_id parameter on cognee.recall() creates or continues a conversation thread. All recalls with the same session_id share conversation history.

Step 3: Ask Follow-up Questions

result2 = await cognee.recall(
    query_text="What does she do for work?",
    query_type=SearchType.GRAPH_COMPLETION,
    session_id="conversation_1",  # Same session
)

When you use the same session_id, Cognee automatically includes previous Q&A turns in the LLM prompt, so the LLM resolves “she” to Alice from the earlier question.

Step 4: Isolate Conversations

result3 = await cognee.recall(
    query_text="What does she do for work?",
    query_type=SearchType.GRAPH_COMPLETION,
    session_id="conversation_2",  # New session
)

Each session_id maintains its own conversation history. This recall runs in a fresh session, so no previous turns are sent to the LLM and “she” is ambiguous.

Advanced Usage

Custom Session IDs

Use meaningful session IDs to organize conversations:

# User-specific sessions
await cognee.recall(query_text="...", session_id=f"user_{user_id}_chat")

# Topic-specific sessions
await cognee.recall(query_text="...", session_id="project_planning")
await cognee.recall(query_text="...", session_id="bug_discussion")

Session IDs are arbitrary strings—use whatever naming scheme fits your application.

See Sessions and Caching for what happens when you omit session_id (the default-session behavior), reading session history with get_session(), the include_context flag and SessionManager, disabling sessions entirely, which search types are session-aware, session persistence/clearing, and token usage tracking.

Legacy Guide

Sessions with add(), cognify(), and search()

If you are still on the pre-1.0 add() / cognify() / search() surface, the same session behavior is available through cognee.search(). The session_id parameter works exactly as described above. New projects should use remember() and recall() instead — see Search (legacy) for how the legacy surface relates to recall().

import asyncio
import cognee
from cognee import SearchType

async def main():
    # Prepare knowledge base
    await cognee.add([
        "Alice moved to Paris in 2010. She works as a software engineer.",
        "Bob lives in New York. He is a data scientist.",
        "Alice and Bob met at a conference in 2015."
    ])
    await cognee.cognify()

    # First search - starts a new session (default user is used when none is passed)
    result1 = await cognee.search(
        query_type=SearchType.GRAPH_COMPLETION,
        query_text="Where does Alice live?",
        session_id="conversation_1"
    )
    print("First answer:", result1[0])

    # Follow-up search - uses conversation history
    result2 = await cognee.search(
        query_type=SearchType.GRAPH_COMPLETION,
        query_text="What does she do for work?",
        session_id="conversation_1"  # Same session
    )
    print("Follow-up answer:", result2[0])
    # The LLM knows "she" refers to Alice from previous context

    # Different session - no memory of previous conversation
    result3 = await cognee.search(
        query_type=SearchType.GRAPH_COMPLETION,
        query_text="What does she do for work?",
        session_id="conversation_2"  # New session
    )
    print("New session answer:", result3[0])
    # Without conversation history, the LLM cannot tell who "she" refers to

asyncio.run(main())

Sessions and Caching

Understand how sessions work conceptually

Search Basics

Learn about search parameters and types

Setup Configuration

Configure cache adapters and providers

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

Before You Start

Code in Action

What Just Happened

Step 1: Prepare Knowledge Base

Step 2: Start a Session

Step 3: Ask Follow-up Questions

Step 4: Isolate Conversations

Advanced Usage

Legacy Guide

Sessions and Caching

Search Basics

Setup Configuration

​Before You Start

​Code in Action

​What Just Happened

​Step 1: Prepare Knowledge Base

​Step 2: Start a Session

​Step 3: Ask Follow-up Questions

​Step 4: Isolate Conversations

​Advanced Usage

​Legacy Guide

Sessions and Caching

Search Basics

Setup Configuration

Before You Start

Code in Action

What Just Happened

Step 1: Prepare Knowledge Base

Step 2: Start a Session

Step 3: Ask Follow-up Questions

Step 4: Isolate Conversations

Advanced Usage

Legacy Guide