Context and Prompt Management

Relevant source files

• agent/agent_init.py
• agent/agent_runtime_helpers.py
• agent/chat_completion_helpers.py
• agent/coding_context.py
• agent/context_compressor.py
• agent/conversation_compression.py
• agent/conversation_loop.py
• agent/manual_compression_feedback.py
• agent/prompt_builder.py
• agent/system_prompt.py
• agent/tool_executor.py
• agent/turn_context.py
• contributors/emails/kudi3699@gmail.com
• contributors/emails/lanyusea@gmail.com
• contributors/emails/lucas@policastromd.com
• contributors/emails/miniadmin@skshim-mini.local
• contributors/emails/stanislav@local
• hermes_cli/_subprocess_compat.py
• hermes_cli/gateway_windows.py
• hermes_cli/stdio.py
• tests/agent/test_aux_progress_streaming.py
• tests/agent/test_cjk_token_estimation.py
• tests/agent/test_coding_context.py
• tests/agent/test_compression_anti_thrash_persistence.py
• tests/agent/test_compression_concurrent_fork.py
• tests/agent/test_compression_rotation_state.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_manual_compression_feedback.py
• tests/agent/test_prompt_builder.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_system_prompt.py
• tests/agent/test_turn_context.py
• tests/agent/test_turn_context_overflow_warning.py
• tests/cli/test_cli_interrupt_ack_race.py
• tests/cli/test_cli_shutdown_memory_messages.py
• tests/cli/test_compress_type_ahead.py
• tests/cli/test_manual_compress.py
• tests/gateway/test_compress_command.py
• tests/gateway/test_gateway_inactivity_timeout.py
• tests/gateway/test_planned_stop_watcher.py
• tests/gateway/test_session_hygiene.py
• tests/gateway/test_telegram_noise_filter.py
• tests/hermes_cli/test_gateway_windows.py
• tests/hermes_cli/test_gateway_wsl.py
• tests/run_agent/test_413_compression.py
• tests/run_agent/test_compression_boundary_hook.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_cli_manual_compress.py
• tests/test_hermes_state_compression_locks.py
• tests/test_windows_subprocess_no_window_flags.py
• tests/tools/test_daemon_pool.py
• tests/tools/test_env_probe.py
• tests/tools/test_windows_native_support.py
• tests/tui_gateway/test_compress_lock_skip.py
• tools/daemon_pool.py
• tools/env_probe.py
• tools/project_tools.py
• tui_gateway/git_probe.py

This page explains how the AIAgent constructs the system prompt, manages contextual inputs from project files such as SOUL.md, dynamically injects user-specified context, and manages LLM context window limits via compression and auxiliary models.

---

System Prompt Assembly

The central function for constructing the system prompt is AIAgent._build_system_prompt(), which delegates assembly to build_system_prompt_parts agent/system_prompt.py146-234 This method assembles a layered prompt including the agent's identity, behavioral instructions, tools, skills, and contextual project files.

Implementation and Data Flow

• Caching: The system prompt is cached in self._cached_system_prompt to avoid repeated costly rebuilds. It is invalidated when factors like directory changes or context compression occur agent/system_prompt.py1-9
• Stateless Assembly Modules: Composition logic lives in agent/prompt_builder.py and agent/system_prompt.py as functions that return string snippets agent/prompt_builder.py1-5
• Three-Tier Architecture: The prompt is structured into three ordered parts agent/system_prompt.py146-163:
  1. Stable: Identity (SOUL.md or default), tool guidance, skills prompt, environment/platform hints, and model-specific operational guidance.
  2. Context: Context files (e.g., HERMES.md, .cursorrules) and the initial caller-supplied system_message.
  3. Volatile: Memory snapshots (MEMORY.md), user profiles (USER.md), external memory provider blocks, and session metadata.

Composition Layers

Layer	Source / Function	Purpose
Agent Identity	load_soul_md() or DEFAULT_AGENT_IDENTITY	Core persona and behavioral tone agent/prompt_builder.py131-147
Help Guidance	HERMES_AGENT_HELP_GUIDANCE	Directs agent to official docs for self-troubleshooting agent/prompt_builder.py149-158
Memory Guidance	MEMORY_GUIDANCE	Instructions on how to use the memory tool effectively agent/prompt_builder.py160-170
Skills Guidance	SKILLS_GUIDANCE	Defines the progressive disclosure pattern for skill usage agent/prompt_builder.py190-195
Tool Enforcement	TOOL_USE_ENFORCEMENT_GUIDANCE	Specialized formatting for models like GPT-4o agent/prompt_builder.py209-225
Platform Hints	_resolve_platform_hint()	Platform-specific instructions (e.g., TUI embedded pane) agent/system_prompt.py67-114

