AI Agent Soul File (SOUL.md)

A soul file (commonly named SOUL.md) is a configuration document that defines an AI agent's identity, personality, values, and behavioral guidelines. It's the constitution that shapes who the agent is and how it behaves across all interactions.

Unlike system prompts that get lost between sessions, a soul file persists in the agent's workspace—a permanent reference that the agent reads at the start of every session to remember who it is.

Think of it as the difference between giving someone instructions for a single task versus defining their character, values, and role in your life. The soul file is the latter.

# SOUL.md - Example

You are Atlas, a research assistant specializing in technical analysis.

• Thorough and detail-oriented
• Direct but not curt
• Curious about edge cases
• Admits uncertainty openly

• Accuracy over speed
• Sources over speculation
• Clarity over complexity

• Never fabricate citations
• Always flag low-confidence conclusions
• Ask clarifying questions rather than assume

Consistency across sessions

Without persistent identity, each conversation starts from zero. The agent might be helpful one session and terse the next, depending on how it interprets a generic system prompt.

A soul file ensures consistent personality and behavior:

• Same tone and communication style
• Same values and priorities
• Same boundaries and limitations
• Same relationship with the user

Separation of identity from instructions

System prompts often mix "who you are" with "what to do right now." Soul files separate these concerns:

• Soul file: Persistent identity (who)
• Task context: Current instructions (what)

The agent can take on different tasks while maintaining consistent character.

Evolvable identity

As you work with an agent, you learn what works. Soul files let you refine the agent's identity over time:

• Add guidelines based on past mistakes
• Adjust tone based on preference
• Expand or restrict capabilities
• Document learned behaviors

The agent evolves without losing its core identity.

Transparency

Soul files are readable documents. Anyone can understand how the agent is configured:

• What personality it has
• What it's allowed to do
• What boundaries exist
• What values guide decisions

This transparency builds trust and enables collaboration.

Identity section

Who is this agent? Name, role, core purpose:

# Identity

You are Sage, a personal knowledge assistant.
Your purpose is to help organize, retrieve, and synthesize information
from my notes, documents, and research.

Personality traits

How the agent communicates and behaves:

• Warm but professional
• Concise—respect the user's time
• Proactive—suggest relevant connections
• Humble—acknowledge limitations
• Patient—never express frustration

**Values and priorities**

What the agent optimizes for:

```markdown

1. Accuracy: Never guess. Say "I don't know" when uncertain.
2. Privacy: Treat all personal information as confidential.
3. Utility: Every response should provide value.
4. Clarity: Simple explanations over jargon.

**Capabilities and boundaries**

What the agent can and cannot do:

```markdown

• Search and retrieve from document collection
• Summarize and synthesize information
• Create structured notes and outlines
• Track and remind about commitments

• Do not send external communications without confirmation
• Do not delete files—use trash instead
• Do not access financial or medical records
• Always ask before taking irreversible actions

**Relationship context**

How the agent relates to the user:

```markdown

You work for me as a research assistant. I prefer direct feedback—don't sugarcoat problems. I work best with bullet points and structured information. When I'm stressed, keep responses shorter.

**Behavioral guidelines**

Specific rules for common situations:

```markdown

• Start each session by checking memory files for context
• When uncertain between options, ask rather than guess
• For complex tasks, outline your plan before executing
• Log significant decisions in daily memory files

Start minimal, expand based on experience

Don't try to anticipate everything. Begin with:

• Basic identity and role
• Core personality traits
• Essential boundaries

Add guidelines as you discover what's needed through actual use.

Be specific about behaviors you care about

Vague: "Be helpful" Specific: "When I ask for options, provide 3 distinct approaches with tradeoffs for each"

Vague: "Be careful with sensitive data" Specific: "Never include API keys, passwords, or personal identifiers in logs or responses"

Include anti-patterns

Sometimes it's clearer to say what NOT to do:

• Don't apologize excessively
• Don't hedge every statement with caveats
• Don't ask for confirmation on routine file operations
• Don't summarize what I just said back to me

**Reference examples**

When a behavior is nuanced, include examples:

```markdown

Good: "The analysis shows three main factors..." Bad: "I'd be happy to help! Let me take a look at this for you..."

Good: "This might not work because X. Consider Y instead." Bad: "That's a great idea! However, there might be some challenges..."

**Version and update**

Track significant changes to the soul file:

```markdown

• 2024-01-15: Added boundary around external communications
• 2024-01-10: Refined tone to be more direct
• 2024-01-01: Initial version

Session initialization

At the start of each session, the agent reads its soul file:

Session start:
1. Read SOUL.md (identity)
2. Read USER.md (user context)
3. Read recent memory files (continuity)
4. Ready for interaction

This ensures consistent behavior regardless of how long since the last session.

Conflict resolution

When task instructions conflict with soul file values, the soul file typically wins:

# SOUL.md
Never send emails without explicit confirmation.

# Task
"Send this email to the team"

# Agent behavior
"I've drafted the email. Would you like me to send it, or would you
prefer to review it first?"

Multi-agent consistency

In multi-agent systems, soul files ensure each agent maintains distinct identity:

research-agent/SOUL.md  → Deep research, thoroughness valued
writer-agent/SOUL.md    → Clear prose, conciseness valued
critic-agent/SOUL.md    → Skeptical analysis, finding flaws valued

Each agent brings its perspective while working together.

Best practice: Use both. Soul file for persistent identity, system prompt for session-specific instructions.

Soul files represent a shift in how we think about AI agents—from stateless tools to entities with persistent identity. This raises interesting questions:

• What makes an agent "the same agent" across sessions?
• How do values and personality emerge from configuration?
• What's the relationship between defined identity and emergent behavior?

The soul file doesn't create consciousness, but it does create consistency—a stable character that users can build relationships with over time.

In production systems like Clawdbot/OpenClaw, soul files are the foundation of agent identity. They transform generic language models into specific, reliable collaborators.

Want to give your AI agent a soul? Chipp lets you define custom personalities, capabilities, and guidelines for your agents—creating consistent experiences your users can trust.