System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- optional-skills/software-development/code-wiki/SKILL.md
- skills/research/llm-wiki/SKILL.md
- optional-skills/creative/system-atlas/SKILL.md
- website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
- optional-skills/creative/simple-english/SKILL.md
- optional-skills/software-development/code-wiki/templates/architecture.md
Hermes Agent operates as a tool-based autonomous framework. It performs complex technical tasks by coordinating specialized skills such as documentation generation, research synthesis, and architectural visualization. The system relies on local tools—including terminal, read_file, and write_file—to interact with codebases and knowledge bases without external service dependencies.
The architecture emphasizes a layered approach to information management. It separates immutable raw source material from agent-generated synthesis and structural schemas. This design ensures data integrity while allowing the agent to maintain persistent, compounding knowledge over multiple sessions.
Agent Identity and Configuration
Hermes differentiates between global agent personality and project-specific operational instructions. This separation prevents project details from contaminating the agent's core behavioral style.
SOUL.md vs. AGENTS.md
The system utilizes two primary Markdown files to define its behavior:
| File | Scope | Primary Contents |
|---|---|---|
SOUL.md | Global Identity | Tone, personality, communication style, and core values. |
AGENTS.md | Project Local | Coding standards, file paths, ports, and specific workflow rules. |
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md:1-55
Identity Data Flow
Hermes injects identity into the system prompt through a prioritized hierarchy. The SOUL.md file acts as the primary identity marker.
The diagram shows how global identity, temporary overrides, and project-specific instructions merge into the active agent instance.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md:120-140
Knowledge Management Architecture (LLM Wiki)
The LLM Wiki skill implements a three-layer architecture for persistent research. This structure prevents redundant data discovery and maintains cross-referenced synthesis.
Architectural Layers
- Layer 1 (Raw Sources): Immutable source material stored in
raw/. The agent reads these files but never modifies them. - Layer 2 (The Wiki): Agent-owned Markdown files in
entities/,concepts/, andqueries/. The agent creates, updates, and links these files. - Layer 3 (The Schema): Defined in
SCHEMA.md. It constrains agent behavior, tag taxonomy, and structure rules.
Sources: skills/research/llm-wiki/SKILL.md:46-60
Wiki Directory Structure
The flowchart depicts the physical organization of the knowledge base into three functional layers.
Sources: skills/research/llm-wiki/SKILL.md:48-59
Automated Documentation System (Code Wiki)
The code-wiki skill generates reference documentation for existing repositories. It follows a structured 12-step procedure to analyze structure and produce artifacts.
Generation Workflow
The process starts by resolving the target repository (local or remote). The agent then scans the directory tree to identify core modules.
- Scan: Filters noise (e.g.,
node_modules,venv) and identifies entry points. - Pick: Selects 8–10 primary modules to document.
- Analyze: Reads manifests (
package.json,Cargo.toml, etc.) and important source files. - Write: Produces a
README.md,architecture.md, and Mermaid-based diagrams.
Sources: optional-skills/software-development/code-wiki/SKILL.md:48-75
Diagram Synthesis
The agent generates specific Mermaid diagrams based on code analysis:
- Flowcharts: Show the shape of the system and where state lives.
- Class Diagrams: Represent struct or class relationships using
~T~syntax for generics. - Sequence Diagrams: Trace 2–4 critical workflows through the code.
This diagram illustrates the interaction between the user, the agent, and the local file system during wiki generation.
Sources: optional-skills/software-development/code-wiki/SKILL.md:120-195
Explorable Architecture (System Atlas)
The System Atlas provides two complementary views of a software architecture from a single data.mjs source.
View Synchronization
- Interactive Isometric Map: Renders as
atlas.html. It features progressive disclosure through "chapters" and moving data packets. - Text Twin: Renders as
SYSTEM.md. It contains a decision table, structure details, and an ID-based question tracker.
Sources: optional-skills/creative/system-atlas/SKILL.md:15-30
Data Components
| Component | Function |
|---|---|
data.mjs | Single source of truth containing structures, flows, and decisions. |
build.mjs | Node.js script that generates the HTML and Markdown views. |
Q-<code><n> | Stable question IDs used for tracking feedback rounds. |
Sources: optional-skills/creative/system-atlas/SKILL.md:45-75
Conclusion
The Hermes Agent architecture centers on tool-based autonomy and structured information layers. By separating identity (SOUL) from operations (AGENTS) and source material (Raw) from synthesis (Wiki), the system maintains high technical accuracy. Skills like code-wiki and system-atlas further extend this by converting raw code into explorable visual and textual documentation.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md, skills/research/llm-wiki/SKILL.md