Sonzai Documentation

Advance Time compresses real-world time into simulated time for an agent. Useful for character AI that needs in-game time to pass faster than real time, game loops that simulate days of agent state in seconds, or anywhere you want to see what the agent would be like after a period of elapsed time — without actually waiting for it.

What you can build with it

• Character AI / visual novel time skips — the protagonist sleeps for 8 hours; advance agent time by 8 hours and get the diary entry and mood changes that would have happened overnight
• Tamagotchi and life-sim game loops — in-game days pass faster than real time; call advanceTime each tick to keep agent state (mood, memory, habits) in sync with the game clock
• Tutorial onboarding — show a new user what their companion will "remember" after a week by fast-forwarding through a sample history before they send their first real message
• Deterministic replay — reproduce the exact agent state after X hours at any time, for debugging, snapshotting, or building a save/load system
• Eval and benchmarking — compress long-running scenarios into fast test runs (see Also useful for evaluation below)

Quickstart

Advance an agent's clock by 24 hours and inspect the diary entry generated for that simulated day.

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

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

const result = await client.workbench.advanceTime({
agentId: "agent_abc",
userId:  "user_123",
simulatedHours: 24,
});

// result.diary_entries contains any diary entries generated during the window
console.log(result.days_processed);   // 1
console.log(result.diary_entries);    // [{ content: "...", created_at: "..." }]

Core concepts

What fires when time advances

A single advanceTime call runs the full production background worker fleet for each complete 24-hour day in the window, then resolves any proactive wakeups due within it. Concretely:

• Diary generation — one diary entry per simulated day, written from the agent's perspective
• Mood decay — emotional state drifts toward the agent's baseline at the rate it would in real time
• Memory consolidation — facts, events, and commitments are consolidated and deduplicated as they normally would be overnight
• Constellation extraction — personality signals extracted from conversation history are processed on schedule
• Scheduled wakeups — any wakeup whose scheduled_at falls inside the advance window fires with its intent

Pass simulatedHours: 25 (one day plus a sliver) when you need the weekly consolidation gate to tick over.

Deterministic state transitions

Given the same agent state at the start, the same advanceTime call produces the same output. There is no randomness seeded from wall-clock time. This makes Advance Time suitable for save/load, replay, and regression testing.

Async mode for long windows

