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

# Sessions

> Step-by-step guide to using sessions for conversational memory in Cognee

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](../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 conceptual overview
* Configure your cache adapter before using sessions. See [Cache Adapters](../core-concepts/sessions-and-caching#cache-adapters) for Redis and Filesystem setup instructions.

## Code in Action

```python theme={null}
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())
```

<Note>
  This example works with either Redis or Filesystem adapter. Configure your chosen adapter in the [Before you start](#before-you-start) section above.
</Note>

## What Just Happened

### Step 1: Prepare Knowledge Base

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

<Accordion title="Custom Session IDs">
  Use meaningful session IDs to organize conversations:

  ```python theme={null}
  # 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.
</Accordion>

See [Sessions and Caching](/core-concepts/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

<Accordion title="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)](/core-concepts/main-operations/legacy-operations/search) for how the legacy surface relates to `recall()`.

  ```python theme={null}
  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())
  ```
</Accordion>

<Columns cols={3}>
  <Card title="Sessions and Caching" icon="brain" href="/core-concepts/sessions-and-caching">
    Understand how sessions work conceptually
  </Card>

  <Card title="Search Basics" icon="search" href="/guides/search-basics">
    Learn about search parameters and types
  </Card>

  <Card title="Setup Configuration" icon="settings" href="/setup-configuration/overview">
    Configure cache adapters and providers
  </Card>
</Columns>