# NousResearch/hermes-agent · SOUL.md and AGENTS.md identity loading fixes

## Open now

- 3 issues, 3 PRs open on GitHub.
- #11763: AGENTS.md not loaded in gateway mode (WeChat/Telegram/Discord) — inconsistent agent behavior across platforms
- #66118: \[Bug\]: Profile SOUL.md / AGENTS.md identity ignored with custom Ollama provider (v0.18.2)
- #66396: SOUL.md Not Loading in Telegram Gateway
- PR #11885: fix(prompt): load AGENTS.md from HERMES_HOME
- PR #34863: Fix oneshot system prompt handling
- PR #66155: fix(prompt): load profile AGENTS.md from HERMES_HOME when cwd lacks it

A cluster of bugs, fixes, and docs updates centered on SOUL.md and AGENTS.md not being loaded or honored as agent identity across gateway, cron, TUI, and bot contexts. Work includes path resolution, config wiring, caching, and documentation corrections.

## TL;DR

- 28 member(s): 3 open issue(s), 10 closed issue(s), 3 open PR(s), 1 merged PR(s), 11 PR(s) closed without merging.
- A fix was merged to main in PR #17509. Verify it addresses your case.
- **Recommended:** read PR #17509 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-17509`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.06`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Open related issues

- #11763: AGENTS.md not loaded in gateway mode (WeChat/Telegram/Discord) — inconsistent agent behavior across platforms
- #66118: \[Bug\]: Profile SOUL.md / AGENTS.md identity ignored with custom Ollama provider (v0.18.2)
- #66396: SOUL.md Not Loading in Telegram Gateway

## Closed / duplicate issues

- #5200: \[docs\] Context Files (AGENTS.md/SOUL.md): documented behavior doesn't match code
- #6731: Feishu bot uses hardcoded DEFAULT_AGENT_IDENTITY instead of SOUL.md for system prompt
- #16756: \[Bug\]: CRON tasks do not apply prompts defined in SOUL.md
- #26596: \[Bug\] Gateway mode ignores SOUL.md and agent.personalities — DEFAULT_AGENT_IDENTITY always used
- #29476: \[Setup\]: USER.md seems to be unknown to hermes
- #32843: \[Bug\]: SOUL.md and AGENTS.md not loaded for Telegram gateway sessions in v0.14.0
- #34852: SOUL.md/personality not reflected in hermes -z oneshot identity
- #37480: Gateway (Telegram) ignores custom SOUL.md + AGENTS.md — serves DEFAULT_AGENT_IDENTITY despite correct paths, default profile, and load_soul_identity=true
- #43910: \[Bug\]: SOUL.md not loaded as agent identity in Desktop TUI mode — persona system overrides it silently
- #66394: SOUL.md Not Loading in Telegram Gateway

## Prior & competing PRs

