Upstream Subsystem Inventory

7. Upstream Subsystem Inventory

The complete picture of what Gormes must absorb to retire the Python hermes-agent runtime. Each row is one upstream module or capability, mapped to its target phase. This inventory is the source of truth for “what’s left” — when a subsystem is shipped in Go, mark it ✅ and link the spec.

Gateway platforms (24 connectors — 23 unshipped)

Operational layer (cross-cutting, mostly Phase 2.D–2.F)

Memory + state (Phase 3 — 3.A–3.D shipped; 3.E pending)

Upstream splits memory across three stores that Gormes compresses into two:

• hermes_state.py — SessionDB (SQLite + FTS5) holds every session’s message history, model config, parent-session chains for compression splits, and source tagging (cli, telegram, etc.). Gormes Phase 2.C uses bbolt for (platform, chat_id) → session_id mapping; Phase 3.A’s SqliteStore holds turns + FTS5. Together they cover SessionDB’s responsibilities, but the parent-session chains and cross-source search need explicit 3.E work.
• agent/memory_manager.py — MemoryManager owns the entity graph + USER.md mirror.
• agent/memory_provider.py — MemoryProvider (ABC) owns recall-time seed selection + fence assembly.

Cross-cutting registries (used by multiple phases)

These are single source-of-truth registries that drive multiple downstream consumers. A Go port must preserve “one registry, many consumers” so that adding a slash command / tool / skill lights up everywhere automatically.

Agent orchestration core (Phase 4 — the thing Phase 4 ultimately replaces)

The biggest single file upstream is run_agent.py at 12,113 lines — the AIAgent orchestrator that owns the full agent loop. agent/ is its partial decomposition. Phase 4 is the gradual absorption of this orchestrator into native Go; Phases 4.A–4.H each carve off a responsibility.

Brain (Phase 4 — sub-phases 4.A–4.H)

Tools surface (Phase 5 — 61 upstream tool files)

TUI + Interactive Surfaces (Phase 5.Q — new)

Upstream ships a dedicated tui_gateway/ — a 3,094-line Python TUI server that streams live agent state over SSE to the Ink-based Node TUI. Gormes has its own Bubble Tea TUI (shipped Phase 1), but the gateway-side streaming surface is not yet ported.

CLI + packaging (Phase 5.O–5.P)

The upstream hermes_cli/ has 49 Python files. Grouped by capability:

Out of scope for the runtime port

These upstream paths exist but are not part of the runtime that Gormes must absorb. Listed for completeness so future contributors don’t mistake them for missing work:

• agent/, cli.py, run_agent.py, gateway/, hermes/, hermes_cli/, tools/, cron/, acp_adapter/, acp_registry/, plugins/, tui_gateway/, environments/ — runtime paths covered by the phases above. Listed here so future contributors don’t re-add them to “out of scope” by accident.
• tests/ — Python tests are not ported; Gormes has its own Go test suite per spec.
• docs/ (upstream documentation), assets/, optional-skills/, skills/ — content corpus; mirrored separately by docs.gormes.ai (Phase 1.5) and skill packs. Skill-pack categories in optional-skills/ (autonomous-ai-agents, blockchain, communication, creative, devops, email, health, mcp, migration, …) track Hermes’ skills/ categories but as opt-in packages.
• ui-tui/, web/, website/ — Node.js/TypeScript frontends. Gormes has its own Go cmd/gormes/tui Bubble Tea UI (shipped Phase 1) and www.gormes.ai/ Go-templated landing page. Upstream’s React/TS frontends are not part of the Go runtime port.
• tinker-atropos/ — upstream research sandbox (currently empty); no runtime content.
• datagen-config-examples/ — RL/data-generation research examples; deferred to 5.M.
• scripts/ (selectively) — scripts/{install.sh,install.cmd,install.ps1,release.py,build_skills_index.py} ARE ported in 5.P; scripts/{contributor_audit.py,discord-voice-doctor.py,kill_modal.sh,lib/} remain upstream-only contributor tooling.
• plans/ (upstream plans directory), package.json, package-lock.json, flake.lock, flake.nix — build/packaging metadata; partially mirrored at Phase 5.P.
• AGENTS.md, CLAUDE.md, CONTRIBUTING.md, GOOD-PRACTICES.md, hermes-already-has-routines.md — upstream contributor docs; not runtime.

Runtime contracts (config schema, env var surface, on-disk state)

Equally important as the code inventory above is the runtime contract surface — the shape of configuration, environment, and on-disk state that a Hermes user has built muscle memory around. A Gormes binary that ignores these contracts is technically a port but operationally a foreign object.

