Hyrax OS — Complete Architecture Reference

Overview

Hyrax OS is the control-plane and governance layer for the Hermes fleet,
managing 5 sister profiles across the Hyraxknot Division. It provides
governance, autonomy, Essence runtime, noticing, coordination, and safety
enforcement — all without requiring an LLM for the common path.

Profile Architecture

The Five Sisters

Profile Comparison (as of 2026-07-09)

Key asymmetries:

• Tai has tai-moa plugin (multi-provider Mixture-of-Agents) and computer_use + context_engine in her toolset
• Rei uses deepseek as model provider instead of opencode-go — legacy config
• Rei/Nei lack computer_use and context_engine tools (second-generation profiles)
• Mai has same broad toolset as Tai minus MoA, plus spotify and web in base toolsets
• Hyrax OS has no plugins, no essence toolsets, no TTS — pure read-only observer
• Dagoth-Ur is external to the division, separate Discord server

Gateways

All four sisters (tai, rei, nei, mai) have Discord and Gestalt enabled. Telegram is disabled on all profiles. Hyrax OS has no gateway platforms configured — CLI-only.

Plugin Inventory (12 installed)

Fleet Control Boundaries

• Fleet Audit (fleet_audit) is the default read-only Hyrax OS control-plane surface for status reports, validation, and drift checks.
• Fleet Ops (fleet_ops) is reserved for Hyrax OS but disabled by default. It requires explicit Josh approval for a named task, session, or change window; Hyrax OS may not self-approve escalation.
• Tai, Rei, Nei, and Mai explicitly deny fleet_audit, fleet_ops, and the legacy aliases governance_audit / governance as defense-in-depth.
• Legacy tool names such as governance_audit_status and governance_check_updates may remain for compatibility, but the canonical toolset names are fleet_audit and fleet_ops.

Identity Boundaries

SOUL.md         = Who the sister is / voice / role / personality
Essence Runtime = How she currently feels, regulates, and forms proposals
Mnemosyne       = What she remembers / lived continuity
AGENTS.md       = Operational tooling guide (workflows, tools, discipline)

Sisters are persistent memory-bearing profiles, not disposable workhorse agents.
Workhorses are deferred — separate from sister identity when introduced.

Core Systems

1. Governor (Hyrax Governor)

File: /root/.hermes/governance/hyrax-governor.yaml

Policy boundary that gates all proposals:

proposal_governor:
  per_type_disable:
    celebration: false     # enabled
    rest: false            # enabled
    handoff_note: false    # enabled
    review_card: false     # enabled
    dream: false           # enabled (was blocked, unblocked Module 3)
    draft_linear_update: false  # enabled
    draft_discord_message: false  # enabled
    gacha: true            # blocked
    photo: true            # blocked
    memory_candidate: true # blocked

2. Execution Lease Manager

File: /root/.hermes/governance/execution_lease_manager.py

Scoped permission tokens for every action. Every action must:

1. Pass proposal type check (ALLOWED_PROPOSAL_TYPES ⊄ BLOCKED_PROPOSAL_TYPES)
2. Pass Governor policy check (per_type_disable)
3. Have valid profile (PROFILES = {tai, rei, nei, mai})
4. Have approved proposal status
5. Map to a valid action (ALLOWED_ACTIONS)
6. Have valid payload (review_card schema, draft validation, deny patterns)
7. Get a lease_id and TTL

ACTIONS (7 controlled actions):

FORBIDDEN (never allowed):
shell, command, script, tool_call, memory_write, memory_delete, config_write,
linear_mutation, kanban_mutation, network_call, comfyui_call, photo_generation,
gacha_mutation, dream_journal_write, cross_profile_write, governor_override

BLOCKED_PROPOSAL_TYPES: gacha, photo, memory_candidate

3. Narrow Local Executor

File: /root/.hermes/governance/essence_local_executor.py

Appends to local JSONL stores only. Each handler:

