[KongchangAI]
· 1 min read· 848 words

How Do Hermes Agent's .md Files Work? A Breakdown of the Core Mechanism

How Do Hermes Agent's .md Files Work? A Breakdown of the Core Mechanism

Hermes Agent uses three Markdown files to carry the user profile, dynamic memory, and personality settings.

Hermes Agent builds cross-session consistency on a `.hermes` directory, where three Markdown files—`user.md`, `soul.md`, and `memory.md`—handle the personal profile, personality settings, and dynamic memory respectively. `user.md` holds near-static identity information, `memory.md` is dynamically written with details worth remembering during conversation, and `soul.md` describes the Agent's personality and expression style in natural language, replacing hardcoded behavioral parameters. The plain-text approach offers transparency, editability, portability, and auditability, letting users view and correct memories at any time. The cost is that memory writing depends on the Agent's judgment, and as files grow, how to retrieve and inject context becomes a new engineering challenge—the success of the approach largely depends on the scheduling logic for writing and reading.

Hermes Agent entrusts both its "memory" and its "personality" to a handful of Markdown files. Understanding this mechanism is key to understanding how this Agent maintains consistency across sessions.

The .hermes Directory: Where the Agent's "Self" Lives

No matter how you interact with Hermes, you ultimately face the same Agent. This means Hermes maintains its own .hermes directory—though in theory, depending on how you configure things, there may be multiple scattered directories across your system.

This directory holds a large amount of information, the most critical of which are three Markdown files: user.md, soul.md, and memory.md. Markdown (.md) is, to the uninitiated, just plain text with basic formatting—you can add headings, bold text, and so on. These files describe "what Hermes knows about you" and "what it knows about itself."

Hermes manages files like .user.md and soul.md

The choice of Markdown is not arbitrary. Plain text means these files are readable, editable, and version-controllable—users can see exactly what the Agent has remembered without relying on any proprietary format.

user.md and memory.md: Distinguishing "Profile" from "Memory"

Here's an easily confused point: user.md and memory.md have similar content in some descriptions—both contain your name, date of birth (if relevant), country of residence, and so on. The original text's account overlaps in how these two files divide responsibilities, and developers should pay attention to the actual differences in implementation.

A clearer distinction comes from how they're written. memory.md is dynamic: when you tell it something worth remembering, or explicitly say "remember this detail," it writes that information to memory.md. In other words, user.md is closer to a static personal profile, while memory.md is a memory pool that accumulates continuously through conversation.

These two files record personal information such as your name and date of birth

The benefit of this design is transparency: you can open memory.md at any time to check what the Agent has recorded, or manually correct erroneous memories, without worrying that information is locked away in some black-box vector database.

soul.md: Defining the Agent's Personality in Natural Language

soul.md defines the personality of the Hermes Agent. You can write "You are always concise, efficient, and never waste words," or "You are always friendly, talkative, and empathetic." Whatever you write in soul.md, the Agent will act accordingly.

soul.md determines how the Agent behaves

The idea of carrying personality settings in a Markdown file is essentially replacing hardcoded behavioral parameters with natural-language prompts. Compared to adjusting temperature or the system prompt in code, soul.md lets non-engineering users directly rewrite the Agent's behavioral style, with changes taking effect immediately and being easy to roll back.

System Prompt is a special kind of input in large language model applications. It is injected before the user's conversation begins to set the model's identity, behavioral guidelines, and output style—essentially giving the model a "role setting." Unlike ordinary conversation messages, the system prompt usually has higher priority, and the model prioritizes its instructions when generating responses. The traditional approach hardcodes the system prompt in application code or configuration files, requiring developer intervention to modify; the soul.md approach externalizes the system prompt into a user-editable Markdown file whose contents are read and injected at the start of each session. This turns behavior adjustment from "changing code" into "changing documents," lowering the barrier to iteration. Note that the system prompt is not an absolute constraint—the model may still deviate from instructions, so the more specific and consistent the personality description, the more stable the results usually are.

The Trade-offs of This Design

The division of labor among the three files reflects a three-layer structure of "profile—memory—personality": user.md manages identity, memory.md manages experience, and soul.md manages expression. Everything is based on plain text, meaning it's highly portable and auditable.

Markdown plain text records what the Agent knows

The costs are equally real. Plain-text memory relies on the Agent's judgment of "what's worth remembering," and the accuracy of its writing strategy directly determines long-term performance; as the number of files grows, how to retrieve and inject context becomes a new engineering problem. The original text doesn't elaborate on these details, but from the mechanism design one can predict that the success of this approach depends largely on the scheduling logic for writing and reading memories.

Context Injection refers to splicing external information (such as memory file contents) into the prompt before the model generates a response, so the model "sees" this information and answers accordingly. Because the model's context window is limited, not all memory files can be indiscriminately stuffed into every request, so a scheduling logic is needed: first determine which memories are relevant based on the current conversation, then selectively load them. Common strategies include retrieval by keyword or semantic similarity, ordering by temporal recency, and setting fixed quotas. Injecting too much content crowds out conversation space and increases cost, while injecting too little may miss key information. This is precisely the core engineering challenge that plain-text memory solutions face as file size grows—memory "writing" is only the first step; "reading the right fragments at the right time" is what determines long-term performance.

#Hermes Agent#Markdown memory#soul.md#user.md#memory.md#system prompt#context injection#AI agent memory
Share:

Related articles