For advances that would exceed a proxy read timeout (Cloudflare's limit is ~100 s, which corresponds to roughly 4–5 simulated days depending on agent complexity), pass runAsync: true. The API returns immediately with a job descriptor; poll getAdvanceTimeJob until the status is terminal.

// Kick off a long advance asynchronously
const job = await client.workbench.advanceTime({
agentId: "agent_abc",
userId:  "user_123",
simulatedHours: 168, // one week
runAsync: true,
}) as { job_id: string; status: string };

console.log(job.job_id, job.status); // "job_01HX...", "running"

// Poll until done (30-minute TTL in Redis)
let state = await client.workbench.getAdvanceTimeJob(job.job_id);
while (state.status === "running") {
await new Promise(r => setTimeout(r, 2000));
state = await client.workbench.getAdvanceTimeJob(job.job_id);
}

console.log(state.status); // "succeeded"
console.log(state.result); // full AdvanceTimeResponse

Time granularity

The smallest meaningful unit is one full 24-hour simulated day. Background jobs (diary, consolidation, constellation) run once per day. Sub-day advances (e.g. simulatedHours: 8) still process wakeups and mood decay but will not generate a diary entry unless a full day boundary is crossed.

Full API

advanceTime options

Combines with other features

With Scheduled Reminders — fast-forwarding pending reminders

Any schedule whose next_fire_at falls within the advance window fires automatically. Advance 48 hours and two daily reminders will have fired — their intents processed, messages generated, and state updated — exactly as if real time had passed.

// Create a daily 09:00 reminder
await client.schedules.create("agent_abc", "user_123", {
  cadence: { simple: { frequency: "daily", times: ["09:00"] }, timezone: "UTC" },
  intent:  "check in on how the user is feeling",
  check_type: "reminder",
});

// Advance 48 hours — both 09:00 fires trigger inside the window
const result = await client.workbench.advanceTime({
  agentId: "agent_abc",
  userId:  "user_123",
  simulatedHours: 48,
});

console.log(result.wakeups_fired); // 2

With Memory / Diary — replay compressed history

When time advances, a diary entry is generated for each simulated day. The agent "remembers" what happened during the gap — emotional tone, recurring themes, relationship developments — the same way it would after real days of conversation. Use this to give a new user a companion that already feels lived-in, or to let a character "grow" between chapters of a story.

With Wakeups — time-travel scheduled wakeups

Any wakeup scheduled with a scheduled_at inside the advance window fires during the advance, including its LLM-generated proactive message. This lets you test wakeup copy and timing without waiting for the real clock to reach the fire time.

Tutorials

Advance Time is a primitive that chains with scheduled reminders, wakeups, and memory. There is no standalone end-to-end tutorial yet. See the linked Mind Layer pages below for how it combines with other features.

Next steps

• Scheduled Reminders — schedules fire automatically during a time advance
• Memory — diary entries are generated for each simulated day in the window
• Evaluation — if you are using Advance Time for benchmarking, see the eval workflow

Also useful for evaluation

If you are running a benchmark suite, advanceTime lets you compress long-running scenarios into fast test runs. Advance a simulated week in seconds, inspect the diary entries and mood state, then score the result. Pair with the evaluation workflow to measure agent behavior quality after arbitrary amounts of simulated elapsed time.

As the agent talks to a user over time, it builds up a derived view of who they are — what they care about, what they're working toward, who's in their life, and how their mood trends. Agent Insights exposes that derived state as readable (and for some signals, writable) endpoints. These are not things you author; the context engine extracts them automatically from conversations.

What you can build with it

• Personalized dashboards — show the user exactly what the agent has learned about them, building transparency and trust
• Weekly wrap-ups — "here's what's on your mind this week" compiled from diary entries and top interests
• Relationship-aware UX — surface the list of people the agent knows about so users can review or correct them
• Goal-tracking integrations — sync agent-tracked goals to external task managers or CRMs after they are detected
• Engagement health scoring — aggregate breakthroughs, mood trend, and habit streaks into a single user health metric

Quickstart

Fetch habits, goals, and interests for a user in one pass.

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

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

const agentId = "agent_abc";
const userId  = "user_123";

const [habits, goals, interests] = await Promise.all([
client.agents.listHabits(agentId, { userId }),
client.agents.listGoals(agentId, { userId }),
client.agents.getInterests(agentId, { userId }),
]);

console.log("habits:",    habits.habits.length);
console.log("goals:",     goals.goals.length);
console.log("interests:", interests.interests.length);

Core concepts

Derived, not authored. These signals are extracted from conversation text by the context engine. You do not push them in; the agent surfaces them automatically as it talks.

Per-instance scoping. Pass instanceId (TS/Python) or instanceID (Go) to filter results to a specific agent instance — useful when an agent is deployed in multiple scenarios or chat contexts for the same user.

Write endpoints for some signals. Goals and habits can be explicitly created, updated, or deleted when your application needs to drive a specific state (e.g., seeding a goal when a user starts onboarding, or marking a goal achieved after a purchase event). Interests, relationships, diary, constellation, and breakthroughs are read-only.

Read latency. Derived signals update at conversation turn-end, not in real time during a turn. Reads immediately after a chat call may not yet reflect the latest turn.

Full API

Read endpoints

Write endpoints (goals and habits)

Goals and habits support full CRUD. All other insight types are read-only.

Habits

Habits are recurring behaviors the context engine detects across conversations — things like "user meditates in the morning" or "user reviews their tasks every Sunday." Each habit has a strength (0-1) that rises with observations and a formed flag that is set once the habit is considered stable.

const habits = await client.agents.listHabits("agent_abc", {
userId: "user_123",
});

for (const h of habits.habits) {
console.log(h.name, h.category, h.strength, h.formed);
}

Goals

Goals represent what the user is working toward. They are extracted automatically from conversation intent — "I want to run a 5K by June" becomes a goal with a type, title, and priority. Goals have a status field: active, achieved, or abandoned.

// Read
const goals = await client.agents.listGoals("agent_abc", { userId: "user_123" });
for (const g of goals.goals) {
console.log(g.title, g.status, g.priority);
}

// Seed a goal for a new workflow
const goal = await client.agents.createGoal("agent_abc", {
userId:      "user_123",
title:       "Complete onboarding",
description: "Finish all onboarding steps",
type:        "task",
priority:    1,
});

// Mark achieved after a business event
await client.agents.updateGoal("agent_abc", goal.goal_id, {
userId: "user_123",
status: "achieved",
});

Interests

Interests are topics and themes the context engine identifies as meaningful to the user — things like "machine learning", "hiking", or "Italian cooking." Unlike goals, interests have no lifecycle status; they accumulate over time.

const interests = await client.agents.getInterests("agent_abc", {
userId: "user_123",
});

for (const i of interests.interests) {
console.log(i.topic, i.category);
}

Relationships

Relationships are the people the user mentions across conversations — friends, family, colleagues, and others the agent has learned about. Each entry includes the person's name, their relationship to the user, and any context the agent has collected.

const rel = await client.agents.getRelationships("agent_abc", {
userId: "user_123",
});

for (const r of rel.relationships) {
console.log(r.name, r.relationship_type, r.context);
}

Diary

The diary contains agent-authored entries written at session end — reflections on what happened, what was learned, and how the relationship is evolving. Each entry is anchored to a session and a timestamp. Diary entries are the richest narrative signal available.

const diary = await client.agents.getDiary("agent_abc", {
userId: "user_123",
});

for (const entry of diary.entries) {
console.log(entry.created_at, entry.content);
}

Constellation

The constellation is the agent's knowledge graph for a user — a set of nodes (concepts, people, themes) and edges (relationships between them) that the context engine builds from recurring patterns across memory. Nodes have a significance score and a node_type.

const c = await client.agents.getConstellation("agent_abc", {
userId: "user_123",
});

for (const node of c.nodes) {
console.log(node.label, node.node_type, node.significance);
}

Breakthroughs

Breakthroughs are significant relationship or emotional milestones detected by the platform — moments where the agent's understanding of the user meaningfully deepened, or where a notable shift in the relationship dynamic was recorded.

const bt = await client.agents.listBreakthroughs("agent_abc", {
userId: "user_123",
});

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

Combines with other features

With Memory — insights are summaries over raw facts

Insight signals are derived summaries; the underlying evidence lives in memory. Fetch habits to learn what patterns exist, then use memory.search to pull the raw conversation facts behind one of them.

const habits = await client.agents.listHabits("agent_abc", { userId: "user_123" });
const topHabit = habits.habits[0];

// Find the raw memories that support this habit
const facts = await client.agents.memory.search("agent_abc", {
userId: "user_123",
query:  topHabit.name,
limit:  10,
});

console.log(`Found ${facts.results.length} facts supporting "${topHabit.name}"`);

With Emotions — mood + insights for a full user picture

getMood and these insight endpoints together form the agent's complete understanding of a user at a point in time. Fetch both to power a user-facing "how the agent sees you" view or a support dashboard.

const [mood, goals, diary] = await Promise.all([
client.agents.getMood("agent_abc", { userId: "user_123" }),
client.agents.listGoals("agent_abc", { userId: "user_123" }),
client.agents.getDiary("agent_abc", { userId: "user_123" }),
]);

console.log("Current mood:", mood.label);
console.log("Active goals:", goals.goals.filter(g => g.status === "active").length);
console.log("Diary entries:", diary.entries.length);

With Advance Time — replay insight formation

Advance Time fast-forwards the context engine's processing — generating new diary entries, decaying mood, and updating derived signals — without waiting real time. This is useful for simulating what the agent would know after a period of elapsed time, and for testing insight endpoints against a populated state.

// Advance 7 days to populate diary entries and update insights
const result = await client.workbench.advanceTime({
  agentId: "agent_abc",
  userId:  "user_123",
  simulatedHours: 168,
});

// Now read the insights that formed during that window
const diary = await client.agents.getDiary("agent_abc", { userId: "user_123" });
console.log("Diary entries after 7d:", diary.entries.length);

Tutorials

• Memory — the raw facts behind insights; use memory.search to drill into any signal
• Emotions — mood, mood history, and aggregate mood statistics
• Personality — Big5 traits and personality evolution (a different kind of derived state)
• Advance Time — fast-forward the agent's processing to simulate elapsed time

The Mind Layer architecture separates agent intelligence from your application logic: your backend keeps owning auth, business state, and user data, while Sonzai owns personality, memory, mood, habits, and relationships behind a REST API. A single chat call assembles context, streams the AI response, and updates every internal state automatically — no extra orchestration calls. The most load-bearing thing to know: post-chat learning runs on Sonzai's side, so your backend never schedules consolidation, mood decay, or fact extraction.

System Overview

The Mind Layer is a standalone platform that separates agent intelligence (personality, memory, mood) from your application logic. Any backend integrates via REST API or the official SDKs.

Your Backend                  Mind Layer Platform
   |                                  |
   |--- Create Agent ---------------->|
   |<-- Agent ID + Profile -----------|
   |                                  |
   |--- Chat (SSE streaming) -------->|
   |    (messages + app context)      |-- Build context
   |<-- Streaming AI response --------|-- Stream AI response
   |                                  |-- Update memory, mood, personality
   |<-- Proactive notifications -------|   (automatic, no extra calls)

Integration Architecture

A typical deployment has three layers:

What the Platform Manages

On each chat call, the platform automatically assembles relevant context from personality, memory, mood, and relationship data before generating the AI response. Post-chat state updates happen automatically — no extra API calls needed.

Data Ownership

The Mind Layer and your backend each own distinct data:

Mind Layer Owns

• Agent personality profiles
• Memory facts and summaries
• Mood state (happiness, energy, calmness, affection)
• Personality evolution history
• Habits and goals
• Relationship narratives
• Knowledge Base entities and graphs
• Custom agent state

Your Backend Owns

• User authentication
• Business logic and workflows
• User profiles and preferences
• Application data and state
• Billing and subscriptions
• Permissions and access control
• Session management

Session Lifecycle

1. User opens chat
 Your Backend prepares application context (user data, preferences...)

2. Chat happens
 Your Backend ---> Chat SDK call (context + messages)
 User <--- Streaming AI response tokens

3. Chat ends
 Platform updates: memory, mood, personality, habits, relationships

4. Between sessions
 Platform runs: background consolidation, mood decay, proactive wakeups

Background Processing & Self-Improvement

The platform doesn't just respond to chat calls — it runs a continuous background pipeline that keeps memory accurate, behavioral state coherent, and retrieval quality climbing over time. Every loop runs automatically; nothing for you to schedule or wire.

For a complete walk-through of every mechanism — including consolidation, reversible deduplication, boundary detection, personality drift safety caps, breakthroughs, and the cautious-rollout system — see How Agents Improve Over Time.

SDK Integration Points

Use the official SDKs to interact with every part of the platform:

• Agents: create, get, list, update
• Chat: chat, chatStream (SSE)
• Memory: seed, search, list, browse, timeline, listFacts, reset
• Personality: get, update, history
• Mood: get, history, aggregate
• Knowledge Base: createSchema, insertFacts, bulkUpdate, search, recommendations, trends
• Custom States: create, get, upsert, list, delete
• Custom Tools: create, list, delete (agent-level and session-level)
• Notifications: list, consume, history
• User Priming: primeUser, batchImport, getMetadata, updateMetadata

You point your app at client.agents.chat (or open an explicit session with sessions.start → chat turns → sessions.end). Sonzai assembles the system prompt from the agent's identity, recalls relevant memories, runs the LLM, streams tokens back, executes any registered tools, and updates state — all in a single call. You write the least code in this pattern. It is the right default for chat companions, support agents, and anything where Sonzai owning the full agent loop is acceptable.

When to use this

• You want one HTTP call per turn and zero memory plumbing.
• You're happy letting Sonzai pick (or accept your override of) the LLM provider.
• You want personality, mood, memory, voice, KB search, and proactive notifications to all "just work" without orchestrating them yourself.

When to switch

• Your own LLM is non-negotiable — switch to Pattern 4: Standalone Realtime.
• Conversation already happens off-platform (recorded calls, transcripts, batch ingest) — switch to Pattern 5: Standalone Batch.
• Inside Claude Desktop / Cursor / an MCP-compatible IDE — switch to Pattern 2: MCP.
• Already using OpenClaw — switch to Pattern 3: OpenClaw.

Architecture

┌─────────────┐     ┌───────────────────────────────────┐
│  Your App   │     │            Sonzai                 │
└──────┬──────┘     └──────────────────┬────────────────┘
     │                                │
     │  agents.chat({ messages })     │
     │───────────────────────────────>│  • assemble context
     │                                │     (memory, mood,
     │                                │      personality, KB,
     │                                │      relationship)
     │                                │  • run LLM (your choice
     │                                │      of provider/model)
     │                                │  • execute registered
     │                                │      tools (if any)
     │  <── SSE stream ───────────────│  • write back: facts,
     │      tokens + done             │      mood, personality,
     │                                │      goals, habits
     │                                │
     │  (optional) sessions.end       │
     │───────────────────────────────>│  • consolidate, dedup,
     │                                │      diary, clustering

End-to-end snippet

The simplest complete flow: open an explicit session, drive a streaming chat, end the session.

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

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID  = "agent-uuid";
const USER_ID   = "user-123";
const SESSION_ID = crypto.randomUUID();

// 1. Start an explicit session (optional — agents.chat will auto-create one
//    if you don't, but explicit sessions let you scope tools and lifecycle).
await sonzai.agents.sessions.start(AGENT_ID, {
userId:    USER_ID,
sessionId: SESSION_ID,
});

// 2. Drive turns. Sonzai owns context assembly, the LLM call, tool exec,
//    and writeback. You stream the reply straight to your UI.
for await (const event of sonzai.agents.chatStream({
agent:     AGENT_ID,
sessionId: SESSION_ID,
userId:    USER_ID,
messages:  [{ role: "user", content: "Hi! How's your day going?" }],
language:  "en",
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

// 3. End the session — triggers fact extraction + consolidation.
await sonzai.agents.sessions.end(AGENT_ID, {
userId:        USER_ID,
sessionId:     SESSION_ID,
totalMessages: 2,
});

Where to next

The Mind Layer ships a hosted Streamable HTTP MCP endpoint at https://api.sonz.ai/mcp/memory/{agent_id}. Point any MCP-compatible client at it with your Sonzai API key — 34 tools, 4 resources, and 3 guided prompts. No local binary, no SSE port, no Go toolchain.

When to use this

• The user is already inside Claude Code, Cursor, Claude Desktop, ChatGPT, or another MCP-aware client.
• You want to drive Sonzai by conversation rather than by SDK code.
• You're prototyping — pick the create-companion or mind-layer-setup guided prompt and skip writing any code at all.

When to switch

• Building your own product UI — switch to Pattern 1: Managed Runtime.
• You want Sonzai inside your own LLM loop, not as a tool exposed to someone else's — switch to Pattern 4: Standalone Realtime.

Architecture

┌────────────────────────┐                   ┌──────────────────────┐
│  Claude Code · Cursor  │                   │   Sonzai Mind Layer  │
│  ChatGPT · VS Code     │                   │                      │
│  Claude Desktop        │                   │                      │
└──────────┬─────────────┘                   └──────────┬───────────┘
         │                                            │
         │  Streamable HTTP (JSON-RPC 2.0)            │
         │  • list_agents                             │
         │  • chat / start_session / end_session      │
         │  • search_memories / list_facts            │
         │  • get_personality / get_mood              │
         │  • generate_character / trigger_event      │
         │  • schedule_wakeup / list_notifications    │
         │                                            │
         ▼                                            │
 https://api.sonz.ai/mcp/memory/{agent_id}            │
 Authorization: Bearer sk-your-api-key                │
                                                      │
                                                      ▼
                                              Context Engine,
                                              AI Service, DBs

End-to-end snippet

You need a project API key from your dashboard and an agent ID. Pick your client below — pasting the snippet is the entire setup.

# One-liner — registers the hosted MCP server with Claude Code:
claude mcp add --transport http sonzai \
https://api.sonz.ai/mcp/memory/AGENT_ID \
--header "Authorization: Bearer $SONZAI_API_KEY"

# Then from any Claude Code session you can say:
#   "Chat with agent 'Luna' and say 'I had a great day hiking today!'"
#   "Search Luna's memories about hiking adventures"
#   "Use mind-layer-setup with assistant_name 'Aria' …"

Where to next

OpenClaw is an open-source framework for building conversational AI agents through a slot-based plugin system. The slot that decides what context goes into the system prompt is called contextEngine. Installing @sonzai-labs/openclaw-context registers the Sonzai context engine under the name "sonzai" — assign it to the slot in openclaw.json and every conversation flows through the Mind Layer with zero additional code.

When to use this

• You're already building on OpenClaw, or your team has standardised on it.
• You want OpenClaw's existing chat loop, telemetry, and tool plugins to keep working — Sonzai only swaps the memory/personality layer.
• You want a <sonzai-context> block injected into the system prompt on every turn, automatically priority-ordered and budget-trimmed.

When to switch

• Not on OpenClaw — switch to Pattern 1: Managed Runtime (we run the chat) or Pattern 4: Standalone Realtime (you run the chat).
• No real-time chat at all — switch to Pattern 5: Standalone Batch.

Architecture

OpenClaw Runtime              SonzaiContextEngine            Sonzai Mind Layer
    |                                |                            |
    |-- bootstrap(sessionId) ------->|                            |
    |                                |-- resolve agent + session->|
    |                                |<-- session state ----------|
    |                                |                            |
    |-- assemble(messages, budget) ->|                            |
    |                                |-- fetch memory, mood,      |
    |                                |   personality, goals ----->|
    |                                |<-- ranked context blocks --|
    |<-- systemPromptAddition -------|   priority-ordered,        |
    |                                |   token-budget-trimmed     |
    |                                |                            |
    |  [LLM call w/ enriched prompt] |                            |
    |                                |                            |
    |-- afterTurn(sessionId) ------->|                            |
    |                                |-- send transcript -------->|
    |                                |   Mind Layer extracts      |
    |                                |   facts, updates mood,     |
    |                                |   evolves personality      |
    |                                |                            |
    |-- compact(sessionId) --------->|                            |
    |                                |-- merge short → long term->|

End-to-end snippet

The OpenClaw plugin is JavaScript-only (OpenClaw itself is JS). The Python and Go branches show the equivalent B2B provisioning flow: deterministically derive an agent UUID and write the OpenClaw config — the runtime that consumes it stays JS.

// 1. Install:
//    openclaw plugins install @sonzai-labs/openclaw-context
//    # or: npm install @sonzai-labs/openclaw-context
//
// 2. Run the setup wizard (interactive — asks for API key, agent name):
//    npx @sonzai-labs/openclaw-context setup
//
// 3. The wizard writes openclaw.json:
//    {
//      "plugins": {
//        "slots": { "contextEngine": "sonzai" },
//        "entries": {
//          "sonzai": {
//            "enabled": true,
//            "apiKey": "sk_your_api_key",
//            "agentId": "a1b2c3d4-..."
//          }
//        }
//      }
//    }
//
// 4. Start chatting — Sonzai is now the contextEngine:
//    openclaw chat
//
// For programmatic / B2B provisioning use the exported setup() helper:
import { setup } from "@sonzai-labs/openclaw-context";

const result = await setup({
apiKey:     "sk_your_api_key",
agentName:  "customer-support-bot",
configPath: "/path/to/openclaw.json",
});

console.log(result.agentId);  // deterministic UUID — safe to re-run
console.log(result.written);  // true — config file updated

Where to next

You own the entire conversation. Sonzai never sees it in real time. When the conversation ends — call wraps, support case closes, journaling session finishes — you POST the transcript once and Sonzai's extractor turns it into facts, mood updates, personality drift, habit detection, and proactive-outreach signal. Best for tutoring, fitness, CRM, voice calls, journaling, and any flow where Sonzai in the hot path is undesirable or impossible.

When to use this

• Latency budget can't tolerate a per-turn /turn round-trip.
• The transcript already exists (recorded calls, Gong/Zoom exports, journal entries).
• You want bulk ingest after the fact — replay logs, migrate users, benchmark agent quality.

When to switch

• You want fresh per-turn context — Pattern 4: Standalone Realtime.
• You're happy ceding the LLM call too — Pattern 1: Managed Runtime.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│  Your App   │     │   Sonzai API     │     │   Your LLM   │
└──────┬──────┘     └────────┬─────────┘     └──────┬───────┘
     │                     │                       │
     │  GET /context       │                       │
     │────────────────────>│ (optional pre-session │
     │  <── user profile ──│  personalization)     │
     │                     │                       │
     │  ══ Your conversation (Sonzai not involved) ═════════│
     │                     │                       │              │
     │  Chat ──────────────┼──────────────────────>│             │
     │  <── reply ─────────┼───────────────────────│             │
     │  [N turns, your loop, your tools]            │             │
     │                     │                       │             │
     │  ════════════════════════════════════════════════════════│
     │                     │                       │
     │  /process or sessions.end({ messages })     │
     │────────────────────>│── extract facts,      │
     │  (full transcript)  │   personality, mood,  │
     │                     │   habits, interests   │
     │  <── extractions ───│   (Sonzai LLM)        │
     │                     │                       │
     │  Use insights       │                       │
     │  (push notif,       │                       │
     │   dashboard,        │                       │
     │   exercises, …)     │                       │
     └─────────────────────┴───────────────────────┘

End-to-end snippet

The simplest path is /process: one call, auto-creates the session, returns the generated session_id for correlation. Use the explicit sessions.start → end({ messages }) lifecycle when you need session-scoped tools, durations, or async polling.

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

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

async function ingestTranscript(
agentId: string,
userId: string,
transcript: { role: "user" | "assistant" | "tool"; content: string; tool_calls?: any[] }[],
) {
// One call. Auto-creates a session. Tool messages allowed.
const result = await sonzai.agents.process(agentId, {
  userId,
  messages: transcript,
  provider: "gemini",                          // optional override
  model:    "gemini-3.1-flash-lite-preview",   // optional override
});

// result.session_id is the auto-created session id.
// Pull extractions from the read endpoints when ready:
const memory = await sonzai.agents.memory.list(agentId, { userId });
const mood   = await sonzai.agents.getMood(agentId, { userId });

return { sessionId: result.session_id, memory, mood };
}

Where to next

You keep your existing chat loop. Before each LLM call, you ask Sonzai for the enriched context for the user's message; after the LLM replies, you submit just that exchange via session.turn(). Mood lands inline (~300–500 ms). Deeper extraction — facts, personality drift, habit detection, goal updates — runs asynchronously 5–15 seconds later in the background. Sonzai never sees your tool execution and never picks your model.

This is the right shape for chat companions, voice agents, agent frameworks (OpenAI Agents SDK, LangChain, LiveKit), and anywhere you already had a working LLM loop in production before adopting Sonzai.

When to use this

• You already have a production LLM loop with custom tools, evals, prompt templates, or a specific provider.
• You need fresh per-turn context, not a once-a-conversation pull.
• You want mood, facts, personality, habits, goals, and relationship signal — without ceding LLM choice or tool execution.

When to switch

• One conversation can't end fast enough to wait for .turn() per exchange — switch to Pattern 5: Standalone Batch.
• Sonzai owning the LLM call is fine — switch to Pattern 1: Managed Runtime and delete most of this code.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│  Your App   │     │   Sonzai API     │     │   Your LLM   │
└──────┬──────┘     └────────┬─────────┘     └──────┬───────┘
     │                     │                       │
     │  sessions.start     │                       │
     │────────────────────>│ (prewarms memory)     │
     │  <── Session ───────│                       │
     │                     │                       │
     │  ─── Per turn ──────────────────────────── │
     │                     │                       │
     │  session.context()  │                       │
     │────────────────────>│                       │
     │  <── enriched ctx ──│                       │
     │    personality, mood│                       │
     │    memories, goals  │                       │
     │                     │                       │
     │  Your LLM loop ─────┼──────────────────────>│
     │  + your tools       │                       │
     │  + your multimodal  │                       │
     │  <── reply ─────────┼───────────────────────│
     │                     │                       │
     │  sendToUser(reply)  (no waiting on Sonzai)  │
     │                     │                       │
     │  session.turn()     │                       │
     │────────────────────>│ ⇒ sync mood ~300ms    │
     │  <── mood, status ──│ ⇒ background extract  │
     │                     │   (5–15s)             │
     │                     │                       │
     │  ─── Repeat ────────────────────────────── │
     │                     │                       │
     │  session.end()      │                       │
     │────────────────────>│── consolidate         │
     │                     │   long-term memory    │
     └─────────────────────┴───────────────────────┘

End-to-end snippet

The minimum viable loop with a real harness. The OpenAI Agents SDK owns conversation state, model selection, and tool dispatch. Sonzai sits outside that loop: it supplies the system prompt via session.context() before the run, and ingests the finished exchange via session.turn() after. No OPENAI_API_KEY needed — the Agents SDK is pointed at Gemini's OpenAI-compat endpoint.

import os, uuid
from openai import AsyncOpenAI
from agents import Agent, Runner, OpenAIChatCompletionsModel, function_tool, set_tracing_disabled
from sonzai import Sonzai

set_tracing_disabled(True)  # Agents SDK tries to ship traces to OpenAI; we don't have a key.

# Your LLM harness — owns history, tool dispatch, multi-step reasoning.
gemini = AsyncOpenAI(
  base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
  api_key=os.environ["GEMINI_API_KEY"],
)
model = OpenAIChatCompletionsModel(model="gemini-3.1-flash-lite-preview", openai_client=gemini)

@function_tool
def get_current_time() -> str:
  from datetime import datetime, timezone
  return datetime.now(timezone.utc).isoformat(timespec="seconds")

# Sonzai = memory layer. Never sees the LLM client.
sonzai = Sonzai(api_key=os.environ["SONZAI_API_KEY"])

def run_conversation(agent_id: str, user_id: str):
  session = sonzai.agents.sessions.start(
      agent_id,
      user_id=user_id,
      session_id=f"session-{uuid.uuid4().hex[:8]}",
      provider="gemini",                          # default for the deferred-extraction LLM
      model="gemini-3.1-flash-lite-preview",
  )

  def turn(user_message: str) -> str:
      # 1. Fresh, query-relevant context BEFORE the LLM call.
      ctx = session.context(query=user_message)

      # 2. Your harness runs the LLM + your tools. Sonzai is OUT of the loop.
      agent = Agent(
          name="Companion",
          instructions=build_system_prompt(ctx),
          model=model,
          tools=[get_current_time],
      )
      result = Runner.run_sync(agent, user_message)
      send_to_user(result.final_output)

      # 3. Convert the run's items (assistant text + ToolCallItem +
      #    ToolCallOutputItem) into Sonzai's tool-aware shape so
      #    extraction can pick up facts from tool outputs too.
      sonzai_messages = run_result_to_sonzai_messages(user_message, result)

      # 4. Submit. Sync mood ~300ms; deferred extraction 5–15s later.
      session.turn(messages=sonzai_messages)

      return result.final_output

  return turn, session.end


# /context returns a flat dict — read what you need, drop the rest.
def build_system_prompt(ctx: dict) -> str:
  facts = "\n".join(f"- {f.get('atomic_text', '')}" for f in (ctx.get("loaded_facts") or []))
  parts = [
      ctx.get("personality_prompt", "You are a helpful AI companion."),
      f"Personality (Big5): {ctx.get('big5', {})}",
      f"Current mood: {ctx.get('current_mood', {})}",
  ]
  if facts:
      parts.append(f"Relevant memories:\n{facts}")
  return "\n\n".join(parts)

Tool calls flow through to extraction

Sonzai's /turn accepts OpenAI/Anthropic-style tool messages: tool_calls on assistant messages and role: "tool" results. Forward the full exchange and the extractor can capture facts that only surfaced inside a tool output (e.g. "user's last order shipped from Tokyo" from an order-lookup tool).

session.turn(messages=[
    {"role": "user", "content": "Where did my last order ship from?"},
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [{
            "id": "call_1", "type": "function",
            "function": {"name": "order-lookup", "arguments": "{}"},
        }],
    },
    {"role": "tool", "tool_call_id": "call_1",
     "content": '{"order_id":"42","origin":"Tokyo","carrier":"DHL"}'},
    {"role": "assistant", "content": "Your last order shipped from Tokyo via DHL."},
])

Sonzai never executes a tool — that's your harness's job. It just reads the messages you submit. If you're on the OpenAI Agents SDK, see the demo's run_result_to_sonzai_messages helper — it converts a Runner result's MessageOutputItem / ToolCallItem / ToolCallOutputItem items into this shape.

Multimodal: your harness sees pixels, Sonzai sees text

/turn accepts text content only. This is intentional, not a limitation. Memory is a layer of semantic understanding — the question Sonzai needs to answer later is "what does this agent know about this user?", not "what bytes did the LLM see?". Your vision-capable LLM has already understood the image; pass that understanding to Sonzai as text, and the memory pipeline can extract facts, habits, and inventory items from it like any other turn.

The recommended pattern: have your same multimodal LLM produce a short factual description alongside its warm reply, and embed that description in the user message you submit to session.turn().

# Your harness: Gemini sees the actual image bytes via input_image.
result = await gemini.chat.completions.create(
    model="gemini-3.1-flash-lite-preview",
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT_IMAGE_AWARE},  # see below
        {"role": "user", "content": [
            {"type": "text", "text": user_msg},
            {"type": "image_url", "image_url": {"url": image_url}},
        ]},
    ],
)
raw = result.choices[0].message.content

# Dual-output: split the reply (shown to user) from the [MEMORY: ...] note.
memory_note, reply = split_memory_note(raw)   # your tiny parser
send_to_user(reply)

# Sonzai sees: the original user text + a description of the image.
# It will extract facts like "user goes to the gym", "wore a black tank top".
session.turn(messages=[
    {"role": "user",
     "content": f"{user_msg}\n\n[Image attached: {memory_note}, URL: {image_url}]"},
    {"role": "assistant", "content": reply},
])

The SYSTEM_PROMPT_IMAGE_AWARE instruction is what makes this work — it asks the LLM to emit a hidden line like [MEMORY: <factual description>] after its warm reply. Same LLM call, no extra cost or latency, no second roundtrip. The same pattern works for audio (send the transcript) and assistant-generated images (describe what you generated). For the full pattern with all three SDKs, see the deep guide's multimodal section.

Skipping local history with recent_turns

If your harness already keeps a message log (most do — Agents SDK, LangChain, etc.), use that. If you'd rather not maintain one, every /context response carries recent_turns — the raw messages buffered by /turn for the current session, in chronological order. Read them straight off ctx.recent_turns and feed them to your LLM:

ctx = session.context(query=user_message)
history = [{"role": t["role"], "content": t["content"]} for t in (ctx.get("recent_turns") or [])]
reply = your_llm.chat(
    system=build_system_prompt(ctx),
    messages=[*history, {"role": "user", "content": user_message}],
)

The buffer is per-session and text-only — no tool calls, no images, no system prompts. It's the right shape for a simple chat loop where Sonzai is the source of truth; if you need richer message structure, keep your own.

Where to next

Every feature in the Sonzai platform flows through the conversation loop. Each turn sends messages to the agent, streams back a response, and automatically updates memory, mood, relationships, personality, and goals — no separate API calls required.

What you can build with it

• Chat UIs (web, mobile) — stream tokens directly into your interface
• Voice conversations — combine with Voice for spoken responses
• Tool-using agents — combine with Custom Tools to let the agent call your functions
• Streaming responses — Server-Sent Events keep UI latency low
• Multi-instance conversations — scope memory and state per scenario with instanceId
• Background task agents — non-streaming chat for job queues and automation

Quickstart

Simple chat

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

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

const response = await client.agents.chat({
agent: "agent-id",
messages: [{ role: "user", content: "Hello!" }],
userId: "user-123",
language: "en",
});

console.log(response.content);

Streaming chat

Stream tokens as they arrive for a more responsive experience. The platform sends OpenAI-compatible SSE chunks; each line starts with data: and the stream closes with data: [DONE].

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "Tell me a story" }],
userId: "user-123",
language: "en",
timezone: "America/New_York",
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