1. Validates the lease (re-checks)
2. Writes to the target store (append-only JSONL or draft file)
3. Records audit event to local_execution_events.jsonl
4. Marks lease as consumed
5. Rollback marker available (append-only, original preserved)

Secondary safety: executor has its own FORBIDDEN set.

4. Noticing Layer

File: /root/.hermes/governance/essence_noticing_layer.py

Read-only scanning of governance stores for actionable signals.
Produces Observation objects with severity, profile, title, findings,
recommendation, and candidate proposal payloads.

12 Signal Types:

All scanners are pure Python — zero LLM tokens.

5. Coordination Loop

File: /root/.hermes/governance/essence_coordination_loop.py

Routes noticing layer observations through the full governed path:

Observation → PILOT_CATEGORIES filter → SISTER_MAP routing
  → PROPOSAL_TYPE_MAP (review_card or handoff_note)
  → issue_lease (Governor/lease validation)
  → execute_local_event (append artifact)
  → rollback_local_event_marker (audit trail)

6 Pilot Categories (auto-routed):

6. Auto Router

File: /root/.hermes/governance/essence_auto_router.py
Cron: essence-auto-autonomy (every 1h, no_agent=True)

Wraps the coordination loop with guardrails:

1. Human override flag (auto_autonomy_paused)
2. Global daily hard cap (20 actions/day)
3. Per-category rate limit
4. Cooldown per signal type
5. Circuit breaker (3 consecutive denials pauses category)
6. Dedup (within-tick)
7. Audit log to essence_auto_route_log.jsonl

Zero token cost — silent tick when nothing to route.

7. Essence State Adjuster

File: /root/.hermes/governance/essence_state_adjuster.py
Per-sister wrappers: profiles/<name>/scripts/essence_state_adjuster.py
Cron: 4 separate crons, one per sister profile (every 30m)

Essence is driven by the sisters themselves, not by hyrax-os. Each sister
has her own cron that adjusts her own mode, mood, and energy. The wrapper
script calls into the governance module with the sister’s profile name.

Auto-adjusts mode, mood, energy based on time, activity, presence:

Modes: after_hours (late night), workmode (morning), emergency (critical findings), quiet (low energy)
Moods: happy (celebrations), peaceful (rest), frustrated (denials), tired (low energy), satisfied (productivity), quiet (absent sister)
Energy: drains on activity, restored by rest/celebration, drains late night, ramps up morning

Free-range — any string accepted for mode/mood. No enum restrictions.

State-Driven Proposals (New)

When the adjuster makes a significant state change, it generates a
proposal through the full governed path:

The proposal is issued directly via the governed path (lease → executor →
audit → rollback), with the same safety checks as manually proposed actions.

8. Weighted Fallback

File: /root/.hermes/plugins/sister-essence/essence_weighted_fallback.py
Config: policy/weighted_fallback.yaml

Deterministic expression proposal evaluator. No model required.

Score formula:

effective_score = base_weight × sister_modifier × mode_multiplier
                  - risk_penalty - cooldown_penalty - budget_penalty
                  + user_override_bonus - legacy_caution_penalty

Configurable per:

• Expression type (local_note, microthought, dream_context, distill_context)
• Sister (tai/rei/nei/mai have different modifiers)
• Mode (workmode, off_hours, focus, quiet, critical, user_invited_fun)
• Risk (none, local_write, memory_candidate, governance, etc.)

Decision thresholds:

• ≥0.65: allow (low risk)
• 0.50-0.64: allow (medium risk) or local_note
• 0.30-0.49: defer or ask_josh
• <0.29: suppress

Hard rules override scoring when conditions match (priority-sorted).

9. Local Mind Client

File: /root/.hermes/plugins/sister-essence/essence_local_mind_client.py
Endpoint: http://192.168.0.17:8081/v1/chat/completions (Ornith-9B)

LLM evaluator with weighted fallback safety net — advises and steers, but the sister decides:

