Development History Archive¶

Project: Archety Backend - Persona Passport & Memory Platform Archive Date: December 4, 2025

This document contains historical implementation details for completed phases. For current project status, see /CLAUDE.md.

Phase 1: Foundation & Core Loop (Weeks 1-2) - COMPLETE ✅¶

Completed: October 30, 2025 Status: 100% Complete - 4/4 tests passing

What Was Built¶

Core Infrastructure¶

FastAPI application with health checks
PostgreSQL + SQLAlchemy models
Pydantic schemas for validation
Global error handling
Environment configuration

Orchestrator API¶

POST /orchestrator/message - main conversation endpoint
POST /orchestrator/heartbeat - relay health check
Mode detection (direct vs group chat)
Message routing and handling

Persona Engine¶

Persona passport loading system
Training data loader with dynamic few-shot examples
Sage & Echo persona configurations
System prompt builder with relationship stage awareness

Memory System (Supermemory)¶

Supermemory service (primary)
mem0 service (legacy fallback)
Container tag isolation for privacy
Memory operations: add, search, get_all, delete

Performance Metrics¶

Supermemory operations: <300ms (25x faster than mem0)
Persona loading: <100ms
LLM response: 2-3s
Full flow: 3-5s (within 6s SLO ✅)

Phase 2: Memory & Relationship Tracking (Weeks 2-3) - COMPLETE ✅¶

Completed: October 31, 2025 Deployed: https://archety-backend-prod.up.railway.app

What Was Built¶

Enhanced Memory Extraction¶

Automatic memory type classification (emotional, factual, inside jokes, deadlines)
Structured metadata extraction (tone, urgency, topic)
Memory salience scoring with confidence scores

Relationship State Tracker¶

RelationshipStateService class
Trust score tracking (0-100): conversation frequency, vulnerability shared
Rapport score tracking (0-100): inside jokes, emotional support, engagement
Stage progression: stranger (0-20) → acquaintance (21-50) → friend (51-80) → best_friend (81-100)
PostgreSQL persistence

Boundary & Forget Commands¶

"Forget that" / "don't bring that up" detection
Soft delete for memories
User boundary storage and enforcement
Group-specific boundaries

Memory Recall Improvements¶

Temporal decay (recent memories weighted higher)
Semantic similarity threshold
Sensitivity filtering in group mode
Memory deduplication

Files Created¶

app/orchestrator/relationship_service.py
app/memory/memory_classifier.py
app/memory/boundary_manager.py

Phase 3: Superpowers & OAuth (Weeks 3-5) - COMPLETE ✅¶

Completed: October 30, 2025 Status: 100% Complete - All tests passing

Core Workflow Architecture¶

Node-Based System¶

Workflow execution engine with retry logic
Node registry with decorator-based registration
Template interpolation: {{$node.id.field}}, {{$state.key}}
Workflow state manager for persistent data
Execution tracker with pause/resume

Node Types (10 implemented)¶

Triggers: - Manual trigger (keyword/pattern matching) - Schedule trigger (cron expressions)

Actions: - HTTP Request (universal REST API adapter) - Function (execute custom Python code) - Send Message (relay to user)

Logic: - IF (conditional branching) - Wait For User Input (pause/resume)

Transform: - Get/Set/Increment State

OAuth & Google Connectors¶

OAuth Infrastructure¶

Google OAuth 2.0 client with Fernet encryption
Token manager with automatic refresh
Mobile-friendly consent UI
Token revocation endpoint

Google Connectors¶

Google Calendar: list_events, get_event, create_event
Gmail: list_messages, search_messages, get_message with filtering

Agent Workflows¶

Calendar Stress Agent (analyzes stress patterns)
Gmail Mind Reader Agent (urgent email detection)

Performance¶

Workflow execution: <100ms
OAuth flow: ~2s
Calendar/Gmail fetch: ~1-3s
Token refresh: ~500ms (automatic)

Phase 3.5: Web Portal & Onboarding (November 13, 2025) - COMPLETE ✅¶

Components Implemented¶

Photo upload system (10 photos → trait analysis)
Personality analysis using GPT-5 Vision (Big 5 + interests + values)
Persona matching algorithm (Sage vs Echo)
Phone verification via Twilio OTP
Payment integration via Stripe ($5 trial)
iMessage deeplink generation with QR codes
User session management with HTTP-only cookies

Endpoints Created¶

POST /onboarding/start
POST /onboarding/upload-photos
GET /onboarding/status/{id}
GET /onboarding/trait-profile/{id}
GET /onboarding/persona-recommendations/{id}
POST /onboarding/select-persona/{id}
GET /onboarding/chat-deeplink/{id}
POST /auth/verify/start
POST /auth/verify/confirm
POST /payment/checkout/trial
POST /webhooks/stripe

Phase 3.6: Supabase Authentication (November 13, 2025) - COMPLETE ✅¶

Architecture¶

Hybrid approach: Twilio OTP + Supabase JWT
No Redis needed (saves $60-120/year)
Bearer token authentication for all user endpoints
Automatic token refresh via Supabase

Components¶

app/identity/supabase_client.py - Auth wrapper
app/dependencies.py - FastAPI auth dependencies
app/security/hmac_auth.py - HMAC validation utils

Security Improvements¶

JWT validation on all user endpoints
No more insecure query parameters
HTTP-only cookies for session tokens
Automatic token expiry (1 hour)

Edge Agent Architecture (November 1, 2025)¶

What Was Built¶

Command/Event Schemas (app/edge/schemas.py)
Edge Agent Manager with fleet management (app/edge/manager.py)
HMAC-based authentication (app/edge/auth.py)
API Endpoints (app/api/edge_routes.py)

Architecture Benefits¶

Eliminated Celery/Redis infrastructure
70% reduction in backend processing (pre-filtering)
Better privacy (local message filtering)
Cost savings: 70% reduction in LLM tokens

Database Tables¶

edge_agents (registry)
edge_command_queue (command dispatch)
edge_event_log (event tracking)

Training Data Integration (October 31, 2025)¶

Dynamic few-shot example selection by scenario/tone
Burst pattern guidance for multi-bubble messaging
Quality-scored conversation dataset (59K+ examples)
Runtime loading from training_data/sage/

Photo Processing & Memory Integration (November 5, 2025)¶

How It Works¶

User sends photo via iMessage/Telegram
Photo analyzed via GPT-5 Vision API
Memories extracted (activities, people, locations, preferences)
Stored in Supermemory with visual_* memory types
Visual queries automatically search photo memories

Files Modified¶

app/messaging/telegram.py
app/orchestrator/two_stage_handler.py
app/main.py

Infrastructure¶

app/memory/photo_analyzer.py
app/storage/photo_storage.py
app/api/photo_routes.py

Technical Decisions¶

Why GPT-5?¶

Latest OpenAI models (August 2025 release)
Superior reasoning capabilities
Better cost/performance ratio
272K token input, 128K token output
Native image understanding

Memory System: Supermemory over mem0¶

25x faster (<300ms vs 8-10s)
Better namespace isolation
Native support for user profiles and knowledge graphs

Authentication: Supabase JWT¶

Free tier: 50,000 MAU
No Redis infrastructure needed
Automatic token refresh
$0/month vs $5-10/month for custom solution

Archive Note: This document contains historical implementation details. See /CLAUDE.md for current project status and active development phases.