Skip to content

Session Management

Jump to bottom
Markel Cuesta edited this page Dec 21, 2025 · 1 revision

Session Management

Sessions allow you to organize, persist, and resume conversations with full history.

Quick Start

Creating Named Sessions

# Create or resume a named session
REDIS_ENABLED=true pnpm start --session my-project

# With web streaming
REDIS_ENABLED=true WEB_STREAM_ENABLED=true pnpm start --session frontend-work

Auto-Generated Sessions

Without a --session flag, a unique session ID is automatically generated:

REDIS_ENABLED=true pnpm start
# Creates: session-1734782567890-a3f8k2

Resuming Sessions

Use the same session name to continue a previous conversation:

pnpm start --session my-project

The web UI sidebar (http://localhost:3000) displays all available sessions. Click on any session to view its history and copy its name for CLI resumption.

Multiple Concurrent Sessions

Run different sessions simultaneously in separate terminals:

# Terminal 1
pnpm start --session frontend-ui

# Terminal 2
pnpm start --session backend-api

# Terminal 3
pnpm start --session research

Each session maintains independent conversation history and streams.

Configuration

CLI Flag (Recommended)

pnpm start --session <name>

Config File

Set a default session name in config.json:

{
  "redis": {
    "enabled": true,
    "sessionName": "my-default-session"
  }
}

Environment Variable

REDIS_SESSION_NAME=temp-session pnpm start

Priority: CLI flag > Environment variable > Config file

Session Data Storage

Messages

  • Location: Redis List at session:{sessionName}:messages
  • Format: JSON-serialized message objects
  • Content: Full conversation history in chronological order

Metadata

  • Location: Redis Hash at session:{sessionName}:metadata
  • Contains: Session name, message count, timestamps, activity info
  • Purpose: Enables session listing and sorting in web UI

Real-Time Streams

  • Channel: ai-chat:stream:{sessionName}
  • Purpose: Session-specific pub/sub for web streaming
  • Behavior: Each session streams independently to its own channel

TTL (Time-To-Live)

Configure automatic session expiration:

{
  "redis": {
    "ttl": 86400  // 24 hours in seconds
  }
}

Or via environment:

REDIS_TTL=86400 pnpm start

Sessions expire after the specified period of inactivity.

Architecture

Sessions are managed through abstracted storage layers:

MessageHistory

Abstract class for message storage with implementations:

  • RedisMessageHistory - Persistent Redis storage
  • InMemoryMessageHistory - Non-persistent memory storage

SessionStore

Abstract class for session metadata with implementations:

  • RedisSessionStore - Redis Hash storage
  • Extensible to PostgreSQL, MongoDB, etc.

Shared Abstractions

The /shared directory contains storage abstractions used by both CLI and web app, ensuring consistent session management across platforms.

See Also

Clone this wiki locally