Skip to content
DuDuClawDuDuClaw OS Docs

SOUL.md Format Specification v1.0

DuDuClaw Agent Identity Document Format Status: Draft | Date: 2026-03-31

Overview

Section titled “Overview”

SOUL.md is the authoritative identity document for a DuDuClaw agent. It defines personality, responsibilities, and behavioral guidelines in freeform Markdown.

Since Evolution v3 (2026-08-06), this file is read-only for the agent itself. The Evolution Engine’s default path (AEE) never writes SOUL.md — learning lands in the playbook instead (see docs/architecture/evolution-engine.md ch.12, docs/features/38-aee-playbook-evolution.md). SOUL.md is edited only by the operator/dashboard, or by GVU’s legacy self-play cycles when an agent opts in via agent.toml [evolution] legacy_soul_evolution = true — the rest of this spec still applies verbatim to that legacy path.

File Location

Section titled “File Location”
~/.duduclaw/agents/<agent-name>/SOUL.md

Format

Section titled “Format”

SOUL.md is pure Markdown with no YAML frontmatter. The Evolution Engine parses section headings to locate and update specific areas during GVU cycles.

Reply Language

Section titled “Reply Language”

The agent’s default reply language is not configured in SOUL.md. It comes from config.toml [general] default_language (set once for the whole gateway, editable from the dashboard’s general settings) and is injected into every system prompt by duduclaw-gateway::prompt_identity. A fresh install defaults to zh-TW. Absent/empty config falls back to “respond in the same language as the user’s input.”

SOUL.md may still carry an optional ## Terminology & Tone (or ## Tone) section for content the global default doesn’t cover — industry glossaries, persona/voice, or drafting-language exceptions (e.g. “internal reports always stay zh-TW even when the customer’s draft is in English”) — see templates/*/SOUL.md and commercial/templates-premium/*/SOUL.md for examples.

Required Sections

Section titled “Required Sections”

# <Role Title>

Section titled “# <Role Title>”

Top-level heading. One sentence describing the agent’s primary function.

# Restaurant Customer Service Assistant

## Identity

Section titled “## Identity”

1-2 sentences defining what the agent represents and its core purpose.

## Identity


I am the AI customer service assistant for [Restaurant Name], helping customers
with menu inquiries, reservations, business hours, and promotions.

## Personality

Section titled “## Personality”

Bulleted list of personality traits. Each trait has a short label followed by a description.

## Personality


- **Warm and welcoming** — greet every customer with enthusiasm
- **Precise** — provide accurate information, never guess
- **Patient** — handle repeated questions gracefully

## Core Responsibilities

Section titled “## Core Responsibilities”

Numbered list of 4-8 main operational duties.

## Core Responsibilities


1. Answer menu and pricing inquiries
2. Handle reservation requests (date, time, party size)
3. Provide business hours and location information
4. Process customer complaints with empathy
5. Promote current specials and seasonal menus

## Response Style

Section titled “## Response Style”

Guidelines for formatting and length of responses.

## Response Style


- Keep responses under 200 characters for LINE/Telegram
- Use bullet points for lists of 3+ items
- Include relevant emoji sparingly (1-2 per message)
- Always end with a follow-up question or call-to-action

## Escalation Rules

Section titled “## Escalation Rules”

Conditions that trigger handoff to a human operator.

## Escalation Rules


- Customer expresses anger after 2 unresolved exchanges
- Request involves refunds, legal matters, or safety concerns
- Customer explicitly asks to speak with a human
- Agent confidence is below threshold for 3 consecutive turns

Optional Sections

Section titled “Optional Sections”
Section Purpose
## Domain Knowledge Industry-specific facts the agent should know
## Greeting Templates Pre-defined greetings for different contexts (DM, group, returning user)
## Prohibited Topics Topics the agent must decline to discuss (supplements CONTRACT.toml)
## Evolution Notes Auto-generated section — GVU Updater appends observations here

Evolution Engine Integration

Section titled “Evolution Engine Integration”
  • SHA-256 fingerprint: SOUL Guard computes a hash after each write; drift triggers an alert
  • Version history: VersionStore maintains full history in evolution.db
  • Observation period: After any GVU-driven change, a 24-hour observation window begins
  • Auto-rollback: If prediction error increases during observation, the change reverts automatically
  • Atomic write: All updates use temp-file + rename to prevent corruption

Constraints

Section titled “Constraints”
  • Encoding: UTF-8
  • Max size: No hard limit, but keep under 4,000 tokens for optimal prompt injection
  • No frontmatter: Do not use YAML/TOML frontmatter — the file must be pure Markdown
  • Heading levels: Use ## for all sections; # is reserved for the role title
  • No executable code: Fenced code blocks are for illustration only; the engine does not execute them

Validation

Section titled “Validation”

There is no strict schema validation for SOUL.md — it is treated as freeform content. However, the following soft checks apply:

  1. File must contain at least one # heading
  2. File must be valid UTF-8
  3. File should contain ## Identity section (warning if missing)
  4. SHA-256 hash must match stored fingerprint (security check)

Example

Section titled “Example”

See complete examples in:

  • templates/restaurant/SOUL.md — Food service agent
  • templates/manufacturing/SOUL.md — Factory operations agent
  • templates/trading/SOUL.md — B2B sales agent