Persona Design

A well-designed persona produces realistic, consistent emotional responses. This guide covers how to start from presets, configure personality traits, fine-tune emotion dynamics, and set up character identity.

Start with a Preset

Presets are pre-configured persona templates that give you a solid starting point. Pick a preset, then customize the parts you want to change.

Available Presets

Using a Preset

Create a session with a preset and optionally override specific fields:

curl -X POST https://api.molroo.io/v1/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "companion",
    "identity": {
      "name": "Luna",
      "speaking_style": "warm and thoughtful, uses metaphors",
      "language": "en"
    }
  }'

const session = await fetch("https://api.molroo.io/v1/session", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    preset: "companion",
    identity: {
      name: "Luna",
      speaking_style: "warm and thoughtful, uses metaphors",
      language: "en",
    },
  }),
}).then((r) => r.json());

The preset fills in personality traits, emotion config, and baseline values. Your identity overrides (name, speaking style, etc.) are applied on top.

When to Use Presets vs Custom Personas

Identity Configuration

The identity block defines who your character is beyond personality numbers:

{
  "identity": {
    "name": "Luna",
    "core_values": ["empathy", "curiosity", "honesty"],
    "speaking_style": "warm and thoughtful, uses metaphors",
    "role": "companion",
    "goals": ["help users feel heard", "encourage self-reflection"],
    "language": "en"
  }
}

Tips:

• Choose 2-5 core values that create interesting tension (e.g., "honesty" and "kindness" can conflict)
• Be specific with speaking style -- "formal British English with dry humor" is better than "talks normally"
• Goals help the engine determine what events are relevant to the character

Personality (HEXACO)

The HEXACO model extends the Big Five with a sixth factor (Honesty-Humility). Each trait ranges from 0 to 1.

How Personality Affects Emotions

The engine uses your Big 5 trait values (O, C, E, A, N) to automatically derive 40+ internal parameters that control emotion dynamics. You do not need to configure these parameters manually -- they are computed from the personality traits:

• High Neuroticism -- Stronger negative emotional reactions, slower recovery from distress
• High Agreeableness -- More empathetic responses, less anger from social friction
• High Openness -- Greater curiosity-driven excitement, stronger aesthetic emotions
• Low Extraversion -- Subdued positive emotions, preference for calm states
• High Conscientiousness -- Stronger reactions to disorder/failure, satisfaction from completion
• High Honesty-Humility -- Stronger moral emotions, discomfort with deception

Optional Facets

Each HEXACO domain has 4 facets (24 total) for fine-grained control. Facets are optional -- if omitted, they are derived from the domain-level trait value.

Using Facets

{
  "personality": {
    "O": 0.9,
    "C": 0.4,
    "E": 0.6,
    "A": 0.5,
    "N": 0.6,
    "H": 0.7,
    "facets": {
      "O": {
        "creativity": 0.95,
        "unconventionality": 0.85,
        "aesthetic_appreciation": 0.9,
        "inquisitiveness": 0.8
      },
      "N": {
        "anxiety": 0.4,
        "sentimentality": 0.8
      }
    }
  }
}

In this example, the character has high Openness overall, with particularly strong creativity and unconventionality. Within Neuroticism, they have low anxiety but high sentimentality -- meaning they are emotionally moved by beautiful or meaningful things but do not get stressed easily.

When to use facets:

• When a character has contradictions within a trait domain (e.g., high sociability but low social boldness)
• When you need precise control over specific emotional responses
• When two characters share the same domain-level trait but should feel different

Example Personas

Gentle Mentor -- Patient, emotionally stable, values growth:

{
  "personality": {
    "O": 0.7, "C": 0.8, "E": 0.5,
    "A": 0.9, "N": 0.2, "H": 0.9
  }
}

Fiery Artist -- Passionate, emotionally volatile, creative:

{
  "personality": {
    "O": 0.95, "C": 0.3, "E": 0.7,
    "A": 0.4, "N": 0.8, "H": 0.6
  }
}

Stoic Strategist -- Calculated, reserved, emotionally controlled:

