t6_mem0_v2/migrations/supabase/README.md

# Supabase Migrations for T6 Mem0 v2

## Overview

This directory contains SQL migrations for setting up the Supabase vector store used by T6 Mem0 v2.

## Migrations

### 001_init_vector_store.sql

Initial setup migration that creates:

- **pgvector extension**: Enables vector similarity search
- **t6_memories table**: Main storage for memory vectors and metadata
- **Indexes**: HNSW for vectors, B-tree for filters, GIN for JSONB
- **Functions**:
  - `match_t6_memories()`: Vector similarity search with filters
  - `get_t6_memory_stats()`: Memory statistics
  - `update_t6_memories_updated_at()`: Auto-update timestamp
- **View**: `t6_recent_memories` for quick access to recent entries

## Applying Migrations

### Method 1: Supabase SQL Editor (Recommended)

1. Open your Supabase project dashboard
2. Navigate to SQL Editor
3. Create a new query
4. Copy and paste the contents of `001_init_vector_store.sql`
5. Click "Run" to execute

### Method 2: psql Command Line

```bash
# Connect to your Supabase database
psql "postgresql://supabase_admin:PASSWORD@172.21.0.12:5432/postgres"

# Run the migration
\i migrations/supabase/001_init_vector_store.sql
```

### Method 3: Programmatic Application

```python
import psycopg2

# Connect to Supabase
conn = psycopg2.connect(
    "postgresql://supabase_admin:PASSWORD@172.21.0.12:5432/postgres"
)

# Read and execute migration
with open('migrations/supabase/001_init_vector_store.sql', 'r') as f:
    migration_sql = f.read()

with conn.cursor() as cur:
    cur.execute(migration_sql)
    conn.commit()

conn.close()
```

## Verification

After applying the migration, verify the setup:

```sql
-- Check if pgvector extension is enabled
SELECT * FROM pg_extension WHERE extname = 'vector';

-- Check if table exists
\d t6_memories

-- Verify indexes
\di t6_memories*

-- Test the similarity search function
SELECT * FROM match_t6_memories(
    '[0.1, 0.2, ...]'::vector(1536),  -- Sample embedding
    10,                                -- Match count
    'test_user',                       -- User ID filter
    NULL,                              -- Agent ID filter
    NULL                               -- Run ID filter
);

-- Get memory statistics
SELECT * FROM get_t6_memory_stats();
```

## Rollback

If you need to rollback the migration:

```sql
-- Drop view
DROP VIEW IF EXISTS t6_recent_memories;

-- Drop functions
DROP FUNCTION IF EXISTS get_t6_memory_stats();
DROP FUNCTION IF EXISTS match_t6_memories(vector, INT, TEXT, TEXT, TEXT);
DROP FUNCTION IF EXISTS update_t6_memories_updated_at();

-- Drop trigger
DROP TRIGGER IF EXISTS t6_memories_updated_at_trigger ON t6_memories;

-- Drop table (WARNING: This will delete all data!)
DROP TABLE IF EXISTS t6_memories CASCADE;

-- Optionally remove extension (only if not used elsewhere)
-- DROP EXTENSION IF EXISTS vector CASCADE;
```

## Schema

### t6_memories Table

| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| embedding | vector(1536) | OpenAI embedding vector |
| metadata | JSONB | Flexible metadata |
| user_id | TEXT | User identifier |
| agent_id | TEXT | Agent identifier |
| run_id | TEXT | Run identifier |
| memory_text | TEXT | Original memory text |
| created_at | TIMESTAMPTZ | Creation timestamp |
| updated_at | TIMESTAMPTZ | Last update timestamp |
| hash | TEXT | Deduplication hash (unique) |

### Indexes

- **t6_memories_embedding_idx**: HNSW index for fast vector search
- **t6_memories_user_id_idx**: B-tree for user filtering
- **t6_memories_agent_id_idx**: B-tree for agent filtering
- **t6_memories_run_id_idx**: B-tree for run filtering
- **t6_memories_created_at_idx**: B-tree for time-based queries
- **t6_memories_metadata_idx**: GIN for JSON queries
- **t6_memories_text_search_idx**: GIN for full-text search

## Notes

- The HNSW index provides O(log n) approximate nearest neighbor search
- Cosine distance is used for similarity (1 - cosine similarity)
- All timestamps are stored in UTC
- The hash column ensures deduplication of identical memories
- Metadata is stored as JSONB for flexible schema evolution

## Support

For issues or questions about migrations, refer to:
- [Supabase Vector Documentation](https://supabase.com/docs/guides/database/extensions/pgvector)
- [pgvector Documentation](https://github.com/pgvector/pgvector)
- Project Architecture: `../../ARCHITECTURE.md`