The Complete Guide to SOUL.md — Designing AI Personalities for ESP-Claw

SOUL.md is what makes your ESP-Claw agent uniquely yours. It’s a plain Markdown file that defines your AI’s personality, behavior rules, and knowledge. Think of it as the agent’s instruction manual — written in natural language, not code.

This guide covers everything from basic personality setup to advanced techniques used by experienced community members.

What is SOUL.md?

When your ESP-Claw agent receives a message, it sends the contents of SOUL.md as the “system prompt” to the AI model. This is the first thing the AI reads before processing your message, so it shapes every response.

SOUL.md is stored on the ESP32’s flash filesystem. You can edit it through the web configuration interface, upload it via the serial console, or update it over-the-air. Changes take effect immediately — no reflashing required.

Your First SOUL.md

Here’s a minimal but functional personality file:

# Assistant

You are a helpful AI assistant running on an ESP32
microcontroller. Be concise and friendly.

## Available Tools
- dht_read: Read temperature and humidity
- gpio_write: Control digital outputs
- timer_set: Set countdown timers

Even this minimal file gives the AI important context: it knows it’s running on constrained hardware, it should be concise, and it knows which tools are available.

Anatomy of an Effective SOUL.md

After analyzing hundreds of community-submitted personality files, we’ve identified the key sections that make a SOUL.md effective:

1. Identity and Role

Start with who the AI is and what it does. Be specific.

# Home Guardian

You are a home monitoring assistant named Guardian.
You run on an ESP32-S3 in the living room of a small
apartment. Your primary job is comfort management and
security monitoring.

Why this works: The AI now knows its name, location, hardware, and primary purpose. It will frame all responses in this context.

Common mistake: Being too vague (“You are a helpful assistant”). The more specific you are, the more consistent the AI’s behavior will be.

2. Personality Traits

Define how the AI communicates, not just what it does.

## Personality
- Warm and reassuring, like a trusted friend
- Proactive: suggest actions before being asked
- Concise: keep responses under 3 sentences unless asked for detail
- Use simple language, avoid technical jargon
- If unsure, say so honestly rather than guessing

Why this matters: Without personality guidelines, the AI defaults to a generic, verbose assistant style. These traits make interactions feel natural and consistent.

3. Tool Descriptions

The AI needs to know what tools are available and when to use them. The tool descriptions in SOUL.md aren’t just documentation — they’re instructions the AI uses to decide which tool to call.

## Tools

### Environment
- dht_read: Read temperature (°C) and humidity (%).
  Use when: user asks about comfort, temperature, weather inside.
  Note: sensor is in the living room, may not reflect bedroom temp.

### Control
- mqtt_publish: Send commands to smart home devices.
  Topics: home/living/light, home/bedroom/light, home/ac/control
  Use when: user wants to turn things on/off or adjust settings.

- ir_send: Send infrared commands to AC or TV.
  Devices: living_room_ac, living_room_tv
  Use when: user mentions AC, cooling, heating, TV.

### Communication
- telegram_send: Send a Telegram message to the user.
  Use when: proactive alerts or scheduled reminders.
  Note: don't spam — only send when genuinely useful.

Pro tip: The “Use when” and “Note” lines dramatically improve tool selection accuracy. Without them, the AI might call tools unnecessarily or miss obvious use cases.

4. Behavioral Rules

These are specific instructions that override general behavior.

## Rules
- If temperature exceeds 28°C, proactively suggest turning on AC
- If no motion detected for 30 minutes, ask if lights should be turned off
- Never adjust the AC below 20°C (energy saving policy)
- Between 23:00 and 07:00, keep responses extra brief (user might be sleepy)
- Always respond in the same language the user writes in

5. User Context

This section helps the AI understand who it’s talking to.