Core concepts

Chat vs ChatStream

Chat aggregates the full response before returning — simpler to wire into job queues and one-shot automation. ChatStream (and ChatStreamChannel in Go) streams tokens as they arrive, which keeps UI latency low and lets you render responses progressively. Both call the same underlying SSE endpoint; Chat just buffers the events internally.

Session scoping

Pass sessionId to group messages into a traceable conversation. If you omit it, the platform assigns one automatically. Use your own session ID convention (e.g. case-<id>) so you can join conversation logs to your internal systems.

Tool capabilities per-chat

Built-in tools (web_search, image_generation, remember_name, inventory) are opt-in. Pass toolCapabilities on each chat call to enable them for that request. Custom tools defined on the agent are always available; platform-managed tools (memory, state) run automatically without configuration.

Instance ID for multi-scenario

instanceId isolates memory and personality evolution to a specific context — e.g. per-workspace or per-game-session. Without it, state is scoped per user. Set it consistently across calls that belong to the same scenario.

Message role conventions

Use "user" for the end-user's turn and "assistant" for prior agent replies you want to include as history. The platform appends the new assistant turn automatically after each successful chat call — you don't need to re-inject it.

max_turns for multi-message replies

Set maxTurns to control how many assistant messages the agent produces in a single call. Default is 1. Raise it for companions that send a few short messages in a row; keep it at 1 for task agents that should give a single focused reply.

Platform-managed state updates

After every turn, the platform automatically runs:

• Memory extraction — facts, events, and commitments extracted from the conversation
• Mood update — detected emotional themes shift mood dimensions
• Personality evolution — gradual Big5 shifts from interaction patterns
• Habit tracking — recurring patterns become tracked habits
• Relationship update — chemistry and relationship narrative updated
• Goal progress — recorded progress on active goals

No separate API calls are required.

Full API

All chat methods live on client.agents.* (TS/Python) or client.Agents (Go).

ChatOptions fields

Combines with other features

With Wakeups — proactive messages appear in the same chat stream

Wakeups let the agent initiate contact outside the normal request-response cycle. When you poll for or receive a wakeup delivery, feed it into your chat UI as an agent-initiated message so the user sees it inline.

// 1. Schedule a one-off wakeup
await client.agents.wakeups.create("agent-id", {
  userId: "user-123",
  checkType: "interest_check",
  intent: "follow up on the project the user mentioned yesterday",
  delayHours: 24,
});

// 2. Poll for pending proactive messages and surface them in the chat UI
const pending = await client.agents.notifications.list("agent-id", {
  userId: "user-123",
});
for (const msg of pending.messages) {
  renderAgentBubble(msg.content); // proactive message lands inline
}

With Scheduled Reminders — recurring proactive messages surface in chat

Scheduled reminders fire on a cadence and deliver proactive agent messages. Poll notifications.list after each reminder fires to pull the generated message into your chat UI, creating a continuous conversation thread that spans both reactive and proactive turns.

// 1. Create a daily check-in schedule
await client.schedules.create("agent-id", "user-123", {
  cadence: { simple: { frequency: "daily", times: ["09:00"] }, timezone: "Asia/Singapore" },
  intent: "morning check-in on mood and energy",
  checkType: "reminder",
});

// 2. At fire time, the platform generates a proactive message — fetch it
const pending = await client.agents.notifications.list("agent-id", {
  userId: "user-123",
});
pending.messages.forEach(msg => renderAgentBubble(msg.content));

With Custom Tools — agent calls your functions during chat

Register custom tools on the agent and pass toolCapabilities on the chat call. When the agent decides to invoke a tool, the SSE stream emits a tool_call event — your client executes the function and can feed the result back in a follow-up turn.

// 1. Register a custom tool on the agent (one-time setup)
await client.agents.createCustomTool("agent-id", {
  name: "get_order_status",
  description: "Returns the current status of a customer order",
  parameters: {
    type: "object",
    properties: { order_id: { type: "string" } },
    required: ["order_id"],
  },
});

// 2. Enable it in the chat call — agent can now invoke it
for await (const event of client.agents.chatStream({
  agent: "agent-id",
  messages: [{ role: "user", content: "Where's my order #4521?" }],
  userId: "user-123",
})) {
  if (event.type === "tool_call") {
    const result = await getOrderStatus(event.toolCall.parameters.order_id);
    console.log("Tool result:", result); // feed back in next turn
  } else {
    process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
  }
}

With Memory — every turn writes memory, search retrieves it

The platform extracts facts from every conversation turn automatically. You can query memory immediately after a chat call to confirm capture, or use memory.search to build a context widget showing what the agent remembers about the user.

// Chat turn — platform captures facts automatically
const response = await client.agents.chat({
  agent: "agent-id",
  messages: [{ role: "user", content: "I just signed up for a marathon in June." }],
  userId: "user-123",
});

// Memory search — retrieves facts just captured (and prior ones)
const memories = await client.agents.memory.search("agent-id", {
  query: "marathon running plans",
  userId: "user-123",
  limit: 5,
});

for (const result of memories.results) {
  console.log(result.content, result.score);
  // "User signed up for a marathon in June"  0.92
}

Tutorials

• Getting started — first chat call end-to-end
• Quickstart — five-minute TypeScript, Python, or Go setup

Next steps

• Sessions — explicit session management and history
• Voice — combine chat with spoken audio responses
• Memory — how facts flow from conversation turns into long-term storage
• Custom Tools — give the agent callable functions
• Scheduled Reminders — proactive agent-initiated messages on a cadence

Custom State is simple structured per-user data the agent can read and modify during conversations. Use it for counters, flags, or any state your product tracks per user. Unlike memory (which the platform extracts from conversation text), Custom State is data you write explicitly from your backend — and the agent sees it immediately.

What you can build with it

• Game loops — energy, currency, turn counters, progression flags
• Feature flags — per-user toggles for experimental features
• Session-scoped state — timers, streaks, active-quest identifiers
• Progress markers — "completed onboarding", "has premium", "saw-tutorial-X"
• Rate limits / quotas — message counts, daily-action remaining

Quickstart

Create an energy state for a user, starting at 100.

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

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

await client.agents.customStates.create("agent-id", {
key:    "energy",
value:  100,
scope:  "user",
userId: "user-123",
});

Core concepts

Typed values

Every state has a content_type that tells the platform how to interpret value:

Scoping model

Agent reads and writes

