AI companion Android app inspired by Steins;Gate's Amadeus system.

---

Overview

Amadeus is a mobile AI companion that you can call, text, and hang out with. It features voice calls with real-time lip-synced Live2D/sprite visuals, proactive messaging (she can call you), long-term memory, and an ambient mode for just keeping each other company.

Features

• Voice & text calls with emotion-driven character expressions
• Live2D model with real-time lip sync, idle animations, and emotion transitions
• Sprite mode as a lightweight alternative to Live2D
• Proactive messaging -- the AI initiates conversations and calls via push notifications
• Long-term memory with automatic compaction
• Ambient mode -- a low-key hangout where silence is comfortable
• Photo sharing -- send photos and the AI remembers them
• Web search via Brave Search API
• TTS with GPT-SoVITS voice synthesis
• Scheduled reminders the AI can set for you

Tech Stack

Layer	Tech
Frontend	React, Vite, TypeScript, Tailwind CSS
Mobile	Capacitor (Android)
Backend	Node.js, Express, PostgreSQL, Knex
LLM	Any OpenAI-compatible API
Live2D	PixiJS v7, pixi-live2d-display, Cubism 4 SDK
TTS	GPT-SoVITS (self-hosted)
Push	Firebase Cloud Messaging
Search	Brave Search API

Setup

Prerequisites

• Node.js 18+
• PostgreSQL 16+
• Android SDK (for mobile builds)
• An OpenAI-compatible LLM API key

Quick Start (Docker)

cp server/.env.example server/.env
# Edit server/.env with your API keys

docker compose up

This starts PostgreSQL, the backend server, and the TTS service.

Manual Setup

Server:

cd server
cp .env.example .env
# Edit .env with your config
npm install
npm run migrate
npm run dev

Frontend:

npm install
npm run dev

Android build:

npx cap sync android
cd android && ./gradlew assembleDebug

Environment Variables

Variable	Description
JWT_SECRET	Secret for device-based auth tokens
DATABASE_URL	PostgreSQL connection string
LLM_API_URL	OpenAI-compatible API base URL
LLM_API_KEY	API key for the LLM
LLM_MODEL	Model name (e.g. gpt-4o)
BRAVE_API_KEY	Brave Search API key (optional)
TTS_SERVICE_URL	GPT-SoVITS service URL (optional)

Live2D Model

The Live2D model is not included in the repo. Place a Cubism 4 model in public/live2d/blackkitty/ or use sprite mode instead.

Architecture

The server runs a heartbeat loop that periodically checks whether the AI has a reason to reach out (daily check-ins, follow-ups, things she wants to share). When it decides to initiate contact, it pre-generates a greeting with TTS audio and pushes an incoming call notification via FCM.

Conversations use a memory compaction system -- every 20 turns the LLM summarizes the conversation so far into a compact memory block, keeping context windows manageable while preserving long-term continuity.

During calls, emotion tags parsed from LLM responses drive the character's expression in real-time, whether through Live2D parameter transitions or sprite swaps.

License

This project is for personal use.