Glossary

Relevant source files

• .env.example
• AGENTS.md
• CONTRIBUTING.md
• README.md
• README.ur-pk.md
• README.zh-CN.md
• agent/agent_init.py
• agent/agent_runtime_helpers.py
• agent/auxiliary_client.py
• agent/chat_completion_helpers.py
• agent/context_compressor.py
• agent/conversation_compression.py
• agent/conversation_loop.py
• agent/replay_cleanup.py
• agent/tool_executor.py
• agent/tool_result_classification.py
• agent/turn_context.py
• batch_runner.py
• cli-config.yaml.example
• cli.py
• contributors/emails/lanyusea@gmail.com
• contributors/emails/miniadmin@skshim-mini.local
• contributors/emails/tars@users.noreply.github.com
• cron/executions.py
• cron/jobs.py
• cron/lifecycle_guard.py
• cron/scheduler.py
• cron/scheduler_provider.py
• docs/session-lifecycle.md
• gateway/restart_loop_guard.py
• gateway/run.py
• gateway/session.py
• hermes_cli/auth.py
• hermes_cli/codex_models.py
• hermes_cli/commands.py
• hermes_cli/config.py
• hermes_cli/cron.py
• hermes_cli/main.py
• hermes_cli/models.py
• hermes_cli/nous_account.py
• hermes_cli/nous_subscription.py
• hermes_cli/runtime_provider.py
• hermes_cli/setup.py
• hermes_cli/subcommands/cron.py
• hermes_cli/tools_config.py
• hermes_state.py
• model_tools.py
• plugins/cron_providers/chronos/__init__.py
• run_agent.py
• tests/agent/test_auxiliary_client.py
• tests/agent/test_cjk_token_estimation.py
• tests/agent/test_compression_anti_thrash_persistence.py
• tests/agent/test_compression_concurrent_fork.py
• tests/agent/test_compressor_tool_call_budget.py
• tests/agent/test_context_compressor.py
• tests/agent/test_context_compressor_summary_continuity.py
• tests/agent/test_context_compressor_temporal_anchoring.py
• tests/agent/test_credential_pool_routing.py
• tests/agent/test_idle_compaction_lock_and_guards.py
• tests/agent/test_replay_cleanup.py
• tests/agent/test_resume_stale_active_task.py
• tests/agent/test_summary_prefix_semantics.py
• tests/agent/test_summary_prefix_tool_use.py
• tests/agent/test_tool_result_classification.py
• tests/agent/test_turn_context.py
• tests/cli/test_cli_interrupt_ack_race.py
• tests/cli/test_cli_shutdown_memory_messages.py
• tests/cron/test_cron_prompt_injection_skill.py
• tests/cron/test_cron_script.py
• tests/cron/test_execution_ledger.py
• tests/cron/test_jobs.py
• tests/cron/test_jobs_file_ownership.py
• tests/cron/test_scheduler.py
• tests/cron/test_scheduler_mcp_init.py
• tests/cron/test_scheduler_provider.py
• tests/gateway/test_approve_deny_commands.py
• tests/gateway/test_async_delegation_session_binding.py
• tests/gateway/test_auto_continue.py
• tests/gateway/test_clean_shutdown_marker.py
• tests/gateway/test_matrix_exec_approval.py
• tests/gateway/test_restart_resume_pending.py
• tests/gateway/test_session.py
• tests/gateway/test_session_reset_notify.py
• tests/gateway/test_session_store_runtime_stale_guard.py
• tests/gateway/test_shared_group_sender_prefix.py
• tests/gateway/test_stale_confirmation_expiry.py
• tests/gateway/test_yolo_command.py
• tests/hermes_cli/test_auth_codex_provider.py
• tests/hermes_cli/test_auth_codex_self_heal.py
• tests/hermes_cli/test_codex_cli_model_picker.py
• tests/hermes_cli/test_codex_models.py
• tests/hermes_cli/test_commands.py
• tests/hermes_cli/test_cron.py
• tests/hermes_cli/test_gateway_restart_loop.py
• tests/hermes_cli/test_image_gen_picker.py
• tests/hermes_cli/test_install_cua_driver.py
• tests/hermes_cli/test_model_validation.py
• tests/hermes_cli/test_nous_subscription.py
• tests/hermes_cli/test_runtime_provider_resolution.py
• tests/hermes_cli/test_setup.py
• tests/hermes_cli/test_setup_model_provider.py
• tests/hermes_cli/test_status_model_provider.py
• tests/hermes_cli/test_tools_config.py
• tests/hermes_cli/test_video_gen_picker.py
• tests/hermes_cli/test_windows_native_docs.py
• tests/run_agent/test_413_compression.py
• tests/run_agent/test_compression_feasibility.py
• tests/run_agent/test_compression_persistence.py
• tests/run_agent/test_credential_pool_interrupt.py
• tests/run_agent/test_identity_flush.py
• tests/run_agent/test_run_agent.py
• tests/test_batch_runner_checkpoint.py
• tests/test_hermes_state.py
• tests/test_hermes_state_compression_locks.py
• tests/test_model_tools.py
• tests/tools/test_approval.py
• tests/tools/test_approval_interrupt.py
• tests/tools/test_command_guards.py
• tests/tools/test_cron_approval_mode.py
• tests/tools/test_cronjob_tools.py
• tests/tools/test_daemon_pool.py
• tests/tools/test_execution_flag_detection.py
• tests/tools/test_hardline_blocklist.py
• tests/tools/test_tool_backend_helpers.py
• tests/tools/test_yolo_mode.py
• tools/__init__.py
• tools/approval.py
• tools/cronjob_tools.py
• tools/daemon_pool.py
• tools/tool_backend_helpers.py
• toolsets.py
• website/docs/developer-guide/contributing.md
• website/docs/developer-guide/creating-skills.md
• website/docs/developer-guide/provider-runtime.md
• website/docs/getting-started/installation.md
• website/docs/getting-started/quickstart.md
• website/docs/getting-started/updating.md
• website/docs/guides/use-mcp-with-hermes.md
• website/docs/integrations/providers.md
• website/docs/reference/cli-commands.md
• website/docs/reference/environment-variables.md
• website/docs/reference/faq.md
• website/docs/reference/slash-commands.md
• website/docs/user-guide/cli.md
• website/docs/user-guide/configuration.md
• website/docs/user-guide/features/cron.md
• website/docs/user-guide/features/fallback-providers.md
• website/docs/user-guide/features/skills.md
• website/docs/user-guide/messaging/index.md
• website/docs/user-guide/security.md
• website/docs/user-guide/windows-native.md
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/developer-guide/contributing.md
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/installation.md
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/security.md
• website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/windows-native.md

