Database Schema
All data lives in Supabase (PostgreSQL). Row Level Security (RLS) is enabled on all user-facing tables. Service role access is used for background operations.
Core Tables
agents
The central agent record. One row per agent.
| Column | Type | Description |
|--------|------|-------------|
| id | uuid | Primary key |
| user_id | uuid | Owner |
| name | text | Agent name |
| agent_type | text | email, calendar, research, code, custom |
| status | text | active, sleeping, destroyed |
| trust_tier | text | observer, helper, partner, trusted |
| personality_model | text | LLM model ID (e.g. claude-sonnet-4-20250514) |
| personality_tone | text | Communication style |
| personality_verbosity | text | Concise, detailed, etc. |
| objective | text | Primary mission |
| instructions | text | Custom instructions |
| background | text | Agent backstory |
| email_address | text | Agent's Resend email |
| is_head | boolean | Head agent flag (one per user) |
| level | int | XP level |
| xp | int | Experience points |
agent_training_data
Custom knowledge, instructions, and examples attached to agents.
| Column | Type | Description |
|--------|------|-------------|
| agent_id | uuid | Agent FK |
| type | text | knowledge, instruction, example |
| title | text | Entry title |
| content | text | Entry content |
| enabled | boolean | Whether to include in prompts |
agent_skills
Skills installed on each agent.
| Column | Type | Description |
|--------|------|-------------|
| agent_id | uuid | Agent FK |
| skill_slug | text | Unique skill identifier |
| skill_name | text | Display name |
| skill_category | text | Category |
| level | int | Skill level |
agent_knowledge_access
Controls which knowledge collections each agent can access.
| Column | Type | Description |
|--------|------|-------------|
| agent_id | uuid | Agent FK |
| collection_id | uuid | Collection FK |
| access_level | text | read or read_write |
Knowledge Base
knowledge_collections
Groups of knowledge entries.
| Column | Type | Description |
|--------|------|-------------|
| id | uuid | Primary key |
| user_id | uuid | Owner |
| name | text | Collection name |
| description | text | Description |
| is_default | boolean | Default collection flag |
knowledge_entries
Individual knowledge items. Embeddings stored in Pinecone.
| Column | Type | Description |
|--------|------|-------------|
| id | uuid | Primary key |
| user_id | uuid | Owner |
| collection_id | uuid | Collection FK |
| content | text | The knowledge text |
| type | text | fact, preference, knowledge, note, summary |
| importance | float | 0.0 to 1.0 |
| source | text | Origin (manual, halo_onboarding, web_research, agent:id) |
| pinecone_id | text | Vector ID in Pinecone |
Chat & Activity
chat_messages
All conversation history, organized by threads.
| Column | Type | Description |
|--------|------|-------------|
| user_id | uuid | Owner |
| thread_id | text | Thread identifier (e.g. agentId:direct) |
| role | text | user or assistant |
| content | text | Message text |
| agent_id | uuid | Responding agent (nullable) |
| agent_name | text | Agent display name |
feed_events
Activity feed for the home page.
| Column | Type | Description |
|--------|------|-------------|
| user_id | uuid | Owner |
| agent_id | uuid | Related agent |
| type | text | info, task_completed, approval_needed, etc. |
| message | text | Event description |
Integrations & Auth
user_integrations
Encrypted OAuth tokens for external services.
| Column | Type | Description |
|--------|------|-------------|
| user_id | uuid | Owner |
| provider | text | google, notion, slack, github |
| access_token_encrypted | text | Encrypted access token |
| refresh_token_encrypted | text | Encrypted refresh token |
| token_expires_at | timestamptz | Expiration |
| scopes | text | Granted scopes |
| metadata | jsonb | Provider-specific data |
user_personalization
Rich user profile data gathered during onboarding.
| Column | Type | Description |
|--------|------|-------------|
| user_id | uuid | Owner |
| bio | text | Short bio |
| occupation | text | Job title |
| company | text | Company name |
| goals | text | User goals |
| interests | text | Interests |
| about_me | text | Extended profile |
| twitter, linkedin, github, instagram | text | Social handles |
Usage & Billing
usage_logs
Token usage and cost tracking per LLM call.
| Column | Type | Description |
|--------|------|-------------|
| user_id | uuid | Owner |
| agent_id | uuid | Agent that made the call |
| model | text | Model name |
| provider | text | anthropic, openai, google |
| input_tokens | int | Prompt tokens |
| output_tokens | int | Completion tokens |
| cost_cents | float | Calculated cost |
| operation | text | chat, checkin, embedding, etc. |