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,
  Episode,
} from '@molroo-io/sdk';

VAD

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

interface VAD {
  V: number;
  A: number;
  D: number;
}

Dimension	Description
`V` (Valence)	Negative to positive
`A` (Arousal)	Calm to activated
`D` (Dominance)	Submissive to dominant

AppraisalVector

Cognitive appraisal vector. Describes how a persona evaluates an incoming stimulus. The LLM generates these values during chat, or you provide them manually in emotion-only mode.

interface AppraisalVector {
  goal_relevance: number;
  goal_congruence: number;
  expectedness: number;
  controllability: number;
  agency: number;
  norm_compatibility: number;
  internal_standards: number;
  adjustment_potential: number;
  urgency: number;
}

Dimension	Description
`goal_relevance`	How relevant to the persona's current goals
`goal_congruence`	Whether this helps or hinders goals
`expectedness`	How expected/predictable this was
`controllability`	How much control the persona has over the situation
`agency`	Who is responsible: self or other
`norm_compatibility`	Whether this fits the persona's moral/social norms
`internal_standards`	Self-standard evaluation
`adjustment_potential`	Coping/acceptance ability
`urgency`	Time pressure for action

AgentResponse

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

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;
    agency: number;
    coherence: number;
  };
  text?: string;
  action?: string;
  memoryEpisode?: Episode;
  socialUpdates?: SocialUpdate[];
  reflectionPrompt?: ReflectionPrompt;
  goalChanges?: { achieved: string[]; blocked: string[] };
  behaviorModifiers?: Record<string, number>;
}

emotion

Field	Type	Description
`emotion.vad`	`VAD`	Current emotion in VAD space
`emotion.discrete.primary`	`string`	Primary discrete emotion label (e.g., `'joy'`, `'anger'`, `'fear'`)
`emotion.discrete.secondary`	`string?`	Optional secondary emotion label
`emotion.discrete.intensity`	`number`	Emotion intensity (0 to 1)

mood

Background mood:

Field	Type	Description
`mood.vad`	`VAD`	Mood 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 metrics. Included automatically when available.

Side effects

Field	Type	Description
`text`	`string?`	LLM-generated response text (empty in emotion-only mode)
`action`	`string?`	Suggested action
`memoryEpisode`	`Episode`	Memory episode recorded during this interaction
`socialUpdates`	`SocialUpdate[]`	Relationship changes triggered by this interaction
`reflectionPrompt`	`ReflectionPrompt`	Prompt for LLM-generated reflection (used with MemoryAdapter)
`goalChanges`	`{ achieved, blocked }`	Goals that changed status this turn
`behaviorModifiers`	`Record<string, number>?`	Relationship-stage behavioral hints (e.g., approach tendency, disclosure level)

State

Emotion state of a persona. Returned when includeState: true is set in chat options.

Field	Type	Description
`emotion`	`VAD`	Current emotion coordinates

The State object also includes additional internal engine fields. These are managed automatically and should be treated as opaque.

SoulStage

Psychological development stage. The persona progresses through stages reflecting psychological growth or decline. Returned as part of State.

Field	Type	Description
`id`	`number`	Current stage number
`name`	`string`	Stage name

Other fields are internal engine state and should be treated as opaque.

NeedState

Psychological needs state. Each dimension reflects how well the persona's needs are being met.

Field	Type	Description
`autonomy`	`number`	Sense of agency and choice
`competence`	`number`	Sense of effectiveness
`relatedness`	`number`	Sense of social connection

Additional internal types

The engine tracks additional internal state types for emotion dynamics. These are returned as opaque objects and managed automatically — you do not need to interact with them directly.

Episode

A memory episode representing a single interaction or event. Episodes are stored in the persona's memory and can be recalled during future conversations.

interface Episode {
  id: string;
  type?: string;
  content?: string;
  context?: string;
  sourceEntity?: string;
  appraisal?: AppraisalVector;
  emotionSnapshot: VAD;
  intensity?: number;
  importance: number;
  timestamp: number;
}

Field	Type	Description
`id`	`string`	Unique episode identifier
`type`	`string?`	Episode type (e.g., `'chat_message'`, `'world_event'`)
`content`	`string?`	Text content of the interaction
`context`	`string?`	Additional context about the episode
`sourceEntity`	`string?`	Name of the entity that triggered this episode
`appraisal`	`AppraisalVector`	Appraisal at the time of the episode
`emotionSnapshot`	`VAD`	Emotional state at the time of the episode
`intensity`	`number?`	Emotional intensity
`importance`	`number`	Importance score for memory consolidation
`timestamp`	`number`	Epoch timestamp (milliseconds)

SocialUpdate

A relationship change triggered during an interaction.

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

PersonaSnapshot

See PersonaSnapshot in Result Types.

Emotion Types

On this page