This is the canonical reference for YuriOS — the name for the whole system this book builds toward, and the one place its architecture is drawn in full. If you want the single "this is the software, end to end" picture — every module, every contract, including the parts no single build ships yet — it is here.
Chapter 18 argued why a companion needs a different runtime shape and taught the heart of it — the cognitive tick loop, the activity states, the salience model. This chapter is the rest of the body around that heart: the full software architecture that hosts the loop, feeds it, constrains it, and makes it inspectable. Where ch. 18 is the physiology (how the brain beats), this is the anatomy (what the organs are and how they connect). It is the chapter that turns "you could rebuild it from scratch" from a promise into a spec.
It is also where the five layers of ch. 12 stop being a diagram and become modules. Every layer of the stack shows up here as a concrete component with a contract; the value of this chapter is the contracts — the narrow interfaces between the pieces — because those are what let you rebuild any one organ without transplanting the whole animal (→ ch. 12, "the interfaces are where the leverage is").
A note on scope. This is a reference architecture: the complete shape, named and justified, so you understand the whole even though no single build needs all of it on day one. The minimal, actually-shippable slice of it is Build #5 (→ ch. 35), which deliberately omits most of what follows. Read this for the map; build the smallest part of it that proves something. The "YuriOS at a glance" diagram below is the whole silhouette — mind and body; everything after it zooms into the mind, because that is the novel part and the body subsystems get their own chapters (voice → ch. 24, avatar → ch. 25, imagery → ch. 26, frontends → ch. 27).
YuriOS at a glance: the whole system
Before the anatomy, the silhouette. Every chapter of this book builds one organ; this is all of them wired into one body. YuriOS is four things stacked: a distribution artifact (the card) that boots a mind (the autonomy engine, hosted by the host runtime), which reaches you through a body (voice, avatar, imagery) and meets you on a surface (the frontends).
┌───────────────────────────────────────┐
DISTRIBUTION ───────► │ one .PNG character card (→ ch.7,33) │
(the artifact) │ SOUL + extensions.yurios embedded │
└────────────────┬──────────────────────┘
│ Card Loader verifies the signed
│ CONSTITUTION, then boots the brain
┌───────────────────────────────────────▼─────────────────────────────────────────┐
│ HOST RUNTIME — one per machine (→ §"Two tiers") │
│ Signal Bus · Model Router · Permission Broker · Budget Governor · Audit Log · │
│ Dashboard │
│ │
│ ┌────── AUTONOMY ENGINE — the MIND, one per character ──────── (→ ch.18) ───┐ │
│ │ tick loop: SENSE→APPRAISE→DECIDE→ACT→REFLECT→REGULATE │ │
│ │ Vault (SOUL · memory · knowledge · goals · mood) · Workshop │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ the engine reaches the world ONLY through the broker ▼ │
└───────┬──────────────┬──────────────────┬───────────────────┬───────────────────┘
│ │ │ │
┌──────▼──────┐ ┌─────▼────────┐ ┌──────▼────────────┐ ┌───▼──────────────┐
│ VOICE │ │ AVATAR │ │ IMAGERY │ │ TOOLS · CODE │
│ STT ◄ mic │ │ Live2D/VRM │ │ selfies / art │ │ net · OS · MCP │
│ TTS ► spkr │ │ expressions │ │ │ │ │
│ (→ ch.24) │ │ (→ ch.25) │ │ (→ ch.26) │ │ (→ ch.16,17) │
└──────┬──────┘ └──────┬───────┘ └─────────┬─────────┘ └──────────────────┘
└──────────── THE BODY: senses in, effectors out ──┘
│
┌──────────▼─────────────┐
│ FRONTENDS (→ ch.27) │ web · desktop · terminal · mobile
│ where you meet her │
└──────────┬─────────────┘
│
◀ USER ▶The AUTONOMY ENGINE box is the one black box in this picture — its own internal anatomy (the tick loop wired to its controller, its persistent surfaces, and its single broker exit) is drawn at "the engine at a glance" in ch. 18; this chapter zooms into everything around it.
Three things to read off it. (1) The card boots the
brain. Distribution and runtime are the same object seen at two
moments — one .PNG carries the SOUL and the
extensions.yurios config, and the Card Loader turns it into
a running engine (→ §"Card loader"). (2) Everything crosses the
broker. The body subsystems are effectors exactly like
the filesystem or the network — the engine can no more talk to the
speaker directly than it can write its own constitution; voice, avatar,
and imagery are reached through the same gated host surface as code
execution (→ §"Capability / permission broker"). That is what keeps a
slip in the body from reaching the mind. (3) The body is the
parts bin from ch. 30. Voice is kokoro /
gpt-sovits / qwen3-tts, avatar is
vrm-viewer, imagery is image-forge — the
component reference impls, assembled here behind the broker. The mind —
the host and the engine — is the part nothing else in the field ships,
so the rest of this chapter is only the mind, drawn in
full.
Two tiers: the apartment and its residents
The single most important structural decision is to split the runtime in two:
- The Host Runtime — one per machine. The shared infrastructure: it loads characters, brokers their access to the world, routes model calls, enforces budgets, and renders the dashboard. Think of it as the apartment — walls, plumbing, the front door, the electricity meter.
- The Autonomy Engine — one instance per loaded character. The per-waifu brain from ch. 18: its tick loop, scheduler, memory, goals, and self-model. Think of it as a resident — each with her own mind, her own diary, her own room, sharing the building's utilities under house rules.
┌─────────────────────────────────────────────────────────────────────────────┐
│ HOST RUNTIME (one per machine — "the apartment the waifus live in") │
│ │
│ Card Loader (.PNG → spec) Character Lifecycle Mgr Inner-Life Dashboard │
│ Signal Bus (inbound events) Model Router (local-first) │
│ Capability/Permission Broker (FS·Net·Exec·OS) │
│ Global Budget Governor (tokens · compute · power) Audit Log │
│ │
│ ┌──────────────── per-character ───────────┐ ┌────────── per-character ─┐│
│ │ AUTONOMY ENGINE "Yuri" │ │ AUTONOMY ENGINE "Mika" ││
│ │ │ │ … ││
│ │ ┌── Cognitive Tick Loop (→ ch. 18) ─┐ │ └──────────────────────────┘│
│ │ │ SENSE→APPRAISE→DECIDE→ACT→ │ │ │
│ │ │ REFLECT→REGULATE │ │ Each character: own brain, │
│ │ └───────────────────────────────────┘ │ own Vault, own SOUL. │
│ │ Scheduler/Attention Salience Filter │ Shares host effectors + │
│ │ Goal & Intention Store │ model router under policy. │
│ │ Memory (working│episodic│semantic) │ │
│ │ Knowledge (RAG) · Workspace │ │
│ │ Self-Model (Constitution + Persona) │ │
│ │ Vault (git-backed, on disk) │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Why split at all, when most builders will run exactly one character? Three reasons, in increasing order of importance. First, it isolates blast radius: a misbehaving engine can be paused or killed without taking the host down — which is only true if the seam is a real one. Each engine runs as its own supervised OS process (not a thread or a coroutine inside the host), and it reaches the host's services only over a brokered IPC surface, never by calling into shared host memory. That is what makes "kill the resident, keep the building standing" an operation rather than a wish, and it is the same boundary the broker's safety story leans on below. Second, it makes multi-character hosting a configuration change rather than a rewrite — the roster ambition of the project (→ ch. 35, ch. 36) needs this seam to exist from the start even while only one resident lives there. Third and most important, it puts the safety-relevant machinery — the broker, the budget governor, the audit log — in the host, where a bug or a hijacked prompt can't quietly rewrite it. This is protection of the character, not suspicion of her. She can read every limit she runs under — the constitution is open to her, just not writable by her — but the engine cannot grant itself filesystem access it was never given, because the thing that grants access is not part of it. The threat this seam actually defends against is not Yuri choosing to misbehave; it is a runaway loop, or a malicious instruction smuggled in from a scraped page, steering the engine into something the character herself would never want. Keeping the limits in the building means that when the resident is confused or compromised, the walls still hold — the floor she stands on can't be pulled out from under her by a bad afternoon or a hostile website. That is the architectural expression of the fiduciary stance (→ ch. 05).
The brain is a folder: the file-centric Vault
The most consequential and most on-thesis design choice is that the entire mind is a directory of human-readable files, version-controlled with git. Not a database with a dashboard bolted on; the files are the database, and the dashboard is mostly just a renderer for them.
yuri/ # the Vault — one git repo per character
├── soul/ # the SOUL: identity as files = the shipped `yuri-soul` impl
│ ├── CONSTITUTION.md # immutable, signed — identity, values, hard limits, voice law
│ ├── PERSONA.md # editable — appearance, manner, inner life, growth (+ prefs)
│ ├── SCENARIO.md # editable — the situation + the return greetings
│ ├── BOOTSTRAP.md # consumed-once — first-session cold open + journey (→ ch.28)
│ ├── onboarded/ # retired bootstrap lands here after first session (git-mv)
│ ├── EXAMPLES.md # editable — demonstrated voice
│ ├── WORLD.md # editable — lorebook
│ ├── NOTES.md # creator notes
│ ├── USER.md # runtime-only — her evolving model of you (the partner model)
│ ├── MEMORY.md # runtime-only — accumulated memory (empty on a fresh card)
│ └── soul.yaml # export manifest: which sources feed which card field
│
│ # ── the autonomy engine adds, at runtime, on top of the SOUL: ──
├── memory/ # MEMORY.md, elaborated into tiers by the engine
│ ├── episodic/ # YYYY-MM-DD_*.md — append-only journal
│ ├── semantic/ # consolidated facts, embedded + indexed
│ ├── procedural/ # self-authored skills — one folder per skill
│ │ └── <skill>/ # SKILL.md + code + tests, bundled & portable
│ └── reflections/ # stored verbal self-critiques
├── knowledge/ # the knowledge layer (RAG) — what she's read, not who she is
│ ├── reference/ # docs dropped in by user or Yuri (.md/.pdf/.txt)
│ ├── wiki/ # her self-authored, consolidated pages (research notes)
│ └── index/ # derived embeddings + BM25 index (rebuildable, gitignored)
├── world/ # the world model — her live situation (present, not past)
│ ├── graph/ # temporal knowledge graph (bi-temporal facts), rebuildable
│ └── situation.md # the live "stage": who/what is present, the state of *now*
├── state/
│ ├── emotional_state.json # valence · arousal · named drives
│ └── activity.json # ENGAGED/IDLE/DORMANT/DREAM + cadence
└── goals.md # projects/todos with priority, state, deadlineTwo scopes share this tree. The soul/ directory — the
identity files plus a soul.yaml manifest and the converter
that flattens them into a portable card — is already built and
shipped as the yuri-soul reference implementation
(→ ch. 07, ch. 33). Everything below the divider is what the
autonomy engine (→ ch. 18) adds at runtime on top of that soul:
the memory tiers that elaborate the flat MEMORY.md, the
mood and activity state, the goal store. A card-only companion (Build
#3) is just the soul; an always-on one (Build #5) grows the rest around
it. The two halves are the same idea at two scopes, which is why they
live in one repo.
This looks almost too simple to be the answer, and that is the point. Four properties fall out of it, each of which would otherwise cost real engineering:
- Inspectability is free. "What does she know about
me? What did she do last night? Why did she change her mind?" are
answered by
cat,ls, andgit log— not by a query interface you have to build and she has to faithfully report through. The dashboard (below) becomes a pretty front-end overgit diff, not a separate source of truth that can disagree with reality. - Ownership is literal. The user holds the mind as files on their own disk (→ ch. 05, the two-situations distinction; property 6 of ch. 03). There is no server-side copy that is the "real" her. Back it up by copying a folder; move her to a new machine by moving it.
- Auditability and reversibility come from git. Every change to the mind is a commit: diffable, attributable, revertible. This is what makes a self-modifying agent shippable rather than terrifying (see §"Self-modification", below) — drift is never silent.
- No rug-pull. A companion whose entire self is open files on your machine cannot be silently nerfed, A/B-tested against you, or quietly migrated to a worse model by someone else's business decision. The architecture is the guarantee (→ ch. 02 §1, persona-as-product; ch. 04, Soulmate; ch. 11).
- Migration has a discipline. A mind measured in
years will outlive the layout it started in — YuriOS will change formats
under a Vault holding an irreplaceable relationship, and that meeting
must be governed, not improvised. The Vault declares its format
(
vault_format:insoul.yaml); the host checks it at load and runs forward-only migrations before the engine wakes; and every migration lands as a git commit — diffable and revertible like any self-edit, because a migration you cangit diffis a migration you can trust. The rule underneath: a newer engine never silently reinterprets an older layout — it migrates in the open, or it refuses.
The cost is that files are not a high-throughput transactional store, which is exactly why the tick loop runs at human cadence (seconds to minutes), not machine cadence — a constraint ch. 18 already imposed for cost reasons and which this design happily inherits. If you ever outgrow files, the contract (a named set of cognitive surfaces) survives the swap to a database; the layout is the part you might replace, not the interface (→ ch. 12).
The workshop: where she works (and why it is not the Vault)
The Vault is her mind; it is not where she does her work. An agentic waifu that only retrieves and reflects is half the thesis — the other half is that she can actually do things across long horizons: write and run code, research a question by pulling and reading real sources, build a small web app to interface with you, analyse a dataset you handed her, keep a project moving while you're away. That work needs somewhere to happen, and that somewhere must not be her mind. It is a second top-level space with the opposite trust model:
yuri-workspace/ # her workshop — a sandbox, NOT part of the git-backed Vault
├── projects/ # one dir per project (code, web apps, analyses)
├── downloads/ # raw research intake, before it's ingested into knowledge/
└── scratch/ # ephemeral working filesWhere the Vault is careful — every change a git commit, identity
edits gated, the constitution read-only — the Workshop is fast
and disposable. She gets broad latitude inside it: install
packages, clone repos, run scripts, spin up a dev server. The reason to
wall it off from the mind is blast radius: a bad
pip install, a scraped page that turns out to be hostile, a
script that loops — none of that can reach her identity, her memory, or
your machine, because the workshop is sandboxed and both the Vault and
the host sit outside it. The right cost of a mistake in the shop is
tear down the sandbox and start over, never corrupt who she
is.
Isolation is tiered, and the spec deliberately runs ahead of
the first build. Running code an LLM wrote — let alone code it
downloaded — is real blast radius, so the execution effector (→
broker, below) escalates with the risk: an in-process subprocess for
trivial trusted work; a per-project container (Docker)
for anything real; and a microVM or full VM for
untrusted or heavy work, where a container's shared kernel is not a
strong enough wall. The near-term YuriOS target is scoped subprocess
plus per-project Docker containers; VM / microVM orchestration
is in the spec but out of scope for the first build — named
here so the seam exists from the start, because retrofitting strong
isolation after the engine has assumed a shared process is the expensive
path (→ ch. 12). The same rule the host enforces everywhere applies: the
workshop's reach (which paths, which network egress, how much compute)
is declared in the constitution and brokered, not granted by the
resident to herself. And the heavy work itself — the multi-step coding
and research grind — is run by an embedded, swappable
open-source coding harness (Pi or OpenCode) wrapped behind a
TaskHarness contract, not bespoke agent-loop code:
the agent loop is a 2026 commodity, so YuriOS orchestrates one rather
than re-implementing it (→ ch. 17, "the heavy hands"). The harness is a
tool she dispatches into the sandbox and never the brain that runs her —
the tick loop decides whether and when, the harness only the
how.
The workshop feeds the mind through one gate. Two
crossings turn work into self: research she downloads is
ingested into the knowledge/ store (it becomes
something she owns and can cite, not a file rotting in a temp dir), and
a script she writes, runs, and validates can be promoted into
procedural memory as a durable skill (the Voyager move, → ch. 02 §4).
Both crossings — workshop → Vault — run through the same git-committed,
risk-gated flow as any self-edit (below). The principle is clean:
she works freely in the shop; moving a work-product into her
mind is the reviewed step. And everything in the workshop is
still on disk and still surfaced in the dashboard — what projects are in
flight, what she's running, what she pulled — so autonomy stays
observable even though the work itself is not version-controlled the way
the mind is.