lexigram-ai-session

AI session management for the Lexigram Framework — branching, checkpointing, multi-agent sessions

Overview

Stateful conversation session management for the Lexigram AI framework. Provides full session lifecycle (create → turn → checkpoint → restore → close), pluggable persistence backends, timeline branching, and multi-agent group sessions. Zero-config usage starts with sensible defaults.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-ai-session

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module

from lexigram.ai.session import SessionModule
from lexigram.ai.session.config import SessionConfig


@module(
    imports=[
        SessionModule.configure(
            SessionConfig(backend="in_memory"),
            enable_cleanup_scheduler=True,
        )
    ]
)
class AppModule(Module):
    pass


async with Application.boot(modules=[AppModule]) as app:
    # use app.container to resolve services
    ...

Configuration

Zero-config usage: Call SessionModule.configure() with no arguments to use defaults.

Option 1 — YAML file

# application.yaml
ai_session:
  backend: "cache"
  session_ttl: 86400
  max_turns_per_session: 1000
  auto_checkpoint_interval: 10
  consolidate_on_close: true

Option 2 — Profiles + Environment Variables (recommended)

export LEX_AI_SESSION__BACKEND=cache
# Environment variables for each field

Option 3 — Python

from lexigram.ai.session.config import SessionConfig
from lexigram.ai.session import SessionModule

config = SessionConfig(
    backend="cache",
    session_ttl=86400,
    max_turns_per_session=1000,
    auto_checkpoint_interval=10,
)
SessionModule.configure(config)

Config reference

Module Factory Methods

Key Features

• Session lifecycle: Create, turn, checkpoint, restore, suspend, close with FSM-enforced status transitions
• Timeline branching: BranchManager forks sessions into independent timelines that can be merged
• Multi-agent groups: GroupSession coordinates multiple agents with configurable turn-taking strategies
• Persistence backends: In-memory, Redis (cache), and database stores
• Web middleware: SessionMiddleware resolves session ID from cookie or HTTP header
• Analytics: Session analytics with turn counts, token totals, and cost tracking

Testing

async with Application.boot(modules=[SessionModule.stub()]) as app:
    # your test code
    ...

Key Source Files