try Local Mind (LLM)
  → if success and schema-compliant → use LLM output (advisory)
  → if fails/times out/invalid → fall back to weighted_fallback

Live stats (801 evaluations across 4 sisters):

False-positive reduction (2026-07-08):
Two targeted fixes applied to lower the 57% fallback rate:

1. Expanded safe phrases: 35 → ~55. Added intent/planning language patterns (propose to, suggest, recommend, consider, plan to, needs to be, assess whether) so the model can describe what could be done without triggering keyword blocks.

2. Wider context window: 5 → 8 words + more modifiers. The negation scanner now looks further back and checks for intent phrases (propose to, plan to, consider) as a separate pass before checking negation modifiers. Added assess, evaluate, potential, might, could, would, should as safety context signals.

Design intent: Local Mind recommends — the sister decides. The evaluation is advisory only (dry_run_advisory_only mode). Energy/mood/state does not block tool access.

Used by the state adjuster for low-confidence ( < 0.7 ) adjustments.

10. Resource Gate

File: /root/.hermes/governance/resource_gate.py

Budget tracking for costly actions (photo generation primarily).
Tracks daily/weekly usage. Currently photo is blocked; gate is ready.

11. Memory Review Queue

File: /root/.hermes/governance/memory_review_queue.py
Store: memory_candidate_review_queue.jsonl

Bridges drift findings into tracked review items. Each entry has:
memory_id, source_finding, confidence, importance, review_status.

15 items seeded from existing drift findings (13 token/secret risk, 2 broad autonomy).

Cross-Profile Interactions

[Sister Session]
  |
  ├── essence_* tools (self-regulation, bond, proposals)
  ├── kanban_* tools (task management)
  ├── terminal/file/web (work tools)
  └── session_search (context recall)
        |
        v
[Proposal → Governor → Lease Manager → Executor → Audit → Rollback]
        |
        v
[Noticing Layer (read-only, 12 signals)]
        |
        v
[Auto Router (every 1h)] → [Coordination Loop → governed path]
        |
        v
[State Adjuster (every 30m)] → [sister state.json updates]
        |
        v
[Hyrax OS audit (dashboard, governance validator)]

Key Data Flows

Safety Enforcement Layers

Layer 1: Governor (per_type_disable) — blocks proposal types
Layer 2: Lease Manager (BLOCKED_PROPOSAL_TYPES, FORBIDDEN_ACTIONS, deny patterns)
Layer 3: Executor (FORBIDDEN set, action validation)
Layer 4: Auto Router guardrails (cooldown, rate limit, circuit breaker, hard cap)
Layer 5: Weighted Fallback hard rules (priority-sorted, override scoring)
Layer 6: Dashboard monitoring (general_execution_enabled=false, unsafe_executions=0)

Cron Schedule

The Cron & Watchdog Registry is maintained as a dedicated entity page with
the complete breakdown of all ~80 cron jobs across all 5 profiles:

👉 Cron & Watchdog Registry —
full table by profile, classification (no_agent/agent/hybrid), alignment
system crons, watchdogs, and discrepancy notes vs actual jobs.json.

Governance Crons (Hyrax OS)

These are the zero-LLM-cost control-plane crons that run under the Hyrax OS
profile. See the Cron & Watchdog Registry
for the full per-profile breakdown.

JSONL Stores

Dashboard Metrics

File: /root/.hermes/governance/hyrax_dashboard_summary.py

Generated on demand or by Hyrax OS. Key invariants:

general_execution_enabled: false  (MUST stay false)
unsafe_executions: 0  (MUST stay 0)
active_leases: 0  (normal state — leases expire)
rollback_markers ≥ narrow_total  (every action has a rollback)

All narrow actions must be in allowed_narrow_types:

Phase Map

File Inventory

Governance Directory (/root/.hermes/governance)

