How gi-tuu/ambrace works
AMBRACE is a self-hosted AI companion: a user chats with configurable characters, the server builds context from memories and character state, invokes an LLM, and streams a reply. Distinct product stages include recall and response, ongoing memory and life updates, and proactive outreach; the graph also captures voice, social, group-game, phone, and extension capabilities. Exact flow is clearest for sampled modules; several feature links use README descriptions and enclosing source directories where implementation was not sampled.
Main entry points: chat.py Chat API · chat_service.py Chat service · loop.py Agent loop · engine.py SQL database
Components 23
Conversation and cognition
- Chat API
backend/app/api/chat.py - Chat service
backend/app/application/chat_service.py - Context builder
backend/app/agent/context_builder.py - Agent loop
backend/app/agent/loop.py - LLM client
backend/app/agent/llm_client.py
Memory and companion life
- Memory system
backend/app/memory - Character state
backend/app/domain - Life simulation
backend/app/life - Proactive scheduler
backend/app/scheduling
Social and engagement
- Diary and moments
backend/app/application - Group games
backend/app/games - Voice services
backend/app/voice
Devices and integrations
- Phone perception
backend/app/api/phone.py - Android accessibility
flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionAccessibilityService.kt - Android notifications
flutter_app/android/app/src/main/kotlin/com/gituu/ambrace/PhonePerceptionNotificationService.kt - MCP manager
backend/app/mcp/manager.py - Plugin system
backend/app/plugins - Chat channels
backend/app/providers
Service and state
- FastAPI app
backend/app/main.py - SQL database
backend/app/db/engine.py - WebSocket notifications
backend/app/ws/notify_manager.py
Other components
- User
- LLM provider
Connections 23
- User → Chat API: sends message
- FastAPI app → Chat API: registers routes
- Chat API → Chat service: handles chat
- Chat service → Context builder: builds context
- Chat service → Agent loop: runs response
- Agent loop → LLM client: requests completion
- LLM client → LLM provider: calls model
- Context builder → Memory system: retrieves memories
- Context builder → Character state: reads state
- Memory system → SQL database: reads and writes
- Character state → SQL database: stores state
- Proactive scheduler → Life simulation: advances life
- Proactive scheduler → Diary and moments: generates activity
- Diary and moments → SQL database: stores content
- Chat API → Group games: serves game APIs
- Chat API → Voice services: serves voice APIs
- Android accessibility → Phone perception: reports perception
- Android notifications → Phone perception: reports notifications
- Phone perception → SQL database: stores perception
- Agent loop → MCP manager: invokes tools
- Agent loop → Plugin system: uses extensions
- Chat channels → Chat service: delivers messages
- Chat service → WebSocket notifications: pushes updates