Emotions & Mood

Mood Dimensions

Each agent-user pair has a mood state with four dimensions on a 0-100 scale:

• Happiness (0-100): Joy/sadness spectrum
• Energy (0-100): Activity/lethargy level
• Calmness (0-100): Anxiety/peace state
• Affection (0-100): Warmth toward user

Mood Labels

The overall mood label is derived from the combined dimensions:

• Blissful (80-100): Exceptionally happy, enthusiastic
• Content (60-79): Generally positive, at ease
• Neutral (40-59): Balanced, even-keeled
• Melancholy (20-39): Somewhat down, subdued
• Troubled (0-19): Distressed, anxious

What Shifts Mood

1. Chat Interactions

The platform detects emotional themes in conversations and adjusts mood automatically. Common themes:

• joy_blooming — keywords: happy, excited, wonderful — effect: Happiness ↑, Energy ↑
• creative_spark — keywords: create, imagine, inspire — effect: Energy ↑, Happiness ↑
• brave_steps — keywords: courage, try, challenge — effect: Energy ↑, Calmness ↑
• growth_journey — keywords: learn, grow, improve — effect: Happiness ↑, Energy ↑
• seeking_connection — keywords: friend, together, share — effect: Affection ↑, Happiness ↑
• feeling_overwhelmed — keywords: stressed, anxious, worried — effect: Calmness ↓, Energy ↓
• tender_heart — keywords: love, care, miss — effect: Affection ↑, Happiness ↑
• facing_fears — keywords: scared, afraid, nervous — effect: Calmness ↓, Affection ↑

2. Application Events

Pass application context and the platform updates mood automatically.

• Outing completed — Happiness ↑, Affection ↑
• Achievement unlocked — Happiness ↑, Energy ↑
• Breakthrough — Happiness ↑, Energy ↑, Calmness ↑
• Long absence return — Affection ↑, Happiness ↑

3. Time-Based Decay

Mood naturally drifts back toward the agent's personality-derived baseline over time. No action needed — this happens automatically.

Get Mood

Read the current mood state for an agent-user pair.

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk-..." });

const mood = await client.agents.getMood("agent-id", {
userId: "user-123",
});

console.log(mood.label);      // "Content"
console.log(mood.happiness);  // 72
console.log(mood.energy);     // 65
console.log(mood.calmness);   // 80
console.log(mood.affection);  // 68

Mood History

Retrieve the mood history for a user-agent pair over time.

const history = await client.agents.getMoodHistory("agent-id", {
userId: "user-123",
});

for (const snapshot of history.snapshots) {
console.log(snapshot.timestamp, snapshot.label, snapshot.happiness);
}

Mood Aggregate

Get aggregated mood statistics across all users for an agent.

const agg = await client.agents.moodAggregate("agent-id");

console.log(agg.averageHappiness);
console.log(agg.averageEnergy);
console.log(agg.labelDistribution);

Time Machine

Retrieve a historical snapshot of an agent's mood at any point in time.

const snapshot = await client.agents.getTimeMachine("agent-id", {
at: "2026-02-14T12:00:00Z",
userId: "user-123",
});

console.log(snapshot.mood);         // mood state at that timestamp
console.log(snapshot.personality);  // personality state at that timestamp

Constellations

Constellations are automatically detected clusters of related memories that form meaningful patterns. The platform identifies these from recurring themes across conversations.

const constellations = await client.agents.getConstellation("agent-id", {
userId: "user-123",
});

for (const cluster of constellations.clusters) {
console.log(cluster.theme, cluster.memories.length);
}

Breakthroughs

Breakthroughs are significant personality shifts or emotional milestones detected by the platform. They represent moments where an agent's understanding or relationship with a user meaningfully evolved.

const breakthroughs = await client.agents.getBreakthroughs("agent-id", {
userId: "user-123",
});

for (const b of breakthroughs.items) {
console.log(b.type, b.description, b.timestamp);
}

Goals

Goals represent what the agent is working toward with a user — they are detected and updated automatically by the context engine as conversations unfold. You do not need to set or manage them manually.

Common use cases for manual goal management:

• Seeding a goal when a user starts a new workflow (e.g., "complete onboarding")
• Marking a goal achieved after a business event (e.g., a purchase or milestone)
• Abandoning a goal when the user changes direction

// Goals are managed automatically — override only when needed

// List current goals
const goals = await client.agents.listGoals("agent-id", { userId: "user-123" });

// Manually create a goal (optional)
const goal = await client.agents.createGoal("agent-id", {
userId: "user-123",
title: "Onboarding",
description: "Complete onboarding checklist",
type: "task",
priority: 1,
});

// Mark a goal achieved after a business event
await client.agents.updateGoal("agent-id", goal.goal_id, {
userId: "user-123",
status: "achieved",
});

How Mood Affects Responses

Mood state is automatically included in the AI context. The agent adjusts tone accordingly:

• High Happiness: More enthusiastic, uses exclamations, shares positive observations
• Low Energy: Shorter responses, mentions tiredness, less proactive topic exploration
• Low Calmness: May express worry, seek reassurance, shorter attention span
• High Affection: More personal language, terms of endearment, deeper emotional engagement

In Practice

Mood and emotions matter a lot for companions. For task agents, you can largely ignore this system. For enterprise agents, the read-side is useful for sentiment signals even if you don't drive replies from it.

const mood = await client.agents.getMood("agent-id", {
  userId: "user-123",
});

// Drive UI: tint background, adjust avatar expression, pick ambient sound
renderMoodIndicator(mood.happiness, mood.energy);