Soul.md provides a declarative, provider-agnostic specification for defining AI agent personas. It allows developers to separate an agent's identity, voice, interaction style, and behavioral characteristics from its underlying code and tools. This enables consistent AI behavior across diverse platforms like OpenAI, Anthropic, local models, and custom runtimes, offering benefits in portability, reusability, testability, and adaptability for AI systems.

How It Works

Soul.md uses a YAML-based specification to define an AI agent's persona. It details core aspects such as identity, role, voice (formality, warmth, verbosity), interaction policies (clarifying questions, disagreement handling), cognition, decision-making, social dynamics, and safety guardrails. The approach emphasizes separation of concerns, allowing personas to be managed independently. Advanced features like composition (extending base personas and mixing traits) and profiles (switching between predefined modes like 'default', 'concise', or 'friendly') enhance flexibility and reusability. Dynamic state transitions, or "moods," allow agents to adapt their persona based on contextual triggers.

Quick Start & Requirements

The core of the project is the specification itself, defined in YAML. Usage examples demonstrate hypothetical commands like soul-loader --soul=Soul.md --profile=default for runtime integration and soul-validate Soul.md --strict for conformance testing. Specific runtime tools are required to interpret and apply Soul.md files. Links to the Full Specification, Quick Start Guide, Authoring Method, Extended Examples, JSON Schema, and Conformance Tests are available within the project's documentation.

Highlighted Details

• Comprehensive Persona Definition: Covers identity, voice, interaction, cognition, decision-making, social dynamics, and safety.
• Composition & Modularity: Supports inheriting from base personas and mixing reusable traits for complex agent definitions.
• Dynamic Adaptability: Features like profiles and trigger-based state transitions (moods) allow agents to adapt their behavior dynamically.
• Testability: Includes automated conformance checks via a test suite (CTS-1) and a JSON schema for validation.

Maintenance & Community

The project is currently in a Draft (RFC-1) status, with version 1.0.0-rc1 released. Key components like the core specification, JSON schema, examples, and test suite layout are complete. Planned roadmap items include reference implementations, runtime integrations (e.g., OpenAI, LangChain), and community feedback incorporation. Discussions and issue tracking are managed via GitHub. The project is maintained by Emil Rokossovskiy.

Licensing & Compatibility

The Soul.md specification is licensed under CC-BY-4.0. This permissive license allows for broad use, including commercial applications, provided attribution is given. Soul.md files created by users are their own property and can be licensed independently.

Limitations & Caveats

As a draft specification (RFC-1, 1.0.0-rc1), Soul.md is still under active development. Reference implementations and integrations with popular AI runtimes are not yet complete, meaning practical adoption may require building custom tooling. The full specification is extensive (over 200 pages), suggesting a potentially steep learning curve for mastering all its capabilities.