- **#17509: fix(cron): keep SOUL.md identity when workdir is unset (#16756)**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `cron/scheduler.py`, `run_agent.py`, `scripts/release.py`, `tests/cron/test_cron_workdir.py`, `tests/run_agent/test_run_agent.py`
  - fix hunks:
  - `cron/scheduler.py`

    ```diff
    @@ -1033,10 +1033,12 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
                 enabled_toolsets=_resolve_cron_enabled_toolsets(job, _cfg),
                 disabled_toolsets=["cronjob", "messaging", "clarify"],
                 quiet_mode=True,
    -            # When a workdir is configured, inject AGENTS.md / CLAUDE.md /
    -            # .cursorrules from that directory; otherwise preserve the old
    -            # behaviour (don't inject SOUL.md/AGENTS.md from the scheduler cwd).
    +            # Cron jobs should always inherit the user's SOUL.md identity from
    +            # HERMES_HOME. When a workdir is configured, also inject project
    +            # context files (AGENTS.md / CLAUDE.md / .cursorrules) from there.
    +            # Without a workdir, keep cwd context discovery disabled.
                 skip_context_files=not bool(_job_workdir),
    +            load_soul_identity=True,
                 skip_memory=True,  # Cron system prompts would corrupt user representations
                 platform="cron",
                 session_id=_cron_session_id,
    ```
  - `run_agent.py`

    ```diff
    @@ -926,6 +926,7 @@ def __init__(
             thread_id: str = None,
             gateway_session_key: str = None,
             skip_context_files: bool = False,
    +        load_soul_identity: bool = False,
             skip_memory: bool = False,
             session_db=None,
             parent_session_id: str = None,
    ```

    ```diff
    @@ -977,6 +978,9 @@ def __init__(
                 skip_context_files (bool): If True, skip auto-injection of SOUL.md, AGENTS.md, and .cursorrules
                     into the system prompt. Use this for batch processing and data generation to avoid
                     polluting trajectories with user-specific persona or project instructions.
    +            load_soul_identity (bool): If True, still use ~/.hermes/SOUL.md as the primary
    +                identity even when skip_context_files=True. Project context files from the cwd
    +                remain skipped.
             """
             _install_safe_stdio()
     
    ```

    ```diff
    @@ -1005,6 +1009,7 @@ def __init__(
             self._print_fn = None
             self.background_review_callback = None  # Optional sync callback for gateway delivery
             self.skip_context_files = skip_context_files
    +        self.load_soul_identity = load_soul_identity
             self.pass_session_id = pass_session_id
             self._credential_pool = [redacted:secret-assignment]
             self.log_prefix_chars = log_prefix_chars
    ```

    ```diff
    @@ -4742,9 +4747,11 @@ def _build_system_prompt(self, system_message: str = None) -> str:
             #   6. Current date & time (frozen at build time)
             #   7. Platform-specific formatting hint
     
    -        # Try SOUL.md as primary identity (unless context files are skipped)
    +        # Try SOUL.md as primary identity unless the caller explicitly skipped it.
    +        # Some execution modes (cron) still want HERMES_HOME persona while keeping
    +        # cwd project instructions disabled.
             _soul_loaded = False
    -        if not self.skip_context_files:
    +        if self.load_soul_identity or not self.skip_context_files:
                 _soul_content = load_soul_md()
                 if _soul_content:
                     prompt_parts = [_soul_content]
    ```
  - `scripts/release.py`

    ```diff
    @@ -67,6 +67,7 @@
         "[redacted:email]": "BeliefanX",
         "[redacted:email]": "Mind-Dragon",
         "[redacted:email]": "westers",
    +    "[redacted:email]": "liuhao1024",
         "[redacted:email]": "devorun",
         "[redacted:email]": "beesrsj2500",
         "[redacted:email]": "beesrsj2500",
    ```
  - `tests/cron/test_cron_workdir.py`

    ```diff
    @@ -265,6 +265,7 @@ def _install_stubs(monkeypatch, observed: dict):
             class FakeAgent:
                 def __init__(self, **kwargs):
                     observed["skip_context_files"] = kwargs.get("skip_context_files")
    +                observed["load_soul_identity"] = kwargs.get("load_soul_identity")
                     observed["terminal_cwd_during_init"] = os.environ.get(
                         "TERMINAL_CWD", "_UNSET_"
                     )
    ```

    ```diff
    @@ -335,6 +336,7 @@ def test_workdir_sets_and_restores_terminal_cwd(
     
             # AIAgent was built with skip_context_files=False (feature ON).
             assert observed["skip_context_files"] is False
    +        assert observed["load_soul_identity"] is True
             # TERMINAL_CWD was pointing at the job workdir while the agent ran.
             assert observed["terminal_cwd_during_init"] == str(tmp_path.resolve())
             assert observed["terminal_cwd_during_run"] == str(tmp_path.resolve())
    ```

    ```diff
    @@ -373,6 +375,8 @@ def test_no_workdir_leaves_terminal_cwd_untouched(self, monkeypatch):
     
             # Feature is OFF — skip_context_files stays True.
             assert observed["skip_context_files"] is True
    +        # Cron still forces SOUL.md identity even when cwd context files stay off.
    +        assert observed["load_soul_identity"] is True
             # TERMINAL_CWD saw the same value during init as it had before.
             assert observed["terminal_cwd_during_init"] == before
             # And after run_job completes, it's still the sentinel (nothing
    ```
  - `tests/run_agent/test_run_agent.py`

    ```diff
    @@ -862,6 +862,26 @@ def test_always_has_identity(self, agent):
             prompt = agent._build_system_prompt()
             assert DEFAULT_AGENT_IDENTITY in prompt
     
    +    def test_can_use_soul_identity_even_when_context_files_are_skipped(self):
    +        with (
    +            patch("run_agent.get_tool_definitions", return_value=_make_tool_defs("terminal")),
    +            patch("run_agent.check_toolset_requirements", return_value={}),
    +            patch("run_agent.OpenAI"),
    +            patch("run_agent.load_soul_md", return_value="SOUL IDENTITY"),
    +        ):
    +            agent = AIAgent(
    +                api_key="[redacted:secret-assignment]",
    +                base_url="https://openrouter.ai/api/v1",
    +                quiet_mode=True,
    +                skip_context_files=True,
    +                load_soul_identity=True,
    +                skip_memory=True,
    +            )
    +            prompt = agent._build_system_prompt()
    +
    +        assert "SOUL IDENTITY" in prompt
    +        assert DEFAULT_AGENT_IDENTITY not in prompt
    +
         def test_includes_system_message(self, agent):
             prompt = agent._build_system_prompt(system_message="Custom instruction")
             assert "Custom instruction" in prompt
    ```