System Prompt Build Logic

Title: "System Prompt Assembly Flow"

Sources: agent/prompt_builder.py127-225 agent/system_prompt.py146-234 agent/system_prompt.py1-22

---

Context Files and Persona (SOUL.md)

Context Discovery and Security

Hermes Agent discovers context and persona information hierarchically to ground the agent in the user's project environment:

• Persona (SOUL.md): Defines the agent's personality. Located at ${HERMES_HOME}/SOUL.md. If missing, the agent falls back to DEFAULT_AGENT_IDENTITY agent/prompt_builder.py131-147
• Project Context Files: Discovered via _find_hermes_md() which searches agent/prompt_builder.py93-114:
  1. .hermes.md or HERMES.md: Native project instructions (searches up to git root).
  2. AGENTS.md: Common agent instruction file.
  3. .cursorrules: Compatibility with Cursor IDE rules.
• Security Scanning: All context content is passed through _scan_context_content() which utilizes _scan_for_threats (scope="context") to block prompt injection patterns agent/prompt_builder.py50-74

Coding Posture

When running in a code workspace (detected by _PROJECT_MARKERS), the agent adopts a coding posture. This injects a workspace snapshot into the system prompt via build_coding_workspace_block(), including the current git branch, dirty status, and project facts agent/coding_context.py32-37

Sources: agent/prompt_builder.py50-74 agent/prompt_builder.py93-114 agent/coding_context.py1-50

---

Context Window Management and Compression

Long conversations are managed by the ContextCompressor class, which summarizes conversation history to fit within model limits while protecting recent turns agent/context_compressor.py1-17

Preflight Estimation and Progress

Before initiating compression, the agent performs checks in build_turn_context agent/turn_context.py1-23:

• Thresholds: ContextCompressor checks should_compress() based on last_prompt_tokens vs threshold_tokens agent/context_compressor.py84-100
• Summarization: Uses an auxiliary model to summarize middle turns while protecting "head" and "tail" context agent/context_compressor.py1-5
• Historical Snapshots: Compacted turns are marked with SUMMARY_PREFIX and HISTORICAL_TASK_HEADING to ensure the agent treats them as reference only agent/context_compressor.py92-122

Turn Prologue

The build_turn_context function performs per-turn setup, including runtime wiring and preflight context compression agent/turn_context.py1-15 This produces a TurnContext object containing the sanitized messages and the active system prompt for the conversation loop.

Title: "Context Compression Pipeline"

Sources: agent/context_compressor.py1-122 agent/turn_context.py1-15 agent/context_compressor.py84-100

---

Dynamic Prompt Injection

API Content Sidecars

Hermes uses an api_content sidecar pattern to inject ephemeral context into the API copy of a message while keeping the stored transcript clean agent/turn_context.py52-71

• Composition: compose_user_api_content appends memory prefetch and plugin context to the user message agent/turn_context.py72-84
• Substitution: substitute_api_content swaps the clean content for the sidecar right before the API call to maintain prompt-cache stability agent/turn_context.py87-108

Tool Result Management

Large tool outputs are managed via enforce_turn_budget to prevent a single tool response from exhausting the context window agent/tool_executor.py47-51

• Scaling: _budget_for_agent resolves a BudgetConfig scaled to the model's context window agent/tool_executor.py78-92
• Pruning: Before summarization, _summarize_tool_result prunes large tool outputs (like web_extract content) to a text summary agent/context_compressor.py14-17

Sources: agent/turn_context.py52-108 agent/tool_executor.py47-92 agent/context_compressor.py14-17

---

Summary Diagram: Natural Language Concepts to Code Entities

Title: "Context Management - NL to Code Mapping"

Sources: agent/prompt_builder.py1-147 agent/system_prompt.py146-234 agent/context_compressor.py1-40 agent/turn_context.py52-84