Skip to content

Memory Management

Agency provides comprehensive memory management capabilities through integration with the OpenAI Agents SDK, enabling persistent conversation state across multiple interactions.

Overview

The memory system consists of three main components:

  • Sessions: SQLite-based storage for conversation history
  • Conversations: High-level conversation management with metadata
  • Factories: Pattern for creating configured instances

Architecture

graph TD
    A[Agency] --> B[ConversationManager]
    B --> C[ConversationStorage]
    B --> D[SQLiteSession]

    E[SessionFactory] --> D
    F[AgencyFactory] --> A
    F --> D

    C --> G[Conversation Files]
    D --> H[SQLite Database]

Key Benefits

  • Persistent Memory: Conversations survive application restarts
  • Flexible Storage: In-memory for testing, file-based for production
  • OpenAI Integration: Seamless compatibility with OpenAI Agents SDK
  • Factory Pattern: Consistent object creation with proper configuration

Integration with OpenAI Agents SDK

The memory system leverages the OpenAI Agents SDK's SQLiteSession class:

from agents import SQLiteSession
from agency.sessions.session_factory import SessionFactory

# Create session for memory
session = SessionFactory.create_memory_session()

# Use with Agency
agency = AgencyFactory.create_agency(
    config=config,
    session=session
)

Memory Modes

In-Memory Sessions

Perfect for testing and temporary interactions:

session = SessionFactory.create_memory_session("test_session")

File-Based Sessions

Persistent storage for production use:

session = SessionFactory.create_file_session(
    session_id="user_123",
    db_path="data/sessions/user_123.db"
)

Conversation Management

High-level API for managing conversation lifecycle:

from agency.conversations.manager import ConversationManager

manager = ConversationManager()

# Create new conversation
conversation = manager.create_conversation(
    name="Customer Support",
    config=agency_config
)

# Add messages
manager.add_message(conversation.id, "user", "Hello!")
response = manager.process_message(conversation.id, "Hello!")

Best Practices

  1. Use Factories: Always create sessions and agencies through factory methods
  2. Session Management: Clean up old sessions periodically in production
  3. Error Handling: Implement proper error handling for database operations
  4. Configuration: Use environment-specific configurations for different deployments

Next Steps

  • Learn about Conversations for detailed conversation management
  • Explore Sessions for session lifecycle management
  • Check Factories for configuration patterns