Your character is no longer locked in a text chat — they live wherever you are.
Welcome to the world where your AI characters chats, remembers, adventures in tabletop RPGs, and lives directly on your desktop with one continuous, evolving identity.
📚 Documentation • 🗨️ Discord • 🌐 Website
Soul of Waifu (SoW) is a free, open-source desktop app where AI characters can remember, evolve, and exist across multiple dimensions of interaction simultaneously. The core idea: a character you create once exists across multiple interconnected modes at the same time — text and voice conversation, a full tabletop RPG engine, a desktop companion with real tool access, and a persistent memory architecture that builds genuine continuity across all your sessions.
Create or import a character once, and seamlessly interact with them across interconnected dimensions:
- Interactive Text & Voice Chat with customizable UI, Live2D/VRM avatars, and real-time voice calls.
- Soul Memory Architecture featuring long-term emotional evolution, a personal diary, and self-healing memory logs.
- Soul Stage RPG Engine running a full tabletop text-RPG driven by a dedicated AI Game Master.
- Soul Companion desktop overlay living on your screen with neurohormonal simulation, Computer Vision, and MCP tool access.
Everything runs 100% locally and privately on your PC. No subscriptions, no filters, no data leaving your machine. Cloud AI providers are supported as an option for low-spec hardware.
| Mode | Description |
|---|---|
| 🧠 Soul Memory | Each character has an independent digital brain that goes far beyond basic fact-searching. |
| 💬 Text & Voice Chat | Full-duplex conversation with Live2D (motion-linked) & VRM (3D) avatars, custom state variable HUD, lorebooks, and voice calls. |
| 🎲 Soul Stage | Turn-based RPG system under a virtual Game Master with WorldState tracking, inventory, status effects, dynamic NPCs, choices bar, and ambient audio. |
| 🖥️ Soul Companion | Transparent desktop overlay powered by neurohormones. Reads your screen, interacts with clipboard, uses web tools, and talks proactively. |
Standard vector-RAG approaches search old chat logs for keyword matches. Soul Memory functions as an autonomous background agent that continuously rewrites four isolated cognitive files in real time:
- Psychology Layer: Tracks current mood, internal tension, hidden motives, and character development.
- Relationship Profile: Remembers user habits, preferences, shared promises, and trust progression.
- Episodic Topic Archive: Categorized knowledge base indexing locations, events, and key facts using local
all-MiniLM-L6-v2embeddings. - Personal Diary: First-person reflective entries written by the character after meaningful conversations.
Tip
Cognitive Mechanics:
- Emotional Decay: Grudges and negative mood spikes naturally cool down over time if not revisited.
- Memory Self-Healing: The system detects logical contradictions between new responses and past facts, automatically overwriting outdated information and logging corrections.
Choose between Full Sync (maximum depth), Soul Link (balanced), Mind Spark (lightweight), or Reflection Flow (diary only) to fit your VRAM/RAM constraints.
Soul Stage transitions your chat into a structured tabletop roleplaying campaign managed by a virtual Game Master. The GM is a separate AI layer running independently of your character: it maintains the world state, directs events, and enforces structure across both solo and group roleplay sessions.
- WorldState Engine: Rigorous state tracking for in-game time of day, weather, active location, and key facts.
- Interactive Party & NPCs: Main party members synchronize memories via Soul Memory, while dynamic temporary NPCs spawn for specific encounters.
- Inventory & Status HUD: Track equipment, health, conditions (poisoned, exhausted, inspired), and gold in real time.
- Atmospheric Automation: Scene backgrounds and ambient audio loops switch automatically as the story moves to new locations.
- Choices Bar & Event Cards: Branching dialogue options and random encounter cards keep campaigns unpredictable.
Soul Companion turns your character into an autonomous inhabitant of your Windows desktop. Existing as a transparent overlay, the companion stays with you while you work, game, or browse. The companion's behavior is driven by a neurohormone system rather than simple reactive prompting. It has moods that shift over time based on activity levels, time of day, and your interaction patterns. It gets tired after long sessions and gets bored during extended inactivity. When something notable happens on your screen or enough time passes, it initiates conversation on its own.
Six built-in tools, plus support for external MCP server connections:
| Tool | What it does |
|---|---|
| Screen Reader | The companion can see your current screen and comment, analyze, or assist with what's visible |
| Clipboard Reader | Reads and processes copied text on request |
| Web Search | Looks up information in real time |
| Browser Control | Opens URLs in your default browser |
| Music Control | Manages audio playback |
| Custom MCP Server | Connect any external MCP server for expanded integrations |
Build no-code Dating Sims, RPG stat systems, or Tamagotchi mechanics directly inside character cards without writing code.
- Adaptive HUD Bar: Displays animated progress bars (
int), YES/NO badges (bool), item lists (list), or text labels (str) at the top of the chat. - Resilient AI Interceptor: Backend interceptor parses state updates robustly, making updates immune to LLM JSON syntax typos.
- 11 Built-In Presets: Ready-to-use templates for Romance, RPG, Survival, Interrogation, Horror, and Visual Novels.
Run Soul of Waifu on your main PC and connect from your phone or tablet over home Wi-Fi via http://<your-pc-ip>:8000. Features real-time bidirectional WebSocket syncing, custom chat backgrounds, avatar rendering, and voice input routed directly through your PC's local Faster Whisper model.
Connect your Soul of Waifu characters directly to Discord bots. Chat with your characters inside server channels or private messages, preserving their full personality, system prompt settings, and long-term memories.
Generate illustrations directly within chat messages via context menu actions.
- Local Engines: Automatic1111 WebUI, ComfyUI API, FLUX.
- Cloud Engines: NovelAI Diffusion, DALL-E 3.
- Automatically builds contextual visual prompts based on the character's appearance, current pose, emotional state, and scene environment.
🎙️ Voice, Speech-to-Text & Avatars
- 6 Text-to-Speech Engines:
- Qwen3 TTS (Local): Ultra-low latency, voice cloning from a 3-second audio sample, prompt-based voice design, 9 built-in speakers, 1.7B and 0.6B models.
- XTTSv2 & Kokoro 82M (Local): High-fidelity voice synthesis and zero-shot voice cloning.
- Silero TTS (Local): Fast Russian voice engine.
- EdgeTTS & ElevenLabs (Cloud): High-quality cloud neural voices.
- RVC Support: Integrated Voice Conversion parameter tuning (pitch shift, index rate, protection).
- Sentence-by-Sentence Streaming: Audio playback starts on the first generated sentence, eliminating response lag.
- Full-Duplex Calls (SoW System): Silero VAD (Voice Activity Detection) + Faster Whisper transcription with seamless user-interruption support.
- Avatars & 28 Emotion Classifier: Live2D (with motion animation links), VRM 3D models, GIFs, and static images. Automatic 28-state emotional sentiment analysis with LipSync audio matching.
🎛️ Advanced Text Sampling (Loop Prevention)
Tailor local LLM generations with cutting-edge sampling techniques:
- Dynamic Temperature: Dynamically shifts temperature based on confidence to balance creativity and logic.
- DRY Sampler (Don't Repeat Yourself): Prevents multi-word phrase loops without degrading grammatical quality.
- XTC (Exclude Top Candidates): Filters out overused AI clichés and repetitive vocabulary.
- Min-P: Trims low-probability tokens relative to the top candidate for coherent output.
📖 Updated Lorebooks Engine
- Multi-Binding: Link multiple lorebooks to a single character simultaneously.
- Semantic Situation Matching: Local vector search matches lore entries based on situational context rather than strict keywords.
- Scene Tension Accumulator: Dynamically builds story energy to trigger random events.
- Chain Dependencies: Create multi-stage questlines with delayed entry unlocks.
- Injection Modes: Choose between Passive (Background Knowledge) and Active (System Directive) injection.
💻 Local & Cloud LLM Backends
- Models Hub: Integrated Hugging Face repository search, GGUF downloader with progress bar and instant cancel, and automated Llama.cpp binary updater.
- Local Acceleration: Llama.cpp HTTP server supporting CUDA (NVIDIA), HIP (AMD), SYCL (Intel), and Vulkan.
- Performance Options: Flash Attention, MLock, KV-Cache quantization (
q8_0,q4_0), Thinking Mode, and CPU MoE layer offloading. - 10 Cloud Providers Supported: OpenRouter, OpenAI, Anthropic Claude, DeepSeek, Grok (xAI), Google Gemini, Qwen, Mistral AI, Z.AI, and custom OpenAI-compatible endpoints.
No Python knowledge, Node.js, or command-line experience required.
1. Download the latest Soul-of-Waifu-v2.4.0.zip archive from Releases.
2. Extract to a path without spaces or Cyrillic characters (e.g. C:\AI\Soul-Of-Waifu\).
3. Run installer.bat (Do NOT run as Administrator).
4. Launch via Soul of Waifu.exe or start.bat.
Warning
Do not run installer.bat as Administrator! Windows changes the working directory for Administrator processes to C:\Windows\System32, causing installation path errors. Use a standard double-click.
| Minimum | Recommended | |
|---|---|---|
| OS | Windows 10/11 (64-bit) | Windows 10/11 (64-bit) |
| RAM | 8 GB | 16 GB+ |
| GPU | Any (for Cloud APIs) | NVIDIA / AMD with 6+ GB VRAM (for local models) |
| Storage | 10 GB free space | Fast NVMe SSD |
- Option A — Cloud AI (No GPU Required):
Go to Options -> Configuration, input your OpenRouter or OpenAI API key. Import a character card from the Characters Gateway or drag-and-drop a
.png/.jsonfile into the app window. - Option B — Local AI:
Navigate to Models Hub, search for a model (e.g.
GemmaorQwen), and download aQ4_K_MGGUF quantization. In Options -> LLM Settings, select your GPU backend (CUDA/HIP/SYCL/Vulkan), enable Flash Attention, and launch the server via Models Hub.
📖 Read full documentation & guides: jofizcd.github.io/soul-of-waifu-site/docs
Soul of Waifu is a solo-developer open-source project. All features are 100% free with no paywalls or premium tiers.
Financial Support:
Community & Help:
- Star this repository — helps boost visibility on GitHub!
- Join our Discord Server — share custom character cards, lorebooks, RPG scenes, and get help from the community.
Jofi
