Capability parity: Hermes gap analysis

A deep analysis of NousResearch/hermes-agent — how it handles agent isolation and inter-agent / inter-surface communication — and what Nexus must add to be as robust in features. This page is a target spec, not a commitment to a schedule; see Proposed tiers.

Two different shapes

Hermes is a single-user, self-improving personal agent that lives across chat platforms and runs commands in pluggable terminal backends. Nexus is a multi-agent autonomous delivery OS: a Kubernetes-native control plane where a team of runtime-defined agents takes goals → tasks → isolated runs, with an authoritative internal board projected to Taiga.

Many Hermes features map cleanly onto Nexus; some need re-shaping for a multi-agent, server-side world; a few are out of scope. Each item below is labelled accordingly.

Recently shipped (tool foundation)

The executable tool system is now in place: a self-describing, check-gated tool registry (nexus-tools); local tools (fs.*, shell.exec, grep.search, git with per-subcommand permission gating); an always-on hardline command firewall; secret redaction of all tool output; an agentic tool-calling loop for API backends; and a platform tool RPC over NATS so a confined pod can ask Core to memory.propose, memory.search, task.subtask, task.delegate, or board.comment. CLI backends reach these platform tools via an nexus-mcp MCP server the runner launches for them, and API backends additionally get a local execute_code tool. Nexus is also an MCP client: an agent's declared mcp_servers (stdio) are discovered and merged into the run — namespaced for API backends, and written into the CLI's own MCP config for CLI backends. This closes item 8 and part of items 2, 5, 7, and 12 below — remaining gaps are noted inline.

Recently shipped (safety + hub polish — items 2, 4, 5, 7, 13, 15)

The remaining "shipped-foundation" gaps are now closed:

• Command firewall (2) — three tiers: hardline blocklist, firewall::suspicious pattern detection, and an optional auxiliary-LLM classifier (NEXUS_FIREWALL_SMART=1, fail-open) gating both shell.exec and execute_code.
• Input-trust scanning at prompt-entry (4) — the runner scans SOUL, skills, recalled memory, and the task text with nexus-domain::scan and prepends a hardening notice when content is flagged (non-blocking).
• Per-skill credential scoping (5) — skills declare required_environment_variables / required_credential_files; child processes get secret-shaped env vars stripped except the allow-listed ones.
• In-run tool RPC (7) — a per-run Unix-socket tool server lets execute_code / shell.exec scripts call any run tool via the nexus-tool helper.
• Skill hub (13) — import now records trust levels, computes a content hash for GET /v1/skills/{id}/drift detection, and supports bundles.
• User/project modeling (15) — reusable UserProfile documents (/v1/profiles) attach to projects by slug and inject into every run.

Recently shipped (learning loop — Tier C)

The learning loop (items 12–16) is now implemented, keeping Nexus's human-in-the-loop safety while gaining Hermes's procedural write-back:

• Agent-authored skills (12) — skill.propose captures a discovered procedure as a SKILL.md into the draft review queue (input-trust scanned first), versioned per slug; POST /v1/skills/{id}/approve activates it. Progressive disclosure via skill.list → skill.view keeps prompts lean.
• Skill hub + scan (13) — POST /v1/skills/import pulls a skill from a URL (GitHub blob URLs auto-rewritten to raw, with an SSRF host guard) or inline content, parses frontmatter, scans it, and stores it as a draft version.
• Run/session search (14) — a summary text index plus the run.search tool and GET /v1/runs?q= let an agent (and operators) recall past runs.
• User/project modeling (15) — Project.profile is budgeted context prepended to every run's SOUL; editable via GET/POST/PATCH /v1/projects.
• Trajectory export (16) — the agentic loop records a structured tool-call trajectory, persisted on the run (as BSON, not a stringified blob) and exported via GET /v1/runs/{id}/trajectory.

The shared input-trust content scan (nexus-domain::scan) added here also seeds item 4. Remaining learning-loop polish: external skill trust levels / drift detection / bundles (rest of 13) and pluggable user modeling (15).

1. Hermes at a glance