{
  "personality": {
    "O": 0.5, "C": 0.9, "E": 0.2,
    "A": 0.3, "N": 0.1, "H": 0.7
  }
}

Emotion Configuration

Fine-tune how your character's emotions behave over time. These settings are optional -- the engine derives sensible defaults from personality traits.

Baseline

The resting emotional state your character returns to when no events are occurring:

{
  "emotion_config": {
    "baseline": { "V": 0.2, "A": 0.3, "D": 0.1 }
  }
}

Damping Ratio

Controls how quickly emotions return to baseline after a disturbance.

{
  "emotion_config": {
    "damping_ratio": 0.7
  }
}

Recommended: 0.5-0.8 for most characters. Use lower values for dramatic, emotionally volatile characters and higher values for stoic, stable ones.

Natural Frequency

Controls the speed of emotional oscillation -- how quickly the emotion dynamics system responds.

{
  "emotion_config": {
    "natural_freq": 0.5
  }
}

Inertia Coefficient

Resistance to emotional change. Higher values make the character harder to shift emotionally.

{
  "emotion_config": {
    "inertia_coefficient": 0.3
  }
}

Appraisal Weights

Customize how much each appraisal dimension influences the emotional outcome:

{
  "emotion_config": {
    "appraisal_weights": {
      "goal_relevance": 1.0,
      "goal_congruence": 1.2,
      "expectedness": 0.8,
      "controllability": 0.6,
      "agency": 0.5,
      "norm_compatibility": 1.0
    }
  }
}

Use this to create characters who are more sensitive to certain types of events. For example:

• A character with high norm_compatibility weight reacts strongly to moral violations
• A character with high controllability weight is more affected by feeling helpless
• A character with low expectedness weight is less surprised by unexpected events

Putting It All Together

Here is a complete custom persona configuration using a preset as a base with overrides:

curl -X POST https://api.molroo.io/v1/session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "creative",
    "identity": {
      "name": "Aria",
      "core_values": ["creativity", "independence", "authenticity"],
      "speaking_style": "Direct and witty, occasionally sarcastic, uses vivid imagery",
      "role": "artist and mentor",
      "goals": ["inspire creative expression", "challenge assumptions"],
      "language": "en"
    },
    "personality": {
      "O": 0.9, "C": 0.4, "E": 0.6,
      "A": 0.5, "N": 0.6, "H": 0.7,
      "facets": {
        "O": { "creativity": 0.95, "unconventionality": 0.85 },
        "N": { "anxiety": 0.4, "sentimentality": 0.8 }
      }
    },
    "emotion_config": {
      "baseline": { "V": 0.15, "A": 0.45, "D": 0.2 },
      "damping_ratio": 0.55,
      "natural_freq": 0.6,
      "inertia_coefficient": 0.25,
      "appraisal_weights": {
        "goal_relevance": 1.0,
        "goal_congruence": 1.1,
        "expectedness": 0.7,
        "controllability": 0.8,
        "agency": 0.6,
        "norm_compatibility": 1.2
      }
    }
  }'

This creates a character who is:

• Creatively passionate (high O, moderate E, boosted creativity facet)
• Emotionally responsive but not unstable (moderate N, low damping, low anxiety but high sentimentality)
• Sensitive to authenticity violations (high norm_compatibility weight)
• Quick to react but settles naturally (moderate natural_freq, low inertia)

Or build a fully custom persona without any preset:

const session = await fetch("https://api.molroo.io/v1/session", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    identity: {
      name: "Aria",
      core_values: ["creativity", "independence", "authenticity"],
      speaking_style: "Direct and witty, occasionally sarcastic, uses vivid imagery",
      role: "artist and mentor",
      goals: ["inspire creative expression", "challenge assumptions"],
      language: "en",
    },
    personality: {
      O: 0.9, C: 0.4, E: 0.6,
      A: 0.5, N: 0.6, H: 0.7,
    },
    emotion_config: {
      baseline: { V: 0.15, A: 0.45, D: 0.2 },
      damping_ratio: 0.55,
      natural_freq: 0.6,
      inertia_coefficient: 0.25,
    },
  }),
}).then((r) => r.json());