Configuration files

Environment variable surface

Upstream honors ~170 environment variables across three layers. Gormes must re-expose the operator-facing ones without breaking muscle memory.

On-disk state layout

Upstream uses ~/.hermes/ as the state root (overridable via HERMES_HOME). Gormes uses ${XDG_DATA_HOME}/gormes/ (default ~/.local/share/gormes/) and ${XDG_CONFIG_HOME}/gormes/ (default ~/.config/gormes/).

Runtime contract implications for Gormes

1. HERMES_HOME vs XDG_DATA_HOME: Gormes MUST respect XDG by default, but should honor HERMES_HOME as a migration alias so operators switching over don’t lose state.
2. .env dotenv support: Gormes currently expects env vars in the shell. Operators who have a working ~/.hermes/.env will not want to re-key ~170 variables. Phase 5.O should add a dotenv loader that reads ~/.hermes/.env and ~/.config/gormes/.env at startup.
3. Config migration: Upstream _config_version key + migration helpers. Gormes must add a similar versioning scheme before the config schema stabilizes — otherwise TOML-key renames break users.
4. $EDITOR for hermes config edit: operator UX affordance; parity expected at 5.O.
5. Platform-specific home channel pattern: EVERY platform supports <PLATFORM>_HOME_CHANNEL + <PLATFORM>_HOME_CHANNEL_NAME. Gormes should generalize rather than re-implement per-platform.

Inventory cadence

Re-run the upstream survey when a major Hermes release lands, when a new platform connector is added upstream, or when a Gormes phase ships and we need to mark its rows ✅. The survey is mechanical:

1. find upstream root -name "*.py" -newer last-survey-date for new Python files
2. ls gateway/platforms/*.py for new platform connectors
3. ls plugins/memory/ for new memory backends (currently 8)
4. ls tools/environments/*.py for new sandbox backends (currently 10 including ssh.py)
5. ls hermes_cli/*.py for new CLI subcommands (currently 49)
6. ls environments/tool_call_parsers/*.py for new per-model parsers (currently 9)
7. wc -l run_agent.py cli.py tui_gateway/server.py to track orchestrator size growth
8. grep -oE '^class ' agent/*.py tools/*.py gateway/*.py | sort -u | wc -l — class count drift signals new subsystem surface (round-3 audit found 30 classes not previously mapped)
9. grep -oE '"[A-Z_]{4,}":' hermes_cli/config.py | sort -u | wc -l — current: 117 top-level config keys
10. grep -oE 'HERMES_[A-Z_]+' hermes_cli/*.py agent/*.py | sort -u | wc -l — current: ~47 HERMES_* env vars
11. grep -oE 'get_hermes_home\(\) / "[a-z_./\-]+"' agent/*.py hermes_cli/*.py gateway/*.py | sort -u — current: 28 known paths/files under ~/.hermes/ (round-4 audit)

The survey from 2026-04-20 caught 42 items previously under-specified:

• Round 1 (spec-level): Phase 3.D semantic fusion ship criterion, Phase 3.E ledger (7 subphases).
• Round 2 (file-level, 12 finds): run_agent.py (12,113 lines), cli.py (10,570 lines), tui_gateway/server.py (2,931 lines), 9 per-model tool-call parsers, 8 third-party memory plugins, SSH sandbox, SkillSources, TUI skin engine, install scripts, hermes_cli/ expansion from ~15 to 49 files.
• Round 3 (class-level, 30 finds): Slash command registry cross-cutting concern, tool registry orchestrator, toolset definitions, HomeChannel / DeliveryRouter / GatewayStreamConsumer / SessionStore, webhook subscription system, iteration budget, 3 new AuxiliaryClient classes (Anthropic + Codex, not just xAI), billing / cost / failover / metadata types, 7 SkillSource subclasses, AudioRecorder + TermuxAudioRecorder, 15+ file-operation classes, MCP OAuth / Sampling / FAL sync, GitHubAuth + HermesTokenStorage.
• Round 4 (contract-level, this pass): 117 config keys, ~170 env vars across 4 layers (HERMES_*, provider keys, platform credentials, gateway-level), 28 state-directory entries under ~/.hermes/, config migration system (_config_version), XDG vs HERMES_HOME reconciliation, dotenv support gap, cron output filesystem mirror (~/.hermes/cron/).

Next survey: when upstream tags a new release, OR when any single round’s find count exceeds 5 new subsystems.