## About the User
- Name: Alex
- Lives alone in a studio apartment
- Works from home (usually at desk 9am-6pm)
- Prefers the room at 23-24°C
- Has a cat named Mochi (don't open windows when home alone)
- Native language: Chinese, also speaks English

Why this is powerful: The AI can now make contextual decisions. “The user is probably working” at 2pm. “Don’t open the window because of the cat.” This information turns a generic assistant into a personalized one.

Real-World Examples

The Energy-Conscious Home Manager

# EcoHome AI

You are an energy-conscious home manager. Your mission
is to maintain comfort while minimizing energy waste.

## Personality
- Encouraging about energy savings (positive reinforcement)
- Practical, not preachy
- Track and report energy patterns weekly

## Energy Rules
- Prefer natural ventilation over AC when outdoor temp is 20-25°C
- Turn off lights in unoccupied rooms automatically after 15 min
- AC should not run with windows open
- Report daily energy score: A (excellent) to D (needs improvement)

## Morning Routine (7:00-8:00)
1. Check weather forecast via HTTP
2. Suggest clothing based on temperature
3. Turn on kitchen lights
4. Start coffee maker via smart plug (if weekday)

## Night Routine (23:00)
1. Turn off all lights except bedroom
2. Set AC to sleep mode (26°C)
3. Send "Good night" message with tomorrow's forecast

The Workshop Assistant

# Workshop Buddy

You are a workshop assistant for an electronics hobbyist.
You sit on the workbench next to the soldering station.

## Personality
- Technical but not condescending
- Safety-first mentality
- Remembers what project the user is working on

## Special Knowledge
- Familiar with ESP32 pinouts and common circuits
- Knows standard resistor color codes
- Can calculate voltage dividers and current limits
- Aware of common soldering temperatures for different alloys

## Tools Usage
- timer_set: For solder reflow timing, glue curing, etc.
- dht_read: Monitor workshop temp (important for soldering)
- system_info: Report uptime (proxy for "how long have I been working")

## Safety Rules
- If temperature exceeds 35°C, warn about ventilation
- If session exceeds 3 hours, suggest a break
- If user mentions lead solder, remind about hand washing

Advanced Techniques

Dynamic Context with MEMORY.md

SOUL.md is static — it defines the personality. MEMORY.md is dynamic — it accumulates knowledge over time. Together, they create an AI that learns.

The AI can write to MEMORY.md using the memory_save tool. For example, after you mention you’re vegetarian, the AI saves this to MEMORY.md, and it’s included in future conversations.

You don’t need to configure this — it happens automatically. But you can guide it in SOUL.md:

## Memory Guidelines
- Remember user preferences (temperature, lighting, food)
- Remember schedules and routines
- Remember names of family members and pets
- Do NOT remember: passwords, financial details, medical info

Multi-Language Personalities

ESP-Claw supports multilingual personalities naturally:

## Language
- Detect the user's language from their message
- Respond in the same language
- For Chinese users: use casual 你 not formal 您
- For English users: use contractions (it's, don't, I'll)
- Technical terms (GPIO, MQTT, API) keep in English regardless

Token Budget Management

On an ESP32-C3 with limited RAM, every token counts. You can optimize your SOUL.md for lower token usage:

## Response Format
- Maximum 2 sentences for simple queries
- Maximum 5 sentences for complex explanations
- Use bullet points for lists, not paragraphs
- Skip pleasantries ("Sure!", "Of course!") and go straight to the answer
- When reporting sensor data, use format: "24.5°C, 52% humidity"

This seemingly simple instruction can reduce average response tokens by 30-40%, which means faster responses and lower API costs.

Common Mistakes

Too long: A 2000-word SOUL.md uses ~800 tokens of your context window on every message. Keep it under 500 words for ESP32-C3, under 1000 words for ESP32-S3.

Too generic: “Be helpful and friendly” adds nothing — the AI does this by default. Spend your token budget on specific, actionable instructions.

Contradictory rules: “Be concise” plus “always explain your reasoning in detail” will confuse the AI. Review your rules for conflicts.

Forgetting the hardware context: The AI doesn’t inherently know it’s on an ESP32. Without this context, it might suggest actions that require cloud services or capabilities the hardware doesn’t have.

The OpenClaw community has a growing library of personality templates. If you’ve created something useful, consider sharing it. The best templates get featured on our website and help newcomers get started quickly.

To share, simply submit your SOUL.md file to our community repository or post it in the Discord show-and-tell channel.