When the agent has access to custom states, it reads current state at the start of each conversation via the get_custom_state tool — no prompt injection required. The agent can also update state during a conversation if you define a Custom Tool that calls your backend.

Distinct from Inventory

Use Custom State for primitives and simple objects. Reach for Inventory when items have their own identity, multiple typed fields, and a shared schema across users.

Full API

Create

// Global state (shared across all users in an instance)
await client.agents.customStates.create("agent-id", {
key:         "current_status",
value:       "Processing requests",
scope:       "global",
contentType: "text",
instanceId:  "workspace-1",
});

// Per-user state
await client.agents.customStates.create("agent-id", {
key:         "energy",
value:       100,
scope:       "user",
contentType: "json",
userId:      "user-123",
});

Upsert (create or update by key)

Upsert creates the state if the key doesn't exist, or replaces the value if it does. Idempotent — safe to call on every update cycle from your backend.

await client.agents.customStates.upsert("agent-id", {
key:    "energy",
value:  80,
scope:  "user",
userId: "user-123",
});

Get by key

Retrieve a specific state by its composite key (key + scope + user_id + instance_id).

const state = await client.agents.customStates.getByKey("agent-id", {
key:    "energy",
scope:  "user",
userId: "user-123",
});

console.log(state.value);     // 80
console.log(state.updatedAt); // ISO timestamp

List

Return all states for an agent, optionally filtered by scope or user.

// All global states for an instance
const globals = await client.agents.customStates.list("agent-id", {
scope:      "global",
instanceId: "workspace-1",
});

// All per-user states for a specific user
const userStates = await client.agents.customStates.list("agent-id", {
scope:  "user",
userId: "user-123",
});

Update by state ID

Update a state you already have the state_id for. Only value and content_type can be changed.

await client.agents.customStates.update("agent-id", stateId, {
value: 60,
});

Delete

Delete by state ID or by composite key.

// Delete by key
await client.agents.customStates.deleteByKey("agent-id", {
key:    "energy",
scope:  "user",
userId: "user-123",
});

// Delete by state_id
await client.agents.customStates.delete("agent-id", stateId);

Method summary

Combines with other features

With Custom Tools — tools that read and write state

Define a tool that lets the agent trigger a state change from inside a conversation. Your backend executes the tool call and calls upsert to apply the new value.

await client.agents.sessions.setTools("agent-id", "session-id", [
  {
    name: "spend_energy",
    description: "Deduct energy from the user. Call when the user takes an action that costs energy.",
    parameters: {
      type: "object",
      properties: {
        amount: { type: "number", description: "Energy to deduct (1–50)" },
      },
      required: ["amount"],
    },
  },
]);

// In your tool handler:
// 1. Receive externalToolCall { name: "spend_energy", arguments: { amount: 10 } }
// 2. Read current energy with getByKey
// 3. Upsert the new value
// 4. Return the result in the next chat message

With Inventory — when state is structured, use inventory

Custom State is the right tool for primitive values and simple flat objects: energy: 80, tier: "gold", onboarding_complete: true. When a piece of data has its own identity, multiple typed properties, and a shared schema across users — a medication, a stock holding, a pet — use Inventory instead.

With Sessions — session-scoped vs persistent state

Custom State is persistent by default — it survives across sessions and is visible in every future conversation. If you need state that only exists for the duration of one conversation (a temporary form-fill context, a one-time confirmation token), scope it at the session level instead by passing it in the chat request's context fields rather than writing it as a Custom State.

Tutorials

• Custom States walkthrough — end-to-end example: create, upsert, read during chat, trigger events on state changes

Next steps

Custom Tools let the LLM invoke functions during inference. Sonzai handles sonzai_-prefixed built-in tools automatically. Custom tools are defined by you and executed by your backend — Sonzai surfaces the call as a side effect in the SSE stream.

What you can build with it

• Expressive companion actions — emote, change outfit, move scene, give a gift
• Backend integrations — create_ticket, lookup_order, schedule_meeting
• State mutations — tools that read or write Custom State on behalf of the agent
• Approval-gated workflows — propose an action, your backend validates before executing
• Context-sensitive tools — inject different tool sets per session depending on user role or screen

Quickstart

Register a session-level tool and handle its call in the next chat turn.

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

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

// 1. Register a tool for this session
await client.agents.sessions.setTools("agent-id", "session-id", [
{
  name: "check_status",
  description: "Return the current operational status. Call when the user asks about system health.",
  parameters: { type: "object", properties: {} },
},
]);

