Add session-level metadata storage to SQLAlchemySession

[Jash271]

Please read this first

• Have you read the docs? Yes - Agents SDK docs
• Have you searched for related issues? Yes - no existing issues found

Describe the feature

Add session-level metadata storage to SQLAlchemySession

Problem

SQLAlchemySession currently stores conversation messages but has no built-in way to store session-level metadata like:

• User ownership (owner_id)
• Session titles and tags
• Configuration (incognito mode, preferences)
• Custom application data

Developers must maintain separate mapping tables or external systems, causing data fragmentation and complexity.

Proposed Solution

Add a session_metadata table using Entity-Attribute-Value (EAV) pattern for flexible key-value storage.

API:

# Set metadata
await session.set_metadata({"owner_id": "user_123", "title": "My Chat", "tags": ["work"]})

# Get metadata (returns None for missing keys)
await session.get_metadata(keys=["owner_id", "title"])
# Returns: {"owner_id": "user_123", "title": "My Chat"}

# Get all metadata
await session.get_metadata()

# Delete metadata
await session.delete_metadata(keys=["tags"])  # Delete specific keys
await session.delete_metadata()  # Delete all

# Find sessions by metadata (cross-session query)
session_ids = await session.find_sessions_by_metadata("owner_id", "user_123")

Schema:

CREATE TABLE agent_sessions_metadata (
    session_id VARCHAR REFERENCES agent_sessions(session_id) ON DELETE CASCADE,
    key VARCHAR(255) NOT NULL,
    value TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (session_id, key)
);
CREATE INDEX idx_session_metadata_key_value ON session_metadata(key, value);

Benefits

• Unified storage: Messages + metadata in one system
• Efficient queries: Index enables fast "find all sessions for user X"
• Flexible: Add any metadata keys without schema changes
• Cross-database: PostgreSQL, MySQL, SQLite compatible
• Backward compatible: No breaking changes

Use Cases

• Multi-tenant apps: Associate sessions with users
• Organization: Titles, tags, descriptions
• Privacy: Incognito/ephemeral flags
• Analytics: Track usage metrics
• Configuration: Session-specific settings

---

I'm happy to implement this and submit a PR

[seratch]

Thanks for sharing this idea! It could be useful for you, but I think it’s a rather specific use case. When using this feature with the Agents SDK, you typically wouldn’t search by metadata. For now, my recommendation would be to inherit the built-in SQLAlchemy session store and add your customizations on top of it.

[Jash271]

Thanks for the feedback! I just wanted to add that this would actually be a very common pattern when persisting sessions.

The core issue is that if you’re storing sessions in a database, you almost always need to associate them with something — a user ID, workspace, or tenant. Without that association, developers often end up maintaining a separate mapping table.

Common scenarios include:

• load all sessions for user_123
• Load conversations for workspace_456
• Display session titles in a history UI
• Clean up old sessions for a specific user

I do acknowledge that this might not be directly used in the agentic workflow, but it feels like a foundational building block that would make persistent session management much more practical for developers integrating the SDK.

Since we’re already creating database tables for sessions, adding basic metadata management feels like a natural extension rather than a highly specific feature. It’s completely opt-in and provides a standard pattern so users don’t have to build custom implementations themselves.

Happy to discuss further if there’s something I might be missing or not fully understanding!

[seratch]

Thanks for sharing more details! I can see the use case definitely exists, but we’d like to hold off on adding built-in methods for it at the moment. Your code should work as expected, so please go ahead with your subclass that inherits from SQLAlchemySession for now.