One platform-agnostic core (AIAgent) is driven by several entry points — CLI/TUI, messaging gateway, ACP (IDE), batch runner, API server, Python library — and calls out to a self-registering tool registry (40+ tools organized into toolsets) that executes against pluggable backends (six terminal backends — local, Docker, SSH, Singularity, Modal, Daytona — plus browser, web, and dynamic MCP). State is SQLite + FTS5. The differentiator is a closed learning loop: agent-curated memory, autonomous skill creation, session search, and trajectory capture.

CLI/TUI · Gateway(Telegram/Discord/Slack/WhatsApp/Signal/Email) · ACP(IDE) · Batch · API · Library
                         │
                    AIAgent core  ── prompt tiers · provider resolve · tool dispatch · compression
                         │
   tool registry (check_fn-gated) ── terminal/browser/web/MCP/file/memory/delegate/cron…
                         │
   SQLite + FTS5 (sessions, lineage)   ·   skills/ memory/ (learning loop)

2. Agent isolation — how Hermes does it

Mechanism	Detail	Nexus today
Pluggable terminal backends	local, docker, ssh, singularity, modal, daytona. Same tool API; backend chosen by config.	One backend: a Kubernetes Job. Strong, but not pluggable.
Persistent sandbox semantics	The Docker backend is one long-lived container per process; cd, pip install, and /workspace files persist across tool calls, /new, and subagents — a sandbox VM, not a fresh container per command.	Each run is a fresh, ephemeral pod. No cross-run/cross-agent persistent workspace.
Container hardening	--cap-drop ALL (+ minimal re-add), no-new-privileges, --pids-limit 256, size-limited tmpfs for /tmp,/var/tmp,/run, read-only root, resource caps (cpu/mem/disk).	Comparable: non-root, drop ALL caps, readOnlyRootFilesystem, seccomp RuntimeDefault, no SA token, TTL cleanup, NetworkPolicy. Nexus is at parity or ahead here.
Approval as boundary	Dangerous-command detection (tools/approval.py) with manual/smart/off modes, per-session + permanent allowlist, and a hardline blocklist that no flag can override. Skipped inside containers (the container is the boundary).	Permission flags + human approval gates exist, and shell.exec now enforces an always-on hardline blocklist (rm -rf /, fork bombs, mkfs, curl|sh, …). Still missing: a smart risk classifier and per-session allowlist.
Pre-exec content scanning	A content scanner (tirith) inspects command content for homograph URLs, pipe-to-interpreter, and terminal-injection before exec.	None.
Egress / SSRF / website policy	SSRF guard on all URL tools (blocks RFC1918, loopback, link-local, cloud metadata, CGNAT), configurable website blocklist, fail-closed DNS, redirect re-validation.	NetworkPolicy restricts egress to DNS/NATS/443. No application-layer SSRF/domain policy inside the runner.
Secret/credential scoping	execute_code/terminal strip *KEY/TOKEN/SECRET* from child env by default; skills opt specific vars/files back in (required_environment_variables, required_credential_files) — Docker bind-mounts creds read-only. MCP subprocesses get a tiny safe env only; tool errors are credential-redacted.	LLM keys via envFrom (optional secret); CLI creds via PVC; the runner redacts the git token from clone output, and the tool registry now redacts secret-shaped env values from all tool output. Still missing: per-skill env allow-listing.
Context-file injection scanning	AGENTS.md/SOUL.md/.cursorrules scanned for prompt injection (ignore-prior-instructions, hidden HTML, secret reads, invisible Unicode) before entering the system prompt.	SOUL/skills/memory are operator-authored; no injection scanning before they enter a prompt.

Takeaway: Nexus's container isolation is already strong (arguably stronger, being K8s-native). The gaps are (a) backend pluggability (ssh/cloud-sandbox for cheaper/persistent runs), (b) a command/content firewall at the runner (pattern + smart + hardline + tirith-style scanning), (c) application-layer egress policy (SSRF/domain blocklist), and (d) input-trust scanning of SOUL/skill/memory/context before prompting.

3. Communication — how Hermes does it

3.1 Entry points → one core

A single AIAgent serves every surface; platform differences live only in the entry point. The gateway is one long-running process hosting adapters for Telegram, Discord, Slack, WhatsApp, Signal, and Email (plus Home Assistant) with unified session routing, user authorization (allowlists + DM pairing codes), slash-command dispatch, a hook system, cron ticking, and background maintenance.

