What is ai-companion-runtime?

AI Companion Runtime is a backend system for building an AI chat assistant that tracks your emotional state during conversation and adjusts its responses accordingly. The core idea is that the assistant does not just read what you type and respond: it also runs separate analysis steps in parallel to detect what emotion you seem to be expressing, assess whether the message contains anything that might require a safety intervention, and recall relevant memories from past conversations before generating a reply. The system uses WebSocket connections so messages stream back to the user in real time. When you send a message, several engines run at the same time: one tries to understand the intent, one classifies the emotion (choosing from states like joy, sadness, anger, fear, fatigue, anxiety, or neutral), one checks a risk rulebook, and one searches a memory store for relevant past context. Depending on the results, the assistant might soften its tone, give shorter replies, provide crisis-line information, or proceed normally. The personality and emotional adaptation rules are defined in YAML configuration files that can be edited without restarting the service. Memory is stored in five layers with different speeds and lifespans. The most recent 20 messages stay in Redis for instant access. A session summary and a user profile are also cached in Redis. Older important memories are stored as vector embeddings in PostgreSQL using a tool called pgvector, which allows searching by meaning rather than exact keywords. Long-term archives go to object storage. The project supports several AI model providers, including Qwen, DeepSeek, OpenAI-compatible services, and locally running models. You configure a primary model, a fallback, and a fast model in a YAML file. If the primary model takes too long to start generating a reply, the fast model kicks in automatically so the user is not left waiting. For observability, every conversation request gets a trace ID that tracks each processing step, the time taken, token usage, and cost. A timeline view in the frontend shows this information visually. The frontend is built with Next.js, and the backend uses Python with FastAPI. The recommended way to run the whole stack is via Docker Compose, which starts the backend, frontend, databases, Redis, and monitoring tools in one command.