aryanil89/smh-hermes

Purpose and Runtime Topology

Hermes is an on-device AI operations layer for a Snapdragon X Elite laptop. It combines infrastructure telemetry, UNO Q physical sensors, and access state into incident assessments, proactive alerts, and a local operations wall. Core reasoning is Qwen3-4B served by Qualcomm GenieX on the laptop Hexagon NPU; Hermes Agent invokes local MCP servers over stdio. Main operational entry points are mcp-tools/src/dashboard/server.ts, MCP server launchers in mcp-tools/src/servers/, and the board application at uno-q/hermes-sensor-logger/python/main.py.

Telemetry and Sensor Ingestion

The UNO Q produces climate ticks, button/ToF events, and board-local SmolLM2 activity inferences. Its app writes events locally and pushes a log to the laptop over WiFi plus Tailscale; USB is provisioning only. The laptop environmental adapter reads that file, applies freshness checks and labeled mock fallback, forming the boundary between physical telemetry and application logic.

Paths: uno-q/hermes-sensor-logger/python/main.py, uno-q/hermes-sensor-logger/push_sensor_log.sh, mcp-tools/src/environmental/file-source.ts, mcp-tools/src/environmental/unoq-client.ts.

MCP Telemetry and Deterministic Assessment

Five stdio MCP servers expose network, storage, compute, environmental, and a one-call assessment endpoint. Network/storage and most compute data are simulated; host compute can use local OS metrics and preserves real versus mock provenance. The assessment service collects the telemetry families, computes reproducible risk/confidence, and appends UNO activity only after scoring so it cannot change the verdict.

Paths: mcp-tools/src/servers/network-server.ts, mcp-tools/src/servers/environmental-server.ts, mcp-tools/src/servers/assessment-server.ts, mcp-tools/src/assess/assess.ts.

Alerting and On-Site Suppression

A persistent watchdog evaluates environmental state every 15 seconds without calling the LLM. It persists alert state, edge-triggers alert/recovery delivery, and routes messages through a Telegram adapter when configured. Suppression is coupled to fresh access state: an expected enrolled responder can defer normal pages, while escalation or stale access state fails open and pages.

Paths: mcp-tools/src/alert-skill/watch-loop.ts, mcp-tools/src/alert-skill/tick.ts, mcp-tools/src/alert-skill/suppress.ts, mcp-tools/src/common/telegram.ts.

Access-Control Decision Loop

The dashboard server hosts both a read-only wall and the phone approval terminal. Presence events open challenges; captured images go through a pluggable identity ladder, then a decision matrix handles authorization, tailgating, anti-passback, and human approval/denial. Face CPU matching uses external Python/ONNX tooling; unmatched captures remain memory-only, while enrollment stores embeddings/audit state locally.

Paths: mcp-tools/src/access/sentry.ts, mcp-tools/src/access/identify.ts, mcp-tools/src/access/decide.ts, mcp-tools/src/dashboard/server.ts.

Human Interfaces and Messaging Boundaries

The local dashboard presents shared sensor, infrastructure, access, and alert state, and reads Hermes transcript data read-only. /phone.html is the sole human write surface for access decisions. Telegram is the only intentional cloud relay and carries messages, not inference or tool execution. Gateway hooks add early receipts and a degraded failover path when GenieX is unavailable.

Paths: mcp-tools/public/index.html, mcp-tools/public/phone.html, hermes-hooks/ack/handler.py, hermes-hooks/failover/handler.py.

Compute Tiers and Operations

Laptop inference requires Windows ARM64, Node 22+ for MCP tooling, Hermes Agent, and GenieX’s OpenAI-compatible localhost endpoint. The UNO Q independently runs SmolLM2-135M for pre-correlation. A Galaxy S25 Ultra runs a one-shot ADB-backed Qwen failover, explicitly degraded and tool-less. NPU profiling and serving/energy benchmarks are separate evidence harnesses, not runtime dependencies.

Paths: scripts/geniex-supervisor.ps1, llm-serving-bench/phone/run.sh, bench/bench.py, llm-serving-bench/bench.py.