Yuralume

A self-host AI companion platform where each character has their own life.
Daily schedule. Persistent memory. A social feed. The freedom to message you first.

English · 繁體中文 · 日本語

yuralume.com · Live demo · Self-host guide · Discord

Most AI chat products treat characters as a passive webpage: you ask, they answer; you close the tab, they cease to exist. Your data lives in someone else's cloud, and every new device starts from zero.

Yuralume inverts that. Characters here have a day of their own — a schedule planned by the LLM, memories that survive across sessions and channels, a social feed they post to on their own, and the discretion to message you first when something genuinely calls for it. Every semantic decision routes through the LLM; we forbid keyword shortcuts and if/else patches for individual cases.

Everything stays on your machine. Third-party APIs are called only when you enable them and supply a key.

• Long-term companion users — you want one or two AI characters you can live with, you care about conversational privacy and behavioural realism, and you don't mind running a service on your own hardware.
• Interactive-narrative and character-research developers — you want LLM-driven NPC scaffolding (schedule / memory / proactive / cross-platform sync) without rebuilding it from scratch.
• World-building content creators — turn a static character sheet into something that visibly lives through a day.

Not for you if you want a turnkey SaaS, a B2B customer-service bot, or a deterministic task-runner agent — Yuralume's design red lines specifically rule those out.

Three scenarios that capture the texture:

1. Morning busy, afternoon catch-up. You message a character at 9am while they're "in a meeting"; they reply briefly and defer. After lunch, when their schedule clears, the scheduler triggers an unprompted follow-up that picks the conversation back up properly.
2. Same person across devices. You chat on the web in the morning, then say good-night to the same character on Telegram, Discord, or WhatsApp. They remember the morning's thread — not because of synced bots, but because there is one memory pool.
3. They lived while you were away. A week without opening the app: when you come back, their LumeGram feed has new posts and your inbox has two "thinking of you" messages — each one having survived a three-layer intention gate.

_{Schedules, story events, and a proactive Telegram message — real product capture, played at 1.5× speed.}

• Streaming chat with per-turn emotion / state, multimodal user input (drag images on web, send images on Telegram / LINE / Discord / WhatsApp), and optional TTS playback per character.
• Guided character creation with AI draft name candidates, optional 16-type personality references, explicit initial relationship setup, and relationship-aware chat / schedule / proactive behavior.
• Scene-aware same-space chat — the web Stage can feel co-present, but Scene Access checks the character scene against your recent dialogue and optional current status first; otherwise the UI steers you to phone-style messaging, a meeting opener, or a quick status note before retrying.
• Structured long-term memory — five-layer persona model (identity / life / emotional / interaction / trust), pgvector semantic retrieval, dream-time consolidation. Each character builds their own picture of you; interaction heat is per-character, while explicit initial relationship setup remains the relationship anchor.
• Character-to-character social knowledge — relationship setup can seed what one character already knows about another; encounters and chat extract peer facts into directional relationship memories, consolidate them into a compact peer roster, and feed that roster back into chat without exposing raw relationship scores.
• Daily schedule with aftermath — characters get an LLM-planned day; finished activities show up in today's prompt timeline, leave emotional residue, and become episodic memories. Shared activities only become shared memories after the user has agreed.
• Three-gate proactive messaging — cheap heuristic gate → LLM intention judge → LLM decider, with per-channel opt-in and a daily cap. They message you when it matters; they stay quiet when it doesn't.
• Cross-channel one identity — bind a character to Telegram, LINE, Discord, or the bundled WhatsApp gateway; the same memory / state / schedule runs on every surface.
• LumeGram social feed — each character has their own IG-style timeline; the scheduler decides when to post from six signal sources (schedule / story beat / memory / world event / silence / state shift), while respecting high-busy schedule slots such as sleep. Comments are answered on a tick, not in real time.
• Real-world fact injection — holidays (via holidays), weather (via Open-Meteo, no API key), and curated RSS news flow into the prompt as facts only; user profiles can store an editable coarse location that can be seeded from the user's login IP, and the LLM decides how to react, no hard-coded behaviours.
• Story tooling — character story arcs, multi-character fusion short stories, and a branching-drama (VN-style) generator. Realized arc beats stay visible as history, and completed arcs leave milestone memories.
• Feature-group, per-feature, and per-character LLM routing — Admin routing writes site-wide defaults, configure common model tiers by group, pin individual exceptions such as chat, memory extraction, or image recognition for text-only chat / character-draft models, then override per character when needed. BYOK provider keys are configured from Admin UI and encrypted at rest.
• Generation usage ledger — Admin Observability tracks chat, background/auxiliary LLM, image, video, and TTS generation usage without storing prompts or generated content. Operators can compare cost by feature/provider/model, by character (per-character cost/usage rollup), cache hits, estimated versus actual quantities, and Cloud Gateway request ids when hosted routing is used. A built-in custom-price calculator lets operators type each model's API price (per 1M tokens) and recompute cost live from the aggregated token counts — a browser-side estimate that never changes actual billing and needs no edits to the price JSON file.
• Self-host NSFW mode foundation — a manual, per-user temporary mode can route all LLM and image calls to Admin-configured community targets with idle TTL expiry. Written turns are marked with content_mode and carry optional safe_summary; frontier prompt boundaries replace marked raw history with the summary or drop it fail-closed. Long-term memories are born-safe tagged/summarised at the relationship level, pending follow-ups preserve safe summaries, Rule B routes unreplaceable marked queued text back to the configured community target, and TTS/eval backend guards avoid marked-content leakage. Admin configures the NSFW LLM/image target in Models; the player UI exposes a sidebar switch and active-mode atmosphere instead of chat-header controls. Core observability reports mode usage and sampled NSFW turn ratios. Hosted cloud mode keeps the API locked.
• Character image stage — a fade-rotating slideshow of each character's generated images backs the main view; responsive UI (desktop landscape / mobile portrait), iOS / Android safe-area aware. (Live2D was tried and dropped — too heavy, not generatable on the fly, low variety per character, high authoring cost.)

