🎯 Tutorial 7: Sessions & Memory Management

Master automatic conversation memory with Sessions! This tutorial teaches you how to use the OpenAI Agents SDK's built-in session memory to maintain conversation history across multiple agent runs without manual memory management.

🎯 What You'll Learn

• Automatic Memory: Sessions handle conversation history automatically
• SQLite Sessions: Persistent and in-memory conversation storage
• Memory Operations: Adding, retrieving, and managing conversation items
• Session Management: Multiple sessions and custom implementations

🧠 Core Concept: What Are Sessions?

Sessions provide automatic conversation memory that eliminates the need to manually handle .to_input_list() between turns. Think of sessions as a smart conversation database that:

• Automatically stores all conversation history
• Retrieves context before each agent run
• Maintains separate conversations for different session IDs
• Supports persistent storage across application restarts

┌─────────────────────────────────────────────────────────────┐
│                    SESSION WORKFLOW                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  USER INPUT                                                 │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    1. RETRIEVE HISTORY                     │
│  │   SESSION   │◀─────────────────────────────────────────┐ │
│  │   MEMORY    │                                          │ │
│  └─────────────┘    2. PREPEND TO INPUT                   │ │
│       │                                                   │ │
│       ▼                                                   │ │
│  ┌─────────────┐                                          │ │
│  │    AGENT    │    3. PROCESS WITH CONTEXT               │ │
│  │   RUNNER    │                                          │ │
│  └─────────────┘                                          │ │
│       │                                                   │ │
│       ▼                                                   │ │
│  ┌─────────────┐    4. STORE NEW ITEMS                    │ │
│  │   RESPONSE  │──────────────────────────────────────────┘ │
│  │  GENERATED  │                                            │
│  └─────────────┘                                            │
└─────────────────────────────────────────────────────────────┘

🚀 Tutorial Overview

This tutorial demonstrates three key session patterns:

1. Basic SQLite Sessions (basic_sessions.py)

• In-memory and persistent session storage
• Automatic conversation history management
• Simple multi-turn conversations

2. Advanced Memory Operations (memory_operations.py)

• Memory manipulation with get_items(), add_items(), pop_item()
• Conversation corrections and modifications
• Session management operations

3. Multiple Sessions (multi_sessions.py)

• Managing different conversation contexts
• Session isolation and organization
• Custom session implementations

📁 Project Structure

7_sessions/
├── README.md                   # This file - concept explanation
├── requirements.txt            # Dependencies
├── streamlit_sessions_app.py   # Interactive Streamlit demo (recommended)
├── 7_1_basic_sessions/
│   ├── agent.py               # SQLite sessions basics
│   └── README.md              # Basic sessions documentation
├── 7_2_memory_operations/
│   ├── agent.py               # Advanced memory operations
│   └── README.md              # Memory operations documentation
├── 7_3_multi_sessions/
│   ├── agent.py               # Multiple session management
│   └── README.md              # Multi-sessions documentation
└── env.example                # Environment variables template

🎯 Learning Objectives

By the end of this tutorial, you'll understand:

• ✅ How to use SQLiteSession for automatic memory management
• ✅ Difference between in-memory and persistent sessions
• ✅ Advanced memory operations for conversation management
• ✅ Managing multiple concurrent sessions
• ✅ When to use sessions vs manual conversation management

🚀 Getting Started

1. Install OpenAI Agents SDK:

   pip install openai-agents
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Set up environment variables:

   cp env.example .env
   # Edit .env and add your OpenAI API key
   

4. Launch interactive demo (recommended):

   streamlit run streamlit_sessions_app.py
   

   OR run individual examples:

5. Test basic sessions:

   python 7_1_basic_sessions/agent.py
   

6. Try memory operations:

   python 7_2_memory_operations/agent.py
   

7. Test multiple sessions:

   python 7_3_multi_sessions/agent.py
   

🧪 Sample Use Cases

Basic Sessions

• "What city is the Golden Gate Bridge in?" → "What state is it in?"
• "My name is Alice" → "What's my name?"
• "I work as a developer" → "What do I do for work?"

Memory Operations

• Correcting previous messages with pop_item()
• Clearing conversation history with clear_session()
• Adding custom conversation items

Multiple Sessions

• Different users: user_123, user_456
• Different contexts: support_ticket_789, sales_inquiry_101
• Different applications: chatbot_session, assistant_session

🔧 Key Session Patterns

1. Basic Session Usage

from agents import Agent, Runner, SQLiteSession

agent = Agent(name="Assistant", instructions="Reply concisely.")
session = SQLiteSession("conversation_123")

result = await Runner.run(agent, "Hello", session=session)

2. Persistent vs In-Memory

# In-memory (lost when process ends)
session = SQLiteSession("user_123")

# Persistent file-based
session = SQLiteSession("user_123", "conversations.db")

3. Memory Operations

# Get conversation history
items = await session.get_items()

# Add custom items
await session.add_items([{"role": "user", "content": "Hello"}])

# Remove last item (for corrections)
last_item = await session.pop_item()

# Clear all history
await session.clear_session()

💡 Session Design Best Practices

1. Meaningful Session IDs: Use descriptive IDs like user_12345 or support_ticket_789
2. Persistent Storage: Use file-based sessions for production applications
3. Session Isolation: Keep different conversation contexts in separate sessions
4. Memory Management: Use pop_item() for conversation corrections
5. Cleanup: Clear sessions when conversations should start fresh

🔗 Next Steps

After completing this tutorial, you'll be ready for:

• Tutorial 8: Handoffs & Delegation - Agent handoffs and task delegation
• Tutorial 9: Multi-Agent Orchestration - Complex multi-agent workflows
• Tutorial 10: Production Patterns - Real-world deployment strategies

🚨 Troubleshooting

• Memory Not Persisting: Ensure you're using file-based SQLiteSession with a database path
• Session Conflicts: Use unique session IDs for different conversation contexts
• Performance Issues: Consider implementing custom session backends for high-volume applications
• Database Errors: Check file permissions for SQLite database files

💡 Pro Tips

• Start Simple: Begin with in-memory sessions for development and testing
• Plan Session Architecture: Design your session ID strategy before building
• Monitor Memory Usage: Track conversation length and implement cleanup strategies
• Test Session Persistence: Verify that conversations survive application restarts
• Consider Scaling: Plan for custom session implementations in production systems