> ## Documentation Index
> Fetch the complete documentation index at: https://langchat.neurobrains.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Management

> How LangChat tracks conversations per user and per platform.

## How sessions work

Every `chat()` call is tied to a `user_id` and an optional `platform`. Together they form a session key:

```
session_key = "{user_id}_{platform}"
```

LangChat maintains one `UserSession` per key. Within a session:

* The last N exchanges are kept in memory (default: 20, configured via `max_chat_history`)
* Full history is loaded from Supabase when the session is first accessed
* Each new exchange is saved to Supabase in the background (non-blocking)

***

## user\_id

Identifies the person chatting. Use any stable, unique identifier — a database UUID, an email address, or a session token.

```python theme={null}
response = await lc.chat(
    query="What's my account balance?",
    user_id="user_abc123",
)
```

Each `user_id` has its own isolated conversation history. User A never sees User B's messages.

***

## platform

Groups conversations by application or context. Use it when multiple apps or surfaces share the same LangChat backend.

```python theme={null}
# Web app conversation
response = await lc.chat(
    query="Help me track my order",
    user_id="user_123",
    platform="web",
)

# Mobile app — same user, completely separate conversation
response = await lc.chat(
    query="Help me track my order",
    user_id="user_123",
    platform="mobile",
)

# Internal admin tool — separate again
response = await lc.chat(
    query="Show me the user report",
    user_id="user_123",
    platform="admin",
)
```

If you don't pass `platform`, it defaults to `"default"`.

***

## History window

`max_chat_history` controls how many past exchanges are included in each prompt. One exchange = one user message + one AI response.

```python theme={null}
lc = LangChat(
    llm=OpenAI("gpt-4o-mini"),
    vector_db=Pinecone("my-index"),
    db=Supabase(),
    max_chat_history=10,   # include last 10 exchanges in each prompt
)
```

**Trade-offs:**

| Setting          | Context quality                   | Token cost | Speed  |
| ---------------- | --------------------------------- | ---------- | ------ |
| Higher (e.g. 50) | Better memory of the conversation | Higher     | Slower |
| Lower (e.g. 5)   | May forget earlier context        | Lower      | Faster |
| Default (20)     | Good balance                      | Moderate   | Normal |

***

## Get a session object

Access the underlying `UserSession` directly if you need to inspect or manipulate it:

```python theme={null}
session = lc.get_session(user_id="alice", platform="web")

print(session.user_id)          # "alice"
print(session.platform)         # "web"
print(session.chat_history)     # list of (query, response) tuples
```

***

## How history is loaded

When you first call `chat()` for a user:

1. LangChat checks the in-memory session cache — if the session exists, it uses that
2. If not, it creates a new `UserSession` which loads recent messages from Supabase
3. The loaded history is stored in memory for subsequent calls

This means after a server restart, users can continue where they left off.

***

## Database schema

Chat history is stored in the `chat_history` table:

| Column       | Type          | Description                               |
| ------------ | ------------- | ----------------------------------------- |
| `id`         | `bigint`      | Auto-incrementing primary key             |
| `user_id`    | `text`        | User identifier                           |
| `platform`   | `text`        | Platform namespace (default: `"default"`) |
| `message`    | `text`        | User's message                            |
| `response`   | `text`        | AI's response                             |
| `created_at` | `timestamptz` | UTC timestamp                             |

LangChat creates this table automatically on first run.

***

## Multi-tenant isolation

When running LangChat as a shared API, conversations are naturally isolated because:

* Each `user_id` + `platform` combination is a separate session
* History queries always filter by both `user_id` and `platform`
* In-memory session cache is keyed by `"{user_id}_{platform}"`

No extra configuration is needed for multi-tenant use.