molroo docs
SDK ReferenceTypes

Emotion Types

VAD, AppraisalVector, State, AgentResponse, and emotion sub-system types.

Emotion Types

Core emotion types returned by the molroo API. These represent the heart of molroo's psychology-based emotion simulation.

import type {
  VAD,
  AppraisalVector,
  AgentResponse,
  State,
  SoulStage,
  NeedState,
  CatastropheState,
  Episode,
} from '@molroo-ai/sdk';

VAD

Valence-Arousal-Dominance vector -- the core emotion representation. All emotional states in molroo are represented in this 3D space.

interface VAD {
  /** Valence: negative (-1) to positive (+1) */
  V: number;
  /** Arousal: calm (0) to activated (1) */
  A: number;
  /** Dominance: submissive (-1) to dominant (+1) */
  D: number;
}
DimensionRangeLowHigh
V (Valence)-1 to +1Negative (sad, angry)Positive (happy, content)
A (Arousal)0 to 1Calm, relaxedActivated, excited
D (Dominance)-1 to +1Submissive, powerlessDominant, in control

Example values:

EmotionVAD
Joy+0.7+0.5+0.4
Anger-0.6+0.8+0.5
Sadness-0.7-0.3-0.5
Fear-0.6+0.7-0.6
Calm+0.2-0.4+0.1

AppraisalVector

Cognitive appraisal vector based on the Scherer component process model. Describes how a persona evaluates an incoming stimulus along 6 dimensions. The LLM generates these values during chat, or you provide them manually in emotion-only mode.

interface AppraisalVector {
  /** How relevant is this to the persona's goals? [-1, 1] */
  goal_relevance: number;
  /** Does this help (+1) or hinder (-1) goals? [-1, 1] */
  goal_congruence: number;
  /** How expected was this? [0, 1] */
  expectedness: number;
  /** How much control does the persona have? [0, 1] */
  controllability: number;
  /** Who caused this — self (+1) or other (-1)? [-1, 1] */
  agency: number;
  /** Compatible with the persona's norms? [-1, 1] */
  norm_compatibility: number;
}
DimensionRangeDescription
goal_relevance-1 to +1How relevant to the persona's current goals
goal_congruence-1 to +1Whether this helps (+) or hinders (-) goals
expectedness0 to 1How expected/predictable this was
controllability0 to 1How much control the persona has over the situation
agency-1 to +1Who is responsible: self (+1) or other (-1)
norm_compatibility-1 to +1Whether this fits the persona's moral/social norms

AgentResponse

Response from the emotion engine for a single entity interaction. This is the primary result type returned within ChatResult and EventResult.

interface AgentResponse {
  emotion: {
    vad: VAD;
    discrete: {
      primary: string;
      secondary?: string;
      intensity: number;
    };
  };
  mood?: {
    vad: VAD;
    valence: 'negative' | 'neutral' | 'positive';
    arousal: 'calm' | 'moderate' | 'activated';
    dominance: 'submissive' | 'balanced' | 'dominant';
  };
  somatic?: string[];
  narrative?: {
    tone: number;      // -1 (decline) to +1 (recovery)
    agency: number;    // -1 (reactive) to +1 (agentic)
    coherence: number; // 0 to 1
  };
  text?: string;
  action?: string;
  memoryEpisode?: Episode;
  socialUpdates?: SocialUpdate[];
  reflectionPrompt?: ReflectionPrompt;
  stageTransition?: boolean;
  maskExposure?: { integrity: number; state: string };
  goalChanges?: { achieved: string[]; blocked: string[] };
}

emotion

FieldTypeDescription
emotion.vadVADCurrent emotion in VAD space
emotion.discrete.primarystringPrimary discrete emotion label (e.g., 'joy', 'anger', 'fear')
emotion.discrete.secondarystring?Optional secondary emotion label
emotion.discrete.intensitynumberEmotion intensity (0 to 1)

mood

Background mood (changes more slowly than emotion):

FieldTypeDescription
mood.vadVADMood in VAD space
mood.valence'negative' | 'neutral' | 'positive'Valence category
mood.arousal'calm' | 'moderate' | 'activated'Arousal category
mood.dominance'submissive' | 'balanced' | 'dominant'Dominance category

somatic

Array of body sensation strings (e.g., ['chest_warmth', 'stomach_butterflies']).

narrative

Self-narrative perception:

FieldRangeDescription
tone-1 to +1Narrative tone: decline (-1) to recovery (+1)
agency-1 to +1Perceived agency: reactive (-1) to agentic (+1)
coherence0 to 1How coherent the persona's self-narrative is

Side effects

FieldTypeDescription
textstring?LLM-generated response text (empty in emotion-only mode)
actionstring?Suggested action
memoryEpisodeEpisodeMemory episode recorded during this interaction
socialUpdatesSocialUpdate[]Relationship changes triggered by this interaction
reflectionPromptReflectionPromptPrompt for LLM-generated reflection (used with MemoryAdapter)
stageTransitionboolean?Whether a soul stage transition occurred
maskExposure{ integrity, state }Mask integrity drop (persona facade cracking)
goalChanges{ achieved, blocked }Goals that changed status this turn

State

Complete internal emotion state of a persona, including all sub-systems. Returned when includeState: true is set in chat options.

