Serenity Multi Modal Mental Assistant System

Serenity — Multi-Modal Mental Health Assistant

A quieter place for your mind.

**Live Demo →** [serenity.nipun.space](https://serenity.nipun.space)

Serenity is an AI-powered mental health companion built as a final year BTech project (AI & Data Science). It combines a layered memory system, adaptive personality, real-time emotion detection, and crisis-safe response logic into a single full-stack application — deployed and actively in development.

---

What it does

Most chatbots forget you the moment a conversation ends. Serenity doesn't. Every interaction is stored across four memory tiers — short-term context, semantic vector memory, a 30-day emotional profile, and pattern-based meta-reflections — so the assistant builds a genuine understanding of the user over time.

Alongside memory, it runs a real-time emotion pipeline on every message, adapts its personality to what the user needs in that moment, and routes any input flagged as a crisis through a hardened response path before the LLM ever sees it.

---

Architecture

The system is divided into five layers:

**Frontend** — React 19 SPA with Vite, CSS Modules, Framer Motion, and GSAP. Pages include CheckIn (chat), Journal, Insights, Meditate, and Profile. State is managed via context providers with localStorage persistence.

**Backend** — FastAPI with async SQLAlchemy 2.0. All AI logic lives in a pluggable engine system — EmotionEngine, LLMEngine, and CrisisEngine are swappable at config level without touching service code. Background tasks (title generation, memory storage, journal extraction, analytics) run non-blocking via FastAPI's BackgroundTasks.

**Database** — PostgreSQL 15 (Supabase). 10 tables covering users, conversations, messages, emotion logs, journal entries, crisis events, semantic memories, emotional profiles, meta-reflections, and context cache. Migrations managed with Alembic.

**AI/ML Layer** — Primary emotion detection uses a keyword engine (~65% accuracy, no GPU required). Opti