Core Concepts

This guide explains the fundamental building blocks of molroo. Understanding these concepts is essential for building emotionally authentic AI characters.

Persona

A Persona is an AI character with a full emotion engine. It is the core unit of emotional simulation in molroo. Each persona runs as an isolated stateful instance on the server.

A persona has:

• Identity — name, role, speaking style, core values, and optional freeform description and extensions
• Personality — Multi-factor personality model
• Mood — slow-moving emotional baseline that changes gradually
• Somatic Markers — physiological signals tied to emotion (racing heart, sweaty palms)
• Memory — episodic recall of past interactions

import { Molroo } from '@molroo-io/sdk';
import { createOpenAI } from '@ai-sdk/openai';

const molroo = new Molroo({ apiKey: 'mk_live_...' });
const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

const persona = await molroo.createPersona(
  {
    identity: {
      name: 'Sera',
      role: 'friendly barista',
      speakingStyle: 'warm and casual, uses food metaphors',
      coreValues: ['honesty', 'warmth'],
      description: 'Grew up in a small coastal town...',
    },
    personality: { O: 0.7, C: 0.6, E: 0.8, A: 0.9, N: 0.3, H: 0.8 },
  },
  { llm: openai('gpt-4o-mini') },
);

Personality model

molroo uses a 6-factor personality model. Each factor ranges from 0 to 1: Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism, and Honesty-Humility.

For detailed factor descriptions (low vs. high values) and how personality shapes emotion processing, see the Emotion Types Reference.

VAD (Valence-Arousal-Dominance)

VAD is the 3-dimensional coordinate system that represents emotional state. Every emotion maps to a point in this space:

• Valence: Negative to positive
• Arousal: Calm to activated
• Dominance: Submissive to dominant

For the full type definition, see the Emotion Types Reference.

Appraisal

Appraisal is how a persona evaluates an incoming stimulus (message or event). It is the entry point of the emotion pipeline.

In normal operation, the LLM generates appraisal values automatically based on the persona's context. You can also provide manual appraisal in emotion-only mode.

For the full definition, see the Emotion Types Reference.

Server-side prompt assembly

The API builds the system prompt from the persona's live emotional state. You never need to construct emotion-related prompts yourself.

persona.chat(message)
    |
    v
SDK fetches system prompt from API
    |
    v
SDK sends prompt + message to your LLM
    |
    v
LLM returns response text + appraisal
    |
    v
SDK sends appraisal to API → engine updates emotional state

Mood vs. Emotion

Emotions are momentary reactions to stimuli. Mood is a longer-term baseline. They are tracked separately and influence each other over time.

Somatic markers

Characters have physiological responses tied to their emotions — racing heart, warm cheeks, tension in the shoulders. These somatic markers are computed automatically and included in the system prompt to give the LLM grounding for more embodied responses.

Next steps