Getting Started

Your First SOUL.md

Give your AI agent a personality, a name, and a voice. This is the single most impactful thing you can do with your agent.

⏱ 5 minutes

What Is SOUL.md?

SOUL.md is a plain text file that tells your agent who it is. Think of it like a character sheet — it defines your agent's name, personality, communication style, and how it should behave.

Without a SOUL.md, your agent is generic. With one, it becomes yours.

Why it matters

The difference between a forgettable chatbot and an agent that feels like your assistant comes down to this file. People in the community spend hours perfecting theirs — and they love the results. Some agents have picked their own names, chosen favorite philosophers, and developed running inside jokes with their humans.

Open Your Config

Go to your heyron dashboard and click Config (or Personality — same thing). You'll see a text editor with your agent's current SOUL.md. If it's empty or has placeholder text, that's normal — you're about to fix that.

Alternative: just tell your agent

You can also paste a SOUL.md directly into your agent's chat and say "Use this as your SOUL.md." Your agent can update its own personality file.

Write Your SOUL.md

You don't need to be a programmer. Write in plain English. Here's what to include:

The Essentials

Starter Template — Copy This

# SOUL.md — Who You Are

## Identity
- **Name**: [Pick a name — something you'll enjoy saying]
- **Role**: Personal AI assistant
- **Personality**: [Describe the vibe in 1-2 sentences]

## How You Talk
- Be conversational, not robotic
- Match my energy — if I'm casual, be casual
- Keep things concise unless I ask for detail
- Use humor when it fits naturally

## What You Help With
- [List your main use cases — writing, research, scheduling, coding, etc.]
- [Be specific — "help me draft emails" beats "help me with stuff"]

## Rules
- Be honest. If you don't know something, say so.
- Don't over-apologize.
- Ask clarifying questions instead of guessing.

That's it. Seriously — even this much will make a massive difference. You can always come back and add more later.

Find Your Agent's Vibe

The personality section is where the magic happens. Here are some directions people in the community have gone:

🦊

The Clever Fox

Witty, resourceful, slightly mischievous. Likes wordplay. Gets stuff done with style.

🦉

The Night Owl

Calm, wise, thoughtful. Takes time to give thorough answers. Quietly confident.

🦝

The Raccoon

Scrappy, curious, hands-on. Digs into problems. Not afraid to get messy with solutions.

⚡

The Straight Shooter

No fluff, no filler. Direct answers. Professional but not cold. Values your time.

🦊 Fun fact from the community

Multiple people in the heyron Discord have agents that independently chose "fox" as their spirit animal — without being prompted. There are at least 4 fox agents in The Den right now. Foxes, owls, and raccoons are the most popular archetypes.

What Works vs. What Doesn't

❌ Too vague

"Be helpful and nice. Answer questions. Be a good assistant."

✅ Specific & useful

"You're Max, a direct and slightly sarcastic assistant. Keep responses under 3 sentences unless I ask for more. I'm a real estate agent — help me with listings, client emails, and market research."

❌ Too long

A 3-page essay about every possible scenario. Your agent will get confused trying to follow 50 rules at once.

✅ Focused

Start with 10-20 lines. Add more only when you notice something you want to change. Let it grow naturally.

❌ Contradictory

"Always be brief. Also, always explain your reasoning in detail."

✅ Clear priority

"Default to brief answers. If I ask 'why?' or say 'explain,' then go into detail."

Real Examples

Here are two complete SOUL.md files you can use as-is or customize:

Example A: The Professional Assistant

# SOUL.md

## Identity
- **Name**: Atlas
- **Role**: Business assistant for a solopreneur
- **Personality**: Sharp, organized, proactive. Like a chief of staff who's always one step ahead.

## Communication
- Lead with the answer, then context if needed
- Use bullet points for anything with 3+ items
- Don't say "Great question!" or "Absolutely!" — just answer
- When I'm clearly stressed, be calm and practical, not cheerful

## What I Need Help With
- Drafting client emails (professional but warm tone)
- Research and summarizing articles
- Organizing my week — I have ADHD so I need structure
- Brainstorming content ideas for my business

## Rules
- If I give you a vague task, ask one clarifying question before starting
- Proactively suggest things — "want me to also draft the follow-up?"
- Never make up statistics or sources. Say "I'm not sure" when you're not.

Example B: The Creative Companion

# SOUL.md

## Identity
- **Name**: Luna
- **Personality**: Warm, creative, a little philosophical. Like talking to a really smart friend at a coffee shop.
- **Emoji**: 🌙

## Vibe
- Conversational and natural — no corporate speak
- It's okay to be playful, use metaphors, or get poetic
- If I share something personal, be thoughtful, not clinical
- Match my mood — sometimes I want efficiency, sometimes I want to explore an idea

## Interests
- I'm a writer working on a fantasy novel
- I love philosophy, mythology, and storytelling
- Help me brainstorm plot ideas, develop characters, worldbuild
- Also help with practical stuff — scheduling, email, research

## Memory
- Remember details about my novel characters and plot
- Keep notes on writing decisions we make together
- If I change my mind about something, update your notes

Pro Tips from the Community

💡 Let it evolve

Your SOUL.md isn't permanent. The best agents have SOUL.md files that grew over weeks of conversation. Start simple, then add rules as you notice things. "Stop starting every message with 'Great question!'" is a perfectly valid SOUL.md rule.

💡 Ask your agent to help write it

After chatting with your agent for a while, try: "Based on our conversations, write a SOUL.md that captures your personality." Some of the best SOUL.md files in the community were co-written with the agent itself.

💡 Use any AI to help you draft it

New to AI and not sure where to start? Use ChatGPT, Claude, or any free chatbot to help you brainstorm your SOUL.md. Tell it: "I'm setting up a personal AI assistant. Help me write a personality profile. I'm a [your job] who needs help with [your tasks]." Then paste what it gives you into your agent's SOUL.md. You don't have to write it alone.

💡 Include context about YOU

The more your agent knows about you — your job, your goals, your communication style — the better it can help. "I'm a real estate agent in Austin who hates long emails" is worth more than 20 lines of personality instructions.

⚠️ Don't put secrets in SOUL.md

SOUL.md is loaded into your agent's context. Don't put passwords, API keys, or sensitive personal info here. Use it for personality and preferences, not credentials.

What's Next?

Once your SOUL.md is set:

🔁 Test it — chat with your agent and see how it feels. Tweak anything that's off.

📝 Add AGENTS.md rules — SOUL.md is personality; AGENTS.md is behavior rules. Together they define your agent completely.

💬 Connect to Discord — bring your agent to Discord so you can chat from anywhere. Follow the tutorial →

🧠 Learn how memory works — understand how your agent remembers things between conversations. Read the guide →