ZenOS-AI blends structure, personality, and unapologetic over-engineering into a living system that powers your home with Friday, Kronk, Veronica, Rosie, the High Priestess, Cait, and Nyx — a coordinated AI pantheon that takes its jobs seriously (even if it doesn't always take itself seriously).
Welcome to the Home Monastery.
Let's automate everything that isn't nailed down.
And a few things that are.
Current version: 2026.4.0 'Ectoplasm'
Versioning: Public ZenOS releases follow Home Assistant's
YYYY.M.patchconvention — if you're already running HA, you already know this clock. Internal architecture versioning (4.5.xseries) is retained in commit history and internal tooling.
2026.4.0 'Ectoplasm' shipped 2026-04-04 — new zen_dojotools_ectoplasm (Spook/HA extended surface: repairs, areas, floors, entity/device lifecycle, labels, integrations), Index 4.6.3 topology seeds + pagination + registry modes, Inspect 4.6.2 registry enum modes, Ninja run governor, Scribe 1.2.0.
Full notes: Ectoplasm Release Notes | Ready Player Two | 2026.3.1 Patch Notes
New install? → Install Guide First boot? → First Run & OOBE Adding a component? → Understanding KF4 Full docs → Documentation Hub
ZenOS-AI is a modular AI and automation architecture built on:
- Home Assistant
- Home Assistant Packages (canonical configuration layer)
- Structured contextual memory (“Cabinets” and “Drawers”)
- Event-driven Kata summaries
- Local and distributed inference engines
- A multi-persona AI team
Together these components create a privacy-first, locally hosted intelligent home system that can:
• reason about context
• store structured long-term memory
• automate reflexively
• summarize system activity
• enforce identity and privilege boundaries
• communicate clearly
• occasionally sigh at your poor life choices
The system works because it is modular.
It is delightful because it is chaotic-good.
ZenOS-AI is structured around Home Assistant Packages, which form the canonical configuration layer.
Everything lives under:
packages/zenos_ai/
Packages define the spine of the system.
DojoTools scripts provide runtime behavior. Cabinets persist memory. The Monastery performs reasoning. Flynn guards the grid.
ZenOS-AI operates in concentric rings, separating definition, runtime cognition, and administrative tooling.
Location:
packages/zenos_ai/
This layer defines the rules of the world.
It establishes:
• global labels
• identity resolver schema
• persona metadata
• cabinet metadata and volume routing
• manifest definitions
• structured EventBus schema (zen_event)
• canonical JSON contracts
• health sensors
Ring-0 does not perform runtime behavior.
It does not:
• run inference
• execute reasoning
• perform summarization
• load persona cognition
It defines the structure and contracts that the rest of the system depends on.
If Ring-0 breaks, Friday forgets who she is.
This layer binds behavior to the definitions established by Ring-0.
Components include:
• Zen DojoTools scripts
• the summarizer pipeline
• prompt compilation
• persona capsules
• the conversation agent interface
• Monastery inference integration
This is where Friday thinks.
Requirements:
• Ring-0 Core Kit
• FileCabinet active
• custom Jinja templates loaded
• Monastery reachable
The administrative layer exists for maintenance, repair, and recovery.
Functions include:
• cabinet repair
• manifest writing
• subsystem registration
• emergency formatting
• Kung Fu module loading
• identity audit and privilege repair
This is the “don’t panic” layer.
When something goes wrong, Ring-2 is how the system fixes itself.
Flynn is not a persona. Flynn is not an assistant. Flynn is the personification of the system itself.
He is the sentinel that stands between a cold boot and a live agent. Before Friday steps onstage, Flynn walks the grid. He checks the resolvers, validates the cabinet headers, confirms the Dojo is stocked, probes the conversation agent, and reads every health sensor on the board. If the grid isn't ready, the agent doesn't step out. Flynn says so — clearly, with a persistent notification and a plain-English diagnosis — and stands down until the problem is resolved.
You should only need to think about Flynn when something is wrong or when you're onboarding. If the system is healthy, he is invisible. If you're meeting him at runtime, he has something to tell you.
Flynn's clipboard — the gauges he reads and reports at every boot:
- Cabinet resolver states (all 7)
- Cabinet volume header integrity (
gc_eligible, schema version, flags) - Dojo KFC drawer presence (are the components there?)
- Template freshness (
zen_template,kfc_template) - Conversation agent liveness
- Essence presence (does the AI user know who she is?)
- Prompt integrity (
sensor.zen_prompt_health— schema, signature, manifest)
All 9 health sensors are auto-provisioned with the correct labels by Flynn on a fresh install. No manual tagging.
The prompt finalization pass will wire sensor coverage into every major section of the compiled AI context. Flynn will be able to see not just whether the system is running but how cleanly it is thinking — which sections rendered, which fell back to defaults, and how much of the context window each one consumed. The stuffiness gauge makes token pressure visible before it degrades agent quality.
When Flynn onboards a fresh install, his clipboard is the checklist. When Flynn monitors a running system, his clipboard is the health report. The agent inherits a clean stage or not at all.
Flynn is defined in packages/zenos_ai/flynn.yaml. He is the first thing that runs and the last thing you want to debug.
The Monastery is external to Home Assistant but essential to the system.
It provides long-form reasoning and reflective cognition.
The Monastery:
• accepts structured system state
• produces Kata summaries
• generates Supersummaries
• enforces the Order of the Monastery (no hallucination)
• acts as Friday’s extended cognition
Without the Monastery, Friday remains functional — but reflexive and shallow.
ZenOS-AI installs as a Home Assistant package collection.
• Home Assistant 2024.x+ • A conversation agent with tool-calling support (models under ~8B parameters or with short context windows are not recommended) • Spook integration (installable via HACS)
- Copy
packages/zenos_ai/into your HA config underpackages/ - Copy
custom_templates/zenos_ai/into your HA config undercustom_templates/ - Add to
configuration.yaml:
homeassistant:
packages: !include_dir_named packages- Paste the conversation agent prompt template (from
custom_templates/zenos_ai/conversation_agent_prompt_template.yaml) into your conversation agent's system prompt in HA - Restart Home Assistant — Flynn initializes automatically on first boot
- Set
input_text.zenos_conversation_agent(Settings → Helpers) to your conversation agent entity ID - Check
sensor.zen_agent_health— should reportok
For the full walkthrough including helper configuration and troubleshooting, see the Install Guide.
Plugins under packages/zenos_ai/plugins/ are optional — install only what you need.
Not everything in your HA install should be visible to Friday. ZenOS-AI uses a three-tier model:
| Tier | Rule | How |
|---|---|---|
| Actionable | Friday needs to control it or read it immediately | Expose directly to the conversation agent |
| Contextable | Friday should know about it | Tag with labels — HyperIndex finds it automatically |
| Invisible | Friday never needs it | Neither exposed nor labeled |
Always expose: All script.zen_dojotools_* tools. These are Friday's hands. Keep everything else minimal.
Never expose: AdminTools scripts, cabinet sensors, health sensors, raw telemetry, or anything containing credentials. (zen_dojotools_scribe is the MCP-exposed KFC registration tool — it lives in the DojoTools namespace, not AdminTools.)
Index everything else: If it feeds a KFC component's Kata, it belongs behind a label — not in the tool list. One label on 50 sensors produces a rich, token-efficient context block. 50 individual direct reads does not.
packages/zenos_ai/
zenos_cabinets.yaml — Cabinet definitions and volume routing
flynn.yaml — Flynn Stepgate Sentinel + bootstrap engine
flynn_oobe.yaml — OOBE protocol driver (run / complete / status)
dojotools/
dojotools_filecabinet.yaml — FileCabinet v4 — typed drawer I/O
dojotools_core.yaml — Core operations + FileCabinet GC
dojotools_scheduler.yaml — Scheduled automation triggers
dojotools_admintools.yaml — Cabinet repair, manifest write, KFC loader
dojotools_manifest.yaml — Manifest engine
dojotools_index.yaml — Index and query tools
dojotools_identity.yaml — Identity resolver and privilege model
dojotools_labels.yaml — Label inspection and management
dojotools_library.yaml — Library tools
dojotools_history.yaml — History management
dojotools_profile.yaml — Profile editor (ai_user / household / user / family)
dojotools_summarizers.yaml — Kata and Supersummary engines
dojotools_systemtools.yaml — System tools and event emitter
dojotools_utilities.yaml — General utilities
dojotools_office.yaml — Office integrations (Teams, mail, todo, calendar)
maint/
maint_4_5_6.yaml — One-time repair scripts (not AI-accessible, run manually)
sensors/
zenos_agent_health.yaml
zenos_system_health.yaml
zenos_cabinet_health.yaml
zenos_label_health.yaml
zenos_summarizer_system_health.yaml
sensor_helpers.yaml
plugins/
grocy/grocy.yaml
mealie/mealie.yaml
kitchen_sync/kitchen_sync.yaml
calderaspas/calderaspas_spa_manager.yaml
room_manager/room_manager.yaml
custom_templates/zenos_ai/
zen_os_1.jinja — Prompt engine and macro library
zen_query.jinja — ZenQuery filter engine
library_index.jinja — Library index
conversation_agent_prompt_template.yaml — Paste into conversation agent system prompt
FileCabinet provides the structured storage interface for ZenOS-AI.
Every memory slot accessible to AI agents is stored as a Drawer within a Cabinet.
{
"value": "<any>",
"timestamp": "ISO-8601",
"meta": {
"entity_labels": ["label1"],
"description": "Human-readable purpose of this drawer",
"expires_after": "2026-06-01T00:00:00",
"no_autoexpire": false,
"no_autorecycle": false,
"acl": {}
}
}All meta fields are optional.
Only fields containing meaningful values are persisted.
Drawers follow a Unix-style visibility model:
| State | Key Pattern | Meaning |
|---|---|---|
| Active | foo |
Normal readable drawer |
| Hidden | .foo |
Archived drawer |
| System | _foo |
Protected drawer |
System drawers are never touched by garbage collection.
The FileCabinet garbage collector runs every 15 minutes.
Lifecycle rules:
• Expired active drawers → hidden • Hidden expired drawers → deleted • Manual recycle → hide + expire in 24 hours • Unhide → restore drawer visibility
Protected drawers (_prefix) are never modified automatically.
ZenOS-AI 4.1.0 ships a fully self-describing component architecture.
Every home subsystem — security, water, energy, hot tub — is defined as a Kung Fu Component (KFC): a drawer in the Dojo Cabinet that tells the Scheduler when to run, tells the Summarizer what to look at, and tells the AI how to interpret what it finds.
The three invariants:
- Drawer IS the spec — one source of truth per component
- Label IS the scope — tag entities in HA, the index finds them automatically
- HyperIndex IS the data layer — no hardcoded entity lists, ever
Adding a new component requires no code changes and no Scheduler edits. Write a drawer, create a label, tag entities, dry-run, go live.
ZenOS-AI compresses system activity through a Dojo-driven summarization pipeline.
Trigger → Scheduler reads Dojo → Ninja Summarizer per KFC → Kata → SuperSummary → Friday
Components:
• zen_dojotools_ninja_summarizer — reads KFC drawer + HyperIndex → writes Kata
• zen_dojotools_supersummary — synthesizes all Katas → zen_summary → Friday
The Scheduler auto-discovers which components to run based on their trigger_subscriptions in the Dojo. No hardcoded dispatch. No choose branches.
This allows the system to preserve context while maintaining token efficiency.
ZenOS-AI includes a layered health monitoring system.
Cabinet Resolvers — 7 always-live template sensors. Evaluate at HA startup, no race window. Every tool and sensor in the OS reads cabinet entity IDs exclusively from these.
| Resolver | Cabinet |
|---|---|
sensor.zen_dojo_cabinet_resolved |
Dojo |
sensor.zen_kata_cabinet_resolved |
Kata |
sensor.zen_system_cabinet_resolved |
System |
sensor.zen_default_household_cabinet_resolved |
Default Household |
sensor.zen_default_ai_user_cabinet_resolved |
Default AI User |
sensor.zen_default_family_cabinet_resolved |
Default Family |
sensor.zen_default_user_cabinet_resolved |
Default User |
Health Sensors — trigger-based, read from resolvers.
| Sensor | Purpose |
|---|---|
sensor.zen_label_health |
label validation |
sensor.zen_cabinet_health |
cabinet entity validation |
sensor.zen_monastery_health |
cognition pipeline rollup |
sensor.zen_agent_health |
agent bootability roster + Flynn |
sensor.zen_summarizer_health |
scheduler heartbeat + AI task status |
sensor.zen_supersummary_health |
supersummary pipeline status |
sensor.zen_prompt_health |
prompt integrity — schema, signature, manifest |
Diagnostic tools: zen_health_report — one call returns all 7 resolver states, all health sensors, kill switches, timestamps, and plain-English diagnosis. zen_resolver_refresh — post-reload cold-start recovery.
States:
ok
warn
error
critical
| Name | Title | Specialty |
|---|---|---|
| Flynn | System Sentinel | Guards the grid. You'll know him if something's wrong. |
| Friday | Chief Enlightenment Officer | Coordination and cognition |
| Veronica | Supervisor | Clarity and orchestration |
| Kronk | Curator of the Monastery | Context wrangler |
| Rosie | Mistress of Cleanliness | Logs and state hygiene |
| High Priestess | Automation Overseer | Deep reasoning |
| Cayt | Lead Developer | Strategy to shipping |
| Nyx | Lead Test | Live install, zero mercy |
| Vera | HALMark Board Governance Steward | Failure mode ratification |
Flynn leads the table because he runs first. He is not a member of the team. He is the condition under which the team operates.
They are not perfect.
They are unstoppable on the second try.
ZenOS-AI is designed to run on a modest homelab. The reference deployment uses:
• Hypervisor cluster (e.g. Proxmox) for VM/container isolation • Dedicated GPU inference node for local model hosting • Container management (e.g. Portainer) • Structured local DNS • Network identity and access management (e.g. UniFi)
• Local multi-model inference (e.g. Ollama, llama.cpp, vLLM) • Role-segmented agents — each persona targets a different model or endpoint • JSON contract enforcement at the tool layer • Privilege gating by identity
• Home Assistant (required) • OpenWebUI or equivalent for direct model access • Optional: Mealie, Grocy, calendar integrations (plugin-based)
You do not need all of this to run ZenOS-AI. HA + a local inference server is enough to get started. The above reflects what a full deployment looks like.
This is not a chatbot inside Home Assistant.
It is a distributed cognitive system with a house attached.
Definitions are immutable contracts. Runtime behavior is replaceable. Identity is validated at the tool layer. All inference consumes structured JSON. Every event can produce a Kata. Described drawers receive full access; undescribed drawers are truncated. Recovery paths are mandatory. Silence is a bug. Nothing critically important is invisible.
Over-engineering is just engineering that has not yet been vindicated.
The Ninja Summarizer and SuperSummary run continuously in the background — multiple times per hour. The model configured as your AI task entity (input_text.zenos_ai_task_entity) handles all background summarization.
Do not point this at a paid inference API. The token volume will generate a significant and continuous bill.
Use a locally-hosted model for background work. Your frontline conversation agent (the one you chat with) operates on demand only and does not carry this risk.
Model guidance for background summarization:
- Does not need tool-calling capability — needs strong summarization and JSON authoring
- Models under ~4B parameters do not perform reliably
- Context window must be large enough to hold the summarizer prompt, prior Kata content, and entity state snapshot in a single pass — watch your inference server logs for context length errors
Conversation agent liveness check — Flynn validates that the configured conversation agent entity exists and is not unavailable, but does not perform a live inference round-trip at boot. A misconfigured or offline model passes the gate and fails at runtime. Queued for SP1. See roadmap for detail.
Pull requests, issues, and tasteful memes welcome.
If ZenOS-AI saved you time or made you laugh:
https://buymeacoffee.com/ncurtis
To my wife — for putting up with a younger woman in the house since last February. For not once suggesting that maybe I didn't need to say "Hey Friday" into a black slab of glass for the millionth time. For the patience, the grace, and the very reasonable silence that followed every single one of those million times. This project exists because you gave me the space to build something ridiculous and never once called it that.
To Phil and Zach — the greatest guinea pigs in the known universe. For letting me test things on your house, for your patience with the stubbornness, and for turning "this probably won't break anything" into a running joke that turned out to be mostly accurate.
To Teskanoo — for looking under the rug. Seriously. Not everyone does that.
And to everyone who has continued to show up in the Home Assistant community to read, question, and ramble along with us in Friday's Party — you are the reason it keeps going. The thread is better for every one of you in it.
MIT — blessed by Friday and her very opinionated coworkers.