Alexander Whitestone
5d8e7bbe4f
Some checks failed
Forge CI / smoke-and-build (pull_request) Failing after 59s
Documentation for #327 implementation.
140 lines
3.6 KiB
Markdown
140 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|