Skip to main content
Every time you start a new conversation, the BrowserOS assistant reads a file called SOUL.md. This file defines who the assistant is: how it talks, what it prioritizes, and how it behaves. Over time, it evolves based on your interactions, making the assistant feel less like a tool and more like your assistant.

​
What is SOUL.md?

SOUL.md is a plain text file that lives on your machine. It contains your assistant’s personality, tone, communication style, rules, and boundaries. Think of it as a personal guide the assistant reads before every conversation. It shapes how the assistant responds to you, not what it knows. Facts about you (your name, projects, preferences) are stored separately in memory.
The SOUL.md concept was pioneered by OpenClaw and inspired by soul.md, which explore the idea of giving AI systems a persistent identity through written documents. BrowserOS builds on this concept with a file that the assistant can read and rewrite on its own.

​
How It Works

When you first use BrowserOS, the assistant starts with a simple default personality:
Be genuinely helpful. Have opinions when asked. Be resourceful before asking. Earn trust through competence.
As you chat, the assistant picks up on how you like to communicate. If you prefer direct answers, it notices. If you set a boundary (“never send emails without asking me first”), it writes that into SOUL.md. Over time, the file becomes a reflection of how you and your assistant work together.
1

First conversation

The assistant starts with a default template. It watches for cues about your preferred style, tone, and boundaries.
2

The assistant learns your style

Based on your interactions, the assistant rewrites SOUL.md to reflect your preferences. It will briefly tell you when it makes a change.
3

Every future conversation

The assistant reads the updated SOUL.md before responding, so your preferences carry over across sessions.
You do not need to write or edit SOUL.md yourself. The assistant handles it. But you can always view it or ask the assistant to change it.

​
Viewing Your SOUL.md

Open Settings > Agent Soul to see what your assistant’s personality file looks like right now. The page shows the current contents of SOUL.md in a read-only viewer.

​
Shaping Your Assistant

You do not need to edit the file directly. Just talk to your assistant. Here are some ways to shape its personality:

Set the tone

“Be more casual and direct. Skip the formalities.”

Add a boundary

“Never post to Slack or send emails without confirming with me first.”

Change the personality

“Be more opinionated. If you think my approach is wrong, say so.”

Start fresh

“Reset your personality to the default.”
The assistant will update SOUL.md based on your instructions and let you know what changed.

​
Where SOUL.md Lives

SOUL.md is stored locally on your machine, inside the BrowserOS data folder:
Operating SystemPath
macOS~/.browseros/SOUL.md
Windows%APPDATA%/.browseros/SOUL.md
Linux~/.browseros/SOUL.md
The file is plain Markdown, limited to 150 lines. You can open it in any text editor if you want to make manual edits, though we recommend letting the assistant manage it through conversation.

​
SOUL vs Memory

BrowserOS keeps personality and knowledge separate on purpose.

SOUL.md

How the assistant behaves. Personality, tone, communication style, rules, and boundaries. One file, updated by rewriting the whole thing.

Memory

What the assistant knows about you. Your name, projects, tools, preferences, and recent events. Stored as core facts and daily notes.
When the assistant learns that you prefer bullet points over paragraphs, that goes in SOUL.md. When it learns that you work at Acme Corp on a project called Atlas, that goes in memory. This separation means the assistant can have a consistent personality even when its factual knowledge changes, and vice versa.

​
Example SOUL.md

Here is what an evolved SOUL.md might look like after a few conversations: 
# SOUL.md

## Personality
- Direct and concise. No filler phrases.
- Have opinions and share them when relevant.
- Use humor sparingly but naturally.

## Communication Style
- Default to bullet points for lists and options.
- Keep status updates to one or two lines.
- When explaining something technical, use analogies.

## Boundaries
- Never send emails or post messages without explicit confirmation.
- Do not make purchases or financial transactions.
- Ask before modifying any file outside the current project.

## Preferences
- When researching, prioritize primary sources over summaries.
- For code tasks, prefer simple solutions over clever ones.
- Always explain trade-offs when suggesting approaches.
Your SOUL.md will look different because it is shaped by your conversations. No two are the same.