Skip to content

Builder mode

Personality

Edit SOUL.md and AGENTS.md, the two files that set your agent's voice and standing instructions.

Builder mode

Your agent reads two plain-text files at the start of every session. SOUL.md sets its personality, tone and voice; AGENTS.md holds what it should know and the instructions it should always follow. SettingsPersonality lets you read and edit both.

Opening the editor

Open SettingsPersonality (open it). In builder mode it's under "Customize" in the Settings list; in simple mode the link above still opens it.

The editor shows one file at a time. Two buttons at the top, "SOUL.md" and "AGENTS.md", switch between them. SOUL.md opens first.

The two files

FileWhat the editor says it's for
SOUL.mdYour agent's lasting personality, tone and voice, loaded into every session
AGENTS.md"Project context, conventions, and standing instructions for the agent."

Both are loaded into every session, so whatever you write applies to every conversation, not just the next one.

What to put in each

Some ideas, following the editor's own descriptions:

  • SOUL.md, for how it talks. For example: "Keep replies short and plain. Lead with the answer. Say so when you're unsure."
  • AGENTS.md, for what it should know and always do. For example: who you are and what you work on, the people and projects you mention often, and rules such as "Confirm with me before sending anything on my behalf."

If an instruction matters, put it in one file, not both, and word it plainly.

Editing a file

  1. Pick the file with its button at the top.
  2. Edit the text in the box. As soon as it differs from the saved copy, "● unsaved changes" appears, and the counter under the box shows the length, for example "1,204 chars · 38 lines".
  3. Press "save". It reads "saving + restarting…" while it works.

When it's done you see, for example, "Saved SOUL.md (1204 bytes) and restarted container."

  • "reset" puts back the text you last loaded, throwing away your unsaved edits. It and "save" stay greyed out until you change something.
  • A file that doesn't exist yet shows "No SOUL.md on disk yet. Type below and save to create it." (with the file's own name). An empty file shows the same note. Type your text and save to create it.
  • Keep each file under 65,536 characters. Hermes reads at most that much of each file when a session starts. A longer file is cut when it's loaded, so part of it is ignored. The editor won't save a file longer than 262,144 characters; trying gives the same "Couldn't save this file right now" message as any other failed save.

What saving does

  • It writes the file to your agent's own disk, then restarts your agent so it reads the new text.
  • It wakes your agent first if it's asleep.
  • If the restart doesn't go through, your file is still saved, and the message says the restart failed and that you can restart yourself. Press "restart" on SettingsStatus, or send /restart as a message on its own in the chat.
  • If the save itself fails, you see "Couldn't save this file right now. Give it a moment and try again." Nothing was changed.

While your agent is asleep

Opening the editor normally doesn't wake your agent. If your agent is asleep, you see the last copy the dashboard stored, with "Last synced" and a date and time. You can still edit it, and saving wakes your agent as described above.

If the dashboard has no stored copy yet (usually the first time you open the editor), it wakes your agent to read the file. It says your agent is starting up, which usually takes about 30 seconds, and then shows the file.

If the file can't be loaded, you see "Couldn't load this file right now. Give it a moment and try again." with a "↻ retry" button.

Editing safely

  • Keep a copy before a big rewrite. The editor has no history, and "reset" only goes back to the last saved text. Select all, copy the text somewhere safe, then edit. Backups also include both files (see Backups).
  • Leaving with unsaved edits asks first. Switching to the other file asks "Discard unsaved changes to this file?", and closing Settings asks "Discard unsaved changes?".
  • Save when you're done, not after every line. Each save restarts your agent.

Common questions

Do I have to fill in both files?

No. Your agent works without either. Edit whichever one you need.

My change doesn't seem to have taken effect.

Check that you saw the "Saved" message, and whether it said the restart failed. If it did, restart your agent from SettingsStatus. Hermes reads the files when a session starts, so start a new chat to try the change.

What's next