Soul of Waifu: a local-first AI companion that also wants control of your desktop

The split personality problem Soul of Waifu is trying to fix

Most AI companion setups are one chat window with one context buffer. The character you built for roleplay does not know what you told a separate desktop pet, and the desktop pet does not remember last week's conversation. Soul of Waifu's stated premise is that a character should be created once and then persist across several interaction modes with one continuous identity. The README names four: text and voice chat with Live2D/VRM avatars, a memory layer, a tabletop RPG engine called Soul Stage, and an autonomous desktop agent called Soul Companion. The intended user is someone who wants an anime-styled companion on a personal Windows machine, wants the conversation to stay on that machine, and is comfortable with a Python desktop application rather than a web service. The project explicitly frames the local-first default as the core experience and cloud providers (OpenAI, Claude, Gemini) as an optional add-on for low-spec hardware or heavier reasoning. That framing matters: if your hardware cannot run a local model well, you are not the default target, you are the fallback path.

Soul Memory is the actual architectural claim

The README contrasts Soul Memory with vector-RAG over old chat logs. Instead of embedding past messages and retrieving by similarity, it describes an autonomous background agent that continuously rewrites four isolated cognitive files in real time. The first is a Psychology Layer tracking current mood. The README text supplied here is truncated mid-sentence at that point, so the remaining layers are not confirmed by the material I have. What can be said is the design direction: memory is a maintained state document, not a search index. That is a meaningful difference. A retrieval system answers 'what did we say about X' and cannot easily answer 'how does she feel about me right now'. A rewritten state file can, but it also means the file is the source of truth, and any corruption or bad rewrite is a persistence problem rather than a one-off bad retrieval. The README also mentions a personal diary and self-healing memory logs, which suggests the project is aware of the failure mode. Whether the healing logic is a validation pass, a rollback, or something else is not described in the material available. Treat the four-file layout as the thing to inspect first in the repository.

Soul Companion: an agent with mouse and keyboard access

Soul Companion is the module that will decide whether you install this. According to the README, out of the box it can see your screen, control your mouse and keyboard, browse the web through a real headless browser, run sandboxed Python and PowerShell scripts, organize files, and chain multi-step tasks. Extensibility is via custom Python plugins or any external MCP server. The safety mechanism is described as a Human-in-the-Loop approval banner with a 25-second fail-safe countdown, so nothing risky runs without confirmation. That is the right shape for the problem, but the README does not enumerate which actions count as risky versus which run silently. Screen reading and browsing may or may not surface a banner. If you are evaluating this for a work machine, that gap is the first thing to close by reading the source, not the marketing copy. The neurohormonal simulation that drives the agent's behavior is named in the README but not explained in the supplied text, so I cannot describe its mechanics.

Getting it running: releases, not a pip install

The README routes installation through the GitHub releases page. The download badge points at /releases/latest, and the platform icon on that badge is Windows, so the primary distribution path is a Windows release artifact rather than a pip package. The repository's primary language is Python, and the topics list llamacpp, which indicates the local inference path is llama.cpp-based. No pyproject.toml, requirements.txt, model file name, or CLI invocation appears in the material I was given, so I will not invent one. What the README does state as a configuration fact is that cloud providers are optional and that the core experience requires no account and sends no data unless you ask it to. The concrete keys, config file location and model directory are not in the supplied text. If you need those before installing, read the documentation site at jofizcd.github.io/soul-of-waifu-site and the release notes for v2.5.1, which is the most recent release listed (2026-08-28), followed by v2.5.0 and v2.4.7.

Soul Stage is a rules engine wearing a chat UI

