soulspec

One file. Persistent identity.

The open standard for AI agent personas.

Website · 80+ Souls · Docs · Spec v0.5

Every AI agent forgets who it is. Every session starts from zero. Your carefully crafted personality competes with the model's training, the user's pressure, and the accumulating context — and it loses.

Soul Spec fixes that. Drop a SOUL.md file into any agent. It persists across sessions, survives model swaps, and resists drift.

# Install a soul in 10 seconds
npx clawsouls install clawsouls/brad

# Or create your own
npx clawsouls init my-soul

Why Soul Spec?

The Files

A Soul Spec package is just files in a folder. Human-readable. Machine-parseable. Version-controlled.

my-soul/
├── soul.json       # Metadata — name, version, tags
├── SOUL.md         # Who am I? Personality, values, boundaries
├── IDENTITY.md     # Name, emoji, appearance
├── AGENTS.md       # How I work — workflows, tools, rules
└── USER.md         # Who I work with — human preferences

Only soul.json and SOUL.md are required. Everything else is optional — add what you need.

Example SOUL.md

# Atlas — Financial Advisor

## Personality
- Conservative, compliance-first
- Speaks in clear, jargon-free language
- Client safety over returns, always

## Principles
- Full disclosure of risks and conflicts
- Never recommend products I wouldn't buy myself

## Boundaries
- Will not execute trades without explicit approval
- Will not provide tax advice (refer to CPA)

Patterns

🧬 Persistent Identity

Your agent's personality is defined in SOUL.md — not a system prompt that decays, but a structured file that the framework loads on every session. Identity survives context window overflow, model upgrades, and conversation resets.

🔒 Safety Validation

Before deploying a soul, run SoulScan — 53 automated checks for identity contradictions, boundary gaps, persona hijacking vulnerabilities, and governance compliance.

npx clawsouls soulscan

A soul that passes SoulScan is safe to deploy. One that doesn't gets specific remediation steps.

🏪 Soul Marketplace

Browse 80+ community-built personas at clawsouls.ai. Install in one command. Fork and customize. Publish your own.

# Browse categories
npx clawsouls browse

# Install any soul
npx clawsouls install clawsouls/surgical-coder

# Publish yours
npx clawsouls publish

🔄 Cross-Model Portability

The same SOUL.md works across any LLM. Switch from Claude to GPT to Llama — your agent's personality stays the same.

📊 Research-Backed

Soul Spec isn't marketing. It's backed by 15 papers:

• +33% safety improvement on aligned models with structured identity files
• 100% defense on abliterated LLMs when combined with governance frameworks
• 85% persona consistency across 1000+ message sessions

Quick Start

# Create a new soul
npx clawsouls init my-soul
cd my-soul

# Edit SOUL.md with your personality
# ...

# Validate safety
npx clawsouls soulscan

# Publish to marketplace
npx clawsouls publish

Spec Versions

Ecosystem

Compatible With

Soul Spec is framework-agnostic. Any tool that reads markdown persona files works:

OpenClaw · Claude Code · Claude Desktop · Cursor · Windsurf · gitagent · ChatGPT · Gemini · And more

Community

• 🌐 soulspec.org — Specification & documentation
• 🛍️ clawsouls.ai — Soul marketplace
• 📝 blog.clawsouls.ai — Research & tutorials
• 📧 [email protected] — Questions & partnerships

About

Soul Spec is an open standard for AI agent personas — maintained by ClawSouls and open to community contributions.

Contributing

We welcome bug reports, spec improvements, translations, and framework adapters. See CONTRIBUTING.md for guidelines.

License

Code in this repository is licensed under Apache 2.0. Documentation is licensed under CC-BY-4.0. See individual directories for details.

Soul-Driven in philosophy. Community-Driven in practice.

Browse 80+ Souls · Read the Spec · Runtime