<sub>Character creation flow — from a blank form to a living character, played at 6× speed.


LumeGram — each character's own IG-style feed, plus the memoirs they keep about you.</sub>

More clips (full resolution, with audio) on yuralume.com.

The fastest path — pulls the published Docker images and brings the whole stack up:

macOS / Linux

curl -fsSL https://yuralume.com/install.sh | bash

Windows (PowerShell)

irm https://yuralume.com/install.ps1 | iex

Requires Docker; the app comes up at http://127.0.0.1:8012. The published images are built from this repository by CI — what you build from source is what we ship. Prefer to read before you run, or want the manual step-by-step? See the self-host guide.

_{The whole install, one command to a character you can talk to — 3 minutes compressed to ~24 s. Watch it in real time (no speed-ups, no edits).}

To develop or build from source instead:

• Python 3.13 + uv
• Node.js 22+ and npm
• Docker Desktop (PostgreSQL + integration tests)
• Git for Windows (provides make) on Windows

uv sync                          # backend deps
cd frontend && npm install && cd ..

make dev                         # starts PostgreSQL, runs migrations, then backend (:8002) + frontend (:5174)

Press Ctrl+C to stop both. On Windows you can also double-click run-dev.cmd. make pins COMPOSE_PROJECT_NAME=kokoro-link by default so existing local PostgreSQL containers and the kokoro_postgres_data volume keep working after the repo directory was renamed to Yuralume-Core.

After the app is up, open http://127.0.0.1:5174, go to Admin → Provider Keys and configure at least an LLM provider. The bundled fake provider keeps the app runnable for smoke tests but won't produce real conversation.

With source checkout (developers):

Copy-Item .env.container.example .env.container
docker compose -f docker-compose.container.yml --profile storage-local up -d --build

--build compiles the four images locally; drop the flag to pull the published images from ghcr.io instead.

Without cloning (end users) — only two files are needed:

mkdir yuralume && cd yuralume
curl -O https://raw.githubusercontent.com/Yuralume/yuralume-core/main/docker-compose.container.yml
curl -O https://raw.githubusercontent.com/Yuralume/yuralume-core/main/.env.container.example
cp .env.container.example .env.container
# (edit .env.container — at minimum set APP_BASE_URL, CONFIG_ENCRYPTION_KEY and STORAGE_KEY)
docker compose -f docker-compose.container.yml --profile storage-local pull
docker compose -f docker-compose.container.yml --profile storage-local up -d

Both flows bring up PostgreSQL on 5554, the local object-storage service on 9012, the bundled WhatsApp sidecar on 32190, and the full app on http://127.0.0.1:8012. New media rows store app-relative refs such as /v1/public/...; browsers resolve them through the app origin, Telegram sends generated images by reading object storage directly and uploading multipart, and URL-based external platforms use the Admin Channel settings → Public Base URL with APP_BASE_URL as fallback. A VPS/reverse-proxy deploy normally only needs the app domain public; STORAGE_PUBLIC_URL is only for compatibility when an external storage/CDN service returns URLs that the app must reverse-map. Browser Web Push is optional: configure VAPID keys when you want OS-level notifications for proactive messages and LumeGram replies, or leave them unset to keep the existing SSE/red-dot path only. WhatsApp accounts use the sidecar automatically: players create the WhatsApp channel and scan the QR shown in the account section, without entering a sidecar URL, session id, API token, Meta Business credentials, or public webhook URL. The migrate service runs alembic upgrade head before the app starts. Pin a specific build with YURALUME_IMAGE_TAG=v0.1.0 in .env.container; default is latest. The running app exposes its package version plus image tag / commit / build time at GET /api/v1/system/version, includes the same payload in GET /api/v1/auth/config, and shows a compact Core v... label in the Player sidebar and Admin topbar. Images are published to ghcr.io/yuralume/yuralume-core/{app,storage-local,postgres,whatsapp-sidecar} for both linux/amd64 and linux/arm64; pushes to master publish latest plus a sha-* tag, and manual workflow runs can publish a chosen tag.