interface State {
  emotion: VAD;
  velocity: Velocity;
  emotion_history: Array<VAD & { timestamp: number }>;
  body_budget: number;
  soul_stage: SoulStage;
  prediction_model: AppraisalVector;
  prev_emotion_delta?: VAD;
  need_state?: NeedState;
  lastUpdated?: number;
  catastrophe: CatastropheState;
  metacog: MetacogState;
  affect_dynamics: AffectDynamicsState;
  interpersonal: InterpersonalState;
  regulation: RegulationState;
  prevMaskIntegrity?: number;
}
FieldTypeDescription
emotionVADCurrent emotion coordinates
velocityVelocityRate of change in VAD space
emotion_historyArray<VAD & { timestamp }>Recent emotion history
body_budgetnumberBody budget (0 to 1) -- overall physiological resource
soul_stageSoulStageCurrent soul stage (psychological development level)
prediction_modelAppraisalVectorLearned appraisal expectations
need_stateNeedStateSelf-Determination Theory needs
catastropheCatastropheStateZeeman catastrophe model state
metacogMetacogStateMetacognitive state (self-awareness, regulation history)
affect_dynamicsAffectDynamicsStateAffect variability, instability, inertia
interpersonalInterpersonalStateInterpersonal circumplex position (dominance, affiliation)
regulationRegulationStateEmotion regulation strategies and effectiveness

SoulStage

Psychological development stage. The persona progresses through 15 stages reflecting psychological growth or decline.

interface SoulStage {
  id: number;                // [1, 15]
  name: string;
  tolerance: number;
  stress_modifier: number;
  appraisal_bias: Partial<AppraisalVector>;
  avoidance_mod: number;
  blend_table: { rational: number; irrational: number };
  cumulative_load: number;
  turns_in_stage: number;
}
FieldTypeDescription
idnumberStage number (1-15)
namestringStage name
tolerancenumberStress tolerance threshold
stress_modifiernumberHow stress affects this stage
appraisal_biasPartial<AppraisalVector>Appraisal biases at this stage
avoidance_modnumberAvoidance behavior modifier
blend_table{ rational, irrational }Rational vs irrational response blend
cumulative_loadnumberAccumulated psychological load
turns_in_stagenumberHow many turns spent in this stage

NeedState

Self-Determination Theory needs.

interface NeedState {
  autonomy: number;     // [0, 1]
  competence: number;   // [0, 1]
  relatedness: number;  // [0, 1]
}

CatastropheState

Zeeman catastrophe model state. Models sudden emotional shifts (e.g., going from calm to rage).

interface CatastropheState {
  alpha: number;           // Asymmetry factor
  beta: number;            // Bifurcation factor
  z: number;               // State variable
  hysteresis_bound: number;
}

Episode

A memory episode recorded during an interaction.

interface Episode {
  id: string;
  timestamp: number;
  sourceEntity?: string;
  context?: string;
  appraisal: AppraisalVector;
  emotionSnapshot: VAD;
  intensity: number;
  importance: number;
}
FieldTypeDescription
idstringUnique episode ID
timestampnumberEpoch milliseconds
sourceEntitystring?Entity that caused this episode
contextstring?Context/description of what happened
appraisalAppraisalVectorThe appraisal that produced this episode
emotionSnapshotVADEmotion at the time of the episode
intensitynumberEmotional intensity of the episode
importancenumberHow important this episode is for memory recall

SocialUpdate

A relationship change triggered during an interaction.

interface SocialUpdate {
  entityId: string;
  field: string;
  oldValue: number;
  newValue: number;
}

PersonaSnapshot

Complete serialized state of a persona, included in WorldSnapshot entities. Contains the full internal state, relationships, goals, and all sub-system data.

interface PersonaSnapshot {
  state: State;
  relationships: Record<string, Relationship>;
  goals: Goal[];
  selfConcept?: string;
  mood?: VAD;
  moodHistory?: Array<{ emotion: VAD; intensity: number }>;
  somatic?: {
    regions: {
      head: number; neck: number; chest: number;
      stomach: number; upperBack: number; hands: number; legs: number;
    };
    interoception: number;
  };
  narrative?: {
    tone: number;
    coherence: { temporal: number; causal: number; thematic: number };
    agency: number;
    communion: number;
    arcs: Array<{
      id: string;
      type: 'decline' | 'recovery' | 'stability' | 'growth';
      strength: number;
      episodeIds: string[];
      theme: string;
    }>;
  };
  tmt?: {
    mortalitySalience: number;
    deathAnxiety: number;
    proximity: 'immediate' | 'near' | 'distant' | 'abstract';
    proximalDefense: boolean;
    distalDefense: boolean;
    defenseTarget: 'in_group' | 'out_group' | 'values' | 'self_esteem' | null;
    defenseStrength: number;
    lastReminderTime: number;
  };
  selfEsteem?: { global: number; contingencies: Record<string, number> };
  motivationContexts?: Record<string, MotivationContext>;
}

Key sub-systems:

  • state -- full emotion State including all sub-systems
  • relationships -- map of entity ID to Relationship data
  • goals -- array of active/achieved/abandoned goals
  • somatic -- body region activation map and interoception level
  • narrative -- self-narrative arcs (decline, recovery, stability, growth)
  • tmt -- Terror Management Theory state (mortality salience, defense mechanisms)
  • selfEsteem -- global self-esteem and contingencies
  • motivationContexts -- Self-Determination Theory motivation per context

On this page