Sessions

Session configuration allows loading previous conversations and managing agent state. Sessions can be identified by name or configured using detailed query parameters.

Basic Configuration¶

Simple session by name:

agents:
  assistant:
    session: "previous_chat"  # Simple session ID

You can also configure memory settings:

agents:
  assistant:
    session:
      enable: true            # Enable history tracking
      max_tokens: 4000        # Maximum tokens to keep in context
      max_messages: 50        # Maximum messages to keep in context
      provider: "sql"         # Override default storage provider
      session:                # Previous session query
        name: "previous_chat"

Detailed Query Configuration¶

Complex filtering of previous conversations:

agents:
  assistant:
    session:
      name: "coding_session"           # Session identifier
      agents: ["analyzer", "planner"]  # Filter by agent names
      since: "2h"                      # Time periods: 1h, 2d, 1w, etc.
      until: "1h"                      # Up until time period
      contains: "python"               # Filter by content
      roles: ["user", "assistant"]     # Filter by message roles
      limit: 100                       # Max messages to load
      include_forwarded: true          # Include forwarded messages

Time Period Examples¶

The since and until fields support various formats:

agents:
  assistant:
    session:
      # Supported formats
      since: "1h"    # 1 hour ago
      since: "2d"    # 2 days ago
      since: "1w"    # 1 week ago
      since: "30m"   # 30 minutes ago
      since: "1.5h"  # 1.5 hours ago

Role Filtering¶

Filter messages by their roles:

agents:
  assistant:
    session:
      roles:
        - "user"       # User messages
        - "assistant"  # Assistant responses
        - "system"     # System messages

Usage Examples¶

Continue Previous Chat¶

agents:
  assistant:
    session: "last_chat"  # Simple continuation

Load Recent History¶

agents:
  assistant:
    session:
      since: "24h"    # Last 24 hours
      limit: 50       # Max 50 messages

Load Specific Topic¶

agents:
  assistant:
    session:
      contains: "project X"  # Messages about Project X
      agents: ["planner"]    # From planner agent
      since: "1w"           # From last week

Team History¶

agents:
  coordinator:
    session:
      agents: ["researcher", "writer", "reviewer"]
      roles: ["assistant"]  # Only assistant messages
      since: "1d"          # From last day

History Processors¶

History processors allow you to transform message history before each model call using custom Python functions. This is useful for filtering, summarizing, or modifying context dynamically.

Basic Usage¶

agents:
  my_agent:
    session:
      history_processors:
        - my_module:filter_old_messages
        - my_module:summarize_history

Each processor is an import path to a callable with one of these signatures:

# Simple synchronous processor
def processor(messages: list[ModelMessage]) -> list[ModelMessage]:
    return messages[-10:]  # Keep only last 10 messages

# Async processor
async def processor(messages: list[ModelMessage]) -> list[ModelMessage]:
    return await async_filter(messages)

# With RunContext access (for token usage, deps, etc.)
def processor(
    ctx: RunContext,
    messages: list[ModelMessage]
) -> list[ModelMessage]:
    if ctx.usage.total_tokens > 8000:
        return messages[-5:]
    return messages

Execution Order¶

When both compaction pipeline and history processors are configured:

CompactionPipeline runs first (filtering, truncation)
History Processors run second (custom transformations)
LLM Request is made with processed history

Security Considerations¶

History processors execute arbitrary Python code. Only use trusted import paths and avoid side effects (network calls, file I/O) in processors.