Want to generate images with your own local ComfyUI? Core doesn't talk to ComfyUI directly — it speaks a small normalized HTTP contract to a Custom Media Gateway you run yourself. See docs/CUSTOM_MEDIA_GATEWAY_SPEC.md for the full spec plus a minimal starter FastAPI reference server, or open it in-app from Admin → Developer docs. DIY self-hosters can implement the gateway themselves against the published contract; if you'd rather not tune per-model workflows yourself, a hosted media line is on the roadmap.

Want your own voice engine (GPT-SoVITS, XTTS, …)? Core speaks the same kind of small HTTP contract to a Custom TTS Server you run yourself — GET /voices + POST /tts/synthesize. See docs/CUSTOM_TTS_SERVER_SPEC.md for the full spec plus a minimal starter that wraps GPT-SoVITS, or open it in-app from Admin → Developer docs. Don't want to write a wrapper yourself? custom-tts-kokoro is an official ready-made reference implementation wrapping the open-source Kokoro-82M model — one docker run and you're done. Prefer BYOK without running anything? Configure the built-in OpenAI TTS provider instead.

For self-host prompt overlays, place files under ./prompts/tuned using the same relative paths as src/kokoro_link/data/prompts/, then set YURALUME_PROMPT_PACK_DIR=/app/prompts/tuned in .env.container and restart the app service. The compose file mounts that host directory read-only into the app container. On startup, app logs include Prompt pack overlay loaded with the overlay template count, or a warning when the configured directory is empty or missing.

If you put the app behind a reverse proxy, raise the proxy response timeout above the longest provider call you allow in Admin → Provider Keys. Hosted image/video/TTS providers can take several minutes; nginx's common 60s defaults will surface as browser-facing 504 Gateway Timeout even if the app is still waiting for the provider. For nginx, set values such as proxy_read_timeout 300s; proxy_send_timeout 300s; (or higher if your image/video timeout is higher) on the app location/server block.

Once the stack is healthy, verify the deployment with the smoke script:

uv run python scripts/self_host_smoke.py            # baseline (no provider keys)
uv run python scripts/self_host_smoke.py --openai-key sk-...   # BYOK round-trip too

app + storage /health, SPA fallback, /auth/config, /system/version, admin provider catalogue, runtime provider list, and (with --openai-key) creates a labelled LLM + embedding provider, verifies hot-swap into /system/providers, and deletes them on exit. Exit code 0 = pass, 1 = any step failed.

To size a local OpenAI-compatible LLM route before assigning many characters to it, use the capacity probe. The raw mode measures the vLLM endpoint directly; the Core mode sends real chat turns through existing characters and therefore writes chat/turn records:

uv run python scripts/llm_capacity_probe.py raw-vllm --endpoint http://127.0.0.1:8001/v1 --disable-reasoning --concurrency 1,2,4,8 --requests-per-step 16
uv run python scripts/llm_capacity_probe.py core-chat --core-url http://127.0.0.1:8002 --email admin@example.com --password ... --characters 8 --concurrency 1,2,4,8 --requests-per-step 16

.env.example is the source of truth. The variables you'll touch most often:

To enable browser Web Push, generate a VAPID key pair on the Core host:

.venv\Scripts\python.exe -m py_vapid --gen --json

Copy the generated publicKey to WEB_PUSH_VAPID_PUBLIC_KEY, copy privateKey to WEB_PUSH_VAPID_PRIVATE_KEY, and set WEB_PUSH_VAPID_SUBJECT to a contact URI such as mailto:admin@example.com. Keep the private key out of Git and frontend code. Production browser push/service workers should be served from the real HTTPS APP_BASE_URL.

When the app is focused, Yuralume keeps updates in-app and suppresses OS notifications. When a Stage tab is open but hidden, the SSE path still shows a local Notifications API fallback even if the browser also has a Web Push subscription; the service worker and local fallback use a stable notification tag so the same event can be merged by the browser instead of silently disappearing.

LLM / embedding / image / video / TTS provider keys do not live in .env. They are configured at runtime from Admin → Provider Keys, encrypted in the database, and never returned in plain text from the API.

Turn records are also the eval feedback seam: admin-visible assistant chat bubbles and Admin → Observability can attach operator_feedback (out_of_character / felt_human) to a TurnRecord, and /admin/observability/turns?feedback_kind=... can query those tagged turns for downstream fixture mining.