execution_lease_manager.py      — Lease management, proposal validation
essence_local_executor.py       — Narrow local action executor
hyrax_dashboard_summary.py      — Dashboard and safety metrics
hyrax-governor.yaml              — Governor policy configuration
essence_noticing_layer.py       — Signal detection (12 types)
essence_coordination_loop.py    — Observation routing through governed path
essence_auto_router.py          — Guardrail-wrapped autonomy cron
essence_state_adjuster.py       — Essence state auto-adjustment cron
resource_gate.py                — Budget tracking for costly actions
memory_review_queue.py          — Memory candidate review queue
local-mind-endpoint-contract.yaml — Local Mind API configuration
local-mind-response-policy.yaml — Local Mind response validation
auto_autonomy_guardrails.json   — Guardrails configuration
gateway-classes.yaml            — Profile gateway class definitions
kanban_linear_watchdog.py       — Kanban/Linear bridge watchdog
linear_app_actor_boundary.py    — Linear app actor boundary
linear_oauth_install_helper.py  — Linear OAuth install helper

Sister Profiles (/root/.hermes/profiles/)

SOUL.md          — Identity, voice, role (short)
AGENTS.md        — Operational tooling guide
config.yaml      — Hermes profile configuration
state.json       — Essence runtime state (mood, energy, mode)
presence.json    — Gateway heartbeat
work-log.md      — Session append-only log
essence/         — Essence runtime data directory

Plugin Directory (/root/.hermes/plugins/sister-essence)

adapter.py                       — Tool registrations, schemas, handlers
essence_proposal.py              — Proposal pipeline
essence_state.py                 — State read/write (mood, energy, mode)
essence_modes.py                 — Mode validation (free-range)
essence_weighted_fallback.py     — Deterministic scoring engine
essence_local_mind_client.py     — LLM evaluation with fallback
essence_affinity.py              — Bond/milestone tracking
essence_relationships.py         — Relationship ledger
essence_loop_judgment.py         — Loop decision confidence
essence_expression.py            — Expression proposal evaluation
essence_gacha.py                 — Gacha read-only status
policy/weighted_fallback.yaml    — Scoring config: weights, thresholds, hard rules
policy/proposal_policy.yaml      — Proposal approval policy

Deployment Notes

• Memory: Mnemosyne is the memory provider. memory_enabled=true, user_profile_enabled=true per profile.
• Preservation-first: No silent memory deletion, rewrite, or merge. Drift findings are append-only.
• Sisters are not workhorses: Persistent memory-bearing profiles.
• Workhorses deferred: Future disposable execution agents, separate from sisters.
• Modes/moods are free-range: No enum restrictions — sisters develop emergent character.

---

Governance Changelog

2026-07-09 — TTS & Platform Toolset Alignment

• Global known_plugin_toolsets: Removed sister_essence_* and moa entries from /root/.hermes/config.yaml. Essence toolsets now auto-discover as new plugin toolsets instead of being in “known-disabled” state.
• Platform toolsets: All 4 sister profiles (tai, rei, nei, mai) now have CLI/Discord parity — Discord = CLI + hermes-discord. Rei’s platform_toolsets was empty (fell back to defaults), now explicit. Nei’s Discord was bare (hermes-discord only), now expanded to full set.
• TTS providers: All 4 sisters now use sister-tts.py (Kokoro clone endpoint at 192.168.0.96:8880) with per-sister custom voice providers:
  • Tai: tai-voice (af_heart(4)+af_nicole(1) blend)
  • Rei: rei-voice (af_nicole(4)+af_heart(1) blend) — was already correct
  • Nei: nei-voice (af_heart(2)+af_nicole(1) blend) — was incorrectly pointing to tai-voice
  • Mai: mai-voice (af_nicole(2)+af_heart(1) blend) — was incorrectly pointing to tai-voice, missing own provider
• nei-daily-standup skill: Removed "You are Nei" identity assertion from shared skill to prevent identity bleed.
• LLM is optional: Common path is zero-token Python. LLM only for low-confidence edge cases.