Skip to main content

​
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:
SettingContext qualityToken costSpeed
Higher (e.g. 50)Better memory of the conversationHigherSlower
Lower (e.g. 5)May forget earlier contextLowerFaster
Default (20)Good balanceModerateNormal

​
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:
  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:
ColumnTypeDescription
idbigintAuto-incrementing primary key
user_idtextUser identifier
platformtextPlatform namespace (default: "default")
messagetextUser’s message
responsetextAI’s response
created_attimestamptzUTC 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.