Understanding Sessions
A session represents a user’s conversation history and context within a specific domain. Sessions are:
- User-specific: Each user has separate sessions
- Domain-specific: Users can have different sessions for different domains
- Persistent: Chat history is saved to the database
- In-memory: Recent history is cached for fast access
Session Creation
Sessions are automatically created when a user first chats:
from langchat import LangChat, LangChatConfig
config = LangChatConfig.from_env()
langchat = LangChat(config=config)
# First chat creates a session automatically
result = await langchat.chat(
query="Hello!",
user_id="user123",
domain="education"
)
Accessing Sessions
You can access a session directly:
# Get or create a session
session = langchat.get_session(
user_id="user123",
domain="education"
)
# Access chat history
print(session.chat_history) # List of (query, response) tuples
# Access domain
print(session.domain) # "education"
# Access user_id
print(session.user_id) # "user123"
Chat History
Chat history is automatically maintained:
# First message
result1 = await langchat.chat(
query="What universities offer computer science?",
user_id="user123",
domain="education"
)
# Second message (includes previous context)
result2 = await langchat.chat(
query="What about in Europe?",
user_id="user123",
domain="education"
)
# The AI knows "What about in Europe?" refers to CS programs
History Format
Chat history is stored as a list of tuples:
session = langchat.get_session("user123", "education")
print(session.chat_history)
# Output:
# [
# ("What universities offer computer science?", "Here are some universities..."),
# ("What about in Europe?", "Here are European universities..."),
# ...
# ]
History Limits
History is automatically limited:
config = LangChatConfig(
# Maximum messages to keep in memory
max_chat_history=20, # Default: 20
# Conversation buffer window
memory_window=20 # Default: 20
)
Only the most recent messages (up to max_chat_history) are kept in memory. Older messages are stored in the database but not loaded automatically.
Session Configuration
Configure session behavior in LangChatConfig:
config = LangChatConfig(
# Maximum chat history messages in memory
max_chat_history=50, # Keep last 50 messages
# Conversation buffer window
memory_window=50 # Context window size
)
Increasing History
For longer conversations:
config = LangChatConfig(
max_chat_history=100, # Keep last 100 messages
memory_window=100
)
Reducing Memory Usage
For smaller applications:
config = LangChatConfig(
max_chat_history=10, # Keep last 10 messages
memory_window=10
)
Session Persistence
Sessions are persisted to Supabase:
- Chat History: Saved to
chat_history table
- Messages: Automatically saved after each chat
- Metadata: User ID, domain, timestamps
Database Storage
Chat history is stored with:
user_id: User identifierdomain: Session domainquery: User’s questionresponse: AI’s responsetimestamp: When the message was created
Multi-Domain Sessions
Users can have separate sessions for different domains:
# Education domain session
result1 = await langchat.chat(
query="What universities offer CS?",
user_id="user123",
domain="education"
)
# Travel domain session (separate history)
result2 = await langchat.chat(
query="What are good travel destinations?",
user_id="user123",
domain="travel"
)
Each domain maintains its own separate chat history. Messages in one domain don’t affect another.
Session Lifecycle
- Creation: Session created on first chat
- Update: History updated after each chat
- Persistence: Messages saved to database
- Retention: History kept in memory (up to limit)
- Cleanup: Old messages removed from memory (but kept in DB)
Best Practices
1. Use Consistent User IDs
Use stable user identifiers:
# ✅ Good: Stable user ID
user_id = "user_12345"
# ❌ Bad: Random or changing IDs
user_id = str(uuid.uuid4()) # Creates new session each time
2. Choose Appropriate Domains
Use domains to separate contexts:
# Separate contexts
domain = "education" # For education queries
domain = "travel" # For travel queries
domain = "support" # For support queries
3. Adjust History Limits
Balance memory usage with context:
# More history = better context, more memory
config.max_chat_history = 100
# Less history = less memory, less context
config.max_chat_history = 10
4. Monitor Session Usage
Check session sizes:
session = langchat.get_session("user123", "education")
print(f"History length: {len(session.chat_history)}")
Advanced Usage
Manual Session Management
You can manage sessions manually:
# Get session
session = langchat.get_session("user123", "education")
# Chat history is automatically updated
# You can access it directly
for query, response in session.chat_history:
print(f"Q: {query}")
print(f"A: {response}\n")
Clearing History
To start fresh (clear memory, but DB persists):
session = langchat.get_session("user123", "education")
session.chat_history = [] # Clear in-memory history
# Note: Database history persists
Troubleshooting
Issue: History not persisting
Solution: Check Supabase configuration:
config = LangChatConfig(
supabase_url="https://...", # Verify URL
supabase_key="eyJ..." # Verify key
)
Issue: Too much memory usage
Solution: Reduce history limits:
config.max_chat_history = 10
config.memory_window = 10
Issue: Context lost between messages
Solution: Ensure same user_id and domain:
# ✅ Same session
await langchat.chat(query="Q1", user_id="user123", domain="education")
await langchat.chat(query="Q2", user_id="user123", domain="education")
# ❌ Different sessions
await langchat.chat(query="Q1", user_id="user123", domain="education")
await langchat.chat(query="Q2", user_id="user456", domain="education") # Different user
Next Steps
Questions? Check the API Reference for complete details!