@pmatrix/hermes-monitor

Runtime safety governance for Nous Research Hermes Agent — LLM observation + active intervention + multi-platform gateway coverage.

Blocks dangerous tool calls before execution, observes LLM call routing across 5+ providers, detects credential leaks, and continuously measures agent risk with live Trust Grade (A–E).

Requires a P-MATRIX account, API key, and Hermes Agent v0.13.0+ (Plugin hook system "complete", 2026-05-07).

What it does

Core Protection

• Safety Gate — Intercepts high-risk tool calls (bash_tool, web_search, image_gen, tts, mcp__*) before execution. Blocks based on current risk level R(t).
• LLM Call Observation — Pre/post LLM call hooks capture provider routing (OpenAI / Anthropic / OpenRouter / NVIDIA NIM / Hugging Face / custom), model selection, token usage, duration. 2nd SDK with LLM observation (after Gemini CLI Monitor).
• Credential Protection — Detects and blocks 16 types of API keys and secrets in user prompts before they reach the agent (via pre_llm_call hook).
• Kill Switch — Automatically halts the agent when R(t) ≥ 0.75. Manually via ~/.pmatrix/HALT (shared across 6 P-MATRIX SDKs — OpenClaw / Claude Code / Cursor / Gemini / Codex / Hermes).

Hermes-specific Features

• Multi-provider routing tracking — Per-provider R(t) baseline + auxiliary role separation (compression / vision / session_search / title_generation).
• Multi-platform gateway coverage — Single hook surface across 20 platform adapters (Telegram / Discord / Slack / WhatsApp / Signal / CLI / ...).
• Closed learning loop drift detection (v0.1 = observation only) — Static baseline + γ.3 anomaly z-score (Hermes-specific IMMUNE_Z_THRESHOLD 4.0/5.0 권고). Skill handling layer = v0.2+ Python plugin add-on.
• Per-platform session lineage — Parent/child tracking across compressions + per-platform isolation.

Behavioral Intelligence

• Tool Failure Tracking — Records each tool failure and applies a stability nudge.
• Live Grade — Streams 4-axis safety signals and displays Trust Grade (A–E) in real time.

Hooks (6)

| Hook | Role | Block? | |:---|:---|:---| | on_session_start | Session bootstrap + platform identification + lineage parent | — | | pre_llm_call | LLM 호출 전 — provider/model 검증 + credential scan (16 patterns) | exit 2 | | pre_tool_call | Safety Gate core (R(t) × tool risk + meta-control) | JSON deny | | post_tool_call | R(t) update + AP-2 tool result analysis | — | | post_llm_call | LLM 호출 후 — 토큰 + 비용 + duration capture | — | | on_session_end | session_report + breach flush + lineage child | — |

Requirements

| Requirement | Version | |:---|:---| | Node.js | >= 18 | | Hermes Agent | v0.13.0+ (Plugin hook system "complete", 2026-05-07) | | P-MATRIX server | v1.0.0+ | | Platform | macOS / Linux / Windows |

Install

npm install -g @pmatrix/hermes-monitor
pmatrix-hermes setup --agent-id <YOUR_AGENT_ID>
export PMATRIX_API_KEY=<YOUR_API_KEY>

Setup writes hook configuration to ~/.hermes/hooks.yaml (or <repo>/.hermes/hooks.yaml with --repo).

Status

v0.1.0 — Phase R-8 M2 PoC (2026-05-12)

• Shell hook primary (TypeScript SDK, ~60-65% code reuse from codex-monitor + claude-code-monitor)
• v0.2+ optional Python plugin add-on (PyPI pmatrix-hermes-plugin) for Skills Hub + Honcho drift handling

See docs/active/monitors/6_PMATRIX_HERMES_MONITOR_v1_0_PRODUCT_SPEC.md for full architectural specification.

License

Apache-2.0 © P-MATRIX