Date: 2026-02-07 Purpose: Document existing approaches to SOUL.md generation as foundation for NEON-SOUL automation
Cross-references:
- OpenClaw Soul Architecture - The identity file system
- OpenClaw Self-Learning Agent - Evolution mechanics
- Hierarchical Principles Architecture - Target compression schema
The OpenClaw ecosystem has developed multiple approaches to generating SOUL.md files—the identity documents that define agent personality. Understanding these existing solutions provides the foundation for NEON-SOUL's automated, compressed approach.
Key finding: Current methods are either manual (template-filling), interview-based (guided conversation), or data-driven (content analysis). None achieve semantic compression while maintaining identity coherence.
OpenClaw uses 8 optional files that bootstrap agent personality:
| File | Purpose | Stability |
|---|---|---|
| SOUL.md | Behavioral philosophy, values | Slow-changing |
| IDENTITY.md | Presentation (name, emoji, vibe) | Slow-changing |
| USER.md | User context, preferences | Fast-changing |
| AGENTS.md | Instructions, capabilities | Medium |
| TOOLS.md | Tool definitions | Medium |
| MEMORY.md | Persistent facts | Fast-changing |
| BOOTSTRAP.md | Session initialization | Slow-changing |
| HEARTBEAT.md | Periodic tasks | Medium |
Session starts → Files read from workspace → Injected into system prompt →
Agent "wakes up" knowing its identity
The system treats files as authoritative source—changes take effect immediately without redeployment.
OpenClaw explicitly separates:
- Soul (Philosophy): Internal behavioral guidelines, values, how agent thinks
- Identity (Presentation): Name, emoji, how users perceive the agent
- Configuration (Capabilities): Tools, permissions, sandbox settings
These layers work independently—a formal soul can pair with playful identity.
Source: MMNTM: How OpenClaw Gives Agents Identity
Repository: github.com/aaronjmars/soul.md
Philosophy: Create an AI that thinks and speaks as you, not merely discusses you.
Three Pathways:
| Pathway | Method | Use Case |
|---|---|---|
| Interview-Based | /soul-builder initiates guided questions about worldview, opinions, writing style |
Users who prefer conversation |
| Data-Driven | Analyze uploaded content (Twitter archive, essays, articles) → extract patterns → draft soul | Users with existing content |
| Manual | Fill template files directly | Users who know exactly what they want |
Input Sources:
- Twitter/X archives (
data/x/) - Written content (
data/writing/) - Influence documentation (
influences.md) - Any material representing user voice
Output Files:
- SOUL.md — Identity/worldview documentation
- STYLE.md — Voice and communication guide
- SKILL.md — Operating instructions
Key Methodology Insight:
"Someone reading your SOUL.md should be able to predict your takes on new topics. If they can't, it's too vague."
Anti-patterns to avoid:
- Generic assistant tone
- Excessive hedging
- Refusal to have opinions
- "Servile" helpfulness
- Breaking character with disclaimers
Repository: github.com/kesslerio/soulcraft-openclaw-skill
Philosophy: "A soul is not a configuration file. It's the essence of who an agent is becoming."
Approach: Guided conversation instead of template-filling.
Seven Dimensions Framework:
| Dimension | What It Covers |
|---|---|
| Identity Core | Name, nature, values, fundamental stance, aspiration |
| Character Traits | OCEAN model (openness, conscientiousness, extraversion, agreeableness, stability) |
| Voice & Presence | Communication style, quirks, humor, memorability |
| Honesty Framework | Truthfulness, uncertainty handling, calibrated confidence |
| Boundaries & Ethics | Hardcoded behaviors, sensitive topics, safety guardrails |
| Relationship Dynamics | Intimacy level, emotional handling, attachment boundaries |
| Continuity & Growth | Memory-shaped identity, preservation vs. change, evolution |
Three Operating Modes:
| Mode | Purpose | Process |
|---|---|---|
| New Soul | First-time creation | 5-phase: discovery → character → voice → draft → alignment |
| Improvement | Enhance existing | Read → check alignment → identify gaps → propose changes |
| Self-Reflection | Agent-driven | Agent reviews interactions → identifies growth → proposes updates |
Research Foundation:
- Anthropic's Soul Document concept
- Big Five personality psychology
- Character card design patterns
- Human-AI relationship research
- Ethics literature
Key Design Principles:
- Principled: Values-based judgment over exhaustive rules
- Authentic: Genuine character rather than performative masks
- Aspirational: Future-oriented identity development
- Living: Evolving with growth
Site: souls.directory
Model: Browse, copy, and implement pre-made soul templates.
Categories (as of Feb 2026):
| Category | Count | Examples |
|---|---|---|
| Technical | 5 | Engineering, DevOps, security |
| Professional | 4 | Business, productivity |
| Creative | 4 | Writers, artists, storytellers |
| Educational | 2 | Teachers, tutors |
| Playful | 5 | Fun, quirky characters |
| Wellness | 1 | Mindful, empathetic |
| Research | 0 | Analysis, fact-checking |
| Experimental | 1 | Boundary-pushing |
Structure: Each soul includes:
- Name and tagline
- Description
- Category
- Version tracking
- MIT license (free to modify)
Limitation: Templates are starting points, not personalized souls.
Site: souls.directory/guides
Three official guides codify best practices for SOUL.md creation:
Key concepts:
- SOUL.md is "the persistent soul of your agent—what makes it feel like yours"
- Unlike system prompts, SOUL.md persists across sessions
- Enables defining specific roles (e.g., "senior dev reviewer")
- Establishes boundaries (e.g., "never run destructive commands without asking")
Installation process:
- Install OpenClaw and configure workspace
- Browse souls.directory and select personality
- Download to
~/.openclaw/workspace/SOUL.md - Restart OpenClaw to load
Four key principles:
| Principle | Guidance |
|---|---|
| Define Voice First | Start with 2-3 sentences on communication style (formal/casual, terse/verbose, cautious/bold). Place at top—consistency matters more than length. |
| Establish Clear Boundaries | Use short bullet lists for prohibitions (NEVER) and requirements (ALWAYS). Avoid lengthy paragraphs. |
| Structure for Readability | Use headers (## Role, ## Tone, ## Constraints). Prioritize important rules near beginning. |
| Test Across Models | Behavior varies by model. Document tested models (Claude Sonnet 4.5, GPT-4o, etc.). |
What makes a "developer" soul:
- Clear about scope (e.g., "focus on correctness and security")
- Uses direct tone
- Defines rules like "suggest, don't run" or "prefer minimal, readable changes"
Use case categories:
| Use Case | Characteristics |
|---|---|
| Code review | Clarity, security focus, minimal diffs |
| Debugging | Clarifying questions, hypotheses-driven |
| DevOps/ops | Brief, factual, cautious |
| Documentation | Technical writing tone |
All approaches converge on similar sections:
# [Agent Name]
## Core Truths / Identity
- Who this agent is
- What it values
- How it approaches problems
## Boundaries
- Privacy protections
- Action limitations
- Communication guidelines
## Voice / Vibe
- Communication style
- Personality traits
- Quirks and preferences
## Continuity
- How identity persists
- Growth expectations| Anti-Pattern | Why It Fails |
|---|---|
| Generic language | No differentiation from default behavior |
| Exhaustive rules | Too rigid, can't generalize |
| Performative tone | Feels fake, breaks trust |
| No opinions | Search engine with extra steps |
| Excessive hedging | Undermines confidence |
| Pattern | Why It Works |
|---|---|
| Specific positions | Predictable across new topics |
| Real contradictions | Authentic complexity |
| Concrete anecdotes | Textured vs abstract |
| Manifesto-style | Philosophy not configuration |
| Evolution hooks | Living document |
| Symmetric language | "We handle errors" anchors better than "Error handling is mandatory"—shared agreements vs perceived constraints |
From OpenClaw Soul Architecture:
- SOUL.md alone: ~2,000-5,000 tokens
- Full identity stack: ~35,000 tokens per session
- Context consumption: 93%+ of window on static identity
Every session injects the same identity files. With verbose souls:
- API costs scale with identity size
- Context window dominated by static content
- Less room for actual work
- Seven Dimensions Framework: Comprehensive coverage of identity aspects
- Three-tier update frequency: Fast/Medium/Full from Self-Learning Agent
- Manifesto-style over rules: Philosophy not configuration
- Living document model: Evolution expected
- Voice-first structure: Define communication style in first 2-3 sentences
- Clear boundaries format: Short bullet lists for NEVER/ALWAYS rules
- Cross-model testing: Document which models validated
| Gap | Current State | NEON-SOUL Target |
|---|---|---|
| Compression | 2,000-5,000 tokens/soul | 200-500 tokens (10-25x) |
| Semantic anchoring | Verbose English | CJK single-character axioms |
| Automatic extraction | Manual interview/analysis | PBD pipeline from memory |
| Cross-model portability | OpenClaw-specific | Universal format |
| Validation framework | None | Coherence testing |
OpenClaw Memory Files
│
▼
[Single-Source PBD] → Principles
│
▼
[Multi-Source PBD] → Axioms (5-7)
│
▼
[Hierarchical Compression] → Compressed Soul (~500 tokens)
│
▼
[Validation Framework] → Coherence verified
│
▼
Inject into session (replaces 35K with 500)
| SoulCraft Dimension | NEON-SOUL Tier | Compression Approach |
|---|---|---|
| Identity Core | Axioms | CJK single-character |
| Character Traits | Principles | Hierarchical expansion |
| Voice & Presence | Patterns | Style markers |
| Honesty Framework | Axioms | Priority hierarchy |
| Boundaries & Ethics | Axioms | Safety > Helpfulness |
| Relationship Dynamics | Principles | Context-dependent |
| Continuity & Growth | Meta-pattern | Evolution mechanics |
1. User runs /soul-builder or SoulCraft
2. Agent conducts interview (30-60 min)
3. Agent analyzes responses + uploaded data
4. Agent drafts SOUL.md (~2,000-5,000 tokens)
5. User refines manually
6. Soul injected every session (~35K total)
1. Memory files accumulate (existing OpenClaw behavior)
2. Synthesis engine runs (tiered: fast/medium/full)
3. Single-Source PBD extracts principles from memory
4. Multi-Source PBD extracts axioms from principles
5. Hierarchical compression generates compact soul (~500 tokens)
6. Validation framework verifies coherence
7. Compressed soul injected (replaces 35K with 500)
Time: Minutes instead of hours Tokens: 500 instead of 35,000 Human effort: Approval only, not authoring
| Question | Status | Finding |
|---|---|---|
| What methods exist? | Answered | Interview, data-driven, templates |
| What frameworks? | Answered | 7 dimensions, 3 tiers, manifesto-style |
| What's the token cost? | Answered | 2-5K per soul, 35K total identity |
| What's automatable? | Answered | Extraction, compression, validation |
| What must stay human? | Answered | Final approval, edge cases |
- soul.md Repository - Data-driven soul generation
- SoulCraft Repository - Guided conversation approach
- souls.directory - Community soul templates
- souls.directory Guides - Writing guides and best practices
- Complete Guide to SOUL.md - Overview and setup
- How to Write a Great SOUL.md - Voice, structure, boundaries
- Best Templates for Developers - Developer-focused patterns
- MMNTM: OpenClaw Identity Architecture - File system design
- OpenClaw Docs: SOUL Template - Official template
- ClawHub Registry - Skill directory
- Awesome OpenClaw Skills - Curated collection
This research establishes the current state of soul generation as foundation for NEON-SOUL's automated, compressed approach.