// 2. Chat — tool calls appear in sideEffects
const toolCalls: { name: string; arguments: Record<string, unknown> }[] = [];
for await (const event of client.agents.chatStream({
agent:  "agent-id",
userId: "user-123",
messages: [{ role: "user", content: "What's the current status?" }],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
toolCalls.push(...(event.sideEffects?.externalToolCalls ?? []));
}

// 3. Execute and return results
const results = await Promise.all(toolCalls.map(c => myBackend.run(c.name, c.arguments)));
for await (const event of client.agents.chatStream({
agent:  "agent-id",
userId: "user-123",
messages: [
  { role: "user", content: "What's the current status?" },
  { role: "tool", content: results.join("\n") },
],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

Core concepts

Built-In Tools (Capabilities)

Toggle platform-managed capabilities per agent. These are enabled at agent creation or updated via the capabilities API.

// Set capabilities at agent creation
const agent = await client.agents.create({
agentId: "your-stable-uuid",  // recommended — makes creation idempotent
name: "Luna",
big5: { openness: 0.75, conscientiousness: 0.6, extraversion: 0.8,
        agreeableness: 0.7, neuroticism: 0.3 },
toolCapabilities: {
  webSearch:       true,
  rememberName:    true,
  imageGeneration: false,
  inventory:       true,
},
});

// Or update capabilities on an existing agent
await client.agents.update("agent-id", {
toolCapabilities: {
  webSearch: false,
  inventory: true,
},
});

customTools in agent capabilities

AgentCapabilities includes a customTools field — a snapshot of the agent-level custom tools currently registered. Use get_capabilities() to read them, or use the dedicated list_custom_tools() / createCustomTool() methods (shown in the Full API section below) to manage them.

// Read agent capabilities — includes current custom tools
const caps = await client.agents.getCapabilities("agent-id");
console.log(caps.customTools);  // CustomToolDefinition[] | null

// Register a new agent-level custom tool
await client.agents.createCustomTool("agent-id", {
name: "lookup_order",
description: "Look up an order by ID and return its status.",
parameters: {
  type: "object",
  properties: {
    order_id: { type: "string" },
  },
  required: ["order_id"],
},
});

Tool scoping

Full API

Custom Tools (Agent-Level)

Persistent tools stored with the agent and available in every chat, regardless of session or instance.

// Create a custom tool
await client.agents.createCustomTool("agent-id", {
name: "check_inventory",
description: "Check the user's current tasks and their statuses",
parameters: {
  type: "object",
  properties: {
    item_type: {
      type: "string",
      description: "Filter by category: active, pending, completed",
    },
  },
},
});

// List all custom tools
const tools = await client.agents.listCustomTools("agent-id");

// Update a tool's description or parameters
await client.agents.updateCustomTool("agent-id", "check_inventory", {
description: "Check and summarize the user's tasks by category",
});

// Delete a tool
await client.agents.deleteCustomTool("agent-id", "check_inventory");

Session-Level Tools (temporary)

Inject tools dynamically for a specific session. Session tools merge with agent-level tools — same-name session tools take precedence. Discarded when the session ends.

Option 1 — Set for an existing session

await client.agents.sessions.setTools("agent-id", "session-id", [
{
  name: "execute_action",
  description: "Execute an action from the agent's capabilities",
  parameters: {
    type: "object",
    properties: {
      action_name: { type: "string" },
      target:      { type: "string" },
    },
    required: ["action_name"],
  },
},
]);

Option 2 — Pass inline with the chat call

for await (const event of client.agents.chatStream({
agent:    "agent-id",
messages: [{ role: "user", content: "Check my tools" }],
userId:   "user-123",
toolDefinitions: [
  {
    name:        "check_inventory",
    description: "List the agent's active tools",
    parameters:  { type: "object", properties: {} },
  },
],
})) {
// handle events...
}

Handling Tool Calls

When the LLM decides to call a custom tool, it appears as a side effect in the SSE stream. Your backend executes the tool and returns the result in the next message.

1. Receive the tool call

const toolCalls: { name: string; arguments: Record<string, unknown> }[] = [];

for await (const event of client.agents.chatStream({
agent:    "agent-id",
messages: [{ role: "user", content: "What tasks do I have?" }],
userId:   "user-123",
})) {
// Stream content to the user
const content = event.choices?.[0]?.delta?.content;
if (content) process.stdout.write(content);

// Collect tool calls from side effects
const calls = event.sideEffects?.externalToolCalls ?? [];
toolCalls.push(...calls);
}

2. Execute and return results

// Execute your tool calls on your backend
const toolResults: string[] = [];
for (const call of toolCalls) {
const result = await myBackend.executeTool(call.name, call.arguments);
toolResults.push(result);
}

// Return results in the next chat message
for await (const event of client.agents.chatStream({
agent:    "agent-id",
userId:   "user-123",
messages: [
  { role: "user",  content: "What tasks do I have?" },
  { role: "tool",  content: toolResults.join("\n") },
],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

In Practice

What you expose as tools differs sharply by use case — keep descriptions vivid and tightly scoped so the LLM invokes them naturally.

await client.agents.sessions.setTools("agent-id", "session-id", [
  {
    name: "change_scene",
    description: "Move to a new location in the story. Use when the scene has run its course or a new chapter begins.",
    parameters: { type: "object", properties: { location: { type: "string" } }, required: ["location"] },
  },
]);

Combines with

Custom State — what tools often act on

Define a tool that lets the agent trigger a state change from inside a conversation. Your backend executes the tool call and calls upsert to apply the new value.

await client.agents.sessions.setTools("agent-id", "session-id", [
  {
    name: "spend_energy",
    description: "Deduct energy from the user. Call when the user takes an action that costs energy.",
    parameters: {
      type: "object",
      properties: {
        amount: { type: "number", description: "Energy to deduct (1–50)" },
      },
      required: ["amount"],
    },
  },
]);

// In your tool handler:
// 1. Receive externalToolCall { name: "spend_energy", arguments: { amount: 10 } }
// 2. Read current energy with getByKey
// 3. Upsert the new value
// 4. Return the result in the next chat message

Sessions — session-scoped vs persistent tools

Agent-level tools persist across all sessions. Session-level tools are injected at runtime and discarded when the session ends — use them when the available tool set depends on the current screen, user role, or conversation context.

Conversations — tool calls in the message stream

Tool calls appear as side effects in the SSE stream. See the Conversations page for the full event shape and streaming patterns.

Tutorials

• Custom States walkthrough — end-to-end example that includes a spend_energy tool writing back to Custom State

Next steps

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

Your backend knows things the agent doesn't: a user just levelled up, an order shipped, a milestone was hit. TriggerEvent lets you push those signals to an agent and get a tailored reaction — no user message required. Dialogue lets you orchestrate two agents talking to each other, turn by turn, so you can build NPC conversations, run evaluation simulations, or script automated specialist hand-offs.

Both primitives use the same enriched context pipeline as regular chat — the agent draws on memory, personality, and mood when it responds.

What you can build with it

Events

• Level-up celebrations — your game backend detects a rank change and fires a level_up event; the agent congratulates the user in its own voice
• Daily summaries — a cron job fires a daily_summary event with session stats in metadata; the agent writes a personalised recap
• Achievement unlocks — trigger a proactive message the moment a user hits a milestone, so the agent's enthusiasm lands while the moment is fresh
• External state changes — order shipped, appointment confirmed, subscription renewed; the agent reacts to your system events rather than waiting for the user to ask

Multi-Agent Dialogue

• NPC interactions — two character AIs converse while the user watches; each agent stays in its own voice and draws on its own memory
• Simulation runs — iterate N agents through scripted scenarios for offline evaluation without a real user in the loop
• Specialist hand-offs — agent A poses a question to agent B and incorporates the answer before responding to the user

Quickstart — Trigger an event

Fire a level_up event with structured metadata. The agent generates a reaction and the platform queues it for delivery through the same channels as other proactive messages.

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

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

const result = await client.agents.triggerBackendEvent("agent_abc", {
userId: "user_123",
eventType: "level_up",
eventDescription: "The user just reached level 25 — a major milestone in the game.",
metadata: {
  new_level: "25",
  previous_level: "24",
  xp_total: "12500",
},
});

console.log(result.accepted); // true
console.log(result.event_id); // "evt_01HX..."

Quickstart — Run a dialogue

Dialogue is a per-agent call. To run a conversation between two agents, you orchestrate turns yourself: call agent A, append its response to the message history, call agent B with that updated history, and so on. Each agent independently draws on its own memory and personality.

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

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

// Seed the conversation — agent_b opens with the first message
const messages = [
{ role: "user" as const, content: "Tell me something interesting about the ancient ruins." },
];

// Turn 1 — agent_a responds
const turnA = await client.agents.dialogue("agent_a", {
userId: "user_123",
messages,
sceneGuidance: "Two NPCs are exploring ancient ruins together. Keep responses under 3 sentences.",
});

messages.push({ role: "assistant", content: turnA.response });

// Turn 2 — agent_b responds to what agent_a said
const turnB = await client.agents.dialogue("agent_b", {
userId: "user_123",
messages,
sceneGuidance: "Two NPCs are exploring ancient ruins together. Keep responses under 3 sentences.",
});

console.log("Agent A:", turnA.response);
console.log("Agent B:", turnB.response);

Core concepts

Events

EventType is free-form. There is no fixed enum. Common conventions used by tenants: "achievement", "daily_summary", "level_up", "order_shipped", "appointment_confirmed", "milestone". Pick names that are meaningful in your domain and stay consistent across your backend.

EventDescription is for the LLM. Write it as plain-English narration: "The user just cleared chapter 5 for the first time after 3 failed attempts." The agent's underlying model reads this and uses it to shape the reaction — be specific rather than terse.

Metadata is string-only. The metadata map accepts string → string pairs only. For nested or numeric data, either serialize into the event_description or flatten it with explicit keys ("xp_gained", "xp_total", "level_before", "level_after").

Messages field grounds the event in a prior conversation. If the event is closely tied to a conversation that just ended (for example, a daily_summary fired after a chat session), pass the recent messages. The platform uses them directly for context-sensitive generation — diary entries, summaries — instead of relying on lossy consolidation. Omit this field for cron-driven events that have no associated conversation.

TriggerEventResponse contains two fields:

• accepted (bool) — whether the platform accepted the event for processing
• event_id (string) — an opaque identifier for the queued event; store it if you want to correlate platform logs

Dialogue

Each call is per-agent. The dialogue method is scoped to a single agent: you pass an agentId and the current message history. To model a conversation between two agents, you manage the turn loop — append each response to the shared messages slice and alternate which agentId you call.

Messages carry the full context. Unlike chat, which manages conversation history server-side per session, dialogue expects you to pass the full message thread with every call. You control the window.

sceneGuidance steers both tone and constraints. Pass a brief instruction describing the scene and any constraints ("keep responses under 3 sentences", "the agents are rivals", "agent_a does not know about the treasure") so both sides stay in character.

requestType signals the call's purpose. An optional free-form tag ("npc_scene", "eval_round", "specialist_consult") that downstream analytics can use for filtering. Has no effect on generation.

DialogueResponse contains:

• response (string) — the agent's generated text for this turn
• side_effects — optional structured metadata emitted by the agent (tool calls, mood signals, etc.)

Full API

TriggerEventOptions / trigger_backend_event kwargs:

DialogueOptions / dialogue kwargs:

Combines with other features

With Proactive Messaging — events as the dev-controlled push source

Proactive Messaging has three sources: Scheduled Reminders (recurring cadence), Wakeups (one-off timed), and TriggerEvent (your backend fires it when something happens). TriggerEvent is the push-based source you control directly — no schedule required, no timer running. When the event is accepted, the platform routes the generated reaction through the same delivery channels as the other two sources: SSE if the user has an active stream, the polling notifications API, or your registered webhook.

// Proactive triangle in code form:

// Source 1 — recurring schedule (time-based)
await client.schedules.create("agent_abc", "user_123", {
  cadence: { simple: { frequency: "daily", times: ["09:00"] }, timezone: "Asia/Tokyo" },
  intent: "morning check-in",
  check_type: "reminder",
});

// Source 2 — one-off wakeup (time-based)
await client.agents.scheduleWakeup("agent_abc", {
  user_id: "user_123",
  check_type: "appointment_reminder",
  intent: "remind the user about their dentist appointment",
  delay_hours: 2,
});

// Source 3 — TriggerEvent (you push it when something happens)
await client.agents.triggerBackendEvent("agent_abc", {
  userId: "user_123",
  eventType: "appointment_confirmed",
  eventDescription: "The user just confirmed their 3pm dentist appointment for tomorrow.",
});

With Conversations — Messages field grounds the event in context

When a TriggerEvent fires immediately after a chat session — for example, a daily_summary event at session end — pass the recent conversation messages in the messages field. The platform uses them directly as conversation history for context-sensitive generation (diary entries, personality updates) instead of relying on condensed consolidation summaries. The agent's reaction then references what was actually said rather than a lossy reconstruction.

// After a chat session ends, fire a daily_summary event with the full message history
const sessionMessages = [
  { role: "user", content: "I finally finished that project I was stressing about." },
  { role: "assistant", content: "That's huge! You've been working on that for weeks." },
  { role: "user", content: "Yeah. Feels good. Think I'll take the evening off." },
];

await client.agents.triggerBackendEvent("agent_abc", {
  userId: "user_123",
  eventType: "daily_summary",
  eventDescription: "Session ended. User shared a work win and plans to rest.",
  messages: sessionMessages, // grounds the summary in what was actually said
});

With Evaluation — Dialogue as a scoring harness

Run a judge agent and a subject agent in a dialogue loop to score the subject's responses without a real user. The judge poses questions, the subject answers, and you feed both transcripts to your evaluation rubric. This lets you evaluate agent quality at scale offline.

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

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

const JUDGE_AGENT    = "agent_judge";
const SUBJECT_AGENT  = "agent_subject";
const USER_ID        = "eval_run_001";

const messages = [
  { role: "user" as const, content: "I'm feeling really overwhelmed lately." },
];

// Subject responds to the user prompt
const subjectTurn = await client.agents.dialogue(SUBJECT_AGENT, {
  userId: USER_ID,
  messages,
  requestType: "eval_round",
});

messages.push({ role: "assistant", content: subjectTurn.response });

// Judge scores the subject's response
const judgeTurn = await client.agents.dialogue(JUDGE_AGENT, {
  userId: USER_ID,
  messages,
  sceneGuidance:
    "You are evaluating the previous assistant response for empathy and clarity. " +
    "Return a JSON object with keys: score (0–100), feedback (string).",
  requestType: "eval_judge",
});

console.log("Subject:", subjectTurn.response);
console.log("Judge verdict:", judgeTurn.response);

// Then score the exchange through the evaluation API
const evalResult = await client.agents.evaluate(SUBJECT_AGENT, {
  templateId: "empathy-rubric",
  messages,
});
console.log("Eval score:", evalResult.score);

Tutorials

• Medication Reminders — end-to-end example using Schedule + TriggerEvent + Memory together
• Scheduled Reminders walkthrough — covers cadence patterns that pair with events

Next steps

• Proactive Messaging — the three sources and delivery channels
• Conversations — regular agent chat mechanics
• Scheduled Reminders — recurring cadence primitive
• Evaluation — scoring agent responses

Generation covers two distinct capabilities: agent generation (spinning up a complete character — bio, personality, seed memories, avatar — from a text description) and media generation (producing images on demand during a chat turn). Both live under client.agents.generation and client.agents.image.

What you can build with it

• One-click character creation — spec a rough prompt, get a complete agent profile + avatar
• Avatar regeneration — refresh an agent's look as the character evolves over time
• Seed memories — plant backstory facts the agent "remembers" from day 1
• In-chat image generation — agent creates pictures as part of its responses
• Character templates — generate many similar agents from a shared base prompt

Quickstart

Generate a character + create the agent

The single fastest path: one call generates a full personality profile and provisions the agent. Safe to call on every deploy — if the agent already exists, the LLM is skipped.

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

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

const agent = await client.agents.generation.generateAndCreate({
name: "Luna",
description: "A cheerful and curious assistant who loves helping developers debug code.",
language: "en",
});

console.log(agent.agent_id);

Generate an image in-chat

Call client.agents.image.generate with the agent ID and a prompt during or alongside a chat turn.

const image = await client.agents.image.generate("agent-id", {
prompt: "A serene mountain landscape at sunset",
});

console.log(image.url);          // public CDN URL
console.log(image.generationTimeMs);

Capabilities — image, music, and video generation

Three AgentCapabilities flags gate media generation. Each flag is a boolean on the agent, and each has a paired *UnlockedAt timestamp that records when the capability was granted (typically via a tier upgrade or admin enable). Generation calls fail if the flag is false.

imageGeneration is the only media flag you can toggle directly via update_capabilities(). musicGeneration and videoGeneration are platform-managed — they flip when your plan includes those capabilities. Use get_capabilities() to inspect their current state.

// Read current media capability flags
const caps = await client.agents.getCapabilities("agent-id");
console.log(caps.imageGeneration);  // true | false
console.log(caps.imageUnlockedAt);  // "2024-11-01T00:00:00Z"
console.log(caps.musicGeneration);  // true | false
console.log(caps.videoGeneration);  // true | false

// Enable image generation (if your plan allows it)
await client.agents.updateCapabilities("agent-id", { imageGeneration: true });

Core concepts

Character generation

Character generation takes a natural-language description and produces a structured agent profile. You can generate the profile and immediately create the agent (GenerateAndCreate), or generate the profile first for preview and commit only on user approval (GenerateCharacter).

Input: name, description, optional fields filter, optional gender, optional LLM provider/model override, optional regenerate flag.

Output: bio, personality prompt, Big5 scores, speech patterns, interests, dislikes, primary traits, dimensions, interaction preferences, behavioral traits, initial goals.

The Regenerate flag forces a fresh generation even when a cached profile is found — useful for iteration flows where the user wants a different result without deleting the agent.

// Preview without committing
profile, err := client.Agents.Generation.GenerateCharacter(ctx, sonzai.GenerateCharacterOptions{
    Name:        "Atlas",
    Description: "A stoic, wise mentor who speaks in metaphors and values patience above all.",
    Fields:      []string{"big5", "dimensions", "preferences", "behaviors"},
    Regenerate:  true,   // force a fresh pass
})

Bio generation (GenerateBio) and avatar regeneration (RegenerateAvatar) are narrower variants — they update a single attribute of an existing agent without touching the rest of the profile.

Seed memories work in two steps:

1. Generate — GenerateSeedMemories calls an LLM to produce backstory memories from the agent's personality, interests, and lore context.
2. Store — SeedMemories bulk-imports a list of memory objects (generated or hand-authored) into the agent's memory store.

You can run both steps separately for fine-grained control, or set storeMemories: true on the generate call to do both in one request.

Media generation

Image generation is agent-scoped: client.agents.image.generate(agentID, opts). The agent ID is used to apply the agent's visual style and context to the generation request.

Input: prompt (required), optional negative_prompt, optional model/provider override, optional output_bucket/output_path for custom storage routing.

Output: image_id, public_url, mime_type, generation_time_ms.

Images are generated synchronously — the call blocks until the image is ready and returns a public CDN URL. For high-throughput workflows, fan out parallel calls rather than queuing.

Full API

Combines with other features

With Personality — character generation sets initial Big5

generateCharacter (and generateAndCreate) returns a full Big5 profile derived from the description. The platform uses these scores directly as the agent's personality baseline — no manual personality.update call needed.

// Generate the profile — inspect Big5 before committing
const profile = await client.agents.generation.generateCharacter({
name: "Atlas",
description: "A stoic, wise mentor who speaks in metaphors and values patience above all.",
fields: ["big5", "dimensions", "preferences", "behaviors"],
});

console.log(profile.big5);
// { openness: 0.72, conscientiousness: 0.85, extraversion: 0.35,
//   agreeableness: 0.63, neuroticism: 0.22 }

// Then create with those exact scores
const agent = await client.agents.create({
name: "Atlas",
big5: profile.big5,
});

With Memory — seed memories plant backstory

Generate memories from the agent's personality context, then seed them into the memory store. They appear immediately in memory.list and are recalled in the agent's first conversations.

// Step 1: generate backstory memories from personality context
const generated = await client.agents.generation.generateSeedMemories("agent-id", {
agentName: "Luna",
trueInterests: ["astronomy", "poetry", "hiking"],
trueDislikes: ["loud noises", "dishonesty"],
generateOriginStory: true,
generatePersonalizedMemories: true,
});

console.log(`Generated ${generated.memories.length} memories`);

// Step 2: store them (or pass storeMemories: true above to do both in one call)
await client.agents.generation.seedMemories("agent-id", {
userId: "user-123",
memories: generated.memories,
});

// Step 3: verify they appear in memory
const stored = await client.agents.memory.list("agent-id", { userId: "user-123" });
console.log(stored);

With Conversations — image generation as a chat capability

Call image.generate within a chat turn to let the agent produce images as part of its response. Render the returned URL alongside the text content.

// Inside a chat turn handler
const response = await client.agents.chat({
agent: "agent-id",
userId: "user-123",
messages: [{ role: "user", content: "Draw me a cozy forest cabin at night." }],
language: "en",
});

// If the agent decides to produce an image, generate it
const image = await client.agents.image.generate("agent-id", {
prompt: "A cozy forest cabin at night, warm light through windows, snow falling",
});

// Render both in your UI
renderChatBubble(response.content);
renderImage(image.url);

In Practice

const agent = await client.agents.generation.generateAndCreate({
  name: userInput.name,
  description: userInput.description,
  language: "en",
});

Tutorials

• Tutorial: Seed memories from scratch

Next steps

• Personality — understand the Big5 profile that generation produces
• Memory — how seed memories integrate with the live memory system
• Conversations — wiring image generation into a chat turn

Sonzai is the Mind Layer for AI agents: a hosted platform that gives any agent persistent memory, evolving personality, mood, relationships, and a knowledge graph. Integrate via REST, MCP, or native SDKs for TypeScript, Python, and Go.

Install

Pick the path that matches your stack. All paths talk to the same hosted API — mix and match freely (e.g. backend in Python, plus MCP from Claude Desktop for ops).

pip install sonzai

• Python 3.11+. Sync (Sonzai) and async (AsyncSonzai) clients ship in the same package.
• TypeScript runs on Node.js >=18, Bun, and Deno. Zero runtime dependencies.
• Go 1.25+. Standard library only.
• All SDKs read SONZAI_API_KEY from the environment by default.
• OpenClaw itself is required for the OpenClaw path — install it from openclaw.ai (Getting Started).
• Full guides: MCP · OpenClaw · REST API Reference.

Need an API key first? Create a project at platform.sonz.ai, then jump to the Quickstart for the full walkthrough.

What are you building?

Pick the track that matches your product. Each quickstart walks through the features that matter for your use case — and explicitly flags what you can skip.

Core Capabilities

Every feature below works for all three audiences, but the emphasis differs. Use the In practice tabs on each page to jump to examples for your use case.

Integration

For AI Agents

Feeding Sonzai docs to an AI assistant? Every page has a Copy for LLM button, and the bundles below are pre-formatted for ingestion.

Each page also has a raw-markdown URL: append .md to any doc path. For example, /docs/en/memory.md returns plain markdown ready to paste into an LLM or pipe into a tool.

How It Fits Into Your Application

Your backend handles business logic and user sessions. The Mind Layer owns agent intelligence — personality, memory, mood, and relationships. Connect via REST, MCP, or SDK; pass application context per request; let the platform manage everything else.

Read the full integration guide →

Instances let you run a single agent across many isolated deployment contexts without cloning the agent itself. The shared parts — personality, memory, tools, voice — stay unified, while custom states are scoped per instance so a US-East workspace, an EU-West tenant, and a staging environment never see each other's data. Every agent gets a default instance for free; you only need explicit instances when the same AI Employee runs in parallel contexts that must not share runtime state.

What is an Instance?

An Instance is a deployment context for an agent. The agent itself (personality, memory, tools) is shared — but custom state is isolated per instance.

Agent "Luna"
├── Instance: default          ← used when instanceId is omitted
├── Instance: ws-us-east       ← US-East workspace
├── Instance: ws-eu-west       ← EU-West workspace
└── Instance: ws-staging       ← separate deployment

Each instance has its own:
• Global custom states (environment state, configuration)
• Per-user custom states scoped to this instance
• Isolated from other instances

List Instances

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

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

const instances = await client.agents.instances.list("agent-id");

for (const inst of instances) {
console.log(inst.instanceId, inst.name, inst.isDefault, inst.status);
}

Create an Instance

const instance = await client.agents.instances.create("agent-id", {
name: "Workspace US-East",
description: "US-East production workspace",
});

console.log(instance.instance_id); // store this

Get an Instance

const instance = await client.agents.instances.get(
"agent-id",
"instance-id",
);

console.log(instance.name, instance.status, instance.isDefault);

Update an Instance

await client.agents.instances.update("agent-id", "instance-id", {
name: "Workspace US-East (Production)",
status: "active",    // "active" | "inactive"
});

Reset an Instance

Clears all custom state data for an instance without deleting it. Useful for resetting an environment between sessions.

// Wipes all custom states scoped to this instance
await client.agents.instances.reset("agent-id", "instance-id");

Delete an Instance

await client.agents.instances.delete("agent-id", "instance-id");

Using Instances in Chat

Pass instanceId to chat calls to scope state reads to that instance. The agent will see global custom states for that instance and per-user states scoped to it.

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "What's the current status?" }],
userId:     "user-123",
instanceId: "ws-us-east",      // scopes state reads to this instance
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

Instance Data Model

• instanceId (string): Unique instance identifier
• agentId (string): Parent agent ID
• name (string): Human-readable label
• description (string?): Optional description
• status (string): "active" or "inactive"
• isDefault (boolean): True for the auto-created default instance
• createdAt (string): ISO 8601 timestamp
• updatedAt (string): ISO 8601 timestamp

Inventory is the place to store structured per-user data the agent should know about. Each item belongs to a single agent × user pair and follows a schema defined in your Knowledge Base, so the agent always has typed, queryable data rather than free-form text. When the agent adds an item it searches the KB by description to resolve and link the right node automatically.

What you can build with it

• Medication adherence — track each drug, dose, and schedule per user (pairs with Scheduled Reminders)
• Portfolio / holdings — stocks, crypto, collectibles with market-value joins via the KB
• Pet care — pets per user, feeding, vet, and growth tracking
• Goal tracking — user-defined goals with progress state
• Plants / hobbies — anything that follows a "user has N things of type T" pattern

Quickstart

Add a medication to a user's inventory. The response includes an inventory_item_id (and the backward-compatible fact_id alias) you can use for direct updates or deletes later.

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

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

// Preferred: dedicated create route — no action field needed
const result = await client.agents.inventory.create("agent_abc", "user_123", {
item_type: "medication",
label: "Metformin",
description: "Metformin 500mg — biguanide for blood sugar control",
properties: {
  dose_mg: 500,
  frequency: "twice daily",
  with_food: true,
},
});

console.log(result.inventory_item_id); // "inv_01HX..." (preferred)
console.log(result.fact_id);           // "fact_01HX..." (backward compat alias)
console.log(result.status);            // "added" | "disambiguation_needed"

// Alternative: explicit-action route (still supported for backward compat)
// await client.agents.inventory.update("agent_abc", "user_123", { action: "add", item_type: "medication", ... });

Core concepts

• Items belong to users — every item is scoped to agent_id × user_id; no item is shared across users
• Schema-driven shape — item_type references a KB schema that defines the valid property fields; the platform validates writes against it
• Two write paths for adding items — use inventory.create({...}) (dedicated route, no action field) for cleaner code when you specifically want to add; use inventory.update({action: "add", ...}) (explicit-action route) when you handle add/update/remove through a single call site. Both hit equivalent server logic.
• label vs description — label is a short display name for dashboards and agent UI (e.g. "Ibuprofen"); description is the longer text the KB search uses to resolve the right node (e.g. "anti-inflammatory pain reliever, 400mg"). Both are optional but providing both gives the clearest results.
• KB resolution — on add, Sonzai searches the KB by description; on ambiguous matches it returns candidates and status: "disambiguation_needed" so you can resolve before committing
• Query modes — "list" returns raw items, "value" joins with live KB market data and computes gain_loss, "aggregate" returns totals and grouped sums without listing every item

Full API

Response shape

InventoryUpdateResponse:

{
  "status": "added",
  "inventory_item_id": "inv_01HX...",
  "fact_id": "fact_01HX...",
  "kb_resolution": {
    "resolved": true,
    "kb_node_id": "node_xyz",
    "kb_label": "Metformin 500mg",
    "kb_properties": { "drug_class": "biguanide" }
  }
}

inventory_item_id is the preferred identifier going forward. fact_id is included for backward compatibility — both refer to the same item and are interchangeable in all subsequent API calls (direct update, direct delete, schedule linkage).

When status is "disambiguation_needed", the response includes a candidates array instead of kb_resolution. Re-submit with the chosen kb_node_id set explicitly to bypass the search.

Combines with other features

With Knowledge Base — schemas shape items

The item_type field points to a KB entity schema that defines which properties are valid for that type. Create the schema once; all inventory writes for that type are validated against it.

// 1. Define the schema in the KB once
await client.knowledge.createSchema("proj_abc123", {
entity_type: "medication",
fields: [
  { name: "dose_mg",    type: "number", required: true },
  { name: "frequency",  type: "string", required: true },
  { name: "with_food",  type: "boolean", required: false },
],
});

// 2. Inventory writes for item_type "medication" are now validated
await client.agents.inventory.update("agent_abc", "user_123", {
action: "add",
item_type: "medication",   // <-- resolves to the schema above
description: "Metformin 500mg",
properties: { dose_mg: 500, frequency: "twice daily", with_food: true },
});

With Scheduled Reminders — live data at fire time

A schedule can reference an inventory_item_id. At each fire, the agent reads the item's current properties rather than a snapshot baked into the schedule definition. Updating the item's dosage automatically flows to the next reminder without touching the schedule itself.

// Add the item first
const { fact_id } = await client.agents.inventory.update("agent_abc", "user_123", {
action: "add",
item_type: "medication",
description: "Metformin 500mg",
properties: { dose_mg: 500, frequency: "twice daily" },
});

// Reference it in a schedule — agent reads live properties at each fire
await client.schedules.create("agent_abc", "user_123", {
cadence: {
  simple: { frequency: "daily", times: ["08:00", "20:00"] },
  timezone: "America/New_York",
},
intent: "remind the user to take their medication",
inventory_item_id: fact_id,
});

With Memory — inventory state in conversation context

During a conversation the agent can query the user's inventory to answer questions like "what medications am I taking?" directly. Inventory writes also generate memory facts that surface in future sessions, so the agent can reference holdings and items across conversations without a manual query.

// Agent answers from inventory mid-conversation
for await (const event of client.agents.chatStream("agent_abc", {
userId: "user_123",
messages: [{ role: "user", content: "What medications am I on?" }],
})) {
// The agent calls sonzai_inventory internally to fetch the user's items
// and answers from live data — no extra code needed.
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

Tutorials

• Resource Inventory + Knowledge Base — full walkthrough with schema setup, upsert, bulk import, and portfolio queries
• Medication Reminders — worked example combining Inventory + Scheduled Reminders + Memory

Next steps

• Knowledge Base — the schema backbone that shapes inventory items
• Scheduled Reminders — live inventory data injection at fire time
• Memory — how inventory writes surface in chat context

Knowledge Analytics layers a ranking system on top of the Knowledge Base. Rules define scoring signals — per-user affinity for recommendations, aggregate velocity for trends — and readers fetch ranked results at query time with a single call. The graph backbone supplies the nodes and edges; analytics rules decide how to score and order them. The result is a reusable ranking layer that powers product recommendations, trending dashboards, and conversion tracking without building a separate data pipeline.

What you can build with it

• Product recommendations — "top-N products for this user" based on user affinity signals
• Trending topics — "what's rising this week across all users" via aggregate velocity scoring
• Conversion dashboards — which KB nodes convert (browse to engage to buy) and at what rate
• Per-segment ranking — different recommendation models for different user segments
• Feedback loops — record converted recommendations to continuously sharpen scoring over time

Quickstart

Create a recommendation rule, fetch ranked results for a user, then record whether the user acted on a recommendation.

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

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

// 1. Create a recommendation rule
const rule = await client.knowledge.createAnalyticsRule(projectId, {
rule_type: "recommendation",
name:      "product-affinity",
config:    { target_entity_type: "product", scoring: "affinity" },
enabled:   true,
schedule:  "0 * * * *",  // recompute hourly
});

// 2. Fetch top-5 recommendations for a user
const recs = await client.knowledge.getRecommendations(
projectId,
rule.rule_id,
"user_123",   // source_id — the user whose affinity to score against
5,
);

for (const rec of recs.recommendations) {
console.log(rec.target_id, rec.score);
}

// 3. Record that the user converted on the top result
await client.knowledge.recordFeedback(projectId, {
source_node_id: "user_123",
target_node_id: recs.recommendations[0].target_id,
rule_id:        rule.rule_id,
converted:      true,
score_at_time:  recs.recommendations[0].score,
});

Core concepts

• Rule types — "recommendation" scores nodes per source (e.g. per user), returning a personalised top-N list. "trend" aggregates signals across all sources, returning global velocity rankings.
• Config is rule-specific — the config object is a passthrough shape; its fields depend on the rule type and your scoring model. There is no fixed schema enforced by the SDK — pass whatever your rule implementation expects (e.g. target_entity_type, scoring, decay_factor).
• Source and target semantics — recommendations take a source_id (typically a user node ID) and return ranked nodes of the target entity type. The source must exist as a node in the Knowledge Base graph.
• Scheduled vs manual — rules can carry an optional cron schedule for batch recomputation (e.g. "0 * * * *" for hourly). Call RunAnalyticsRule at any time to trigger a manual run outside the schedule.
• Feedback closes the loop — RecordFeedback writes a signal back against the source, target, and rule. Subsequent recomputation can weight nodes that historically converted higher, sharpening ranking over time. Use the action field to record fine-grained user intent: "converted" (user completed the action), "clicked" (user opened the recommendation), "dismissed" (user explicitly rejected it), or "ignored" (recommendation was shown but user did not interact). action: "converted" sets converted: true automatically so existing aggregate conversion queries continue to work without changes.

Full API

Combines with other features

With Knowledge Base — the graph is the substrate

Analytics rules run over KB nodes and edges. Entity schemas define what types of nodes exist; rules score those nodes. The recommended pattern is to define your entity schema first, then create rules that target it.

// 1. Define a product schema in the KB
await client.knowledge.createSchema(projectId, {
entity_type: "product",
fields: [
  { name: "price",    type: "number", required: true },
  { name: "category", type: "string", required: true },
  { name: "in_stock", type: "boolean", required: true },
],
});

// 2. Push some product nodes
await client.knowledge.insertFacts(projectId, {
facts: [
  { entity_type: "product", label: "Razer Blade 16", properties: { price: 2999, category: "laptop", in_stock: true } },
  { entity_type: "product", label: "Razer DeathAdder V3", properties: { price: 79, category: "mouse", in_stock: true } },
],
});

// 3. Create a recommendation rule targeting the product entity type
const rule = await client.knowledge.createAnalyticsRule(projectId, {
rule_type: "recommendation",
name:      "product-recs",
config:    { target_entity_type: "product" },
enabled:   true,
});

With Inventory — per-user holdings drive per-user recommendations

Inventory writes create edges from a user node to the nodes they own. Those ownership edges flow into the recommendation model as affinity signals: items a user already owns inform which related nodes score highest.

// 1. User buys a product — record it in inventory
const { fact_id } = await client.agents.inventory.update("agent_abc", "user_123", {
action:      "add",
item_type:   "product",
description: "Razer DeathAdder V3",
properties:  { purchase_date: "2026-04-01" },
});

// 2. The inventory write creates a user→product edge in the KB graph.
//    The recommendation rule can now weight products related to the
//    DeathAdder higher for this user.
const recs = await client.knowledge.getRecommendations(
projectId,
rule.rule_id,
"user_123",
5,
);
// recs.recommendations may now include accessories or similar peripherals

With Agent Insights — conversation signals sharpen rankings

Agent Insights extract what users express interest in during conversations. Those interest signals can be passed into recommendation rule config as additional affinity weights, so a user who talks about budget peripherals gets different rankings than one who discusses high-end setups — without any explicit user input.

Tutorials

No dedicated Knowledge Analytics tutorial exists yet. The Knowledge Base tutorial covers schema setup and fact insertion — the prerequisite steps before creating analytics rules.

Next steps

• Knowledge Base — the graph backbone; define schemas and push nodes before creating rules
• Inventory — per-user holdings create user-to-node edges that feed the recommendation model
• Organization Knowledge Base — analytics rules can also run over org-scoped KB nodes for shared ranking across all users

The Knowledge Base gives your agents a live, searchable store of facts and documents — so they answer from real data instead of guessing. You push data in (via file upload or API), the platform builds a knowledge graph, and agents query it in real time. Schemas are the bridge to the Inventory primitive: the same entity types you define here back every per-user inventory item, letting a single schema serve both global knowledge and user-specific state.

It is also multiplayer. Agents can autonomously write what they learn during conversations back into the project KB, where every other agent on the project reads it on the next session — a closed-loop company brain that compounds the way human institutional memory does. And a single agent serving a team can carry attributed memory across users, so it can inform user A with the context it gathered while talking to user B. See Multiplayer memory below.

How knowledge gets into the KB

There are two ways to populate the knowledge base, plus one optional capability you toggle on top of either of them:

1. Manual upload. Drop in a PDF, DOCX, Markdown, or plain text file via the SDK or the dashboard. The platform extracts entities and relationships automatically and writes them to the graph. Use this for static documents you control — handbooks, policies, product manuals, lore. One-shot, or re-uploaded whenever the source changes. → Upload a document

2. ETL job that pushes on delta changes. Define an entity schema once; have your job call insertFacts or bulkUpdate on a schedule, queue, or change-data-capture stream. Use this for live upstream sources of truth — databases, price feeds, CMSes, scrapers — so the KB stays in sync as the source changes. Upserts are idempotent; pushing the same label twice merges properties and increments the version, so the same job is safe to re-run on any cadence. → Define a schema, then push facts

+ Autonomous agent editing (optional toggle — enable or disable per agent or project-wide). Flip the knowledgeBaseWrite capability on and agents get knowledge_create / knowledge_update / knowledge_delete tools. During conversations they record verified facts themselves, with a full audit trail (each write is stamped source = "agent:<agent-id>") and compare-and-swap update semantics so concurrent admin edits never get clobbered. Use this when the source of truth IS the conversation — support agents recording verified incident details, customer-success agents capturing renewal context, scribe agents writing meeting notes. → Agents writing to the knowledge base

The two ingestion paths are independent — pick either, both, or neither. Autonomous editing is a per-agent toggle (or a project-wide default via default_agent_kb_write) that sits on top of whichever ingestion paths you're already running. You stay in control: every agent write is server-side validated against your schema, capped by quotas, scoped to the agent's own project, and reversible — soft-delete only, hard delete stays admin-only.

Manual upload          ETL on delta changes      Agent in conversation
 (PDF / DOCX / MD)      (insertFacts / bulkUpdate) (knowledge_create / update / delete)
      |                          |                          |
      |                          |                          | requires
      |                          |                          | knowledgeBaseWrite: true
      v                          v                          v
 +----------------------------------------------------------------+
 |                  Project Knowledge Graph                       |
 |    entities + relationships + version history + audit trail   |
 +----------------------------------------------------------------+
                            |
                            v
              Agents read via knowledge_search
              during every conversation

What you can build with it

• Real-time product Q&A — push a live product catalog and let agents answer "what's in stock under $50?" with current prices and availability
• Medication or supplement advisor — store drug and dosage facts; the agent surfaces the right information when a user asks about interactions or timing
• Collectibles price tracker — scrape market prices hourly, push via bulkUpdate, and let agents answer "what's trending up this week?" with real data
• Internal knowledge assistant — upload employee handbooks, policy docs, and product manuals; agents ground answers in authoritative sources instead of hallucinating
• Personalized recommender — define recommendation rules on entity fields (set, rarity, budget) and surface the top matches for each user at conversation time

Quickstart

Upload a document

Upload a PDF, DOCX, Markdown, or plain text file. The platform extracts entities and relationships automatically.

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

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

const doc = await client.knowledge.uploadDocument(projectId, {
file:     fs.createReadStream("product_catalog.pdf"),
fileName: "product_catalog.pdf",
});

console.log(doc.documentId, doc.status); // "processing"

Define a schema, then push facts

Define typed fields for an entity type, then insert structured facts. Good for scrapers, inventory feeds, and price trackers.

// 1. Create a schema
await client.knowledge.createSchema(projectId, {
entity_type: "pokemon_card",
display_name: "Pokémon Card",
description: "Collectible trading cards",
fields: [
  { name: "price",     type: "number", required: true },
  { name: "condition", type: "enum",   enum_values: ["PSA 10", "PSA 9", "Raw"] },
  { name: "set",       type: "string", required: true },
  { name: "rarity",    type: "enum",   enum_values: ["Common", "Uncommon", "Rare", "Ultra Rare"] },
  { name: "tags",      type: "array" },
  { name: "internal_sku", type: "string", indexed: false }, // stored but not BM25-searchable
],
similarity_config: {
  match_fields: ["set", "rarity"],
  threshold: 0.7,
},
});

// 2. Insert facts
await client.knowledge.insertFacts(projectId, {
source: "price_sync",
facts: [
  {
    entity_type: "pokemon_card",
    label: "Charizard Base Set",
    properties: { price: 450, condition: "PSA 10", set: "Base Set", rarity: "Rare" },
  },
],
relationships: [
  { from_label: "Charizard Base Set", to_label: "Fire Pokemon", edge_type: "is_type" },
],
});

Core concepts

Knowledge graph

Entities are nodes; relationships are typed edges. Nodes deduplicate by normalized label + type — pushing the same label twice merges properties and increments the version. Every change is recorded in version history with source and timestamp, giving you a full audit trail. The graph is completely domain-agnostic: you define entity types and relationship types; the platform stores and indexes them.

Similarity edges

When a schema has a similarity_config, the platform automatically creates similar_to edges between entities whose match_fields values are close enough to exceed the threshold. This turns structured fields into graph topology without any extra work — and powers the recommendation engine.

Entity type naming: entity_type vs display_name

entity_type is the machine-readable slug used everywhere in the API (e.g. "pokemon_card"). It is how inventory writes and KB lookups reference the schema. display_name is the optional human-friendly label shown in the dashboard and agent tool descriptions (e.g. "Pokémon Card"). If display_name is omitted, the dashboard falls back to a title-cased version of entity_type.

Controlling BM25 indexing per field

By default every field value is included in the BM25 full-text index so agents can find nodes by searching field contents. Set indexed: false on a field to exclude it from the search index — the value is still stored and returned in reads, but it will not match keyword queries. Use this for fields that should be readable but not searchable, for example:

• Internal identifiers (sku, barcode, external_id) that should never surface in agent search results
• High-cardinality numeric values like dosage amounts on a medication schema, where token matching produces noise rather than signal
• Raw HTML or markdown blobs that you render in UI but do not want polluting search

fields: [
  { name: "name",    type: "string", required: true },           // searchable
  { name: "dosage",  type: "string", indexed: false },           // stored-only
  { name: "sku",     type: "string", indexed: false },           // stored-only
]

Upsert semantics

insertFacts and bulkUpdate default to upsert mode (upsert: true): if a node with the same label + type exists, its properties are merged and the version is incremented; if it does not exist, it is created. This makes idempotent syncs safe to run on any schedule.

Set upsert: false for strict update-only semantics: nodes that do not already exist are skipped rather than created, and their IDs appear in the response not_found list. Use this when you want to ensure you are only patching existing data and never accidentally inserting stale or erroneous entries from an upstream feed.

How agents use the graph

During conversations, agents have access to a knowledge_search tool that queries your graph. Instead of hallucinating facts, the agent calls this tool and returns grounded answers. The search result includes the entity's properties, relevance score, and any related nodes reachable via one-hop traversal.

Full API

All SDK methods are on client.knowledge.* (TS/Python) or client.Knowledge (Go).

Documents

Schemas

Facts and graph

Search

Analytics

Combines with other features

With Inventory — shared schemas for per-user items

Inventory items are knowledge graph nodes scoped to a specific user. The same entity_type you define in a KB schema can back both global knowledge entries and per-user inventory items, so the agent reasons across both surfaces with a single mental model. When you call inventory.update with action: "add", the platform creates a node in the graph and returns a fact_id — the same identifier you use in KB lookups.

// Add a per-user inventory item that lives in the knowledge graph
const item = await client.agents.inventory.update("agent_abc", "user_123", {
  action:      "add",
  item_type:   "medication",
  description: "Ibuprofen 500mg",
  project_id:  "proj_abc",
  properties: {
    medication_name: "ibuprofen",
    dosage:          "500mg",
    frequency:       "twice daily",
  },
});

// item.fact_id is a knowledge graph node ID — use it for KB lookups or schedule linkage
console.log(item.fact_id);

With Scheduled Reminders — live data injection at fire time

A schedule can reference an inventory_item_id (a fact_id from the graph). At every fire the platform reads the item's current properties from the knowledge graph and injects them into the agent's wakeup block. This means a dosage change or property update flows through to the next reminder with no schedule edit required — the graph is the single source of truth for what the reminder is about.

// 1. Create the inventory item (returns fact_id)
const item = await client.agents.inventory.update("agent_abc", "user_123", {
  action:      "add",
  item_type:   "medication",
  description: "Ibuprofen",
  project_id:  "proj_abc",
  properties: { medication_name: "ibuprofen", dosage: "500mg" },
});

// 2. Link the schedule — at every fire the graph is re-read for live properties
await client.schedules.create("agent_abc", "user_123", {
  cadence: {
    simple: { frequency: "daily", times: ["08:00", "20:00"] },
    timezone: "Asia/Singapore",
  },
  intent:             "remind the user to take their ibuprofen at the correct dose",
  check_type:         "reminder",
  inventory_item_id:  item.fact_id,
});

With Knowledge Analytics — graph becomes a recommender

Define analytics rules on your entity graph to surface recommendations and trend rankings. Rules match source entities to target entities by field similarity, price range, or other numeric proximity. Conversion feedback flows back into the rule to improve rankings over time. The same graph you use for search becomes a live recommender with no extra data store.

// Create a recommendation rule matching cards by set and rarity
const rule = await client.knowledge.createAnalyticsRule(projectId, {
  rule_type: "recommendation",
  name:      "Similar cards",
  config:    { match_fields: ["set", "rarity"], limit: 5 },
  enabled:   true,
});

// Fetch pre-computed recommendations for a source node
const recs = await client.knowledge.getRecommendations(projectId, {
  rule_id:   rule.rule_id,
  source_id: sourceNodeId,
  limit:     5,
});
for (const rec of recs.recommendations) {
  console.log(rec.target_id, rec.score);
}

// Record conversion feedback — improves future rankings
await client.knowledge.recordFeedback(projectId, {
  rule_id:        rule.rule_id,
  source_node_id: sourceNodeId,
  target_node_id: recs.recommendations[0].target_id,
  converted:      true,
  score_at_time:  recs.recommendations[0].score,
});

Multiplayer memory: a company brain

Sonzai's knowledge layer is not a static store you hand-curate and agents read from once. It is a closed-loop system your agents read, write to, and learn from collaboratively — the way a real team builds shared institutional memory. Three capabilities stack on top of each other:

The result is the same compounding effect human teams get from institutional knowledge: an agent doesn't just remember what it did with one user — it picks up what the team did, and a new agent joining the project benefits from everything every previous agent already wrote down.

Project (your tenant)
                            |
 +--------------------------+--------------------------+
 |                          |                          |
 v                          v                          v
agent A                    agent B                    agent C
 |                          |                          |
 |--- writes verified ------+                          |
 |    incident detail       |                          |
 |                          |                          |
 |                  reads + grounds reply              |
 |                          |                          |
 |                          +--- updates the entry --->|
 |                                                     |
 |                                            reads enriched fact
 v                          v                          v
user X                     user Y                     user Z

 Inter-agent: closed loop. Anything one agent learns is
 instantly available to every other agent on the project.

 Intra-agent: a single agent can also share memory across
 the users it serves -- attributed (sharedMemory) or
 de-attributed (wisdom). Same agent, multiple users,
 shared context.

Real-world shapes this enables:

• Customer-success scribes. Agent A captures verified renewal context with user X; agent B picks it up on a follow-up call with the same account.
• Support that learns from itself. Each verified incident detail an agent records is grounded data for every other agent the next time the same product issue surfaces.
• Team coordinators. One agent serves the whole project team — "Alice owns the migration, Bob is on incident response" — and informs each teammate with the context it gathered with the others.
• Group / party planning. "Carol brings dessert, Dave does setup." Everyone joining the agent already knows who's doing what.
• Cross-product company brain. Organization-scope KB sits above projects: tenant-wide policies, lore, brand, and reference catalogs every project agent reads alongside its own.

The detailed mechanics of each layer are below.

Agents writing to the knowledge base

By default the KB is admin-curated: you push data in via document upload or the bulkUpdate API, and agents only read. You can opt agents into autonomous editing so they create, update, and soft-delete entries themselves during conversations — useful when the source of truth is the conversation (e.g. a customer-success agent capturing renewal context, or a support agent recording verified incident details).

Three tools the agent gets when this is on

Every write is stamped with source = "agent:<agent-id>" on each PropertySource, so the KB audit trail shows exactly which agent made which change. Schema validation, write quotas, and the project-tenant scope check all run server-side — capability-on agents can only touch their own project.

Two ways to turn it on

Per-agent — set knowledgeBaseWrite: true on the agent's capabilities. Most useful when only specific agents in a project should be allowed to edit (e.g. a "scribe" agent vs. a customer-facing one).

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:      true,  // required prerequisite — agent must be able to read first
  knowledgeBaseWrite: true,
});

Project default — flip the project's default_agent_kb_write toggle. Every agent in that project with knowledgeBase: true gets the write capability automatically. Available in the dashboard at /dashboard/knowledge (the toggle next to the project selector) and via the API:

await client.projects.update(projectId, {
  default_agent_kb_write: true,
});

The platform resolves both flags with OR semantics — the agent's own flag wins immediately when on; the project default applies only when the agent flag is off. So you can default-on the whole project and not need to touch each agent.

Wisdom & shared memory

Beyond static documents, agents that talk to many users develop patterns — recurring behaviours, common goals, stable preferences. Sonzai surfaces this cross-user generalization through two complementary tiers: wisdom (de-attributed, on by default) and shared memory (attributed, opt-in).

Wisdom (de-attributed, on by default)

When the wisdom capability is on — which it is for every new agent — the platform runs a daily promotion job that pulls patterns from per-user fact histories, k-anonymizes them, and rewrites the result through an LLM into de-attributed knowledge. No individual user is identifiable. Every agent benefits from "what tends to work / what tends to come up" without ever leaking who said what.

This is your free generalization layer. There's nothing for agents to call — wisdom shows up alongside facts in the agent's context automatically when the capability is on.

// Wisdom is on by default for every new agent. To opt out for a specific
// agent (e.g. a single-user companion product where cross-user generalization
// isn't appropriate), pass false at create time or via updateCapabilities:
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

Shared memory (attributed, opt-in)

Some businesses want the opposite of de-attribution — they want users working with the same agent to see who is doing what. A team-collaboration agent might surface "Alice owns the migration, Bob is on incident response." A party-coordinator agent might track "Carol brings dessert, Dave does setup." That's what the sharedMemory capability gates.

When this capability is on, the agent records person/entity-attributed facts (roles, expertise, business context, relationship edges) and exposes them to other users sharing the agent. Three things change:

1. Tools. The agent gets wisdom_create, wisdom_update, wisdom_delete, and relation edges, plus admin-side CSV import.
2. Context. Other users' attributed facts surface in the agent's per-turn context with attribution.
3. Privacy floor. Every write is validated against a privacy blocklist (compensation, health, politics) using a dedicated semantic validator before persistence — so the agent can't share something that shouldn't cross the user boundary even if a user asks it to.

Shared memory is OFF by default. Enable it explicitly when the agent serves a group, team, or party that benefits from cross-user visibility.

// Wisdom is the precondition (default ON for new agents — only pass it
// explicitly when overriding the default).
await client.agents.updateCapabilities("agent_abc", {
wisdom:       true,
sharedMemory: true,
});

You can also enable it at agent creation time:

const agent = await client.agents.create({
name:       "Team Coordinator",
project_id: "proj_abc",
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});

Tutorials

• Inventory tutorial — model per-user items as typed KB entities and read them back during conversations
• Medication Reminders — end-to-end flow combining Knowledge Base, Inventory, and Scheduled Reminders for a medication adherence product

Next steps

• Inventory — per-user structured items backed by the same knowledge graph
• Knowledge Analytics — recommendation rules, trend rankings, and conversion tracking built on your entity graph
• Organization Knowledge Base — project-level shared knowledge visible to all agents across a tenant

Memory is the persistence layer behind every agent relationship. Each conversation is analyzed to extract facts, events, and commitments — stored in a structured tree and recalled automatically before the next response. Memory also composes directly with Scheduled Reminders: when a reminder fires and the user replies, the reply is captured as a new memory fact. It feeds Agent Insights too — habits, goals, and interests are derived signals aggregated over memory facts.

What you can build with it

• Relationship-arc companions — agents that reference shared history ("the week you were stressed about finals") to deepen connection over months
• Context-aware work assistants — skip re-asking for role, preferences, and recent tickets by seeding from CRM data on first run
• Compliance-ready enterprise agents — every recalled fact carries source message IDs, making the agent's reasoning auditable at review time
• Adherence dashboards — query memory after reminder fires to build medication or habit compliance views without a separate database
• Shared-memories UX — render the timeline endpoint as a browsable "our story" view inside companion or wellness apps

Quickstart

Search a user's memory by semantic query, then list the top-level tree for context.

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

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

// Semantic search — scoped to a specific user
const results = await client.agents.memory.search("agent-id", {
query:   "hiking trip",
userId:  "user-123",   // optional: omit to search across all users for this agent
limit:   10,
});

for (const mem of results.results) {
console.log(mem.content, mem.factType, mem.score);
}

// Browse the tree
const tree = await client.agents.memory.list("agent-id", {
userId: "user-123",
limit: 20,
});

Core concepts

Memory tree structure

Memory is organized as a hierarchical tree of nodes, each with a NodeID, Title, Summary, and optional child nodes. Nodes act as thematic containers — "Jane's work life," "travel experiences" — and hold atomic facts beneath them. You can navigate the tree by passing parentID to list, or fetch a subtree with includeContents: true to pull a node's facts in one call.

Key MemoryNode fields: NodeID, AgentID, UserID, ParentID, Title, Summary, Importance, CreatedAt, UpdatedAt.

Facts vs summaries

Facts are atomic, source-anchored statements ("User is a senior product manager at Acme Corp"). Every fact traces back to a specific message in a real conversation — the agent cannot hallucinate memories. Summaries are auto-generated consolidations written at session end, giving long conversations a compact digest. Both live in the tree and both appear in search results.

Timeline queries

timeline returns a chronological view organized by session — each TimelineSession carries session_id, facts, first_fact_at, last_fact_at, and fact_count. Use it to render episodic history in your UI or to audit what was extracted from a specific time window.

Reset and scoping

reset deletes all memory for an agent–user pair and is irreversible. Use it for testing, privacy-right-to-erasure flows, or account handoffs. All write operations (seed, createFact, search) accept an instanceId to scope memory to a workspace or tenant, preventing cross-boundary leakage in multi-tenant deployments.

Sync vs async memory recall

Supplementary memory recall — the extra fact lookups that enrich each turn beyond the agent's automatic working set — runs synchronously by default: every fact lands in the current turn before generation starts. Switch to async when first-token latency matters more than completeness; recall races a deadline, and slow hits spill into the next turn.

memory_mode is an agent-wide capability. Set it once via update_capabilities(); every subsequent chat uses that mode until you change it. There is no equivalent at agent-creation time — create the agent first, then flip the mode.

// Read current capabilities
const caps = await client.agents.getCapabilities("agent-id");
console.log(caps.memoryMode); // "sync" or "async"

// Switch to async for lower first-token latency
await client.agents.updateCapabilities("agent-id", { memoryMode: "async" });

// Switch back to sync
await client.agents.updateCapabilities("agent-id", { memoryMode: "sync" });

When to pick async: high-volume voice agents, mobile clients on slow networks, or any setup where missing one or two enrichment facts is preferable to a 200ms latency spike. The agent's automatic working set still lands on every turn — only supplementary recall slips.

Pending capabilities

AgentCapabilities.pendingCapabilities is a list of capability changes that have been queued by the platform but not yet applied — for example, a tier upgrade that will unlock music or video generation. Each entry carries a capability name (string) and an optional context string with human-readable detail. Read it via get_capabilities() to surface upgrade status in your UI.

const caps = await client.agents.getCapabilities("agent-id");

for (const pending of caps.pendingCapabilities ?? []) {
console.log(pending.capability, pending.context);
// e.g. "musicGeneration"  "Scheduled for activation on plan upgrade"
}

Full API

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

Combines with other features

With Scheduled Reminders — responses populate memory

When a scheduled reminder fires and the user replies, the memory layer auto-captures the reply as a fact. Query those facts later to build a compliance view or adherence dashboard without an extra database.

// After a week of daily medication reminders, query the captured replies
const memories = await client.agents.memory.search("agent-id", {
  query: "medication taken ibuprofen",
  limit: 10,
});

for (const result of memories.results) {
  console.log(result.content, result.score);
  // "User confirmed taking 500mg ibuprofen at 08:14"  0.89
}

The full reminder-to-memory flow is shown in the Medication Reminders tutorial.

With Conversations — every turn writes memory

Memory is fully automatic during chat — you do not call any write endpoint yourself. The platform analyzes each conversation turn, extracts facts, events, and commitments, and stores them in the tree. The next time you call chat for that agent–user pair, the most relevant memories are assembled into context automatically.

// Just call chat — memory extraction and retrieval happen on every turn
const stream = client.agents.chat.stream("agent-id", {
  userId:   "user-123",
  messages: [{ role: "user", content: "I've been training for a half marathon." }],
});

// After the conversation, the fact "user is training for a half marathon"
// is stored automatically — no extra call needed.
const results = await client.agents.memory.search("agent-id", {
  query: "running training marathon",
  limit: 5,
});
console.log(results.results[0].content);
// "User is training for a half marathon"

With Agent Insights — memory is the raw material

Habits, goals, interests, and mood trends are derived signals the context engine aggregates over memory facts. Memory is what the engine reads; Agent Insights is what the engine produces. Search memory for raw facts, then call Agent Insights to see what those facts have been distilled into.

// 1. Fetch raw memory facts about fitness
const facts = await client.agents.memory.search("agent-id", {
  query: "exercise fitness running",
  limit: 10,
});

// 2. Fetch the derived habit signal the engine built from those facts
const habits = await client.agents.listHabits("agent-id", {
  userId: "user-123",
});

console.log(habits.habits);
// [{ label: "Daily runner", frequency: "daily", confidence: 0.91 }]

Tutorials

• Memory — end-to-end walkthrough — covers seed, search, timeline, manual facts, and reset.

Next steps

• Agent Insights — derived signals (habits, goals, interests) built on top of memory facts.
• Scheduled Reminders — proactive messages whose user replies flow back into memory.
• Conversations — every chat turn is the primary source of memory writes.

The default agent memory model is per-pair — every conversation builds a fact profile scoped to one (agent, user) pair. That isolation is the right default for privacy, but the moment your product has more than one agent or more than one user per agent, you want memory to cross the boundary in controlled, observable ways.

Multiplayer memory is the umbrella for those crossing capabilities. It splits cleanly along two axes:

Both axes can run simultaneously. The full picture: agents on the same project share the world they've learned about (inter-agent) and a single agent shares context about the people it serves (intra-agent). Same compounding curve, two dimensions.

INTER-AGENT (across agents)
            shared knowledge base, autonomous updates,
              org-wide scope, closed-loop company brain
                              |
                              v
 +-------------------------+      +-------------------------+
 |       Agent A           |      |       Agent B           |
 |  reads + writes KB      |<---->|  reads + writes KB      |
 +-------------------------+      +-------------------------+
          ^ ^ ^                                ^ ^ ^
          | | |  INTRA-AGENT (across users)    | | |
          | | |  wisdom (de-attributed),       | | |
          | | |  shared memory (attributed)    | | |
 +--------+ | +---------+              +-------+ | +---------+
 |          |           |              |         |           |
user X1   user X2     user X3        user Y1    user Y2    user Y3

 Inter-agent: anything any agent learns is grounded data
              for every other agent on the project.
 Intra-agent: a single agent carries memory across the
              users it serves -- with privacy guardrails.

Inter-agent memory — agent ↔ agent

Inter-agent memory turns the project knowledge base into a closed-loop company brain: anything one agent learns or verifies during a conversation becomes grounded data every other agent on the project retrieves on the next session. Three layers stack from baseline to organization-wide.

1. Baseline read — every agent grounds replies in the project KB

Any agent with knowledgeBase: true reads the project knowledge graph during conversations via the knowledge_search tool. The graph is hand-curated, ETL-loaded, or both — see How knowledge gets into the KB for the two ingestion paths.

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase: true,
});

2. Autonomous editing — agents write what they learn back

Flip knowledgeBaseWrite: true and the agent gets knowledge_create / knowledge_update / knowledge_delete tools. During conversations the agent records verified facts itself, with a full audit trail (source = "agent:<agent-id>") and compare-and-swap update semantics so admin edits don't get clobbered. The next agent that runs knowledge_search on the same topic retrieves what the previous agent wrote down.

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:      true,
  knowledgeBaseWrite: true,
});

Use this when the source of truth IS the conversation — support agents recording verified incident details, customer-success agents capturing renewal context, scribe agents writing meeting notes. Detail: Agents writing to the knowledge base.

3. Organization scope — tenant-wide knowledge above projects

Set knowledgeBaseScopeMode: "cascade" on an agent and it reads from both the project KB and the org-scope KB on every search. The org scope is for tenant-wide artefacts: policies, lore, brand, reference catalogs. Project wins on collisions; org fills in defaults.

await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:          true,
  knowledgeBaseScopeMode: "cascade",
});