This page defines codebase-specific terminology, architectural concepts, and domain jargon used throughout the Hermes Agent project. It serves as a technical reference for onboarding engineers to map natural language concepts to specific code entities and understand their detailed implementation and data flow.

---

Core Architectural Terms

1. AIAgent

The core orchestration class that manages the conversation loop, tool execution, and agent state. It acts as the "brain" of the system, coordinating interactions between the LLM client, tool registry, session management, and execution environments.

• Implementation: AIAgent class, defined in run_agent.py17-21
• Responsibilities: Managing iterative conversation loops with tool calling, maintaining iteration budgets, invoking tool handlers, handling error recovery, and managing message history and session persistence.
• Key Functions: run_conversation() initiates a conversation; interacts with handle_function_call to dispatch tools.
• Relation to Tool System: Uses get_tool_definitions to resolve available tools and dispatches calls during conversation flow.
• Caching: LRU caching enforced in gateway to manage agent instance lifetimes (see Gateway details) gateway/run.py78-79

Sources: run_agent.py17-21 gateway/run.py78-79

2. Toolset

A named logical grouping of tools that provide specific capabilities (e.g., web, terminal, file). Toolsets allow selective enabling/disabling of features per platform or agent context for granularity and security.

• Implementation: Toolset logic resides mainly in model_tools.py, imported and used in run_agent.py (run_agent.py136-141)
• Composition: Toolsets are composed of multiple tools that share a common domain; e.g., web toolset contains search and extraction tools, terminal includes command execution tools.
• Configuration: Controlled through user configuration (config.yaml) and can be restricted at runtime such as disabling certain toolsets during cron or in interactive modes. Config-driven disabling logic is present in cron jobs cron/scheduler.py156-177

Sources: run_agent.py136-141 cron/scheduler.py156-177

3. Iteration Budget

A concurrency-safe counter managing the allowed number of reasoning and tool invocation iterations per request. This prevents infinite loops and bounds resource expenditure.

• Implementation: IterationBudget class imported from agent/iteration_budget.py and used in run_agent.py run_agent.py116
• Scope: The budget is decremented each time the agent processes a reasoning step or calls a tool.
• Subagent Delegation: When a subagent is spawned (via the delegate_task tool), it receives a partitioned portion of the parent's iteration budget to honor overall limits.
• Lifecycle: Tied closely to a conversation’s runtime in AIAgent.

Sources: run_agent.py116

4. Gateway

A long-running multi-platform messaging bridge that integrates Hermes with external chat platforms like Telegram, Discord, Slack, WhatsApp, and others.

• Implementation: Main gateway lifecycle manager is the GatewayRunner class defined in gateway/run.py6-14
• Platform Adapters: Implements the BasePlatformAdapter interface from gateway/platforms/base.py, with concrete classes for each messaging platform.
• Responsibilities: Manages platform connections, listens for incoming messages/events, routes messages to/from the Core Agent (AIAgent), schedules cron jobs, caches sessions and media, maintains session expiry, and handles security like pairing and allowlists.
• Agent Cache: Holds a bounded cache (_AGENT_CACHE_MAX_SIZE=128) of live AIAgent instances keyed by session for performance; evicts based on idle TTL gateway/run.py78-79
• Slash Commands: Gateway processes slash commands (e.g. /reset, /model) and routes them accordingly gateway/run.py340-341
• Message Formatting: Ensures platform-specific message formatting, threading, and reply anchoring.

Sources: gateway/run.py6-14 gateway/run.py78-79 gateway/run.py340-341

