oh-my-hermes

Product Introduction

1. Definition: Oh My Hermes (OMH) is a comprehensive, open-source plugin suite and orchestration layer for the Hermes Agent, an AI-powered coding assistant. It is a technical middleware that provides intelligent routing, long-term agentic memory, and optimized workflow management.
2. Core Value Proposition: It exists to solve the operational complexity of using Hermes Agent professionally by providing a unified, configurable system for model pooling, skill execution, and workflow orchestration. Its primary value is maximizing developer efficiency through intelligent routing, executor-neutral contracts, and review-first memory, without ever patching the core Hermes Agent.

Main Features

1. Intelligent Model Routing: OMH introduces a declarative, category-based routing system. It allows users to define ordered candidate chains of AI model families (e.g., GPT, Claude, Gemini) for nine distinct work categories (e.g., ultrabrain, architect, writing). The system resolves these chains against locally confirmed, reachable models at setup, skipping unavailable candidates gracefully. This enables model pooling and optimal utilization of paid AI subscriptions.
2. Executor-Neutral Workflows & The Maestro Lane: OMH decouples planning from execution. Its flagship workflows (prefixed ulw-*) prepare tasks and create handoffs. For coding, the ulw-maestro workflow orchestrates work for external executors like Claude Code or Codex via the Maestro coordinator. Maestro prepares the session and reports results but never executes code itself, enforcing a clear evidence boundary between planning and verified execution.
3. Four-Layer Agentic Memory System: OMH implements a structured, multi-tiered memory architecture for AI agents. L0 is owner-written context (e.g., SOUL.md). L1 is a capped, fail-loud core memory (MEMORY.md). L2 is a review-first, budgeted archival system (.omh/memory/). L3 is a zero-token-until-queried full message history using SQLite with FTS5 and vector hybrid search. This system prioritizes recall on prefetch and eviction on provable redundancy.
4. Capability Families & Skill Packages: Functionality is organized into 116 installable skills across seven human-readable capability families (Clarify and plan, Build with leverage, Research and learn, etc.). This modular approach allows users to understand and invoke capabilities like omh-code-review or omh-best-practice-research based on the job to be done, rather than underlying technical commands.

Problems Solved

1. Pain Point: Inefficient and manual management of multiple AI models and executors within a coding agent workflow, leading to suboptimal model selection, context loss across sessions, and unclear ownership between planning and execution phases.
2. Target Audience: Professional developers and engineering teams who use Hermes Agent as a core part of their development workflow. This includes full-stack developers, DevOps engineers, and technical leads who require reliable, auditable, and efficient AI-assisted coding with multiple AI provider subscriptions.
3. Use Cases: Clarifying ambiguous feature requests using the ulw-interview workflow; conducting source-backed technical research with ulw-research; orchestrating parallel coding work across multiple AI executors using ulw-work; ensuring code quality with adversarial QA via ulw-qa; and maintaining persistent project knowledge across agent sessions with the layered memory system.

Unique Advantages

1. Differentiation: Unlike simple Hermes Agent extensions or scripts, OMH is a full orchestration framework. It does not patch Hermes, preserving stability. It is executor-neutral, avoiding vendor lock-in for coding execution. Its evidence boundary philosophy clearly separates prepared plans from verified results, a distinction most tools blur.
2. Key Innovation: The combination of category-based model routing chains and the Maestro-based external handoff protocol. This allows declarative configuration of AI resources while cleanly separating the planning agent (Hermes) from specialized execution agents (e.g., Claude Code), coordinated through a neutral controller that enforces contract fulfillment and evidence reporting.

Frequently Asked Questions (FAQ)

1. Does Oh My Hermes modify or patch the Hermes Agent? No, Oh My Hermes is a standalone plugin suite and orchestration layer that operates alongside Hermes Agent. It never patches the core Hermes binary, interacting with it through its official interfaces and protocols to ensure stability and compatibility.
2. How does the model routing work if I don't have all the configured AI models? The OMH routing system is fault-tolerant. During the omh setup interview, you confirm which models are reachable. The routing chains then skip any unconfirmed or unavailable model candidates and proceed to the next eligible model in the chain for that work category. A lack of eligible candidates is recorded but does not block installation.
3. What is the "evidence boundary" in Oh My Hermes? The evidence boundary is a core architectural principle that labels the verification level of any claim or output. It distinguishes between a "plan" (not run), "code reported done" (executor claimed completion), and "test verified" (objective pass/fail gate met). This prevents the system from conflating an executor's report with an independently verified result.
4. Can I use Oh My Hermes with coding executors other than Claude Code? Yes, the system is designed to be executor-neutral. The ulw-maestro workflow and the underlying Maestro coordinator are built to hand off prepared work to any compatible executor that adheres to the contract protocol. Setup discovers available executors, and routing follows what is actually installed on the machine.
5. How does the agentic memory system prevent context overload or irrelevant data? OMH's four-layer memory uses strategic constraints: L1 memory has a strict token cap that fails loudly when full, forcing prioritization. The L2 archival system is "review-first," meaning entries are consolidated and indexed for efficient querying rather than being loaded raw. The L3 full history uses a hybrid search (BM25 + vector) to retrieve only relevant past messages on demand, keeping token usage at zero until queried.