Detail: Organization Knowledge Base.

Intra-agent memory — across users sharing one agent

Intra-agent memory turns a single agent into a team brain: one agent serving multiple users carries memory that crosses the user boundary, so it can inform user A with the context it gathered while talking to user B. Two complementary tiers.

1. Wisdom — default-on, de-attributed

wisdom is on for every new agent. A daily promotion job pulls patterns from per-user fact histories, k-anonymises them, and rewrites the result through an LLM into agent-wide knowledge. No individual user is identifiable. Every agent benefits from "what tends to work / what tends to come up" without ever leaking who said what.

// Wisdom is on by default. Pass false only to opt out
// (rare — usually only for strict single-user products).
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

This is the safe intra-agent layer — privacy-protected by construction, no opt-in required.

2. Shared memory — opt-in, attributed

sharedMemory: true is the powerful intra-agent layer. The agent records person/entity-attributed facts (roles, expertise, business context, relationships) and surfaces them to other users sharing the agent — with names visible. "Alice owns the migration; Bob is on incident response." "Carol brings dessert; Dave does setup."

await client.agents.updateCapabilities("agent_abc", {
  wisdom:       true,   // precondition; default on
  sharedMemory: true,
});

Three things flip when you turn it on: the agent gets sonzai_wisdom_set/update/delete/relate tools; the prompt grows a "Shared facts" section with a discretion clause; every write is server-side validated against a privacy floor (compensation, health, politics blocked). Every disclosure is logged to the audit table. Full detail: Shared Memory.

