LightRAG/SESSION_ALWAYS_ON.md

Session History: Always-On Feature

Final Simplification

Based on user feedback, we've removed the SESSION_HISTORY_ENABLED variable completely. Session history is now always enabled as a core feature of LightRAG Server.

Rationale

Why Remove the Toggle?

1. It's Always Useful: Session history is a fundamental feature for chat applications
2. No Overhead: If you don't use it, it doesn't impact performance
3. Graceful Degradation: If PostgreSQL fails, server still starts (endpoints just unavailable)
4. Simpler UX: One less thing for users to configure
5. Modern Default: Chat history should be expected, not optional

What Changed

Before (With Toggle)

SESSION_HISTORY_ENABLED=true  # Required this line

After (Always On)

# Nothing needed! Session history just works

How It Works Now

Automatic Initialization

When LightRAG Server starts:

1. ✅ Reads POSTGRES_* environment variables
2. ✅ Connects to PostgreSQL
3. ✅ Creates session tables automatically (if they don't exist)
4. ✅ Enables /history/* endpoints
5. ✅ Ready to use!

Graceful Failure

If PostgreSQL is not available:

WARNING: Session history initialization failed: connection refused
WARNING: Session history endpoints will be unavailable
INFO: Server is ready to accept connections! 🚀

• ✅ Server still starts
• ✅ Other features work normally
• ✅ Session endpoints return 503 (service unavailable)
• ✅ No crash or hard failure

Configuration

Complete Setup

# File: .env
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=lightrag_db

# That's it! Session history automatically enabled

No PostgreSQL?

If you don't have PostgreSQL:

• LightRAG Server will start normally
• Session endpoints won't be available
• All other features work as expected
• Check logs for: "Session history endpoints will be unavailable"

Benefits

For Users

1. ✅ Zero Configuration: No ENV variable to set
2. ✅ Just Works: Automatic if PostgreSQL is available
3. ✅ No Surprises: Consistent behavior
4. ✅ Less Confusion: No "should I enable this?" questions

For Developers

1. ✅ Cleaner Code: No conditional logic for enable/disable
2. ✅ Simpler Tests: Always test with feature enabled
3. ✅ Better UX: Feature discovery through API docs
4. ✅ Modern Architecture: Features are on by default

Migration

From SESSION_HISTORY_ENABLED=true

Simply remove the line from your .env:

# Remove this line
# SESSION_HISTORY_ENABLED=true

# Everything else stays the same

From SESSION_HISTORY_ENABLED=false

If you had it disabled:

# Remove this line
# SESSION_HISTORY_ENABLED=false

# Session history will now be available
# Just don't use the endpoints if you don't need them

API Endpoints

Always available (when PostgreSQL is configured):

POST   /history/sessions                 - Create session
GET    /history/sessions                 - List sessions
GET    /history/sessions/{id}/history    - Get messages
DELETE /history/sessions/{id}            - Delete session

Database Tables

Automatically created in POSTGRES_DATABASE:

• lightrag_chat_sessions_history
• lightrag_chat_messages_history
• lightrag_message_citations_history

Use Cases

Development

# Just configure PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_DATABASE=dev_lightrag

# Session history automatically available!

Production

# Production database
POSTGRES_HOST=prod-db.example.com
POSTGRES_DATABASE=lightrag_prod

# Session history automatically available!

Testing Without Sessions

# Don't configure PostgreSQL
# Or use SQLite for other storage

# Session endpoints return 503
# Rest of LightRAG works fine

Implementation

Server Initialization

# In lightrag_server.py
app = FastAPI(**app_kwargs)

# Initialize session history - always attempt
try:
    session_db_manager = get_session_db_manager()
    app.include_router(history_router)
    logger.info("Session history initialized")
except Exception as e:
    logger.warning(f"Session history unavailable: {e}")
    # Server continues normally

Key Points

• ✅ No if SESSION_HISTORY_ENABLED checks
• ✅ Try to initialize, log warning if fails
• ✅ Server continues regardless
• ✅ Clean and simple

Philosophy

Modern Software Defaults

Good software should:

1. Work out of the box - Session history just works
2. Fail gracefully - Server starts even if sessions fail
3. Be discoverable - Feature is in API docs by default
4. Require minimal config - Use existing PostgreSQL

KISS Principle

• ❌ Before: "Do I need session history? Should I enable it?"
• ✅ After: "It's there if I need it!"

Progressive Enhancement

• Basic: LightRAG without PostgreSQL
• Enhanced: LightRAG with PostgreSQL + Session History
• No configuration needed to progress!

Summary

Aspect	Before	After
Configuration	SESSION_HISTORY_ENABLED=true	Nothing needed
If PostgreSQL available	Enabled	Enabled
If PostgreSQL unavailable	Disabled	Graceful warning
User decision needed	Yes	No
Code complexity	Conditional logic	Always attempt

Quote from User

"Biến này lúc nào cũng = true thì cần gì nữa, xóa luôn"

Exactly right! If it's always true, why have it at all?

Session history is now a first-class citizen of LightRAG Server - always available, no questions asked! 🎉

---

Technical Notes

Database Connection

Uses the standard SQLAlchemy pattern:

class SessionDatabaseConfig:
    def __init__(self):
        self.host = os.getenv("POSTGRES_HOST", "localhost")
        self.port = os.getenv("POSTGRES_PORT", "5432")
        # ... etc

No special handling, no overrides, no complexity.

Graceful Degradation

Exception handling ensures server resilience:

try:
    session_db_manager = get_session_db_manager()
    app.include_router(history_router)
except Exception as e:
    logger.warning(f"Session history unavailable: {e}")
    # Server continues

Zero Impact

If session endpoints aren't used:

• ✅ No queries to database
• ✅ No performance overhead
• ✅ No resource consumption
• ✅ Just available when needed

Perfect! 🎯