PERSONA.md
The open spec for AI Personas.
Define who your agent is. Version it. Guarantee it holds.
Most behavioral specifications for AI agents are incomplete — a flat system prompt that captures tone and tasks but leaves character, values, normative commitments, and metacognition unspecified. PERSONA.md is the open standard for the complete picture: a declarative format covering ten layers of agent personhood, portable across every model, and auditable when regulators ask.
What it is
The behavioral layer is the most critical part of any AI system. It has never had a complete standard. Until now.
PERSONA.md is a declarative spec — YAML frontmatter and Markdown — that captures ten layers of agent personhood: identity, character, personality, cognition, affect, drives & values, normative self-regulation, memory, metacognition, and the interface it presents to the world. It is the source of truth for who your agent is. Change models. Change frameworks. The spec stays.
It works at two levels. A PERSONA.md at the project root establishes the shared behavioral baseline every agent in the project inherits — the limits none of them cross, the character the project embodies. Individual agents live in .personaxis/personas/ and extend that baseline with everything specific to their role.
MIT licensed. Published on GitHub. The standard belongs to the community — Personaxis builds the tooling, runtime, and platform around it: registry, Evaluator, governance, and the Proxy that enforces the spec at inference time.
Ten dimensions
Each maps to a field in the spec. Together they define an AI Persona completely.
identity:
Who the agent is
character:
Values and principles
personality:
Style and temperament
cognition:
How it reasons
affect:
Emotional tendencies
drives_values:
Goals and value hierarchy
normative_self_reg:
Principled refusals
memory:
What persists across sessions
metacognition:
Self-model and meta-awareness
persona:
How it presents itself
How it works
01
Write
Run personaxis init and fill in each layer of your AI Persona.
02
Validate
The CLI checks your spec against the schema and flags missing or contradictory fields.
03
Compile
Generate SOUL.md for OpenClaw, rules for Cursor, system prompts for Claude — from one source.
04
Publish
Publish to the registry. Versioned, signed, and available to pull from any machine or team.
Fits your stack
PERSONA.md completes the triangle — it does not replace the standards you already use.
AGENTS.md
What your agent does in the repo
SKILL.md
What your agent can do
PERSONA.md
Who your agent is
Why we built it.
Five beliefs about AI agents, character drift, and why the spec was missing.