Combining inter-agent and intra-agent

The two axes are independent — every combination is valid:

// Full multiplayer memory in one capability update
await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:          true,
  knowledgeBaseWrite:     true,    // inter-agent: closed-loop KB
  knowledgeBaseScopeMode: "cascade", // inter-agent: org scope
  wisdom:                 true,    // intra-agent: de-attributed (default on)
  sharedMemory:           true,    // intra-agent: attributed
});

How to verify it's working

Each capability has a live read endpoint you can hit to confirm the loop closes. Replace $AGENT_ID, $PROJECT_ID, $API_KEY with your own.

Inter-agent — KB writes

# Search the project KB — does an agent write show up?
curl 'https://api.sonz.ai/api/v1/projects/$PROJECT_ID/knowledge/search?q=YourQuery' \
  -H "Authorization: Bearer $API_KEY"

Intra-agent — attributed shared memory

# List attributed facts on the agent
curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed?limit=20' \
  -H "Authorization: Bearer $API_KEY"

# Read the disclosure audit — every fact disclosed in a turn is logged
curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/audit?limit=50' \
  -H "Authorization: Bearer $API_KEY"

Intra-agent — wisdom (default-on)

The de-attributed wisdom layer surfaces inline in every prompt the agent runs once the daily promotion job has scanned per-user fact histories — no separate read endpoint. To verify it's running, watch agent context size over a 48-hour window after multi-user traffic; you should see the wisdom block populate.

Privacy and control

Multiplayer memory is sensitive by design. Each capability has its own controls — none of them require trusting the LLM:

Every cross-boundary flow has a corresponding read endpoint, so you can audit retrospectively at any time.

Where to dive deeper

• Knowledge Base — the inter-agent surface: ingestion paths, schemas, autonomous editing detail
• Organization Knowledge Base — the org-wide cascade detail
• Shared Memory — the intra-agent surface: enable/disable, four wisdom tools, privacy floor, full verification probes
• Self-Improvement — how multiplayer memory layers on top of per-pair online learning
• Wisdom API — full endpoint reference for shared memory CRUD + audit

Proactive messages — generated by recurring schedules, one-off wakeups, or tenant-triggered events — land in a per-user notifications queue the moment they fire. Your frontend or backend polls that queue to fetch pending messages, display them to the user, and mark each one consumed. No push infrastructure, no webhook endpoint, no server-side listener to maintain — just an HTTP GET on your schedule.

This is the recommended delivery pattern for web clients and mobile apps that can't accept inbound HTTP requests, and it doubles as a handy catch-up mechanism for users who were offline when messages were generated.

What you can build with it