Session Management

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.

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.

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

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:

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:

LangChat checks the in-memory session cache — if the session exists, it uses that
If not, it creates a new UserSession which loads recent messages from Supabase
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.

Getting Started

Guides

Components

API Reference

Examples

Advanced

Session Management

How sessions work

user_id

platform

History window

Get a session object

How history is loaded

Database schema

Multi-tenant isolation

​How sessions work

​user_id

​platform

​History window

​Get a session object

​How history is loaded

​Database schema

​Multi-tenant isolation

How sessions work

user_id

platform

History window

Get a session object

How history is loaded

Database schema

Multi-tenant isolation