- **#26789: fix(gateway): honor SOUL.md and agent.personality in gateway sessions**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#26596`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#37520: fix(gateway): wire agent.load_soul_identity config to gateway AIAgent construction (#37480)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`
- **#66426: fix(agent): load root SOUL.md when profile home has only the seeded default (#66396)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#66396`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#6761: fix(gateway): evict cached agents across fresh session boundaries**. closed without merge
  - maintainer direction: category `silent_close`; implication `active`
- **#11885: fix(prompt): load AGENTS.md from HERMES_HOME**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#23412`
  - files: `agent/prompt_builder.py`, `tests/agent/test_prompt_builder.py`
- **#16947: fix(cron): keep SOUL.md identity without workdir**. closed without merge
  - maintainer direction: category `merged_via`; implication `superseded`; refs `#17509`, `#16756`
- **#18878: fix(agent): load SOUL.md from cwd with fallback to HERMES_HOME**. closed without merge
  - maintainer direction: category `silent_close`; implication `active`
- **#23166: docs(env): mark MESSAGING_CWD as deprecated compatibility fallback**. closed without merge
  - maintainer direction: category `superseded_by_pr`; implication `superseded`; refs `#22050`, `#34781`
- **#23167: docs(worktrees): use terminal.cwd for gateway working directories**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `119390a2a1eeb47a9b59d29e4158cfd31ae63e1f`
- **#23168: docs(config): clarify messaging cwd in cli-config example**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `119390a2a1eeb47a9b59d29e4158cfd31ae63e1f`
- **#23169: docs(security): recommend terminal.cwd for gateway hardening**. closed without merge
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `119390a2a1eeb47a9b59d29e4158cfd31ae63e1f`
- **#34863: Fix oneshot system prompt handling**. open
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#34852`, `#34852`
  - files: `hermes_cli/config.py`, `hermes_cli/oneshot.py`, `tests/cli/test_oneshot.py`, `tests/hermes_cli/test_placeholder_usage.py`
- **#65800: fix(agent): load gateway AGENTS.md from HERMES_HOME fallback**. closed without merge
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `d682f320b35a13084371a541a835e1d988c982b8`, `c62bcdeaaeeb`, `#11885`, `#65800`, `#66155`, `#29935`, `#30236`, `#76011`, `#11885`, `#11763`, `#65800`, `#29935`, `#29871`, `#30236`, `#30236`, `#29871`, `#65800`, `#66155`, `#66118`, `#76011`, `#75108`, `#29935`, `#30236`, `#29871`, `#30236`, `#29935`, `#11885`, `#65800`, `#11763`, `#66155`, `#66118`, `#65800`, `#66155`, `#11885`, `#11885`, `#65800`, `#29935`, `#30236`, `#76011`, `#1`, `#1`, `#15803`, `#14532`, `#6`, `#1`, `#9`, `#374151`, `#4338`, `#11763`, `#11885`, `#65800`
- **#66155: fix(prompt): load profile AGENTS.md from HERMES_HOME when cwd lacks it**. open
  - maintainer direction: category `partial_fix`; implication `needs_llm`; refs `d682f320b35a13084371a541a835e1d988c982b8`, `eb946036d905`, `#11885`, `#65800`, `#66155`, `#29935`, `#30236`, `#76011`, `#11885`, `#29935`, `#30236`, `#30236`, `#29871`, `#65800`, `#11763`, `#66155`, `#66118`, `#76011`, `#75108`, `#29935`, `#30236`, `#30236`, `#11885`, `#65800`, `#66155`, `#66155`, `#65800`, `#11885`, `#29935`, `#30236`, `#76011`, `#374151`, `#11763`, `#66118`, `#66155`
  - files: `agent/prompt_builder.py`, `tests/agent/test_prompt_builder.py`

## Fix status

- Merged to main in PR #17509 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-04-29`.
- Subsystem: `agent`