hermes-agent/docs/warm-session-provisioning.md

Warm Session Provisioning

Issue: #327

Overview

Warm session provisioning allows creating pre-contextualized agent sessions that start with established patterns and context, reducing initial errors and improving session quality.

Key Concepts

Session Seed

A SessionSeed contains:

• System context: Key instructions and context from previous sessions
• Tool examples: Successful tool call patterns to establish conventions
• User patterns: User interaction style preferences
• Context markers: Important files, URLs, and references

Warm Template

A WarmTemplate wraps a seed with metadata:

• Name and description
• Source session ID
• Usage statistics
• Success rate tracking

Usage

Extract Template from Session

# Create a template from a successful session
hermes warm extract SESSION_ID --name "Code Review Template" --description "For code review tasks"

# The template captures:
# - System context and key instructions
# - Successful tool call examples
# - User interaction patterns
# - Important context markers

List Templates

hermes warm list

Output:

=== Warm Session Templates ===

ID: warm_20260413_123456
  Name: Code Review Template
  Description: For code review tasks
  Usage: 5 times, 80% success

Test Warm Session

# Test what messages would be generated
hermes warm test warm_20260413_123456 "Review this pull request"

Output shows the messages that would be sent to the agent, including:

• System context with warm-up information
• Tool call examples
• The actual user message

Delete Template

hermes warm delete warm_20260413_123456

How It Works

1. Extraction Phase

When you extract a template:

1. System messages provide base context
2. First 10 user messages establish patterns
3. Successful tool calls become examples
4. File paths and URLs become context markers

2. Bootstrap Phase

When creating a warm session:

1. System context is injected as initial message
2. Tool examples establish successful patterns
3. User message follows the warm-up context
4. Agent starts with established conventions

Example Workflow

# 1. Have a successful session
# ... work with the agent on a complex task ...

# 2. Extract template from that session
hermes warm extract abc123 --name "API Integration" --description "REST API work"

# 3. Later, start a new session with warm context
# The agent will have context about:
# - Your coding style
# - Successful tool patterns
# - Common file paths
# - Previous instructions

Benefits

1. Reduced Initial Errors: Agent starts with proven patterns
2. Consistent Behavior: Established conventions carry over
3. Faster Context: No need to re-explain preferences
4. Quality Tracking: Success rate shows template effectiveness

Implementation Details

Files

• tools/warm_session.py: Core implementation
• ~/.hermes/warm_templates/: Template storage

Data Flow

Session -> SessionExtractor -> SessionSeed -> WarmTemplate
                                            ↓
WarmSessionBootstrapper -> Messages -> Agent

Research Context

This implementation addresses Finding #4 from the empirical audit:

• Marathon sessions show different error patterns
• Context establishment affects session quality
• Pre-seeding can improve initial session reliability

Future Enhancements

1. Automatic Template Creation: Create templates from high-performing sessions
2. Template Sharing: Export/import templates between installations
3. A/B Testing: Compare warm vs cold session performance
4. Smart Selection: Automatically choose best template for task type