molroo docs
SDK ReferenceTypes

Configuration Types

PersonaConfigData, Identity, PersonalityTraits, Goal, and related persona setup types.

Configuration Types

Types used when creating and configuring molroo personas.

import type {
  PersonaConfigData,
  PersonalityTraits,
  Identity,
  Goal,
  SimConfig,
  CalibrationConfig,
} from '@molroo-io/sdk';

PersonaConfigData

Configuration data for creating or updating a persona via molroo.createPersona() or persona.patch().

interface PersonaConfigData {
  personality?: PersonalityTraits;
  identity?: Identity;
  goals?: Goal[];
  [key: string]: unknown;
}
FieldTypeRequiredDescription
personalityPersonalityTraitsNoPersonality factor scores (0-1)
identityIdentityNoName, role, speaking style, values
goalsGoal[]NoPersona's goals and motivations
[key]unknown--Extensible with custom fields

Example:

const molroo = new Molroo({ apiKey: 'mk_live_xxx' });

const persona = await molroo.createPersona(
  {
    identity: {
      name: 'Sera',
      role: 'barista at a cozy cafe',
      speakingStyle: 'warm and casual, uses coffee metaphors',
      coreValues: ['kindness', 'creativity', 'authenticity'],
    },
    personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.9, N: 0.3, H: 0.8 },
    goals: [
      { content: 'Make every customer feel welcome', priority: 1 },
      { content: 'Perfect the art of latte art', priority: 0.7 },
    ],
  },
  { llm },
);

PersonalityTraits

Personality factor scores. Each factor ranges from 0 to 1.

type PersonalityTraits = {
  O: number;
  C: number;
  E: number;
  A: number;
  N: number;
  H: number;
};
KeyFactorRangeDescription
OOpenness to Experience0 - 1Curiosity, creativity, openness to new ideas
CConscientiousness0 - 1Organization, discipline, reliability
EExtraversion0 - 1Sociability, assertiveness, positive emotionality
AAgreeableness0 - 1Cooperativeness, tolerance, gentleness
NNeuroticism0 - 1Emotional volatility, anxiety, sensitivity
HHonesty-Humility0 - 1Sincerity, fairness, modesty

Example:

// A cheerful, open, and agreeable persona
const personality: PersonalityTraits = {
  O: 0.8,  // Very open and creative
  C: 0.5,  // Moderately organized
  E: 0.7,  // Fairly extroverted
  A: 0.9,  // Highly agreeable
  N: 0.2,  // Emotionally stable
  H: 0.8,  // Very honest and humble
};

Identity

Persona identity information used for system prompt construction and character consistency.

interface Identity {
  name: string;
  role?: string;
  speakingStyle?: string;
  coreValues?: string[];
  culturalIdentity?: string;
  description?: string;
  extensions?: Record<string, string>;
}
FieldTypeRequiredDescription
namestringYesPersona display name
rolestring?NoCharacter role or occupation (e.g., 'barista', 'knight')
speakingStylestring?NoDescription of how the persona speaks (e.g., 'warm and casual')
coreValuesstring[]?NoCore values that guide the persona's behavior
culturalIdentitystring?NoCultural background or identity
descriptionstring?NoFree-form description of the persona
extensionsRecord<string, string>?NoArbitrary key-value pairs rendered as subsections in the system prompt

Goal

A persona's goal or motivation. Goals are included in the system prompt and influence emotional appraisal.

interface Goal {
  id?: string;
  content: string;
  priority?: number;
  mutable?: boolean;
  status?: 'active' | 'achieved' | 'abandoned';
}
FieldTypeDefaultDescription
idstring?auto-generatedUnique goal identifier
contentstring--Goal description (e.g., 'Protect the village')
prioritynumber?1Priority weight (0 to 1). Higher priority goals have more influence on emotion
mutableboolean?trueWhether the goal can be modified or removed during interaction
statusstring?'active'Goal status: 'active', 'achieved', or 'abandoned'

Example:

const goals: Goal[] = [
  {
    content: 'Make every customer feel welcome',
    priority: 1,
    mutable: false,   // Core goal, never changes
  },
  {
    content: 'Learn to make the perfect cappuccino',
    priority: 0.6,
    mutable: true,    // Can evolve through interaction
    status: 'active',
  },
];

SimConfig

Simulation configuration for tuning engine physics. Passed as simConfig in PersonaConfigData.

interface SimConfig {
  calibration?: CalibrationConfig;
}
FieldTypeRequiredDescription
calibrationCalibrationConfigNoBody budget physics constants

CalibrationConfig

Controls body budget recovery, depletion, and per-turn intensity scaling. See the Calibration guide for usage examples.

interface CalibrationConfig {
  budgetRecoveryPerHour?: number;
  budgetMinimum?: number;
  turnScale?: number;
  baselineIntensityWeight?: number;
}
FieldTypeDescription
budgetRecoveryPerHournumber?Controls how fast body budget recovers over time. Higher = faster recovery.
budgetMinimumnumber?Floor for the body budget. Prevents complete depletion.
turnScalenumber?Multiplier for per-turn emotion intensity. Higher = more dramatic reactions.
baselineIntensityWeightnumber?How much personality baseline contributes vs. situational appraisal.

All fields are optional. Omitted fields use engine defaults.

On this page