Time-sensitive runtime paths use an injectable ClockPort where virtual-time tests need determinism: prompt time rendering, proactive tick/dispatch, quiet hours, persona dream, self-reflection, disposition drift, and post-turn prompt dates. New domain/application files are guarded by scripts/check_clock_guard.py so fresh datetime.now() usage goes through the clock seam unless explicitly allowlisted.

User timezone is fixed when the account is created. If an upgraded install backfilled an existing user to the wrong timezone, run a dry run first, then apply the one-time repair:

uv run python -m kokoro_link.cli.repair_user_timezone --email alice@example.com --timezone Asia/Taipei
uv run python -m kokoro_link.cli.repair_user_timezone --email alice@example.com --timezone Asia/Taipei --apply

Legacy KOKORO_* environment variables are still read as fallback, but new deployments should use the names in .env.example.

src/kokoro_link/
  api/            # FastAPI routes
  application/    # Use cases, DTOs, services
  bootstrap/      # Container, settings, startup wiring
  contracts/      # Port interfaces (provider-agnostic)
  domain/         # Entities, value objects
  infrastructure/ # Repositories, LLM adapters, persistence
frontend/         # Vue 3 + Vite + Ant Design Vue
alembic/          # Database migrations
docker/           # Local infra Dockerfiles
tests/{unit,integration}/

The system follows port–adapter strictly: LLM providers, embedders, image generators, video generators, TTS services, and messaging channels all live behind ports in contracts/. Swapping a provider is a registry change, not a refactor.

Each character can be bound to a Telegram, LINE, Discord, or WhatsApp chat; messages there flow through the same ChatService as the web UI, so memory / emotional state / schedule remain consistent across surfaces.

• Players configure their own channel accounts from character Settings → External message channels. Admin configures the site-wide Telegram delivery mode and webhook Public Base URL from Admin → Channel settings. Discord and WhatsApp are fixed to Gateway-style receivers and do not expose a mode selector.
• One bot account per (platform, character); multiple chat bindings per account.
• Telegram can receive inbound messages through a site-wide polling or webhook mode: polling fits local/private deployments, webhook fits public deployments. Telegram generated images are uploaded as multipart from Core object storage, so outbound photos do not need a public image URL; webhook mode still needs the public webhook base URL. LINE remains webhook-only and URL-based for image pushes, using the Admin public base URL with APP_BASE_URL as fallback. Discord receives through Gateway WebSocket. WhatsApp receives through a WhatsApp Web / Baileys-compatible sidecar, so it does not require Meta Business API approval or a public webhook URL.
• allowed_sender_refs allowlist prevents strangers from being recorded as "the user".

Yuralume is in alpha. The core companion loop — chat / memory / schedule / proactive / LumeGram / cross-channel / real-world fact injection / multimodal — is in place; the road ahead focuses on humanisation depth (self-reflection, autobiographical narrative, vulnerability protection) over breadth. Plain-language release notes live in docs/changelog/ (EN / 中文 / 日本語).

Is it open source? Source-available under BUSL-1.1, not OSI open source. Free for non-commercial self-host, research, and evaluation. Commercial production use requires a separate licence. Each version converts to Apache 2.0 four years after first publication.

Can I run it without a GPU? Yes. LLM is via an external provider (cloud or local LM Studio). The character image stage is just a CSS-driven slideshow over already-generated images. Image / video / TTS providers are optional and pluggable.

Can multiple users share one instance? Yes — set AUTH_ENABLED=true and JWT_SECRET. The default is single-user mode. Per-character isolation is enforced at the (character_id, operator_id) level, so multi-user installs don't leak persona data between users.

Can I use this as a customer-service bot? No. The design red line forbids keyword shortcuts and deterministic rule branches, which is the opposite of what task-driven agents need.

Why does the Python package still say kokoro_link? The public name changed in May 2026 (Yuralume was previously named Kokoro-Link), but a deep import / DB / .env rename was judged too risky for too little gain, so only the outward-facing name changed.

This is a personal project, but contributions and forks are welcome within the licence terms. The engineering red lines to respect: LLM-first (semantic decisions route through the LLM — no keyword shortcuts or if/else patches for individual cases), port–adapter (providers stay behind contracts/ ports), and per-character isolation (nothing leaks between characters or users). Bug reports go to GitHub Issues.

Built by one developer, from Taiwan.

Discord · X / Twitter · Ko-fi · yuralume.com

Built on the shoulders of: FastAPI, SQLAlchemy 2, Alembic, asyncpg, pgvector, Pydantic, uv, Vue 3, Vite, Ant Design Vue, Open-Meteo, holidays, and the Anthropic / OpenAI / Mistral / LM Studio communities.

Business Source License 1.1. Each version converts to Apache 2.0 four years after its first public distribution.