Emotions & Mood

Mood is a four-dimensional value (happiness, energy, calmness, affection) that the context engine maintains automatically for every agent-user pair. Every conversation, application event, and time-based decay is processed without any code on your side. The APIs on this page are for reading that state (dashboards, UI, analytics) or time-traveling to understand what it looked like at a past moment.

What you can build with it

• Mood-aware UI — show the agent's current mood label and dimension values so users can read emotional state at a glance
• Mood history graphs — plot happiness, energy, calmness, or affection over time to surface relationship phases
• Mood-influenced response tuning — the engine already bakes mood into every reply; you can also use the live signal to adjust your own UI (avatar expression, ambient sound, tint)
• Aggregate mood over time for cohort analysis — roll up mood across all users for a given agent to track product-level sentiment health
• Time-machine replay — fetch mood as it stood at any past timestamp for audit trails or narrative moments ("we were in a tough place three weeks ago")

Quickstart

Fetch the current mood for an agent-user pair.

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

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

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

Core concepts

Four mood dimensions

Each agent-user pair carries a mood state with four independent dimensions, each on a 0–100 scale:

The overall mood label is derived from the combined dimensions: Blissful (80–100), Content (60–79), Neutral (40–59), Melancholy (20–39), Troubled (0–19).

What shifts mood automatically

• Chat interactions — the engine detects emotional themes in each turn (e.g. joy_blooming, feeling_overwhelmed) and adjusts dimensions accordingly.
• Application events — achievements, outings, and returns trigger mood shifts without your code doing anything.
• Time-based decay — mood drifts back toward the agent's personality-derived baseline over time.

History vs current vs aggregate

• Current (GetMood) — the live snapshot for a single user right now.
• History (GetMoodHistory) — a time-series of snapshots for one user, suitable for graphs and narrative moments.
• Aggregate (GetMoodAggregate) — rolled-up statistics across all users for an agent, suitable for cohort dashboards.

Time Machine

GetTimeMachine returns the agent's full state — mood, personality, and evolution events — as it stood at any past UTC timestamp. The response carries mood_at (the mood state at that moment), personality_at (personality state then), current_personality (today's state for comparison), evolution_events (what changed in between), and requested_at (the timestamp you queried).

Full API

All mood methods are on client.agents.* (TS/Python) or client.Agents (Go). Full request/response shapes live in the API reference.

Combines with other features

With Self-Improvement — mood feeds personality evolution

The self-improvement engine reads sustained mood patterns and extracts evolution events that gradually reshape the agent's personality. You can observe this pipeline in action by fetching mood history alongside recent evolution events.

// 1. Read the mood history to see emotional trajectory
const history = await client.agents.getMoodHistory("agent-id", {
userId: "user-123",
});

// 2. Fetch self-improvement events to see what evolved from it
const improvements = await client.agents.getSelfImprovement("agent-id", {
userId: "user-123",
});

for (const evt of improvements.events) {
console.log(evt.trigger, evt.dimension, evt.delta);
// "sustained_low_calmness"  "neuroticism"  +0.04
}

With Agent Insights — mood is part of the "what the agent learned" picture

Agent Insights surfaces what the agent has understood about a user across all sessions. Mood is a key dimension of that picture — pairing a current mood read with insights lets you build a complete emotional-state panel.

const [mood, insights] = await Promise.all([
client.agents.getMood("agent-id", { userId: "user-123" }),
client.agents.getInsights("agent-id", { userId: "user-123" }),
]);

console.log("Current mood:", mood.label, mood.happiness);
console.log("Key insight:", insights.summary);

With Advance Time — fast-forward mood decay

In the workbench or integration tests, you can advance the clock to observe how mood decays back toward baseline without waiting for real time to pass. Read mood before and after to see the delta.

// 1. Read mood now
const before = await client.agents.getMood("agent-id", { userId: "user-123" });
console.log("Before:", before.happiness); // 90

// 2. Advance time by 72 hours to trigger decay
await client.workbench.advanceTime({ hours: 72 });

// 3. Read mood again — decayed toward baseline
const after = await client.agents.getMood("agent-id", { userId: "user-123" });
console.log("After:", after.happiness);  // 68

Tutorials

• Memory tutorial — see how conversation content flows into mood and memory together.

Next steps

• Self-Improvement — how sustained mood patterns drive personality evolution
• Agent Insights — the full picture of what the agent knows about a user
• Personality — the baseline that mood decays toward
• Advance Time — fast-forward the clock in tests and the workbench