# Supabase Session Manager

{{ community_contribution_banner }}

The [Strands Supabase Session Manager](https://github.com/siddharthkrish/strands-supabase-session-manager) is a persistent session manager for Strands Agents that uses Supabase (PostgreSQL) as the storage backend. It enables agents to maintain conversation history and state across sessions, and works with both a local Supabase instance (via the Supabase CLI) and a hosted Supabase Cloud project.

## Installation

```bash
pip install supabase-strands
```

## Database Setup

Run the provided migration in your Supabase SQL Editor (or via `supabase db reset` locally) before using the session manager:

```
migrations/001_create_session_tables.sql
```

For production deployments, also apply the Row-Level Security migration:

```
migrations/002_enable_rls.sql
```

Migrations are available in the [GitHub repository](https://github.com/siddharthkrish/strands-supabase-session-manager/tree/main/migrations).

## Usage

Set your Supabase credentials as environment variables:

```bash
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_KEY="your-anon-key"
```

Then use `SupabaseSessionManager` with a Strands Agent:

```python
from strands import Agent
from supabase_strands import SupabaseSessionManager

# Create a session manager with a unique session ID
session_manager = SupabaseSessionManager(session_id="user-123")
agent = Agent(session_manager=session_manager)

# Conversations are automatically persisted to Supabase
agent("Hello! My name is Alice and I love Python programming.")
agent("What's my name and what do I love?")

# Resume the same session from a new agent instance
session_manager_2 = SupabaseSessionManager(session_id="user-123")
agent_2 = Agent(session_manager=session_manager_2)
agent_2("Can you remind me what we discussed earlier?")
```

## Configuration

Credentials are read from `SUPABASE_URL` and `SUPABASE_KEY` environment variables by default. You can also pass them explicitly:

```python
session_manager = SupabaseSessionManager(
    session_id="user-123",
    supabase_url="https://your-project.supabase.co",
    supabase_key="your-anon-key"
)
```

### Parameters

- `session_id`: Unique identifier for the session
- `supabase_url`: Supabase project URL (defaults to `SUPABASE_URL` env var)
- `supabase_key`: Supabase API key (defaults to `SUPABASE_KEY` env var)

### Database Schema

```
sessions (session_id PK, session_type, created_at, updated_at)
    └── agents (session_id FK, agent_id, state JSONB, conversation_manager_state JSONB)
        └── messages (session_id FK, agent_id, message_id, message JSONB, redact_message JSONB)
```

Foreign keys use `ON DELETE CASCADE` for referential integrity.

## Available Methods

The following methods are used transparently by Strands:

- `create_session(session)`: Create a new session
- `read_session(session_id)`: Retrieve session data
- `delete_session(session_id)`: Remove a session and all associated data
- `create_agent(session_id, agent)`: Store an agent in a session
- `read_agent(session_id, agent_id)`: Retrieve agent data
- `update_agent(session_id, agent)`: Update agent state
- `create_message(session_id, agent_id, message)`: Store a message
- `read_message(session_id, agent_id, message_id)`: Retrieve a message
- `update_message(session_id, agent_id, message)`: Update a message
- `list_messages(session_id, agent_id, limit=None, offset=0)`: List all messages for an agent

## Requirements

- Python 3.10+
- Supabase — [local via CLI](https://supabase.com/docs/guides/local-development) or a [hosted project](https://supabase.com) (free tier works)
- strands-agents >= 1.0.0
- supabase >= 2.0.0

## References

- **PyPI**: [supabase-strands](https://pypi.org/project/supabase-strands/)
- **GitHub**: [siddharthkrish/strands-supabase-session-manager](https://github.com/siddharthkrish/strands-supabase-session-manager)
- **Issues**: [GitHub Issues](https://github.com/siddharthkrish/strands-supabase-session-manager/issues)