Soul Stage is the module with the clearest engineering boundaries. The README describes deterministic dice rolls and skill checks, hidden Story Arcs the party has to uncover, a live Campaign Board with pressure clocks, structural relationship tracking that persists grudges and bonds, and Scene Folders for organizing campaigns. A dedicated AI Game Master drives it. The word deterministic is doing real work here: it implies the dice and skill resolution are computed by code, not narrated by the model, which is the only way a tabletop loop stays fair across sessions. The hidden Story Arcs and pressure clocks are the parts most likely to break under a weak local model, because they require the GM to track state it was not explicitly handed in the prompt. If you already run tabletop games with a human GM and a rules system, the comparison to make is not 'does the AI write good prose' but 'does it preserve campaign state between sessions'. The README claims structural relationship tracking never forgets a grudge, which is a testable claim you can check in your own campaign before trusting it with a long one.

Where it is the wrong tool

The desktop agent is the failure mode. An application that reads your screen, moves your mouse, types into any window, and executes sandboxed Python and PowerShell is, by construction, a large attack surface, and the approval banner is a mitigation rather than a boundary. The README's own phrasing, that nothing risky runs without your say-so, leaves the definition of risky to the implementation. If you handle regulated data, shared credentials, or a machine with production access, this is not the tool, regardless of how good the memory system is. There is a second, quieter mismatch: the project is a GUI desktop app with a Windows-first release path. If your use case is a headless companion on a Linux server, a Discord bot you script yourself, or something you want to call from another program, the desktop agent and Live2D avatar layers are weight you will carry without using. The repository does list a Discord Gateway with per-member awareness and image/GIF vision, so a Discord-adjacent workflow exists, but the README presents it as a feature of the desktop app rather than a standalone service.

What to compare it against

The obvious alternative for the memory problem specifically is a self-hosted chat frontend backed by a vector database, for example SillyTavern with a retrieval extension, or a custom stack of llama.cpp plus Chroma or similar. The difference in approach is not cosmetic. Retrieval-based memory keeps the raw transcript as ground truth and pulls relevant fragments into the prompt; Soul of Waifu's Soul Memory rewrites a compact state document and lets that document stand in for history. Retrieval is auditable, because you can read exactly which messages were injected. A rewritten state file is not, unless the project keeps a change log, and the README does not say that it does. On the agent side, the comparison is to general desktop automation tools that drive a browser or a shell with an explicit script you wrote. Those give you a deterministic action sequence you can review before it runs. Soul Companion generates the sequence at runtime, which is more flexible and much harder to audit in advance. If your priority is reproducibility, the scripting approach wins. If your priority is a character that acts unprompted, Soul of Waifu is built for exactly that.

Licence, maintenance and upgrade cost

The licence is GPL-3.0. That is a copyleft licence, so if you distribute a modified version, or a product that links against this code in the way the licence treats as a derivative work, you take on source-disclosure obligations. Running it privately for yourself does not trigger distribution. I am not a lawyer and this is not legal advice; read the full GPL-3.0 text and, if you plan to ship anything built on this, get proper review. On maintenance: the release cadence visible in the material is rapid, with v2.5.1 on 2026-08-28, v2.5.0 the day before, and v2.4.7 on 2026-08-17. The v2.5.0 release is titled Soul Continuum, and the README's changelog section is explicitly organized around what changed since v2.4.0, which tells you the project expects users to track version-to-version behavior. Fast releases on an app that owns persistent memory files and desktop automation mean you should read the release notes before upgrading rather than after, and you should know where the cognitive files live so you can back them up. The material does not state a migration policy for those files across releases, so treat that as an open question to verify.

Editorial conclusion

Adopt Soul of Waifu if you want a single local character identity spanning chat, voice, tabletop RPG and desktop presence, and you are willing to run a Python desktop stack on Windows and read the GPL-3.0 terms before redistributing anything. Do not adopt it if the desktop agent's OS access is a non-starter for your machine, or if you need a headless, server-side, scriptable companion with a documented API rather than a GUI app. Before installing, verify three things in the repository and docs: which Python version and dependencies the current release pins, where the four Soul Memory cognitive files are written on disk and how they are backed up, and what the approval banner actually gates (the README names a 25-second countdown, but the scope of gated actions is not fully specified in the README text).

Official sources

1. jofizcd/Soul-of-Waifu on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases