Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Session Management controls the lifecycle, configuration, and message history of individual AI dialogue streams within the Agent workspace. It maintains the state of conversations, including associated LLM providers, model settings, and technical parameters like temperature and token limits.
The system persists data locally and synchronizes it across devices using encrypted payloads. Users interact with sessions through the Sidebar and ChatArea, while the MainScreen orchestrates the active state between these components.
Data Structure and Lifecycle
A session consists of a unique identifier, metadata, configuration parameters, and a chronological list of messages. The system initializes new sessions with default values, including an RTK (Real-Time Knowledge) configuration for context optimization.
Session Object Model
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier, typically generated via Date.now() |
title | string | User-defined or default name for the conversation |
systemPromptId | string | ID of the active behavior overlay (e.g., General Assistant) |
modelId | string | The specific LLM model version (e.g., llama3.1:8b) |
providerId | string | The target backend (e.g., ollama, openai) |
temperature | number | Randomness control (0.0 to 1.2) |
messages | Message[] | Array of user, assistant, and system messages |
rtkConfig | object | Optimization settings for context and compression |
Sources: [src/hooks/useSessions.ts:25-46], [src/data.ts:284-338]
Persistence Flow
The useSessions hook manages state persistence using the browser's localStorage. When the application initializes, it retrieves stored sessions. Any subsequent state changes trigger an effect that updates the agent_sessions key in storage.
Sources: [src/hooks/useSessions.ts:7-22]
Application Orchestration
The MainScreen component serves as the central hub for session state. It tracks the activeSessionId and ensures at least one session exists upon startup.
Active Session Management
- Initialization: If no sessions exist,
MainScreencallscreateSessionand sets the resulting ID as active. - Selection: The
SidebarpassesonSelectSessionto update theactiveSessionId. - Validation: If an active session is deleted, the system automatically reverts to the first available session.
Sources: [src/screens/MainScreen.tsx:30-44]
Messaging Flow
When a user sends a message, the handleSendMessage function performs the following steps:
- Validates input and active session state.
- Checks for RTK (Real-Time Knowledge) bypass flags.
- Appends the user message to the session's message array via
updateSessionMessages. - Simulates assistant latency and appends the AI response.
Sources: [src/screens/MainScreen.tsx:50-80], [src/utils/ai.ts:16-100]
User Interface Components
Sidebar Interface
The Sidebar provides management controls for the session list. It enables users to:
- Add: Establish new conversation branches.
- Rename: Modify the title of an existing session.
- Delete: Purge dialogue history and session metadata.
- Monitor: View the message count and active model tag for each session.
Sources: [src/components/Sidebar.tsx:17-105]
Chat Configuration
The ChatArea component exposes session-specific parameters through a configuration drawer. These settings directly modify the session state in real-time.
| Parameter | UI Control | Logic |
|---|---|---|
| Provider | Select Dropdown | Swaps between local (Ollama) and remote (OpenAI) endpoints |
| Model | Datalist Input | Selects specific versions available for the chosen provider |
| Temperature | Range Slider | Adjusts the temperature field for deterministic or creative output |
| Max Tokens | Range Slider | Truncates the output buffer to manage context window limits |
Sources: [src/components/ChatArea.tsx:186-258]
Context and behavior Selection
Sessions are bound to system prompt presets, which Agent calls "Behavior Overlays". These presets define the persona and technical constraints of the AI.
Behavior Overlay Injection
Users can inject behaviors using the PromptStudio or through autocomplete in the chat input using the / prefix. When a new behavior is selected, the onChangeSessionParam function updates the systemPromptId of the active session, which is then passed to the AI provider during response generation.
Sources: [src/components/PromptStudio.tsx:210-224], [src/components/ChatArea.tsx:128-135]
File Attachment Integration
Sessions support local file context. Users attach files using the @ symbol or a paperclip icon. The names of attached files are stored within individual messages, allowing the AI to reference specific virtual filesystem contents during the completion request.
Sources: [src/components/ChatArea.tsx:148-154], [src/utils/ai.ts:107-111]
Summary
Session Management provides the framework for isolated, configurable, and persistent technical dialogues. By separating session state (history and config) from provider logic (AI endpoints), the system allows users to seamlessly switch between models and behaviors while maintaining a continuous workspace context.