Session Management

Last updated: April 11, 2026

Assistant Session Management

Session management is the mechanism that maintains state and context for every user interaction with the assistant module.

The ChatSession Structure

Every interaction creates or resumes a ChatSession (defined in assistant/assistant.go).

Core Fields

  • ID: A unique UUID for the session.
  • Agent: The persona assigned to the session (Nikki, Sasha, etc.).
  • History: A chronological list of Message objects (User, Assistant, System, Tool).
  • Tools: A map of tools available in this specific session.
  • UserRole: The RBAC role of the user (MasterAdmin, Partner, etc.).
  • Platform: The source platform (WhatsApp, Discord, etc.).

Persistence & Rehydration

Sessions are persistent across restarts.

  • Storage: Sessions are saved as JSON files in the chats/ directory.
  • Metadata: chats/sessions.json acts as an index of all active and historical sessions.
  • Rehydration: When a new message arrives, the system looks up the last active session for that user/platform and reloads it from disk.

Lifecycle Events

  1. Creation: Triggered by a new user interaction or explicit session start command.
  2. Activation: The session is loaded into memory and the LLM context is prepared.
  3. Execution: The ReAct loop runs within the session context.
  4. Suspension: After a period of inactivity, the session is serialized and saved.
  5. Cleanup: Stale sessions are periodically removed by the background maintenance loop (at 03:00 AM daily).

Sequence Diagram: Session Flow

sequenceDiagram
    participant U as User
    participant I as Ingress (e.g. WhatsApp)
    participant A as assistant.go
    participant CP as chat_persistence.go
    participant LLM as Multi-LLM Provider

    U->>I: Sends Message
    I->>A: QueryAssistant(query, user, platform)
    A->>CP: Load Last Session (userID, platform)
    CP-->>A: Return ChatSession
    A->>LLM: Process with Context
    LLM-->>A: Agent Response
    A->>CP: Save Updated Session
    A->>I: Send Response to User
    I->>U: Delivers Response

Key Functions

  • NewChatSession(): Initializes a new session with agent-specific tools and prompt.
  • SaveChatSession(session *ChatSession): Persists the session state to disk.
  • LoadChatSession(chatID string): Retrieves a session from storage.
  • SaveLastUsedAgent(userID, agentName string): Manages "sticky agent" memory.

Guidance for AI Agents

  • Context Awareness: Be aware that the current session history is your primary source of short-term truth.
  • Session IDs: If you need to reference an asynchronous task, always include the ChatID.

Cross-References