Skip to content

FileStateRegistry

FileStateRegistry is a process-level concurrency management mechanism in Hermes Agent v0.11 designed to prevent data corruption and race conditions when multiple sub-agents operate on the same file system in parallel^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

In a multi-agent environment, independent sub-agents may attempt to read and write to the same files simultaneously. Without coordination, this leads to "last write wins" scenarios where work is silently overwritten. The FileStateRegistry solves this by acting as a singleton service that tracks the state of file interactions, effectively serializing the "read-modify-write" cycle on a per-path basis^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Core Mechanism

The registry operates as a singleton instance within the agent process^[001-TODO__Hermes_Agent_v0.11_-结构升级与实战工作流解读.md]. It utilizes per-path threading locks to ensure that while different files can be processed in parallel, operations on a single specific file are strictly serialized^[001-TODO__Hermes_Agent_v0.11-_结构升级与实战工作流解读.md].

It manages file state through three primary hooks:

  1. Stamping Reads: When a sub-agent reads a file (e.g., via read_file), the registry records a "read stamp" for that agent.
  2. Tracking Writes: When a file is written to, the registry updates the "last writer" record.
  3. Checking Staleness: Before a write operation completes, the registry checks if the file has been modified by another agent (or externally) since the current agent last read it^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Staleness Detection

The FileStateRegistry proactively detects conflicts by validating the state of the file against the agent's current knowledge^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

There are three types of staleness warnings that can be returned to the model:

Detection Type Trigger Condition Behavior
Sibling Overwrite Another sub-agent (different task ID) has written to the file after the current agent read it. The agent is warned specifically which task modified the file.
External Modification The file's modification time (mtime) on disk has changed (e.g., due to manual editing). The agent is warned of external edits.
Write Without Read The agent attempts to write to a file it has never read (e.g., creating a new file). The agent is prompted to read the file first to ensure awareness of existing content.^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md]

Operational Behavior

  • Non-Blocking: The registry is designed to assist the LLM rather than hard-block execution. When a conflict is detected, check_stale returns a warning text string to the model. It is then up to the model to decide whether to re-read the file and proceed^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • Self-Refresh: To prevent false positives, the registry automatically updates an agent's read stamp immediately after that agent successfully writes to a file^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Configuration

The FileStateRegistry can be disabled if necessary for specific workflows, though it is enabled by default to support safe parallelization^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

  • Environment Variable: HERMES_DISABLE_FILE_STATE_GUARD=1
  • [[Hermes Agent v0.11]]
  • [[Orchestrator]]
  • [[Sub-agent Delegation]]
  • [[Agentic Workflow]]

Sources

  • 001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md