---

Technical Mapping: From Concept to Code

This diagram shows how high-level concepts map to crucial code entities, helping engineers navigate the core relationships.

System Entity Mapping

Sources:
run_agent.py17-21 run_agent.py137 run_agent.py139 run_agent.py142 gateway/run.py6-14 hermes_cli/main.py1-44 cron/scheduler.py1-10 hermes_state.py1-23 tools/terminal_tool.py

---

Domain Jargon & Abbreviations

Term	Definition	Code Pointer
ACP	Agent Client Protocol - protocol for editor integration with Hermes (VS Code, Zed IDE).	hermes_cli/main.py40
Auxiliary Client	Secondary LLM client router for side tasks like vision analysis, compression, web extraction with fallback chains.	agent/auxiliary_client.py1-41
CalVer	Calendar Versioning scheme (e.g., 2026.3.15) used for Hermes releases.	scripts/release.py
Context Compression	Automatic conversation history summarization done by ContextCompressor to fit token limits, used dynamically.	agent/context_compressor.py1-122
Credential Pool	Mechanism managing multiple API keys/providers for rotation and failover.	agent/credential_pool.py (refer in agent/auxiliary_client.py107)
FTS5	SQLite Full-Text Search module used for efficient session message text search.	hermes_state.py10-15
Honcho	AI-native memory integration plugin providing dialectic queries and prefetch pipelining for session memory.	hermes_cli/main.py21-36
Kanban	SQLite-based task board supporting multi-agent, multi-profile agile task coordination.	hermes_cli/kanban_db.py
SOUL.md	Markdown file representing the agent's core identity and personality for system prompt injection.	run_agent.py169
Slash Command	Commands starting with / within CLI and messaging platforms, e.g., /reset, /model.	gateway/run.py340-341
TUI	Terminal User Interface - React Ink-based frontend rendering CLI in full-screen mode with JSON-RPC gateway.	cli.py60-70
Trajectory	Detailed logs of agent reasoning, tool calls, and results for diagnostics and training purposes.	agent/trajectory.py
WAL Mode	SQLite Write-Ahead Logging mode for concurrent reads/writes in session storage.	hermes_state.py10-11
Tool	Code encapsulating an external function callable by the agent (e.g. shell command executor, web search).	model_tools.py (tool registry)
Iteration Budget	Thread-safe counter limiting number of LLM reasoning or tool calls per session/conversation.	agent/iteration_budget.py

Sources: hermes_cli/main.py40 agent/auxiliary_client.py1-41 scripts/release.py agent/context_compressor.py1-122 agent/auxiliary_client.py107 hermes_state.py10-15 hermes_cli/main.py21-36 hermes_cli/kanban_db.py run_agent.py169 gateway/run.py340-341 cli.py60-70 agent/trajectory.py hermes_state.py10-11 model_tools.py agent/iteration_budget.py

---

Data Flow: Message Processing

Illustrates how a platform user’s message flows through the gateway, into the agent, and back out after tool invocation and reasoning.

Message Trajectory

Sources:
run_agent.py17-21 run_agent.py166 run_agent.py139 gateway/run.py1-14 gateway/platforms/base.py

---

Execution Environment Backends

Hermes supports multiple backend environments for running commands securely and portably.

Backend	Description	Code Pointer
local	Executes commands directly on the host machine.	run_agent.py68-90
docker	Runs commands isolated inside Docker containers.	run_agent.py68-90
ssh	Executes commands remotely over SSH connections.	run_agent.py68-90
modal	Serverless sandbox execution on Modal cloud.	run_agent.py68-90
daytona	Integration with Daytona cloud development backend.	run_agent.py68-90

Note: The backend selection depends on user configuration and runtime environment variables, resolved early in AIAgent or tool calls.

Sources:
run_agent.py68-90 hermes_cli/config.py1-13

---

Configuration Hierarchy & Profiles

Hermes resolves its configuration settings using the following precedence:

1. CLI Arguments: Passed directly to the CLI entry point (such as hermes chat --model ...).
2. Configuration File (config.yaml): User-editable YAML stored in ~/.hermes/config.yaml. Stores model, provider, gateway, toolset, and feature settings.
3. Environment Variables: Loaded from .env files using load_hermes_dotenv, sourced automatically at startup in run_agent.py.
4. Defaults: Hardcoded default settings applied when no user overrides exist.

• Profile Management: Configuration profiles switch contexts by changing the active HERMES_HOME directory, allowing entirely separate config and session stores per profile.
• Implementation: Core config loading and saving operations are in hermes_cli/config.py Env var loading is done via run_agent.py126-130
• Helpers: Reverse model alias cache enables friendly model name display in frontends cli.py129-165
• Config Wizard: Interactive setup resides in hermes_cli.setup for initial profile and credential provisioning.

Sources:
hermes_cli/config.py1-157 run_agent.py126-130 hermes_constants.py cli.py129-165 hermes_cli/setup.py

---

This glossary page reflects the technical foundations and key system components for Hermes Agent, enabling onboarded engineers to navigate source code effectively and understand core domain concepts that the code encapsulates.