Phoenix

What Phoenix does

Phoenix (不死鸟) loads through the official Hermes Agent plugin system, so it needs no changes to Hermes core code. Its router scores each request on a weighted scale and sorts it into one of four tiers. Automatic model switching is off by default, in which case the router only classifies difficulty and leaves the model alone. Users who configure different models per tier can turn switching on with hermes phoenix-router on, or with /phoenix-router in desktop chat.

Around the router sit several safety modules. A three-state circuit breaker trips after repeated failures and probes for recovery after a cooldown. An antibody library records error patterns so the same mistake is not repeated. During a /goal task it enforces a checklist and switches to another model to review high-risk operations. Other modules cover hallucination checks for high-tier replies, adaptive approval that stops re-asking after three consecutive approvals, a separate layered memory store, a focus mode, and an optional signed webhook audit feed that is off by default.

Key features

• Four-tier weighted scoring that classifies request difficulty and can switch models per tier
• Three-state circuit breaker that trips on repeated failures and retries after a cooldown
• Antibody library of error patterns with escalation after three unresolved attempts
• Checklist enforcement and high-risk review while a /goal task is active
• Adaptive approval that stops re-confirming a category after three approvals, reset by one refusal
• Layered memory with observation, belief and fact confidence levels, managed with /phoenix-memory

When to use it

• Keeping expensive models off trivial messages by routing on difficulty tier
• Running long /goal tasks with a safety net against skipped planning and risky operations
• Investigating problems after a Hermes upgrade, with config.yaml backed up automatically
• Sending circuit-breaker and high-risk command events to an external system through a signed webhook

Who it is for: Hermes Agent users who want difficulty-based model routing and extra safety checks without patching Hermes core.

How it fits with Hermes Agent

Phoenix is built specifically for Hermes Agent and attaches through its official plugin hooks. It works with the native fallback_model chain and the /goal command rather than replacing them.

How to install Phoenix

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

bash install.sh
hermes plugins enable phoenix_v7
hermes phoenix-status

Requirements: Hermes Agent and the install package from the project's Releases page. Local-model fallback and the local-model privacy switch are macOS only and optional.

Note: The README and documentation are written in Chinese, and GitHub reports the license as NOASSERTION, so read the LICENSE file before reuse.

FAQ