feat: Add Layer 4 Session History Manager for Cross-Conversation Context Management

[yhjun1026]

Summary

This PR implements Layer 4 Session History Manager, a comprehensive cross-conversation context management system that addresses two critical issues:

1. Pure Model Output Handling: Provides dedicated tracking and management for agent responses without tool calls
2. Cross-Conversation Context Inheritance: Enables agents to maintain context across multiple conversation turns

Key Features

1. SessionConversation Data Model

• Complete conversation unit tracking with user queries, agent responses, and execution details
• Automatic detection of pure model outputs (no tool calls)
• Rich metadata including timestamps, token counts, and success status

2. SessionHistoryManager with Three-Tier Storage

• Hot Zone: Recent conversations with full details (configurable, default 3)
• Warm Zone: Compressed summaries (configurable, default 5)
• Cold Zone: Archived references for long-term storage

3. Pure Model Output Support

• Dedicated pure_model_output field for tracking non-tool responses
• Automatic detection via has_tool_calls flag
• Special handling in history context building

4. Automatic Compression & Archiving

• Auto-compress when hot zone exceeds threshold
• Smart summary generation using Layer 3 Compaction logic
• Graceful archiving to prevent memory overflow

5. Seamless Integration

• Core V1: Integration points in generate_reply() and load_thinking_messages()
• Core V2: Integration points in run() method and message management
• Prompts: Ready-to-use templates with session_history variable

Implementation Details

Files Added

• session_history.py (550+ lines) - Core implementation
• SESSION_HISTORY_INTEGRATION_GUIDE.md - Comprehensive integration guide
• PROJECT_SUMMARY.md - Complete project documentation
• test_session_history.py - Unit tests (9 test methods)
• test_session_history_integration.py - Integration tests (2 test classes)
• validate_session_history.py - Validation script (6 validation tests)

Code Quality

• ✅ Comprehensive unit tests
• ✅ Integration tests for Core V1 and Core V2
• ✅ Validation script - all tests passing
• ✅ Detailed code documentation
• ✅ Type hints throughout

Testing

All tests have been validated and pass successfully:

✅ SessionConversation data model
✅ SessionHistoryManager initialization
✅ Pure model output tracking
✅ Automatic compression mechanism
✅ History context building
✅ Complete workflow

Run the validation script:

python packages/derisk-core/src/derisk/agent/core/memory/tests/validate_session_history.py

Usage Example

from derisk.agent.expand.react_master_agent import ReActMasterAgent
from derisk.agent.core.memory.session_history import SessionHistoryConfig

agent = ReActMasterAgent(
    enable_session_history=True,  # Enable Layer 4
    session_history_config=SessionHistoryConfig(
        hot_retention_count=3,
        warm_retention_count=5,
        include_pure_model_outputs=True,  # Enable pure model output tracking
    ),
)

# Agent automatically:
# 1. ✅ Loads history context at conversation start
# 2. ✅ Saves conversation records on completion
# 3. ✅ Detects and tracks pure model outputs
# 4. ✅ Auto-compresses and archives when needed

Benefits

Before (Only 3-Layer Compression)

User: "Analyze this log"
Agent: [Tool call] [Analysis] [Result]
History: [Compressed by Layer 3]

User: "What did you analyze?"
Agent: ❌ Cannot answer - history compressed

After (With Layer 4 Session History)

User: "Analyze this log"
Agent: [Tool call] [Analysis] [Result]
SessionHistory: ✅ Saved to Hot Zone

User: "What did you analyze?"
Agent: ✅ Loads from SessionHistory
      "I analyzed xxx log and found..."

Configuration

@dataclass
class SessionHistoryConfig:
    hot_retention_count: int = 3        # Hot zone size
    warm_retention_count: int = 5       # Warm zone size
    cold_retention_days: int = 30       # Archive retention
    max_hot_tokens: int = 6000          # Token limit
    include_pure_model_outputs: bool = True  # Pure model tracking

Documentation

• 📖 Integration Guide
• 📊 Project Summary

Related Issues

Addresses the need for:

• Cross-conversation context inheritance
• Pure model output tracking and management
• Long-term memory management for agent systems

Checklist

• Code implementation complete
• Unit tests passing
• Integration tests passing
• Validation script passing
• Documentation complete
• Ready for production use

[tptpp]

R+