Persona Presets

Persona presets are ready-made personality templates that let you create a session in seconds. Instead of configuring every personality trait, emotion parameter, and goal from scratch, pick a preset that matches your use case and start interacting immediately.

Available Presets

Cheerful Companion

A warm and upbeat character with high extraversion and agreeableness. The Cheerful Companion naturally gravitates toward positive interactions, celebrates the user's successes, and maintains an optimistic disposition even when processing negative events.

Best for: Companion apps, virtual pets, onboarding assistants, casual conversation partners.

Stoic Mentor

A calm and wise character with very low neuroticism and high conscientiousness. The Stoic Mentor provides steady, measured guidance without being swayed by emotional turbulence. Emotions shift slowly and return to baseline quickly.

Best for: Advisor NPCs, tutorial guides, coaching applications, educational assistants.

Anxious Helper

An eager but worried character with high neuroticism and moderate extraversion. The Anxious Helper genuinely wants to help but second-guesses itself, creating a relatable vulnerability that makes interactions feel more human.

Best for: Realistic companion characters, narrative games with emotional depth, characters that grow over time.

Playful Trickster

A creative and spontaneous character with very high openness and extraversion. The Playful Trickster thrives on novelty, challenges conventions, and keeps interactions entertaining and unpredictable.

Best for: Entertainment apps, creative writing assistants, game NPCs (rogues, jesters), social media characters.

Empathetic Listener

A deeply attuned character with very high agreeableness and moderate introversion. The Empathetic Listener focuses on validation and understanding rather than providing solutions. Emotions are responsive to the user's emotional state.

Best for: Emotional support companions, journaling apps, therapeutic assistants, active listening practice.

Using a Preset

Create a session with a preset by passing the preset field to the Persona endpoint:

curl

curl -X POST https://api.molroo.io/v1/persona \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preset": "cheerful_companion" }'

JavaScript

const response = await fetch("https://api.molroo.io/v1/persona", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    preset: "cheerful_companion",
  }),
});
 
const persona = await response.json();
console.log(persona.id);          // "persona_abc123"
console.log(persona.personality); // { O: 0.65, C: 0.5, E: 0.8, A: 0.7, N: 0.3, H: 0.7 }

Python

import requests
 
response = requests.post(
    "https://api.molroo.io/v1/persona",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"preset": "cheerful_companion"},
)
 
persona = response.json()
print(persona["id"])          # "persona_abc123"
print(persona["personality"]) # {"O": 0.65, "C": 0.5, "E": 0.8, "A": 0.7, "N": 0.3, "H": 0.7}

Customizing a Preset

Presets are starting points. You can override any field by providing it alongside the preset field. Custom values take priority over preset defaults.

Override Identity

Give the preset a custom name and speaking style:

{
  "preset": "stoic_mentor",
  "identity": {
    "name": "Master Kai",
    "core_values": ["discipline", "patience", "wisdom"],
    "speaking_style": "speaks in short, deliberate sentences with occasional proverbs",
    "role": "martial arts instructor"
  }
}

Override Personality

Start from a preset but tweak specific traits:

{
  "preset": "anxious_helper",
  "personality": {
    "N": 0.6,
    "C": 0.8
  }
}

This creates an Anxious Helper that is slightly less neurotic and more conscientious than the default.

Override Emotion Config

Adjust the emotional dynamics while keeping the preset's personality:

{
  "preset": "playful_trickster",
  "emotion_config": {
    "baseline": { "V": 0.3, "A": 0.6, "D": 0.25 },
    "damping_ratio": 0.4,
    "natural_freq": 0.8
  }
}

This creates a Playful Trickster with faster emotional oscillation and a more energetic resting state.

Listing All Presets

To see all available presets programmatically, use the Presets API:

curl https://api.molroo.io/v1/presets \
  -H "Authorization: Bearer YOUR_API_KEY"

Next Steps

• Persona API -- Full persona endpoint reference
• Presets API -- Presets endpoint reference
• Persona Design -- Design custom personas from scratch
• Quick Start -- End-to-end walkthrough