Conversation Session Management#

RAGFlow organizes chat history through a Dialog → Conversation (one-to-many) hierarchy. A Dialog (also called a "chat" in the REST API) holds LLM configuration, prompt templates, and knowledge-base bindings. A Conversation (also called a "session") belongs to exactly one Dialog and stores the full message history for a single user thread.

Key entities:

• Dialog table — LLM config, prompt settings, kb_ids, tenant_id 1
• Conversation table — id, dialog_id FK, name, message (JSON), reference (JSON), user_id 2
• API4Conversation table — like Conversation but adds tokens, duration, round, source, dsl, thumb_up, errors for API/agent-driven sessions 3

Session ID Generation#

Session IDs are 32-character hex strings produced by get_uuid() in common/misc_utils.py:

def get_uuid():
    return uuid.uuid1().hex

uuid.uuid1() encodes a timestamp + MAC address, making IDs time-ordered and globally unique. IDs are assigned at creation time by the REST API layer and by async_completion.

Exception — channel sessions: get_or_create_for_channel() derives a deterministic ID from SHA-256(dialog_id:channel_id:chat_id)[:32] so history survives process restarts without storing a back-reference column. The method includes a migration path from the prior MD5 scheme and uses IntegrityError catch-and-retry for concurrent callers 4.

Message & Reference Persistence#

Messages are not stored in a separate table. Each Conversation row has a message JSONField — a list of {role, content, id, created_at} objects. The reference JSONField is a parallel list: reference[n] holds the retrieval chunks used for the n-th assistant response.

structure_answer() is the single writer for both arrays. It appends or updates the last assistant entry during streaming and commits reference[-1] when the final answer arrives. After each completed exchange, ConversationService.update_by_id() flushes the full row back to the database .

New sessions are seeded with the Dialog's prompt_config.prologue as the first assistant message 6.

REST API Surface#

All session endpoints nest under the parent chat_id, enforcing the Dialog ownership check before any session operation 7.

_build_session_response() normalizes the DB model for API consumers, remapping dialog_id → chat_id and message → messages.

ConversationService#

ConversationService in api/db/services/conversation_service.py wraps the Conversation model. Key methods:

• get_list(dialog_id, ...) — paginated query filtered by dialog_id; supports optional user_id and name filters.
• get_or_create_for_channel(...) — idempotent upsert for channel-backed sessions with a deterministic SHA-256 ID and race-safe IntegrityError handling.
• get_all_conversation_by_dialog_ids(dialog_ids) — bulk fetch across multiple dialogs, batched in pages of 100.

Dual Session Tables#

Two parallel tables serve different integration paths:

The iframe/embed flow (async_iframe_completion) writes to API4Conversation and calls API4ConversationService.append_message() instead of update_by_id.