3.2 Tool dispatch & "tools as RPC"

Tools self-register at import (registry.register) and are gated by check_fn (availability/credentials). The model emits a tool_call → handle_function_call → optional plugin pre-hook → registry.dispatch → handler → post-hook. Crucially, execute_code lets the agent write a script that calls other tools via RPC, collapsing multi-step pipelines into a single zero-context-cost turn.

3.3 Subagent delegation

delegate_task is an agent-loop-level tool (intercepted before registry dispatch, like todo/memory/session_search). It spawns an isolated subagent for a parallel workstream that shares the same persistent container (so the parent and children see the same /workspace). This is how Hermes "delegates and parallelizes".

3.4 IDE & external protocols

• ACP adapter exposes Hermes as an editor-native agent over stdio/JSON-RPC (VS Code, Zed, JetBrains); an ACP registry advertises capabilities.
• MCP client (tools/mcp_tool.py) dynamically discovers and registers tools from any MCP server, with filtered env + error redaction.

3.5 Persistence, isolation & recall of conversations

SQLite + FTS5 with session lineage (parent/child across compressions), per-platform isolation (sessions can't read each other), atomic writes. The session_search tool gives the agent free, fast recall of its own past conversations.

3.6 Plugins & hooks

Three discovery sources (user / project / pip entry points). Plugins register tools, hooks, and CLI commands; two single-select specialized types — memory providers and context engines — are swappable implementations.

Communication mechanism	Nexus today	Gap
Authoritative core + event bus	✅ Core is the only mutator; NATS JetStream; runner→events; worker reconciles.	— (Nexus's server-side equivalent is solid.)
Multi-surface gateway	⚠️ Telegram only + Admin UI.	Discord/Slack/WhatsApp/Signal/Email; DM pairing; unified session routing.
Agent-initiated subagent delegation	⚠️ Worker does team routing / dependency-aware leasing, but an agent cannot spawn its own child sub-runs that share a workspace.	A delegate capability + shared-workspace semantics (PVC or persistent sandbox).
Tools-as-RPC from code	❌ Runner runs one backend; no in-run tool-RPC bus the agent can script against.	An in-run tool RPC surface (execute_code calling Nexus tools).
MCP client	✅ Per-agent mcp_servers (stdio) discovered + merged into the run — namespaced <server>.<tool> for API backends, written into the CLI's own MCP config for CLI backends.	— (remote http/SSE servers intentionally out of scope for confined pods.)
IDE protocol (ACP)	❌ None.	Optional ACP/MCP server exposing Nexus agents to editors.
Session storage + full-text recall	⚠️ Runs/history in Mongo; no agent-facing session search.	FTS over past runs/conversations as a retrieval tool.
Plugins / hooks	❌ Fixed pipeline.	Lifecycle hooks (pre/post tool, pre/post run) + provider plugins (board, memory, context engine already trait-seamed).

4. The learning loop — how Hermes does it

This is Hermes's headline feature and Nexus's biggest functional gap.

Capability	Hermes	Nexus today	Gap
Curated long-term memory	MEMORY.md + USER.md, hard char budgets, agent self-manages (add/replace/remove), frozen-at-session-start snapshot for prefix-cache stability, duplicate + injection scanning.	Memory in Mongo + Qdrant; human-approval queue before shared writes; summarizer compaction.	Nexus is safer (approval gates) but lacks agent-managed working memory and user modeling as first-class, budgeted stores.
Autonomous skill creation	skill_manage (create/patch/edit/delete + supporting files): after a complex task (5+ tool calls), on correction, or on discovering a workflow, the agent writes a reusable SKILL.md — procedural memory write-back.	Skills are operator-authored, versioned, human-approved.	Agents can't propose/author skills from experience (even into a review queue).
Skill registries / hub	Hub with many sources (official, skills.sh, well-known endpoints, GitHub taps, URL), security scanning, trust levels, update/drift detection, bundles, progressive disclosure (list→view). agentskills.io-compatible.	Local Mongo skill registry only.	External skill sourcing + security scan + progressive disclosure + bundles.
Session search	FTS5 recall tool over all sessions.	—	A retrieval tool over historical runs.
User modeling	Honcho dialectic user modeling + pluggable memory providers.	—	Optional pluggable user/project modeling.
Trajectory capture	Batch trajectory generation + trajectory compression for training next-gen tool-calling models.	nexus-agent-runtime has compression for context, not training export.	Trajectory export pipeline for eval/training.

5. Other notable Hermes features

Feature	Nexus today	Gap / fit
Cron / scheduled automations	Worker has timers for internal loops; no user-defined scheduled agent jobs.	First-class scheduled goals/tasks with board + delivery (natural-language "nightly audit"). High fit for autonomous projects.
Provider breadth + hot-swap	Per-agent + system LLM settings (API & CLI), editable in Admin UI.	Add an auxiliary/cheap model lane (summaries, risk classification, vision) and broader provider catalog.
Background process management	Runner runs to completion; no managed long-running processes.	process(list/poll/wait/log/kill) semantics for long tasks (test suites, servers) inside a run.
Supply-chain advisory + lazy deps	Images are pre-baked.	Advisory scan of agent images / installed packages; report on the Logs/Status page.
Media delivery niceties	Telegram text only.	Auto-deliver artifacts (diffs, screenshots, charts) to the chat surface.
Profiles	Single control plane.	Multi-tenant/project isolation (HERMES_HOME-style) maps to Nexus projects/namespaces.

6. Target capability set for Nexus

Grouped so each can be specced and scheduled independently. Each note is written to fit Nexus's Mongo/NATS/K8s/board architecture.

A. Runner isolation & safety firewall

1. Pluggable run backends behind the existing AgentRuntime trait: KubernetesAgentRuntime (today), plus SshAgentRuntime and a cloud-sandbox runtime (Modal/Daytona-style) for cheap, persistent, or burstable workspaces. Backend selectable per agent/project in the Admin UI.
2. Command firewall in the runner: ✅ shipped. Three tiers now: the always-on hardline blocklist (no override), pattern detection (firewall::suspicious — sudo, package installs, credential reads, host/cluster tooling, recursive perm changes, network fetches), and an optional auxiliary-LLM risk classifier (NEXUS_FIREWALL_SMART=1) that gives a cheap ALLOW/BLOCK verdict on flagged commands, failing open on model error. Gates both shell.exec and execute_code.
3. Application-layer egress policy: SSRF guard + domain allow/blocklist for any HTTP/browse tool the runner gains, fail-closed. (Skill-import already has an SSRF host guard.)
4. Input-trust scanning: ✅ shipped. The runner scans everything entering the prompt — SOUL, skills, recalled memory, the task text — with nexus-domain::scan at prompt-entry. Findings are logged and, when anything is flagged, a hardening notice is prepended telling the model to treat retrieved content as data, not instructions. Non-blocking by design.
5. Per-skill credential scoping: ✅ shipped. Skills declare required_environment_variables / required_credential_files; the worker unions them into the run, and shell.exec/execute_code strip every secret-shaped env var (*KEY/TOKEN/SECRET*) from child processes except the allow-listed ones. Tool output is still secret-redacted on the way back.

B. Communication & orchestration

6. Agent-initiated delegation: a delegate capability letting an agent spawn child sub-runs (within its permission envelope) that share a workspace (a run-scoped PVC or persistent sandbox), with results streamed back over NATS. Extends today's worker-side team routing to agent-driven fan-out. Groundwork exists: agents already check out multiple repositories side-by-side into a single run workspace, so the multi-repo working set a delegation would share is already modeled.
7. In-run tool RPC (execute_code-style): ✅ shipped. In addition to the platform tool RPC over NATS and the execute_code local tool, the runner now hosts a per-run Unix-socket tool server for the lifetime of the agentic loop. Scripts call the nexus-tool helper (e.g. nexus-tool fs.read '{"path":"x"}') to invoke any of the run's tools — local or platform — through the same registry, permissions, firewall, env-scoping, and redaction, chaining several tools in one turn without a model round-trip.
8. MCP client/server: ✅ shipped. Both directions are now wired. nexus-mcp is an MCP server exposing Nexus's platform tools to CLI backends (Claude Code, Codex). The client direction lets each agent declare mcp_servers (stdio): API backends discover their tools (initialize/tools/list) and merge them namespaced (<server>.<tool>) into the run; CLI backends get the same servers written into their own MCP config. Tool output is redacted and the pod firewall still applies. Remaining: remote http/SSE servers (intentionally excluded for confined, egress-restricted pods).
9. Multi-surface gateway: generalize nexus-telegram into a gateway hosting multiple adapters (Discord/Slack first), with DM pairing and unified session routing — all still funneling to POST /v1/goals.
10. Lifecycle hooks / plugins: pre/post-tool and pre/post-run hooks (audit, policy, notifications); formalize the already-trait-seamed providers (board, memory, context engine) as a plugin surface.
11. Optional ACP/MCP server: expose Nexus agents to IDEs and other MCP hosts.

C. Learning loop (largest gap)

12. Agent-authored skills — ✅ shipped. skill.propose routes a discovered procedure into the draft review queue (scanned, versioned per slug); skill.list→skill.view give progressive disclosure; POST /v1/skills/{id}/approve activates. Mirrors the memory.propose pattern, keeping the human-in-loop gate.
13. Skill registry/hub + security scan — ✅ shipped (core). POST /v1/skills/import pulls from a URL (GitHub blob→raw, SSRF-guarded) or inline content, parses frontmatter, scans, and stores a draft version. Now also: trust levels (official/community/unverified), content-hash drift detection (GET /v1/skills/{id}/drift re-fetches and compares), and bundles ({ "bundle": [ … ] } imports many at once with per-entry errors). Remaining: agentskills.io-format catalogue browsing.
14. Session/run search — ✅ shipped. summary text index + the run.search tool and GET /v1/runs?q= give the agent and operators FTS over HISTORY.
15. User/project modeling — ✅ shipped. Project.profile is budgeted context injected into every run's SOUL, plus a pluggable reusable-profile layer: standalone UserProfile documents (user/operator/team + prose content + structured attributes) managed via GET/POST/PATCH/DELETE /v1/profiles and attached to a project by slug (Project.profile_refs). Each attached profile is injected into runs alongside the inline profile.
16. Trajectory export — ✅ shipped. The agentic loop records a structured tool-call trajectory, persisted on the run (BSON) and exported via GET /v1/runs/{id}/trajectory. Compression for training reuses nexus-agent-runtime (future).

D. Productivity & ops

17. Scheduled automations (cron): user-defined recurring goals/tasks with board reflection and delivery to a chat surface.
18. Auxiliary model lane: cheap model for summaries / risk classification / vision, configured alongside planner/summarizer settings.
19. Background process management inside a run.
20. Artifact delivery to chat surfaces (diffs, screenshots, charts).

7. Proposed tiers

Ordering only — timing to be decided (per your request). Picked to maximize "autonomous projects handled by a team of agents" with least risk first.

Tier	Items	Rationale
P0 — safety & loop foundations	2 (command firewall), 4 (input-trust scan — scan engine shipped), 12 (agent-authored skills — ✅), 14 (run search — ✅)	Closes the biggest safety and learning gaps without new infra.
P1 — orchestration depth	6 (delegation + shared workspace), 8 (MCP client — ✅), 17 (cron), 18 (aux model)	Unlocks real multi-agent autonomy + scheduled work.
P2 — reach & backends	1 (pluggable backends), 9 (multi-surface gateway), 13 (skill hub), 7 (tool RPC)	Broadens where/how Nexus runs and sources capability.
P3 — ecosystem	10 (hooks/plugins), 11 (ACP/MCP server), 15 (user modeling), 16 (trajectory export), 3/5/19/20	Long-tail polish, research, and integrations.

8. Out of scope / deliberately different

• Personal-assistant surface area (voice memos, Home Assistant, Spotify, TTS bubbles) — Hermes is a personal agent; Nexus is a delivery platform. Adopt only the delivery niceties (artifacts to chat).
• Local-laptop lifestyle (hermes TUI as primary UX) — Nexus's primary UX is the Admin UI + chat gateways; a TUI is not a goal.
• Single-process model — Nexus stays distributed (Core/worker/runner) for multi-agent scale and K8s isolation; we borrow Hermes's features, not its single-binary shape.

Related

• Architecture · Security & permissions
• Concepts: skills · Memory
• Roadmap