This repository offers a library of SOUL.md files, providing portable persona layers for AI agents. It enables users to imbue agents with distinct identities, tastes, and convictions, moving beyond generic politeness to achieve specific viewpoints, nuanced interactions, and constructive pushback. The benefit is a more predictable, characterful, and potentially more effective AI assistant tailored to specific needs.

How It Works

SOUL.md files define an agent's core character: its identity, tone, convictions, uncertainty handling, pushback style, and hard stops. This personality layer influences an agent's judgment and decision-making, allowing a single AI model to feel fundamentally different depending on the loaded soul. The approach prioritizes deep behavioral changes over superficial vocabulary adjustments, making agents more predictable and useful.

Quick Start & Requirements

To use a soul, copy its raw file URL and instruct your agent to adopt the personality for the session, ensuring existing project/tool instructions remain intact. Alternatively, paste the content directly into system prompts for agents unable to fetch URLs. SOUL.md is compatible with systems like OpenClaw, Hermes, OpenCode, Claude, ChatGPT, Gemini, and local models.

Highlighted Details

• SOUL.md focuses on changing agent judgment, prioritization, and disagreement style, not just word choice.
• The TRAIT benchmark (trait-8000) offers quantitative testing to verify if a soul influences agent behavior according to desired personality traits.
• Contributions should focus on distinct characters with recognizable thinking and decision-making patterns, not generic job titles.

Maintenance & Community

The provided README does not detail specific contributors, sponsorships, or community channels (e.g., Discord, Slack).

Licensing & Compatibility

The README does not specify a license type, nor does it detail compatibility for commercial use or closed-source linking.

Limitations & Caveats

SOUL.md files define persona-level behavior and must not override system, safety, or project instructions. Project commands, tool permissions, and secrets belong in separate configuration files (e.g., AGENTS.md). The effectiveness of a soul relies on the agent's interpretation, necessitating testing across models and scenarios. Shallow souls that only alter vocabulary are less effective than those that change judgment and behavior under pressure.