LightRAG/docs/SessionHistoryMigration.md

Session History Migration Guide

Overview

The session history functionality has been migrated from the standalone service/ folder into the main LightRAG codebase as an integrated feature. This document explains the changes and migration steps.

What Changed

Before (Standalone Service)

• Session history was implemented as a separate service in the service/ folder
• Required manual setup and configuration
• Separate database connections and initialization
• Required adding service path to sys.path

After (Integrated Feature)

• Session history is now a built-in feature of LightRAG Server
• Automatically initialized when LightRAG Server starts
• Unified configuration through .env file
• Native integration with LightRAG API

Migration Steps

1. Update Dependencies

The session history feature requires SQLAlchemy and PostgreSQL driver:

# Using uv (recommended)
uv pip install sqlalchemy psycopg2-binary

# Or using pip
pip install sqlalchemy psycopg2-binary

2. Update Configuration

Move your session database configuration to the main .env file:

# Enable session history feature
SESSION_HISTORY_ENABLED=true

# PostgreSQL configuration for session history
SESSION_POSTGRES_HOST=localhost
SESSION_POSTGRES_PORT=5433
SESSION_POSTGRES_USER=lightrag
SESSION_POSTGRES_PASSWORD=lightrag_password
SESSION_POSTGRES_DATABASE=lightrag_sessions

3. Update Docker Compose (if using Docker)

The new docker-compose.yml includes PostgreSQL service automatically:

# Stop existing services
docker compose down

# Pull/build new images
docker compose pull
docker compose build

# Start all services
docker compose up -d

4. API Endpoints

Session history endpoints are under the /history prefix:

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

5. Remove Old Service Folder

Once migration is complete and tested, you can safely remove the old service/ folder:

# Backup first (optional)
mv service service.backup

# Or remove directly
rm -rf service

New Features

The integrated session history includes several improvements:

1. Automatic Initialization: Session database is automatically initialized on server startup
2. Graceful Degradation: If session database is unavailable, server still starts (without history features)
3. Better Error Handling: Improved error messages and logging
4. User Isolation: Proper user ID handling via X-User-ID header
5. Session Deletion: New endpoint to delete sessions and messages

Configuration Reference

Configuration

Session history is always enabled and uses the same PostgreSQL as LightRAG:

• No environment variables needed
• Session tables created automatically in POSTGRES_DATABASE
• Works out of the box when PostgreSQL is configured

That's it - zero configuration!

Troubleshooting

Session history not available

Symptom: /history/sessions endpoints return 404

Solution:

1. Check that SESSION_HISTORY_ENABLED=true in .env
2. Verify PostgreSQL is running and accessible
3. Check server logs for initialization errors

Database connection errors

Symptom: Server starts but session endpoints fail with database errors

Solution:

1. Verify PostgreSQL credentials in .env
2. Ensure PostgreSQL is accessible from your network
3. Check PostgreSQL logs for connection issues
4. For Docker: ensure session-db container is running

Migration from old service

Symptom: Want to preserve existing session data

Solution: The database schema is compatible. Point SESSION_DATABASE_URL to your existing PostgreSQL database and the tables will be reused.

API Examples

Create a Session

import requests

response = requests.post(
    "http://localhost:9621/history/sessions",
    json={"title": "Research Session"},
    headers={"X-User-ID": "user@example.com"}
)
print(response.json())

List Sessions

response = requests.get(
    "http://localhost:9621/history/sessions",
    headers={"X-User-ID": "user@example.com"}
)
print(response.json())

Get Session History

session_id = "..."  # UUID from create session
response = requests.get(
    f"http://localhost:9621/history/sessions/{session_id}/history"
)
print(response.json())

Delete Session

response = requests.delete(
    f"http://localhost:9621/history/sessions/{session_id}",
    headers={"X-User-ID": "user@example.com"}
)
print(response.status_code)  # 204 on success

Support

For issues or questions:

• Check the main README.md
• Review LightRAG Server documentation
• Open an issue on GitHub