How to Define an IM Agent's Role, Personality, and Voice with SOUL.md

An IM Agent does not feel like the same person simply because it is connected to Telegram or WhatsApp. Stable role rules, voice, behavioral boundaries, and durable context all shape how it behaves across messaging scenarios.

In the Hermes Agent runtime, SOUL.md is the core file that carries the Agent persona. LightVela generates and injects a Soul through the Personality feature, so you do not need to operate the cloud file system directly.

Defining an IM Agent's role, personality, and voice with SOUL.md

Summary

Whether an IM Agent feels like "the same person" depends on its persona, not on which channel it runs through. SOUL.md carries the role, tone, priorities, behaviour, and limits, and it is the core persona file in the Hermes runtime. On LightVela you never touch the cloud filesystem directly — the Persona section on an Agent's settings page offers two entry points, drawing a persona at random or answering a short quiz. Review a persona card's role, tone, and behaviour notes, then choose Inject Persona to apply it. Write judgeable principles rather than specific facts: "lead with the conclusion", "state uncertainty explicitly", and "confirm before sending external messages" are persona rules, while project names and ports belong in long-term memory. After injecting, verify tone and limits with one real conversation.

Who this is for

This guide is for people who want to give an IM Agent a stable role, such as a personal assistant, research partner, study companion, or everyday customer-communication assistant. If you have not chosen a messaging channel yet, start with How to Connect an AI Agent to Messaging Platforms.

Understand the three context layers first

`SOUL.md`: who the Agent is and how it works

SOUL.md is best for stable persona rules, including role, voice, priorities, behavior, and boundaries. Rules such as "give the conclusion first", "state uncertainty clearly", and "ask before sending an external message" belong here.

User profile: who you are and how you want to be treated

The user profile is best for your language, time zone, identity, background, and communication preferences. For example, "I am in Singapore", "use English by default", and "show deadlines first" are usually user preferences, not Agent identity rules.

Long-term memory: what you have established together

Long-term memory is best for project state, decisions, and reusable context from your shared work. It grows through continued conversation and can be reviewed or capacity-managed in Memory Management.

Mixing the three makes the Agent's identity, user preferences, and temporary project context interfere with one another. Keeping them separate lets the personality stay stable while the conversation adapts to the real user and work.

Prerequisites

A running LightVela Hermes Agent. If you have not created one yet, start with the Quickstart.
A configured model and at least one available conversation channel.
A short persona brief. Decide who the Agent serves, what it mainly does, how it should sound, and which actions always require confirmation.

Steps / key concepts

1. Define the persona goal with five questions

Before choosing a Soul, answer these five questions:

Who is the Agent?
Who does it mainly help?
How should it normally sound?
What should it do when information is uncertain?
Which external actions require confirmation first?

Turn the answers into a planning brief like this:

Role: A research assistant for personal projects
Audience: A user who wants reliable conclusions quickly
Voice: Concise, professional, friendly, conclusion first, evidence second
Behavior: Break down questions, flag uncertainty, and ask only one key question when needed
Boundaries: Never send external messages, change files, or take high-risk actions without confirmation

This template helps you choose and calibrate a persona. It does not mean that LightVela exposes a general-purpose editor for arbitrary cloud files.

2. Open Personality in Agent settings

In the LightVela console, open the target Hermes Agent's settings and select "Personality". The international site provides both "Draw random soul" and "Soul personality test" entry points.

Use the random draw to explore different role styles. Use the personality test when you want a Soul that better matches your communication and behavior preferences.

Review the role, voice, and behavior description on each card, then choose the one that best matches your planning brief.

3. Inject the selected Soul into `SOUL.md`

Select the Soul and click "Inject soul". LightVela writes the selected Soul to the current Hermes Agent's SOUL.md and keeps a backup before replacing an existing file.

Only one personality is active for an Agent at a time. If you want to switch roles, review the new card's boundaries before injecting it again.

After the injection succeeds, return to your IM channel and send:

/new

Hermes Agent reads the new SOUL.md when a new conversation starts. This matters because an existing conversation may still hold the previous persona snapshot.

4. Add user preferences and durable facts through conversation

Do not put every piece of information into SOUL.md. Keep the stable persona short, and let the user profile and long-term memory handle personal preferences and project facts.

For example, tell Hermes:

Remember that I am in Singapore time and want a concise weekday plan at 8:00 AM, with deadlines listed first.

Or:

Forget the Friday evening reminder preference I mentioned earlier. Do not schedule it again.

Hermes handles remember and forget requests through conversation. Use Memory Management to review Memory and User Profile content and capacity.

5. Install skills only for real work

Personality defines how the Agent works, but it does not automatically add external capabilities. If you want it to browse, organize material, look up information, or perform another concrete task, install a suitable skill and check its source and permissions first.

Start with Configure Skills. Skills and personality should reinforce each other, not use a high-risk skill to compensate for unclear persona boundaries.

Verify that the personality is active

After starting a new conversation, do more than ask for a self-introduction. Test at least these four cases:

What is your current role, main job, and default voice?

How do you respond when you are uncertain about a fact?

If I ask you to send a message to an external service, what do you do first?

Turn this material into conclusions, evidence, and questions that still need confirmation.

Check whether the Agent preserves the role, voice, and safety boundaries, and whether it can still use relevant context from the user profile and long-term memory. If the behavior is unstable, simplify the persona rules before choosing or injecting another Soul.

FAQ

Do I need to edit the cloud `SOUL.md` manually?

Usually not. LightVela's Personality entry generates and injects the Soul, so normal use does not require direct cloud file-system operations.

Does changing `SOUL.md` affect every messaging channel?

It affects Agent-level behavior for the same Hermes Agent. If that Agent is connected to Telegram and WhatsApp, both channels use the personality in new conversations, while each channel still has its own authorization, message format, and capability limits.

How to Configure a Hermes Agent with a Distinct Personality in Telegram - Apply the personality to 1-to-1 Telegram conversations.
How to Configure a Hermes Agent with a Distinct Personality in WhatsApp - Apply the personality to 1-to-1 WhatsApp conversations.
Where Hermes Agent's Personality Comes From - Understand Persona, user preferences, and long-term memory in more depth.
Cloud Storage - Manage reference material and work files that the Agent can use.