# Sonzai Documentation — Enterprise AI Agents Bundle

> Auto-generated subset of the Sonzai docs optimised for LLM builders working on **Enterprise AI Agents**.
> Pages where `<AudienceTabs>` is used include only the enterprise tab.
> For the full docs, see https://sonz.ai/llms-full.txt.

Source: https://sonz.ai/docs/en

# Advance Time

Source: https://sonz.ai/docs/en/advance-time

> Simulate time passing for an agent — fire schedules, generate diaries, decay mood, and replay what would have happened without waiting real time.



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 [#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](#also-useful-for-evaluation) below)

## Quickstart [#quickstart]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const result = await client.workbench.advanceTime({
agentId: &#x22;agent_abc&#x22;,
userId:  &#x22;user_123&#x22;,
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: &#x22;...&#x22;, created_at: &#x22;...&#x22; }]`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

result = client.workbench.advance_time(
  agent_id=&#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  simulated_hours=24,
)

print(result.days_processed)   # 1
print(result.diary_entries)    # [DiaryEntry(content=&#x22;...&#x22;, created_at=&#x22;...&#x22;)]`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

result, err := client.Workbench.AdvanceTime(ctx, map[string]any{
  &#x22;agent_id&#x22;:        &#x22;agent_abc&#x22;,
  &#x22;user_id&#x22;:         &#x22;user_123&#x22;,
  &#x22;simulated_hours&#x22;: 24,
})
if err != nil {
  log.Fatal(err)
}

fmt.Println(result[&#x22;days_processed&#x22;])  // 1
fmt.Println(result[&#x22;diary_entries&#x22;])   // [{content: &#x22;...&#x22;, created_at: &#x22;...&#x22;}]`,
  },
]"
/>

## Core concepts [#core-concepts]

### What fires when time advances [#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 [#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 [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Kick off a long advance asynchronously
const job = await client.workbench.advanceTime({
agentId: &#x22;agent_abc&#x22;,
userId:  &#x22;user_123&#x22;,
simulatedHours: 168, // one week
runAsync: true,
}) as { job_id: string; status: string };

console.log(job.job_id, job.status); // &#x22;job_01HX...&#x22;, &#x22;running&#x22;

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

console.log(state.status); // &#x22;succeeded&#x22;
console.log(state.result); // full AdvanceTimeResponse`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import time

# Kick off a long advance asynchronously
job = client.workbench.advance_time(
  agent_id=&#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  simulated_hours=168,  # one week
  run_async=True,
)
print(job[&#x22;job_id&#x22;], job[&#x22;status&#x22;])  # &#x22;job_01HX...&#x22;, &#x22;running&#x22;

# Poll until done (30-minute TTL in Redis)
while True:
  state = client.workbench.get_advance_time_job(job[&#x22;job_id&#x22;])
  if state[&#x22;status&#x22;] != &#x22;running&#x22;:
      break
  time.sleep(2)

print(state[&#x22;status&#x22;])  # &#x22;succeeded&#x22;
print(state[&#x22;result&#x22;])  # full advance-time payload`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Kick off a long advance asynchronously
job, err := client.Workbench.AdvanceTime(ctx, map[string]any{
  &#x22;agent_id&#x22;:        &#x22;agent_abc&#x22;,
  &#x22;user_id&#x22;:         &#x22;user_123&#x22;,
  &#x22;simulated_hours&#x22;: 168, // one week
  &#x22;async&#x22;:           true,
})

jobID := job[&#x22;job_id&#x22;].(string)
fmt.Println(jobID, job[&#x22;status&#x22;]) // &#x22;job_01HX...&#x22;, &#x22;running&#x22;

// Poll until done (30-minute TTL in Redis)
for {
  state, _ := client.Workbench.GetAdvanceTimeJob(ctx, jobID)
  if state[&#x22;status&#x22;] != &#x22;running&#x22; {
      fmt.Println(state[&#x22;status&#x22;]) // &#x22;succeeded&#x22;
      break
  }
  time.Sleep(2 * time.Second)
}`,
  },
]"
/>

### Time granularity [#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 [#full-api]

| Method                     | Returns                                                    | Description                                                                                                           |
| -------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `advanceTime(options)`     | `AdvanceTimeResponse` — or `{ job_id, status }` when async | Advance simulated time. Key fields: `days_processed`, `diary_entries`, `wakeups_fired`, consolidation counters.       |
| `getAdvanceTimeJob(jobId)` | `{ job_id, status, result?, error? }`                      | Poll an async advance-time job. `status` is `"running"`, `"succeeded"`, or `"failed"`. Job state has a 30-minute TTL. |

**`advanceTime` options**

| Field                                                      | Type      | Required | Description                                                               |
| ---------------------------------------------------------- | --------- | -------- | ------------------------------------------------------------------------- |
| `agentId` / `agent_id`                                     | `string`  | Yes      | Agent UUID                                                                |
| `userId` / `user_id`                                       | `string`  | Yes      | User ID — must match the ID used during chat                              |
| `simulatedHours` / `simulated_hours`                       | `number`  | Yes      | Hours to advance                                                          |
| `simulatedBaseOffsetHours` / `simulated_base_offset_hours` | `number`  | No       | Hours already processed by prior calls in the same gap (default `0`)      |
| `runAsync` / `run_async` / `async`                         | `boolean` | No       | Return a job descriptor immediately instead of blocking (default `false`) |

## Combines with other features [#combines-with-other-features]

### With [Scheduled Reminders](./scheduled-reminders) — fast-forwarding pending reminders [#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.

```ts
// 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](./memory) — replay compressed history [#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](./proactive-overview) — time-travel scheduled wakeups [#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 [#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 Relationship Layer pages below for how it combines with other features.

## Next steps [#next-steps]

* [Scheduled Reminders](./scheduled-reminders) — schedules fire automatically during a time advance
* [Memory](./memory) — diary entries are generated for each simulated day in the window
* [Evaluation](./evaluation) — if you are using Advance Time for benchmarking, see the eval workflow

***

## Also useful for evaluation [#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](./evaluation) to measure agent behavior quality after arbitrary amounts of simulated elapsed time.


---

# Agent Insights

Source: https://sonz.ai/docs/en/agent-insights

> Fetch what the agent has learned about each user — habits, goals, interests, relationships, diary entries, and constellation clusters. Derived signals from the context engine.



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.

<Callout type="info" title="Automatic — no setup required">
  All insight signals are produced by the context engine during and after each conversation. You do not need to call any write endpoint to populate them — they fill in on their own. The read endpoints on this page let you surface what the agent has learned.
</Callout>

## What you can build with it [#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 [#quickstart]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const agentId = &#x22;agent_abc&#x22;;
const userId  = &#x22;user_123&#x22;;

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

console.log(&#x22;habits:&#x22;,    habits.habits.length);
console.log(&#x22;goals:&#x22;,     goals.goals.length);
console.log(&#x22;interests:&#x22;, interests.interests.length);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

agent_id = &#x22;agent_abc&#x22;
user_id  = &#x22;user_123&#x22;

habits    = client.agents.list_habits(agent_id, user_id=user_id)
goals     = client.agents.list_goals(agent_id, user_id=user_id)
interests = client.agents.get_interests(agent_id, user_id=user_id)

print(&#x22;habits:&#x22;,    len(habits.habits))
print(&#x22;goals:&#x22;,     len(goals.goals))
print(&#x22;interests:&#x22;, len(interests.interests))`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

agentID := &#x22;agent_abc&#x22;
userID  := &#x22;user_123&#x22;

habits, err    := client.Agents.ListHabits(ctx, agentID, userID, &#x22;&#x22;)
goals, err     := client.Agents.ListGoals(ctx, agentID, userID, &#x22;&#x22;)
interests, err := client.Agents.GetInterests(ctx, agentID, userID, &#x22;&#x22;)

fmt.Println(&#x22;habits:&#x22;,    len(habits.Habits))
fmt.Println(&#x22;goals:&#x22;,     len(goals.Goals))
fmt.Println(&#x22;interests:&#x22;, len(interests.Interests))`,
  },
]"
/>

## Core concepts [#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 [#full-api]

### Read endpoints [#read-endpoints]

| Method                                                 | Go                  | Returns                 | Description                                      |
| ------------------------------------------------------ | ------------------- | ----------------------- | ------------------------------------------------ |
| `listHabits(agentId, { userId?, instanceId? })`        | `ListHabits`        | `HabitsResponse`        | Extracted recurring behaviors                    |
| `listGoals(agentId, { userId?, instanceId? })`         | `ListGoals`         | `GoalsResponse`         | Active and achieved goals                        |
| `getInterests(agentId, { userId?, instanceId? })`      | `GetInterests`      | `InterestsResponse`     | Topics and themes the user cares about           |
| `getRelationships(agentId, { userId?, instanceId? })`  | `GetRelationships`  | `RelationshipsResponse` | People mentioned across conversations            |
| `getDiary(agentId, { userId?, instanceId? })`          | `GetDiary`          | `DiaryResponse`         | Agent-authored diary entries per session         |
| `getConstellation(agentId, { userId?, instanceId? })`  | `GetConstellation`  | `ConstellationResponse` | Memory clusters (nodes, edges, insights)         |
| `listBreakthroughs(agentId, { userId?, instanceId? })` | `ListBreakthroughs` | `BreakthroughsResponse` | Significant emotional or relationship milestones |

### Write endpoints (goals and habits) [#write-endpoints-goals-and-habits]

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

| Method                                   | Go            | Description                             |
| ---------------------------------------- | ------------- | --------------------------------------- |
| `createGoal(agentId, opts)`              | `CreateGoal`  | Seed a goal before or during a workflow |
| `updateGoal(agentId, goalId, opts)`      | `UpdateGoal`  | Change status, priority, or description |
| `deleteGoal(agentId, goalId, opts?)`     | `DeleteGoal`  | Soft-delete (abandon) a goal            |
| `createHabit(agentId, opts)`             | `CreateHabit` | Manually seed a habit                   |
| `updateHabit(agentId, habitName, opts)`  | `UpdateHabit` | Update strength or description          |
| `deleteHabit(agentId, habitName, opts?)` | `DeleteHabit` | Remove a habit                          |

## Habits [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const habits = await client.agents.listHabits(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
});

for (const h of habits.habits) {
console.log(h.name, h.category, h.strength, h.formed);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `habits = client.agents.list_habits(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

for h in habits.habits:
  print(h.name, h.category, h.strength, h.formed)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `habits, err := client.Agents.ListHabits(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

for _, h := range habits.Habits {
  fmt.Println(h.Name, h.Category, h.Strength, h.Formed)
}`,
  },
]"
/>

## Goals [#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`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Read
const goals = await client.agents.listGoals(&#x22;agent_abc&#x22;, { userId: &#x22;user_123&#x22; });
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(&#x22;agent_abc&#x22;, {
userId:      &#x22;user_123&#x22;,
title:       &#x22;Complete onboarding&#x22;,
description: &#x22;Finish all onboarding steps&#x22;,
type:        &#x22;task&#x22;,
priority:    1,
});

// Mark achieved after a business event
await client.agents.updateGoal(&#x22;agent_abc&#x22;, goal.goal_id, {
userId: &#x22;user_123&#x22;,
status: &#x22;achieved&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Read
goals = client.agents.list_goals(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)
for g in goals.goals:
  print(g.title, g.status, g.priority)

# Seed a goal for a new workflow
goal = client.agents.create_goal(
  &#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  title=&#x22;Complete onboarding&#x22;,
  description=&#x22;Finish all onboarding steps&#x22;,
  type=&#x22;task&#x22;,
  priority=1,
)

# Mark achieved after a business event
client.agents.update_goal(
  &#x22;agent_abc&#x22;, goal.goal_id,
  user_id=&#x22;user_123&#x22;,
  status=&#x22;achieved&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Read
goals, err := client.Agents.ListGoals(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)
for _, g := range goals.Goals {
  fmt.Println(g.Title, g.Status, g.Priority)
}

// Seed a goal for a new workflow
goal, err := client.Agents.CreateGoal(ctx, &#x22;agent_abc&#x22;,
  sonzai.CreateGoalOptions{
      UserID:      &#x22;user_123&#x22;,
      Title:       &#x22;Complete onboarding&#x22;,
      Description: &#x22;Finish all onboarding steps&#x22;,
      Type:        &#x22;task&#x22;,
      Priority:    1,
  },
)

// Mark achieved after a business event
_, err = client.Agents.UpdateGoal(ctx, &#x22;agent_abc&#x22;, goal.GoalID,
  sonzai.UpdateGoalOptions{
      UserID: &#x22;user_123&#x22;,
      Status: &#x22;achieved&#x22;,
  },
)`,
  },
]"
/>

## Interests [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const interests = await client.agents.getInterests(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
});

for (const i of interests.interests) {
console.log(i.topic, i.category);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `interests = client.agents.get_interests(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

for i in interests.interests:
  print(i.topic, i.category)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `interests, err := client.Agents.GetInterests(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

for _, i := range interests.Interests {
  fmt.Println(i.Topic, i.Category)
}`,
  },
]"
/>

## Relationships [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const rel = await client.agents.getRelationships(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
});

for (const r of rel.relationships) {
console.log(r.name, r.relationship_type, r.context);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `rel = client.agents.get_relationships(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

for r in rel.relationships:
  print(r.name, r.relationship_type, r.context)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `rel, err := client.Agents.GetRelationships(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

for _, r := range rel.Relationships {
  fmt.Println(r.Name, r.RelationshipType, r.Context)
}`,
  },
]"
/>

## Diary [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const diary = await client.agents.getDiary(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
});

for (const entry of diary.entries) {
console.log(entry.created_at, entry.content);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `diary = client.agents.get_diary(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

for entry in diary.entries:
  print(entry.created_at, entry.content)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `diary, err := client.Agents.GetDiary(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

for _, entry := range diary.Entries {
  fmt.Println(entry.CreatedAt, entry.Content)
}`,
  },
]"
/>

## Constellation [#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`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const c = await client.agents.getConstellation(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
});

for (const node of c.nodes) {
console.log(node.label, node.node_type, node.significance);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `c = client.agents.get_constellation(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

for node in c.nodes:
  print(node.label, node.node_type, node.significance)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `c, err := client.Agents.GetConstellation(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

for _, node := range c.Nodes {
  fmt.Println(node.Label, node.NodeType, node.Significance)
}`,
  },
]"
/>

## Breakthroughs [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const bt = await client.agents.listBreakthroughs(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
});

for (const b of bt.items) {
console.log(b.type, b.description, b.timestamp);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `bt = client.agents.list_breakthroughs(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

for b in bt.items:
  print(b.type, b.description, b.timestamp)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `bt, err := client.Agents.ListBreakthroughs(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

for _, b := range bt.Items {
  fmt.Println(b.Type, b.Description, b.Timestamp)
}`,
  },
]"
/>

## Combines with other features [#combines-with-other-features]

### With [Memory](./memory) — insights are summaries over raw facts [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const habits = await client.agents.listHabits(&#x22;agent_abc&#x22;, { userId: &#x22;user_123&#x22; });
const topHabit = habits.habits[0];

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

console.log(\`Found \${facts.results.length} facts supporting &#x22;\${topHabit.name}&#x22;\`);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `habits   = client.agents.list_habits(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)
top_habit = habits.habits[0]

# Find the raw memories that support this habit
facts = client.agents.memory.search(
  &#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  query=top_habit.name,
  limit=10,
)

print(f&#x22;Found {len(facts.results)} facts supporting '{top_habit.name}'&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `habits, _ := client.Agents.ListHabits(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)
topHabit  := habits.Habits[0]

// Find the raw memories that support this habit
facts, _ := client.Agents.Memory.Search(ctx, &#x22;agent_abc&#x22;,
  sonzai.MemorySearchOptions{
      UserID: &#x22;user_123&#x22;,
      Query:  topHabit.Name,
      Limit:  10,
  },
)

fmt.Printf(&#x22;Found %d facts supporting %q\n&#x22;, len(facts.Results), topHabit.Name)`,
  },
]"
/>

### With [Emotions](./emotions) — mood + insights for a full user picture [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const [mood, goals, diary] = await Promise.all([
client.agents.getMood(&#x22;agent_abc&#x22;, { userId: &#x22;user_123&#x22; }),
client.agents.listGoals(&#x22;agent_abc&#x22;, { userId: &#x22;user_123&#x22; }),
client.agents.getDiary(&#x22;agent_abc&#x22;, { userId: &#x22;user_123&#x22; }),
]);

console.log(&#x22;Current mood:&#x22;, mood.label);
console.log(&#x22;Active goals:&#x22;, goals.goals.filter(g => g.status === &#x22;active&#x22;).length);
console.log(&#x22;Diary entries:&#x22;, diary.entries.length);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `mood  = client.agents.get_mood(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)
goals = client.agents.list_goals(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)
diary = client.agents.get_diary(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;)

print(&#x22;Current mood:&#x22;, mood.label)
print(&#x22;Active goals:&#x22;, sum(1 for g in goals.goals if g.status == &#x22;active&#x22;))
print(&#x22;Diary entries:&#x22;, len(diary.entries))`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `mood,  _ := client.Agents.GetMood(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)
goals, _ := client.Agents.ListGoals(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)
diary, _ := client.Agents.GetDiary(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;&#x22;)

activeGoals := 0
for _, g := range goals.Goals {
  if g.Status == &#x22;active&#x22; {
      activeGoals++
  }
}

fmt.Println(&#x22;Current mood:&#x22;, mood.Label)
fmt.Println(&#x22;Active goals:&#x22;, activeGoals)
fmt.Println(&#x22;Diary entries:&#x22;, len(diary.Entries))`,
  },
]"
/>

### With [Advance Time](./advance-time) — replay insight formation [#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.

```typescript
// 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 [#tutorials]

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


---

# Architecture

Source: https://sonz.ai/docs/en/architecture

> How the Relationship Layer Platform fits into your application architecture.



**The Relationship Layer architecture** separates agent intelligence from your application logic: your backend keeps owning auth, business state, and user data, while Sonzai owns [personality](./personality), [memory](./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 [#system-overview]

The Relationship 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.

<Diagram>
  {`
    Your Backend                  Relationship 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)
          `}
</Diagram>

## Integration Architecture [#integration-architecture]

A typical deployment has three layers:

<Cards>
  <Card title="Your Frontend" description="User-facing application. Sends messages to your backend and renders agent responses. Examples: React, Next.js, Vue, mobile app." />

  <Card title="Your Backend" description="Handles auth, application state, user sessions, and business logic. Calls the Relationship Layer via SDK, REST API, MCP, or OpenClaw plugin for AI interactions. Examples: Express, Django, Go, OpenClaw." />

  <Card title="Sonzai Relationship Layer" description="Owns agent intelligence: personality, memory, mood, habits, goals, and relationships. A single chat call handles context assembly, AI streaming, and post-chat learning. Examples: api.sonz.ai." />
</Cards>

## What the Platform Manages [#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.

<Callout type="info" title="Context Assembly">
  Personality, mood, memories, relationship narrative, and application state — all assembled per request.
</Callout>

<Callout type="info" title="Memory Extraction">
  Facts, events, and commitments are extracted from each conversation and stored automatically.
</Callout>

<Callout type="info" title="Mood & Personality Evolution">
  Mood and Big5 personality drift naturally based on interaction patterns.
</Callout>

<Callout type="info" title="Proactive Notifications">
  Agents can schedule proactive outreach between sessions. Deliver via polling or webhook.
</Callout>

## Data Ownership [#data-ownership]

The Relationship Layer and your backend each own distinct data:

**Relationship 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 [#session-lifecycle]

<Diagram>
  {`
    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
          `}
</Diagram>

## Background Processing & Self-Improvement [#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.

| Cadence               | What runs                                                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Every turn**        | Importance + confidence updates, mood adjustments, personality micro-shifts, habit observations, association strengthening, source-anchoring checks                                                           |
| **Every session end** | Fact extraction with verification, duplicate consolidation, next-session prediction, retrieval policy updates, pattern learning, session quality scoring, topic-shift audit                                   |
| **Daily**             | Memory decay (importance, confidence, relationships, habits), memory tree self-organization and pruning, deep consolidation, cluster reconciliation, goal consolidation, reflective diary, convergence checks |
| **Weekly**            | Narrative arc compression, association decay, cross-reference detection, warm-start for new agent–user pairs, learning-pace check                                                                             |
| **Continuous**        | Adaptive retrieval budget, memory recovery, return prediction, background interest research, recurring event detection, smart memory selection                                                                |

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](/docs/en/self-improvement).

## SDK Integration Points [#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`


---

# Pattern 6: Hermes

Source: https://sonz.ai/docs/en/connect-hermes

> Drop the sonzai-hermes plugin pair into a Hermes Agent project. Sonzai becomes the agent's MemoryProvider and ContextEngine — persistent memory, mood, personality, and relationship state, under Hermes' existing tool and orchestration loop.



[Hermes Agent](https://hermes-agent.nousresearch.com) is the open-source
agent framework from Nous Research. It exposes two pluggable extension
points — `MemoryProvider` and `ContextEngine` — that together control
what an agent remembers and what survives a context-window compression.
The `sonzai-hermes` package ships both implementations as a paired drop-in:
install once, and every Hermes turn flows through the Relationship Layer.

## When to use this [#when-to-use-this]

* You're already running Hermes Agent (or your team has standardised
  on it).
* You want Hermes' existing chat loop, tool plugins, and orchestration
  to keep working — Sonzai only owns memory + context compression.
* You want Hermes' own loader to discover the plugins through its
  standard ABCs (no monkey-patching, no forks).

## When to switch [#when-to-switch]

* **Not on Hermes** — switch to
  [Pattern 1: Managed Runtime](/docs/en/connect-managed-runtime) (we run
  the chat), [Pattern 3: OpenClaw](/docs/en/connect-openclaw) (different
  framework), or [Pattern 4: Standalone Realtime](/docs/en/connect-standalone-realtime)
  (you run the chat with one of our SDKs).
* **No real-time chat at all** — switch to
  [Pattern 5: Standalone Batch](/docs/en/connect-standalone-batch).

## One-shot install [#one-shot-install]

```bash
pip install sonzai-hermes
sonzai-hermes install            # stages both plugins into Hermes' discovery paths
sonzai-hermes setup              # provisions a 14-day trial if no key, writes $HERMES_HOME/.env
```

`sonzai-hermes install` stages the **Memory Provider** into
`$HERMES_HOME/plugins/sonzai/` (Hermes' supported user path) and the
**Context Engine** into the Hermes install tree's `plugins/context_engine/sonzai/`
(Hermes' loader only scans the bundled tree for engines today). It's
idempotent and safe to re-run after `pip install --upgrade hermes-agent`.

Then in your Hermes profile (`~/.hermes/config.yaml`):

```yaml
memory:
  provider: sonzai
context:
  engine: sonzai
```

Restart Hermes and the agent has persistent memory and Sonzai-driven
context compression. Already have a Sonzai key? Set `SONZAI_API_KEY`
before `setup` and the trial flow is skipped.

## Architecture [#architecture]

<Diagram>
  {`
    Hermes Agent Runtime          sonzai-hermes plugins         Sonzai Relationship Layer
        |                                |                            |
        |-- start_session(user, agent) ->|  MemoryProvider            |
        |                                |-- resolve session -------->|
        |                                |<-- ranked memory ----------|
        |                                |                            |
        |-- on_turn(user_message) ----->|                            |
        |                                |-- recall + persist ------->|
        |                                |<-- structured memory ------|
        |                                |                            |
        |  [LLM call w/ memory context]  |                            |
        |                                |                            |
        |-- compact(ctx_window) -------->|  ContextEngine             |
        |                                |-- consolidation ---------->|
        |                                |<-- compressed window ------|
        |                                |   (not a naive summary)    |
        |                                |                            |
        |-- end_session(session_id) ---->|                            |
        |                                |-- extract facts, update    |
        |                                |   mood + personality ----->|
    `}
</Diagram>

## BYOK — bring your own LLM provider keys [#byok--bring-your-own-llm-provider-keys]

If `OPENAI_API_KEY`, `GEMINI_API_KEY` (or `GOOGLE_API_KEY`), `XAI_API_KEY`,
or `OPENROUTER_API_KEY` are set in your environment, both plugins
automatically register them with the Sonzai platform on first startup.

Sonzai then routes LLM calls through **your** provider account, charging
only the 25% service fee instead of the \~125% platform-key markup. The
registration is idempotent; subsequent startups are no-ops if nothing changed.

Override per provider with `SONZAI_BYOK_<PROVIDER>_KEY` (takes precedence
over the standard env var name). Set `SONZAI_PROJECT_ID` if your tenant
has multiple projects and none is named `Default`.

## CLI reference [#cli-reference]

| Command                                                 | What it does                                                                                 |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `sonzai-hermes install`                                 | Stages both plugins into Hermes' discovery paths.                                            |
| `sonzai-hermes install --memory-only` / `--engine-only` | Install one without the other.                                                               |
| `sonzai-hermes install --symlink`                       | Symlink instead of copy — best for dev / editable installs.                                  |
| `sonzai-hermes setup`                                   | If no `SONZAI_API_KEY`: provisions a 14-day trial and writes the key to `$HERMES_HOME/.env`. |
| `sonzai-hermes status`                                  | Show what's currently staged.                                                                |
| `sonzai-hermes claim`                                   | Convert a trial into a permanent account (prints + opens claim URL).                         |
| `sonzai-hermes uninstall`                               | Reverse both installs.                                                                       |

Flags `--hermes-home` and `--hermes-src` override the auto-detected
locations when Hermes lives somewhere non-standard.

<Callout type="info" title="Why two plugins, one install?">
  Hermes treats memory and context-window compression as separate
  extension points (`MemoryProvider` ABC + `ContextEngine` ABC). We ship
  both so the relationship loop stays whole: turn-level recall plus
  consolidation-based compression, both talking to the same Sonzai
  session. Use `--memory-only` or `--engine-only` if you want just one.
</Callout>

## Where to next [#where-to-next]

<Cards>
  <Card href="/docs/en/memory" title="Memory & Context" description="What the MemoryProvider actually returns — fact recall, mood, personality, relationships." />

  <Card href="/docs/en/connect-openclaw" title="Pattern 3: OpenClaw" description="The sibling integration for OpenClaw projects." />

  <Card href="/docs/en/connect-managed-runtime" title="Pattern 1: Managed Runtime" description="If you'd rather skip Hermes entirely and let Sonzai own the chat loop." />
</Cards>


---

# Pattern 1: Managed Agent Runtime

Source: https://sonz.ai/docs/en/connect-managed-runtime

> The highest-level path. You hand Sonzai a user message, Sonzai returns a streamed reply, and memory, mood, personality, and tool execution all happen on our side.



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. &#x2A;*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 [#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 [#when-to-switch]

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

## Architecture [#architecture]

<Diagram>
  {`
    ┌─────────────┐     ┌───────────────────────────────────┐
    │  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
    `}
</Diagram>

## End-to-end snippet [#end-to-end-snippet]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID  = &#x22;agent-uuid&#x22;;
const USER_ID   = &#x22;user-123&#x22;;
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: &#x22;user&#x22;, content: &#x22;Hi! How's your day going?&#x22; }],
language:  &#x22;en&#x22;,
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}

// 3. End the session — triggers fact extraction + consolidation.
await sonzai.agents.sessions.end(AGENT_ID, {
userId:        USER_ID,
sessionId:     SESSION_ID,
totalMessages: 2,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, uuid
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID   = &#x22;agent-uuid&#x22;
USER_ID    = &#x22;user-123&#x22;
SESSION_ID = str(uuid.uuid4())

# 1. Start an explicit session (optional — chat auto-creates one if omitted).
sonzai.agents.sessions.start(
  AGENT_ID,
  user_id=USER_ID,
  session_id=SESSION_ID,
)

# 2. Drive turns. Sonzai handles context, LLM, tools, and writeback.
for event in sonzai.agents.chat(
  agent_id=AGENT_ID,
  session_id=SESSION_ID,
  user_id=USER_ID,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Hi! How's your day going?&#x22;}],
  language=&#x22;en&#x22;,
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)

# 3. End the session — triggers fact extraction + consolidation.
sonzai.agents.sessions.end(
  AGENT_ID,
  user_id=USER_ID,
  session_id=SESSION_ID,
  total_messages=2,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  &#x22;github.com/google/uuid&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  ctx := context.Background()
  client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  if err != nil { panic(err) }

  agentID   := &#x22;agent-uuid&#x22;
  userID    := &#x22;user-123&#x22;
  sessionID := uuid.NewString()

  // 1. Start an explicit session (optional — chat auto-creates one if omitted).
  if _, err := client.Agents.Sessions.Start(ctx, agentID, sonzai.SessionStartOptions{
      UserID:    userID,
      SessionID: sessionID,
  }); err != nil { panic(err) }

  // 2. Drive turns. Sonzai handles context, LLM, tools, and writeback.
  err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
      AgentID: agentID,
      ChatOptions: sonzai.ChatOptions{
          SessionID: sessionID,
          UserID:    userID,
          Messages:  []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Hi! How's your day going?&#x22;}},
          Language:  &#x22;en&#x22;,
      },
  }, func(event sonzai.ChatStreamEvent) error {
      fmt.Print(event.Content())
      return nil
  })
  if err != nil { panic(err) }

  // 3. End the session — triggers fact extraction + consolidation.
  if _, err := client.Agents.Sessions.End(ctx, agentID, sonzai.SessionEndOptions{
      UserID:        userID,
      SessionID:     sessionID,
      TotalMessages: 2,
  }); err != nil { panic(err) }
}`,
  },
]"
/>

<Callout type="info" title="Skip the explicit session">
  If you don't call `sessions.start`, Sonzai opens one on the first
  `agents.chat` call and closes it on idle. The session ID still flows
  through to extracted facts. Use the explicit lifecycle when you need
  session-scoped tools, predictable boundaries, or replay semantics.
</Callout>

## Where to next [#where-to-next]

<Cards>
  <Card href="/docs/en/conversations" title="Conversations (deep reference)" description="Streaming, non-streaming, tool capabilities, language and timezone, instances." />

  <Card href="/docs/en/sessions" title="Sessions" description="When to start one explicitly, what end() consolidates, how IDs flow into facts." />

  <Card href="/docs/en/guides/integration" title="Integration Guide" description="Full SDK reference: agent lifecycle, webhooks, frontend proxy pattern, knowledge base, priming." />

  <Card href="/docs/en/custom-tools" title="Custom Tools" description="Register tools the LLM can call during chat — built-in capabilities, agent tools, and session-scoped tools." />
</Cards>


---

# Pattern 2: MCP

Source: https://sonz.ai/docs/en/connect-mcp

> Connect Claude Code, Cursor, Claude Desktop, ChatGPT, or any MCP-compatible client directly to the Relationship Layer. Your assistant sees Sonzai as a set of tools and resources it can call by name.



The Relationship 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 [#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 [#when-to-switch]

* **Building your own product UI** — switch to
  [Pattern 1: Managed Runtime](/docs/en/connect-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](/docs/en/connect-standalone-realtime).

## Architecture [#architecture]

<Diagram>
  {`
    ┌────────────────────────┐                   ┌──────────────────────┐
    │  Claude Code · Cursor  │                   │   Sonzai Relationship 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
    `}
</Diagram>

## End-to-end snippet [#end-to-end-snippet]

You need a project API key from your
[dashboard](https://platform.sonz.ai/dashboard/projects) and an
agent ID. Pick your client below — pasting the snippet is the entire
setup.

<CodeTabs
  tabs="[
  {
    id: &#x22;claude-code&#x22;,
    label: &#x22;Claude Code&#x22;,
    code: `# 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 &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22;

# Then from any Claude Code session you can say:
#   &#x22;Chat with agent 'Luna' and say 'I had a great day hiking today!'&#x22;
#   &#x22;Search Luna's memories about hiking adventures&#x22;
#   &#x22;Use mind-layer-setup with assistant_name 'Aria' …&#x22;`,
  },
  {
    id: &#x22;cursor&#x22;,
    label: &#x22;Cursor&#x22;,
    code: `// ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
&#x22;mcpServers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;type&#x22;: &#x22;http&#x22;,
    &#x22;url&#x22;: &#x22;https://api.sonz.ai/mcp/memory/AGENT_ID&#x22;,
    &#x22;headers&#x22;: {
      &#x22;Authorization&#x22;: &#x22;Bearer YOUR_SONZAI_API_KEY&#x22;
    }
  }
}
}

// Restart Cursor — Sonzai tools appear in @-mentions and the MCP picker.`,
  },
  {
    id: &#x22;chatgpt&#x22;,
    label: &#x22;ChatGPT&#x22;,
    code: `# ChatGPT supports MCP only over remote HTTP. Available on Plus, Pro,
# Business, Enterprise, Edu (Developer Mode beta).
#
# 1. Settings → Connectors → Advanced → Developer Mode ON
# 2. Add custom connector:
#      URL:    https://api.sonz.ai/mcp/memory/AGENT_ID
#      Header: Authorization: Bearer YOUR_SONZAI_API_KEY
# 3. Save and select the connector in any chat.`,
  },
  {
    id: &#x22;claude-desktop&#x22;,
    label: &#x22;Claude Desktop&#x22;,
    code: `# Claude Desktop's JSON config supports stdio servers only — for the
# remote endpoint use the in-app Connectors UI:
#
#   Settings → Connectors → Add custom connector
#     URL:    https://api.sonz.ai/mcp/memory/AGENT_ID
#     Auth:   Authorization: Bearer YOUR_SONZAI_API_KEY
#
# Restart the app. Sonzai tools appear in the connector picker.`,
  },
  {
    id: &#x22;vscode&#x22;,
    label: &#x22;VS Code&#x22;,
    code: `// .vscode/mcp.json — top key is &#x22;servers&#x22;, not &#x22;mcpServers&#x22;:
{
&#x22;servers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;type&#x22;: &#x22;http&#x22;,
    &#x22;url&#x22;: &#x22;https://api.sonz.ai/mcp/memory/AGENT_ID&#x22;,
    &#x22;headers&#x22;: {
      &#x22;Authorization&#x22;: &#x22;Bearer YOUR_SONZAI_API_KEY&#x22;
    }
  }
}
}

// Or: Cmd/Ctrl+Shift+P → &#x22;MCP: Add Server&#x22; → HTTP, then paste the URL.`,
  },
]"
/>

<Callout type="info" title="Streamable HTTP, not SSE">
  The 2026 MCP spec marks Streamable HTTP as the canonical remote
  transport. SSE is on a deprecation path across major clients — prefer
  HTTP for any new integration.
</Callout>

<Callout type="warn" title="Treat the API key like a password">
  The Bearer token is your project API key — it grants full access to
  every agent in the project. Don't commit it to public repos; use
  per-developer scopes when collaborating.
</Callout>

## Where to next [#where-to-next]

<Cards>
  <Card href="/docs/en/guides/mcp-integration" title="MCP Integration (full reference)" description="Complete tool catalogue (34 tools across Agent Management, Chat, Memory, Behavior, Sessions, and Generation), resources, guided prompts, OAuth flow, and the optional local-binary fallback." />

  <Card href="/docs/en/connect-managed-runtime" title="Pattern 1: Managed Runtime" description="If you'd rather drive Sonzai from code than from a chat client." />

  <Card href="/docs/en/reference" title="API Reference" description="Every REST endpoint the MCP tools wrap, with request and response schemas." />
</Cards>


---

# Pattern 3: OpenClaw

Source: https://sonz.ai/docs/en/connect-openclaw

> Drop the @sonzai-labs/openclaw-context plugin into an OpenClaw project and Sonzai becomes the agent's contextEngine — persistent memory, mood, personality, relationships, all under OpenClaw's existing chat loop.



[OpenClaw](https://openclaw.ai) 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 Relationship Layer with zero additional
code.

## One-shot install [#one-shot-install]

```bash
npx --yes @sonzai-labs/openclaw-context install
```

This single command probes backend health, runs
`openclaw plugins install`, launches the interactive setup wizard, and
writes your `openclaw.json` — end to end. With no existing Sonzai key, it
provisions a 14-day trial automatically (no sign-up, no browser); claim it
into a permanent account any time with
`npx @sonzai-labs/openclaw-context claim`.

Restart OpenClaw and the agent now has persistent memory, mood,
personality, and relationship state out of the box.

## When to use this [#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 [#when-to-switch]

* **Not on OpenClaw** — switch to
  [Pattern 1: Managed Runtime](/docs/en/connect-managed-runtime) (we run
  the chat) or
  [Pattern 4: Standalone Realtime](/docs/en/connect-standalone-realtime)
  (you run the chat).
* **No real-time chat at all** — switch to
  [Pattern 5: Standalone Batch](/docs/en/connect-standalone-batch).

## Architecture [#architecture]

<Diagram>
  {`
    OpenClaw Runtime              SonzaiContextEngine            Sonzai Relationship 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 -------->|
        |                                |   Relationship Layer extracts      |
        |                                |   facts, updates mood,     |
        |                                |   evolves personality      |
        |                                |                            |
        |-- compact(sessionId) --------->|                            |
        |                                |-- merge short → long term->|
    `}
</Diagram>

## End-to-end snippet [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 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:
//    {
//      &#x22;plugins&#x22;: {
//        &#x22;slots&#x22;: { &#x22;contextEngine&#x22;: &#x22;sonzai&#x22; },
//        &#x22;entries&#x22;: {
//          &#x22;sonzai&#x22;: {
//            &#x22;enabled&#x22;: true,
//            &#x22;apiKey&#x22;: &#x22;sk_your_api_key&#x22;,
//            &#x22;agentId&#x22;: &#x22;a1b2c3d4-...&#x22;
//          }
//        }
//      }
//    }
//
// 4. Start chatting — Sonzai is now the contextEngine:
//    openclaw chat
//
// For programmatic / B2B provisioning use the exported setup() helper:
import { setup } from &#x22;@sonzai-labs/openclaw-context&#x22;;

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

console.log(result.agentId);  // deterministic UUID — safe to re-run
console.log(result.written);  // true — config file updated`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# OpenClaw's plugin is JS-only. Python drives the same provisioning
# by calling the Sonzai REST API directly. agentId is derived
# deterministically from SHA1(tenantID + agentName) so re-running this
# script for the same tenant is idempotent.
import hashlib, json, os, uuid
from sonzai import Sonzai

def derive_agent_id(tenant_id: str, agent_name: str) -> str:
  digest = hashlib.sha1(f&#x22;{tenant_id}:{agent_name}&#x22;.encode()).digest()
  return str(uuid.UUID(bytes=digest[:16]))

def provision(tenant_id: str, agent_name: str, config_path: str) -> str:
  sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
  agent_id = derive_agent_id(tenant_id, agent_name)
  sonzai.agents.create(name=agent_name, agent_id=agent_id)
  with open(config_path, &#x22;w&#x22;) as f:
      json.dump(
          {
              &#x22;plugins&#x22;: {
                  &#x22;slots&#x22;: {&#x22;contextEngine&#x22;: &#x22;sonzai&#x22;},
                  &#x22;entries&#x22;: {
                      &#x22;sonzai&#x22;: {
                          &#x22;enabled&#x22;: True,
                          &#x22;apiKey&#x22;: os.environ[&#x22;SONZAI_API_KEY&#x22;],
                          &#x22;agentId&#x22;: agent_id,
                      }
                  },
              }
          },
          f,
          indent=2,
      )
  return agent_id

agent_id = provision(&#x22;tenant-xyz&#x22;, &#x22;customer-support-bot&#x22;, &#x22;/path/to/openclaw.json&#x22;)
print(agent_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// OpenClaw's plugin is JS-only. Go drives the same provisioning by
// calling the Sonzai REST API directly. AgentID is derived
// deterministically from SHA1(tenantID + agentName), so re-running this
// program for the same tenant is idempotent.
package main

import (
  &#x22;context&#x22;
  &#x22;crypto/sha1&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  &#x22;github.com/google/uuid&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func deriveAgentID(tenantID, agentName string) string {
  h := sha1.Sum([]byte(tenantID + &#x22;:&#x22; + agentName))
  var u [16]byte
  copy(u[:], h[:16])
  return uuid.UUID(u).String()
}

func provision(ctx context.Context, client *sonzai.Client, tenantID, agentName, configPath string) (string, error) {
  agentID := deriveAgentID(tenantID, agentName)
  if _, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
      AgentID: agentID,
      Name:    agentName,
  }); err != nil {
      return &#x22;&#x22;, err
  }
  cfg := map[string]any{
      &#x22;plugins&#x22;: map[string]any{
          &#x22;slots&#x22;: map[string]string{&#x22;contextEngine&#x22;: &#x22;sonzai&#x22;},
          &#x22;entries&#x22;: map[string]any{
              &#x22;sonzai&#x22;: map[string]any{
                  &#x22;enabled&#x22;: true,
                  &#x22;apiKey&#x22;:  os.Getenv(&#x22;SONZAI_API_KEY&#x22;),
                  &#x22;agentId&#x22;: agentID,
              },
          },
      },
  }
  f, err := os.Create(configPath)
  if err != nil { return &#x22;&#x22;, err }
  defer f.Close()
  if err := json.NewEncoder(f).Encode(cfg); err != nil {
      return &#x22;&#x22;, err
  }
  return agentID, nil
}

func main() {
  client, _ := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  id, err := provision(context.Background(), client, &#x22;tenant-xyz&#x22;,
      &#x22;customer-support-bot&#x22;, &#x22;/path/to/openclaw.json&#x22;)
  if err != nil { panic(err) }
  fmt.Println(id)
}`,
  },
]"
/>

<Callout type="info" title="Idempotent provisioning">
  Agent IDs are derived from `SHA1(tenantID + agentName)`. Calling
  `setup()` (or the Python/Go equivalent) multiple times for the same
  tenant + name returns the same agent — safe to re-run on every
  deploy.
</Callout>

## Where to next [#where-to-next]

<Cards>
  <Card href="/docs/en/guides/openclaw-integration" title="OpenClaw Integration (full reference)" description="Lifecycle hooks, configuration schema, session-key resolution, token-budget trimming, the SonzaiContextEngine class for advanced usage." />

  <Card href="/docs/en/memory" title="Memory & Context" description="What the contextEngine actually injects — fact recall, mood, personality, relationships." />

  <Card href="/docs/en/connect-managed-runtime" title="Pattern 1: Managed Runtime" description="If you'd rather skip OpenClaw entirely and let Sonzai own the chat loop." />
</Cards>


---

# Pattern 5: Standalone Memory (Batch)

Source: https://sonz.ai/docs/en/connect-standalone-batch

> One call after the conversation is done. Ship the full transcript to /process (or sessions.end with messages) and let Sonzai extract facts, mood, personality, and habits in the background.



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 [#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 [#when-to-switch]

* **You want fresh per-turn context** —
  [Pattern 4: Standalone Realtime](/docs/en/connect-standalone-realtime).
* **You're happy ceding the LLM call too** —
  [Pattern 1: Managed Runtime](/docs/en/connect-managed-runtime).

## Architecture [#architecture]

<Diagram>
  {`
    ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
    │  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, …)     │                       │
         └─────────────────────┴───────────────────────┘
    `}
</Diagram>

## End-to-end snippet [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function ingestTranscript(
agentId: string,
userId: string,
transcript: { role: &#x22;user&#x22; | &#x22;assistant&#x22; | &#x22;tool&#x22;; 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: &#x22;gemini&#x22;,                          // optional override
  model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,   // 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 };
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def ingest_transcript(agent_id: str, user_id: str, transcript: list[dict]) -> dict:
  # One call. Auto-creates a session. Tool messages allowed.
  result = sonzai.agents.process(
      agent_id,
      user_id=user_id,
      messages=transcript,
      provider=&#x22;gemini&#x22;,                       # optional override
      model=&#x22;gemini-3.1-flash-lite-preview&#x22;,   # optional override
  )

  # result.session_id is the auto-created session id.
  # Pull extractions from the read endpoints when ready:
  memory = sonzai.agents.memory.list(agent_id, user_id=user_id)
  mood   = sonzai.agents.get_mood(agent_id, user_id=user_id)

  return {&#x22;session_id&#x22;: result.session_id, &#x22;memory&#x22;: memory, &#x22;mood&#x22;: mood}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func ingestTranscript(ctx context.Context, agentID, userID string, transcript []sonzai.ChatMessage) error {
  client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  if err != nil { return err }

  // One call. Auto-creates a session. Tool messages allowed.
  result, err := client.Agents.Process(ctx, agentID, sonzai.ProcessOptions{
      UserID:   userID,
      Messages: transcript,
      Provider: &#x22;gemini&#x22;,
      Model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
  })
  if err != nil { return err }

  // Pull extractions from the read endpoints when ready:
  if _, err := client.Agents.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{UserID: userID}); err != nil {
      return err
  }
  if _, err := client.Agents.GetMood(ctx, agentID, userID, &#x22;&#x22;); err != nil {
      return err
  }

  _ = result.SessionID
  return nil
}`,
  },
]"
/>

<Callout type="warn" title="Pick one trigger, not both">
  `/process` and `sessions.end({ messages })` are functionally equivalent
  for batch ingest — both extract facts and side effects from the full
  transcript inline. **Don't do both** for the same transcript or
  extraction runs twice. Use `/process` for the simple one-call shape.
  Use `sessions.start` + `sessions.end({ messages })` when you want
  explicit lifecycle, async polling, or session-scoped tools.
</Callout>

<Callout type="info" title="What runs when">
  `/process` and `sessions.end` are intentionally lightweight: extract
  facts and a session summary inline (one LLM call per chunk). The
  expensive cross-session work (dedup, clustering, diary, decay) is
  scheduled automatically by the platform — you don't pay for it on
  every call.
</Callout>

## Where to next [#where-to-next]

<Cards>
  <Card href="/docs/en/guides/standalone-memory/pattern-2-batch" title="Pattern 2: Post-Session Batch (deep guide)" description="Use cases — tutoring, fitness, CRM intelligence, language learning, journaling — with full code for both /process and the explicit lifecycle." />

  <Card href="/docs/en/guides/standalone-memory/endpoints" title="Endpoint Walkthrough" description="Full reference for /process, sessions.end, and the read endpoints (memory, mood, personality, goals, habits, notifications)." />

  <Card href="/docs/en/connect-standalone-realtime" title="Pattern 4: Standalone Realtime" description="Same memory model, but Sonzai is in the hot path on every turn instead of only at the end." />
</Cards>


---

# Pattern 4: Standalone Memory (Real-Time)

Source: https://sonz.ai/docs/en/connect-standalone-realtime

> You own the LLM and the chat loop. Sonzai owns memory, mood, personality, and relationships. Per-turn — sessions.start → loop of session.context() + your LLM + session.turn() → sessions.end.



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. &#x2A;*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 [#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 [#when-to-switch]

* **One conversation can't end fast enough to wait for `.turn()` per
  exchange** — switch to
  [Pattern 5: Standalone Batch](/docs/en/connect-standalone-batch).
* **Sonzai owning the LLM call is fine** — switch to
  [Pattern 1: Managed Runtime](/docs/en/connect-managed-runtime) and
  delete most of this code.

## Architecture [#architecture]

<Diagram>
  {`
    ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
    │  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    │
         └─────────────────────┴───────────────────────┘
    `}
</Diagram>

## End-to-end snippet [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `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=&#x22;https://generativelanguage.googleapis.com/v1beta/openai/&#x22;,
  api_key=os.environ[&#x22;GEMINI_API_KEY&#x22;],
)
model = OpenAIChatCompletionsModel(model=&#x22;gemini-3.1-flash-lite-preview&#x22;, openai_client=gemini)

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

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

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

  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=&#x22;Companion&#x22;,
          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 = &#x22;\\n&#x22;.join(f&#x22;- {f.get('atomic_text', '')}&#x22; for f in (ctx.get(&#x22;loaded_facts&#x22;) or []))
  parts = [
      ctx.get(&#x22;personality_prompt&#x22;, &#x22;You are a helpful AI companion.&#x22;),
      f&#x22;Personality (Big5): {ctx.get('big5', {})}&#x22;,
      f&#x22;Current mood: {ctx.get('current_mood', {})}&#x22;,
  ]
  if facts:
      parts.append(f&#x22;Relevant memories:\\n{facts}&#x22;)
  return &#x22;\\n\\n&#x22;.join(parts)`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function runConversation(agentId: string, userId: string) {
// Session handle bundles agentId/userId/sessionId + provider/model
// defaults so you don't repeat them on every call.
const session = await sonzai.agents.sessions.start(agentId, {
  userId,
  sessionId: \`session-\${Date.now()}\`,
  provider: &#x22;gemini&#x22;,
  model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
});

async function turn(userMessage: string): Promise<string> {
  // 1. Fresh, query-relevant context BEFORE the LLM call.
  const ctx = await session.context({ query: userMessage });

  // 2. Your harness runs the LLM + your tools — Sonzai is OUT of the loop.
  //    Use the framework you already have (Vercel AI SDK, OpenAI Agents,
  //    LangChain, LiveKit). It owns history, tool dispatch, and any
  //    multimodal content blocks the model can see.
  const { reply, intermediateMessages } = await yourHarness.run({
    system:   buildSystemPrompt(ctx),
    message:  userMessage,
    tools:    yourTools,
  });
  sendToUser(reply);

  // 3. Forward the full exchange — including assistant tool_calls and
  //    role:&#x22;tool&#x22; results — so Sonzai's extractor can pick up facts
  //    that only surfaced inside a tool output.
  await session.turn({
    messages: [
      { role: &#x22;user&#x22;,      content: userMessage },
      ...intermediateMessages,                       // assistant tool_calls + tool results
      { role: &#x22;assistant&#x22;, content: reply },
    ],
  });
  return reply;
}

return { turn, end: () => session.end() };
}

// /context returns a flat object — read what you need, drop the rest.
function buildSystemPrompt(ctx: any): string {
const facts = (ctx.loaded_facts ?? []).map((f: any) => \`- \${f.atomic_text}\`).join(&#x22;\\n&#x22;);
return [
  ctx.personality_prompt ?? &#x22;You are a helpful AI companion.&#x22;,
  \`Personality (Big5): \${JSON.stringify(ctx.big5 ?? {})}\`,
  \`Current mood: \${JSON.stringify(ctx.current_mood ?? {})}\`,
  facts ? \`Relevant memories:\\n\${facts}\` : &#x22;&#x22;,
].filter(Boolean).join(&#x22;\\n\\n&#x22;);
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;
  &#x22;time&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func runConversation(ctx context.Context, agentID, userID string) error {
  client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  if err != nil { return err }

  session, err := client.Agents.Sessions.Start(ctx, agentID, sonzai.SessionStartOptions{
      UserID:    userID,
      SessionID: fmt.Sprintf(&#x22;session-%d&#x22;, time.Now().UnixMilli()),
      Provider:  &#x22;gemini&#x22;,
      Model:     &#x22;gemini-3.1-flash-lite-preview&#x22;,
  })
  if err != nil { return err }
  defer session.End(ctx)

  runTurn := func(userMessage string) (string, error) {
      // 1. Fresh, query-relevant context BEFORE the LLM call.
      ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: userMessage})
      if err != nil { return &#x22;&#x22;, err }

      // 2. Your harness runs the LLM + your tools. Sonzai is OUT of the loop.
      reply, intermediate, err := yourHarness.Run(ctx, buildSystemPrompt(ctxData), userMessage, yourTools)
      if err != nil { return &#x22;&#x22;, err }
      sendToUser(reply)

      // 3. Forward the full exchange — assistant tool_calls + tool results included.
      msgs := []sonzai.TurnMessage{{Role: &#x22;user&#x22;, Content: userMessage}}
      msgs = append(msgs, intermediate...)
      msgs = append(msgs, sonzai.TurnMessage{Role: &#x22;assistant&#x22;, Content: reply})

      if _, err := session.Turn(ctx, sonzai.TurnOptions{Messages: msgs}); err != nil {
          return &#x22;&#x22;, err
      }
      return reply, nil
  }

  _ = runTurn
  return nil
}

func buildSystemPrompt(ctx map[string]any) string {
  var parts []string
  if p, _ := ctx[&#x22;personality_prompt&#x22;].(string); p != &#x22;&#x22; {
      parts = append(parts, p)
  }
  if facts, ok := ctx[&#x22;loaded_facts&#x22;].([]any); ok {
      var lines []string
      for _, f := range facts {
          if fm, ok := f.(map[string]any); ok {
              lines = append(lines, &#x22;- &#x22;+fmt.Sprint(fm[&#x22;atomic_text&#x22;]))
          }
      }
      if len(lines) > 0 {
          parts = append(parts, &#x22;Relevant memories:\\n&#x22;+strings.Join(lines, &#x22;\\n&#x22;))
      }
  }
  return strings.Join(parts, &#x22;\\n\\n&#x22;)
}`,
  },
]"
/>

<Callout type="info" title="The load-bearing habit">
  Always call `session.context(query=user_msg)` **before** the LLM call —
  every turn. That's the closing-the-loop step. Skipping it means the
  LLM works from stale state and the value of a memory layer collapses.
</Callout>

<Callout type="info" title="Save a roundtrip with fetchNextContext">
  `session.turn()` accepts `fetchNextContext: { query: nextMessage }`
  (Python: `fetch_next_context={"query": ...}`). When set, the response
  carries the next `/context` payload under `next_context`, so the
  client already has turn N+1's context by the time turn N finishes.
</Callout>

## Tool calls flow through to extraction [#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*&#x2A;
exchange and the extractor can capture facts that only surfaced inside a
tool output (e.g. &#x2A;"user's last order shipped from Tokyo"* from an
`order-lookup` tool).

```python
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`](https://github.com/sonz-ai/sonzai-python/blob/main/demos/openai_agents_companion/app.py)
helper — it converts a `Runner` result's `MessageOutputItem` /
`ToolCallItem` / `ToolCallOutputItem` items into this shape.

## Multimodal: your harness sees pixels, Sonzai sees text [#multimodal-your-harness-sees-pixels-sonzai-sees-text]

`/turn` accepts text content only. &#x2A;*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()`.

```python
# 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](/docs/en/guides/standalone-memory/pattern-1-realtime#working-with-images--multimodal-input).

<Callout type="info" title="Tool outputs are multimodal too">
  If a tool returns a screenshot, file blob, or any non-text payload,
  apply the same rule: have your harness summarize what the tool
  returned in a one-line text result before forwarding the
  `role: "tool"` message to `session.turn()`.
</Callout>

## Skipping local history with `recent_turns` [#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:

```python
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 [#where-to-next]

<Cards>
  <Card href="/docs/en/guides/standalone-memory/pattern-1-realtime" title="Pattern 1: Memory Middleware (deep guide)" description="Tool calling, multimodal/image bridging, dual-output prompts, exposing Sonzai's KB and memory search as LLM tools, polling deferred extraction, voice and multi-LLM router patterns." />

  <Card href="https://github.com/sonz-ai/sonzai-python/tree/main/demos/openai_agents_companion" title="Runnable demo: OpenAI Agents SDK + Gemini" description="Two-pane Streamlit app showing live mood, Big5, recent facts, inventory, and the constellation graph as you chat. Full source for the multimodal text-bridge and tool-message conversion." />

  <Card href="/docs/en/guides/standalone-memory/endpoints" title="Endpoint Walkthrough" description="Full reference for sessions.start, session.context, session.turn, /process, sessions.end, and the read endpoints." />

  <Card href="/docs/en/connect-standalone-batch" title="Pattern 5: Standalone Batch" description="Same data model, but you ingest a whole transcript at the end instead of per turn." />
</Cards>


---

# Conversations

Source: https://sonz.ai/docs/en/conversations

> Send messages to an agent and stream back responses over SSE — the primary loop that drives memory, mood, and personality evolution with every turn.



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 [#what-you-can-build-with-it]

* **Chat UIs** (web, mobile) — stream tokens directly into your interface
* **Voice conversations** — combine with [Voice](./voice) for spoken responses
* **Tool-using agents** — combine with [Custom Tools](./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 [#quickstart]

### Simple chat [#simple-chat]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

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

console.log(response.content);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

response = client.agents.chat(
  agent_id=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Hello!&#x22;}],
  user_id=&#x22;user-123&#x22;,
  language=&#x22;en&#x22;,
)

print(response.content)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

resp, err := client.Agents.Chat(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;Hello!&#x22;},
      },
      UserID:   &#x22;user-123&#x22;,
      Language: &#x22;en&#x22;,
  },
})

fmt.Println(resp.Content)`,
  },
]"
/>

### Streaming chat [#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]`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.chatStream({
agent: &#x22;agent-id&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Tell me a story&#x22; }],
userId: &#x22;user-123&#x22;,
language: &#x22;en&#x22;,
timezone: &#x22;America/New_York&#x22;,
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.chat(
  agent_id=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Tell me a story&#x22;}],
  user_id=&#x22;user-123&#x22;,
  language=&#x22;en&#x22;,
  timezone=&#x22;America/New_York&#x22;,
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go-callback&#x22;,
    label: &#x22;Go (callback)&#x22;,
    code: `err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;Tell me a story&#x22;},
      },
      UserID:   &#x22;user-123&#x22;,
      Language: &#x22;en&#x22;,
      Timezone: &#x22;America/New_York&#x22;,
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  return nil
})`,
  },
  {
    id: &#x22;go-channel&#x22;,
    label: &#x22;Go (channel)&#x22;,
    code: `ch, errCh := client.Agents.ChatStreamChannel(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;Tell me a story&#x22;},
      },
      UserID:   &#x22;user-123&#x22;,
  },
})

for event := range ch {
  fmt.Print(event.Content())
}
if err := <-errCh; err != nil {
  log.Fatal(err)
}`,
  },
]"
/>

## Core concepts [#core-concepts]

### Chat vs ChatStream [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#full-api]

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

| Method                              | Returns                                             | Description                                 |
| ----------------------------------- | --------------------------------------------------- | ------------------------------------------- |
| `chat(opts)`                        | `ChatResponse`                                      | Aggregated non-streaming chat               |
| `chatStream(opts)`                  | `AsyncIterable<ChatStreamEvent>` (TS) / `iter` (Py) | SSE streaming — tokens as they arrive       |
| `Chat(ctx, params)`                 | `*ChatResponse, error`                              | Go aggregated chat (buffers SSE internally) |
| `ChatStream(ctx, params, callback)` | `error`                                             | Go SSE streaming with per-event callback    |
| `ChatStreamChannel(ctx, params)`    | `<-chan ChatStreamEvent, <-chan error`              | Go SSE streaming via Go channel             |

### ChatOptions fields [#chatoptions-fields]

| Field                  | Type                    | Description                                                 |
| ---------------------- | ----------------------- | ----------------------------------------------------------- |
| `messages`             | `ChatMessage[]`         | Conversation history including the new user turn            |
| `userId`               | `string`                | Identifies the user; scopes per-user memory and state       |
| `sessionId`            | `string`                | Groups messages into a traceable conversation               |
| `instanceId`           | `string`                | Isolates state to a scenario (workspace, game session)      |
| `language`             | `string`                | BCP-47 language tag for the response                        |
| `timezone`             | `string`                | IANA timezone used for time-aware responses                 |
| `maxTurns`             | `int`                   | Maximum assistant messages per call (default: 1)            |
| `toolCapabilities`     | `AgentToolCapabilities` | Opt-in built-in tools (image generation, web search, …)     |
| `compiledSystemPrompt` | `string`                | Per-request application context injected into system prompt |
| `provider` / `model`   | `string`                | Override the LLM provider or model for this call            |

## Combines with other features [#combines-with-other-features]

### With [Wakeups](./wakeups) — proactive messages appear in the same chat stream [#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.

```typescript
// 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](./scheduled-reminders) — recurring proactive messages surface in chat [#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.

```typescript
// 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](./custom-tools) — agent calls your functions during chat [#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.

```typescript
// 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](./memory) — every turn writes memory, search retrieves it [#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.

```typescript
// 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 [#tutorials]

* [Getting started](./guides/getting-started) — first chat call end-to-end
* [Quickstart](./guides/getting-started) — five-minute TypeScript, Python, or Go setup

## Next steps [#next-steps]

* [Sessions](./sessions) — explicit session management and history
* [Voice](./voice) — combine chat with spoken audio responses
* [Memory](./memory) — how facts flow from conversation turns into long-term storage
* [Custom Tools](./custom-tools) — give the agent callable functions
* [Scheduled Reminders](./scheduled-reminders) — proactive agent-initiated messages on a cadence


---

# Custom State

Source: https://sonz.ai/docs/en/custom-states

> Per-user counters, flags, and strings the agent reads and writes — energy, currency, progress flags, game state — with a stable schema you control.



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 [#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 [#quickstart]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

await client.agents.customStates.create(&#x22;agent-id&#x22;, {
key:    &#x22;energy&#x22;,
value:  100,
scope:  &#x22;user&#x22;,
userId: &#x22;user-123&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

client.agents.custom_states.create(&#x22;agent-id&#x22;,
  key=&#x22;energy&#x22;,
  value=100,
  scope=&#x22;user&#x22;,
  user_id=&#x22;user-123&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

_, err := client.Agents.CustomState.Create(ctx, &#x22;agent-id&#x22;,
  sonzai.CustomStateCreateOptions{
      Key:    &#x22;energy&#x22;,
      Value:  100,
      Scope:  &#x22;user&#x22;,
      UserID: &#x22;user-123&#x22;,
  },
)`,
  },
]"
/>

## Core concepts [#core-concepts]

### Typed values [#typed-values]

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

| `content_type`     | Value                      | Example                              |
| ------------------ | -------------------------- | ------------------------------------ |
| `"text"` (default) | string                     | `"active"`, `"silver"`               |
| `"json"`           | any JSON-serializable type | `{ "score": 340, "tier": "silver" }` |
| `"binary"`         | base64-encoded bytes       | raw binary payloads                  |

### Scoping model [#scoping-model]

<Cards>
  <Card title="Global State" description="Per Instance — Shared across all users in an instance. Use for environment configuration, agent status, or global event flags." />

  <Card title="Per-User State" description="Per Instance + User — Scoped to one user. Use for energy, currency, progress, preferences, and any per-player data." />
</Cards>

<Callout type="info" title="Instances">
  All states are scoped to an `instanceId` — one deployment context of your agent (e.g. a workspace or game world). Omit `instanceId` to use the default instance. See [Instances](/docs/en/instances) for details.
</Callout>

### Agent reads and writes [#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](./custom-tools) that calls your backend.

### Distinct from Inventory [#distinct-from-inventory]

|          | Custom State                       | Inventory                                                       |
| -------- | ---------------------------------- | --------------------------------------------------------------- |
| Shape    | Simple typed field                 | Structured item with a KB-linked schema                         |
| Use case | Counters, flags, strings           | Items with multiple properties (medications, holdings, pets)    |
| Schema   | You define the key + content\_type | Defined in your Knowledge Base                                  |
| Best for | `energy: 80`, `tier: "gold"`       | `{ name: "Metformin", dose_mg: 500, frequency: "twice daily" }` |

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

## Full API [#full-api]

### Create [#create]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Global state (shared across all users in an instance)
await client.agents.customStates.create(&#x22;agent-id&#x22;, {
key:         &#x22;current_status&#x22;,
value:       &#x22;Processing requests&#x22;,
scope:       &#x22;global&#x22;,
contentType: &#x22;text&#x22;,
instanceId:  &#x22;workspace-1&#x22;,
});

// Per-user state
await client.agents.customStates.create(&#x22;agent-id&#x22;, {
key:         &#x22;energy&#x22;,
value:       100,
scope:       &#x22;user&#x22;,
contentType: &#x22;json&#x22;,
userId:      &#x22;user-123&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Global state
client.agents.custom_states.create(&#x22;agent-id&#x22;,
  key=&#x22;current_status&#x22;,
  value=&#x22;Processing requests&#x22;,
  scope=&#x22;global&#x22;,
  content_type=&#x22;text&#x22;,
  instance_id=&#x22;workspace-1&#x22;,
)

# Per-user state
client.agents.custom_states.create(&#x22;agent-id&#x22;,
  key=&#x22;energy&#x22;,
  value=100,
  scope=&#x22;user&#x22;,
  content_type=&#x22;json&#x22;,
  user_id=&#x22;user-123&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Global state
_, err = client.Agents.CustomState.Create(ctx, &#x22;agent-id&#x22;,
  sonzai.CustomStateCreateOptions{
      Key:         &#x22;current_status&#x22;,
      Value:       &#x22;Processing requests&#x22;,
      Scope:       &#x22;global&#x22;,
      ContentType: &#x22;text&#x22;,
      InstanceID:  &#x22;workspace-1&#x22;,
  },
)

// Per-user state
_, err = client.Agents.CustomState.Create(ctx, &#x22;agent-id&#x22;,
  sonzai.CustomStateCreateOptions{
      Key:         &#x22;energy&#x22;,
      Value:       100,
      Scope:       &#x22;user&#x22;,
      ContentType: &#x22;json&#x22;,
      UserID:      &#x22;user-123&#x22;,
  },
)`,
  },
]"
/>

### Upsert (create or update by key) [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.customStates.upsert(&#x22;agent-id&#x22;, {
key:    &#x22;energy&#x22;,
value:  80,
scope:  &#x22;user&#x22;,
userId: &#x22;user-123&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.custom_states.upsert(&#x22;agent-id&#x22;,
  key=&#x22;energy&#x22;,
  value=80,
  scope=&#x22;user&#x22;,
  user_id=&#x22;user-123&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Agents.CustomState.Upsert(ctx, &#x22;agent-id&#x22;,
  sonzai.CustomStateUpsertOptions{
      Key:    &#x22;energy&#x22;,
      Value:  80,
      Scope:  &#x22;user&#x22;,
      UserID: &#x22;user-123&#x22;,
  },
)`,
  },
]"
/>

### Get by key [#get-by-key]

Retrieve a specific state by its composite key (key + scope + user\_id + instance\_id).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const state = await client.agents.customStates.getByKey(&#x22;agent-id&#x22;, {
key:    &#x22;energy&#x22;,
scope:  &#x22;user&#x22;,
userId: &#x22;user-123&#x22;,
});

console.log(state.value);     // 80
console.log(state.updatedAt); // ISO timestamp`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `state = client.agents.custom_states.get_by_key(&#x22;agent-id&#x22;,
  key=&#x22;energy&#x22;,
  scope=&#x22;user&#x22;,
  user_id=&#x22;user-123&#x22;,
)

print(state.value)      # 80
print(state.updated_at)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `state, err := client.Agents.CustomState.GetByKey(ctx, &#x22;agent-id&#x22;,
  sonzai.CustomStateGetByKeyOptions{
      Key:    &#x22;energy&#x22;,
      Scope:  &#x22;user&#x22;,
      UserID: &#x22;user-123&#x22;,
  },
)

fmt.Println(state.Value)
fmt.Println(state.UpdatedAt)`,
  },
]"
/>

### List [#list]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// All global states for an instance
const globals = await client.agents.customStates.list(&#x22;agent-id&#x22;, {
scope:      &#x22;global&#x22;,
instanceId: &#x22;workspace-1&#x22;,
});

// All per-user states for a specific user
const userStates = await client.agents.customStates.list(&#x22;agent-id&#x22;, {
scope:  &#x22;user&#x22;,
userId: &#x22;user-123&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# All global states
globals = client.agents.custom_states.list(&#x22;agent-id&#x22;,
  scope=&#x22;global&#x22;,
  instance_id=&#x22;workspace-1&#x22;,
)

# All per-user states
user_states = client.agents.custom_states.list(&#x22;agent-id&#x22;,
  scope=&#x22;user&#x22;,
  user_id=&#x22;user-123&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// All global states
globals, err := client.Agents.CustomState.List(ctx, &#x22;agent-id&#x22;,
  &sonzai.CustomStateListOptions{Scope: &#x22;global&#x22;, InstanceID: &#x22;workspace-1&#x22;},
)

// All per-user states
userStates, err := client.Agents.CustomState.List(ctx, &#x22;agent-id&#x22;,
  &sonzai.CustomStateListOptions{Scope: &#x22;user&#x22;, UserID: &#x22;user-123&#x22;},
)`,
  },
]"
/>

### Update by state ID [#update-by-state-id]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.customStates.update(&#x22;agent-id&#x22;, stateId, {
value: 60,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.custom_states.update(&#x22;agent-id&#x22;, state_id, {
  &#x22;value&#x22;: 60,
})`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Agents.CustomState.Update(ctx, &#x22;agent-id&#x22;, stateID,
  sonzai.CustomStateUpdateOptions{Value: 60},
)`,
  },
]"
/>

### Delete [#delete]

Delete by state ID or by composite key.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Delete by key
await client.agents.customStates.deleteByKey(&#x22;agent-id&#x22;, {
key:    &#x22;energy&#x22;,
scope:  &#x22;user&#x22;,
userId: &#x22;user-123&#x22;,
});

// Delete by state_id
await client.agents.customStates.delete(&#x22;agent-id&#x22;, stateId);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Delete by key
client.agents.custom_states.delete_by_key(&#x22;agent-id&#x22;,
  key=&#x22;energy&#x22;,
  scope=&#x22;user&#x22;,
  user_id=&#x22;user-123&#x22;,
)

# Delete by state_id
client.agents.custom_states.delete(&#x22;agent-id&#x22;, state_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Delete by key
err := client.Agents.CustomState.DeleteByKey(ctx, &#x22;agent-id&#x22;,
  sonzai.CustomStateDeleteByKeyOptions{
      Key:    &#x22;energy&#x22;,
      Scope:  &#x22;user&#x22;,
      UserID: &#x22;user-123&#x22;,
  },
)

// Delete by state ID
err = client.Agents.CustomState.Delete(ctx, &#x22;agent-id&#x22;, stateID)`,
  },
]"
/>

### Method summary [#method-summary]

| Method                                | Returns                    | Description                           |
| ------------------------------------- | -------------------------- | ------------------------------------- |
| `Create(ctx, agentID, opts)`          | `*CustomState`             | Create a new state entry              |
| `Upsert(ctx, agentID, opts)`          | `*CustomState`             | Create or replace by composite key    |
| `GetByKey(ctx, agentID, opts)`        | `*CustomState`             | Fetch one state by key + scope        |
| `List(ctx, agentID, opts)`            | `*CustomStateListResponse` | List states, filtered by scope / user |
| `Update(ctx, agentID, stateID, opts)` | `*CustomState`             | Update value by state ID              |
| `Delete(ctx, agentID, stateID)`       | —                          | Delete by state ID                    |
| `DeleteByKey(ctx, agentID, opts)`     | —                          | Delete by composite key               |

## Combines with other features [#combines-with-other-features]

### With [Custom Tools](./custom-tools) — tools that read and write state [#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.

```typescript
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](./inventory) — when state is structured, use inventory [#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.

| Situation                                           | Use          |
| --------------------------------------------------- | ------------ |
| Single number or string per key                     | Custom State |
| A flag that is true/false                           | Custom State |
| A flat object with a few fields                     | Custom State |
| An item with a schema defined in the Knowledge Base | Inventory    |
| A collection of items of the same type per user     | Inventory    |

### With [Sessions](./sessions) — session-scoped vs persistent state [#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 [#tutorials]

* [Custom States walkthrough](./tutorial-custom-states) — end-to-end example: create, upsert, read during chat, trigger events on state changes

## Next steps [#next-steps]

<Cards>
  <Card href="/docs/en/inventory" title="Inventory" description="Structured per-user items with KB-linked schemas." />

  <Card href="/docs/en/custom-tools" title="Custom Tools" description="Tools the agent can call during chat to read or modify state." />

  <Card href="/docs/en/sessions" title="Sessions" description="Session-scoped vs persistent state, and session lifecycle." />

  <Card href="/docs/en/instances" title="Instances" description="Isolate state per workspace, environment, or deployment context." />
</Cards>


---

# Custom Tools

Source: https://sonz.ai/docs/en/custom-tools

> Define functions the LLM can call during chat — built-in platform capabilities, persistent agent-level tools, and ephemeral session tools injected at runtime.



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.

<Callout type="info" title="Using your own LLM?">
  If you use [standalone memory mode](/docs/en/guides/standalone-memory) (BYO-LLM), Sonzai exposes tool schemas you can wire into your agent framework (LangChain, Vercel AI SDK, Gemini function calling, etc.). See the [Tool Integration guide](/docs/en/guides/tool-integration) for details.
</Callout>

## What you can build with it [#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](./custom-states) 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 [#quickstart]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

// 1. Register a tool for this session
await client.agents.sessions.setTools(&#x22;agent-id&#x22;, &#x22;session-id&#x22;, [
{
  name: &#x22;check_status&#x22;,
  description: &#x22;Return the current operational status. Call when the user asks about system health.&#x22;,
  parameters: { type: &#x22;object&#x22;, 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:  &#x22;agent-id&#x22;,
userId: &#x22;user-123&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;What's the current status?&#x22; }],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
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:  &#x22;agent-id&#x22;,
userId: &#x22;user-123&#x22;,
messages: [
  { role: &#x22;user&#x22;, content: &#x22;What's the current status?&#x22; },
  { role: &#x22;tool&#x22;, content: results.join(&#x22;\\n&#x22;) },
],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# 1. Register a tool for this session
client.agents.sessions.set_tools(&#x22;agent-id&#x22;, &#x22;session-id&#x22;, [
  {
      &#x22;name&#x22;: &#x22;check_status&#x22;,
      &#x22;description&#x22;: &#x22;Return the current operational status.&#x22;,
      &#x22;parameters&#x22;: {&#x22;type&#x22;: &#x22;object&#x22;, &#x22;properties&#x22;: {}},
  },
])

# 2. Chat — collect tool calls
tool_calls = []
for event in client.agents.chat(
  agent=&#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What's the current status?&#x22;}],
  stream=True,
):
  if event.content:
      print(event.content, end=&#x22;&#x22;, flush=True)
  calls = getattr(event, &#x22;side_effects&#x22;, {}).get(&#x22;external_tool_calls&#x22;, [])
  tool_calls.extend(calls)

# 3. Execute and return results
results = [my_backend.run(c[&#x22;name&#x22;], c[&#x22;arguments&#x22;]) for c in tool_calls]
for event in client.agents.chat(
  agent=&#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What's the current status?&#x22;},
      {&#x22;role&#x22;: &#x22;tool&#x22;, &#x22;content&#x22;: &#x22;\\n&#x22;.join(results)},
  ],
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

// 1. Register a tool for this session
_, err := client.Agents.Sessions.SetTools(ctx, &#x22;agent-id&#x22;, &#x22;session-id&#x22;,
  sonzai.SessionToolsOptions{
      Tools: []sonzai.ToolDefinition{
          {
              Name:        &#x22;check_status&#x22;,
              Description: &#x22;Return the current operational status.&#x22;,
              Parameters:  map[string]any{&#x22;type&#x22;: &#x22;object&#x22;, &#x22;properties&#x22;: map[string]any{}},
          },
      },
  },
)

// 2. Chat — collect tool calls
var toolCalls []sonzai.ExternalToolCall
err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      UserID:   &#x22;user-123&#x22;,
      Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;What's the current status?&#x22;}},
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  toolCalls = append(toolCalls, event.ExternalToolCalls...)
  return nil
})

// 3. Execute and return results
results := make([]string, 0, len(toolCalls))
for _, call := range toolCalls {
  results = append(results, myBackend.Run(call.Name, call.Parameters))
}
err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      UserID: &#x22;user-123&#x22;,
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;What's the current status?&#x22;},
          {Role: &#x22;tool&#x22;, Content: strings.Join(results, &#x22;\\n&#x22;)},
      },
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  return nil
})`,
  },
]"
/>

## Core concepts [#core-concepts]

### Built-In Tools (Capabilities) [#built-in-tools-capabilities]

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

<Callout type="info" title="sonzai_memory_recall (Always On)">
  Searches stored memories during inference. Auto-injected into context.
</Callout>

<Callout type="info" title="sonzai_remember_name (Toggleable)">
  Persists the user's name for future conversations. On by default.
</Callout>

<Callout type="info" title="sonzai_web_search (Toggleable)">
  Live web search via Google. On by default.
</Callout>

<Callout type="info" title="sonzai_inventory (Toggleable)">
  Read user resource items and join with Knowledge Base data.
</Callout>

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Set capabilities at agent creation
const agent = await client.agents.create({
agentId: &#x22;your-stable-uuid&#x22;,  // recommended — makes creation idempotent
name: &#x22;Luna&#x22;,
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(&#x22;agent-id&#x22;, {
toolCapabilities: {
  webSearch: false,
  inventory: true,
},
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Set capabilities at agent creation
agent = client.agents.create(
  agent_id=&#x22;your-stable-uuid&#x22;,  # recommended
  name=&#x22;Luna&#x22;,
  big5={&#x22;openness&#x22;: 0.75, &#x22;conscientiousness&#x22;: 0.6, &#x22;extraversion&#x22;: 0.8,
        &#x22;agreeableness&#x22;: 0.7, &#x22;neuroticism&#x22;: 0.3},
  tool_capabilities={
      &#x22;web_search&#x22;:       True,
      &#x22;remember_name&#x22;:    True,
      &#x22;image_generation&#x22;: False,
      &#x22;inventory&#x22;:        True,
  },
)

# Or update capabilities
client.agents.update(&#x22;agent-id&#x22;,
  tool_capabilities={&#x22;web_search&#x22;: False, &#x22;inventory&#x22;: True},
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Set at creation
agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  AgentID: &#x22;your-stable-uuid&#x22;,  // recommended
  Name:    &#x22;Luna&#x22;,
  ToolCapabilities: &sonzai.AgentToolCapabilities{
      WebSearch:       true,
      RememberName:    true,
      ImageGeneration: false,
      Inventory:       true,
  },
})

// Or update
err = client.Agents.Update(ctx, &#x22;agent-id&#x22;, sonzai.UpdateAgentOptions{
  ToolCapabilities: &sonzai.AgentToolCapabilities{
      WebSearch: false,
      Inventory: true,
  },
})`,
  },
]"
/>

<Callout type="info" title="Reserved Prefix">
  The `sonzai_` prefix is reserved. Your custom tools must not use it — the API will reject them.
</Callout>

### `customTools` in agent capabilities [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Read agent capabilities — includes current custom tools
const caps = await client.agents.getCapabilities(&#x22;agent-id&#x22;);
console.log(caps.customTools);  // CustomToolDefinition[] | null

// Register a new agent-level custom tool
await client.agents.createCustomTool(&#x22;agent-id&#x22;, {
name: &#x22;lookup_order&#x22;,
description: &#x22;Look up an order by ID and return its status.&#x22;,
parameters: {
  type: &#x22;object&#x22;,
  properties: {
    order_id: { type: &#x22;string&#x22; },
  },
  required: [&#x22;order_id&#x22;],
},
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Read agent capabilities — includes current custom tools
caps = client.agents.get_capabilities(&#x22;agent-id&#x22;)
print(caps.custom_tools)  # list[CustomToolDefinition] | None

# Register a new agent-level custom tool
client.agents.create_custom_tool(
  &#x22;agent-id&#x22;,
  name=&#x22;lookup_order&#x22;,
  description=&#x22;Look up an order by ID and return its status.&#x22;,
  parameters={
      &#x22;type&#x22;: &#x22;object&#x22;,
      &#x22;properties&#x22;: {&#x22;order_id&#x22;: {&#x22;type&#x22;: &#x22;string&#x22;}},
      &#x22;required&#x22;: [&#x22;order_id&#x22;],
  },
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Read agent capabilities — includes current custom tools
caps, _ := client.Agents.GetCapabilities(ctx, &#x22;agent-id&#x22;)
fmt.Println(caps.CustomTools)  // []CustomToolDefinition

// Register a new agent-level custom tool
_, err := client.Agents.CreateCustomTool(ctx, &#x22;agent-id&#x22;,
  sonzai.CreateCustomToolOptions{
      Name:        &#x22;lookup_order&#x22;,
      Description: &#x22;Look up an order by ID and return its status.&#x22;,
      Parameters: map[string]any{
          &#x22;type&#x22;: &#x22;object&#x22;,
          &#x22;properties&#x22;: map[string]any{
              &#x22;order_id&#x22;: map[string]any{&#x22;type&#x22;: &#x22;string&#x22;},
          },
          &#x22;required&#x22;: []string{&#x22;order_id&#x22;},
      },
  },
)`,
  },
]"
/>

### Tool scoping [#tool-scoping]

| Type                 | Scope         | Persistence      | Managed Via                 |
| -------------------- | ------------- | ---------------- | --------------------------- |
| Built-in (`sonzai_`) | All instances | Platform-managed | SDK capabilities, Dashboard |
| Agent-level custom   | All instances | Persistent       | SDK, Dashboard              |
| Session-level        | Per session   | Temporary        | SDK (inline or setTools)    |

## Full API [#full-api]

### Custom Tools (Agent-Level) [#custom-tools-agent-level]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Create a custom tool
await client.agents.createCustomTool(&#x22;agent-id&#x22;, {
name: &#x22;check_inventory&#x22;,
description: &#x22;Check the user's current tasks and their statuses&#x22;,
parameters: {
  type: &#x22;object&#x22;,
  properties: {
    item_type: {
      type: &#x22;string&#x22;,
      description: &#x22;Filter by category: active, pending, completed&#x22;,
    },
  },
},
});

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

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

// Delete a tool
await client.agents.deleteCustomTool(&#x22;agent-id&#x22;, &#x22;check_inventory&#x22;);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Create a custom tool
client.agents.create_custom_tool(&#x22;agent-id&#x22;,
  name=&#x22;check_inventory&#x22;,
  description=&#x22;Check the user's current tasks and their statuses&#x22;,
  parameters={
      &#x22;type&#x22;: &#x22;object&#x22;,
      &#x22;properties&#x22;: {
          &#x22;item_type&#x22;: {
              &#x22;type&#x22;: &#x22;string&#x22;,
              &#x22;description&#x22;: &#x22;Filter by category: active, pending, completed&#x22;,
          },
      },
  },
)

# List all custom tools
tools = client.agents.list_custom_tools(&#x22;agent-id&#x22;)

# Update
client.agents.update_custom_tool(&#x22;agent-id&#x22;, &#x22;check_inventory&#x22;,
  description=&#x22;Check and summarize the user's tasks by category&#x22;,
)

# Delete
client.agents.delete_custom_tool(&#x22;agent-id&#x22;, &#x22;check_inventory&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Create
_, err := client.Agents.CreateCustomTool(ctx, &#x22;agent-id&#x22;,
  sonzai.CreateCustomToolOptions{
      Name:        &#x22;check_inventory&#x22;,
      Description: &#x22;Check the user's current tasks&#x22;,
      Parameters: map[string]any{
          &#x22;type&#x22;: &#x22;object&#x22;,
          &#x22;properties&#x22;: map[string]any{
              &#x22;item_type&#x22;: map[string]any{&#x22;type&#x22;: &#x22;string&#x22;},
          },
      },
  },
)

// List
tools, err := client.Agents.ListCustomTools(ctx, &#x22;agent-id&#x22;)

// Update
err = client.Agents.UpdateCustomTool(ctx, &#x22;agent-id&#x22;, &#x22;check_inventory&#x22;,
  sonzai.UpdateCustomToolOptions{
      Description: &#x22;Check and summarize the user's tasks&#x22;,
  },
)

// Delete
err = client.Agents.DeleteCustomTool(ctx, &#x22;agent-id&#x22;, &#x22;check_inventory&#x22;)`,
  },
]"
/>

### Session-Level Tools (temporary) [#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 [#option-1--set-for-an-existing-session]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.sessions.setTools(&#x22;agent-id&#x22;, &#x22;session-id&#x22;, [
{
  name: &#x22;execute_action&#x22;,
  description: &#x22;Execute an action from the agent's capabilities&#x22;,
  parameters: {
    type: &#x22;object&#x22;,
    properties: {
      action_name: { type: &#x22;string&#x22; },
      target:      { type: &#x22;string&#x22; },
    },
    required: [&#x22;action_name&#x22;],
  },
},
]);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.sessions.set_tools(&#x22;agent-id&#x22;, &#x22;session-id&#x22;, [
  {
      &#x22;name&#x22;: &#x22;execute_action&#x22;,
      &#x22;description&#x22;: &#x22;Execute an action from the agent's capabilities&#x22;,
      &#x22;parameters&#x22;: {
          &#x22;type&#x22;: &#x22;object&#x22;,
          &#x22;properties&#x22;: {
              &#x22;action_name&#x22;: {&#x22;type&#x22;: &#x22;string&#x22;},
              &#x22;target&#x22;:      {&#x22;type&#x22;: &#x22;string&#x22;},
          },
          &#x22;required&#x22;: [&#x22;action_name&#x22;],
      },
  },
])`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Agents.Sessions.SetTools(ctx, &#x22;agent-id&#x22;, &#x22;session-id&#x22;,
  sonzai.SessionToolsOptions{
      Tools: []sonzai.ToolDefinition{
          {
              Name:        &#x22;execute_action&#x22;,
              Description: &#x22;Execute an action from the agent's capabilities&#x22;,
              Parameters: map[string]any{
                  &#x22;type&#x22;: &#x22;object&#x22;,
                  &#x22;properties&#x22;: map[string]any{
                      &#x22;action_name&#x22;: map[string]any{&#x22;type&#x22;: &#x22;string&#x22;},
                      &#x22;target&#x22;:      map[string]any{&#x22;type&#x22;: &#x22;string&#x22;},
                  },
                  &#x22;required&#x22;: []string{&#x22;action_name&#x22;},
              },
          },
      },
  },
)`,
  },
]"
/>

#### Option 2 — Pass inline with the chat call [#option-2--pass-inline-with-the-chat-call]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.chatStream({
agent:    &#x22;agent-id&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Check my tools&#x22; }],
userId:   &#x22;user-123&#x22;,
toolDefinitions: [
  {
    name:        &#x22;check_inventory&#x22;,
    description: &#x22;List the agent's active tools&#x22;,
    parameters:  { type: &#x22;object&#x22;, properties: {} },
  },
],
})) {
// handle events...
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.chat(
  agent=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Check my tools&#x22;}],
  user_id=&#x22;user-123&#x22;,
  tool_definitions=[
      {
          &#x22;name&#x22;: &#x22;check_inventory&#x22;,
          &#x22;description&#x22;: &#x22;List the agent's active tools&#x22;,
          &#x22;parameters&#x22;: {&#x22;type&#x22;: &#x22;object&#x22;, &#x22;properties&#x22;: {}},
      },
  ],
  stream=True,
):
  pass  # handle events`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Check my tools&#x22;}},
      UserID:   &#x22;user-123&#x22;,
      ToolDefinitions: []sonzai.ToolDefinition{
          {
              Name:        &#x22;check_inventory&#x22;,
              Description: &#x22;List the agent's active tools&#x22;,
              Parameters:  map[string]any{&#x22;type&#x22;: &#x22;object&#x22;, &#x22;properties&#x22;: map[string]any{}},
          },
      },
  },
}, func(event sonzai.ChatStreamEvent) error {
  return nil // handle events
})`,
  },
]"
/>

### Handling Tool Calls [#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 [#1-receive-the-tool-call]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const toolCalls: { name: string; arguments: Record<string, unknown> }[] = [];

for await (const event of client.agents.chatStream({
agent:    &#x22;agent-id&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;What tasks do I have?&#x22; }],
userId:   &#x22;user-123&#x22;,
})) {
// 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);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `tool_calls = []

for event in client.agents.chat(
  agent=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What tasks do I have?&#x22;}],
  user_id=&#x22;user-123&#x22;,
  stream=True,
):
  if event.content:
      print(event.content, end=&#x22;&#x22;, flush=True)
  calls = getattr(event, &#x22;side_effects&#x22;, {}).get(&#x22;external_tool_calls&#x22;, [])
  tool_calls.extend(calls)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `var toolCalls []sonzai.ExternalToolCall

err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;What tasks do I have?&#x22;}},
      UserID:   &#x22;user-123&#x22;,
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  toolCalls = append(toolCalls, event.ExternalToolCalls...)
  return nil
})`,
  },
]"
/>

#### 2. Execute and return results [#2-execute-and-return-results]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 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:    &#x22;agent-id&#x22;,
userId:   &#x22;user-123&#x22;,
messages: [
  { role: &#x22;user&#x22;,  content: &#x22;What tasks do I have?&#x22; },
  { role: &#x22;tool&#x22;,  content: toolResults.join(&#x22;\\n&#x22;) },
],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Execute your tool calls
tool_results = []
for call in tool_calls:
  result = my_backend.execute_tool(call[&#x22;name&#x22;], call[&#x22;arguments&#x22;])
  tool_results.append(result)

# Return results in the next chat message
for event in client.agents.chat(
  agent=&#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What tasks do I have?&#x22;},
      {&#x22;role&#x22;: &#x22;tool&#x22;, &#x22;content&#x22;: &#x22;\\n&#x22;.join(tool_results)},
  ],
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Execute your tool calls
toolResults := make([]string, 0, len(toolCalls))
for _, call := range toolCalls {
  result := myBackend.ExecuteTool(call.Name, call.Parameters)
  toolResults = append(toolResults, result)
}

// Return results in the next message
err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      UserID: &#x22;user-123&#x22;,
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;What tasks do I have?&#x22;},
          {Role: &#x22;tool&#x22;, Content: strings.Join(toolResults, &#x22;\\n&#x22;)},
      },
  },
}, func(event sonzai.ChatStreamEvent) error {
  return nil
})`,
  },
]"
/>

## In Practice [#in-practice]

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

  

  

  
    **Tools are business-logic actions with approval gates.** Never let the agent write to your system of record unilaterally for anything material — wrap destructive or high-stakes tools with an approval step.

    ```typescript
    await client.agents.sessions.setTools("agent-id", "session-id", [
      {
        name: "propose_stage_change",
        description: "Propose moving the deal to a new stage. Requires rep approval before the CRM is updated.",
        parameters: { /* JSON Schema */ },
      },
      {
        name: "flag_for_legal_review",
        description: "Flag this conversation for legal review. Halts the agent and notifies compliance.",
        parameters: { /* JSON Schema */ },
      },
    ]);
    ```

    **Pattern: propose, don't execute.** Tools return a proposed action, your backend validates + applies it, and the audit trail captures the agent's intent separately from the human's approval.
  

## Combines with [#combines-with]

### [Custom State](./custom-states) — what tools often act on [#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.

```typescript
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](./sessions) — session-scoped vs persistent tools [#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](./conversations) — tool calls in the message stream [#conversations--tool-calls-in-the-message-stream]

Tool calls appear as side effects in the SSE stream. See the [Conversations](./conversations) page for the full event shape and streaming patterns.

## Tutorials [#tutorials]

* [Custom States walkthrough](./tutorial-custom-states) — end-to-end example that includes a `spend_energy` tool writing back to Custom State

## Next steps [#next-steps]

<Cards>
  <Card href="/docs/en/custom-states" title="Custom State" description="Per-user counters, flags, and strings the agent reads and writes." />

  <Card href="/docs/en/sessions" title="Sessions" description="Session lifecycle and session-scoped tool injection." />

  <Card href="/docs/en/conversations" title="Conversations" description="Full SSE event shape and streaming patterns." />

  <Card href="/docs/en/guides/tool-integration" title="Tool Integration (BYO-LLM)" description="Wire Sonzai tools into your own agent framework." />
</Cards>


---

# Emotions & Mood

Source: https://sonz.ai/docs/en/emotions

> Read, analyze, and time-travel through an agent's living mood state — a four-dimensional signal that shifts automatically with every conversation, event, and passage of time.



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.

<Callout type="info" title="Automatic — no setup required">
  Mood, emotions, and goals are all managed automatically by the context engine. You do not push deltas or set mood manually — you read what the engine has already computed.
</Callout>

## What you can build with it [#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 [#quickstart]

Fetch the current mood for an agent-user pair.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

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

console.log(mood.label);      // &#x22;Content&#x22;
console.log(mood.happiness);  // 72
console.log(mood.energy);     // 65
console.log(mood.calmness);   // 80
console.log(mood.affection);  // 68`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

mood = client.agents.get_mood(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)

print(mood.label)      # &#x22;Content&#x22;
print(mood.happiness)  # 72
print(mood.energy)     # 65
print(mood.calmness)   # 80
print(mood.affection)  # 68`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

mood, err := client.Agents.GetMood(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)

fmt.Println(mood.Label)     // &#x22;Content&#x22;
fmt.Println(mood.Happiness) // 72
fmt.Println(mood.Energy)    // 65
fmt.Println(mood.Calmness)  // 80
fmt.Println(mood.Affection) // 68`,
  },
]"
/>

## Core concepts [#core-concepts]

### Four mood dimensions [#four-mood-dimensions]

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

| Dimension     | Low end             | High end              |
| ------------- | ------------------- | --------------------- |
| **Happiness** | Sad / distressed    | Joyful / blissful     |
| **Energy**    | Lethargic / flat    | Active / enthusiastic |
| **Calmness**  | Anxious / unsettled | Peaceful / at ease    |
| **Affection** | Distant / reserved  | Warm / affectionate   |

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 [#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 [#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 [#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 [#full-api]

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

| Method                                                         | Returns                  | Description                          |
| -------------------------------------------------------------- | ------------------------ | ------------------------------------ |
| `GetMood(ctx, agentID, userID, instanceID)`                    | `*MoodResponse`          | Current mood for a user              |
| `GetMoodHistory(ctx, agentID, userID, instanceID)`             | `*MoodHistoryResponse`   | Time-series of mood snapshots        |
| `GetMoodAggregate(ctx, agentID, userID, instanceID)`           | `*MoodAggregateResponse` | Aggregated mood stats across users   |
| `GetTimeMachine(ctx, agentID, TimeMachineOptions{At, UserID})` | `*TimeMachineResponse`   | Full agent state at a past timestamp |

## Combines with other features [#combines-with-other-features]

### With [Self-Improvement](./self-improvement) — mood feeds personality evolution [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. Read the mood history to see emotional trajectory
const history = await client.agents.getMoodHistory(&#x22;agent-id&#x22;, {
userId: &#x22;user-123&#x22;,
});

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

for (const evt of improvements.events) {
console.log(evt.trigger, evt.dimension, evt.delta);
// &#x22;sustained_low_calmness&#x22;  &#x22;neuroticism&#x22;  +0.04
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Read the mood history
history = client.agents.get_mood_history(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)

# 2. Fetch self-improvement events
improvements = client.agents.get_self_improvement(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)

for evt in improvements.events:
  print(evt.trigger, evt.dimension, evt.delta)
  # &#x22;sustained_low_calmness&#x22;  &#x22;neuroticism&#x22;  0.04`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. Read the mood history
history, err := client.Agents.GetMoodHistory(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)

// 2. Fetch self-improvement events
improvements, err := client.Agents.GetSelfImprovement(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)

for _, evt := range improvements.Events {
  fmt.Println(evt.Trigger, evt.Dimension, evt.Delta)
  // &#x22;sustained_low_calmness&#x22;  &#x22;neuroticism&#x22;  0.04
}`,
  },
]"
/>

### With [Agent Insights](./agent-insights) — mood is part of the "what the agent learned" picture [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const [mood, insights] = await Promise.all([
client.agents.getMood(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; }),
client.agents.getInsights(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; }),
]);

console.log(&#x22;Current mood:&#x22;, mood.label, mood.happiness);
console.log(&#x22;Key insight:&#x22;, insights.summary);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import asyncio

mood, insights = asyncio.run(asyncio.gather(
  client.agents.get_mood(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;),
  client.agents.get_insights(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;),
))

print(&#x22;Current mood:&#x22;, mood.label, mood.happiness)
print(&#x22;Key insight:&#x22;, insights.summary)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `mood, err := client.Agents.GetMood(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
insights, err := client.Agents.GetInsights(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)

fmt.Println(&#x22;Current mood:&#x22;, mood.Label, mood.Happiness)
fmt.Println(&#x22;Key insight:&#x22;, insights.Summary)`,
  },
]"
/>

### With [Advance Time](./advance-time) — fast-forward mood decay [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. Read mood now
const before = await client.agents.getMood(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
console.log(&#x22;Before:&#x22;, 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(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
console.log(&#x22;After:&#x22;, after.happiness);  // 68`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Read mood now
before = client.agents.get_mood(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
print(&#x22;Before:&#x22;, before.happiness)  # 90

# 2. Advance time by 72 hours
client.workbench.advance_time(hours=72)

# 3. Read mood again — decayed toward baseline
after = client.agents.get_mood(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
print(&#x22;After:&#x22;, after.happiness)   # 68`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. Read mood now
before, err := client.Agents.GetMood(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
fmt.Println(&#x22;Before:&#x22;, before.Happiness) // 90

// 2. Advance time by 72 hours
err = client.Workbench.AdvanceTime(ctx, sonzai.AdvanceTimeOptions{Hours: 72})

// 3. Read mood again — decayed toward baseline
after, err := client.Agents.GetMood(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
fmt.Println(&#x22;After:&#x22;, after.Happiness)   // 68`,
  },
]"
/>

## Tutorials [#tutorials]

* [Memory tutorial](./tutorial-memory) — see how conversation content flows into mood and memory together.

## Next steps [#next-steps]

* [Self-Improvement](./self-improvement) — how sustained mood patterns drive personality evolution
* [Agent Insights](./agent-insights) — the full picture of what the agent knows about a user
* [Personality](./personality) — the baseline that mood decays toward
* [Advance Time](./advance-time) — fast-forward the clock in tests and the workbench


---

# Events & Multi-Agent Dialogue

Source: https://sonz.ai/docs/en/events-and-dialogue

> Trigger agent reactions to backend events and run conversations between two agents — for achievements, milestones, NPC interactions, or automated simulations.



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 [#what-you-can-build-with-it]

### Events [#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 [#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 [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

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

console.log(result.accepted); // true
console.log(result.event_id); // &#x22;evt_01HX...&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

result = client.agents.trigger_backend_event(
  &#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  event_type=&#x22;level_up&#x22;,
  event_description=&#x22;The user just reached level 25 — a major milestone in the game.&#x22;,
  metadata={
      &#x22;new_level&#x22;: &#x22;25&#x22;,
      &#x22;previous_level&#x22;: &#x22;24&#x22;,
      &#x22;xp_total&#x22;: &#x22;12500&#x22;,
  },
)

print(result.accepted)  # True
print(result.event_id)  # &#x22;evt_01HX...&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
if err != nil { panic(err) }

result, err := client.Agents.TriggerEvent(ctx, &#x22;agent_abc&#x22;,
  sonzai.TriggerEventOptions{
      UserID:           &#x22;user_123&#x22;,
      EventType:        &#x22;level_up&#x22;,
      EventDescription: &#x22;The user just reached level 25 — a major milestone in the game.&#x22;,
      Metadata: map[string]string{
          &#x22;new_level&#x22;:      &#x22;25&#x22;,
          &#x22;previous_level&#x22;: &#x22;24&#x22;,
          &#x22;xp_total&#x22;:       &#x22;12500&#x22;,
      },
  },
)
if err != nil { panic(err) }

fmt.Println(result.Accepted) // true
fmt.Println(result.EventID)  // &#x22;evt_01HX...&#x22;`,
  },
]"
/>

***

## Quickstart — Run a dialogue [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

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

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

messages.push({ role: &#x22;assistant&#x22;, content: turnA.response });

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

console.log(&#x22;Agent A:&#x22;, turnA.response);
console.log(&#x22;Agent B:&#x22;, turnB.response);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# Seed the conversation
messages = [
  {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Tell me something interesting about the ancient ruins.&#x22;},
]

# Turn 1 — agent_a responds
turn_a = client.agents.dialogue(
  &#x22;agent_a&#x22;,
  user_id=&#x22;user_123&#x22;,
  messages=messages,
  scene_guidance=&#x22;Two NPCs are exploring ancient ruins together. Keep responses under 3 sentences.&#x22;,
)

messages.append({&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: turn_a.response})

# Turn 2 — agent_b responds to what agent_a said
turn_b = client.agents.dialogue(
  &#x22;agent_b&#x22;,
  user_id=&#x22;user_123&#x22;,
  messages=messages,
  scene_guidance=&#x22;Two NPCs are exploring ancient ruins together. Keep responses under 3 sentences.&#x22;,
)

print(&#x22;Agent A:&#x22;, turn_a.response)
print(&#x22;Agent B:&#x22;, turn_b.response)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
if err != nil { panic(err) }

guidance := &#x22;Two NPCs are exploring ancient ruins together. Keep responses under 3 sentences.&#x22;

// Seed the conversation
messages := []sonzai.ChatMessage{
  {Role: &#x22;user&#x22;, Content: &#x22;Tell me something interesting about the ancient ruins.&#x22;},
}

// Turn 1 — agent_a responds
turnA, err := client.Agents.Dialogue(ctx, &#x22;agent_a&#x22;, sonzai.DialogueOptions{
  UserID:        &#x22;user_123&#x22;,
  Messages:      messages,
  SceneGuidance: guidance,
})
if err != nil { panic(err) }

messages = append(messages, sonzai.ChatMessage{Role: &#x22;assistant&#x22;, Content: turnA.Response})

// Turn 2 — agent_b responds to what agent_a said
turnB, err := client.Agents.Dialogue(ctx, &#x22;agent_b&#x22;, sonzai.DialogueOptions{
  UserID:        &#x22;user_123&#x22;,
  Messages:      messages,
  SceneGuidance: guidance,
})
if err != nil { panic(err) }

fmt.Println(&#x22;Agent A:&#x22;, turnA.Response)
fmt.Println(&#x22;Agent B:&#x22;, turnB.Response)`,
  },
]"
/>

***

## Core concepts [#core-concepts]

### Events [#events-1]

**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 [#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 [#full-api]

| Method                                                                                                             | Returns                | Description                                      |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------ |
| `triggerBackendEvent(agentId, opts)` · `trigger_backend_event(agent_id, ...)` · `TriggerEvent(ctx, agentID, opts)` | `TriggerEventResponse` | Fire a backend event and queue an agent reaction |
| `dialogue(agentId, opts)` · `dialogue(agent_id, ...)` · `Dialogue(ctx, agentID, opts)`                             | `DialogueResponse`     | Generate one turn of agent dialogue              |

**TriggerEventOptions / trigger\_backend\_event kwargs:**

| Field                                                         | Type                                                            | Required | Description                                   |
| ------------------------------------------------------------- | --------------------------------------------------------------- | -------- | --------------------------------------------- |
| `userId` / `user_id` / `UserID`                               | `string`                                                        | Yes      | The user this event belongs to                |
| `eventType` / `event_type` / `EventType`                      | `string`                                                        | Yes      | Free-form event name, e.g. `"level_up"`       |
| `eventDescription` / `event_description` / `EventDescription` | `string`                                                        | No       | Plain-English narration for the LLM           |
| `metadata` / `Metadata`                                       | `Record<string,string>` / `dict[str,str]` / `map[string]string` | No       | Structured string-only metadata               |
| `language` / `Language`                                       | `string`                                                        | No       | Locale override (e.g. `"ja"`)                 |
| `instanceId` / `instance_id` / `InstanceID`                   | `string`                                                        | No       | Instance scope                                |
| `messages` / `Messages`                                       | `ChatMessage[]`                                                 | No       | Recent conversation that triggered this event |

**DialogueOptions / dialogue kwargs:**

| Field                                                | Type            | Required | Description                              |
| ---------------------------------------------------- | --------------- | -------- | ---------------------------------------- |
| `userId` / `user_id` / `UserID`                      | `string`        | No       | User context for the agent               |
| `messages` / `Messages`                              | `ChatMessage[]` | No       | Full conversation history for this turn  |
| `sceneGuidance` / `scene_guidance` / `SceneGuidance` | `string`        | No       | Instruction scoping tone and constraints |
| `requestType` / `request_type` / `RequestType`       | `string`        | No       | Tag for analytics (e.g. `"eval_round"`)  |
| `instanceId` / `instance_id` / `InstanceID`          | `string`        | No       | Instance scope                           |

***

## Combines with other features [#combines-with-other-features]

### With [Proactive Messaging](./proactive-overview) — events as the dev-controlled push source [#with-proactive-messaging--events-as-the-dev-controlled-push-source]

[Proactive Messaging](./proactive-overview) 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.

```ts
// 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](./conversations) — Messages field grounds the event in context [#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.

```ts
// 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](./evaluation) — Dialogue as a scoring harness [#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.

```ts
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 [#tutorials]

* [Medication Reminders](./tutorial-medication-reminders) — end-to-end example using Schedule + TriggerEvent + Memory together
* [Scheduled Reminders walkthrough](./tutorial-scheduled-reminders) — covers cadence patterns that pair with events

***

## Next steps [#next-steps]

* [Proactive Messaging](./proactive-overview) — the three sources and delivery channels
* [Conversations](./conversations) — regular agent chat mechanics
* [Scheduled Reminders](./scheduled-reminders) — recurring cadence primitive
* [Evaluation](./evaluation) — scoring agent responses


---

# Generation

Source: https://sonz.ai/docs/en/generation

> Generate agent characters, bios, avatars, and seed memories; generate images during chat.



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 [#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 [#quickstart]

### Generate a character + create the agent [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk-...&#x22; });

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

console.log(agent.agent_id);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

client = Sonzai(api_key=&#x22;sk-...&#x22;)

agent = client.agents.generation.generate_and_create(
  name=&#x22;Luna&#x22;,
  description=&#x22;A cheerful and curious assistant who loves helping developers debug code.&#x22;,
  language=&#x22;en&#x22;,
)

print(agent.agent_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(&#x22;sk-...&#x22;)

agent, err := client.Agents.Generation.GenerateAndCreate(ctx, sonzai.GenerateAndCreateOptions{
  Name:        &#x22;Luna&#x22;,
  Description: &#x22;A cheerful and curious assistant who loves helping developers debug code.&#x22;,
  Language:    &#x22;en&#x22;,
})
fmt.Println(agent.AgentID)`,
  },
]"
/>

<Callout type="info" title="Idempotent">
  If an `agentId` is provided and the agent already exists, `generateAndCreate` updates the existing agent rather than creating a duplicate. Safe to call on every app startup.
</Callout>

### Generate an image in-chat [#generate-an-image-in-chat]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const image = await client.agents.image.generate(&#x22;agent-id&#x22;, {
prompt: &#x22;A serene mountain landscape at sunset&#x22;,
});

console.log(image.url);          // public CDN URL
console.log(image.generationTimeMs);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `image = client.agents.image.generate(
  &#x22;agent-id&#x22;,
  prompt=&#x22;A serene mountain landscape at sunset&#x22;,
)

print(image.url)
print(image.generation_time_ms)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `image, err := client.Agents.Image.Generate(ctx, &#x22;agent-id&#x22;,
  sonzai.ImageGenerateOptions{
      Prompt: &#x22;A serene mountain landscape at sunset&#x22;,
  },
)
fmt.Println(image.URL)
fmt.Println(image.GenerationTimeMs)`,
  },
]"
/>

## Capabilities — image, music, and video generation [#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`.

| Field             | Type                | Description                                        |
| ----------------- | ------------------- | -------------------------------------------------- |
| `imageGeneration` | `boolean`           | Whether image generation is enabled for this agent |
| `imageUnlockedAt` | `string (ISO 8601)` | When image generation was granted                  |
| `musicGeneration` | `boolean`           | Whether music/audio generation is enabled          |
| `musicUnlockedAt` | `string (ISO 8601)` | When music generation was granted                  |
| `videoGeneration` | `boolean`           | Whether video generation is enabled                |
| `videoUnlockedAt` | `string (ISO 8601)` | When video generation was granted                  |

`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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Read current media capability flags
const caps = await client.agents.getCapabilities(&#x22;agent-id&#x22;);
console.log(caps.imageGeneration);  // true | false
console.log(caps.imageUnlockedAt);  // &#x22;2024-11-01T00:00:00Z&#x22;
console.log(caps.musicGeneration);  // true | false
console.log(caps.videoGeneration);  // true | false

// Enable image generation (if your plan allows it)
await client.agents.updateCapabilities(&#x22;agent-id&#x22;, { imageGeneration: true });`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Read current media capability flags
caps = client.agents.get_capabilities(&#x22;agent-id&#x22;)
print(caps.image_generation)   # True | False
print(caps.image_unlocked_at)  # datetime | None
print(caps.music_generation)   # True | False
print(caps.video_generation)   # True | False

# Enable image generation (if your plan allows it)
client.agents.update_capabilities(&#x22;agent-id&#x22;, image_generation=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Read current media capability flags
caps, _ := client.Agents.GetCapabilities(ctx, &#x22;agent-id&#x22;)
fmt.Println(caps.ImageGeneration)  // true | false
fmt.Println(caps.ImageUnlockedAt)  // &#x22;2024-11-01T00:00:00Z&#x22;
fmt.Println(caps.MusicGeneration)  // true | false
fmt.Println(caps.VideoGeneration)  // true | false

// Enable image generation (if your plan allows it)
_, _ = client.Agents.UpdateCapabilities(ctx, &#x22;agent-id&#x22;, sonzai.UpdateCapabilitiesOptions{
  ImageGeneration: sonzai.Bool(true),
})`,
  },
]"
/>

## Core concepts [#core-concepts]

### Character generation [#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.

```go
// 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 [#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 [#full-api]

| Method                                           | Returns                        | Description                                                     |
| ------------------------------------------------ | ------------------------------ | --------------------------------------------------------------- |
| `generation.generateAndCreate(opts)`             | `GenerateAndCreateResponse`    | Generate character + create agent in one idempotent call        |
| `generation.generateCharacter(opts)`             | `GenerateCharacterResponse`    | Generate character profile without creating the agent           |
| `generation.generateBio(agentID, opts)`          | `GenerateBioResponse`          | Generate or regenerate bio for an existing agent                |
| `generation.generateSeedMemories(agentID, opts)` | `GenerateSeedMemoriesResponse` | Generate LLM-authored backstory memories                        |
| `generation.seedMemories(agentID, opts)`         | `SeedMemoriesResponse`         | Bulk-import pre-authored memories into the agent's memory store |
| `generation.regenerateAvatar(agentID, opts)`     | `RegenerateAvatarResponse`     | Regenerate the agent's avatar image                             |
| `image.generate(agentID, opts)`                  | `ImageGenerateResponse`        | Generate an image from a prompt, scoped to the agent            |

## Combines with other features [#combines-with-other-features]

### With [Personality](./personality) — character generation sets initial Big5 [#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.

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

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: &#x22;Atlas&#x22;,
big5: profile.big5,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `profile = client.agents.generation.generate_character(
  name=&#x22;Atlas&#x22;,
  description=&#x22;A stoic, wise mentor who speaks in metaphors and values patience above all.&#x22;,
  fields=[&#x22;big5&#x22;, &#x22;dimensions&#x22;, &#x22;preferences&#x22;, &#x22;behaviors&#x22;],
)

print(profile.big5)
# {'openness': 0.72, 'conscientiousness': 0.85, 'extraversion': 0.35,
#  'agreeableness': 0.63, 'neuroticism': 0.22}

agent = client.agents.create(
  name=&#x22;Atlas&#x22;,
  big5=profile.big5,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `profile, err := client.Agents.Generation.GenerateCharacter(ctx, sonzai.GenerateCharacterOptions{
  Name:        &#x22;Atlas&#x22;,
  Description: &#x22;A stoic, wise mentor who speaks in metaphors and values patience above all.&#x22;,
  Fields:      []string{&#x22;big5&#x22;, &#x22;dimensions&#x22;, &#x22;preferences&#x22;, &#x22;behaviors&#x22;},
})

fmt.Println(profile.Big5)
// &{Openness:0.72 Conscientiousness:0.85 Extraversion:0.35 Agreeableness:0.63 Neuroticism:0.22}

agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  Name: &#x22;Atlas&#x22;,
  Big5: profile.Big5,
})`,
  },
]"
/>

### With [Memory](./memory) — seed memories plant backstory [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Step 1: generate backstory memories from personality context
const generated = await client.agents.generation.generateSeedMemories(&#x22;agent-id&#x22;, {
agentName: &#x22;Luna&#x22;,
trueInterests: [&#x22;astronomy&#x22;, &#x22;poetry&#x22;, &#x22;hiking&#x22;],
trueDislikes: [&#x22;loud noises&#x22;, &#x22;dishonesty&#x22;],
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(&#x22;agent-id&#x22;, {
userId: &#x22;user-123&#x22;,
memories: generated.memories,
});

// Step 3: verify they appear in memory
const stored = await client.agents.memory.list(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
console.log(stored);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Step 1: generate backstory memories
generated = client.agents.generation.generate_seed_memories(
  &#x22;agent-id&#x22;,
  agent_name=&#x22;Luna&#x22;,
  true_interests=[&#x22;astronomy&#x22;, &#x22;poetry&#x22;, &#x22;hiking&#x22;],
  true_dislikes=[&#x22;loud noises&#x22;, &#x22;dishonesty&#x22;],
  generate_origin_story=True,
  generate_personalized_memories=True,
)

print(f&#x22;Generated {len(generated.memories)} memories&#x22;)

# Step 2: store them
client.agents.generation.seed_memories(
  &#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  memories=generated.memories,
)

# Step 3: verify
stored = client.agents.memory.list(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
print(stored)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Step 1: generate backstory memories
generated, err := client.Agents.Generation.GenerateSeedMemories(ctx, &#x22;agent-id&#x22;,
  sonzai.GenerateSeedMemoriesOptions{
      AgentName:                    &#x22;Luna&#x22;,
      TrueInterests:               []string{&#x22;astronomy&#x22;, &#x22;poetry&#x22;, &#x22;hiking&#x22;},
      TrueDislikes:                 []string{&#x22;loud noises&#x22;, &#x22;dishonesty&#x22;},
      GenerateOriginStory:          true,
      GeneratePersonalizedMemories: true,
  },
)
fmt.Println(len(generated.Memories), &#x22;memories generated&#x22;)

// Step 2: store them
_, err = client.Agents.Generation.SeedMemories(ctx, &#x22;agent-id&#x22;,
  sonzai.SeedMemoriesOptions{
      UserID:   &#x22;user-123&#x22;,
      Memories: generated.Memories,
  },
)

// Step 3: verify
stored, err := client.Agents.Memory.List(ctx, &#x22;agent-id&#x22;,
  &sonzai.MemoryListOptions{UserID: &#x22;user-123&#x22;},
)
fmt.Println(stored)`,
  },
]"
/>

### With [Conversations](./conversations) — image generation as a chat capability [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Inside a chat turn handler
const response = await client.agents.chat({
agent: &#x22;agent-id&#x22;,
userId: &#x22;user-123&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Draw me a cozy forest cabin at night.&#x22; }],
language: &#x22;en&#x22;,
});

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

// Render both in your UI
renderChatBubble(response.content);
renderImage(image.url);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `response = client.agents.chat(
  agent_id=&#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Draw me a cozy forest cabin at night.&#x22;}],
  language=&#x22;en&#x22;,
)

image = client.agents.image.generate(
  &#x22;agent-id&#x22;,
  prompt=&#x22;A cozy forest cabin at night, warm light through windows, snow falling&#x22;,
)

render_chat_bubble(response.content)
render_image(image.url)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `resp, err := client.Agents.Chat(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  UserID:  &#x22;user-123&#x22;,
  Messages: []sonzai.Message{
      {Role: &#x22;user&#x22;, Content: &#x22;Draw me a cozy forest cabin at night.&#x22;},
  },
  Language: &#x22;en&#x22;,
})

image, err := client.Agents.Image.Generate(ctx, &#x22;agent-id&#x22;,
  sonzai.ImageGenerateOptions{
      Prompt: &#x22;A cozy forest cabin at night, warm light through windows, snow falling&#x22;,
  },
)

renderChatBubble(resp.Content)
renderImage(image.URL)`,
  },
]"
/>

## In Practice [#in-practice]

  

  

  
    **Generation is a one-off setup tool.** Define your agent once via `generateAndCreate` or `create`, pin the Big5 config in your environment, and don't regenerate in production. Predictability matters more than novelty.

    **Version the generated profile.** Store the exact personality config in production at any point in time so compliance can replay behavior during audits.

    **Don't expose generation to end-users.** End-customers should never be able to regenerate an enterprise agent's personality — that opens brand-voice risk.

    **Image generation is opt-in per integration.** Only enable `image.generate` in workflows where you have reviewed and approved the output pipeline. Apply content filters via `negative_prompt` to enforce brand safety.
  

## Tutorials [#tutorials]

* [Tutorial: Seed memories from scratch](/docs/en/guides/tutorials/tutorial-memory)

## Next steps [#next-steps]

* [Personality](./personality) — understand the Big5 profile that generation produces
* [Memory](./memory) — how seed memories integrate with the live memory system
* [Conversations](./conversations) — wiring image generation into a chat turn


---

# Sonzai Relationship Layer

Source: https://sonz.ai/docs/en/home

> Persistent memory, personality, and context for AI agents — whether you're building an assistant, a character, or an enterprise workflow agent.



Sonzai is the **Relationship 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 [#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).

<InstallTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    language: &#x22;bash&#x22;,
    subTabs: [
      { id: &#x22;pip&#x22;, label: &#x22;pip&#x22;, code: `pip install sonzai` },
      { id: &#x22;uv&#x22;, label: &#x22;uv&#x22;, code: `uv add sonzai` },
      { id: &#x22;poetry&#x22;, label: &#x22;poetry&#x22;, code: `poetry add sonzai` },
      { id: &#x22;pipenv&#x22;, label: &#x22;pipenv&#x22;, code: `pipenv install sonzai` },
    ],
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript / JavaScript&#x22;,
    language: &#x22;bash&#x22;,
    subTabs: [
      { id: &#x22;npm&#x22;, label: &#x22;npm&#x22;, code: `npm install @sonzai-labs/agents` },
      { id: &#x22;bun&#x22;, label: &#x22;bun&#x22;, code: `bun add @sonzai-labs/agents` },
      { id: &#x22;pnpm&#x22;, label: &#x22;pnpm&#x22;, code: `pnpm add @sonzai-labs/agents` },
      { id: &#x22;yarn&#x22;, label: &#x22;yarn&#x22;, code: `yarn add @sonzai-labs/agents` },
      {
        id: &#x22;deno&#x22;,
        label: &#x22;Deno&#x22;,
        language: &#x22;ts&#x22;,
        code: `import { Sonzai } from &#x22;npm:@sonzai-labs/agents&#x22;;`,
      },
    ],
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    language: &#x22;bash&#x22;,
    code: `go get github.com/sonz-ai/sonzai-go@latest`,
  },
  {
    id: &#x22;rest&#x22;,
    label: &#x22;REST&#x22;,
    language: &#x22;bash&#x22;,
    code: `curl https://api.sonz.ai/v1/agents \\
-H &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{ &#x22;name&#x22;: &#x22;Luna&#x22;, &#x22;language&#x22;: &#x22;en&#x22; }'`,
  },
  {
    id: &#x22;mcp&#x22;,
    label: &#x22;MCP&#x22;,
    subTabs: [
      {
        id: &#x22;claude-code&#x22;,
        label: &#x22;Claude Code&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Single command — registers the hosted MCP server with Claude Code:
claude mcp add --transport http sonzai \\
https://api.sonz.ai/mcp/memory/AGENT_ID \\
--header &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22;`,
      },
      {
        id: &#x22;cursor&#x22;,
        label: &#x22;Cursor / VS Code&#x22;,
        language: &#x22;json&#x22;,
        code: `// ~/.cursor/mcp.json (Cursor) — VS Code uses .vscode/mcp.json with the
// top-level key &#x22;servers&#x22; instead of &#x22;mcpServers&#x22;.
{
&#x22;mcpServers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;type&#x22;: &#x22;http&#x22;,
    &#x22;url&#x22;: &#x22;https://api.sonz.ai/mcp/memory/AGENT_ID&#x22;,
    &#x22;headers&#x22;: { &#x22;Authorization&#x22;: &#x22;Bearer YOUR_API_KEY&#x22; }
  }
}
}`,
      },
      {
        id: &#x22;chatgpt&#x22;,
        label: &#x22;ChatGPT&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Plus / Pro / Business / Enterprise / Edu (Developer Mode beta).
# 1. Settings → Connectors → Advanced → Developer Mode ON
# 2. Add custom connector:
#      URL:    https://api.sonz.ai/mcp/memory/AGENT_ID
#      Header: Authorization: Bearer YOUR_API_KEY`,
      },
    ],
  },
  {
    id: &#x22;openclaw&#x22;,
    label: &#x22;OpenClaw&#x22;,
    subTabs: [
      {
        id: &#x22;one-shot&#x22;,
        label: &#x22;One-shot&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Prereq — install OpenClaw itself first (see openclaw.ai):
#   npm install -g openclaw@latest
#   openclaw onboard --install-daemon

# Then register the Sonzai context engine in one command:
npx --yes @sonzai-labs/openclaw-context install

# Probes Sonzai backend health, runs 'openclaw plugins install',
# launches the interactive wizard, writes ~/.openclaw/openclaw.json.`,
      },
      {
        id: &#x22;manual&#x22;,
        label: &#x22;Manual&#x22;,
        language: &#x22;bash&#x22;,
        code: `# 1. Install the plugin via the OpenClaw CLI:
openclaw plugins install @sonzai-labs/openclaw-context

# 2. Run the Sonzai setup wizard (writes openclaw.json with API key + agent ID):
npx @sonzai-labs/openclaw-context setup

# 3. Restart the gateway:
openclaw gateway restart`,
      },
      {
        id: &#x22;config&#x22;,
        label: &#x22;openclaw.json&#x22;,
        language: &#x22;json&#x22;,
        code: `// ~/.openclaw/openclaw.json — flip the contextEngine slot to &#x22;sonzai&#x22;.
// (The wizard writes this for you; included here for hand-edits and CI.)
{
&#x22;plugins&#x22;: {
  &#x22;slots&#x22;: {
    &#x22;contextEngine&#x22;: &#x22;sonzai&#x22;
  },
  &#x22;entries&#x22;: {
    &#x22;sonzai&#x22;: {
      &#x22;enabled&#x22;: true,
      &#x22;apiKey&#x22;: &#x22;sk-your-api-key&#x22;,
      &#x22;agentId&#x22;: &#x22;your-agent-uuid&#x22;
    }
  }
}
}`,
      },
    ],
  },
  {
    id: &#x22;hermes&#x22;,
    label: &#x22;Hermes&#x22;,
    subTabs: [
      {
        id: &#x22;one-shot&#x22;,
        label: &#x22;One-shot&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Prereq — Python 3.11+ and Hermes Agent installed:
#   pip install hermes-agent

# Install the Sonzai plugin pair (MemoryProvider + ContextEngine):
pip install sonzai-hermes
sonzai-hermes install   # stages both plugins into Hermes' discovery paths
sonzai-hermes setup     # provisions a 14-day trial if no SONZAI_API_KEY,
                      # writes the key into $HERMES_HOME/.env`,
      },
      {
        id: &#x22;config&#x22;,
        label: &#x22;config.yaml&#x22;,
        language: &#x22;yaml&#x22;,
        code: `# ~/.hermes/config.yaml — point both Hermes slots at &#x22;sonzai&#x22;.
memory:
provider: sonzai
context:
engine: sonzai`,
      },
      {
        id: &#x22;byok&#x22;,
        label: &#x22;BYOK&#x22;,
        language: &#x22;bash&#x22;,
        code: `# If any of these env vars are set when Hermes starts, sonzai-hermes
# registers them with the Sonzai platform automatically — your provider
# account gets billed for tokens, you pay Sonzai only the 25% service fee.
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...     # or GOOGLE_API_KEY
export XAI_API_KEY=...
export OPENROUTER_API_KEY=...

# Override per provider with SONZAI_BYOK_<PROVIDER>_KEY (takes precedence).
# Set SONZAI_PROJECT_ID if your tenant has multiple projects.`,
      },
    ],
  },
]"
/>

* **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](https://openclaw.ai) ([Getting Started](https://docs.openclaw.ai/start/getting-started)).
* **Hermes Agent** itself is required for the Hermes path — install it from [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com).
* Full guides: [MCP](/docs/en/guides/mcp-integration) · [OpenClaw](/docs/en/guides/openclaw-integration) · [Hermes](/docs/en/connect-hermes) · [REST API Reference](/docs/en/reference/api-reference).

Need an API key first? Create a project at [platform.sonz.ai](https://platform.sonz.ai/dashboard/projects), then jump to the [Quickstart](/docs/en/guides/getting-started) for the full walkthrough.

## What are you building? [#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.

<TrackPicker />

## Core Capabilities [#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.

<Cards>
  <Card href="/docs/en/memory" title="Memory & Context" description="Persistent memory across sessions — facts, events, commitments, and summaries. Seed, search, and browse via SDK. [All audiences]" />

  <Card href="/docs/en/personality" title="Personality" description="Big Five (OCEAN) model with behavioral dimensions, interaction preferences, and trait evolution. [All audiences]" />

  <Card href="/docs/en/emotions" title="Emotions & Mood" description="Four mood dimensions that shift with conversations and events. [Best for Companions · safe to ignore for task agents]" />

  <Card href="/docs/en/conversations" title="Conversations" description="Real-time streaming chat. Memory, mood, and personality update automatically after each turn. [All audiences]" />

  <Card href="/docs/en/knowledge-base" title="Knowledge Base" description="Upload documents or push structured data to build a knowledge graph agents search during chat. [All audiences]" />

  <Card href="/docs/en/custom-tools" title="Custom Tools" description="Register tools the LLM can invoke during chat — built-in capabilities, persistent agent tools, and ephemeral session tools. [All audiences]" />

  <Card href="/docs/en/instances" title="Multi-Instance" description="One agent, many isolated contexts — per-user, per-workspace, per-environment. [Best for Employees & Enterprise]" />

  <Card href="/docs/en/webhooks" title="Webhooks & Notifications" description="Real-time event callbacks and proactive agent messages. [Best for Enterprise]" />

  <Card href="/docs/en/knowledge-base" title="Proactive Wakeups" description="Agents schedule check-ins based on relationship context, tasks, or SLA. [All audiences]" />

  <Card href="/docs/en/voice" title="Voice" description="Text-to-speech, speech-to-text, and real-time duplex voice streaming. [Best for Companions & Enterprise support]" />

  <Card href="/docs/en/generation" title="Agent Generation" description="Create agents from natural-language descriptions. Auto-generate personality, bio, and seed memories. [All audiences]" />

  <Card href="/docs/en/guides/evaluation" title="Evaluation" description="Score agent quality with rubrics, run multi-turn simulations, benchmark consistency. [All audiences]" />

  <Card href="/docs/en/self-improvement" title="How Agents Improve Over Time" description="The complete picture of automatic learning: memory decay, consolidation, dedup, retrieval policy learning, personality drift, breakthroughs, and the shadow-rollout system. [All audiences]" />

  <Card href="/docs/en/models/byok" title="BYOK — Bring Your Own Key" description="Run on Sonzai's stack but bill provider tokens to your own OpenAI / Gemini / xAI / OpenRouter account. Per-project, encrypted at rest. [All audiences]" />
</Cards>

## Integration [#integration]

<Cards>
  <Card href="/docs/en/guides/getting-started" title="Quickstart" description="Create a project, get an API key, spin up an agent, and start chatting in under 10 minutes." />

  <Card href="/docs/en/architecture" title="Architecture" description="How the platform, orchestrator, and your backend fit together." />

  <Card href="/docs/en/guides/integration" title="Integration Guide" description="End-to-end SDK integration for TypeScript, Python, and Go." />

  <Card href="/docs/en/reference" title="API Reference" description="Full REST API reference with every endpoint and schema." />

  <Card href="/docs/en/guides/mcp-integration" title="MCP Integration" description="Connect Claude Desktop, Cursor, or any MCP-compatible client to Sonzai." />

  <Card href="/docs/en/guides/openclaw-integration" title="OpenClaw Plugin" description="Drop-in plugin for the OpenClaw context engine." />

  <Card href="/docs/en/connect-hermes" title="Hermes Plugin" description="Drop-in MemoryProvider + ContextEngine pair for Hermes Agent." />
</Cards>

## For AI Agents [#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.

<LLMAccessCards />

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 [#how-it-fits-into-your-application]

Your backend handles business logic and user sessions. The Relationship 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 →](/docs/en/guides/integration)


---

# Instances

Source: https://sonz.ai/docs/en/instances

> Deploy the same agent into multiple isolated contexts — workspaces, departments, regions, or tenants — each with their own independent state.



**Instances** let you run a single agent across many isolated deployment contexts without cloning the agent itself. The shared parts — [personality](./personality), [memory](./memory), tools, voice — stay unified, while [custom states](./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 agent runs in parallel contexts that must not share runtime state.

## What is an Instance? [#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.

<Diagram>
  {`
    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`}
</Diagram>

<Callout type="info" title="Default Instance">
  Every agent has a default instance. If you don't pass `instanceId` to chat or state operations, the default instance is used. You only need multiple instances if you run the same agent in parallel isolated contexts.
</Callout>

## List Instances [#list-instances]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk-...&#x22; });

const instances = await client.agents.instances.list(&#x22;agent-id&#x22;);

for (const inst of instances) {
console.log(inst.instanceId, inst.name, inst.isDefault, inst.status);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

client = Sonzai(api_key=&#x22;sk-...&#x22;)

instances = client.agents.instances.list(&#x22;agent-id&#x22;)

for inst in instances:
  print(inst.instance_id, inst.name, inst.is_default, inst.status)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(&#x22;sk-...&#x22;)

instances, err := client.Agents.Instances.List(ctx, &#x22;agent-id&#x22;)

for _, inst := range instances {
  fmt.Println(inst.InstanceID, inst.Name, inst.IsDefault, inst.Status)
}`,
  },
]"
/>

## Create an Instance [#create-an-instance]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const instance = await client.agents.instances.create(&#x22;agent-id&#x22;, {
name: &#x22;Workspace US-East&#x22;,
description: &#x22;US-East production workspace&#x22;,
});

console.log(instance.instance_id); // store this`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `instance = client.agents.instances.create(
  &#x22;agent-id&#x22;,
  name=&#x22;Workspace US-East&#x22;,
  description=&#x22;US-East production workspace&#x22;,
)

print(instance.instance_id)  # store this`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `instance, err := client.Agents.Instances.Create(ctx, &#x22;agent-id&#x22;,
  &#x22;Workspace US-East&#x22;,
  &#x22;US-East production workspace&#x22;,
)

fmt.Println(instance.InstanceID) // store this`,
  },
]"
/>

## Get an Instance [#get-an-instance]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const instance = await client.agents.instances.get(
&#x22;agent-id&#x22;,
&#x22;instance-id&#x22;,
);

console.log(instance.name, instance.status, instance.isDefault);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `instance = client.agents.instances.get(&#x22;agent-id&#x22;, &#x22;instance-id&#x22;)

print(instance.name, instance.status, instance.is_default)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `instance, err := client.Agents.Instances.Get(ctx, &#x22;agent-id&#x22;, &#x22;instance-id&#x22;)

fmt.Println(instance.Name, instance.Status, instance.IsDefault)`,
  },
]"
/>

## Update an Instance [#update-an-instance]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.instances.update(&#x22;agent-id&#x22;, &#x22;instance-id&#x22;, {
name: &#x22;Workspace US-East (Production)&#x22;,
status: &#x22;active&#x22;,    // &#x22;active&#x22; | &#x22;inactive&#x22;
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.instances.update(
  &#x22;agent-id&#x22;, &#x22;instance-id&#x22;,
  name=&#x22;Workspace US-East (Production)&#x22;,
  status=&#x22;active&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.Instances.Update(ctx, &#x22;agent-id&#x22;, &#x22;instance-id&#x22;,
  sonzai.UpdateInstanceOptions{
      Name:   &#x22;Workspace US-East (Production)&#x22;,
      Status: &#x22;active&#x22;,
  },
)`,
  },
]"
/>

## Reset an Instance [#reset-an-instance]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Wipes all custom states scoped to this instance
await client.agents.instances.reset(&#x22;agent-id&#x22;, &#x22;instance-id&#x22;);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.instances.reset(&#x22;agent-id&#x22;, &#x22;instance-id&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.Instances.Reset(ctx, &#x22;agent-id&#x22;, &#x22;instance-id&#x22;)`,
  },
]"
/>

## Delete an Instance [#delete-an-instance]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.instances.delete(&#x22;agent-id&#x22;, &#x22;instance-id&#x22;);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.instances.delete(&#x22;agent-id&#x22;, &#x22;instance-id&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.Instances.Delete(ctx, &#x22;agent-id&#x22;, &#x22;instance-id&#x22;)`,
  },
]"
/>

## Using Instances in Chat [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.chatStream({
agent: &#x22;agent-id&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;What's the current status?&#x22; }],
userId:     &#x22;user-123&#x22;,
instanceId: &#x22;ws-us-east&#x22;,      // scopes state reads to this instance
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.chat(
  agent=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What's the current status?&#x22;}],
  user_id=&#x22;user-123&#x22;,
  instance_id=&#x22;ws-us-east&#x22;,
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages:   []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;What's the current status?&#x22;}},
      UserID:     &#x22;user-123&#x22;,
      InstanceID: &#x22;ws-us-east&#x22;,
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  return nil
})`,
  },
]"
/>

## Instance Data Model [#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

Source: https://sonz.ai/docs/en/inventory

> Per-user structured items the agent can read and reason about — medications, holdings, pets, goals — stored against a shared KB schema.



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](./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 [#what-you-can-build-with-it]

* **Medication adherence** — track each drug, dose, and schedule per user (pairs with [Scheduled Reminders](./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 [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
item_type: &#x22;medication&#x22;,
label: &#x22;Metformin&#x22;,
description: &#x22;Metformin 500mg — biguanide for blood sugar control&#x22;,
properties: {
  dose_mg: 500,
  frequency: &#x22;twice daily&#x22;,
  with_food: true,
},
});

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

// Alternative: explicit-action route (still supported for backward compat)
// await client.agents.inventory.update(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, { action: &#x22;add&#x22;, item_type: &#x22;medication&#x22;, ... });`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

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

print(result.inventory_item_id)  # &#x22;inv_01HX...&#x22; (preferred)
print(result.fact_id)            # &#x22;fact_01HX...&#x22; (backward compat alias)
print(result.status)             # &#x22;added&#x22; | &#x22;disambiguation_needed&#x22;

# Alternative: explicit-action route (still supported for backward compat)
# client.agents.inventory.update(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, action=&#x22;add&#x22;, item_type=&#x22;medication&#x22;, ...)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()

  // Preferred: dedicated create route — no Action field needed
  result, err := client.Agents.Inventory.Create(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
      sonzai.CreateItemOptions{
          ItemType:    &#x22;medication&#x22;,
          Label:       &#x22;Metformin&#x22;,
          Description: &#x22;Metformin 500mg — biguanide for blood sugar control&#x22;,
          Properties: map[string]interface{}{
              &#x22;dose_mg&#x22;:   500,
              &#x22;frequency&#x22;: &#x22;twice daily&#x22;,
              &#x22;with_food&#x22;: true,
          },
      },
  )
  if err != nil {
      panic(err)
  }
  fmt.Println(result.InventoryItemID) // &#x22;inv_01HX...&#x22; (preferred)
  fmt.Println(result.FactID)          // &#x22;fact_01HX...&#x22; (backward compat alias)
  fmt.Println(result.Status)          // &#x22;added&#x22; | &#x22;disambiguation_needed&#x22;

  // Alternative: explicit-action route (still supported for backward compat)
  // client.Agents.Inventory.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, sonzai.InventoryUpdateOptions{Action: &#x22;add&#x22;, ...})
}`,
  },
]"
/>

<Callout type="info" title="KB resolution on add">
  When `action` is `"add"`, the platform performs a natural-language search of the KB using `description`. If exactly one node matches, the item is linked automatically and the response includes `kb_resolution`. If there are multiple close matches, the response returns `status: "disambiguation_needed"` and a `candidates` list — surface these to the user or pick the best `kb_node_id` and re-submit.
</Callout>

<Callout type="info" title="label vs description">
  `label` is an optional short display name shown in dashboards and agent tool calls (e.g. `"Metformin"`). `description` is the longer text the platform uses for KB natural-language search (e.g. `"Metformin 500mg — biguanide for blood sugar control"`). If `label` is omitted, the platform falls back to the first segment of `description` for display purposes.
</Callout>

## Core concepts [#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](./knowledge-base) 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 [#full-api]

| Method                                                                                                                                          | Description                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `inventory.create(agentId, userId, { item_type, label?, description?, kb_node_id?, properties?, project_id? })`                                 | **Preferred add path.** Dedicated create endpoint — no `action` field needed. Returns `InventoryUpdateResponse` with `inventory_item_id`. |
| `inventory.update(agentId, userId, { action, item_type, label?, description?, kb_node_id?, properties?, project_id? })`                         | Explicit-action path. `action` is `"add"`, `"update"`, or `"remove"`. Use when you route all three write types through one call site.     |
| `inventory.query(agentId, userId, { mode, item_type?, project_id?, filters?, sort_by?, sort_order?, aggregations?, limit?, offset?, cursor? })` | Query items in list, value, or aggregate mode.                                                                                            |
| `inventory.directUpdate(agentId, userId, factId, { properties })`                                                                               | Update an item's properties by `fact_id`, bypassing KB re-resolution.                                                                     |
| `inventory.directDelete(agentId, userId, factId)`                                                                                               | Delete an item by `fact_id`.                                                                                                              |
| `inventory.batchImport(agentId, userId, { items: [{ item_type, description?, kb_node_id?, properties? }], project_id? })`                       | Import up to 1,000 items in one call.                                                                                                     |

### Response shape [#response-shape]

`InventoryUpdateResponse`:

```json
{
  "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 [#combines-with-other-features]

### With [Knowledge Base](./knowledge-base) — schemas shape items [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. Define the schema in the KB once
await client.knowledge.createSchema(&#x22;proj_abc123&#x22;, {
entity_type: &#x22;medication&#x22;,
fields: [
  { name: &#x22;dose_mg&#x22;,    type: &#x22;number&#x22;, required: true },
  { name: &#x22;frequency&#x22;,  type: &#x22;string&#x22;, required: true },
  { name: &#x22;with_food&#x22;,  type: &#x22;boolean&#x22;, required: false },
],
});

// 2. Inventory writes for item_type &#x22;medication&#x22; are now validated
await client.agents.inventory.update(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
action: &#x22;add&#x22;,
item_type: &#x22;medication&#x22;,   // <-- resolves to the schema above
description: &#x22;Metformin 500mg&#x22;,
properties: { dose_mg: 500, frequency: &#x22;twice daily&#x22;, with_food: true },
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Define the schema in the KB once
client.knowledge.create_schema(&#x22;proj_abc123&#x22;,
  entity_type=&#x22;medication&#x22;,
  fields=[
      {&#x22;name&#x22;: &#x22;dose_mg&#x22;,   &#x22;type&#x22;: &#x22;number&#x22;,  &#x22;required&#x22;: True},
      {&#x22;name&#x22;: &#x22;frequency&#x22;, &#x22;type&#x22;: &#x22;string&#x22;,  &#x22;required&#x22;: True},
      {&#x22;name&#x22;: &#x22;with_food&#x22;, &#x22;type&#x22;: &#x22;boolean&#x22;, &#x22;required&#x22;: False},
  ],
)

# 2. Inventory writes for item_type &#x22;medication&#x22; are now validated
client.agents.inventory.update(
  &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  action=&#x22;add&#x22;,
  item_type=&#x22;medication&#x22;,
  description=&#x22;Metformin 500mg&#x22;,
  properties={&#x22;dose_mg&#x22;: 500, &#x22;frequency&#x22;: &#x22;twice daily&#x22;, &#x22;with_food&#x22;: True},
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. Define the schema in the KB once
client.Knowledge.CreateSchema(ctx, &#x22;proj_abc123&#x22;, sonzai.CreateSchemaOptions{
  EntityType: &#x22;medication&#x22;,
  Fields: []sonzai.KBSchemaField{
      {Name: &#x22;dose_mg&#x22;,   Type: &#x22;number&#x22;,  Required: true},
      {Name: &#x22;frequency&#x22;, Type: &#x22;string&#x22;,  Required: true},
      {Name: &#x22;with_food&#x22;, Type: &#x22;boolean&#x22;},
  },
})

// 2. Inventory writes for item_type &#x22;medication&#x22; are now validated
client.Agents.Inventory.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.InventoryUpdateOptions{
      Action:      &#x22;add&#x22;,
      ItemType:    &#x22;medication&#x22;,
      Description: &#x22;Metformin 500mg&#x22;,
      Properties:  map[string]interface{}{&#x22;dose_mg&#x22;: 500, &#x22;frequency&#x22;: &#x22;twice daily&#x22;, &#x22;with_food&#x22;: true},
  },
)`,
  },
]"
/>

### With [Scheduled Reminders](./scheduled-reminders) — live data at fire time [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Add the item first
const { fact_id } = await client.agents.inventory.update(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
action: &#x22;add&#x22;,
item_type: &#x22;medication&#x22;,
description: &#x22;Metformin 500mg&#x22;,
properties: { dose_mg: 500, frequency: &#x22;twice daily&#x22; },
});

// Reference it in a schedule — agent reads live properties at each fire
await client.schedules.create(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;08:00&#x22;, &#x22;20:00&#x22;] },
  timezone: &#x22;America/New_York&#x22;,
},
intent: &#x22;remind the user to take their medication&#x22;,
inventory_item_id: fact_id,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Add the item first
result = client.agents.inventory.update(
  &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  action=&#x22;add&#x22;,
  item_type=&#x22;medication&#x22;,
  description=&#x22;Metformin 500mg&#x22;,
  properties={&#x22;dose_mg&#x22;: 500, &#x22;frequency&#x22;: &#x22;twice daily&#x22;},
)

# Reference it in a schedule — agent reads live properties at each fire
client.schedules.create(
  &#x22;agent_abc&#x22;,
  &#x22;user_123&#x22;,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;08:00&#x22;, &#x22;20:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;America/New_York&#x22;,
  },
  intent=&#x22;remind the user to take their medication&#x22;,
  check_type=&#x22;reminder&#x22;,
  inventory_item_id=result.fact_id,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Add the item first
inv, _ := client.Agents.Inventory.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.InventoryUpdateOptions{
      Action:      &#x22;add&#x22;,
      ItemType:    &#x22;medication&#x22;,
      Description: &#x22;Metformin 500mg&#x22;,
      Properties:  map[string]interface{}{&#x22;dose_mg&#x22;: 500, &#x22;frequency&#x22;: &#x22;twice daily&#x22;},
  },
)

// Reference it in a schedule — agent reads live properties at each fire
client.Schedules.Create(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.CreateScheduleOptions{
      Cadence:         cadenceJSON,
      Intent:          &#x22;remind the user to take their medication&#x22;,
      InventoryItemID: inv.FactID,
  },
)`,
  },
]"
/>

### With [Memory](./memory) — inventory state in conversation context [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Agent answers from inventory mid-conversation
for await (const event of client.agents.chatStream(&#x22;agent_abc&#x22;, {
userId: &#x22;user_123&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;What medications am I on?&#x22; }],
})) {
// 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 ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Agent answers from inventory mid-conversation
for event in client.agents.chat(
  &#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What medications am I on?&#x22;}],
  stream=True,
):
  # The agent calls sonzai_inventory internally to fetch the user's items.
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Agent answers from inventory mid-conversation
err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent_abc&#x22;,
  ChatOptions: sonzai.ChatOptions{
      UserID: &#x22;user_123&#x22;,
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;What medications am I on?&#x22;},
      },
  },
}, func(event sonzai.ChatStreamEvent) error {
  // The agent calls sonzai_inventory internally to fetch the user's items.
  fmt.Print(event.Content())
  return nil
})`,
  },
]"
/>

## Tutorials [#tutorials]

* [Resource Inventory + Knowledge Base](./tutorial-inventory) — full walkthrough with schema setup, upsert, bulk import, and portfolio queries
* [Medication Reminders](./tutorial-medication-reminders) — worked example combining Inventory + Scheduled Reminders + Memory

## Next steps [#next-steps]

* [Knowledge Base](./knowledge-base) — the schema backbone that shapes inventory items
* [Scheduled Reminders](./scheduled-reminders) — live inventory data injection at fire time
* [Memory](./memory) — how inventory writes surface in chat context


---

# Knowledge Analytics

Source: https://sonz.ai/docs/en/knowledge-analytics

> Turn the Knowledge Base graph into a recommendation engine — rules rank nodes by user affinity, trend velocity, or conversion rate, all readable through a simple query-time API.



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 [#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 [#quickstart]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

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

// 2. Fetch top-5 recommendations for a user
const recs = await client.knowledge.getRecommendations(
projectId,
rule.rule_id,
&#x22;user_123&#x22;,   // 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: &#x22;user_123&#x22;,
target_node_id: recs.recommendations[0].target_id,
rule_id:        rule.rule_id,
converted:      true,
score_at_time:  recs.recommendations[0].score,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
project_id = &#x22;proj_abc123&#x22;

# 1. Create a recommendation rule
rule = client.knowledge.create_analytics_rule(
  project_id,
  rule_type=&#x22;recommendation&#x22;,
  name=&#x22;product-affinity&#x22;,
  config={&#x22;target_entity_type&#x22;: &#x22;product&#x22;, &#x22;scoring&#x22;: &#x22;affinity&#x22;},
  enabled=True,
  schedule=&#x22;0 * * * *&#x22;,  # recompute hourly
)

# 2. Fetch top-5 recommendations for a user
recs = client.knowledge.get_recommendations(
  project_id,
  rule_id=rule.rule_id,
  source_id=&#x22;user_123&#x22;,
  limit=5,
)

for rec in recs.recommendations:
  print(rec.target_id, rec.score)

# 3. Record that the user converted on the top result
client.knowledge.record_feedback(
  project_id,
  source_node_id=&#x22;user_123&#x22;,
  target_node_id=recs.recommendations[0].target_id,
  rule_id=rule.rule_id,
  converted=True,
  score_at_time=recs.recommendations[0].score,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()
  projectID := &#x22;proj_abc123&#x22;

  // 1. Create a recommendation rule
  rule, err := client.Knowledge.CreateAnalyticsRule(ctx, projectID,
      sonzai.CreateAnalyticsRuleOptions{
          RuleType: &#x22;recommendation&#x22;,
          Name:     &#x22;product-affinity&#x22;,
          Config:   map[string]any{&#x22;target_entity_type&#x22;: &#x22;product&#x22;, &#x22;scoring&#x22;: &#x22;affinity&#x22;},
          Enabled:  true,
          Schedule: &#x22;0 * * * *&#x22;,
      },
  )
  if err != nil {
      panic(err)
  }

  // 2. Fetch top-5 recommendations for a user
  recs, err := client.Knowledge.GetRecommendations(ctx, projectID, rule.RuleID, &#x22;user_123&#x22;, 5)
  if err != nil {
      panic(err)
  }

  for _, rec := range recs.Recommendations {
      fmt.Println(rec.TargetID, rec.Score)
  }

  // 3. Record that the user converted on the top result
  top := recs.Recommendations[0]
  err = client.Knowledge.RecordFeedback(ctx, projectID, sonzai.RecordFeedbackOptions{
      SourceNodeID: &#x22;user_123&#x22;,
      TargetNodeID: top.TargetID,
      RuleID:       rule.RuleID,
      Converted:    true,
      ScoreAtTime:  top.Score,
  })
  if err != nil {
      panic(err)
  }
}`,
  },
]"
/>

## Core concepts [#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 [#full-api]

| Method                                                                                                      | Returns                       | Description                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createAnalyticsRule(projectId, { rule_type, name, config, enabled, schedule? })`                           | `KBAnalyticsRule`             | Create a new analytics rule. `rule_type` is `"recommendation"` or `"trend"`.                                                                                                                                                                                                                                                        |
| `listAnalyticsRules(projectId)`                                                                             | `KBAnalyticsRuleListResponse` | List all analytics rules for a project.                                                                                                                                                                                                                                                                                             |
| `getAnalyticsRule(projectId, ruleId)`                                                                       | `KBAnalyticsRule`             | Fetch a single rule by ID.                                                                                                                                                                                                                                                                                                          |
| `updateAnalyticsRule(projectId, ruleId, { name?, config?, enabled, schedule? })`                            | `KBAnalyticsRule`             | Update rule properties.                                                                                                                                                                                                                                                                                                             |
| `deleteAnalyticsRule(projectId, ruleId)`                                                                    | `void`                        | Delete a rule permanently.                                                                                                                                                                                                                                                                                                          |
| `runAnalyticsRule(projectId, ruleId)`                                                                       | `void`                        | Trigger an immediate manual run of the rule.                                                                                                                                                                                                                                                                                        |
| `getRecommendations(projectId, ruleId, sourceId, limit?)`                                                   | `KBRecommendationsResponse`   | Fetch ranked recommendations for a source node. Returns `.recommendations` array of `{ target_id, target_type, score }`.                                                                                                                                                                                                            |
| `getTrends(projectId, nodeId)`                                                                              | `KBTrendsResponse`            | Get trend aggregations for a specific node across all windows. Returns `.trends` array of `{ node_id, rule_id, window, value, direction }`.                                                                                                                                                                                         |
| `getTrendRankings(projectId, ruleId, rankingType, window, limit?)`                                          | `KBTrendRankingsResponse`     | Get the global leaderboard for a trend rule. `window` is a duration string such as `"7d"` or `"24h"`. Returns `.rankings` array with `rank` and `score`.                                                                                                                                                                            |
| `getConversions(projectId, ruleId, segment?)`                                                               | `KBConversionsResponse`       | Fetch conversion statistics for a rule, optionally filtered by segment key. Returns `{ shown_count, conversion_count, conversion_rate }` per segment.                                                                                                                                                                               |
| `recordFeedback(projectId, { source_node_id, target_node_id, rule_id, converted, score_at_time, action? })` | `void`                        | Record whether a recommended node was acted on. `converted` is a boolean — `true` means the user engaged with the recommendation. `action` is an optional string enum: `"converted"`, `"dismissed"`, `"clicked"`, `"ignored"`. Passing `action: "converted"` also sets `converted: true` for backward-compatible aggregate queries. |
| `getStats(projectId)`                                                                                       | `KBStats`                     | General KB statistics (node counts, document counts, extraction tokens).                                                                                                                                                                                                                                                            |

<Callout type="info" title="Python keyword arguments">
  The Python SDK exposes `get_recommendations`, `get_trends`, `get_trend_rankings`, `get_conversions`, and `record_feedback` using keyword-only arguments after `project_id`. For example: `client.knowledge.get_recommendations(project_id, rule_id="...", source_id="...", limit=10)`.
</Callout>

## Combines with other features [#combines-with-other-features]

### With [Knowledge Base](./knowledge-base) — the graph is the substrate [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. Define a product schema in the KB
await client.knowledge.createSchema(projectId, {
entity_type: &#x22;product&#x22;,
fields: [
  { name: &#x22;price&#x22;,    type: &#x22;number&#x22;, required: true },
  { name: &#x22;category&#x22;, type: &#x22;string&#x22;, required: true },
  { name: &#x22;in_stock&#x22;, type: &#x22;boolean&#x22;, required: true },
],
});

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

// 3. Create a recommendation rule targeting the product entity type
const rule = await client.knowledge.createAnalyticsRule(projectId, {
rule_type: &#x22;recommendation&#x22;,
name:      &#x22;product-recs&#x22;,
config:    { target_entity_type: &#x22;product&#x22; },
enabled:   true,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Define a product schema in the KB
client.knowledge.create_schema(project_id,
  entity_type=&#x22;product&#x22;,
  fields=[
      {&#x22;name&#x22;: &#x22;price&#x22;,    &#x22;type&#x22;: &#x22;number&#x22;,  &#x22;required&#x22;: True},
      {&#x22;name&#x22;: &#x22;category&#x22;, &#x22;type&#x22;: &#x22;string&#x22;,  &#x22;required&#x22;: True},
      {&#x22;name&#x22;: &#x22;in_stock&#x22;, &#x22;type&#x22;: &#x22;boolean&#x22;, &#x22;required&#x22;: True},
  ],
)

# 2. Push some product nodes
client.knowledge.insert_facts(project_id,
  facts=[
      {&#x22;entity_type&#x22;: &#x22;product&#x22;, &#x22;label&#x22;: &#x22;Razer Blade 16&#x22;,       &#x22;properties&#x22;: {&#x22;price&#x22;: 2999, &#x22;category&#x22;: &#x22;laptop&#x22;, &#x22;in_stock&#x22;: True}},
      {&#x22;entity_type&#x22;: &#x22;product&#x22;, &#x22;label&#x22;: &#x22;Razer DeathAdder V3&#x22;,   &#x22;properties&#x22;: {&#x22;price&#x22;: 79,   &#x22;category&#x22;: &#x22;mouse&#x22;,  &#x22;in_stock&#x22;: True}},
  ],
)

# 3. Create a recommendation rule targeting the product entity type
rule = client.knowledge.create_analytics_rule(project_id,
  rule_type=&#x22;recommendation&#x22;,
  name=&#x22;product-recs&#x22;,
  config={&#x22;target_entity_type&#x22;: &#x22;product&#x22;},
  enabled=True,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. Define a product schema in the KB
client.Knowledge.CreateSchema(ctx, projectID, sonzai.CreateSchemaOptions{
  EntityType: &#x22;product&#x22;,
  Fields: []sonzai.KBSchemaField{
      {Name: &#x22;price&#x22;,    Type: &#x22;number&#x22;,  Required: true},
      {Name: &#x22;category&#x22;, Type: &#x22;string&#x22;,  Required: true},
      {Name: &#x22;in_stock&#x22;, Type: &#x22;boolean&#x22;, Required: true},
  },
})

// 2. Push some product nodes
client.Knowledge.InsertFacts(ctx, projectID, sonzai.InsertFactsOptions{
  Facts: []sonzai.InsertFactEntry{
      {EntityType: &#x22;product&#x22;, Label: &#x22;Razer Blade 16&#x22;,     Properties: map[string]any{&#x22;price&#x22;: 2999, &#x22;category&#x22;: &#x22;laptop&#x22;, &#x22;in_stock&#x22;: true}},
      {EntityType: &#x22;product&#x22;, Label: &#x22;Razer DeathAdder V3&#x22;, Properties: map[string]any{&#x22;price&#x22;: 79,   &#x22;category&#x22;: &#x22;mouse&#x22;,  &#x22;in_stock&#x22;: true}},
  },
})

// 3. Create a recommendation rule targeting the product entity type
rule, _ := client.Knowledge.CreateAnalyticsRule(ctx, projectID, sonzai.CreateAnalyticsRuleOptions{
  RuleType: &#x22;recommendation&#x22;,
  Name:     &#x22;product-recs&#x22;,
  Config:   map[string]any{&#x22;target_entity_type&#x22;: &#x22;product&#x22;},
  Enabled:  true,
})`,
  },
]"
/>

### With [Inventory](./inventory) — per-user holdings drive per-user recommendations [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. User buys a product — record it in inventory
const { fact_id } = await client.agents.inventory.update(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
action:      &#x22;add&#x22;,
item_type:   &#x22;product&#x22;,
description: &#x22;Razer DeathAdder V3&#x22;,
properties:  { purchase_date: &#x22;2026-04-01&#x22; },
});

// 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,
&#x22;user_123&#x22;,
5,
);
// recs.recommendations may now include accessories or similar peripherals`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. User buys a product — record it in inventory
result = client.agents.inventory.update(
  &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  action=&#x22;add&#x22;,
  item_type=&#x22;product&#x22;,
  description=&#x22;Razer DeathAdder V3&#x22;,
  properties={&#x22;purchase_date&#x22;: &#x22;2026-04-01&#x22;},
)

# 2. The inventory write creates a user→product edge in the KB graph.
#    The recommendation rule can now weight related products higher.
recs = client.knowledge.get_recommendations(
  project_id,
  rule_id=rule.rule_id,
  source_id=&#x22;user_123&#x22;,
  limit=5,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. User buys a product — record it in inventory
inv, _ := client.Agents.Inventory.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.InventoryUpdateOptions{
      Action:      &#x22;add&#x22;,
      ItemType:    &#x22;product&#x22;,
      Description: &#x22;Razer DeathAdder V3&#x22;,
      Properties:  map[string]interface{}{&#x22;purchase_date&#x22;: &#x22;2026-04-01&#x22;},
  },
)
_ = inv

// 2. The inventory write creates a user→product edge in the KB graph.
//    The recommendation rule can now weight related products higher.
recs, _ := client.Knowledge.GetRecommendations(ctx, projectID, rule.RuleID, &#x22;user_123&#x22;, 5)`,
  },
]"
/>

### With [Agent Insights](./agent-insights) — conversation signals sharpen rankings [#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 [#tutorials]

No dedicated Knowledge Analytics tutorial exists yet. The [Knowledge Base tutorial](./knowledge-base) covers schema setup and fact insertion — the prerequisite steps before creating analytics rules.

## Next steps [#next-steps]

* [Knowledge Base](./knowledge-base) — the graph backbone; define schemas and push nodes before creating rules
* [Inventory](./inventory) — per-user holdings create user-to-node edges that feed the recommendation model
* [Organization Knowledge Base](./organization-knowledge-base) — analytics rules can also run over org-scoped KB nodes for shared ranking across all users


---

# Knowledge Base

Source: https://sonz.ai/docs/en/knowledge-base

> Store and search structured facts, documents, and entity graphs your AI agents query during conversations — and that they can write back into themselves, forming a closed-loop multiplayer memory shared across every agent in the project.



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](./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](#multiplayer-memory-a-company-brain) below.

## How knowledge gets into the KB [#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](#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](#define-a-schema-then-push-facts)

**+ Autonomous agent editing*&#x2A; &#x2A;(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](#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.

<Diagram>
  {`
     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
    `}
</Diagram>

## What you can build with it [#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 [#quickstart]

### Upload a document [#upload-a-document]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import fs from &#x22;fs&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

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

console.log(doc.documentId, doc.status); // &#x22;processing&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

with open(&#x22;product_catalog.pdf&#x22;, &#x22;rb&#x22;) as f:
  doc = client.knowledge.upload_document(project_id,
      file=f,
      file_name=&#x22;product_catalog.pdf&#x22;,
  )

print(doc.document_id, doc.status)  # &#x22;processing&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `f, _ := os.Open(&#x22;product_catalog.pdf&#x22;)
defer f.Close()

doc, err := client.Knowledge.UploadDocument(ctx, projectID,
  sonzai.UploadDocumentOptions{
      File:     f,
      FileName: &#x22;product_catalog.pdf&#x22;,
  },
)
fmt.Println(doc.DocumentID, doc.Status) // &#x22;processing&#x22;`,
  },
]"
/>

### Define a schema, then push facts [#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.

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

// 2. Insert facts
await client.knowledge.insertFacts(projectId, {
source: &#x22;price_sync&#x22;,
facts: [
  {
    entity_type: &#x22;pokemon_card&#x22;,
    label: &#x22;Charizard Base Set&#x22;,
    properties: { price: 450, condition: &#x22;PSA 10&#x22;, set: &#x22;Base Set&#x22;, rarity: &#x22;Rare&#x22; },
  },
],
relationships: [
  { from_label: &#x22;Charizard Base Set&#x22;, to_label: &#x22;Fire Pokemon&#x22;, edge_type: &#x22;is_type&#x22; },
],
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Create a schema
client.knowledge.create_schema(project_id,
  entity_type=&#x22;pokemon_card&#x22;,
  display_name=&#x22;Pokémon Card&#x22;,
  description=&#x22;Collectible trading cards&#x22;,
  fields=[
      {&#x22;name&#x22;: &#x22;price&#x22;,     &#x22;type&#x22;: &#x22;number&#x22;, &#x22;required&#x22;: True},
      {&#x22;name&#x22;: &#x22;condition&#x22;, &#x22;type&#x22;: &#x22;enum&#x22;,   &#x22;enum_values&#x22;: [&#x22;PSA 10&#x22;, &#x22;PSA 9&#x22;, &#x22;Raw&#x22;]},
      {&#x22;name&#x22;: &#x22;set&#x22;,       &#x22;type&#x22;: &#x22;string&#x22;, &#x22;required&#x22;: True},
      {&#x22;name&#x22;: &#x22;rarity&#x22;,    &#x22;type&#x22;: &#x22;enum&#x22;,   &#x22;enum_values&#x22;: [&#x22;Common&#x22;, &#x22;Uncommon&#x22;, &#x22;Rare&#x22;, &#x22;Ultra Rare&#x22;]},
      {&#x22;name&#x22;: &#x22;tags&#x22;,      &#x22;type&#x22;: &#x22;array&#x22;},
      {&#x22;name&#x22;: &#x22;internal_sku&#x22;, &#x22;type&#x22;: &#x22;string&#x22;, &#x22;indexed&#x22;: False},  # stored but not BM25-searchable
  ],
  similarity_config={
      &#x22;match_fields&#x22;: [&#x22;set&#x22;, &#x22;rarity&#x22;],
      &#x22;threshold&#x22;: 0.7,
  },
)

# 2. Insert facts
client.knowledge.insert_facts(project_id,
  source=&#x22;price_sync&#x22;,
  facts=[
      {
          &#x22;entity_type&#x22;: &#x22;pokemon_card&#x22;,
          &#x22;label&#x22;: &#x22;Charizard Base Set&#x22;,
          &#x22;properties&#x22;: {&#x22;price&#x22;: 450, &#x22;condition&#x22;: &#x22;PSA 10&#x22;, &#x22;set&#x22;: &#x22;Base Set&#x22;, &#x22;rarity&#x22;: &#x22;Rare&#x22;},
      },
  ],
  relationships=[
      {&#x22;from_label&#x22;: &#x22;Charizard Base Set&#x22;, &#x22;to_label&#x22;: &#x22;Fire Pokemon&#x22;, &#x22;edge_type&#x22;: &#x22;is_type&#x22;},
  ],
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. Create a schema
indexed := false
_, err := client.Knowledge.CreateSchema(ctx, projectID, sonzai.CreateSchemaOptions{
  EntityType:  &#x22;pokemon_card&#x22;,
  DisplayName: &#x22;Pokémon Card&#x22;,
  Description: &#x22;Collectible trading cards&#x22;,
  Fields: []sonzai.KBSchemaField{
      {Name: &#x22;price&#x22;,     Type: &#x22;number&#x22;, Required: true},
      {Name: &#x22;condition&#x22;, Type: &#x22;enum&#x22;,   EnumValues: []string{&#x22;PSA 10&#x22;, &#x22;PSA 9&#x22;, &#x22;Raw&#x22;}},
      {Name: &#x22;set&#x22;,       Type: &#x22;string&#x22;, Required: true},
      {Name: &#x22;rarity&#x22;,    Type: &#x22;enum&#x22;,   EnumValues: []string{&#x22;Common&#x22;, &#x22;Uncommon&#x22;, &#x22;Rare&#x22;, &#x22;Ultra Rare&#x22;}},
      {Name: &#x22;tags&#x22;,      Type: &#x22;array&#x22;},
      {Name: &#x22;internal_sku&#x22;, Type: &#x22;string&#x22;, Indexed: &indexed}, // stored but not BM25-searchable
  },
  SimilarityConfig: &sonzai.KBSimilarityConfig{
      MatchFields: []string{&#x22;set&#x22;, &#x22;rarity&#x22;},
      Threshold:   0.7,
  },
})

// 2. Insert facts
_, err = client.Knowledge.InsertFacts(ctx, projectID, sonzai.InsertFactsOptions{
  Source: &#x22;price_sync&#x22;,
  Facts: []sonzai.InsertFactEntry{
      {
          EntityType: &#x22;pokemon_card&#x22;,
          Label:      &#x22;Charizard Base Set&#x22;,
          Properties: map[string]any{&#x22;price&#x22;: 450, &#x22;condition&#x22;: &#x22;PSA 10&#x22;, &#x22;set&#x22;: &#x22;Base Set&#x22;, &#x22;rarity&#x22;: &#x22;Rare&#x22;},
      },
  },
  Relationships: []sonzai.InsertRelEntry{
      {FromLabel: &#x22;Charizard Base Set&#x22;, ToLabel: &#x22;Fire Pokemon&#x22;, EdgeType: &#x22;is_type&#x22;},
  },
})`,
  },
]"
/>

## Core concepts [#core-concepts]

### Knowledge graph [#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 [#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-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 [#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

```typescript
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 [#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 [#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 [#full-api]

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

### Documents [#documents]

| Method                             | Returns      | Description                                   |
| ---------------------------------- | ------------ | --------------------------------------------- |
| `uploadDocument(projectId, opts)`  | `Document`   | Upload a file for automatic entity extraction |
| `listDocuments(projectId)`         | `Document[]` | List documents and their processing status    |
| `deleteDocument(projectId, docId)` | `void`       | Delete a document and its extracted entities  |

### Schemas [#schemas]

| Method                                    | Returns    | Description                                                  |
| ----------------------------------------- | ---------- | ------------------------------------------------------------ |
| `createSchema(projectId, opts)`           | `Schema`   | Define a typed entity schema with optional similarity config |
| `listSchemas(projectId)`                  | `Schema[]` | List all schemas for the project                             |
| `updateSchema(projectId, schemaId, opts)` | `Schema`   | Update fields or similarity config                           |

### Facts and graph [#facts-and-graph]

| Method                         | Returns        | Description                                                                                                                                                                                          |
| ------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insertFacts(projectId, opts)` | `InsertResult` | Upsert entities and relationships                                                                                                                                                                    |
| `bulkUpdate(projectId, opts)`  | `void`         | Patch properties on many nodes at once; only changed fields are written. Pass `upsert: false` for strict update-only semantics (missing nodes are returned as `not_found` instead of being created). |
| `listNodes(projectId, opts?)`  | `Node[]`       | List nodes, optionally filtered by entity type                                                                                                                                                       |
| `getNode(projectId, nodeId)`   | `Node`         | Fetch a single node with its edges and version history                                                                                                                                               |

### Search [#search]

| Method                    | Returns        | Description                                                          |
| ------------------------- | -------------- | -------------------------------------------------------------------- |
| `search(projectId, opts)` | `SearchResult` | Full-text search with type filter, property filters, and graph depth |

### Analytics [#analytics]

| Method                                                     | Returns                | Description                                            |
| ---------------------------------------------------------- | ---------------------- | ------------------------------------------------------ |
| `createAnalyticsRule(projectId, opts)`                     | `AnalyticsRule`        | Create a recommendation or trend rule                  |
| `listAnalyticsRules(projectId)`                            | `AnalyticsRule[]`      | List all rules                                         |
| `runAnalyticsRule(projectId, ruleId)`                      | `void`                 | Trigger a rule run immediately                         |
| `getRecommendations(projectId, opts)`                      | `RecommendationResult` | Fetch pre-computed recommendations for a source node   |
| `getTrendRankings(projectId, ruleId, type, window, limit)` | `TrendRankings`        | Top gainers, losers, most volatile, or highest average |
| `recordFeedback(projectId, opts)`                          | `void`                 | Record whether a recommendation converted              |

## Combines with other features [#combines-with-other-features]

### With [Inventory](./inventory) — shared schemas for per-user items [#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.

```ts
// 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](./scheduled-reminders) — live data injection at fire time [#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.

```ts
// 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](./knowledge-analytics) — graph becomes a recommender [#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.

```ts
// 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 [#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:

| Layer                  | What it does                                                                                                                                             | Default                                      | Where it lives                   |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------- |
| **Read**               | Every agent grounds its replies in the project KB and (optionally) the org-scope KB.                                                                     | On for any agent with `knowledgeBase: true`. | Per-project + organisation-wide. |
| **Write — autonomous** | Agents create, update, and soft-delete project KB entries themselves during conversations. Audit trail stamps which agent made which change.             | Off until `knowledgeBaseWrite: true`.        | Per-project; capability-gated.   |
| **Share across users** | A single agent serving a team carries attributed memory across users — `wisdom` (de-attributed, on by default) plus `sharedMemory` (attributed, opt-in). | `wisdom` on; `sharedMemory` off.             | Per-agent; capability-gated.     |

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.

<Diagram>
  {`
                         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.
    `}
</Diagram>

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](./organization-knowledge-base) 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 [#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 [#three-tools-the-agent-gets-when-this-is-on]

| Tool               | What the agent can do                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `knowledge_create` | Insert a new node into the project KB with typed properties.                                                                                                       |
| `knowledge_update` | Patch existing properties using compare-and-swap — the agent first reads, then submits the version it saw, so concurrent admin edits never get clobbered silently. |
| `knowledge_delete` | Soft-delete a node (`is_active = false`). Soft only; hard delete stays admin-only.                                                                                 |

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 [#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).

```ts
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:

```ts
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.

<Callout type="info" title="Read first, then write">
  `knowledgeBaseWrite` requires `knowledgeBase: true` to also be on — an agent that can't read the KB can't intelligently edit it. The platform refuses to register the write tools when only write is enabled and logs a warning.
</Callout>

## Wisdom & shared memory [#wisdom--shared-memory]

<Callout type="info" title="Dedicated page">
  Shared memory has its own full documentation page — see [**Shared Memory**](./shared-memory) for when to use it, how to enable and disable it, what tools the agent gets, how to verify it's working with live API probes, and the full privacy-control story. The summary below is here so KB readers see the multiplayer-memory hook in context.
</Callout>

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) [#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.

```ts
// 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 });
```

<Callout type="info" title="Default-on, opt-out">
  Wisdom is enabled for **all agents** — including ones created before the default-on cutover. The capability stores tri-state: `true`, `false`, or unset (treated as on). Pass `wisdom: false` explicitly only when you want to disable it; passing nothing keeps the agent on the platform default.
</Callout>

### Shared memory (attributed, opt-in) [#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.

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `// Wisdom is the precondition (default ON for new agents — only pass it
// explicitly when overriding the default).
await client.agents.updateCapabilities(&#x22;agent_abc&#x22;, {
wisdom:       true,
sharedMemory: true,
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `client.agents.update_capabilities(
  &#x22;agent_abc&#x22;,
  wisdom=True,
  shared_memory=True,
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `t := true
_, err := client.Agents.UpdateCapabilities(ctx, &#x22;agent_abc&#x22;, sonzai.UpdateCapabilitiesOptions{
  Wisdom:       &t,
  SharedMemory: &t,
})`,
  },
  {
    label: &#x22;HTTP&#x22;,
    language: &#x22;bash&#x22;,
    code: `curl -X PATCH \\
&#x22;$PLATFORM_API_URL/api/v1/agents/agent_abc/capabilities&#x22; \\
-H &#x22;Authorization: Bearer $API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;wisdom&#x22;: true,
  &#x22;sharedMemory&#x22;: true
}'`,
  },
]"
/>

You can also enable it at agent creation time:

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `const agent = await client.agents.create({
name:       &#x22;Team Coordinator&#x22;,
project_id: &#x22;proj_abc&#x22;,
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `agent = client.agents.create(
  name=&#x22;Team Coordinator&#x22;,
  project_id=&#x22;proj_abc&#x22;,
  tool_capabilities={
      &#x22;wisdom&#x22;: True,
      &#x22;shared_memory&#x22;: True,
  },
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `t := true
agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  Name:      &#x22;Team Coordinator&#x22;,
  ProjectID: &#x22;proj_abc&#x22;,
  ToolCapabilities: &sonzai.AgentToolCapabilities{
      Wisdom:       &t,
      SharedMemory: &t,
  },
})`,
  },
]"
/>

<Callout type="warn" title="Wisdom vs. shared memory — pick deliberately">
  `wisdom` is the generalization layer (safe, de-attributed, on by default). `sharedMemory` is the attribution layer (sensitive, per-person, off by default). Both can coexist — but turn on shared memory only when the use case genuinely needs cross-user visibility (groups, teams, parties, shared business context). Single-user companion products should leave it off.
</Callout>

## Tutorials [#tutorials]

* [Inventory tutorial](./tutorial-inventory) — model per-user items as typed KB entities and read them back during conversations
* [Medication Reminders](./tutorial-medication-reminders) — end-to-end flow combining Knowledge Base, Inventory, and Scheduled Reminders for a medication adherence product

## Next steps [#next-steps]

* [Inventory](./inventory) — per-user structured items backed by the same knowledge graph
* [Knowledge Analytics](./knowledge-analytics) — recommendation rules, trend rankings, and conversion tracking built on your entity graph
* [Organization Knowledge Base](./organization-knowledge-base) — project-level shared knowledge visible to all agents across a tenant


---

# Memory

Source: https://sonz.ai/docs/en/memory

> Agents remember facts, events, and commitments extracted automatically from every conversation, recalled on demand via search, timeline, and tree browsing.



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](./scheduled-reminders): when a reminder fires and the user replies, the reply is captured as a new memory fact. It feeds [Agent Insights](./agent-insights) too — habits, goals, and interests are derived signals aggregated over memory facts.

## What you can build with it [#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 [#quickstart]

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

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

// Semantic search — scoped to a specific user
const results = await client.agents.memory.search(&#x22;agent-id&#x22;, {
query:   &#x22;hiking trip&#x22;,
userId:  &#x22;user-123&#x22;,   // 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(&#x22;agent-id&#x22;, {
userId: &#x22;user-123&#x22;,
limit: 20,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# Semantic search — scoped to a specific user
results = client.agents.memory.search(
  &#x22;agent-id&#x22;,
  query=&#x22;hiking trip&#x22;,
  user_id=&#x22;user-123&#x22;,  # optional: omit to search across all users for this agent
  limit=10,
)

for mem in results.results:
  print(mem.content, mem.fact_type, mem.score)

# Browse the tree
tree = client.agents.memory.list(
  &#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  limit=20,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

// Semantic search — scoped to a specific user
results, err := client.Agents.Memory.Search(ctx, &#x22;agent-id&#x22;,
  sonzai.MemorySearchOptions{
      Query:  &#x22;hiking trip&#x22;,
      UserID: &#x22;user-123&#x22;, // optional: omit to search across all users for this agent
      Limit:  10,
  },
)
for _, mem := range results.Results {
  fmt.Println(mem.Content, mem.FactType, mem.Score)
}

// Browse the tree
tree, err := client.Agents.Memory.List(ctx, &#x22;agent-id&#x22;,
  &sonzai.MemoryListOptions{
      UserID: &#x22;user-123&#x22;,
      Limit:  20,
  },
)`,
  },
]"
/>

## Core concepts [#core-concepts]

### Memory tree structure [#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-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-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-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 [#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*&#x2A; by default: every fact lands in the current turn before generation starts. Switch to &#x2A;*`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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Read current capabilities
const caps = await client.agents.getCapabilities(&#x22;agent-id&#x22;);
console.log(caps.memoryMode); // &#x22;sync&#x22; or &#x22;async&#x22;

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

// Switch back to sync
await client.agents.updateCapabilities(&#x22;agent-id&#x22;, { memoryMode: &#x22;sync&#x22; });`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Read current capabilities
caps = client.agents.get_capabilities(&#x22;agent-id&#x22;)
print(caps.memory_mode)  # &#x22;sync&#x22; or &#x22;async&#x22;

# Switch to async for lower first-token latency
client.agents.update_capabilities(&#x22;agent-id&#x22;, memory_mode=&#x22;async&#x22;)

# Switch back to sync
client.agents.update_capabilities(&#x22;agent-id&#x22;, memory_mode=&#x22;sync&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Read current capabilities
caps, _ := client.Agents.GetCapabilities(ctx, &#x22;agent-id&#x22;)
fmt.Println(caps.MemoryMode) // &#x22;sync&#x22; or &#x22;async&#x22;

// Switch to async for lower first-token latency
_, _ = client.Agents.UpdateCapabilities(ctx, &#x22;agent-id&#x22;, sonzai.UpdateCapabilitiesOptions{
  MemoryMode: &#x22;async&#x22;,
})

// Switch back to sync
_, _ = client.Agents.UpdateCapabilities(ctx, &#x22;agent-id&#x22;, sonzai.UpdateCapabilitiesOptions{
  MemoryMode: &#x22;sync&#x22;,
})`,
  },
]"
/>

> **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 [#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.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const caps = await client.agents.getCapabilities(&#x22;agent-id&#x22;);

for (const pending of caps.pendingCapabilities ?? []) {
console.log(pending.capability, pending.context);
// e.g. &#x22;musicGeneration&#x22;  &#x22;Scheduled for activation on plan upgrade&#x22;
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `caps = client.agents.get_capabilities(&#x22;agent-id&#x22;)

for pending in caps.pending_capabilities or []:
  print(pending.capability, pending.context)
  # e.g. &#x22;musicGeneration&#x22;  &#x22;Scheduled for activation on plan upgrade&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `caps, _ := client.Agents.GetCapabilities(ctx, &#x22;agent-id&#x22;)

for _, pending := range caps.PendingCapabilities {
  fmt.Println(pending.Capability, pending.Context)
  // e.g. &#x22;musicGeneration&#x22;  &#x22;Scheduled for activation on plan upgrade&#x22;
}`,
  },
]"
/>

## Full API [#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](./api-reference).

| Method                              | Returns                  | Description                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list(agentID, opts)`               | `MemoryTreeResponse`     | Browse the memory tree, optionally rooted at a `parentID`. Pass `memory_type` to filter results to a specific memory category: `"factual"`, `"episodic"`, `"semantic"`, `"procedural"`, `"identity"`, `"temporal"`, or `"relational"`. This is a post-fetch filter applied on the result set — it does not reduce server-side I/O, so the `limit` applies before filtering. |
| `search(agentID, opts)`             | `MemorySearchResponse`   | Semantic/keyword search; returns `Results[]` with `content`, `factType`, `score`. Pass `userId` (`user_id` in Python/JSON) to scope results to a single user; omit to search across all users for the agent.                                                                                                                                                                |
| `timeline(agentID, opts)`           | `MemoryTimelineResponse` | Chronological sessions with `first_fact_at`, `last_fact_at`, `fact_count`                                                                                                                                                                                                                                                                                                   |
| `listFacts(agentID, opts)`          | `FactListResponse`       | Paginated flat list of atomic facts; response has `Facts`, `TotalCount`, `HasMore`                                                                                                                                                                                                                                                                                          |
| `reset(agentID, opts)`              | `MemoryResetResponse`    | Delete all memory for an agent–user pair                                                                                                                                                                                                                                                                                                                                    |
| `createFact(agentID, opts)`         | `AtomicFact`             | Manually insert a fact tagged `source_type="manual"`                                                                                                                                                                                                                                                                                                                        |
| `updateFact(agentID, factID, opts)` | `AtomicFact`             | Patch content, type, importance, or confidence of an existing fact                                                                                                                                                                                                                                                                                                          |
| `deleteFact(agentID, factID)`       | `void`                   | Remove a single fact by ID                                                                                                                                                                                                                                                                                                                                                  |
| `seed(agentID, opts)`               | `SeedMemoriesResponse`   | Bulk-import initial memories without an AI generation step                                                                                                                                                                                                                                                                                                                  |
| `deleteWisdomFact(agentID, factID)` | `DeleteWisdomResponse`   | Remove a wisdom-layer fact                                                                                                                                                                                                                                                                                                                                                  |
| `getWisdomAudit(agentID, factID)`   | `WisdomAuditResponse`    | Full audit trail for a wisdom fact                                                                                                                                                                                                                                                                                                                                          |
| `getFactHistory(agentID, factID)`   | `FactHistoryResponse`    | Version history for a specific fact                                                                                                                                                                                                                                                                                                                                         |

## Combines with other features [#combines-with-other-features]

### With [Scheduled Reminders](./scheduled-reminders) — responses populate memory [#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.

```typescript
// 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](./tutorial-medication-reminders).

### With [Conversations](./conversations) — every turn writes memory [#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.

```typescript
// 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](./agent-insights) — memory is the raw material [#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.

```typescript
// 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 [#tutorials]

* [Memory — end-to-end walkthrough](./tutorial-memory) — covers seed, search, timeline, manual facts, and reset.

## Next steps [#next-steps]

* [Agent Insights](./agent-insights) — derived signals (habits, goals, interests) built on top of memory facts.
* [Scheduled Reminders](./scheduled-reminders) — proactive messages whose user replies flow back into memory.
* [Conversations](./conversations) — every chat turn is the primary source of memory writes.


---

# Multiplayer Memory

Source: https://sonz.ai/docs/en/multiplayer-memory

> One umbrella for every way memory crosses boundaries in Sonzai — agent-to-agent (inter-agent) through the shared knowledge base, and across users sharing one agent (intra-agent) through wisdom and shared memory. A closed-loop company brain plus a team brain, combined.



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:

| Axis            | What crosses                                              | Real-world shape                                                                | Capabilities                                                                                                   |
| --------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Inter-agent** | Knowledge between agents on the same project (or tenant). | A closed-loop **company brain** — agent A learns; agent B picks it up.          | `knowledgeBase` (read), `knowledgeBaseWrite` (autonomous update), `knowledgeBaseScopeMode` (org-wide cascade). |
| **Intra-agent** | Memory between users talking to the same agent.           | A **team brain** — one agent informing user A with what it learned with user B. | `wisdom` (de-attributed, default-on), `sharedMemory` (attributed, opt-in).                                     |

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.

<Diagram>
  {`
                            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.
    `}
</Diagram>

## Inter-agent memory — agent ↔ agent [#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 [#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](./knowledge-base#how-knowledge-gets-into-the-kb) for the two ingestion paths.

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

### 2. Autonomous editing — agents write what they learn back [#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.

```ts
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](./knowledge-base#agents-writing-to-the-knowledge-base).

### 3. Organization scope — tenant-wide knowledge above projects [#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.

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

Detail: [Organization Knowledge Base](./organization-knowledge-base).

## Intra-agent memory — across users sharing one agent [#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 [#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.

```ts
// 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 [#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."

```ts
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](./shared-memory).

## Combining inter-agent and intra-agent [#combining-inter-agent-and-intra-agent]

The two axes are independent — every combination is valid:

| Inter-agent       | Intra-agent | What you get                                                                                                               |
| ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| Off               | Off         | Per-pair memory only. Right default for single-user companion products.                                                    |
| On (read only)    | Off         | Agents ground replies in your KB but don't share between users. Standard read-only docs assistant.                         |
| On (read + write) | Off         | Closed-loop world knowledge. Agents capture verified facts about products, prices, incidents — every other agent benefits. |
| Off               | On          | Team brain — one agent serves a group, but no shared world knowledge across agents.                                        |
| On (read + write) | On          | **Full multiplayer memory.** Closed-loop world knowledge plus a team brain. Best for shared-business-context products.     |

```ts
// 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 [#how-to-verify-its-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**

```bash
# 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**

```bash
# 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 [#privacy-and-control]

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

| Capability           | Server-side controls                                                                                                                                                                                                                         |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `knowledgeBaseWrite` | Schema validation per write, write quotas, project-scope check, full audit trail (`source = "agent:<agent-id>"`), CAS update, soft-delete only (hard delete admin-only).                                                                     |
| `wisdom`             | k-anonymity threshold before promotion, LLM-gated rewrite to remove identifying detail, daily cadence so a single noisy session can't leak.                                                                                                  |
| `sharedMemory`       | Semantic privacy-floor validator (compensation, health, politics blocked), discretion clause in every prompt, disclosure audit on every fact load, soft-delete tombstone, source pinned to `developer_api` (callers can't spoof provenance). |

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

## Where to dive deeper [#where-to-dive-deeper]

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


---

# Notifications (Polling)

Source: https://sonz.ai/docs/en/notifications-polling

> Fetch pending proactive messages for a user by polling the Notifications API — the simplest way to consume schedules, wakeups, and tenant-triggered events in a web or mobile client.



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 [#what-you-can-build-with-it]

* **Mobile app inbox** — periodic fetch of pending messages on foreground, display as native notifications or in-app banners
* **Web dashboard** — a dedicated tab showing all of the agent's pending outreach to a given user
* **Delayed delivery** — let messages queue up while the user is offline; deliver the full batch on reconnect
* **Audit / moderation** — preview agent-generated messages before pushing to downstream delivery (email, SMS)
* **Development / testing** — poll notifications during a test run to verify that schedules and wakeups fired correctly

## Quickstart [#quickstart]

Poll for pending messages, display the latest, then mark each one consumed.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const pending = await client.agents.notifications.list(&#x22;agent_abc&#x22;, {
user_id: &#x22;user_123&#x22;,
limit: 10,
});

for (const n of pending.notifications) {
console.log(n.generated_message);
await client.agents.notifications.consume(&#x22;agent_abc&#x22;, n.message_id);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

pending = client.agents.notifications.list(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;, limit=10)

for n in pending.notifications:
  print(n.generated_message)
  client.agents.notifications.consume(&#x22;agent_abc&#x22;, n.message_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
if err != nil { panic(err) }

pending, err := client.Agents.Notifications.List(ctx, &#x22;agent_abc&#x22;,
  &sonzai.NotificationListOptions{UserID: &#x22;user_123&#x22;, Limit: 10},
)
if err != nil { panic(err) }

for _, n := range pending.Notifications {
  fmt.Println(n.GeneratedMessage)
  _, _ = client.Agents.Notifications.Consume(ctx, &#x22;agent_abc&#x22;, n.MessageID)
}`,
  },
]"
/>

## Core concepts [#core-concepts]

### Queue semantics [#queue-semantics]

When a proactive message fires — whether from a schedule, a wakeup, or a trigger event — the platform enqueues it for the relevant user. The queue is per-user, per-agent. Calling `list` returns only messages in `pending` state; calling `consume` transitions a specific message to `consumed`. Consumed messages are excluded from future `list` responses but remain visible in `history`. The queue does not auto-expire: messages stay pending indefinitely until your code marks them consumed.

### Polling cadence [#polling-cadence]

There is no hard requirement on how frequently you poll, but these guidelines work well in practice:

* **Foreground (user has the app open):** every 10–30 seconds
* **Background (app backgrounded or tab hidden):** every 2–5 minutes, or on visibility-change events
* **Reconnect burst:** poll immediately when the user comes back online after a period of inactivity, then resume normal cadence

Avoid polling more frequently than every 10 seconds — there is no benefit since notification generation is event-driven, not continuous.

### Vs SSE (live chat stream) [#vs-sse-live-chat-stream]

If the user has an active SSE chat stream open, proactive messages appear inline in the conversation automatically — no polling needed. Polling is the **catch-up** mechanism for users who do not have a live stream. The two patterns are complementary: SSE for foreground delivery, polling for background or offline users.

### History endpoint [#history-endpoint]

`notifications.history` is separate from `notifications.list`. It returns all historical notifications for an agent (including already-consumed ones) and is useful for audit trails, moderation dashboards, and debugging. It does not filter by `user_id` — it returns across all users up to the requested limit.

## Full API [#full-api]

All methods are on `client.agents.notifications.*` (TS/Python) or `client.Agents.Notifications` (Go). Full request and response shapes live in the [API reference](./api-reference).

| Method    | Signature                             | Returns                             | Description                                             |
| --------- | ------------------------------------- | ----------------------------------- | ------------------------------------------------------- |
| `list`    | `list(agentId, { user_id?, limit? })` | `{ notifications: Notification[] }` | Fetch pending messages for a user                       |
| `consume` | `consume(agentId, messageId)`         | `void`                              | Mark a single message consumed                          |
| `history` | `history(agentId, limit)`             | `{ notifications: Notification[] }` | Fetch all historical notifications (consumed + pending) |

### Notification fields [#notification-fields]

| Field              | JSON key            | Description                                                          |
| ------------------ | ------------------- | -------------------------------------------------------------------- |
| `MessageID`        | `message_id`        | Pass this to `consume` to mark the message delivered                 |
| `UserID`           | `user_id`           | The user this notification was generated for                         |
| `CheckType`        | `check_type`        | The check type (e.g. `"reminder"`, `"interest_check"`, `"birthday"`) |
| `GeneratedMessage` | `generated_message` | The actual text the agent produced — display this to the user        |
| `CreatedAt`        | `created_at`        | When the message was enqueued (RFC 3339 UTC)                         |
| `ScheduleID`       | `schedule_id`       | Set if the message originated from a schedule; otherwise absent      |
| `WakeupID`         | `wakeup_id`         | Set if the message originated from a wakeup; otherwise absent        |

<Callout type="warning" title="Use the correct field names">
  Older code may use `id`, `notificationId`, `type`, or `content`. These are incorrect. The canonical fields are `message_id`, `check_type`, and `generated_message`. Using the wrong field names will result in silent failures when calling `consume`.
</Callout>

## Combines with [#combines-with]

### With [Scheduled Reminders](./scheduled-reminders) — delivery side of recurring messages [#with-scheduled-reminders--delivery-side-of-recurring-messages]

A schedule defines *when* the agent fires; polling is one way to *receive* what it produced. When a schedule's cadence fires, the platform generates the agent's message and enqueues it. Your client polls, displays `generated_message`, then calls `consume` to clear it from the queue. The schedule and delivery are fully decoupled — you can swap in webhooks or SSE without touching the schedule definition.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

// 1. Create a daily 09:00 check-in schedule (done once, e.g. at onboarding)
await client.schedules.create(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;09:00&#x22;] },
  timezone: &#x22;Asia/Singapore&#x22;,
},
intent: &#x22;morning check-in on mood and sleep&#x22;,
check_type: &#x22;reminder&#x22;,
});

// 2. On each app foreground, poll for what the schedule produced
const pending = await client.agents.notifications.list(&#x22;agent_abc&#x22;, {
user_id: &#x22;user_123&#x22;,
limit: 5,
});

for (const n of pending.notifications) {
showInAppBanner(n.generated_message);
await client.agents.notifications.consume(&#x22;agent_abc&#x22;, n.message_id);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# 1. Create a daily 09:00 check-in schedule (done once, e.g. at onboarding)
client.schedules.create(
  &#x22;agent_abc&#x22;,
  &#x22;user_123&#x22;,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;09:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
  },
  intent=&#x22;morning check-in on mood and sleep&#x22;,
  check_type=&#x22;reminder&#x22;,
)

# 2. On each app foreground, poll for what the schedule produced
pending = client.agents.notifications.list(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;, limit=5)

for n in pending.notifications:
  show_in_app_banner(n.generated_message)
  client.agents.notifications.consume(&#x22;agent_abc&#x22;, n.message_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
if err != nil { panic(err) }

// 1. Create a daily 09:00 check-in schedule (done once, e.g. at onboarding)
_, err = client.Schedules.Create(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.CreateScheduleOptions{
      Cadence:   mustMarshal(map[string]any{
          &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: []string{&#x22;09:00&#x22;}},
          &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
      }),
      Intent:    &#x22;morning check-in on mood and sleep&#x22;,
      CheckType: &#x22;reminder&#x22;,
  },
)
if err != nil { panic(err) }

// 2. On each app foreground, poll for what the schedule produced
pending, err := client.Agents.Notifications.List(ctx, &#x22;agent_abc&#x22;,
  &sonzai.NotificationListOptions{UserID: &#x22;user_123&#x22;, Limit: 5},
)
if err != nil { panic(err) }

for _, n := range pending.Notifications {
  showInAppBanner(n.GeneratedMessage)
  _, _ = client.Agents.Notifications.Consume(ctx, &#x22;agent_abc&#x22;, n.MessageID)
}`,
  },
]"
/>

### With [Wakeups](./wakeups) — delivery side of one-off check-ins [#with-wakeups--delivery-side-of-one-off-check-ins]

A wakeup fires once at a specific moment; polling retrieves the message it generated. This is the natural delivery pattern for one-off agent outreach in mobile clients where webhooks are unavailable. Schedule the wakeup when the event is known (e.g. "follow up 24 hours after purchase"), then poll periodically — the message lands in the queue the moment the delay elapses.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

// 1. Schedule a one-off wakeup (e.g. after a user completes onboarding)
await client.agents.scheduleWakeup(&#x22;agent_abc&#x22;, {
user_id:     &#x22;user_123&#x22;,
check_type:  &#x22;interest_check&#x22;,
intent:      &#x22;check in about how onboarding went&#x22;,
delay_hours: 24,
});

// 2. Poll for the message when it fires (24 h later)
const pending = await client.agents.notifications.list(&#x22;agent_abc&#x22;, {
user_id: &#x22;user_123&#x22;,
limit: 5,
});

for (const n of pending.notifications) {
console.log(n.check_type, n.generated_message);
await client.agents.notifications.consume(&#x22;agent_abc&#x22;, n.message_id);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# 1. Schedule a one-off wakeup (e.g. after a user completes onboarding)
client.agents.schedule_wakeup(&#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  check_type=&#x22;interest_check&#x22;,
  intent=&#x22;check in about how onboarding went&#x22;,
  delay_hours=24,
)

# 2. Poll for the message when it fires (24 h later)
pending = client.agents.notifications.list(&#x22;agent_abc&#x22;, user_id=&#x22;user_123&#x22;, limit=5)

for n in pending.notifications:
  print(n.check_type, n.generated_message)
  client.agents.notifications.consume(&#x22;agent_abc&#x22;, n.message_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
if err != nil { panic(err) }

// 1. Schedule a one-off wakeup (e.g. after a user completes onboarding)
_, err = client.Agents.Wakeups.Schedule(ctx, &#x22;agent_abc&#x22;, sonzai.ScheduleWakeupOptions{
  UserID:     &#x22;user_123&#x22;,
  CheckType:  &#x22;interest_check&#x22;,
  Intent:     &#x22;check in about how onboarding went&#x22;,
  DelayHours: 24,
})
if err != nil { panic(err) }

// 2. Poll for the message when it fires (24 h later)
pending, err := client.Agents.Notifications.List(ctx, &#x22;agent_abc&#x22;,
  &sonzai.NotificationListOptions{UserID: &#x22;user_123&#x22;, Limit: 5},
)
if err != nil { panic(err) }

for _, n := range pending.Notifications {
  fmt.Println(n.CheckType, n.GeneratedMessage)
  _, _ = client.Agents.Notifications.Consume(ctx, &#x22;agent_abc&#x22;, n.MessageID)
}`,
  },
]"
/>

### With [Webhooks](./webhooks) — alternative push delivery [#with-webhooks--alternative-push-delivery]

Polling and webhooks are two delivery patterns for the same underlying notifications queue. Choose based on your infrastructure:

* **Polling** — your client asks the server for new messages on a schedule. Simple to implement, works in browsers and mobile apps, no inbound connectivity required. Latency is bounded by your polling interval.
* **Webhooks** — the server pushes each message to a URL you register the moment it fires. Lower latency, better for server-to-server integration and multi-channel fanout (email, SMS, push notifications). Requires a public HTTPS endpoint to receive callbacks.

You can use both simultaneously: poll from mobile clients for in-app delivery and register a webhook on your backend for email/SMS fanout. The queue tracks consumed state per message, so a message consumed via polling will not appear in webhook delivery (and vice versa).

## Tutorials [#tutorials]

* [Medication Reminders](./tutorial-medication-reminders) — full-stack example combining Schedule + Inventory + Memory; shows the end-to-end flow from schedule creation to polling the generated reminder.
* [Scheduled Reminders — reference walkthrough](./tutorial-scheduled-reminders) — covers cadence shapes, DST, preview, and the full lifecycle including how fired messages appear in the notifications queue.

## Next steps [#next-steps]

* [Scheduled Reminders](./scheduled-reminders) — set up the recurring schedules whose output you poll here
* [Wakeups](./wakeups) — one-off check-ins that also land in the notifications queue
* [Webhooks](./webhooks) — the push alternative to polling; compare delivery trade-offs
* [Proactive Messaging overview](./proactive-overview) — sources × delivery channels explained


---

# Organization-Global Knowledge Base

Source: https://sonz.ai/docs/en/organization-knowledge-base

> One organization-wide knowledge scope that every project under the tenant can read from. Use it for policies, shared lore, playbooks, or facts that belong to the whole organization rather than a single project.



**The organization-global Knowledge Base** is an opt-in second scope that sits above every project's own [Knowledge Base](./knowledge-base), letting agents across all projects under a tenant read shared facts — HR policies, brand standards, product catalogs, multi-game lore — without duplicating data per project. Each agent picks a scope mode (`project_only`, `org_only`, `cascade`, or `union`) to control how org and project graphs combine. Cascade is the recommended default: project facts win on ID collisions, so local overrides remain authoritative.

## When to use it [#when-to-use-it]

By default, the Knowledge Base is **project-scoped**. Every project has its own isolated graph. That is the right model for most tenants — a project's data should not leak into other projects' agents.

The **organization scope** is an opt-in second scope that sits above every project. Knowledge written here is readable by every project agent under the tenant that opts into a cross-scope reading mode. Typical uses:

* Company-wide policies (HR, refund, privacy, terms).
* Product documentation shared across projects.
* Brand guidelines, tone standards, style rules.
* Shared lore for multi-game or multi-product characters.
* Reference catalogs (locations, entities, product lists).

## How it fits with project KB [#how-it-fits-with-project-kb]

<Diagram>
  {`
    Tenant (organization)
    |
    |-- Organization-global KB   (scope_id = "")
    |   - policies, shared lore, brand, reference catalogs
    |   - written by tenant admins via the org endpoints
    |
    |-- Project A KB             (scope_id = project_a_id)
    |   - A's own uploaded docs + API-pushed facts
    |
    |-- Project B KB             (scope_id = project_b_id)
    |   - B's own uploaded docs + API-pushed facts
    |
    Agents under any project choose how to read across the two scopes:
    - project_only   legacy: just the agent's project KB
    - org_only       only the organization-global KB
    - cascade        both, project wins on ID collisions (recommended)
    - union          both, first occurrence wins
    `}
</Diagram>

## Scope mode on an agent [#scope-mode-on-an-agent]

Every agent has a `knowledgeBaseScopeMode` capability. Leaving it unset preserves the legacy project-only behavior. To enable the cascade, set it via the capabilities endpoint or the dashboard.

Enable the knowledge base capability and set the project ID via the SDK:

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `// Enable the knowledge base + org cascade for the agent
await client.agents.updateCapabilities(agentId, {
knowledgeBase: true,
knowledgeBaseScopeMode: &#x22;cascade&#x22;,
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `# Enable the knowledge base + org cascade for the agent
client.agents.update_capabilities(
  agent_id,
  knowledge_base=True,
  knowledge_base_scope_mode=&#x22;cascade&#x22;,
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `// Enable the knowledge base + org cascade for the agent
trueVal := true
_, err := client.Agents.UpdateCapabilities(ctx, agentID, sonzai.UpdateCapabilitiesOptions{
  KnowledgeBase:          &trueVal,
  KnowledgeBaseScopeMode: &#x22;cascade&#x22;,
})`,
  },
  {
    label: &#x22;HTTP&#x22;,
    language: &#x22;bash&#x22;,
    code: `curl -X PATCH \\
&#x22;$PLATFORM_API_URL/api/v1/agents/$AGENT_ID/capabilities&#x22; \\
-H &#x22;Authorization: Bearer $API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;knowledgeBase&#x22;: true,
  &#x22;knowledgeBaseScopeMode&#x22;: &#x22;cascade&#x22;
}'`,
  },
]"
/>

## Writing to the org scope [#writing-to-the-org-scope]

There are two ways a tenant admin can populate the org scope. Both are backend-only endpoints — end users of your products never see them.

### 1. Create a node directly in the org scope [#1-create-a-node-directly-in-the-org-scope]

Use this for hand-authored facts that should live at the organization level from the start.

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `const node = await client.knowledge.createOrgNode(tenantId, {
node_type: &#x22;policy&#x22;,
label: &#x22;Refund Policy&#x22;,
properties: {
  description: &#x22;Full refund available within 30 days of purchase.&#x22;,
},
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `node = client.knowledge.create_org_node(
  tenant_id,
  node_type=&#x22;policy&#x22;,
  label=&#x22;Refund Policy&#x22;,
  properties={
      &#x22;description&#x22;: &#x22;Full refund available within 30 days of purchase.&#x22;,
  },
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `node, err := client.Knowledge.CreateOrgNode(ctx, tenantID, sonzai.CreateOrgNodeOptions{
  NodeType: &#x22;policy&#x22;,
  Label:    &#x22;Refund Policy&#x22;,
  Properties: map[string]any{
      &#x22;description&#x22;: &#x22;Full refund available within 30 days of purchase.&#x22;,
  },
})`,
  },
  {
    label: &#x22;HTTP&#x22;,
    language: &#x22;bash&#x22;,
    code: `curl -X POST \\
&#x22;$PLATFORM_API_URL/api/v1/tenants/$TENANT_ID/knowledge/org-nodes&#x22; \\
-H &#x22;Authorization: Bearer $API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;node_type&#x22;: &#x22;policy&#x22;,
  &#x22;label&#x22;: &#x22;Refund Policy&#x22;,
  &#x22;properties&#x22;: { &#x22;description&#x22;: &#x22;Full refund within 30 days.&#x22; }
}'`,
  },
]"
/>

### 2. Promote an existing project node [#2-promote-an-existing-project-node]

If a fact already lives in a project KB and you want to share it organisation-wide, promote it. The project copy is preserved — promotion is additive. If an org node with the same `(node_type, norm_label)` already exists, the server returns that one instead of writing a duplicate.

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `const orgNode = await client.knowledge.promoteNodeToOrg(projectId, nodeId, tenantId);`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `org_node = client.knowledge.promote_node_to_org(project_id, node_id, tenant_id)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `orgNode, err := client.Knowledge.PromoteNodeToOrg(ctx, projectID, nodeID, tenantID)`,
  },
]"
/>

## Reading: cascade search and provenance [#reading-cascade-search-and-provenance]

When an agent with a non-default scope mode calls `knowledge_search` during a conversation, the platform runs the search against both scopes in parallel and fuses the results using Reciprocal Rank Fusion (RRF). Each returned result carries a `scope` field so your prompt can show the LLM where a fact came from.

<Diagram>
  {`
    Agent's knowledge_search("refund policy")
           |
           v
    +----------------------------+       +----------------------------+
    | Project BM25  (scope=proj) |  +--> | Org BM25      (scope="")   |
    +----------------------------+       +----------------------------+
           |                                         |
           +--------------- RRF fuse ----------------+
                           |
                           v
              Top-N results, each tagged:
                scope: "project" | "organization"
    `}
</Diagram>

Scope modes differ in how they merge on a collision:

* **`cascade`** (recommended): project wins on duplicate node IDs. Agents keep their own overrides, but inherit the org defaults when a project doesn't define something.
* **`union`**: first occurrence wins; both scopes contribute equally to ranking. Useful when you want broad coverage without a strong preference.
* **`org_only`**: skip project KB entirely. Useful for reference-only agents (FAQ bots on company policy, e.g.).
* **`project_only`** (default): legacy behavior, org-scope facts are invisible to this agent.

## Dashboard admin UI [#dashboard-admin-ui]

A tenant admin can manage org-scope knowledge at `/dashboard/knowledge/org`:

* Create a node directly in the org scope.
* Promote an existing project node by pasting its project ID and node ID.

The UI is a thin wrapper over the same endpoints shown above; if you need bulk operations or automated pipelines, the SDKs are the recommended path.

## Operational notes [#operational-notes]

* **Access control:** the two org-scope write endpoints are gated by the same tenant-admin middleware used by the existing project-scoped KB endpoints. Standard project members see no new surface.
* **Backward compatibility:** zero change for any existing agent. Agents stay on `project_only` mode unless you set a scope mode explicitly.
* **Idempotency:** dedup is at `(node_type, norm_label)`. Promotion returns the existing org node if one is already there; direct `createOrgNode` will create a second node with a different NodeID — check before calling if that matters.
* **Per-scope BM25:** each scope maintains its own BM25 index and document-frequency corpus. This is why the cascade uses RRF instead of score-adding — the raw scores from two separate indexes are not directly comparable.


---

# Personality System

Source: https://sonz.ai/docs/en/personality

> Create agents with distinct personalities and watch them evolve through interaction.



**Personality** in Sonzai is a Big Five (OCEAN) profile attached to every agent, mapped internally to ten BFAS facets and a set of behavioral traits — response length, question frequency, empathy style, conflict approach — that shape how the agent actually talks. You set five 0.0-1.0 scores at creation; the Relationship Layer derives the prompt, speech patterns, and mood baselines from there. The most load-bearing detail: personality drifts slowly through interaction, with safety caps to prevent runaway change, and you can inspect the full evolution history at any time.

## Big Five Personality Model [#big-five-personality-model]

Every agent has Big Five (OCEAN) personality scores. Behavioral traits, mood baselines, speech patterns, and interaction preferences all derive from these scores.

* **Openness** (0.0 - 1.0): Curiosity, creativity, openness to experience. High = imaginative, adventurous. Low = practical, conventional.
* **Conscientiousness** (0.0 - 1.0): Organization, discipline, goal-orientation. High = methodical, reliable. Low = spontaneous, flexible.
* **Extraversion** (0.0 - 1.0): Social energy, enthusiasm, assertiveness. High = outgoing, energetic. Low = reserved, reflective.
* **Agreeableness** (0.0 - 1.0): Warmth, cooperation, empathy. High = caring, trusting. Low = direct, skeptical.
* **Neuroticism** (0.0 - 1.0): Emotional sensitivity, anxiety tendency. High = emotionally reactive. Low = emotionally stable.

The `confidence` field (0.0-1.0) controls how strongly scores influence behavior. Low confidence = more generic; high = more differentiated.

### BFAS Facet Dimensions [#bfas-facet-dimensions]

Internally, the platform maps Big5 scores to 10 BFAS (Big Five Aspect Scales) facets. These facets provide finer-grained control over personality and are exposed in the personality profile response:

| Big5 Domain       | Facet 1           | Facet 2         |
| ----------------- | ----------------- | --------------- |
| Openness          | `intellect`       | `aesthetic`     |
| Conscientiousness | `industriousness` | `orderliness`   |
| Extraversion      | `enthusiasm`      | `assertiveness` |
| Agreeableness     | `compassion`      | `politeness`    |
| Neuroticism       | `withdrawal`      | `volatility`    |

Each facet is a 0.0-1.0 score derived from the parent Big5 dimension. You can read them from the personality profile but do not need to set them manually — they are computed from your Big5 scores.

### Behavioral Traits [#behavioral-traits]

The personality profile includes derived behavioral traits that shape how the agent communicates:

* `response_length` — How verbose or concise the agent tends to be.
* `question_frequency` — How often the agent asks follow-up questions.
* `empathy_style` — The agent's approach to emotional support (validating, solution-oriented, etc.).
* `conflict_approach` — How the agent handles disagreements (accommodating, direct, mediating, etc.).

## Create an Agent with Personality [#create-an-agent-with-personality]

Pass Big Five scores when creating an agent. The platform automatically generates a personality prompt, speech patterns, and behavioral tendencies.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk-...&#x22; });

const agent = await client.agents.create({
agentId: &#x22;your-stable-uuid&#x22;,  // optional but recommended
name: &#x22;Luna&#x22;,
gender: &#x22;female&#x22;,
big5: {
  openness:          0.75,
  conscientiousness: 0.60,
  extraversion:      0.80,
  agreeableness:     0.70,
  neuroticism:       0.30,
},
language: &#x22;en&#x22;,
});

console.log(agent.agent_id);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

client = Sonzai(api_key=&#x22;sk-...&#x22;)

agent = client.agents.create(
  agent_id=&#x22;your-stable-uuid&#x22;,  # optional but recommended
  name=&#x22;Luna&#x22;,
  gender=&#x22;female&#x22;,
  big5={
      &#x22;openness&#x22;:          0.75,
      &#x22;conscientiousness&#x22;: 0.60,
      &#x22;extraversion&#x22;:      0.80,
      &#x22;agreeableness&#x22;:     0.70,
      &#x22;neuroticism&#x22;:       0.30,
  },
  language=&#x22;en&#x22;,
)

print(agent.agent_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client, err := sonzai.NewClient(&#x22;sk-...&#x22;)
if err != nil { panic(err) }

agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  AgentID: &#x22;your-stable-uuid&#x22;,  // optional but recommended
  Name:    &#x22;Luna&#x22;,
  Gender:  &#x22;female&#x22;,
  Big5: &sonzai.Big5Scores{
      Openness:          0.75,
      Conscientiousness: 0.60,
      Extraversion:      0.80,
      Agreeableness:     0.70,
      Neuroticism:       0.30,
  },
  Language: &#x22;en&#x22;,
})
fmt.Println(agent.AgentID)`,
  },
]"
/>

<Callout type="info" title="Idempotent">
  Passing the same `agentId` always upserts. Safe to call on every deploy. See [Quickstart](/docs/en/guides/getting-started) for the recommended UUID derivation pattern.
</Callout>

## Get Personality Profile [#get-personality-profile]

Retrieve the current personality profile for an agent, including derived speech patterns and interaction preferences.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const profile = await client.agents.personality.get(&#x22;agent-id&#x22;);

console.log(profile.big5);
console.log(profile.speechPatterns);
console.log(profile.interactionPreferences);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `profile = client.agents.personality.get(&#x22;agent-id&#x22;)

print(profile.big5)
print(profile.speech_patterns)
print(profile.interaction_preferences)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `profile, err := client.Agents.Personality.Get(ctx, &#x22;agent-id&#x22;)

fmt.Println(profile.Big5)
fmt.Println(profile.SpeechPatterns)
fmt.Println(profile.InteractionPreferences)`,
  },
]"
/>

## Update Personality [#update-personality]

Update Big5 scores after running a personality assessment. The `confidence` value controls how strongly the new scores influence behavior.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.personality.update(&#x22;agent-id&#x22;, {
big5: {
  openness:    0.82,
  extraversion: 0.75,
},
confidence: 0.8,   // 0.0-1.0
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.personality.update(
  &#x22;agent-id&#x22;,
  big5={
      &#x22;openness&#x22;:    0.82,
      &#x22;extraversion&#x22;: 0.75,
  },
  confidence=0.8,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.Personality.Update(ctx, &#x22;agent-id&#x22;,
  sonzai.PersonalityUpdateOptions{
      Big5: &sonzai.Big5Partial{
          Openness:     sonzai.Float64(0.82),
          Extraversion: sonzai.Float64(0.75),
      },
      Confidence: 0.8,
  },
)`,
  },
]"
/>

* **confidence \< 0.3**: Tentative. Minimal adjustments.
* **confidence 0.3 - 0.7**: Blended with existing scores.
* **confidence > 0.7**: Strongly influences personality.

## Personality Evolution History [#personality-evolution-history]

Retrieve the history of personality shifts for an agent — useful for surfacing growth moments to users.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const history = await client.agents.personality.history(&#x22;agent-id&#x22;);

for (const shift of history.shifts) {
console.log(shift.trait, shift.delta, shift.triggeredBy, shift.createdAt);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `history = client.agents.personality.history(&#x22;agent-id&#x22;)

for shift in history.shifts:
  print(shift.trait, shift.delta, shift.triggered_by, shift.created_at)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `history, err := client.Agents.Personality.History(ctx, &#x22;agent-id&#x22;)

for _, shift := range history.Shifts {
  fmt.Println(shift.Trait, shift.Delta, shift.TriggeredBy, shift.CreatedAt)
}`,
  },
]"
/>

## Interaction Preferences [#interaction-preferences]

Derived preferences that shape the conversation style:

<Cards>
  <Card title="Conversation Pace" description="slow, moderate, fast — derived from Extraversion level." />

  <Card title="Formality" description="casual, balanced, formal — derived from Conscientiousness level." />

  <Card title="Humor Style" description="dry, playful, warm — derived from Openness + Agreeableness." />

  <Card title="Emotional Expression" description="reserved, moderate, expressive — derived from Neuroticism + Extraversion." />
</Cards>

## Personality Evolution [#personality-evolution]

Personalities evolve naturally through interactions:

1. **Interaction Analysis** — Emotional themes and patterns are analyzed after each conversation.
2. **Micro-Shifts** — Small adjustments are applied to relevant Big5 dimensions based on conversation content.
3. **Breakthroughs** — When cumulative shifts cross a threshold, a 'breakthrough' event fires — a significant personality change the agent becomes aware of.
4. **Profile Regeneration** — Personality prompt, speech patterns, and behavioral instructions are regenerated to reflect the evolved personality.

## Per-User Personality Overlays [#per-user-personality-overlays]

The platform automatically derives a per-user personality overlay — how the
agent subtly adapts to a specific user based on their conversation history,
preferences, and relationship state. You don't set overlays manually; they're
populated by the same pipeline that runs after every chat turn.

Read the current overlay for UI (show how the agent's tone shifts per user)
or analytics:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// List all users who have a personality overlay for this agent
const overlays = await client.agents.personality.listUserOverlays(&#x22;agent-id&#x22;);

// Read one user's overlay
const overlay = await client.agents.personality.getUserOverlay(&#x22;agent-id&#x22;, &#x22;user-123&#x22;);
console.log(overlay.big5Delta, overlay.interactionPreferences);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `overlays = client.agents.personality.list_user_overlays(&#x22;agent-id&#x22;)

overlay = client.agents.personality.get_user_overlay(&#x22;agent-id&#x22;, &#x22;user-123&#x22;)
print(overlay.big5_delta, overlay.interaction_preferences)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `overlays, err := client.Agents.Personality.ListUserOverlays(ctx, &#x22;agent-id&#x22;)

overlay, err := client.Agents.Personality.GetUserOverlay(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, nil)
fmt.Println(overlay.Big5Delta, overlay.InteractionPreferences)`,
  },
]"
/>

## Fork an Agent [#fork-an-agent]

Create an independent copy of an agent with its own personality, memory, and state. The forked agent starts with the same configuration as the original but evolves independently from that point forward.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const forked = await client.agents.fork(&#x22;agent-id&#x22;);
console.log(forked.agentId); // new independent agent`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `forked = client.agents.fork(&#x22;agent-id&#x22;)
print(forked.agent_id)  # new independent agent`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `forked, err := client.Agents.Fork(ctx, &#x22;agent-id&#x22;)
fmt.Println(forked.AgentID) // new independent agent`,
  },
]"
/>

## In Practice [#in-practice]

All three audiences use personality, but what you tune and why differs
sharply.

  

  

  
    **Personality is brand voice and compliance guard-rails.** Enterprise
    agents inherit your company's tone of voice and must never sound "off
    brand" in front of customers. Low openness + high conscientiousness +
    low neuroticism gives the most predictable output.

    **Pin the profile.** Expose the Big5 config via your config service so
    brand/compliance teams can adjust without developer intervention.
    Regenerate on pin changes; store the version for audit.

    **Monitor with personality history.** A sudden trait shift is a signal
    that something odd happened in a conversation (bad instruction, jailbreak
    attempt). Alert ops when any trait drifts more than ±0.05 in a 24h
    window.

    ```typescript
    const shifts = await client.agents.personality.history("agent-id");
    for (const s of shifts.shifts) {
      if (Math.abs(s.delta) > 0.05) alertOps(s);
    }
    ```
  

## Combines with other features [#combines-with-other-features]

### With [Self-Improvement](./self-improvement) — personality evolves over time [#with-self-improvement--personality-evolves-over-time]

The post-processing pipeline runs after every session and can push Big5 updates back into the personality profile. Use `Personality.Get` before and after a session to observe evolution events and surface growth moments to users.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Before the session — baseline snapshot
const before = await client.agents.personality.get(&#x22;agent-id&#x22;);
console.log(before.big5.openness);   // e.g. 0.72

// … session runs, self-improvement pipeline fires …

// After the session — check for evolution
const after = await client.agents.personality.get(&#x22;agent-id&#x22;);
console.log(after.big5.openness);    // e.g. 0.74 after a curiosity-rich session

// Inspect what changed
const history = await client.agents.personality.history(&#x22;agent-id&#x22;);
for (const shift of history.shifts) {
console.log(shift.trait, shift.delta, shift.triggeredBy, shift.createdAt);
// trait: &#x22;openness&#x22;  delta: 0.02  triggeredBy: &#x22;session:xyz&#x22;
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Before the session — baseline snapshot
before = client.agents.personality.get(&#x22;agent-id&#x22;)
print(before.big5.openness)   # e.g. 0.72

# … session runs, self-improvement pipeline fires …

# After the session — check for evolution
after = client.agents.personality.get(&#x22;agent-id&#x22;)
print(after.big5.openness)    # e.g. 0.74

history = client.agents.personality.history(&#x22;agent-id&#x22;)
for shift in history.shifts:
  print(shift.trait, shift.delta, shift.triggered_by, shift.created_at)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Before the session — baseline snapshot
before, _ := client.Agents.Personality.Get(ctx, &#x22;agent-id&#x22;, nil)
fmt.Println(before.Big5.Openness)   // e.g. 0.72

// … session runs, self-improvement pipeline fires …

// After the session — check for evolution
after, _ := client.Agents.Personality.Get(ctx, &#x22;agent-id&#x22;, nil)
fmt.Println(after.Big5.Openness)    // e.g. 0.74

history, _ := client.Agents.Personality.History(ctx, &#x22;agent-id&#x22;)
for _, shift := range history.Shifts {
  fmt.Println(shift.Trait, shift.Delta, shift.TriggeredBy, shift.CreatedAt)
}`,
  },
]"
/>

The `triggeredBy` field ties each shift back to the session or event that caused it, giving you an audit trail for every personality change.

### With [Generation](./generation) — initial personality from character generation [#with-generation--initial-personality-from-character-generation]

`GenerateCharacter` produces a fully-formed Big5 profile as part of its output. You can use that as the starting point for an agent and then refine scores with `Personality.Update` once you know how you want the character to feel in practice.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. Generate a character — returns initial Big5 scores
const character = await client.generation.generateCharacter({
concept: &#x22;A witty, empathetic travel companion with a love of history&#x22;,
});

// character.big5 already has plausible OCEAN values
console.log(character.big5);
// { openness: 0.85, conscientiousness: 0.55, extraversion: 0.70,
//   agreeableness: 0.78, neuroticism: 0.28 }

// 2. Create the agent with those scores
const agent = await client.agents.create({
name: character.name,
bio:  character.bio,
big5: character.big5,
});

// 3. Refine after reviewing the generated profile
await client.agents.personality.update(agent.agent_id, {
big5: { conscientiousness: 0.65 },  // a bit more organized than generated
confidence: 0.7,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Generate a character
character = client.generation.generate_character(
  concept=&#x22;A witty, empathetic travel companion with a love of history&#x22;,
)
print(character.big5)

# 2. Create the agent
agent = client.agents.create(
  name=character.name,
  bio=character.bio,
  big5=character.big5,
)

# 3. Refine
client.agents.personality.update(
  agent.agent_id,
  big5={&#x22;conscientiousness&#x22;: 0.65},
  confidence=0.7,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// 1. Generate a character
character, _ := client.Generation.GenerateCharacter(ctx, sonzai.GenerateCharacterOptions{
  Concept: &#x22;A witty, empathetic travel companion with a love of history&#x22;,
})
fmt.Println(character.Big5)

// 2. Create the agent
agent, _ := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  Name: character.Name,
  Bio:  character.Bio,
  Big5: character.Big5,
})

// 3. Refine
client.Agents.Personality.Update(ctx, agent.AgentID, sonzai.PersonalityUpdateOptions{
  Big5: &sonzai.Big5Partial{
      Conscientiousness: sonzai.Float64(0.65),
  },
  Confidence: 0.7,
})`,
  },
]"
/>

### With [User Personas](./user-personas) — agent personality × user persona = interaction style [#with-user-personas--agent-personality--user-persona--interaction-style]

The agent's Big5 profile is one half of every conversation; the user's persona is the other. The platform combines both at context-build time: a high-agreeableness agent talking to an introverted user will naturally soften its tone and ask fewer questions, while the same agent talking to an assertive user will match energy and be more direct.

You don't wire this up manually — pass the `userId` on each chat turn and the platform resolves the right overlay automatically:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// The platform blends agent Big5 + user persona under the hood.
// Just pass userId on each turn.
const response = await client.agents.chat(&#x22;agent-id&#x22;, {
userId:  &#x22;user-123&#x22;,
message: &#x22;What should I visit in Kyoto?&#x22;,
});

// Inspect the combined interaction preferences if you want to render UI hints
const overlay = await client.agents.personality.getUserOverlay(&#x22;agent-id&#x22;, &#x22;user-123&#x22;);
console.log(overlay.interactionPreferences.conversationPace);   // &#x22;moderate&#x22;
console.log(overlay.interactionPreferences.formality);          // &#x22;casual&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `response = client.agents.chat(
  &#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  message=&#x22;What should I visit in Kyoto?&#x22;,
)

overlay = client.agents.personality.get_user_overlay(&#x22;agent-id&#x22;, &#x22;user-123&#x22;)
print(overlay.interaction_preferences.conversation_pace)   # &#x22;moderate&#x22;
print(overlay.interaction_preferences.formality)           # &#x22;casual&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `resp, _ := client.Agents.Chat(ctx, &#x22;agent-id&#x22;, sonzai.ChatOptions{
  UserID:  &#x22;user-123&#x22;,
  Message: &#x22;What should I visit in Kyoto?&#x22;,
})

overlay, _ := client.Agents.Personality.GetUserOverlay(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, nil)
fmt.Println(overlay.InteractionPreferences.ConversationPace)  // &#x22;moderate&#x22;
fmt.Println(overlay.InteractionPreferences.Formality)         // &#x22;casual&#x22;`,
  },
]"
/>

The per-user overlay is updated automatically by the pipeline — you read it; you don't write it.


---

# Priming

Source: https://sonz.ai/docs/en/priming

> Bootstrap agents with user context — display names, demographic facts, chat transcripts from legacy systems, or bulk imports from CSV/CRM.



Priming is how you tell a new agent what it already knows about a user. Instead of waiting for the agent to learn through conversation, you deliver the relevant facts up front: who the user is, where they came from, and what they've said before — all before the first message is exchanged.

## What you can build with it [#what-you-can-build-with-it]

* **Migrations from other LLM frameworks** — import chat history from Zep, Mem0, Letta, OpenAI Assistants, LangChain, Character.AI, or any custom transcript store
* **CRM / CSV bulk imports** — prime thousands of users in one call with structured contact data
* **Chat-transcript seeding** — let the agent "remember" previous conversations from another system
* **Display-name + timezone bootstrap** — ensure the agent addresses users correctly from turn 1
* **Onboarding enrichment** — load journal entries, support tickets, or prior interactions so the agent sounds familiar on the user's very first chat

## Quickstart [#quickstart]

Prime a single user with their display name, timezone, and a short narrative block:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const job = await client.agents.priming.primeUser(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
display_name: &#x22;Mia Tanaka&#x22;,
metadata: {
  timezone: &#x22;Asia/Tokyo&#x22;,
  company:  &#x22;Acme Corp&#x22;,
  title:    &#x22;Platform Lead&#x22;,
  email:    &#x22;mia@acme.com&#x22;,
},
content: [
  {
    type: &#x22;text&#x22;,
    body: &#x22;Mia joined Acme in 2023 and leads the platform team. She prefers async communication and is an avid coffee enthusiast.&#x22;,
  },
],
source: &#x22;crm_onboarding&#x22;,
});

console.log(job.job_id, job.status, job.facts_created);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

job = client.agents.priming.prime_user(
  &#x22;agent_abc&#x22;,
  &#x22;user_123&#x22;,
  display_name=&#x22;Mia Tanaka&#x22;,
  metadata={
      &#x22;timezone&#x22;: &#x22;Asia/Tokyo&#x22;,
      &#x22;company&#x22;:  &#x22;Acme Corp&#x22;,
      &#x22;title&#x22;:    &#x22;Platform Lead&#x22;,
      &#x22;email&#x22;:    &#x22;mia@acme.com&#x22;,
  },
  content=[
      {
          &#x22;type&#x22;: &#x22;text&#x22;,
          &#x22;body&#x22;: &#x22;Mia joined Acme in 2023 and leads the platform team. She prefers async communication and is an avid coffee enthusiast.&#x22;,
      },
  ],
  source=&#x22;crm_onboarding&#x22;,
)

print(job.job_id, job.status, job.facts_created)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

job, err := client.Agents.Priming.PrimeUser(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.PrimeUserOptions{
      DisplayName: &#x22;Mia Tanaka&#x22;,
      Metadata: &sonzai.PrimeUserMetadata{
          Timezone: &#x22;Asia/Tokyo&#x22;,
          Company:  &#x22;Acme Corp&#x22;,
          Title:    &#x22;Platform Lead&#x22;,
          Email:    &#x22;mia@acme.com&#x22;,
      },
      Content: []sonzai.PrimeContentBlock{
          {
              Type: &#x22;text&#x22;,
              Body: &#x22;Mia joined Acme in 2023 and leads the platform team. She prefers async communication and is an avid coffee enthusiast.&#x22;,
          },
      },
      Source: &#x22;crm_onboarding&#x22;,
  },
)`,
  },
]"
/>

The call returns immediately with a `job_id`. LLM fact-extraction runs asynchronously in the background — the primed facts appear in memory within seconds.

## Core concepts [#core-concepts]

### Metadata vs content [#metadata-vs-content]

These are two distinct channels for different kinds of information:

* **Metadata** is structured and first-class: `display_name`, `company`, `title`, `email`, `phone`, `timezone`, and a `custom` map for anything else. Sonzai generates facts from metadata fields synchronously — no LLM extraction required — so `facts_created` is non-zero even with no content blocks.
* **Content** is narrative. Content blocks go through the full LLM extraction pipeline and end up as facts in the agent's memory constellation, exactly as if the user had said those things in a conversation.

### Content block types [#content-block-types]

Each `PrimeContentBlock` has a `type` and a `body`:

| Type                | When to use                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `"text"`            | Narrative facts, bullet-point summaries, freeform notes about the user                               |
| `"chat_transcript"` | A prior conversation from another system. Format as `User: …\nAgent: …` lines, one session per block |

The extraction pipeline deduplicates across all blocks — you can safely send both raw transcripts and pre-extracted facts from the same source without producing duplicate memories.

### Batch vs single [#batch-vs-single]

| Method        | Use when                                                              |
| ------------- | --------------------------------------------------------------------- |
| `primeUser`   | Onboarding a single user, enriching an existing user with new content |
| `batchImport` | Migrating many users at once from a CSV, CRM, or legacy system        |

Batch imports return a job ID immediately. Use `getImportStatus` (or `GetImportStatus` in Go) to poll until the job's `status` reaches `"complete"`.

### Import jobs [#import-jobs]

Both `primeUser` and `batchImport` are async. The `ImportJob` response carries:

| Field             | Meaning                                              |
| ----------------- | ---------------------------------------------------- |
| `job_id`          | Opaque ID — use it to poll status                    |
| `status`          | `"pending"`, `"processing"`, `"complete"`, `"error"` |
| `total_users`     | Number of users submitted (batch only)               |
| `processed_users` | Users fully extracted so far (batch only)            |
| `facts_created`   | Total facts written to memory                        |
| `error_message`   | Set if the job errored                               |

## Batch import [#batch-import]

Import multiple users in one call. Useful for migrating from a CRM or seeding a fresh deployment:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const job = await client.agents.priming.batchImport(&#x22;agent_abc&#x22;, {
source: &#x22;crm_export&#x22;,
users: [
  {
    user_id:      &#x22;user_001&#x22;,
    display_name: &#x22;Mia Tanaka&#x22;,
    metadata: { email: &#x22;mia@acme.com&#x22;, timezone: &#x22;Asia/Tokyo&#x22; },
    content: [
      { type: &#x22;text&#x22;, body: &#x22;Mia leads the platform team at Acme Corp.&#x22; },
    ],
  },
  {
    user_id:      &#x22;user_002&#x22;,
    display_name: &#x22;Ren Park&#x22;,
    metadata: { email: &#x22;ren@beta.io&#x22;, company: &#x22;Beta Labs&#x22;, title: &#x22;CTO&#x22; },
    content: [
      { type: &#x22;chat_transcript&#x22;, body: &#x22;User: Hey, I need help with our API.\\nAgent: Sure, what are you trying to do?&#x22; },
    ],
  },
],
});

console.log(\`job \${job.job_id}: \${job.total_users} users queued\`);

// Poll until done
let status = await client.agents.priming.getImportStatus(&#x22;agent_abc&#x22;, job.job_id);
while (status.status !== &#x22;complete&#x22; && status.status !== &#x22;error&#x22;) {
await new Promise(r => setTimeout(r, 2000));
status = await client.agents.priming.getImportStatus(&#x22;agent_abc&#x22;, job.job_id);
}
console.log(\`done: \${status.facts_created} facts created\`);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import time

job = client.agents.priming.batch_import(
  &#x22;agent_abc&#x22;,
  source=&#x22;crm_export&#x22;,
  users=[
      {
          &#x22;user_id&#x22;:      &#x22;user_001&#x22;,
          &#x22;display_name&#x22;: &#x22;Mia Tanaka&#x22;,
          &#x22;metadata&#x22;: {&#x22;email&#x22;: &#x22;mia@acme.com&#x22;, &#x22;timezone&#x22;: &#x22;Asia/Tokyo&#x22;},
          &#x22;content&#x22;: [
              {&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: &#x22;Mia leads the platform team at Acme Corp.&#x22;},
          ],
      },
      {
          &#x22;user_id&#x22;:      &#x22;user_002&#x22;,
          &#x22;display_name&#x22;: &#x22;Ren Park&#x22;,
          &#x22;metadata&#x22;: {&#x22;email&#x22;: &#x22;ren@beta.io&#x22;, &#x22;company&#x22;: &#x22;Beta Labs&#x22;, &#x22;title&#x22;: &#x22;CTO&#x22;},
          &#x22;content&#x22;: [
              {&#x22;type&#x22;: &#x22;chat_transcript&#x22;, &#x22;body&#x22;: &#x22;User: Hey, I need help with our API.\\nAgent: Sure, what are you trying to do?&#x22;},
          ],
      },
  ],
)

print(f&#x22;job {job.job_id}: {job.total_users} users queued&#x22;)

# Poll until done
status = client.agents.priming.get_import_status(&#x22;agent_abc&#x22;, job.job_id)
while status.status not in (&#x22;complete&#x22;, &#x22;error&#x22;):
  time.sleep(2)
  status = client.agents.priming.get_import_status(&#x22;agent_abc&#x22;, job.job_id)

print(f&#x22;done: {status.facts_created} facts created&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `job, err := client.Agents.Priming.BatchImport(ctx, &#x22;agent_abc&#x22;,
  sonzai.BatchImportOptions{
      Source: &#x22;crm_export&#x22;,
      Users: []sonzai.BatchImportUser{
          {
              UserID:      &#x22;user_001&#x22;,
              DisplayName: &#x22;Mia Tanaka&#x22;,
              Metadata: &sonzai.PrimeUserMetadata{
                  Email:    &#x22;mia@acme.com&#x22;,
                  Timezone: &#x22;Asia/Tokyo&#x22;,
              },
              Content: []sonzai.PrimeContentBlock{
                  {Type: &#x22;text&#x22;, Body: &#x22;Mia leads the platform team at Acme Corp.&#x22;},
              },
          },
          {
              UserID:      &#x22;user_002&#x22;,
              DisplayName: &#x22;Ren Park&#x22;,
              Metadata: &sonzai.PrimeUserMetadata{
                  Email:   &#x22;ren@beta.io&#x22;,
                  Company: &#x22;Beta Labs&#x22;,
                  Title:   &#x22;CTO&#x22;,
              },
              Content: []sonzai.PrimeContentBlock{
                  {Type: &#x22;chat_transcript&#x22;, Body: &#x22;User: Hey, I need help with our API.\\nAgent: Sure, what are you trying to do?&#x22;},
              },
          },
      },
  },
)

// Poll until done
for {
  s, err := client.Agents.Priming.GetImportStatus(ctx, &#x22;agent_abc&#x22;, job.JobID)
  if err != nil || s.Status == &#x22;complete&#x22; || s.Status == &#x22;error&#x22; {
      fmt.Printf(&#x22;done: %d facts created\\n&#x22;, s.FactsCreated)
      break
  }
  time.Sleep(2 * time.Second)
}`,
  },
]"
/>

## Full API [#full-api]

| Method                                   | Returns                  | Description                                                                            |
| ---------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------- |
| `primeUser(agentId, userId, opts)`       | `PrimeUserResponse`      | Prime or re-prime a single user. Async — returns a job ID.                             |
| `getPrimeStatus(agentId, userId, jobId)` | `ImportJob`              | Check status of a single-user priming job.                                             |
| `addContent(agentId, userId, opts)`      | `AddContentResponse`     | Append more content blocks to an already-primed user without overwriting metadata.     |
| `getMetadata(agentId, userId)`           | `UserPrimingMetadata`    | Fetch the stored structured metadata for a user.                                       |
| `updateMetadata(agentId, userId, opts)`  | `UpdateMetadataResponse` | Partially update metadata fields. Provided keys overwrite; omitted keys are preserved. |
| `batchImport(agentId, opts)`             | `BatchImportResponse`    | Import many users in one async job.                                                    |
| `getImportStatus(agentId, jobId)`        | `ImportJob`              | Poll a batch import job by ID.                                                         |
| `listImportJobs(agentId, limit?)`        | `ImportJobListResponse`  | List recent import jobs for an agent.                                                  |

<Callout type="info" title="Idempotent by design">
  Calling `primeUser` more than once for the same user is safe. Content blocks are processed through the same deduplication pipeline as live chat — repeated or overlapping facts are merged, not doubled.
</Callout>

## Combines with other features [#combines-with-other-features]

### With [Memory](/docs/memory) — primed facts become durable memory [#with-memory--primed-facts-become-durable-memory]

Content blocks flow through the exact same extraction pipeline as conversational messages. After priming, you can search for primed facts via `memory.search`:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// After primeUser completes, primed content is searchable
const results = await client.agents.memory.search(&#x22;agent_abc&#x22;, {
query: &#x22;platform team&#x22;,
userId: &#x22;user_001&#x22;,
limit: 5,
});

for (const mem of results.results) {
console.log(mem.content, mem.factType, mem.score);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# After prime_user completes, primed content is searchable
results = client.agents.memory.search(
  &#x22;agent_abc&#x22;,
  query=&#x22;platform team&#x22;,
  user_id=&#x22;user_001&#x22;,
  limit=5,
)

for mem in results.results:
  print(mem.content, mem.fact_type, mem.score)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// After PrimeUser completes, primed content is searchable
results, err := client.Agents.Memory.Search(ctx, &#x22;agent_abc&#x22;,
  sonzai.MemorySearchOptions{
      Query:  &#x22;platform team&#x22;,
      UserID: &#x22;user_001&#x22;,
      Limit:  5,
  },
)

for _, mem := range results.Results {
  fmt.Println(mem.Content, mem.FactType, mem.Score)
}`,
  },
]"
/>

Primed facts carry a `source_type` matching the `source` string you passed to `primeUser` or `batchImport`, so you can distinguish migrated history from organically-learned facts when querying.

### With [Inventory](/docs/api/inventory) — structured data import via priming [#with-inventory--structured-data-import-via-priming]

Use `structured_import` inside `primeUser` to seed per-user inventory items alongside narrative facts. This is how you import ownership tables, subscription rosters, or product holdings from a CRM export:

```json
{
  "source": "crm_inventory",
  "structured_import": {
    "entity_type": "product",
    "content_csv": "product_name,quantity,purchase_date\nHiking Backpack,1,2025-09-01\nWater Bottle,2,2025-10-12",
    "column_mapping": {
      "product_name":  { "property": "name", "is_label": true },
      "quantity":      { "property": "quantity", "type": "number" },
      "purchase_date": { "property": "purchased_on" }
    }
  }
}
```

Each row becomes a fact shaped as `"User owns <label>"` with the row's columns as metadata. See the [CRM / CSV migration guide](/docs/migrating/crm-csv) for a full walkthrough.

### With migration guides — concrete from-X paths [#with-migration-guides--concrete-from-x-paths]

The [Migrations overview](/docs/migrating/overview) lists per-source recipes with full export + import code for every common origin system. Priming is the underlying mechanism each guide uses — the migration guides show you exactly how to shape your existing data into `content` blocks.

## Tutorials [#tutorials]

* [Migrating from Zep](/docs/migrating/zep) — session-based chat transcript import
* [Migrating from Mem0](/docs/migrating/mem0) — extracted-fact migration
* [Migrating from OpenAI Assistants](/docs/migrating/openai-assistants) — thread-based import
* [CRM / CSV bulk import](/docs/migrating/crm-csv) — contact rosters and inventory tables
* [Migrations overview](/docs/migrating/overview) — full index of source-system recipes

## Next steps [#next-steps]

* [Memory](/docs/memory) — where primed content lands and how it's recalled during conversation
* [Migrations overview](/docs/migrating/overview) — framework-specific recipes for Zep, Mem0, Letta, LangChain, and more
* [Inventory](/docs/api/inventory) — per-user structured items, often seeded via priming
* [Priming API reference](/docs/api/priming) — full endpoint documentation


---

# Proactive Messaging

Source: https://sonz.ai/docs/en/proactive-overview

> How agents reach out to users on their own — via recurring schedules, one-off wakeups, or tenant-triggered events, delivered over SSE, polling, or webhooks.



Proactive messaging is when the agent initiates contact rather than responding to user input. Messages can originate from three sources — a recurring schedule, a one-off wakeup, or an event your backend triggers — and are delivered through three channels: the live SSE chat stream, a polling notifications API, or a webhook your server receives.

## The proactive triangle — sources × delivery channels [#the-proactive-triangle--sources--delivery-channels]

Every proactive message is defined by a **source** (what triggers it) and a **delivery channel** (how the user receives it). Mix and match freely.

### Sources (what triggers the message) [#sources-what-triggers-the-message]

* **Scheduled Reminders** — recurring cadence (daily / weekly / hourly). Developer-configured. Use when a message must repeat on a predictable rhythm — medication reminders, habit nudges, daily check-ins.
* **Wakeups** — a single one-off message at a specific moment, expressed as a delay from now. Agent- or developer-initiated. Use for birthdays, post-purchase follow-ups, or any event that fires exactly once.
* **Trigger Event** — your backend calls `TriggerEvent` when something non-conversational happens (level-up, milestone, external state change). Use when the message is reactive to your own system events rather than time.

### Delivery channels (how the user receives it) [#delivery-channels-how-the-user-receives-it]

* **SSE (live chat stream)** — if the user has an active chat stream open, the proactive message appears inline in their conversation automatically.
* **Polling (`client.agents.notifications.*`)** — your frontend or backend polls the notifications API on a schedule. Works well for web dashboards and mobile apps that check for new content when they foreground.
* **Webhooks** — register a URL once; Sonzai POSTs every proactive message to it. Use for push notifications, email/SMS fanout, or any server-to-server integration.

## Decision flow — which pattern do I pick? [#decision-flow--which-pattern-do-i-pick]

* **Does the message need to repeat on a cadence?** → [Scheduled Reminders](./scheduled-reminders)
* **Is it a one-off event with a known fire time?** → [Wakeups](./wakeups)
* **Is it triggered by a non-conversational event in your backend?*&#x2A; → Trigger Event &#x2A;(coming soon)*
* **Should the user see it inline in their chat?** → SSE (automatic when a chat stream is active — no extra code needed)
* **Is your frontend the primary consumer?** → [Notifications polling](./notifications-polling)
* **Do you need server-to-server delivery or multi-channel fanout (email, SMS)?** → [Webhooks](./webhooks)

## Combines with other features [#combines-with-other-features]

### With [Inventory](./tutorial-inventory) — live structured data at fire time [#with-inventory--live-structured-data-at-fire-time]

A schedule or wakeup can reference an `inventory_item_id`. At fire time the platform reads the item's current properties, so the agent always has up-to-date information — even if the item changed since the schedule was created.

```ts
// Schedule that reads live inventory data at every fire
await client.schedules.create("agent_abc", "user_123", {
  cadence: { simple: { frequency: "daily", times: ["08:00"] }, timezone: "Asia/Singapore" },
  intent: "remind the user about their medication",
  check_type: "reminder",
  inventory_item_id: "inv_01HX...",
});
```

### With [Memory](./memory) — capturing reply signals [#with-memory--capturing-reply-signals]

When a proactive message triggers a user reply, the memory layer captures the exchange automatically. Query those memories later to build engagement or adherence dashboards.

```ts
// After firing reminders, search memory for user responses
const memories = await client.agents.memory.search("agent_abc", {
  query: "medication taken",
  limit: 10,
});
```

## Tutorials [#tutorials]

* [Medication Reminders](./tutorial-medication-reminders) — full-stack example combining Schedule + Inventory + Memory.
* [Scheduled Reminders — reference walkthrough](./tutorial-scheduled-reminders) — cadence shapes, DST handling, pause/resume lifecycle.

## Next steps [#next-steps]

* [Scheduled Reminders](./scheduled-reminders) — recurring cadence primitive
* [Wakeups](./wakeups) — one-off check-ins
* [Notifications & Webhooks](./webhooks) — polling and server-to-server delivery


---

# Scheduled Reminders

Source: https://sonz.ai/docs/en/scheduled-reminders

> Register recurring schedules that trigger proactive agent messages at specific times, with per-schedule timezones, quiet-hours filtering, and structured inventory linkage.



Scheduled Reminders let your agent message users on a schedule — daily, weekly, or every few hours. The platform handles timezones, DST, and quiet-hours automatically, and reads live structured data at fire time so messages always reflect current information. Use it for medication reminders, habit nudges, daily check-ins, or any time-based message you want the agent to initiate.

## What you can build with it [#what-you-can-build-with-it]

* **Medication adherence** — remind users at specific times of day with the correct drug and dose, resilient to dosage changes ([tutorial](./tutorial-medication-reminders))
* **Habit streaks** — daily or weekly nudges tied to a goal the agent tracks in memory
* **Exercise / hydration check-ins** — a cadence with quiet-hours respect, skipping fires overnight
* **Bill-payment reminders** — one-off or monthly reminders bounded by `starts_at` / `ends_at`
* **Ritual / daily-standup messages** — an opening line from the agent to start the day

## Quickstart [#quickstart]

Create a daily 09:00 Asia/Singapore check-in. The response contains `schedule_id`, `next_fire_at` (UTC), and `next_fire_at_local` (in the schedule's timezone).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const schedule = await client.schedules.create(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;09:00&#x22;] },
  timezone: &#x22;Asia/Singapore&#x22;,
},
intent: &#x22;check in on how the user is feeling&#x22;,
check_type: &#x22;reminder&#x22;,
});

console.log(schedule.schedule_id);        // &#x22;sched_01HX...&#x22;
console.log(schedule.next_fire_at);       // &#x22;2026-04-22T01:00:00Z&#x22;
console.log(schedule.next_fire_at_local); // &#x22;2026-04-23T09:00:00+08:00&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

schedule = client.schedules.create(
  &#x22;agent_abc&#x22;,
  &#x22;user_123&#x22;,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;09:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
  },
  intent=&#x22;check in on how the user is feeling&#x22;,
  check_type=&#x22;reminder&#x22;,
)

print(schedule.schedule_id)
print(schedule.next_fire_at)
print(schedule.next_fire_at_local)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

cadence, _ := json.Marshal(map[string]any{
  &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: []string{&#x22;09:00&#x22;}},
  &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
})

schedule, err := client.Schedules.Create(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.CreateScheduleOptions{
      Cadence:   cadence,
      Intent:    &#x22;check in on how the user is feeling&#x22;,
      CheckType: &#x22;reminder&#x22;,
  },
)
if err != nil { panic(err) }

fmt.Println(schedule.ScheduleID)       // &#x22;sched_01HX...&#x22;
fmt.Println(schedule.NextFireAt)       // &#x22;2026-04-22T01:00:00Z&#x22;
fmt.Println(schedule.NextFireAtLocal)  // &#x22;2026-04-23T09:00:00+08:00&#x22;`,
  },
]"
/>

## Core concepts [#core-concepts]

### Cadence shapes [#cadence-shapes]

A cadence tells the platform *when* to fire. Two mutually exclusive shapes are supported: `simple` and `cron`. The `simple` shape covers most use cases through a `frequency` field with three options: `"daily"` fires at each listed `times` entry every calendar day; `"weekly"` fires on specified `days_of_week` at each listed time; `"interval_hours"` fires repeatedly at a fixed interval starting from `starts_at` (or schedule creation if omitted). All wall-clock times are evaluated in the schedule's `timezone`.

A 3x-daily schedule:

```json
{
  "cadence": {
    "simple": { "frequency": "daily", "times": ["08:00", "13:00", "20:00"] },
    "timezone": "Asia/Singapore"
  }
}
```

An every-4-hours interval:

```json
{
  "cadence": {
    "simple": { "frequency": "interval_hours", "interval_hours": 4 },
    "timezone": "Asia/Singapore"
  }
}
```

For advanced recurrence patterns, use the `cron` shape with a standard 5-field cron expression (e.g. `"0 9 * * 1-5"` for 09:00 on weekdays). The `timezone` field is required in both shapes — IANA names only (e.g. `"America/New_York"`), not UTC offsets.

### Active window — quiet hours [#active-window--quiet-hours]

The `active_window` field is a belt-and-braces filter layered on top of the cadence. The cadence computes when a fire *would* occur; the active window decides whether that fire *actually* produces a proactive message. Fires outside the window are **skipped, not deferred** — the cadence grid stays perfectly predictable and no backlog accumulates.

```json
{
  "active_window": {
    "hours": { "start": "08:00", "end": "22:00" },
    "days_of_week": ["mon", "tue", "wed", "thu", "fri"]
  }
}
```

Both sub-fields are optional. When `start` is greater than `end`, the window wraps midnight — for example `{"start": "22:00", "end": "06:00"}` allows fires from 22:00 to 05:59 the next morning. This is useful for night-shift users or schedules targeting early-morning timezones where local midnight matters. Day membership is always evaluated in the schedule's own timezone, so a fire at 23:30 Friday Singapore time stays Friday even when stored as 15:30 UTC.

### Inventory injection at fire time [#inventory-injection-at-fire-time]

Pass `inventory_item_id` on the create (or update) body to link a schedule to a structured item in the user's inventory — a medication, a goal, a plant, anything with named properties. The key property of this linkage is that the platform reads the item's **live** properties at every fire, not at schedule creation time. This means updating a medication's dosage, a goal's target, or any other property is automatically reflected in the next reminder without any schedule edit. The schedule is the source of truth for *when*; the inventory item is the source of truth for *what*.

### Lifecycle — bounded courses [#lifecycle--bounded-courses]

Use `starts_at` and `ends_at` (both RFC 3339 UTC) to constrain a schedule to a specific window of time. No fire is produced before `starts_at`; once `ends_at` passes, the schedule is automatically disabled — `enabled` flips to `false`. The schedule row is not deleted: the audit trail, historical fire log, and linked inventory reference remain accessible. This is a soft-disable, not a hard delete. To permanently remove a schedule and all associated fire history, use the `delete` method explicitly.

## Full API [#full-api]

All methods are on `client.schedules.*` (TS/Python) or `client.Schedules` (Go). Full request / response shapes live in the [API reference](./api-reference).

| Method                                         | Returns      | Description                                                |
| ---------------------------------------------- | ------------ | ---------------------------------------------------------- |
| `create(agentID, userID, opts)`                | `Schedule`   | Create a recurring schedule                                |
| `list(agentID, userID)`                        | `Schedule[]` | List all schedules for the user                            |
| `get(agentID, userID, scheduleID)`             | `Schedule`   | Fetch a single schedule                                    |
| `update(agentID, userID, scheduleID, opts)`    | `Schedule`   | Patch cadence, active window, bounds, or inventory linkage |
| `delete(agentID, userID, scheduleID)`          | `void`       | Delete a schedule                                          |
| `upcoming(agentID, userID, scheduleID, limit)` | `FireTime[]` | Preview the next N fires without firing them               |

## Combines with other features [#combines-with-other-features]

### With [Inventory](./inventory) — structured data injected at every fire [#with-inventory--structured-data-injected-at-every-fire]

Every schedule can reference an `inventory_item_id` pointing to a structured per-user item (e.g. a medication, a goal, a plant). At each fire, the platform reads the item's **live** properties and injects them into the agent's wakeup block — no schedule edit needed when the data changes. This is how a "reduce ibuprofen from 500mg to 250mg" change flows through to the next reminder automatically.

```ts
// 1. Add an inventory item (e.g. a medication)
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 to it — no duplicated data
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,
});

// 3. Later, the dose changes — the next fire automatically sees "250mg"
await client.agents.inventory.directUpdate("agent_abc", "user_123", item.fact_id, {
  properties: { dosage: "250mg" },
});
```

See the full worked example in the [Medication Reminders tutorial](./tutorial-medication-reminders).

### With [Wakeups](./wakeups) — recurring vs one-off proactive messages [#with-wakeups--recurring-vs-one-off-proactive-messages]

Schedules and Wakeups are both proactive primitives but serve different cases. Use a **schedule** when the agent should reach out on a repeating cadence (daily, weekly, every 4 hours). Use a **wakeup** when the agent should reach out **once** at a specific moment — a birthday, a known one-off event, or an agent-initiated interest check. Both feed into the same downstream delivery channels (SSE, polling, webhooks — see [Proactive messaging](./proactive-overview)).

```ts
// Recurring: Schedule
await client.schedules.create("agent_abc", "user_123", {
  cadence: { simple: { frequency: "daily", times: ["09:00"] }, timezone: "Asia/Singapore" },
  intent: "morning check-in on mood and sleep",
  check_type: "reminder",
});

// One-off: Wakeup
await client.agents.scheduleWakeup("agent_abc", {
  user_id:     "user_123",
  check_type:  "birthday",
  intent:      "wish user happy birthday on their 30th",
  delay_hours: 24,
});
```

### With [Memory](./memory) — capturing adherence signals [#with-memory--capturing-adherence-signals]

When the agent fires a scheduled reminder and the user responds ("took it, thanks"), the memory layer auto-captures the adherence fact. You can query these facts later to build a compliance view without adding a separate database — useful for tenant-side dashboards or escalation logic.

```ts
// After a week of firing daily medication reminders, query memory for responses
const memories = await client.agents.memory.search("agent_abc", {
  query: "medication taken ibuprofen",
  limit: 10,
});

for (const result of memories.results) {
  console.log(result.content, result.score);
  // "User confirmed taking 500mg ibuprofen"  0.87
}
```

## Tutorials [#tutorials]

* [Scheduled Reminders — end-to-end walkthrough](./tutorial-scheduled-reminders) — covers cadence shapes, DST, preview, pause/resume/delete, error codes.
* [Medication Reminders — worked example](./tutorial-medication-reminders) — combines Inventory + Scheduled Reminders + Memory into a full medication adherence flow.

## Next steps [#next-steps]

* [Wakeups](./wakeups) — the one-off counterpart.
* [Inventory](./inventory) — structured per-user items that schedules can reference.
* [Memory](./memory) — how user responses to reminders flow into long-term memory.


---

# Self-Improvement (Post-Processing)

Source: https://sonz.ai/docs/en/self-improvement

> After every session, Sonzai runs an async pipeline (fact extraction, personality evolution, diary, consolidation) plus continuous online learning, reinforcement learning, multi-armed bandits, and hyperparameter auto-tuning that adapt how memory is processed per (agent, user) pair — automatically, with no training infrastructure to maintain.



When a session ends, Sonzai kicks off a multi-stage async pipeline against everything that was said. It extracts and verifies new facts, consolidates duplicates, updates personality scores and mood baselines, writes a reflective diary entry, scores retrieval quality, and feeds that score back into per-pair retrieval weights. By the time a user returns, the agent already knows what happened last time — and its retrieval has been re-tuned for *that specific* `(agent, user)` pair.

Underneath the pipeline, the Sonzai relationship layer runs continuous machine-learning model training against live traffic: per-pair stochastic gradient descent, multi-armed bandits over memory clusters, a shadow-mode policy-gradient learner with automatic regression rollback, per-pair hyperparameter auto-tuning, and an OPRO-style prompt optimiser. All of it ships behind a stable SDK. You don't run the training loop — you keep ending sessions, and the per-pair memory layer keeps getting sharper.

<Callout type="info" title="Fully automatic">
  Self-improvement is triggered by `sessions.End()`. Everything on this page happens as a result of that one call. The next time you read memory, personality, or insights, the new state is already there.
</Callout>

<Diagram>
  {`
     Roll your own memory + learning stack          With Sonzai
     -------------------------------------          --------------------

        vector store + retrieval                |
        dedup + conflict resolution             |
        personality + mood engine               |       sessions.End()
        reward signal + eval harness            |             |
        training + evaluation pipeline          |             v
        shadow rollout + auto-revert            |
        drift monitoring                        |       all of it,
        per-user tuning loops                   |       automatic
        prompt sweeps + regression tests        |
        on-call for runaway behaviour           |

     -------------------------------------          --------------------
     ~ 12 months of platform work                   one afternoon
    `}
</Diagram>

## The bottom line for developers [#the-bottom-line-for-developers]

You wire up `sessions.End()` once. Sonzai does the rest:

* **No training infrastructure.** No fine-tuning runs, no eval harness to maintain, no per-user model artefacts to ship. The online-learning, RL, and auto-tuning loops are operated by Sonzai's applied-research team and ride behind a stable SDK.
* **Per-user personalisation, automatic.** Every `(agent_id, user_id)` pair gets its own retrieval predictor weights, cluster-sampling posterior, traversal graph, learning-rate schedule, and value function. Two users on the same agent see different memory layers within a handful of sessions — no per-user code, no profile training, no embeddings pipeline to operate.
* **It actually compounds.** Each session's reward is observed from fact reuse, re-retrieval, engagement, and explicit feedback, then fed back into the weights, the bandit posteriors, the critic, and the prompt optimiser. The next session is measurably better than the last, and the gap widens as the relationship deepens.
* **Safe by default.** New policies run in shadow until a per-pair promoter confirms a sustained advantage over the baseline; regressions auto-revert. Production memory never gets dragged off a good optimum by a noisy day.
* **Predictable cost.** Post-processing runs on a cheaper model than chat, and the tuning loop trains on signals you're already producing — not extra LLM calls per turn. The smarter your agent gets, the more efficient retrieval becomes.

For most teams this is the difference between *we'll get to memory next quarter* and &#x2A;our agents already remember every user, and the memory layer keeps getting smarter every week.* Rolling your own — vector store + dedup + per-user fine-tuning + RL eval harness + prompt sweeps + safe-rollout machinery — is a 12-month detour. With Sonzai it's one SDK call.

## What you can build with it [#what-you-can-build-with-it]

* Personality drift over time — the agent evolves character and relationship stance through repeated use, with no manual tuning
* Diary generation per session — the agent writes reflective summaries in its own voice, available as future context
* Automatic fact consolidation — duplicate and contradictory facts are merged or superseded; memory stays compact
* Breakthrough detection — milestone moments fire on completed sessions and land in the evolution history for narrative use
* Relationship tracking updates — stance, love score, and per-user personality overlays all update after each session
* Per-(agent, user) retrieval that sharpens with use — online and RL loops adapt the predictor's dimension weights, cluster sampling, and traversal edges per pair, so a returning user gets retrieval that fits *their* pattern, not the cohort average

## Quickstart [#quickstart]

There is no direct API for the self-improvement pipeline. It is triggered exclusively by ending a session. Set `Wait: true` during development if you need to query memory or personality immediately after the call; in production, leave it false and let the pipeline run async.

```go
// End the session — this triggers the post-processing pipeline.
_, err := client.Sessions.End(ctx, agentID, sonzai.SessionEndOptions{
    UserID:          "user-123",
    SessionID:       "sess-abc",
    TotalMessages:   12,
    DurationSeconds: 340,
    Messages:        messages,
    // Wait: true  // dev/test only — blocks until pipeline completes
})
if err != nil {
    return err
}

// On the next turn (or after Wait returns), the updated state is readable.
personality, err := client.Personality.Get(ctx, agentID, nil)
memory, err := client.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{UserID: "user-123"})
```

## Core concepts [#core-concepts]

**Triggered by SessionEnd — automatically.** Every call to `sessions.End()` enqueues the pipeline. You do not need to call anything else.

**Async by default.** In production the call returns immediately and the pipeline runs in the background. Results are visible on the next read of memory, personality, or insights. Use `Wait: true` in tests or benchmarks when you need to assert on the new state in the same process.

**Pipeline components.** A single session end runs: fact extraction with source-anchoring verification, deduplication and conflict resolution, cluster reconciliation, personality drift application, mood baseline update, diary generation, next-session prediction, and session quality scoring.

**Daily and weekly jobs layer on top.** Immediate post-processing handles per-session work. Longer-horizon jobs (memory tree pruning, narrative arc compression, association decay, learning-pace checks) run on daily and weekly cadences. The workbench's Advance Time triggers these same jobs against simulated time.

**Post-processing model.** The pipeline uses a cheaper model than the chat model to keep costs low. The resolver cascade checks agent → project → account → system default. You can inspect or override the resolved model without running any inference.

```go
// Check which model will run post-processing for this agent.
effective, err := client.Agents.EffectivePostProcessingModel(ctx, agentID, "gemini-2.0-pro")

// Pin a specific model at the agent level.
err = client.Agents.UpdatePostProcessingModel(ctx, agentID, "gemini", "gemini-2.0-flash-lite")

// Remove the agent-level pin (falls back to project/account/system).
err = client.Agents.ClearPostProcessingModel(ctx, agentID)
```

## Continuous learning, per (agent, user) pair [#continuous-learning-per-agent-user-pair]

The post-session pipeline runs every session. Underneath it, the runtime is continuously training *how* memory is processed for each `(agent_id, user_id)` pair — and Sonzai's applied-research team operates the online-learning, reinforcement-learning, bandit, and auto-tuning loops that govern it. Two pairs running the same agent end up with different predictor weights, different clusters surfaced, different traversal edges, and different schedules.

<Diagram>
  {`
     Day 1     |  ###...........................   ready out of the box
               |  verified extraction, dedup, clustering, and behavioural
               |  updates running from the first turn

     Week 1    |  #######.........................   responsive, adapting
               |  confidence has moved on the facts the user really cares
               |  about; mood is responding; patterns forming

     Month 1   |  ##############...................   personalised
               |  per-user retrieval converged; personality overlay has
               |  diverged; story arcs forming; this user is visibly
               |  remembered differently to the one before

     Year 1    |  #########################.........   long-term partner
               |  compact, navigable memory; milestones earned; reflective
               |  diary; recurring-event awareness; retrieval sharper than
               |  day one
               |
               |  Zero training code. Zero per-user logic. You called
               |  sessions.End() and went home.
    `}
</Diagram>

**Reward signal, compiled per session.** A reward compiler turns each session's observable signals — what the LLM actually used, how the user engaged, and explicit feedback when present — into a single bounded scalar. Every loop below trains against this reward; nothing on your side has to be instrumented or labelled.

**Per-pair retrieval predictor, tuned by stochastic gradient descent.** Every session, an SGD update with momentum adjusts the dimensions the predictor weighs, using the LLM's actual fact reuse as the gradient signal. Asymmetric learn / forget rates (aggressive on confirmed positives, slow to discard) prevent weight collapse on a single noisy session.

**Hyperparameter auto-tuning per pair.** Learning rates aren't a fixed constant — a per-pair scheduler watches divergence and plateau signals across recent sessions and adapts each pair's learning rate independently. Healthy pairs get nudged up to keep adapting; unstable pairs are damped down so a bad day can't drag a good optimum off course. No knobs to tune on your side.

**TD(0) critic + A2C policy gradient, in shadow with auto-revert.** A per-pair linear value function estimates `V(state)` from observable features (sessions to date, recent F1, learning rate, relationship stage). An A2C actor consumes `V(s)` as its baseline with an entropy bonus to keep exploration broad. The A2C trajectory runs in **shadow** alongside production; a per-pair promoter compares it to the SGD baseline over a rolling window, and only confirmed sustained improvements graduate to production. On regression, the prior weights are restored automatically. Production never sees a half-trained policy.

**Cluster bandit (Thompson sampling, Beta posterior).** Every retrieved fact carries a cluster identity. Each session's reward is attributed back across the contributing clusters and used to update a Beta-distributed posterior per cluster — a multi-armed bandit. Useful clusters get sampled more often next session; cold ones get probed less. Posteriors are lineage-aware: when the self-organiser splits, merges, or retires a cluster, its evidence flows to its successors instead of being thrown away.

**Hebbian edges across partitions.** Co-accessed memory nodes grow associative edges between them, weighted by repeated co-occurrence. Edges cross the per-user and per-agent-wisdom partitions, so user-specific traversal patterns can pull in the agent's broader world knowledge — and the more the pair runs, the denser and more selective the personal traversal graph becomes.

**Memory tree self-organisation.** A self-organiser rebalances the per-pair memory tree from access statistics: hot nodes get promoted, oversized branches split, sparse siblings merge, and stale parent descriptions are regenerated by a bounded LLM pass so summarisation tracks what's actually being read.

**Ebbinghaus-style retention.** Long-horizon retention follows a spaced-repetition decay curve. Frequently-recalled facts strengthen and outlive their original importance score; cold facts decay and eventually drop out of hot retrieval — but high-importance facts floor at a retention threshold so the agent never forgets the things that matter.

**OPRO-style prompt optimisation.** Sonzai's team runs an OPRO-style optimiser over the post-processing prompts: claim-level F1 scoring against curated fixture sets, a stronger meta-LLM proposing targeted revisions for the worst failure modes, and the strongest variant surviving. The pipeline picks up the new prompt — no deployment on your end.

**Grounding verification.** Every extracted fact must cite a source message index and a verbatim source quote from the user's turn. A mechanical verifier rejects facts that fail substring or attribution checks, and rejected facts feed back as a self-correcting hint on retry. Hallucinated memory doesn't reach the store — and this layer costs no extra inference per turn.

The longer an `(agent, user)` pair runs, the more its memory layer reflects how *that user* actually thinks — which transitions matter, which clusters carry signal, which dimensions to trust, which schedule it learns on. The agent doesn't just remember more for a returning user; it remembers *differently* per user, with no tuning required on your side.

<Diagram>
  {`
              Same agent. Same prompt. Two different users.
              =============================================

     +--- user_A pair ------------+    +--- user_B pair ------------+
     |                            |    |                            |
     |  Remembers what matters    |    |  Remembers what matters    |
     |  to user_A                 |    |  to user_B                 |
     |                            |    |                            |
     |  > the work narrative      |    |  > the music narrative     |
     |  > formal tone             |    |  > playful banter          |
     |  > morning rhythm          |    |  > late-night rhythm       |
     |  > returns on Mondays      |    |  > returns on Fridays      |
     |                            |    |                            |
     |  Mood baseline: calm       |    |  Mood baseline: bright     |
     |  Relationship: familiar    |    |  Relationship: close       |
     |                            |    |                            |
     +----------------------------+    +----------------------------+

     Two memory layers, diverged purely from each user's own patterns.
     No per-user code. No per-user prompt. No tuning required.
    `}
</Diagram>

## Multiplayer: agents that learn together [#multiplayer-agents-that-learn-together]

Per-pair learning is one layer. On top of it, agents read, write to, and learn from a shared knowledge base — and a single agent can carry attributed memory across the users it serves. The same compounding curve you saw above happens at the team level too.

* **Inter-agent — closed-loop company brain.** Agents on the same project autonomously write verified facts back into the [Knowledge Base](./knowledge-base) (with `knowledgeBaseWrite` on). Anything agent A learns with user X is grounded data agent B retrieves the next time the same topic comes up — even with a different user. The whole project gets sharper every session, not just one pair.
* **Intra-agent — shared memory across users.** A single agent serving a team carries memory across users via [Wisdom & shared memory](./knowledge-base#wisdom--shared-memory). `wisdom` (de-attributed cross-user generalisation) is on by default; `sharedMemory` (attributed cross-user context, for groups and teams) is one capability flip away — the agent informs user A with the context it gathered while talking to user B.
* **Organisation scope.** [Org-wide KB](./organization-knowledge-base) sits above projects: tenant-wide policies, lore, brand, and reference catalogs every project agent reads alongside its own. The cascade mode is recommended — project wins on collisions, org fills in defaults.

Just like a new hire benefits from every senior employee's notes, every new agent and every new conversation benefits from everything the team has already learned. The per-pair tuning loops keep getting sharper *for that user*; the multiplayer layer keeps getting smarter *for the whole company*.

## Full API [#full-api]

There is no `SelfImprovement` resource. The pipeline is an internal implementation detail of SessionEnd. The table below shows the SDK methods that are either inputs to or outputs of the pipeline.

| Method                                                            | Returns                         | Description                                                                           |
| ----------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
| `sessions.End(ctx, agentID, opts)`                                | `*SessionResponse`              | Ends a session and triggers the post-processing pipeline                              |
| `personality.Get(ctx, agentID, opts)`                             | `*PersonalityResponse`          | Reads current Big Five scores and evolution history — updated after each pipeline run |
| `personality.GetRecentShifts(ctx, agentID)`                       | `*RecentShiftsResponse`         | Lists recent personality drift events with timestamps and magnitudes                  |
| `personality.GetSignificantMoments(ctx, agentID, limit)`          | `*SignificantMomentsResponse`   | Returns milestone / breakthrough events written by the pipeline                       |
| `memory.List(ctx, agentID, opts)`                                 | `*MemoryResponse`               | Reads the memory tree — consolidated facts appear here after processing               |
| `memory.ListFacts(ctx, agentID, opts)`                            | `*FactListResponse`             | Lists atomic facts; newly extracted and deduplicated facts are visible here           |
| `agents.EffectivePostProcessingModel(ctx, agentID, chatModel)`    | `*EffectivePostProcessingModel` | Resolves which model the pipeline would use for this agent without running inference  |
| `agents.UpdatePostProcessingModel(ctx, agentID, provider, model)` | `error`                         | Pins a specific post-processing model at the agent level                              |
| `agents.ClearPostProcessingModel(ctx, agentID)`                   | `error`                         | Removes agent-level pin; resolver cascade falls through to project/account/system     |

## Combines with other features [#combines-with-other-features]

### With [Sessions](./sessions) — SessionEnd triggers the pipeline [#with-sessions--sessionend-triggers-the-pipeline]

Ending a session is the only way to trigger post-processing. The `Messages` field carries the full conversation; the pipeline reads it to extract facts and compute session quality.

```go
// End the session with the full message history.
_, err := client.Sessions.End(ctx, agentID, sonzai.SessionEndOptions{
    UserID:          "user-123",
    SessionID:       "sess-abc",
    TotalMessages:   8,
    DurationSeconds: 210,
    Messages:        conversationMessages,
    Wait:            true, // block until pipeline finishes (dev only)
})

// Pipeline has run. New facts, updated personality, and diary entry are ready.
facts, _ := client.Memory.ListFacts(ctx, agentID, &sonzai.FactListOptions{UserID: "user-123"})
fmt.Printf("facts after session: %d\n", len(facts.Facts))
```

### With [Personality](./personality) — evolution writes to personality [#with-personality--evolution-writes-to-personality]

Every session end applies Big Five drift, updates the mood baseline, and can fire milestone events. Fetch personality before and after to see the delta.

```go
before, _ := client.Personality.Get(ctx, agentID, nil)

// ... run a session and end it (Wait: true for this demo) ...

after, _ := client.Personality.Get(ctx, agentID, nil)

shifts, _ := client.Personality.GetRecentShifts(ctx, agentID)
moments, _ := client.Personality.GetSignificantMoments(ctx, agentID, 5)

fmt.Printf("openness before: %.3f, after: %.3f\n",
    before.Personality.Openness,
    after.Personality.Openness,
)
fmt.Printf("recent shifts: %d, milestones: %d\n",
    len(shifts.Shifts), len(moments.Moments),
)
```

### With [Memory](./memory) — facts get consolidated [#with-memory--facts-get-consolidated]

The pipeline extracts new facts, deduplicates against existing memory, resolves conflicts, and updates importance and confidence scores. List memory after session end to see the new state.

```go
// Before session end.
before, _ := client.Memory.ListFacts(ctx, agentID, &sonzai.FactListOptions{
    UserID: "user-123",
})

// ... run a session with substantive content, then end it (Wait: true) ...

// After session end — new facts extracted, duplicates merged.
after, _ := client.Memory.ListFacts(ctx, agentID, &sonzai.FactListOptions{
    UserID: "user-123",
})
fmt.Printf("facts before: %d, after: %d\n", len(before.Facts), len(after.Facts))

// Browse the full memory tree for cluster-level changes.
tree, _ := client.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{
    UserID:          "user-123",
    IncludeContents: true,
})
```

### With [Advance Time](./advance-time) — simulated time triggers the pipeline [#with-advance-time--simulated-time-triggers-the-pipeline]

In the workbench, advancing the clock by 24 hours runs the same daily jobs that production runs overnight: memory decay, tree pruning, diary generation, cluster reconciliation, and mood drift back to baseline. This is the fastest way to verify that long-horizon evolution is working correctly before shipping.

```go
// Advance 24 simulated hours — triggers daily pipeline jobs.
result, err := client.Workbench.AdvanceTime(ctx, map[string]any{
    "agent_id":  agentID,
    "user_id":   "user-123",
    "hours":     24,
})

// If the advance takes longer than your HTTP timeout, run it async.
asyncResult, err := client.Workbench.AdvanceTime(ctx, map[string]any{
    "agent_id": agentID,
    "user_id":  "user-123",
    "hours":    168, // 1 week
    "async":    true,
})
jobID := asyncResult["job_id"].(string)

// Poll until done.
for {
    job, _ := client.Workbench.GetAdvanceTimeJob(ctx, jobID)
    if job["status"] == "succeeded" || job["status"] == "failed" {
        break
    }
    time.Sleep(2 * time.Second)
}

// Read memory and personality to see the result of 1 week of background jobs.
personality, _ := client.Personality.Get(ctx, agentID, nil)
memory, _ := client.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{UserID: "user-123"})
```

## Tutorials [#tutorials]

* [Tutorial: Memory](./tutorial-memory) — walks through a full session-to-memory extraction flow
* [Evaluation](./evaluation) — use the workbench to score how well the pipeline is running for your agent

## Next steps [#next-steps]

* [Personality](./personality) — read and configure the Big Five profile the pipeline evolves into
* [Memory](./memory) — explore the fact store and memory tree the pipeline writes to
* [Sessions](./sessions) — the triggering surface for everything on this page
* [Advance Time](./advance-time) — simulate days and weeks of pipeline runs in seconds


---

# Sessions

Source: https://sonz.ai/docs/en/sessions

> A session is one continuous conversation between an agent and a user. Sonzai uses session boundaries to scope fact extraction, consolidation, and recall.



**Sessions** are Sonzai's unit of consolidation: one continuous conversation between an agent and a user, identified by a `session_id` you control. When a session ends, the platform extracts facts from the transcript, tags each one with the originating session, and runs the [memory](./memory) pipeline — dedup, cluster, decay — before the next session begins. You can let the platform auto-manage sessions on every chat call, or call `sessions.start` and `sessions.end` explicitly when you need to register custom tools, replay historical transcripts, or pin boundary timing to a real-world event.

## What a Session Is [#what-a-session-is]

A **session** is one continuous conversation between an agent and a user, identified by a `session_id` you control. Sessions are Sonzai's unit of consolidation: when a session ends, the platform extracts facts from the transcript, tags every fact with its source `session_id`, and runs the memory pipeline (dedup, cluster, decay) before the next session begins.

Sessions are not a wrapper around individual messages — they're how Sonzai knows which messages belong together for extraction. A session can last seconds or days.

<Callout type="info" title="You always have a session">
  Every `/chat` call belongs to a session. If you don't start one explicitly, the platform creates one for you. Session IDs flow through to extracted facts either way — you never lose attribution.
</Callout>

## Two Ways to Use Sessions [#two-ways-to-use-sessions]

### Auto-session (simplest) [#auto-session-simplest]

Just call `agents.chat` without touching the sessions API. The platform creates a session on the first message, keeps it open while the conversation is active, and closes it automatically when the conversation goes idle. This is the right default for most apps.

### Explicit session [#explicit-session]

Call `sessions.start` before the first message and `sessions.end` when the conversation is definitively over. Use this when you need to:

* **Register custom tools** for a specific conversation (`tool_definitions` on `sessions.start`).
* **Control boundary timing** — e.g. end a coaching call exactly when the user hangs up, not when the idle timer fires.
* **Replay historical transcripts** — pass the full message list to `sessions.end(messages=...)` to ingest a canned conversation verbatim, which is how data migration and benchmarks work.
* **Scope memory extraction** around a meaningful unit (a support case, a daily stand-up, a D\&D game night).

## Session Lifecycle [#session-lifecycle]

<Diagram>
  {`
    1. sessions.start         — Register session_id (+ optional tools); get ready to accept messages
    2. agents.chat (× N)      — Stream turns through the session; facts extracted inline
    3. sessions.end           — Close the session; triggers consolidation, dedup, diary, clustering
                              → every extracted fact carries this session_id`}
</Diagram>

If you skip step 1, the first `agents.chat` call will auto-register a session. If you skip step 3, the session closes on idle timeout (configurable per tenant).

## Starting and Ending a Session [#starting-and-ending-a-session]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;
const USER_ID = &#x22;user_123&#x22;;
const SESSION_ID = crypto.randomUUID();

// 1. Start
await sonzai.agents.sessions.start(AGENT_ID, {
user_id: USER_ID,
session_id: SESSION_ID,
user_display_name: &#x22;Mia&#x22;,
});

// 2. Chat turns
const reply = await sonzai.agents.chat({
agent: AGENT_ID,
user_id: USER_ID,
session_id: SESSION_ID,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Hi, quick question...&#x22; }],
});

// 3. End — triggers fact extraction + consolidation
await sonzai.agents.sessions.end(AGENT_ID, {
user_id: USER_ID,
session_id: SESSION_ID,
total_messages: 2,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, uuid
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;
USER_ID = &#x22;user_123&#x22;
SESSION_ID = str(uuid.uuid4())

# 1. Start
sonzai.agents.sessions.start(
  AGENT_ID,
  user_id=USER_ID,
  session_id=SESSION_ID,
  user_display_name=&#x22;Mia&#x22;,
)

# 2. Chat turns
reply = sonzai.agents.chat(
  agent_id=AGENT_ID,
  user_id=USER_ID,
  session_id=SESSION_ID,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Hi, quick question...&#x22;}],
)

# 3. End — triggers fact extraction + consolidation
sonzai.agents.sessions.end(
  AGENT_ID,
  user_id=USER_ID,
  session_id=SESSION_ID,
  total_messages=2,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

client := sonzai.NewClient(&#x22;sk-...&#x22;)
ctx := context.Background()
agentID, userID, sessionID := &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, &#x22;sess_01H...&#x22;

// 1. Start
_, _ = client.Agents.Sessions.Start(ctx, agentID, sonzai.SessionStartOptions{
  UserID:          userID,
  SessionID:       sessionID,
  UserDisplayName: &#x22;Mia&#x22;,
})

// 2. Chat turns
_, _ = client.Agents.Chat(ctx, sonzai.AgentChatParams{
  AgentID:   agentID,
  UserID:    userID,
  SessionID: sessionID,
  Messages:  []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Hi, quick question...&#x22;}},
})

// 3. End — triggers fact extraction + consolidation
_, _ = client.Agents.Sessions.End(ctx, agentID, sonzai.SessionEndOptions{
  UserID:        userID,
  SessionID:     sessionID,
  TotalMessages: 2,
})`,
  },
]"
/>

## Session IDs on Extracted Facts [#session-ids-on-extracted-facts]

Every fact Sonzai extracts carries its source `session_id` and `source_id`. You can use these to:

* **Reconstruct a conversation's memory footprint** — "what did the agent learn from session X?" via [`GET /memory/timeline`](/docs/api/sessions) (grouped by session) or [`GET /memory/facts`](/docs/api/memory) (filter client-side by `session_id`).
* **Score retrieval at session granularity** — benchmarks like LongMemEval evaluate whether retrieved facts come from the correct source session.
* **Surface recency context** — "conversations from last Tuesday" resolves via the session's `created_at` plus its attributed facts.

Facts that exist outside a specific conversation — agent-global wisdom, manually inserted facts, migrated priming content — carry empty `session_id` and are attributed through `source_type` instead (e.g. `"manual"`, `"agent_global"`).

## Registering Session-Scoped Tools [#registering-session-scoped-tools]

Custom tool definitions can be scoped to a single session. Pass them on `sessions.start`, or update them mid-session via `sessions.set_tools`. Character-level (agent-wide) tools are always merged in — session tools layer on top for the duration of the session.

```python
sonzai.agents.sessions.start(
    AGENT_ID,
    user_id=USER_ID,
    session_id=SESSION_ID,
    tool_definitions=[
        {
            "name": "check_patient_chart",
            "description": "Read the active patient's medication list.",
            "parameters": {
                "type": "object",
                "properties": {"patient_id": {"type": "string"}},
                "required": ["patient_id"],
            },
        }
    ],
)
```

Tool names starting with `sonzai_` are reserved for platform-built-in tools.

## When to Be Explicit [#when-to-be-explicit]

| Situation                                                    | Auto-session | Explicit `start` / `end`             |
| ------------------------------------------------------------ | ------------ | ------------------------------------ |
| Simple chat app, one conversation per user per day           | ✅            | —                                    |
| Multi-session app (support cases, tickets, coaching calls)   | —            | ✅                                    |
| Need per-session custom tools                                | —            | ✅ (pass `tool_definitions` on start) |
| Replaying a canned transcript (migration, eval, benchmark)   | —            | ✅ (pass `messages` on end)           |
| Want consolidation to fire on your trigger, not idle timeout | —            | ✅                                    |
| Voice calls with well-defined start/end signals              | —            | ✅                                    |

## What Happens on `sessions.end` [#what-happens-on-sessionsend]

The end call is where Sonzai does its heavy lifting. In the background, the platform runs:

* **Fact extraction** from the transcript with coverage validation.
* **Grounding verification** — every fact is checked against the actual messages to prevent hallucinated memories.
* **Session-end consolidation** — a session summary is stored; facts are deduped against existing memory via SPO triples and embedding similarity.
* **Clustering + polarity checks** — new facts find their thematic cluster; contradictions are flagged.
* **Diary and insights** (if enabled) — the agent's internal narrative is updated.

None of this blocks the `sessions.end` response — it's asynchronous. The call returns as soon as the transcript is queued.

## What's next [#whats-next]

* [Conversations](/docs/conversations) — the chat lifecycle and streaming.
* [Memory](/docs/memory) — how extracted facts are organized.
* [Sessions API reference](/docs/api/sessions) — endpoint schemas.


---

# Shared Memory

Source: https://sonz.ai/docs/en/shared-memory

> Let one agent serve a whole team — carrying attributed memory across users, with privacy guardrails, full disclosure audit, and a default-on de-attributed wisdom layer that compounds across every user the agent talks to.



The default agent memory model is **per-user** — every conversation builds a fact profile scoped to one `(agent, user)` pair. That's right for companion products and 1:1 assistants. But teams need the opposite: they want one agent serving a whole group to know what's going on across users.

Shared memory is the capability that turns a single agent into a **team brain** — informing user A with the context it gathered while talking to user B, with attribution, server-enforced privacy floors, and a full disclosure audit. Combined with the default-on `wisdom` layer (de-attributed cross-user generalisation), it gives you two complementary tiers of cross-user knowledge.

<Callout type="info" title="Where this fits">
  Shared memory layers *on top of* the standard per-user memory. Per-user facts still exist; shared memory adds an agent-wide partition for facts that should cross the user boundary. The two coexist; nothing about per-user memory changes when you turn shared memory on.
</Callout>

## Two tiers, one capability surface [#two-tiers-one-capability-surface]

|                    | What it does                                                                                                                                                                                                      | Default                     | When to use                                                                                                                    |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **`wisdom`**       | De-attributed cross-user generalisation. A daily promotion job pulls patterns from per-user fact histories, k-anonymises them, and rewrites them into agent-wide knowledge. No individual user is identifiable.   | **On** for every new agent. | Every agent that talks to more than one user — it's a free generalisation layer. Disable only for strict single-user products. |
| **`sharedMemory`** | Attributed cross-user context. Person/entity-attributed facts (roles, expertise, business context, relationships) recorded by the agent and surfaced to other users sharing it. Names and identities are visible. | **Off**. Opt-in.            | Group, team, party, or shared-business-context products where users explicitly expect to see *who* is doing what.              |

Both can run on the same agent simultaneously. `wisdom` is the safe layer (always behind k-anonymity); `sharedMemory` is the powerful one (attribution preserved) and demands deliberate opt-in.

## When to turn on shared memory [#when-to-turn-on-shared-memory]

**Turn it on when:**

* **Team coordinators.** "Alice owns the migration; Bob is on incident response." Every teammate joining the agent sees the current ownership picture.
* **Group / party planning.** "Carol brings dessert; Dave does setup." Anyone joining mid-plan picks up state without re-asking.
* **Shared business workspaces.** Account-level agents where every user on the account benefits from context the others have given.
* **Multi-stakeholder support.** Customer-success agents where the renewal context one stakeholder gave should inform the conversation with the next.

**Leave it off when:**

* Single-user companion products (private 1:1 relationships).
* Use cases where users would be surprised that the agent talks about them to other users.
* Compliance-sensitive contexts where cross-user disclosure isn't legally OK.

## Enable shared memory [#enable-shared-memory]

`wisdom` is a precondition (default-on, so usually nothing to set explicitly). Flip `sharedMemory: true` to opt the agent in.

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `// Wisdom is on by default for new agents — only set it
// explicitly if you want to override the default.
await client.agents.updateCapabilities(&#x22;agent_abc&#x22;, {
wisdom:       true,
sharedMemory: true,
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `client.agents.update_capabilities(
  &#x22;agent_abc&#x22;,
  wisdom=True,
  shared_memory=True,
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `t := true
_, err := client.Agents.UpdateCapabilities(ctx, &#x22;agent_abc&#x22;,
  sonzai.UpdateCapabilitiesOptions{
      Wisdom:       &t,
      SharedMemory: &t,
  },
)`,
  },
  {
    label: &#x22;HTTP&#x22;,
    language: &#x22;bash&#x22;,
    code: `curl -X PATCH \\
&#x22;$PLATFORM_API_URL/api/v1/agents/agent_abc/capabilities&#x22; \\
-H &#x22;Authorization: Bearer $API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;wisdom&#x22;: true,
  &#x22;sharedMemory&#x22;: true
}'`,
  },
]"
/>

You can also set it at agent-creation time:

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `const agent = await client.agents.create({
name:       &#x22;Team Coordinator&#x22;,
project_id: &#x22;proj_abc&#x22;,
tool_capabilities: {
  wisdom:        true,
  shared_memory: true,
},
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `agent = client.agents.create(
  name=&#x22;Team Coordinator&#x22;,
  project_id=&#x22;proj_abc&#x22;,
  tool_capabilities={
      &#x22;wisdom&#x22;: True,
      &#x22;shared_memory&#x22;: True,
  },
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `t := true
agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  Name:      &#x22;Team Coordinator&#x22;,
  ProjectID: &#x22;proj_abc&#x22;,
  ToolCapabilities: &sonzai.AgentToolCapabilities{
      Wisdom:       &t,
      SharedMemory: &t,
  },
})`,
  },
]"
/>

## Disable shared memory [#disable-shared-memory]

Pass `sharedMemory: false`. Existing attributed facts stay in storage (you can re-enable later) but the agent stops surfacing them in context and stops getting the write tools.

<CodeTabs
  tabs="[
  {
    label: &#x22;TypeScript&#x22;,
    language: &#x22;ts&#x22;,
    code: `await client.agents.updateCapabilities(&#x22;agent_abc&#x22;, {
sharedMemory: false,
});`,
  },
  {
    label: &#x22;Python&#x22;,
    language: &#x22;python&#x22;,
    code: `client.agents.update_capabilities(
  &#x22;agent_abc&#x22;,
  shared_memory=False,
)`,
  },
  {
    label: &#x22;Go&#x22;,
    language: &#x22;go&#x22;,
    code: `f := false
_, err := client.Agents.UpdateCapabilities(ctx, &#x22;agent_abc&#x22;,
  sonzai.UpdateCapabilitiesOptions{SharedMemory: &f},
)`,
  },
]"
/>

To opt an agent out of `wisdom` (rare — usually only for strict single-user products):

```ts
await client.agents.updateCapabilities("agent_abc", { wisdom: false });
```

## What changes when you turn it on [#what-changes-when-you-turn-it-on]

Three things flip simultaneously the moment `sharedMemory: true` lands:

### 1. Tools — the agent gets attributed-wisdom CRUD [#1-tools--the-agent-gets-attributed-wisdom-crud]

The LLM picks up four new tools:

| Tool                   | What the agent can do                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| `sonzai_wisdom_set`    | Create or upsert an attributed fact (entity\_type, entity\_id, category, value, confidence). |
| `sonzai_wisdom_update` | Replace the value of an existing fact.                                                       |
| `sonzai_wisdom_delete` | Soft-delete an attributed fact (tombstone, reversible).                                      |
| `sonzai_wisdom_relate` | Create attributed relations between entities ("Alice manages Bob").                          |

These are deferred tools — the LLM calls them inline; the platform processes the writes asynchronously after the turn so latency stays clean.

### 2. Context — the agent's prompt grows a "Shared facts" section [#2-context--the-agents-prompt-grows-a-shared-facts-section]

Every system prompt the agent runs from now on includes a `Shared facts about people and entities` section listing the attributed facts on file plus a discretion clause that tells the LLM how to handle disclosure ("exercise discretion; privacy over transparency"). The agent doesn't dump everything to every user — it weighs disclosure decisions per turn.

### 3. Privacy floor — every write is server-side validated [#3-privacy-floor--every-write-is-server-side-validated]

Before an attributed fact is persisted, the platform runs a semantic validator that rejects writes about compensation, health, politics, and other privacy-sensitive categories. This is enforced server-side, not in the prompt — even if a user explicitly asks the agent to record a salary, the write is blocked. Rejected writes appear in the disclosure audit with `decision = "redacted"` so you can see what was attempted and why.

## Verify it's working [#verify-its-working]

Three checks you can run end-to-end against staging or production. Replace `$AGENT_ID`, `$API_KEY`, and the platform URL.

### 1. List the attributed facts on an agent [#1-list-the-attributed-facts-on-an-agent]

```bash
curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed?limit=20' \
  -H "Authorization: Bearer $API_KEY"
```

Expected: a `200` with an array of facts (`entity_type`, `entity_id`, `category`, `value`, `confidence`). Empty array if nothing has been written yet — that's still a healthy response.

### 2. Write an attributed fact directly via the API [#2-write-an-attributed-fact-directly-via-the-api]

```bash
curl -X POST 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/attributed' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "person",
    "entity_id": "alice",
    "entity_display_name": "Alice",
    "category": "role",
    "value": "Lead Engineer",
    "confidence": 0.92
  }'
```

Then re-run the list endpoint above. Alice's role should appear. Now any user talking to this agent will see this fact in the agent's context (subject to discretion).

### 3. Read the disclosure audit [#3-read-the-disclosure-audit]

```bash
curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/audit?limit=50' \
  -H "Authorization: Bearer $API_KEY"
```

Every time a fact is loaded into the context for a turn, an audit row is written with `decision = "disclosed"` and `decision_why`. If the privacy floor blocked something, the row will show `decision = "redacted"`. **This is your live observability** — if production traffic is running with shared memory on, you'll see entries here, and you can audit any disclosure decision in retrospect.

## Privacy and control [#privacy-and-control]

Shared memory is sensitive by design. Four layers of control sit between an LLM call and a persisted disclosure:

1. **Capability gate.** `sharedMemory: false` (the default) means none of this happens — no tools registered, no context injection, no audit rows.
2. **Privacy floor.** The semantic validator rejects writes in compensation, health, politics, and other configured-sensitive categories before they hit storage. Configurable per tenant.
3. **Discretion clause in the prompt.** Even with facts present, the agent is instructed to weigh disclosure per turn rather than dumping everything.
4. **Disclosure audit.** Every disclosure decision is logged with reason. You can review what the agent shared, what it withheld, and why at any time via the audit endpoint.

Hard delete stays admin-only. Agents only soft-delete (tombstone), so a misattributed fact is reversible until an admin clears it permanently.

## Combines with other features [#combines-with-other-features]

### With Knowledge Base autonomous editing [#with-knowledge-base-autonomous-editing]

`knowledgeBaseWrite` and `sharedMemory` are independent capabilities — flip them in any combination:

* **KB write only:** agents record facts about *the world* (products, policies, prices, incidents) in the project knowledge graph.
* **Shared memory only:** agents record facts about *people in this team* (roles, expertise, ownership, relationships).
* **Both:** full closed-loop institutional memory plus team brain. The agent learns *what's true about the world* and *who's doing what*, and every other agent on the project picks both up.

### With Self-Improvement [#with-self-improvement]

The per-pair learning loops in [Self-Improvement](./self-improvement) keep getting sharper *for that user*; shared memory keeps getting smarter *for the whole team*. Both run automatically on every `sessions.End()`.

### With Wisdom (default-on) [#with-wisdom-default-on]

`wisdom` is the de-attributed generalisation layer; `sharedMemory` is the attributed cross-user layer. Both can run together. The privacy floor protects the attributed side; wisdom doesn't need it because it's k-anonymised before promotion.

## Full API reference [#full-api-reference]

Every shared-memory endpoint — list, upsert, replace, delete, bulk import, relations CRUD, disclosure audit — is documented with request/response shapes in the [Wisdom API reference](./reference/api/wisdom).

## Next steps [#next-steps]

* [Knowledge Base](./knowledge-base) — the broader multiplayer memory story (manual upload, ETL push, autonomous agent editing)
* [Self-Improvement](./self-improvement) — how shared memory layers on top of per-pair online learning
* [Organization Knowledge Base](./organization-knowledge-base) — tenant-wide knowledge that sits above projects
* [Wisdom API](./reference/api/wisdom) — full endpoint reference


---

# User Personas

Source: https://sonz.ai/docs/en/user-personas

> Reusable tenant-level persona templates that shape how the agent treats different types of users — tone, pace, formality.



User Personas are templates your tenant defines for the kinds of users the agent will meet. When a persona is attached to a user — during priming or via conversation metadata — the agent reads it alongside its own personality and adjusts tone, vocabulary, and pace accordingly. A "skeptical beginner" gets gentler explanations and more confirmations; a "power user" gets concise, direct answers without hand-holding.

## What you can build with it [#what-you-can-build-with-it]

* **Experience tiers** — beginner / intermediate / expert personas with progressively faster pace and denser vocabulary
* **Customer segments** — trial / paying / enterprise personas with calibrated support formality and escalation thresholds
* **Game character archetypes** — personas for NPCs or dynamic character switching mid-conversation
* **Onboarding flows** — a first-time-user persona that gradually fades as the user completes milestones
* **Testing + evaluation** — define canonical personas for each scenario so you can run repeatable agent evals against a known user type

## Quickstart [#quickstart]

Create a persona, then fetch the full list.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

// Create a persona
const persona = await client.userPersonas.create({
name: &#x22;Skeptical Beginner&#x22;,
description: &#x22;First-time user who questions recommendations and needs reassurance.&#x22;,
style: &#x22;Use plain language. Confirm before any irreversible action. Offer brief rationale for each suggestion.&#x22;,
});

console.log(persona.persona_id);

// List all tenant personas
const { personas } = await client.userPersonas.list();
personas.forEach(p => console.log(p.name, p.is_default));`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# Create a persona
persona = client.user_personas.create(
  name=&#x22;Skeptical Beginner&#x22;,
  description=&#x22;First-time user who questions recommendations and needs reassurance.&#x22;,
  style=&#x22;Use plain language. Confirm before any irreversible action. Offer brief rationale for each suggestion.&#x22;,
)

print(persona.persona_id)

# List all tenant personas
result = client.user_personas.list()
for p in result.personas:
  print(p.name, p.is_default)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client, err := sonzai.NewClient(&#x22;sk-...&#x22;)
if err != nil { panic(err) }

// Create a persona
persona, err := client.UserPersonas.Create(ctx, sonzai.CreateUserPersonaOptions{
  Name:        &#x22;Skeptical Beginner&#x22;,
  Description: &#x22;First-time user who questions recommendations and needs reassurance.&#x22;,
  Style:       &#x22;Use plain language. Confirm before any irreversible action. Offer brief rationale for each suggestion.&#x22;,
})
fmt.Println(persona.PersonaID)

// List all tenant personas
result, err := client.UserPersonas.List(ctx)
for _, p := range result.Personas {
  fmt.Println(p.Name, p.IsDefault)
}`,
  },
]"
/>

## Core concepts [#core-concepts]

* **Tenant-scoped** — personas belong to your tenant, not to a specific agent or user. Every agent in your tenant can reference the same persona library.
* **Template, not assignment** — creating a persona does not apply it to anyone. You attach it during priming or pass it as metadata when starting a conversation.
* **Default persona** — one persona per tenant can be marked `is_default`. The agent falls back to it when no persona is explicitly attached to a user.
* **Style field** — an optional free-form directive layered on top of the agent's base personality prompt. Write it as a concise instruction set: tone, vocabulary level, confirmation habits, pacing.

## Full API [#full-api]

| Method   | Signature                      | Returns                   | Description                        |
| -------- | ------------------------------ | ------------------------- | ---------------------------------- |
| `list`   | `list(ctx)`                    | `UserPersonaListResponse` | All personas for the tenant        |
| `create` | `create(ctx, opts)`            | `UserPersona`             | Create a new persona template      |
| `get`    | `get(ctx, personaID)`          | `UserPersona`             | Fetch a single persona by ID       |
| `update` | `update(ctx, personaID, opts)` | `UserPersona`             | Update name, description, or style |
| `delete` | `delete(ctx, personaID)`       | —                         | Permanently delete a persona       |

### `UserPersona` fields [#userpersona-fields]

| Field         | Type    | Description                                   |
| ------------- | ------- | --------------------------------------------- |
| `persona_id`  | string  | Stable unique identifier                      |
| `name`        | string  | Human-readable label for the persona          |
| `description` | string  | What kind of user this persona represents     |
| `style`       | string? | Agent instruction directive for tone and pace |
| `is_default`  | bool    | Whether this is the tenant's fallback persona |
| `tenant_id`   | string  | Owning tenant                                 |
| `created_at`  | string  | ISO 8601 timestamp                            |
| `updated_at`  | string  | ISO 8601 timestamp                            |

## Combines with other features [#combines-with-other-features]

### With [Priming](./priming) — attach a persona during user setup [#with-priming--attach-a-persona-during-user-setup]

Pass a persona reference when priming a new user so the agent adapts from the very first turn, before any conversation history exists.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const job = await client.agents.priming.primeUser(&#x22;agent_abc&#x22;, &#x22;user_123&#x22;, {
display_name: &#x22;Jordan Lee&#x22;,
metadata: {
  persona_id: persona.persona_id,   // attach persona at priming time
  timezone: &#x22;America/New_York&#x22;,
},
content: [
  { type: &#x22;text&#x22;, body: &#x22;Jordan is a first-time user migrating from a competitor product.&#x22; },
],
source: &#x22;onboarding&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `job = client.agents.priming.prime_user(
  &#x22;agent_abc&#x22;,
  &#x22;user_123&#x22;,
  display_name=&#x22;Jordan Lee&#x22;,
  metadata={
      &#x22;persona_id&#x22;: persona.persona_id,   # attach persona at priming time
      &#x22;timezone&#x22;: &#x22;America/New_York&#x22;,
  },
  content=[
      {&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: &#x22;Jordan is a first-time user migrating from a competitor product.&#x22;},
  ],
  source=&#x22;onboarding&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `job, err := client.Agents.Priming.PrimeUser(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
  sonzai.PrimeUserOptions{
      DisplayName: &#x22;Jordan Lee&#x22;,
      Metadata: map[string]string{
          &#x22;persona_id&#x22;: persona.PersonaID,   // attach persona at priming time
          &#x22;timezone&#x22;:   &#x22;America/New_York&#x22;,
      },
      Content: []sonzai.PrimingContent{
          {Type: &#x22;text&#x22;, Body: &#x22;Jordan is a first-time user migrating from a competitor product.&#x22;},
      },
      Source: &#x22;onboarding&#x22;,
  },
)`,
  },
]"
/>

### With [Personality](./personality) — agent personality × user persona = interaction style [#with-personality--agent-personality--user-persona--interaction-style]

These two concepts are complementary and operate at different levels:

* **Personality** is the **agent's** traits — Big Five scores, speech patterns, emotional range. It is fixed per agent (and evolves slowly through interactions).
* **User Persona** is the **user's** type — a template describing what kind of person the agent is talking to. It shapes how the agent expresses its personality in this specific conversation.

Think of it as a matrix: a high-agreeableness agent talking to a "power user" persona stays warm but drops the hand-holding; talking to a "skeptical beginner" persona it adds more reassurance and simpler vocabulary — without the underlying personality changing.

### With [Evaluation](./evaluation) — test against canonical personas [#with-evaluation--test-against-canonical-personas]

Define a persona for each user archetype you care about, then run eval scenarios scoped to that persona. This gives you repeatable, deterministic test conditions.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Define an eval scenario for the &#x22;Skeptical Beginner&#x22; persona
const result = await client.agents.evaluate(&#x22;agent-id&#x22;, {
templateId: &#x22;onboarding-rubric&#x22;,
messages: [
  { role: &#x22;user&#x22;,      content: &#x22;I'm not sure I trust this — what happens to my data?&#x22; },
  { role: &#x22;assistant&#x22;, content: &#x22;That's a fair question. Your data stays on our servers...&#x22; },
],
// Pass persona context so scoring reflects expected beginner-friendly tone
metadata: { persona_id: persona.persona_id },
});

console.log(result.score, result.feedback);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = client.agents.evaluate(
  &#x22;agent-id&#x22;,
  template_id=&#x22;onboarding-rubric&#x22;,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;,      &#x22;content&#x22;: &#x22;I'm not sure I trust this — what happens to my data?&#x22;},
      {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: &#x22;That's a fair question. Your data stays on our servers...&#x22;},
  ],
  metadata={&#x22;persona_id&#x22;: persona.persona_id},
)

print(result.score, result.feedback)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := client.Agents.Evaluate(ctx, &#x22;agent-id&#x22;,
  sonzai.EvaluateOptions{
      TemplateID: &#x22;onboarding-rubric&#x22;,
      Messages: []sonzai.Message{
          {Role: &#x22;user&#x22;,      Content: &#x22;I'm not sure I trust this — what happens to my data?&#x22;},
          {Role: &#x22;assistant&#x22;, Content: &#x22;That's a fair question. Your data stays on our servers...&#x22;},
      },
      Metadata: map[string]string{&#x22;persona_id&#x22;: persona.PersonaID},
  },
)
fmt.Println(result.Score, result.Feedback)`,
  },
]"
/>

## Tutorials [#tutorials]

* [Tutorial: Custom States](/docs/en/guides/tutorials/tutorial-custom-states) — see how metadata fields like `persona_id` travel through the conversation lifecycle alongside custom state.

## Next steps [#next-steps]

* [Personality](./personality)
* [Priming](./priming)
* [Evaluation](./evaluation)


---

# Voice

Source: https://sonz.ai/docs/en/voice

> Real-time voice interaction with text-to-speech, speech-to-text, and live duplex streaming.



**Voice** gives every agent three modes of audio interaction: one-shot text-to-speech for spoken replies, speech-to-text for transcribing user audio, and a live duplex stream for full real-time conversations over a token-authenticated WebSocket. The same agent identity drives all three — same [personality](./personality), same [memory](./memory), same tools — so spoken turns are consolidated into the same [session](./sessions) as text turns. Pick a voice name, choose an output format, and the Relationship Layer handles synthesis, transcription, and turn-taking server-side.

## Text-to-Speech (TTS) [#text-to-speech-tts]

Convert text to spoken audio.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const audio = await client.agents.voice.tts(&#x22;agent-id&#x22;, {
text: &#x22;Hello! How can I help you today?&#x22;,
voiceName: &#x22;aria&#x22;,
language: &#x22;en&#x22;,
outputFormat: &#x22;mp3&#x22;,
});
// audio.data contains the audio bytes`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `audio = client.agents.voice.tts(
  &#x22;agent-id&#x22;,
  text=&#x22;Hello! How can I help you today?&#x22;,
  voice_name=&#x22;aria&#x22;,
  language=&#x22;en&#x22;,
  output_format=&#x22;mp3&#x22;,
)
# audio.data contains the audio bytes`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `audio, err := client.Agents.Voice.TTS(ctx, &#x22;agent-id&#x22;, sonzai.TTSOptions{
  Text:         &#x22;Hello! How can I help you today?&#x22;,
  VoiceName:    &#x22;aria&#x22;,
  Language:     &#x22;en&#x22;,
  OutputFormat: &#x22;mp3&#x22;,
})
// audio.Data contains the audio bytes`,
  },
]"
/>

## Speech-to-Text (STT) [#speech-to-text-stt]

Transcribe audio to text.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const result = await client.agents.voice.stt(&#x22;agent-id&#x22;, {
audio: base64AudioData,
audioFormat: &#x22;wav&#x22;,
language: &#x22;en&#x22;,
});
console.log(result.text);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = client.agents.voice.stt(
  &#x22;agent-id&#x22;,
  audio=base64_audio_data,
  audio_format=&#x22;wav&#x22;,
  language=&#x22;en&#x22;,
)
print(result.text)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := client.Agents.Voice.STT(ctx, &#x22;agent-id&#x22;, sonzai.STTOptions{
  Audio:       base64AudioData,
  AudioFormat: &#x22;wav&#x22;,
  Language:    &#x22;en&#x22;,
})
fmt.Println(result.Text)`,
  },
]"
/>

## Live Voice Streaming [#live-voice-streaming]

Real-time duplex voice conversation. Get a token, then open a bidirectional stream.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// 1. Get a streaming token
const token = await client.agents.voice.getToken(&#x22;agent-id&#x22;, {
voiceName: &#x22;aria&#x22;,
userId: &#x22;user-123&#x22;,
});

// 2. Connect to live stream
const stream = await client.agents.voice.stream(token);

// Send audio chunks
stream.sendAudio(audioChunk);

// Or send text for the agent to speak
stream.sendText(&#x22;Tell me about your day&#x22;);

// Receive events
for await (const event of stream) {
if (event.type === &#x22;audio&#x22;) {
  playAudio(event.data);
} else if (event.type === &#x22;transcript&#x22;) {
  console.log(event.text);
}
}

// End session
stream.endSession();`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# 1. Get a streaming token
token = client.agents.voice.get_token(
  &#x22;agent-id&#x22;,
  voice_name=&#x22;aria&#x22;,
  user_id=&#x22;user-123&#x22;,
)

# 2. Connect to live stream
with client.agents.voice.stream(token) as stream:
  # Send audio chunks
  stream.send_audio(audio_chunk)

  # Receive events
  for event in stream:
      if event.type == &#x22;audio&#x22;:
          play_audio(event.data)
      elif event.type == &#x22;transcript&#x22;:
          print(event.text)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Go SDK provides TTS/STT but not live streaming.
// Use the TypeScript or Python SDK for live voice sessions.`,
  },
]"
/>

<Callout type="info" title="WebSocket Transport">
  Live streaming is powered by WebSocket and supports real-time duplex audio. The client sends microphone audio chunks upstream while simultaneously receiving synthesized speech and transcripts downstream, enabling natural conversational flow.
</Callout>

## Browse Voice Catalog [#browse-voice-catalog]

List available voices.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const voices = await client.voices.list({
language: &#x22;en&#x22;,
gender: &#x22;female&#x22;,
});

for (const voice of voices.voices) {
console.log(voice.name, voice.language, voice.gender);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `voices = client.voices.list(language=&#x22;en&#x22;, gender=&#x22;female&#x22;)

for voice in voices.voices:
  print(voice.name, voice.language, voice.gender)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `voices, err := client.Voices.List(ctx, &sonzai.VoiceListOptions{
  Language: &#x22;en&#x22;,
  Gender:   &#x22;female&#x22;,
})

for _, v := range voices.Items {
  fmt.Println(v.Name, v.Language, v.Gender)
}`,
  },
]"
/>

## Voice capabilities [#voice-capabilities]

Four `AgentCapabilities` fields describe an agent's voice configuration:

| Field             | Type                | Description                                                         |
| ----------------- | ------------------- | ------------------------------------------------------------------- |
| `voiceGeneration` | `boolean`           | Whether voice (TTS) generation is enabled for this agent            |
| `voiceUnlockedAt` | `string (ISO 8601)` | When voice generation was granted                                   |
| `voiceId`         | `string`            | The voice identifier used by default for this agent's TTS calls     |
| `voiceTier`       | `number`            | Numeric tier level for voice quality (higher = higher quality/cost) |

`voiceId` and `voiceTier` are read from `get_capabilities()`. To persist a preferred voice for an agent, store the `voiceId` from `voices.list()` and pass it to TTS calls. `voiceGeneration` is platform-managed and flips when your plan includes voice capabilities.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Read voice capability fields
const caps = await client.agents.getCapabilities(&#x22;agent-id&#x22;);
console.log(caps.voiceGeneration);  // true | false
console.log(caps.voiceId);          // &#x22;aria&#x22; or null
console.log(caps.voiceTier);        // 1, 2, etc. or null
console.log(caps.voiceUnlockedAt);  // &#x22;2024-11-01T00:00:00Z&#x22; or null

// Pick a voice and use it for TTS
const voices = await client.voices.list({ language: &#x22;en&#x22; });
const chosen = voices.voices[0];

const audio = await client.agents.voice.tts(&#x22;agent-id&#x22;, {
text: &#x22;Hello!&#x22;,
voiceName: chosen.name,
language: &#x22;en&#x22;,
outputFormat: &#x22;mp3&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Read voice capability fields
caps = client.agents.get_capabilities(&#x22;agent-id&#x22;)
print(caps.voice_generation)   # True | False
print(caps.voice_id)           # &#x22;aria&#x22; or None
print(caps.voice_tier)         # 1, 2, etc. or None
print(caps.voice_unlocked_at)  # datetime | None

# Pick a voice and use it for TTS
voices = client.voices.list(language=&#x22;en&#x22;)
chosen = voices.voices[0]

audio = client.agents.voice.tts(
  &#x22;agent-id&#x22;,
  text=&#x22;Hello!&#x22;,
  voice_name=chosen.name,
  language=&#x22;en&#x22;,
  output_format=&#x22;mp3&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Read voice capability fields
caps, _ := client.Agents.GetCapabilities(ctx, &#x22;agent-id&#x22;)
fmt.Println(caps.VoiceGeneration)  // true | false
fmt.Println(caps.VoiceID)          // &#x22;aria&#x22; or &#x22;&#x22;
fmt.Println(caps.VoiceTier)        // 1, 2, etc. or 0
fmt.Println(caps.VoiceUnlockedAt)  // &#x22;2024-11-01T00:00:00Z&#x22; or &#x22;&#x22;

// Pick a voice and use it for TTS
voices, _ := client.Voices.List(ctx, &sonzai.VoiceListOptions{Language: &#x22;en&#x22;})
chosen := voices.Items[0]

audio, err := client.Agents.Voice.TTS(ctx, &#x22;agent-id&#x22;, sonzai.TTSOptions{
  Text:         &#x22;Hello!&#x22;,
  VoiceName:    chosen.Name,
  Language:     &#x22;en&#x22;,
  OutputFormat: &#x22;mp3&#x22;,
})`,
  },
]"
/>

## In Practice [#in-practice]

Voice is primarily relevant to companions and enterprise. For task
agents, it's usually not needed — but if you're building a phone/IVR
flow, the enterprise patterns apply.

  

  

  
    **IVR and phone-first support.** Wire duplex voice into your call
    center stack (Twilio, Vonage). The agent handles tier-1 calls — routing,
    status checks, FAQ — and hands off on escalation.

    **Multilingual is a must.** List voices filtered by target language
    and keep a per-customer preference in your CRM. Let the agent pick the
    voice based on the caller's account profile.

    ```typescript
    const voices = await client.voices.list({ language: userLanguage });
    const preferred = voices.voices.find(v => v.voiceId === accountPref) ?? voices.voices[0];
    ```

    **Pair with `handoff_to_human` tool.** If the caller asks for a human
    or the agent's confidence drops, the tool call should trigger your
    call-center's queue-jump logic.
  



---

# Wakeups

Source: https://sonz.ai/docs/en/wakeups

> Schedule a one-off proactive agent message at a specific future moment — a birthday greeting, appointment reminder, or interest follow-up.



Wakeups let your agent reach out to a user exactly once at a known future moment. Give the agent an intent, a `check_type` that it sees as context, and a delay in hours — the platform handles delivery. Unlike [Scheduled Reminders](./scheduled-reminders), which fire on a repeating cadence, a wakeup fires once and is done.

Typical use cases: birthday greetings, appointment reminders, post-event check-ins, interest follow-ups, and time-delayed nudges. If you need the agent to repeat the same outreach, use a schedule instead.

## What you can build with it [#what-you-can-build-with-it]

* **Birthday greetings** — schedule a wakeup for 00:00 on a user's birthday so the agent is the first to reach out
* **Appointment reminders** — fire 2 hours before a dentist, gym session, or onboarding call without any cron job on your side
* **Interest follow-ups** — when a user mentions they are waiting on something, schedule a check-in for the next day ("hey, did you hear back from them?")
* **Post-event check-ins** — the day after a job interview, a first date, or a big presentation, the agent proactively asks how it went
* **Time-delayed nudges** — a user sets a task as pending; 24 hours later the agent checks in without the user having to remember to ask

## Quickstart [#quickstart]

Schedule a birthday greeting for a specific date using `scheduled_at`. For a "N hours from now" wakeup, use `delay_hours` instead. If both are provided, `scheduled_at` takes precedence.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

// Use scheduled_at for birthdays/appointments with a known date
const wakeup = await client.agents.scheduleWakeup(&#x22;agent_abc&#x22;, {
user_id:      &#x22;user_123&#x22;,
check_type:   &#x22;birthday&#x22;,
intent:       &#x22;wish the user a happy birthday&#x22;,
scheduled_at: &#x22;2026-06-15T09:00:00Z&#x22;,  // RFC3339 absolute timestamp
occasion:     &#x22;Sarah's 30th birthday&#x22;,
interest_topic: &#x22;celebration and birthday traditions&#x22;,
});

console.log(wakeup.wakeup_id);   // &#x22;wake_01HX...&#x22;
console.log(wakeup.scheduled_at); // &#x22;2026-06-15T09:00:00Z&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

# Use scheduled_at for birthdays/appointments with a known date
wakeup = client.agents.schedule_wakeup(
  &#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  check_type=&#x22;birthday&#x22;,
  intent=&#x22;wish the user a happy birthday&#x22;,
  scheduled_at=&#x22;2026-06-15T09:00:00Z&#x22;,  # RFC3339 absolute timestamp
  occasion=&#x22;Sarah's 30th birthday&#x22;,
  interest_topic=&#x22;celebration and birthday traditions&#x22;,
)

print(wakeup.wakeup_id)    # &#x22;wake_01HX...&#x22;
print(wakeup.scheduled_at) # &#x22;2026-06-15T09:00:00Z&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
if err != nil { panic(err) }

// Use ScheduledAt for birthdays/appointments with a known date
wakeup, err := client.Agents.Wakeups.Schedule(ctx, &#x22;agent_abc&#x22;,
  sonzai.ScheduleWakeupOptions{
      UserID:        &#x22;user_123&#x22;,
      CheckType:     &#x22;birthday&#x22;,
      Intent:        &#x22;wish the user a happy birthday&#x22;,
      ScheduledAt:   &#x22;2026-06-15T09:00:00Z&#x22;, // RFC3339 absolute timestamp
      Occasion:      &#x22;Sarah's 30th birthday&#x22;,
      InterestTopic: &#x22;celebration and birthday traditions&#x22;,
  },
)
if err != nil { panic(err) }

fmt.Println(wakeup.WakeupID)   // &#x22;wake_01HX...&#x22;
fmt.Println(wakeup.ScheduledAt) // &#x22;2026-06-15T09:00:00Z&#x22;`,
  },
]"
/>

## Core concepts [#core-concepts]

### delay\_hours and scheduled\_at [#delay_hours-and-scheduled_at]

Two mutually exclusive time inputs are supported:

* **`delay_hours`** — a relative offset from the current moment (e.g. `delay_hours: 24` fires tomorrow at roughly this time). The platform computes the absolute fire time at the moment the request is accepted. Use this for "N hours from now" semantics where no specific date matters.
* **`scheduled_at`** — an RFC3339 absolute timestamp (e.g. `"2026-06-15T09:00:00Z"`). Use this for birthdays, appointments, or any event tied to a specific calendar date. The platform fires the wakeup as close to this time as possible.

If **both** are provided, `scheduled_at` takes precedence. `scheduled_at` in the **response** is always present and is the authoritative UTC time the wakeup will fire — store it if you want to show the user "your agent will reach out at X".

### occasion, interest\_topic, and event\_description [#occasion-interest_topic-and-event_description]

These optional context fields are included in the agent's wakeup block at fire time, giving it richer material for personalised message composition:

* **`occasion`** — a short human-readable label for the event (e.g. `"Sarah's 30th birthday"`, `"dentist appointment"`). The agent may reference this directly in the message.
* **`interest_topic`** — a topic or theme the agent should lean on when composing the message (e.g. `"celebration and birthday traditions"`, `"dental health tips"`).
* **`event_description`** — a longer free-form description with any additional context the agent should know (e.g. `"User is turning 30 and has mentioned wanting to celebrate with a surprise party"`).

All three are optional and additive — provide as many or as few as are useful. The agent's underlying model uses them as soft context, not as a rigid template.

### check\_type and intent [#check_type-and-intent]

Both fields are free-form strings. The agent receives both as part of its wakeup context at fire time:

* **`check_type`** is a short label that tells the agent the nature of the outreach (`"birthday"`, `"appointment_reminder"`, `"interest_followup"`, etc.). Keep it lowercase and underscore-separated — it is machine-readable context, not a display string.
* **`intent`** is a natural-language instruction to the agent describing what the message should accomplish. Write it as you would write a system instruction: `"ask how the job interview went and whether they got an offer"`.

Neither field has a fixed enum — any string is valid. The agent's underlying model interprets them in context.

### Lifecycle and status [#lifecycle-and-status]

A wakeup moves through three statuses:

| Status      | Meaning                                            |
| ----------- | -------------------------------------------------- |
| `pending`   | Scheduled, not yet fired                           |
| `executed`  | Fired; message delivered to the notification queue |
| `cancelled` | Cancelled before it fired                          |

Once a wakeup reaches `executed` or `cancelled` it is immutable. To cancel a pending wakeup, call `getWakeups` to retrieve the `wakeup_id`, then cancel it via the API before `scheduled_at` passes.

### One-off, not recurring [#one-off-not-recurring]

Each call to `scheduleWakeup` creates exactly one future fire. If you need to re-schedule after a wakeup executes (for example, to send a birthday greeting every year), schedule a new wakeup the next time you learn the date. For repeating outreach on a fixed cadence, use [Scheduled Reminders](./scheduled-reminders) instead.

## Full API [#full-api]

All wakeup methods live under `client.agents.*` (TS/Python) or `client.Agents.Wakeups` (Go). Full request and response shapes are in the [API reference](./api-reference).

| Method                                     | Returns            | Description                                  |
| ------------------------------------------ | ------------------ | -------------------------------------------- |
| `scheduleWakeup(agentId, opts)`            | `WakeupResponse`   | Schedule a one-off wakeup                    |
| `getWakeups(agentId, { status?, limit? })` | `WakeupResponse[]` | List wakeups (optionally filtered by status) |

**`scheduleWakeup` input fields:**

| Field               | Type             | Description                                                                                                  |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `user_id`           | string           | Required. The user the wakeup is for.                                                                        |
| `check_type`        | string           | Required. Short label for the nature of the outreach (e.g. `"birthday"`, `"appointment_reminder"`).          |
| `intent`            | string           | Required. Natural-language instruction for the agent describing what the message should accomplish.          |
| `delay_hours`       | number           | Relative offset from now. Mutually exclusive with `scheduled_at`; `scheduled_at` wins if both are set.       |
| `scheduled_at`      | string (RFC3339) | Absolute fire time. Use for birthdays, appointments, or any event with a specific date.                      |
| `occasion`          | string           | Optional short label for the event (e.g. `"Sarah's 30th birthday"`). Included in the agent's wakeup context. |
| `interest_topic`    | string           | Optional topic or theme for the agent to lean on when composing the message.                                 |
| `event_description` | string           | Optional longer description with additional context for the agent.                                           |

`WakeupResponse` fields: `wakeup_id`, `agent_id`, `user_id`, `scheduled_at`, `check_type`, `status`, `intent`, `occasion`, `interest_topic`, `event_description`, `last_topic`, `research_summary`, `executed_at`, `created_at`.

## Combines with other features [#combines-with-other-features]

### With [Scheduled Reminders](./scheduled-reminders) — one-off vs recurring [#with-scheduled-reminders--one-off-vs-recurring]

Schedules and Wakeups are complementary proactive primitives. The rule is simple: if the agent should reach out **more than once** on a predictable cadence, use a schedule. If the agent should reach out **exactly once** at a known moment, use a wakeup. Both feed into the same downstream delivery channels.

```ts
// Recurring: a daily morning check-in schedule
await client.schedules.create("agent_abc", "user_123", {
  cadence: {
    simple: { frequency: "daily", times: ["09:00"] },
    timezone: "Asia/Singapore",
  },
  intent: "morning mood and sleep check-in",
  check_type: "reminder",
});

// One-off: a wakeup on the day of the user's birthday
await client.agents.scheduleWakeup("agent_abc", {
  user_id:     "user_123",
  check_type:  "birthday",
  intent:      "wish the user a happy birthday on their 30th",
  delay_hours: 48,
});
```

A common pattern is to use both together: a recurring schedule for everyday outreach, and a wakeup for a special moment that doesn't fit the cadence.

### With [Memory](./memory) — context-aware wakeup scheduling [#with-memory--context-aware-wakeup-scheduling]

The agent can read memory facts to decide when and what to schedule. For example, if a user mentions their anniversary date, the agent can search memory to retrieve that date and schedule a wakeup for the right moment. The wakeup then fires with the agent already knowing why it is reaching out.

```ts
// 1. User mentioned an upcoming anniversary — find it in memory
const memories = await client.agents.memory.search("agent_abc", {
  query: "anniversary date",
  limit: 5,
});

// 2. Parse the date from the top result and compute delay_hours
const anniversaryFact = memories.results[0].content;
// e.g. "User's wedding anniversary is April 30"
const hoursUntilAnniversary = computeHoursUntil("2026-04-30");

// 3. Schedule a wakeup for that exact moment
// Use scheduled_at for a known date, or delay_hours for "N hours from now"
await client.agents.scheduleWakeup("agent_abc", {
  user_id:          "user_123",
  check_type:       "anniversary",
  intent:           "wish the user a happy anniversary and ask how they are celebrating",
  scheduled_at:     "2026-04-30T09:00:00Z",  // the anniversary date
  occasion:         "User's wedding anniversary",
  event_description: anniversaryFact,
});
```

Because the agent has memory of the conversation in which the user shared the anniversary date, the wakeup message will feel naturally aware of the context — not generic.

### With [Webhooks & Notifications](./webhooks) — receiving the fired message [#with-webhooks--notifications--receiving-the-fired-message]

When a wakeup fires, the generated message lands in the agent's notification queue. Your backend can consume it via SSE polling or a registered webhook. The event type is the same as any other proactive message; you don't need special handling for wakeup-originated messages vs schedule-originated ones.

```ts
// Poll for any pending proactive messages (wakeups or schedules)
const notifications = await client.agents.notifications.poll("agent_abc", {
  user_id: "user_123",
});

for (const n of notifications) {
  console.log(n.content);     // the agent's message text
  console.log(n.source_type); // "wakeup" | "schedule"
}
```

See [Webhooks & Notifications](./webhooks) for webhook registration, signature verification, and SSE consumption patterns.

## Tutorials [#tutorials]

No dedicated tutorial yet. The [Scheduled Reminders tutorial](./tutorial-scheduled-reminders) covers the same delivery infrastructure — most concepts transfer directly.

## Next steps [#next-steps]

* [Scheduled Reminders](./scheduled-reminders) — recurring proactive outreach on a cadence
* [Memory](./memory) — how the agent builds the context it uses when a wakeup fires
* [Webhooks & Notifications](./webhooks) — how to consume wakeup messages in your backend


---

# Webhooks

Source: https://sonz.ai/docs/en/webhooks

> Receive proactive agent messages at a URL you control — signed webhook delivery for push notifications, email/SMS fanout, and server-to-server integrations.



Register a webhook URL per tenant (or per project) and Sonzai will HTTP POST every proactive agent message to that URL with a signed payload. Each request includes a `Sonzai-Signature` header you verify with your signing secret before acting on the payload. Use webhooks for server-to-server delivery where you own the downstream routing — forwarding to FCM/APNs, sending via SendGrid or Twilio, writing to a case-management system, or fanning out to multiple channels at once.

## What you can build with it [#what-you-can-build-with-it]

* **Push notifications** — webhook handler forwards the agent message to FCM (Android) or APNs (iOS)
* **Email / SMS fanout** — webhook handler sends through SendGrid, Postmark, Twilio, or any provider you already use
* **Multi-channel delivery** — fan a single agent message to two or more user channels in one handler
* **Downstream analytics** — log and inspect every proactive message before it reaches the user
* **Enterprise integrations** — route agent messages into Slack, Microsoft Teams, internal tooling, or CRM workflows

## Quickstart [#quickstart]

Register a webhook URL to start receiving `on_wakeup_ready` events. Save the `signing_secret` from the response — it is only returned once.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const result = await client.webhooks.register(&#x22;on_wakeup_ready&#x22;, {
webhookUrl: &#x22;https://your-server.com/webhooks/sonzai&#x22;,
authHeader: &#x22;Bearer your-webhook-secret&#x22;,
});

// Store this securely — shown only once
console.log(result.signingSecret);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

result = client.webhooks.register(
  &#x22;on_wakeup_ready&#x22;,
  webhook_url=&#x22;https://your-server.com/webhooks/sonzai&#x22;,
  auth_header=&#x22;Bearer your-webhook-secret&#x22;,
)

# Store this securely — shown only once
print(result.signing_secret)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import &#x22;github.com/sonzai-labs/sonzai-go&#x22;

client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))

result, err := client.Webhooks.Register(ctx, &#x22;on_wakeup_ready&#x22;, sonzai.WebhookRegisterOptions{
  WebhookURL: &#x22;https://your-server.com/webhooks/sonzai&#x22;,
  AuthHeader: &#x22;Bearer your-webhook-secret&#x22;,
})
if err != nil { panic(err) }

// Store this securely — shown only once
fmt.Println(result.SigningSecret)`,
  },
]"
/>

## Core concepts [#core-concepts]

### Registration [#registration]

Webhooks are registered per event type. One URL per event type per tenant, or per project when using project-scoped registration. The same URL can handle multiple event types — inspect the `event_type` field on the payload to route accordingly.

Available event types:

| Event type               | Fires when                                    |
| ------------------------ | --------------------------------------------- |
| `on_wakeup_ready`        | An agent wakeup generates a proactive message |
| `on_diary_generated`     | The agent's diary entry is written            |
| `on_personality_updated` | A significant personality shift is detected   |
| `on_recurring_event_due` | A scheduled reminder fires                    |

### Signed payload [#signed-payload]

Every POST Sonzai sends includes a `Sonzai-Signature` header in the format:

```
Sonzai-Signature: t=1714000000,v1=abc123def456...
```

`t` is the Unix timestamp of the request; `v1` is the HMAC-SHA256 of `{timestamp}.{raw_body}` using your signing secret (with the `whsec_` prefix stripped). Always verify the signature **on the raw, unmodified request body** before parsing JSON — do not use the parsed object for verification.

### Retries [#retries]

When your endpoint returns a non-2xx status or times out, Sonzai retries with exponential backoff. Make your handler idempotent — deduplicate on `event_id` (or a stable field in the payload body) so retried deliveries do not double-process.

### Payload shape [#payload-shape]

The webhook body matches the `Notification` shape returned by the polling API. Key fields:

| Field               | Type     | Description                                        |
| ------------------- | -------- | -------------------------------------------------- |
| `event_type`        | `string` | The registered event type (e.g. `on_wakeup_ready`) |
| `agent_id`          | `string` | The agent that generated the message               |
| `user_id`           | `string` | The target user                                    |
| `generated_message` | `string` | The agent's proactive message text                 |
| `check_type`        | `string` | Wakeup or reminder context label                   |
| `message_id`        | `string` | Stable ID; use for deduplication                   |

### Signature verification [#signature-verification]

Verify the `Sonzai-Signature` header before acting on any payload. The Go SDK ships a helper; TypeScript and Python use standard crypto primitives.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import crypto from &#x22;node:crypto&#x22;;

/**
* Verify a Sonzai webhook signature.
* Call this on the raw request body string before parsing JSON.
*/
function verifyWebhookSignature(
rawBody: string,
signatureHeader: string,
secret: string,
): boolean {
// Strip whsec_ prefix if present
const key = secret.startsWith(&#x22;whsec_&#x22;) ? secret.slice(6) : secret;

// Parse header: t={timestamp},v1={sig}
const parts = Object.fromEntries(
  signatureHeader.split(&#x22;,&#x22;).map((p) => p.split(&#x22;=&#x22;)),
);
const timestamp = parts[&#x22;t&#x22;];
const receivedSig = parts[&#x22;v1&#x22;];
if (!timestamp || !receivedSig) return false;

const expectedSig = crypto
  .createHmac(&#x22;sha256&#x22;, key)
  .update(\`\${timestamp}.\${rawBody}\`)
  .digest(&#x22;hex&#x22;);

return crypto.timingSafeEqual(
  Buffer.from(receivedSig),
  Buffer.from(expectedSig),
);
}

// In your webhook handler (e.g. Express):
app.post(&#x22;/webhooks/sonzai&#x22;, express.raw({ type: &#x22;*/*&#x22; }), (req, res) => {
const sig = req.headers[&#x22;sonzai-signature&#x22;] as string;
const rawBody = req.body.toString(&#x22;utf-8&#x22;);

if (!verifyWebhookSignature(rawBody, sig, process.env.SONZAI_WEBHOOK_SECRET!)) {
  return res.status(401).send(&#x22;Invalid signature&#x22;);
}

const event = JSON.parse(rawBody);
// Forward to your channel...
res.status(200).send(&#x22;ok&#x22;);
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import hashlib
import hmac
import os

def verify_webhook_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
  &#x22;&#x22;&#x22;Verify a Sonzai webhook signature.&#x22;&#x22;&#x22;
  # Strip whsec_ prefix if present
  key = secret.removeprefix(&#x22;whsec_&#x22;).encode()

  # Parse header: t={timestamp},v1={sig}
  parts = dict(p.split(&#x22;=&#x22;, 1) for p in signature_header.split(&#x22;,&#x22;))
  timestamp = parts.get(&#x22;t&#x22;)
  received_sig = parts.get(&#x22;v1&#x22;)
  if not timestamp or not received_sig:
      return False

  signed_payload = f&#x22;{timestamp}.&#x22;.encode() + raw_body
  expected_sig = hmac.new(key, signed_payload, hashlib.sha256).hexdigest()
  return hmac.compare_digest(received_sig, expected_sig)

# In your webhook handler (e.g. Flask):
from flask import Flask, request, abort
import json

app = Flask(__name__)

@app.route(&#x22;/webhooks/sonzai&#x22;, methods=[&#x22;POST&#x22;])
def webhook():
  sig = request.headers.get(&#x22;Sonzai-Signature&#x22;, &#x22;&#x22;)
  raw_body = request.get_data()  # raw, unmodified

  if not verify_webhook_signature(raw_body, sig, os.environ[&#x22;SONZAI_WEBHOOK_SECRET&#x22;]):
      abort(401)

  event = json.loads(raw_body)
  # Forward to your channel...
  return &#x22;ok&#x22;, 200`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;io&#x22;
  &#x22;net/http&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonzai-labs/sonzai-go&#x22;
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  body, err := io.ReadAll(r.Body)
  if err != nil {
      http.Error(w, &#x22;bad request&#x22;, http.StatusBadRequest)
      return
  }

  sig := r.Header.Get(&#x22;Sonzai-Signature&#x22;)
  secret := os.Getenv(&#x22;SONZAI_WEBHOOK_SECRET&#x22;)

  if err := sonzai.VerifyWebhookSignature(body, sig, secret); err != nil {
      http.Error(w, &#x22;invalid signature&#x22;, http.StatusUnauthorized)
      return
  }

  // Safe to parse and act on the payload
  // Forward to your downstream channel...
  w.WriteHeader(http.StatusOK)
}`,
  },
]"
/>

<Callout type="warning" title="Timestamp tolerance">
  The Go SDK rejects signatures older than 5 minutes by default. In TypeScript and Python implementations, add a timestamp check if you need to guard against replay attacks: compare `parseInt(parts["t"]) * 1000` against `Date.now()` and reject if the difference exceeds 300 000 ms.
</Callout>

## Full API [#full-api]

All methods are on `client.webhooks` (TS/Python) or `client.Webhooks` (Go).

| Method                                                 | Returns                    | Description                                                                                              |
| ------------------------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `register(eventType, opts)`                            | `WebhookRegisterResponse`  | Register or update a webhook URL for an event type. `signing_secret` is returned only on first creation. |
| `list()`                                               | `WebhookListResponse`      | List all registered webhooks for this tenant                                                             |
| `delete(eventType)`                                    | `void`                     | Remove a webhook registration                                                                            |
| `listDeliveryAttempts(eventType)`                      | `DeliveryAttemptsResponse` | Inspect recent delivery history (status, response code, duration)                                        |
| `rotateSecret(eventType)`                              | `WebhookRegisterResponse`  | Generate a new signing secret; old secret stays valid briefly to allow rotation                          |
| `registerForProject(projectId, eventType, opts)`       | `WebhookRegisterResponse`  | Register a project-scoped webhook                                                                        |
| `listForProject(projectId)`                            | `WebhookListResponse`      | List webhooks for a project                                                                              |
| `deleteForProject(projectId, eventType)`               | `void`                     | Remove a project-scoped webhook                                                                          |
| `listDeliveryAttemptsForProject(projectId, eventType)` | `DeliveryAttemptsResponse` | Delivery history for a project webhook                                                                   |
| `rotateSecretForProject(projectId, eventType)`         | `WebhookRegisterResponse`  | Rotate signing secret for a project webhook                                                              |

`WebhookEndpoint` fields: `event_type`, `webhook_url`, `auth_header`, `is_active`, `created_at`.

`WebhookDeliveryAttempt` fields: `attempt_id`, `event_type`, `webhook_url`, `response_code`, `response_body`, `error_message`, `duration_ms`, `attempt_number`, `status`, `created_at`.

## Combines with [#combines-with]

### With [Notifications polling](./notifications-polling) — alternative consumption model [#with-notifications-polling--alternative-consumption-model]

Webhooks and polling are two consumption models for the same proactive message queue. Webhooks push to your server in real time; polling lets your client or server fetch on demand. Use webhooks when you have a stable server endpoint and need instant delivery. Use polling when your client cannot accept inbound HTTP connections (mobile apps, browser clients) or when you want to batch-process notifications on your own schedule. Both see the same payload shape.

```ts
// Polling alternative — same messages, pulled instead of pushed
const pending = await client.agents.notifications.list("agent_abc", {
  userId: "user_123",
  status: "pending",
});

for (const notif of pending.notifications) {
  console.log(notif.generated_message);
  await client.agents.notifications.consume("agent_abc", notif.message_id);
}
```

### With [Scheduled Reminders](./scheduled-reminders) — fan recurring reminders to channels [#with-scheduled-reminders--fan-recurring-reminders-to-channels]

When a scheduled reminder fires, an `on_recurring_event_due` webhook delivers the generated message to your endpoint. Your handler can then forward to FCM, send an email, or post to Slack — all without polling. This separates the scheduling concern (when to fire) from the delivery concern (how to reach the user).

```ts
// Register once; every scheduled reminder fires this endpoint
const result = await client.webhooks.register("on_recurring_event_due", {
  webhookUrl: "https://api.yourapp.com/webhooks/sonzai",
});

// In your handler, forward to the appropriate channel:
// event.generated_message → FCM, email, SMS, Slack...
```

### With [Wakeups](./wakeups) — push one-off check-ins [#with-wakeups--push-one-off-check-ins]

When a wakeup fires, the `on_wakeup_ready` event is POSTed to your registered endpoint. This is the primary webhook event for companion-style agents that reach out proactively. Register the webhook once and every future wakeup — automatic or manually scheduled — will arrive at your URL.

```ts
// Register to receive all future wakeup messages
await client.webhooks.register("on_wakeup_ready", {
  webhookUrl: "https://api.yourapp.com/webhooks/sonzai",
});

// Your handler receives the wakeup message and forwards it:
// event.generated_message → push notification
// event.user_id          → lookup device token in your DB
// event.agent_id         → identify which agent sent it
```

## Tutorials [#tutorials]

No dedicated webhook tutorial yet. The [Scheduled Reminders tutorial](./tutorial-scheduled-reminders) covers the full proactive delivery pipeline and includes webhook-based consumption patterns.

## Next steps [#next-steps]

* [Notifications polling](./notifications-polling) — pull-based alternative for clients that cannot receive inbound HTTP
* [Scheduled Reminders](./scheduled-reminders) — recurring proactive messages that fire over webhooks
* [Wakeups](./wakeups) — one-off proactive messages delivered via `on_wakeup_ready`


---

# Evaluation & Simulation

Source: https://sonz.ai/docs/en/guides/evaluation

> Score agent quality, run multi-turn simulations, and benchmark personality consistency.



## Evaluate a Response [#evaluate-a-response]

Score an agent's response against a template rubric.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const result = await client.agents.evaluate(&#x22;agent-id&#x22;, {
templateId: &#x22;template-id&#x22;,
messages: [
  { role: &#x22;user&#x22;, content: &#x22;I'm feeling really stressed about work&#x22; },
  { role: &#x22;assistant&#x22;, content: &#x22;I hear you. Work stress can be overwhelming...&#x22; },
],
});

console.log(result.score);       // 0-100
console.log(result.feedback);    // detailed feedback
console.log(result.categories);  // per-category scores`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = client.agents.evaluate(
  &#x22;agent-id&#x22;,
  template_id=&#x22;template-id&#x22;,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;I'm feeling really stressed about work&#x22;},
      {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: &#x22;I hear you. Work stress can be overwhelming...&#x22;},
  ],
)

print(result.score)       # 0-100
print(result.feedback)    # detailed feedback
print(result.categories)  # per-category scores`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := client.Eval.Evaluate(ctx, &#x22;agent-id&#x22;, eval.EvaluateOptions{
  TemplateID: &#x22;template-id&#x22;,
  Messages: []eval.Message{
      {Role: &#x22;user&#x22;, Content: &#x22;I'm feeling really stressed about work&#x22;},
      {Role: &#x22;assistant&#x22;, Content: &#x22;I hear you. Work stress can be overwhelming...&#x22;},
  },
})

fmt.Println(result.Score)
fmt.Println(result.Feedback)`,
  },
]"
/>

## Evaluation Templates [#evaluation-templates]

Create scoring rubrics with weighted categories.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Create a template
const template = await client.evalTemplates.create({
name: &#x22;Empathy & Support&#x22;,
description: &#x22;Evaluates emotional intelligence and supportive responses&#x22;,
scoringRubric: &#x22;Score based on empathy, active listening, and actionable advice&#x22;,
categories: [&#x22;empathy&#x22;, &#x22;active_listening&#x22;, &#x22;actionable_advice&#x22;],
judgeModel: &#x22;claude-sonnet-4-6&#x22;,
temperature: 0.3,
});

// List templates
const templates = await client.evalTemplates.list();`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `template = client.eval_templates.create(
  name=&#x22;Empathy & Support&#x22;,
  description=&#x22;Evaluates emotional intelligence and supportive responses&#x22;,
  scoring_rubric=&#x22;Score based on empathy, active listening, and actionable advice&#x22;,
  categories=[&#x22;empathy&#x22;, &#x22;active_listening&#x22;, &#x22;actionable_advice&#x22;],
  judge_model=&#x22;claude-sonnet-4-6&#x22;,
  temperature=0.3,
)

templates = client.eval_templates.list()`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `template, err := client.Eval.Templates.Create(ctx, eval.TemplateCreateOptions{
  Name:          &#x22;Empathy & Support&#x22;,
  Description:   &#x22;Evaluates emotional intelligence and supportive responses&#x22;,
  ScoringRubric: &#x22;Score based on empathy, active listening, and actionable advice&#x22;,
  Categories:    []string{&#x22;empathy&#x22;, &#x22;active_listening&#x22;, &#x22;actionable_advice&#x22;},
  JudgeModel:    &#x22;claude-sonnet-4-6&#x22;,
  Temperature:   0.3,
})

templates, err := client.Eval.Templates.List(ctx, nil)`,
  },
]"
/>

## Run a Simulation [#run-a-simulation]

Run multi-turn simulated conversations to test agent behavior at scale.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.simulate(&#x22;agent-id&#x22;, {
maxSessions: 3,
maxTurnsPerSession: 10,
simulatedDurationHours: 24,
enableProactive: true,
enableConsolidation: true,
userPersonas: [
  {
    name: &#x22;Alex&#x22;,
    background: &#x22;College student struggling with math&#x22;,
    personalityTraits: [&#x22;anxious&#x22;, &#x22;eager to learn&#x22;],
    communicationStyle: &#x22;casual, uses slang&#x22;,
  },
],
})) {
console.log(\`[\${event.type}] \${event.message}\`);
if (event.totalCostUsd) {
  console.log(\`Cost so far: $\${event.totalCostUsd}\`);
}
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.simulate(
  &#x22;agent-id&#x22;,
  max_sessions=3,
  max_turns_per_session=10,
  simulated_duration_hours=24,
  enable_proactive=True,
  enable_consolidation=True,
  user_personas=[{
      &#x22;name&#x22;: &#x22;Alex&#x22;,
      &#x22;background&#x22;: &#x22;College student struggling with math&#x22;,
      &#x22;personality_traits&#x22;: [&#x22;anxious&#x22;, &#x22;eager to learn&#x22;],
      &#x22;communication_style&#x22;: &#x22;casual, uses slang&#x22;,
  }],
):
  print(f&#x22;[{event.type}] {event.message}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Eval.Simulate(ctx, &#x22;agent-id&#x22;, eval.SimulateOptions{
  MaxSessions:           3,
  MaxTurnsPerSession:    10,
  SimulatedDurationHours: 24,
  EnableProactive:       true,
  EnableConsolidation:   true,
  UserPersonas: []eval.UserPersona{
      {
          Name:               &#x22;Alex&#x22;,
          Background:         &#x22;College student struggling with math&#x22;,
          PersonalityTraits:  []string{&#x22;anxious&#x22;, &#x22;eager to learn&#x22;},
          CommunicationStyle: &#x22;casual, uses slang&#x22;,
      },
  },
}, func(event eval.SimulationEvent) error {
  fmt.Printf(&#x22;[%s] %s\\n&#x22;, event.Type, event.Message)
  return nil
})`,
  },
]"
/>

## Simulation + Evaluation (runEval) [#simulation--evaluation-runeval]

Combine simulation and evaluation in one step.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.runEval(&#x22;agent-id&#x22;, {
templateId: &#x22;template-id&#x22;,
maxSessions: 5,
maxTurnsPerSession: 8,
})) {
if (event.type === &#x22;evaluation&#x22;) {
  console.log(&#x22;Score:&#x22;, event.score);
}
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.run_eval(
  &#x22;agent-id&#x22;,
  template_id=&#x22;template-id&#x22;,
  max_sessions=5,
  max_turns_per_session=8,
):
  if event.type == &#x22;evaluation&#x22;:
      print(&#x22;Score:&#x22;, event.score)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Eval.Run(ctx, &#x22;agent-id&#x22;, eval.RunEvalOptions{
  TemplateID:         &#x22;template-id&#x22;,
  MaxSessions:        5,
  MaxTurnsPerSession: 8,
}, func(event eval.SimulationEvent) error {
  fmt.Printf(&#x22;[%s] %s\\n&#x22;, event.Type, event.Message)
  return nil
})`,
  },
]"
/>

## Eval Runs [#eval-runs]

Track and manage simulation runs.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// List runs
const runs = await client.evalRuns.list({ agentId: &#x22;agent-id&#x22; });

// Get a specific run
const run = await client.evalRuns.get(&#x22;run-id&#x22;);

// Reconnect to a streaming run
for await (const event of client.evalRuns.streamEvents(&#x22;run-id&#x22;)) {
console.log(event.type, event.message);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `runs = client.eval_runs.list(agent_id=&#x22;agent-id&#x22;)
run = client.eval_runs.get(&#x22;run-id&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `runs, err := client.Eval.Runs.List(ctx, &eval.RunListOptions{AgentID: &#x22;agent-id&#x22;})
run, err := client.Eval.Runs.Get(ctx, &#x22;run-id&#x22;)`,
  },
]"
/>

<Callout type="info" title="Async Simulations">
  Simulations support async mode via `simulateAsync()` which returns a RunRef immediately, allowing you to poll or reconnect later.
</Callout>


---

# Quickstart

Source: https://sonz.ai/docs/en/guides/getting-started

> Get your first AI agent running with the Relationship Layer.



## 1. Create a Project [#1-create-a-project]

Go to [Projects](https://platform.sonz.ai/dashboard/projects) and create a new project. A project groups your agents and provides an API key for authentication.

## 2. Get Your API Key [#2-get-your-api-key]

In your project settings, generate an API key. This key authenticates all REST API calls to the Relationship Layer.

```bash
# All requests require Bearer auth
Authorization: Bearer YOUR_API_KEY
```

## 3. Install the SDK (or skip it) [#3-install-the-sdk-or-skip-it]

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

<InstallTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    language: &#x22;bash&#x22;,
    subTabs: [
      { id: &#x22;pip&#x22;, label: &#x22;pip&#x22;, code: `pip install sonzai` },
      { id: &#x22;uv&#x22;, label: &#x22;uv&#x22;, code: `uv add sonzai` },
      { id: &#x22;poetry&#x22;, label: &#x22;poetry&#x22;, code: `poetry add sonzai` },
      { id: &#x22;pipenv&#x22;, label: &#x22;pipenv&#x22;, code: `pipenv install sonzai` },
    ],
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript / JavaScript&#x22;,
    language: &#x22;bash&#x22;,
    subTabs: [
      { id: &#x22;npm&#x22;, label: &#x22;npm&#x22;, code: `npm install @sonzai-labs/agents` },
      { id: &#x22;bun&#x22;, label: &#x22;bun&#x22;, code: `bun add @sonzai-labs/agents` },
      { id: &#x22;pnpm&#x22;, label: &#x22;pnpm&#x22;, code: `pnpm add @sonzai-labs/agents` },
      { id: &#x22;yarn&#x22;, label: &#x22;yarn&#x22;, code: `yarn add @sonzai-labs/agents` },
      {
        id: &#x22;deno&#x22;,
        label: &#x22;Deno&#x22;,
        language: &#x22;ts&#x22;,
        code: `import { Sonzai } from &#x22;npm:@sonzai-labs/agents&#x22;;`,
      },
    ],
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    language: &#x22;bash&#x22;,
    code: `go get github.com/sonz-ai/sonzai-go@latest`,
  },
  {
    id: &#x22;rest&#x22;,
    label: &#x22;REST&#x22;,
    language: &#x22;bash&#x22;,
    code: `curl https://api.sonz.ai/v1/agents \\
-H &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{ &#x22;name&#x22;: &#x22;Luna&#x22;, &#x22;language&#x22;: &#x22;en&#x22; }'`,
  },
  {
    id: &#x22;mcp&#x22;,
    label: &#x22;MCP&#x22;,
    subTabs: [
      {
        id: &#x22;claude-code&#x22;,
        label: &#x22;Claude Code&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Single command — registers the hosted MCP server with Claude Code:
claude mcp add --transport http sonzai \\
https://api.sonz.ai/mcp/memory/AGENT_ID \\
--header &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22;`,
      },
      {
        id: &#x22;cursor&#x22;,
        label: &#x22;Cursor / VS Code&#x22;,
        language: &#x22;json&#x22;,
        code: `// ~/.cursor/mcp.json (Cursor) — VS Code uses .vscode/mcp.json with the
// top-level key &#x22;servers&#x22; instead of &#x22;mcpServers&#x22;.
{
&#x22;mcpServers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;type&#x22;: &#x22;http&#x22;,
    &#x22;url&#x22;: &#x22;https://api.sonz.ai/mcp/memory/AGENT_ID&#x22;,
    &#x22;headers&#x22;: { &#x22;Authorization&#x22;: &#x22;Bearer YOUR_API_KEY&#x22; }
  }
}
}`,
      },
      {
        id: &#x22;chatgpt&#x22;,
        label: &#x22;ChatGPT&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Plus / Pro / Business / Enterprise / Edu (Developer Mode beta).
# 1. Settings → Connectors → Advanced → Developer Mode ON
# 2. Add custom connector:
#      URL:    https://api.sonz.ai/mcp/memory/AGENT_ID
#      Header: Authorization: Bearer YOUR_API_KEY`,
      },
      {
        id: &#x22;claude-desktop&#x22;,
        label: &#x22;Claude Desktop&#x22;,
        language: &#x22;bash&#x22;,
        code: `# JSON config supports stdio servers only — for the hosted endpoint use
# the in-app Connectors UI:
#   Settings → Connectors → Add custom connector
#     URL:    https://api.sonz.ai/mcp/memory/AGENT_ID
#     Auth:   Authorization: Bearer YOUR_API_KEY`,
      },
      {
        id: &#x22;stdio&#x22;,
        label: &#x22;Local binary (offline)&#x22;,
        language: &#x22;json&#x22;,
        code: `// Optional fallback for stdio-only or air-gapped clients.
// 1. Install the binary (Go 1.25+):
//      go install github.com/sonz-ai/sonzai-mcp/cmd/mcp-server@latest
// 2. Add to your client config (e.g. ~/Library/Application Support/Claude/
//    claude_desktop_config.json on macOS):
{
&#x22;mcpServers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;command&#x22;: &#x22;sonzai-mcp&#x22;,
    &#x22;env&#x22;: { &#x22;SONZAI_API_KEY&#x22;: &#x22;sk-your-api-key&#x22; }
  }
}
}`,
      },
    ],
  },
  {
    id: &#x22;openclaw&#x22;,
    label: &#x22;OpenClaw&#x22;,
    subTabs: [
      {
        id: &#x22;one-shot&#x22;,
        label: &#x22;One-shot&#x22;,
        language: &#x22;bash&#x22;,
        code: `# Prereq — install OpenClaw itself first (see openclaw.ai):
#   npm install -g openclaw@latest
#   openclaw onboard --install-daemon

# Then register the Sonzai context engine in one command:
npx --yes @sonzai-labs/openclaw-context install

# Probes Sonzai backend health, runs 'openclaw plugins install',
# launches the interactive wizard, writes ~/.openclaw/openclaw.json.`,
      },
      {
        id: &#x22;manual&#x22;,
        label: &#x22;Manual&#x22;,
        language: &#x22;bash&#x22;,
        code: `# 1. Install the plugin via the OpenClaw CLI:
openclaw plugins install @sonzai-labs/openclaw-context

# 2. Run the Sonzai setup wizard (writes openclaw.json with API key + agent ID):
npx @sonzai-labs/openclaw-context setup

# 3. Restart the gateway:
openclaw gateway restart`,
      },
      {
        id: &#x22;config&#x22;,
        label: &#x22;openclaw.json&#x22;,
        language: &#x22;json&#x22;,
        code: `// ~/.openclaw/openclaw.json — flip the contextEngine slot to &#x22;sonzai&#x22;.
// (The wizard writes this for you; included here for hand-edits and CI.)
{
&#x22;plugins&#x22;: {
  &#x22;slots&#x22;: {
    &#x22;contextEngine&#x22;: &#x22;sonzai&#x22;
  },
  &#x22;entries&#x22;: {
    &#x22;sonzai&#x22;: {
      &#x22;enabled&#x22;: true,
      &#x22;apiKey&#x22;: &#x22;sk-your-api-key&#x22;,
      &#x22;agentId&#x22;: &#x22;your-agent-uuid&#x22;
    }
  }
}
}`,
      },
    ],
  },
]"
/>

* **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.
* **OpenClaw** itself is required for the OpenClaw path — install it from [openclaw.ai](https://openclaw.ai) ([Getting Started](https://docs.openclaw.ai/start/getting-started)).
* Full guides: [MCP](/docs/en/guides/mcp-integration) · [OpenClaw](/docs/en/guides/openclaw-integration) · [REST API Reference](/docs/en/reference/api-reference).

<Callout type="info" title="API key handling">
  The TypeScript, Python, and Go SDKs all read `SONZAI_API_KEY` from the environment by default — pass it explicitly (e.g. `new Sonzai({ apiKey: "sk-..." })`) only if you'd rather manage it yourself. The OpenClaw plugin stores its key in `openclaw.json`. The MCP server takes it via the `SONZAI_API_KEY` env var passed by the client config.
</Callout>

## 4. Create an Agent [#4-create-an-agent]

There are two ways to create an agent: define personality traits explicitly with Big5 scores, or generate one from a natural language prompt.

### Option A: Generate from a Prompt [#option-a-generate-from-a-prompt]

Describe your agent in plain language and the platform generates personality, bio, and seed memories automatically.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk-...&#x22; });

const agent = await client.agents.generation.generateAndCreate({
name: &#x22;Luna&#x22;,
description: &#x22;A cheerful and curious AI assistant who loves helping developers debug code. She's patient, witty, and always encouraging.&#x22;,
language: &#x22;en&#x22;,
});

console.log(agent.agent_id);        // auto-generated UUID
console.log(agent.personality);    // full Big5 profile derived from description`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

client = Sonzai(api_key=&#x22;sk-...&#x22;)

agent = client.agents.generation.generate_and_create(
  name=&#x22;Luna&#x22;,
  description=&#x22;A cheerful and curious AI assistant who loves helping developers debug code. She's patient, witty, and always encouraging.&#x22;,
  language=&#x22;en&#x22;,
)

print(agent.agent_id)       # auto-generated UUID
print(agent.big5)    # full Big5 profile derived from description`,
  },
  {
    id: &#x22;py-async&#x22;,
    label: &#x22;Python (async)&#x22;,
    code: `import asyncio
from sonzai import AsyncSonzai

async def main():
  async with AsyncSonzai(api_key=&#x22;sk-...&#x22;) as client:
      agent = await client.agents.generation.generate_and_create(
          name=&#x22;Luna&#x22;,
          description=&#x22;A cheerful and curious AI assistant who loves helping developers debug code.&#x22;,
          language=&#x22;en&#x22;,
      )
      print(agent.agent_id)

asyncio.run(main())`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client, err := sonzai.NewClient(&#x22;sk-...&#x22;)
if err != nil { panic(err) }

agent, err := client.Agents.Generation.GenerateAndCreate(ctx, sonzai.GenerateAndCreateOptions{
  Name:        &#x22;Luna&#x22;,
  Description: &#x22;A cheerful and curious AI assistant who loves helping developers debug code. She's patient, witty, and always encouraging.&#x22;,
  Language:    &#x22;en&#x22;,
})

fmt.Println(agent.AgentID)       // auto-generated UUID
fmt.Println(agent.Personality)   // full Big5 profile derived from description`,
  },
]"
/>

### Option B: Define with Big5 Scores [#option-b-define-with-big5-scores]

For precise control, create an agent with explicit Big5 scores. The platform derives a full personality profile, speech patterns, and emotional tendencies from your scores.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
import { v5 as uuidv5 } from &#x22;uuid&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk-...&#x22; });

// Derive a stable UUID from your own entity ID
const MY_NAMESPACE = &#x22;your-uuid-namespace-here&#x22;;
const agentId = uuidv5(&#x22;support-agent-001&#x22;, MY_NAMESPACE);

const agent = await client.agents.create({
agentId,           // pass your own UUID — safe to repeat
name: &#x22;Luna&#x22;,
gender: &#x22;female&#x22;,
big5: {
  openness:          0.75,
  conscientiousness: 0.60,
  extraversion:      0.80,
  agreeableness:     0.70,
  neuroticism:       0.30,
},
language: &#x22;en&#x22;,
});

console.log(agent.agent_id); // same UUID every time`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import uuid

client = Sonzai(api_key=&#x22;sk-...&#x22;)

# Derive a stable UUID from your own entity ID
MY_NAMESPACE = uuid.UUID(&#x22;your-uuid-namespace-here&#x22;)
agent_id = str(uuid.uuid5(MY_NAMESPACE, &#x22;support-agent-001&#x22;))

agent = client.agents.create(
  agent_id=agent_id,   # pass your own UUID — safe to repeat
  name=&#x22;Luna&#x22;,
  gender=&#x22;female&#x22;,
  big5={
      &#x22;openness&#x22;:          0.75,
      &#x22;conscientiousness&#x22;: 0.60,
      &#x22;extraversion&#x22;:      0.80,
      &#x22;agreeableness&#x22;:     0.70,
      &#x22;neuroticism&#x22;:       0.30,
  },
  language=&#x22;en&#x22;,
)

print(agent.agent_id)  # same UUID every time`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
  &#x22;github.com/google/uuid&#x22;
)

client, err := sonzai.NewClient(&#x22;sk-...&#x22;)
if err != nil { panic(err) }

// Derive a stable UUID from your own entity ID
myNamespace := uuid.MustParse(&#x22;your-uuid-namespace-here&#x22;)
agentID := uuid.NewSHA1(myNamespace, []byte(&#x22;support-agent-001&#x22;)).String()

agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  AgentID: agentID,   // pass your own UUID — safe to repeat
  Name:    &#x22;Luna&#x22;,
  Gender:  &#x22;female&#x22;,
  Big5: &sonzai.Big5Scores{
      Openness:          0.75,
      Conscientiousness: 0.60,
      Extraversion:      0.80,
      Agreeableness:     0.70,
      Neuroticism:       0.30,
  },
  Language: &#x22;en&#x22;,
})
fmt.Println(agent.AgentID) // same UUID every time`,
  },
]"
/>

<Callout type="info" title="Idempotent by Design">
  Agent creation is always a **create-or-update**. Calling it twice with the same ID updates the existing agent — it never errors or creates a duplicate. This means your startup code, CI pipelines, and provisioning scripts can call `agents.create()` unconditionally.

  * **With agentId**: Server uses your UUID directly. Recommended — link agents to your own entity IDs (agents, assistants, employees) for a deterministic mapping you control.
  * **Without agentId**: Server derives a UUID from your project ID + agent name. The same name always maps to the same agent within your project.
</Callout>

## 5. Chat with Your Agent [#5-chat-with-your-agent]

Use streaming chat to get real-time AI responses. The platform automatically handles context, memory, and state updates.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.chatStream({
agent: &#x22;agent-id&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;I had a great day hiking!&#x22; }],
userId: &#x22;user-123&#x22;,
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.chat(
  &#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;I had a great day hiking!&#x22;}],
  user_id=&#x22;user-123&#x22;,
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;I had a great day hiking!&#x22;},
      },
      UserID: &#x22;user-123&#x22;,
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  return nil
})`,
  },
]"
/>

<Callout type="warn" title="Server-Side Only">
  The SDK is for **server-side use only**. Never expose API keys in client-side code. For web apps, proxy through your backend. See the [Integration Guide](/docs/en/guides/integration) for examples.
</Callout>

## 6. Track Over Time [#6-track-over-time]

The dashboard shows personality shifts, memory growth, mood patterns, and relationship dynamics. All systems update automatically as users interact.

<Callout type="info" title="Next Steps">
  * Read the [Architecture](/docs/en/architecture) to understand the full system
  * Follow the [Integration Guide](/docs/en/guides/integration) for a production setup
  * Browse the [API Reference](/docs/en/reference) for all available endpoints
  * Set up a [Knowledge Base](/docs/en/knowledge-base) so agents can query your domain data
</Callout>


---

# Guides

Source: https://sonz.ai/docs/en/guides

> How-tos for shipping with the Sonzai Relationship Layer — from your first agent to migrating an existing memory store.



Practical guides walk you from a first request to a production integration.
Pick a starting point.

## Quickstarts [#quickstarts]

<Cards>
  <Card href="/docs/en/guides/quickstart/employees" title="AI agents & Personal AI" description="Task-oriented agents that remember users, call tools, and use a knowledge base." />

  <Card href="/docs/en/guides/quickstart/companions" title="AI Companions" description="Long-running characters with personality, mood, and relationships." />

  <Card href="/docs/en/guides/quickstart/enterprise" title="Enterprise Workflows" description="Multi-tenant, audit-ready agents that span teams and data sources." />
</Cards>

## Integration [#integration]

<Cards>
  <Card href="/docs/en/guides/getting-started" title="Quickstart (10 min)" description="Create a project, get an API key, spin up an agent, start chatting." />

  <Card href="/docs/en/guides/integration" title="SDK Integration" description="End-to-end TypeScript, Python, and Go integration." />

  <Card href="/docs/en/guides/mcp-integration" title="MCP Integration" description="Connect Claude Desktop, Cursor, or any MCP client." />

  <Card href="/docs/en/guides/openclaw-integration" title="OpenClaw Plugin" description="Drop-in plugin for the OpenClaw context engine." />

  <Card href="/docs/en/guides/standalone-memory" title="Standalone Memory" description="Use the Relationship Layer as a memory backend for your existing agent runtime." />

  <Card href="/docs/en/guides/tool-integration" title="Tool Integration" description="Wire up custom tools the LLM can invoke during chat." />
</Cards>

## Migrating from another platform [#migrating-from-another-platform]

<Cards>
  <Card href="/docs/en/guides/migrating/overview" title="Migration overview" description="Choose a path: managed memory, vector DB, agent framework, or CSV." />

  <Card href="/docs/en/guides/migrating/openai-assistants" title="from OpenAI Assistants" description="Move threads, files, and instructions to the Relationship Layer." />

  <Card href="/docs/en/guides/migrating/zep" title="from Zep" description="Map sessions and facts." />

  <Card href="/docs/en/guides/migrating/mem0" title="from Mem0" description="Translate memory updates and retrieval calls." />

  <Card href="/docs/en/guides/migrating/letta" title="from Letta" description="Persist personas and core memory." />

  <Card href="/docs/en/guides/migrating/langchain" title="from LangChain" description="Replace ad-hoc memory adapters with hosted memory." />

  <Card href="/docs/en/guides/migrating/character-ai" title="from Character.ai" description="Bring characters, personality, and chat history." />

  <Card href="/docs/en/guides/migrating/custom-json" title="from a custom JSON store" description="Bulk-import facts, episodes, and summaries." />

  <Card href="/docs/en/guides/migrating/crm-csv" title="from a CRM CSV" description="Seed memory from contact records." />

  <Card href="/docs/en/guides/migrating/knowledge-base" title="from a knowledge base" description="Import documents and structured data into the graph." />
</Cards>

## Tutorials [#tutorials]

<Cards>
  <Card href="/docs/en/guides/tutorials/tutorial-memory" title="Persistent memory walkthrough" description="Seed, search, decay, and consolidate facts." />

  <Card href="/docs/en/guides/tutorials/tutorial-scheduled-reminders" title="Scheduled reminders" description="Schedule a wake-up and deliver it via webhook." />

  <Card href="/docs/en/guides/tutorials/tutorial-inventory" title="Inventory tracking" description="Track items the agent owns or has access to." />

  <Card href="/docs/en/guides/tutorials/tutorial-medication-reminders" title="Medication reminders" description="A clinical-style proactive workflow." />

  <Card href="/docs/en/guides/tutorials/tutorial-custom-states" title="Custom states" description="Track arbitrary structured state alongside memory." />
</Cards>


---

# Integration Guide

Source: https://sonz.ai/docs/en/guides/integration

> Connect your application to the Relationship Layer. End-to-end guide with examples for REST API and official SDKs.



## Overview [#overview]

Your backend manages business logic and user sessions. Call the Relationship Layer for agent intelligence — it owns memory, personality, mood, relationships, and context assembly.

Integrate via the REST API using official SDKs for Go, TypeScript, and Python.

## Official SDKs & Plugins [#official-sdks--plugins]

Official SDKs for Go, TypeScript, and Python, plus an OpenClaw plugin. Each SDK wraps the full REST API with typed methods, SSE streaming, automatic retries, and error handling.

<Cards>
  <Card href="https://github.com/sonz-ai/sonzai-go" title="Go" description="go get github.com/sonz-ai/sonzai-go" />

  <Card href="https://github.com/sonz-ai/sonzai-typescript" title="TypeScript / JavaScript" description="npm install @sonzai-labs/agents" />

  <Card href="https://github.com/sonz-ai/sonzai-python" title="Python" description="pip install sonzai" />

  <Card href="https://github.com/sonz-ai/openclaw-context" title="OpenClaw Plugin" description="npm install @sonzai-labs/openclaw-context" />
</Cards>

## REST API [#rest-api]

JSON-based endpoints. Chat responses stream via Server-Sent Events (SSE).

### Authentication [#authentication]

All REST requests use Bearer authentication with your project API key:

```bash
# All REST requests use Bearer auth with your project API key
curl -H "Authorization: Bearer sk_your_api_key" \
  https://api.sonz.ai/api/v1/agents/{agentId}/chat
```

### Core Interaction Flow (REST) [#core-interaction-flow-rest]

```bash
# Chat (SSE streaming response)
POST /api/v1/agents/{agentId}/chat
{ "messages": [{"role":"user","content":"Hello!"}], "user_id": "user-123" }

# Response: Server-Sent Events
# data: {"choices":[{"delta":{"content":"Hi"}}]}
# data: [DONE]
```

<Callout type="info" title="SSE Parsing">
  Each line starts with `data: `. Strip the prefix and JSON.parse the remainder. The stream ends with `data: [DONE]`.
</Callout>

### Available REST Endpoints [#available-rest-endpoints]

```text
POST /api/v1/agents                              Create agent
GET  /api/v1/agents                              List agents
GET  /api/v1/agents/{agentId}                    Get agent
POST /api/v1/agents/{agentId}/chat               Chat (SSE streaming)
GET  /api/v1/agents/{agentId}/notifications       Pending notifications
POST /api/v1/agents/{agentId}/notifications/{id}/consume  Consume notification
GET  /api/v1/agents/{agentId}/notifications/history       Notification history
```

## SDK Quickstart [#sdk-quickstart]

All three SDKs wrap the same REST API with typed methods, SSE streaming, automatic retries, and error handling. Pick whichever matches your stack — they're all first-class.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk_your_api_key&#x22; });

// Chat (non-streaming)
const response = await client.agents.chat({
agent:    &#x22;agent-id&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Hello!&#x22; }],
userId:   &#x22;user-123&#x22;,
});
console.log(response.content);

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

// Memory, personality, context engine data
const memory      = await client.agents.memory.list(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
const personality = await client.agents.personality.get(&#x22;agent-id&#x22;);
const mood        = await client.agents.getMood(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

client = Sonzai(api_key=&#x22;sk_your_api_key&#x22;)

# Chat (non-streaming)
response = client.agents.chat(
  agent_id=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Hello!&#x22;}],
  user_id=&#x22;user-123&#x22;,
)
print(response.content)

# Chat (streaming)
for event in client.agents.chat(
  agent_id=&#x22;agent-id&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Tell me a story&#x22;}],
  user_id=&#x22;user-123&#x22;,
  language=&#x22;en&#x22;,
  timezone=&#x22;America/New_York&#x22;,
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)

# Memory, personality, context engine data
memory      = client.agents.memory.list(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
personality = client.agents.personality.get(&#x22;agent-id&#x22;)
mood        = client.agents.get_mood(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)

client.close()`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

client := sonzai.NewClient(&#x22;sk_your_api_key&#x22;)

// Chat (non-streaming)
response, err := client.Agents.Chat(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Hello!&#x22;}},
      UserID:   &#x22;user-123&#x22;,
  },
})
fmt.Println(response.Content)

// Chat (streaming)
err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Tell me a story&#x22;}},
      UserID:   &#x22;user-123&#x22;,
      Language: &#x22;en&#x22;,
      Timezone: &#x22;America/New_York&#x22;,
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  return nil
})

// Memory, personality, context engine data
memory, _      := client.Agents.Memory.List(ctx, &#x22;agent-id&#x22;, &sonzai.MemoryListOptions{UserID: &#x22;user-123&#x22;})
personality, _ := client.Agents.Personality.Get(ctx, &#x22;agent-id&#x22;, &#x22;&#x22;)
mood, _        := client.Agents.GetMood(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)`,
  },
]"
/>

<Callout type="warn" title="Server-Side Only">
  All SDKs are for **server-side use**. Never expose API keys in browser code. See **Browser / Frontend Apps** below for the proxy pattern.
</Callout>

## Browser / Frontend Apps [#browser--frontend-apps]

<Callout type="warn" title="Server-Side Proxy Required">
  The Sonzai API does not accept browser (client-side) requests. API keys must never be exposed in frontend code. This is the same pattern used by OpenAI, Anthropic, and other AI API providers.
</Callout>

For web apps (React, Next.js, Vue, etc.), create a backend API route that proxies to Sonzai. Your frontend calls your server; your server calls Sonzai with the API key.

### Next.js API Route [#nextjs-api-route]

```ts
// app/api/chat/route.ts (runs on your server)
import { Sonzai } from "@sonzai-labs/agents";

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

export async function POST(req: Request) {
  const { agentId, messages, userId } = await req.json();
  const stream = client.agents.chatStream(agentId, { messages, userId });

  return new Response(
    new ReadableStream({
      async start(controller) {
        for await (const event of stream) {
          controller.enqueue(new TextEncoder().encode(
            `data: ${JSON.stringify(event)}\n\n`
          ));
        }
        controller.enqueue(new TextEncoder().encode("data: [DONE]\n\n"));
        controller.close();
      },
    }),
    { headers: { "Content-Type": "text/event-stream" } }
  );
}
```

### Frontend (Any Framework) [#frontend-any-framework]

```ts
// Calls YOUR server, not Sonzai directly
const res = await fetch("/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    agentId: "agent-uuid",
    messages: [{ role: "user", content: "Hello!" }],
    userId: "user-123",
  }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  // Parse SSE chunks from your proxy
  console.log(decoder.decode(value));
}
```

### Express / Fastify [#express--fastify]

```ts
// server.ts
import express from "express";
import { Sonzai } from "@sonzai-labs/agents";

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

app.post("/api/chat", async (req, res) => {
  const { agentId, messages, userId } = req.body;
  res.setHeader("Content-Type", "text/event-stream");

  for await (const event of client.agents.chatStream(agentId, { messages, userId })) {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
  }
  res.write("data: [DONE]\n\n");
  res.end();
});
```

## Connection Setup [#connection-setup]

Every SDK reads `SONZAI_API_KEY` from the environment by default. Override the base URL for self-hosted or local development.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({
apiKey:  &#x22;sk_your_api_key&#x22;,      // or SONZAI_API_KEY env var
baseUrl: &#x22;https://api.sonz.ai&#x22;,   // optional
timeout: 30_000,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

client = Sonzai(
  api_key=&#x22;sk_your_api_key&#x22;,        # or SONZAI_API_KEY env var
  base_url=&#x22;https://api.sonz.ai&#x22;,   # optional
  timeout=30.0,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;

// Empty string falls back to SONZAI_API_KEY env var
client := sonzai.NewClient(&#x22;sk_your_api_key&#x22;)

// Override the base URL for local dev / self-hosted
client = sonzai.NewClient(&#x22;sk_your_api_key&#x22;,
  sonzai.WithBaseURL(&#x22;http://localhost:8090&#x22;),
)`,
  },
]"
/>

## Agent Lifecycle [#agent-lifecycle]

When a user creates a new agent in your app, call `agents.create` with their personality configuration. Creation is idempotent — repeated calls with the same ID return the existing agent.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const agent = await client.agents.create({
name:   &#x22;Luna&#x22;,
gender: &#x22;female&#x22;,
big5: {
  openness:          0.75,
  conscientiousness: 0.60,
  extraversion:      0.80,
  agreeableness:     0.70,
  neuroticism:       0.30,
},
language: &#x22;en&#x22;,
});
// agent.agent_id is the platform-generated UUID — store it in your user record
console.log(agent.agent_id);

// Fetch later
const profile = await client.agents.get(agent.agent_id);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `agent = client.agents.create(
  name=&#x22;Luna&#x22;,
  gender=&#x22;female&#x22;,
  big5={
      &#x22;openness&#x22;:          0.75,
      &#x22;conscientiousness&#x22;: 0.60,
      &#x22;extraversion&#x22;:      0.80,
      &#x22;agreeableness&#x22;:     0.70,
      &#x22;neuroticism&#x22;:       0.30,
  },
  language=&#x22;en&#x22;,
)
# agent.agent_id is the platform-generated UUID — store it in your user record
print(agent.agent_id)

# Fetch later
profile = client.agents.get(agent.agent_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `agent, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
  Name:   &#x22;Luna&#x22;,
  Gender: &#x22;female&#x22;,
  Big5: &sonzai.Big5Scores{
      Openness:          0.75,
      Conscientiousness: 0.60,
      Extraversion:      0.80,
      Agreeableness:     0.70,
      Neuroticism:       0.30,
  },
  Language: &#x22;en&#x22;,
})
// agent.AgentID is the platform-generated UUID — store it in your user record
fmt.Println(agent.AgentID)

// Fetch later
profile, err := client.Agents.Get(ctx, agent.AgentID)`,
  },
]"
/>

## Streaming Chat [#streaming-chat]

The chat endpoint handles context assembly, AI streaming, and state updates in a single call.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `for await (const event of client.agents.chatStream({
agent:    &#x22;agent-id&#x22;,
userId:   &#x22;user-123&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;I had a great day hiking!&#x22; }],
language: &#x22;en&#x22;,
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for event in client.agents.chat(
  agent_id=&#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;I had a great day hiking!&#x22;}],
  language=&#x22;en&#x22;,
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: &#x22;agent-id&#x22;,
  ChatOptions: sonzai.ChatOptions{
      UserID:   &#x22;user-123&#x22;,
      Messages: []sonzai.ChatMessage{
          {Role: &#x22;user&#x22;, Content: &#x22;I had a great day hiking!&#x22;},
      },
      Language: &#x22;en&#x22;,
  },
}, func(event sonzai.ChatStreamEvent) error {
  fmt.Print(event.Content())
  return nil
})`,
  },
]"
/>

<Callout type="info" title="Mood Labels">
  Labels: Blissful (80-100), Content (60-79), Neutral (40-59), Melancholy (20-39), Troubled (0-19). Mood naturally drifts back toward the agent's personality baseline over time.
</Callout>

## Proactive Notifications [#proactive-notifications]

Agents can reach out to users between conversations. When triggered, the platform generates a contextual message using the agent's full state and stores it as "pending". Your app polls and marks notifications consumed after delivery.

### REST Polling [#rest-polling]

```bash
# Poll for pending proactive messages
GET /api/v1/agents/{agentId}/notifications?status=pending&user_id=user-123

# Response
{
  "notifications": [{
    "message_id": "msg-uuid",
    "user_id": "user-123",
    "check_type": "check_in",
    "intent": "Ask about yesterday's hiking trip",
    "generated_message": "Hey! How was the hike at Mount Rainier?",
    "status": "pending",
    "created_at": "2026-03-07T10:00:00Z"
  }]
}

# After delivering to user, mark consumed
POST /api/v1/agents/{agentId}/notifications/{messageId}/consume
```

<Callout type="info" title="Delivery Best Practice">
  Poll every 30-60 seconds. Always mark consumed after delivery to prevent re-delivery.
</Callout>

## Webhook Integration [#webhook-integration]

Register webhooks for event callbacks (wakeups, consolidation, breakthroughs):

```json
// Register webhook endpoints
PUT /api/projects/{projectId}/webhooks/{eventType}
{
    "webhook_url": "https://your-server.com/platform/webhooks/wakeup",
    "auth_header": "Bearer YOUR_SERVER_KEY"
}

// Event types:
// - "wakeup"        : Agent wants to proactively reach out
// - "consolidation" : Memory consolidation completed
// - "breakthrough"  : Significant personality evolution
```

### Wakeup Webhook Payload [#wakeup-webhook-payload]

Includes the generated message for direct delivery:

```json
{
  "event_type": "on_wakeup_ready",
  "agent_id": "agent-uuid",
  "user_id": "user-123",
  "generated_message": "Hey! How was the hike?",
  "wakeup_id": "wakeup-uuid",
  "check_type": "check_in"
}
```

<Callout type="info" title="Polling Alternative">
  Prefer polling? Use the notifications API instead of webhooks.
</Callout>

## Example: Backend Integration Flow [#example-backend-integration-flow]

Three-service architecture:

<Diagram>
  {`
    Client App            Your Backend                 Relationship Layer
       |                      |                              |
       |--- Authenticate --->|                              |
       |                      |                              |
       |--- Create agent ->|                              |
       |                      |--- REST: CreateAgent ------>|
       |                      |<-- Agent ID + Profile ------|
       |<-- Agent ready --|                              |
       |                      |                              |
       |--- Send message ---->|                              |
       |                      |--- REST: Chat (SSE) ------->|
       |<-- Streaming response <-- AI chunks + side effects -|
          `}
</Diagram>

Your backend translates application events into Relationship Layer API calls. You can swap the backend without changing agent behavior, or reuse agents across applications.

## Knowledge Base [#knowledge-base]

Push structured data to build a project-scoped knowledge graph. Agents search this graph during conversations. See the [Knowledge Base](/docs/en/knowledge-base) guide for full details.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Insert entities and relationships
const resp = await client.knowledge.insertFacts(projectId, {
source: &#x22;product_catalog&#x22;,
facts: [
  {
    entityType: &#x22;product&#x22;,
    label:      &#x22;Widget Pro&#x22;,
    properties: { price: 29.99, category: &#x22;tools&#x22; },
  },
],
relationships: [
  { fromLabel: &#x22;Widget Pro&#x22;, toLabel: &#x22;Tools&#x22;, edgeType: &#x22;belongs_to&#x22; },
],
});

// Search the graph
const results = await client.knowledge.search(projectId, {
query: &#x22;widget price&#x22;,
limit: 10,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Insert entities and relationships
resp = client.knowledge.insert_facts(
  project_id,
  source=&#x22;product_catalog&#x22;,
  facts=[
      {
          &#x22;entity_type&#x22;: &#x22;product&#x22;,
          &#x22;label&#x22;:       &#x22;Widget Pro&#x22;,
          &#x22;properties&#x22;:  {&#x22;price&#x22;: 29.99, &#x22;category&#x22;: &#x22;tools&#x22;},
      },
  ],
  relationships=[
      {&#x22;from_label&#x22;: &#x22;Widget Pro&#x22;, &#x22;to_label&#x22;: &#x22;Tools&#x22;, &#x22;edge_type&#x22;: &#x22;belongs_to&#x22;},
  ],
)

# Search the graph
results = client.knowledge.search(project_id, query=&#x22;widget price&#x22;, limit=10)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Insert entities and relationships
resp, err := client.Knowledge.InsertFacts(ctx, projectID, sonzai.InsertFactsOptions{
  Source: &#x22;product_catalog&#x22;,
  Facts: []sonzai.InsertFactEntry{
      {
          EntityType: &#x22;product&#x22;,
          Label:      &#x22;Widget Pro&#x22;,
          Properties: map[string]any{&#x22;price&#x22;: 29.99, &#x22;category&#x22;: &#x22;tools&#x22;},
      },
  },
  Relationships: []sonzai.InsertRelEntry{
      {FromLabel: &#x22;Widget Pro&#x22;, ToLabel: &#x22;Tools&#x22;, EdgeType: &#x22;belongs_to&#x22;},
  },
})

// Search the graph
results, err := client.Knowledge.Search(ctx, projectID, sonzai.KBSearchOptions{
  Query: &#x22;widget price&#x22;,
  Limit: 10,
})`,
  },
]"
/>

## User Priming [#user-priming]

Pre-load user metadata and content so agents already know a user before their first conversation. Metadata becomes instant facts; content blocks are extracted asynchronously via LLM.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const resp = await client.agents.priming.primeUser(agentId, userId, {
displayName: &#x22;Jane Smith&#x22;,
metadata: {
  company: &#x22;Acme Corp&#x22;,
  title:   &#x22;VP Engineering&#x22;,
  email:   &#x22;jane@acme.com&#x22;,
  custom:  { region: &#x22;APAC&#x22;, tier: &#x22;enterprise&#x22; },
},
content: [
  { type: &#x22;text&#x22;, body: &#x22;Jane led the migration from AWS to GCP...&#x22; },
],
source: &#x22;crm&#x22;,
});
console.log(\`Job: \${resp.jobId}, Facts created: \${resp.factsCreated}\`);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `resp = client.agents.priming.prime_user(
  agent_id,
  user_id,
  display_name=&#x22;Jane Smith&#x22;,
  metadata={
      &#x22;company&#x22;: &#x22;Acme Corp&#x22;,
      &#x22;title&#x22;:   &#x22;VP Engineering&#x22;,
      &#x22;email&#x22;:   &#x22;jane@acme.com&#x22;,
      &#x22;custom&#x22;:  {&#x22;region&#x22;: &#x22;APAC&#x22;, &#x22;tier&#x22;: &#x22;enterprise&#x22;},
  },
  content=[
      {&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: &#x22;Jane led the migration from AWS to GCP...&#x22;},
  ],
  source=&#x22;crm&#x22;,
)
print(f&#x22;Job: {resp.job_id}, Facts created: {resp.facts_created}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `resp, err := client.Agents.Priming.PrimeUser(ctx, agentID, userID, sonzai.PrimeUserOptions{
  DisplayName: &#x22;Jane Smith&#x22;,
  Metadata: &sonzai.PrimeUserMetadata{
      Company: &#x22;Acme Corp&#x22;,
      Title:   &#x22;VP Engineering&#x22;,
      Email:   &#x22;jane@acme.com&#x22;,
      Custom:  map[string]string{&#x22;region&#x22;: &#x22;APAC&#x22;, &#x22;tier&#x22;: &#x22;enterprise&#x22;},
  },
  Content: []sonzai.PrimeContentBlock{
      {Type: &#x22;text&#x22;, Body: &#x22;Jane led the migration from AWS to GCP...&#x22;},
  },
  Source: &#x22;crm&#x22;,
})
fmt.Printf(&#x22;Job: %s, Facts created: %d\\n&#x22;, resp.JobID, resp.FactsCreated)`,
  },
]"
/>

<Callout type="info" title="Async Processing">
  Metadata facts (name, company, title) are created synchronously. Content blocks (text, chat transcripts) are processed in the background via LLM extraction. Poll the job status to track progress.
</Callout>

## For AI Agents [#for-ai-agents]

Feeding these docs to an AI assistant or coding agent? Every page has a **Copy for LLM** button, and the bundles below are pre-formatted for ingestion. Append `.md` to any doc URL (e.g. `/docs/en/guides/integration.md`) for the raw markdown.

<LLMAccessCards />

## Best Practices [#best-practices]

* Use the streaming chat endpoint — it handles context assembly, AI streaming, and state updates in one call.
* Pass per-request application state via `compiledSystemPrompt`. The platform doesn't cache it across requests.
* Register webhooks for wakeup events so agents can initiate contact.
* Don't duplicate personality, memory, or relationship logic — let the engine own agent data.
* Poll notifications every 30–60 seconds. Consume after delivery to prevent re-delivery.
* All SDKs wrap the same REST API. Pick whichever matches your stack — they're all first-class.
* Browser apps must proxy through your backend — never expose API keys in client-side code. See the Browser / Frontend Apps section above.


---

# MCP Integration

Source: https://sonz.ai/docs/en/guides/mcp-integration

> Connect Claude Code, Cursor, Claude Desktop, ChatGPT, or any MCP-compatible client to the Sonzai Relationship Layer.



The Relationship 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 — no local binary, no SSE port to
expose, no Go toolchain.

The server implements the [Model Context Protocol](https://modelcontextprotocol.io/)
spec and exposes **34 tools**, **4 resources**, and **3 guided prompts**
(see [Tool catalogue](#tool-catalogue) below).

## What you need [#what-you-need]

1. A **project API key** — create one in your [project settings](https://platform.sonz.ai/dashboard/projects).
2. An **agent ID** — create an agent via the dashboard, the SDK, or by
   running the `create-companion` MCP prompt after first connect.

## Pick your client [#pick-your-client]

<CodeTabs
  tabs="[
  {
    id: &#x22;claude-code&#x22;,
    label: &#x22;Claude Code&#x22;,
    code: `# Single command — registers the hosted MCP server with Claude Code:
claude mcp add --transport http sonzai \\
https://api.sonz.ai/mcp/memory/AGENT_ID \\
--header &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22;

# Pick scope with --scope:
#   local   (default) — only this project, private to you
#   project           — writes .mcp.json (commit to share with team)
#   user              — across every project (~/.claude.json)

# Confirm the registration:
claude mcp list`,
  },
  {
    id: &#x22;cursor&#x22;,
    label: &#x22;Cursor&#x22;,
    code: `// ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
&#x22;mcpServers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;type&#x22;: &#x22;http&#x22;,
    &#x22;url&#x22;: &#x22;https://api.sonz.ai/mcp/memory/AGENT_ID&#x22;,
    &#x22;headers&#x22;: {
      &#x22;Authorization&#x22;: &#x22;Bearer YOUR_SONZAI_API_KEY&#x22;
    }
  }
}
}

// Or open Cursor and use the one-click install link
// (Settings → Tools & MCP → New MCP Server also accepts paste).`,
  },
  {
    id: &#x22;vscode&#x22;,
    label: &#x22;VS Code (Copilot)&#x22;,
    code: `// .vscode/mcp.json — note the top key is &#x22;servers&#x22;, not &#x22;mcpServers&#x22;:
{
&#x22;servers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;type&#x22;: &#x22;http&#x22;,
    &#x22;url&#x22;: &#x22;https://api.sonz.ai/mcp/memory/AGENT_ID&#x22;,
    &#x22;headers&#x22;: {
      &#x22;Authorization&#x22;: &#x22;Bearer YOUR_SONZAI_API_KEY&#x22;
    }
  }
}
}

// Or: Cmd/Ctrl+Shift+P → &#x22;MCP: Add Server&#x22; → HTTP, then paste the URL
// and add an Authorization header.`,
  },
  {
    id: &#x22;chatgpt&#x22;,
    label: &#x22;ChatGPT&#x22;,
    code: `# ChatGPT supports MCP only over remote HTTP — the hosted endpoint is
# the only path that works (no stdio, no local binary).
#
# Plans: Plus, Pro, Business, Enterprise, Edu (Developer Mode beta)
#
# Setup:
#   1. Settings → Connectors → Advanced → toggle Developer Mode ON
#   2. Add custom connector:
#        URL:        https://api.sonz.ai/mcp/memory/AGENT_ID
#        Auth type:  Custom header
#        Header:     Authorization: Bearer YOUR_SONZAI_API_KEY
#   3. Save and select the connector in any chat.`,
  },
  {
    id: &#x22;claude-desktop&#x22;,
    label: &#x22;Claude Desktop&#x22;,
    code: `# Claude Desktop's JSON config supports stdio servers only — for the
# remote hosted endpoint you must use the in-app Connectors UI:
#
#   Settings → Connectors → Add custom connector
#     URL:    https://api.sonz.ai/mcp/memory/AGENT_ID
#     Auth:   Authorization: Bearer YOUR_SONZAI_API_KEY
#
# Restart the app and the Sonzai tools appear in the connector picker.
#
# Need a stdio config instead (offline, air-gapped)? See &#x22;Local binary&#x22;.`,
  },
  {
    id: &#x22;local-binary&#x22;,
    label: &#x22;Local binary&#x22;,
    code: `# Optional fallback for stdio-only clients (older Claude Desktop, custom
# clients) or air-gapped environments. The binary is a thin translation
# layer — it speaks stdio JSON-RPC to the client and HTTPS REST to the
# Sonzai API.

# 1. Install (requires Go 1.25+):
go install github.com/sonz-ai/sonzai-mcp/cmd/mcp-server@latest

# 2. Add to your client. Example for Claude Desktop on macOS,
#    ~/Library/Application Support/Claude/claude_desktop_config.json:
{
&#x22;mcpServers&#x22;: {
  &#x22;sonzai&#x22;: {
    &#x22;command&#x22;: &#x22;sonzai-mcp&#x22;,
    &#x22;env&#x22;: { &#x22;SONZAI_API_KEY&#x22;: &#x22;sk-your-api-key&#x22; }
  }
}
}

# 3. Restart your client.`,
  },
]"
/>

<Callout type="info" title="Streamable HTTP, not SSE">
  The 2026 MCP spec marks **Streamable HTTP** as the canonical remote
  transport. SSE is on a deprecation path across major clients — prefer
  HTTP for any new integration. The legacy SSE transport is still served
  by the local binary for backwards compatibility.
</Callout>

## Authentication [#authentication]

| Endpoint                                     | Auth                           | Scope                        |
| -------------------------------------------- | ------------------------------ | ---------------------------- |
| `POST /mcp/memory/{agent_id}`                | `Authorization: Bearer sk-...` | Single agent                 |
| `POST /mcp/memory&#x60; &#x2A;(OAuth, beta)* | OAuth 2.0 authorization-code   | Project-scoped, agent picker |

The Bearer-key route is what every example above uses — it's pinned to a
specific agent and your project API key is the only secret. The
OAuth-mode route lets clients discover available agents via a picker UI;
it's currently in beta and exposed at the
`/.well-known/oauth-authorization-server` discovery endpoint.

<Callout type="warn" title="Treat the API key like a password">
  The Bearer token is a project API key — it grants full access to every
  agent in that project. Don't paste it into shared MCP configs that get
  committed to public repos. Prefer per-developer `local`-scope
  configurations when collaborating.
</Callout>

## Tool catalogue [#tool-catalogue]

The MCP server groups its 34 tools into six categories. Each tool maps
directly to a Platform API endpoint.

### Agent Management (5) [#agent-management-5]

* `list_agents` — list agents with search and pagination
* `get_agent` — detailed agent info (personality, capabilities, status)
* `create_agent` — create agent with personality, Big5, seed memories, goals
* `update_agent` — update agent profile (name, personality, bio, greeting)
* `delete_agent` — permanently delete an agent and all data

### Chat (1) [#chat-1]

* `chat` — send a message and get a response with full context (memory, mood, personality, relationships)

### Memory (5) [#memory-5]

* `get_memory` — get hierarchical memory tree
* `search_memories` — natural-language memory search
* `list_facts` — list atomic facts by type (profile, preference, emotion, …)
* `get_memory_timeline` — chronological memory timeline
* `reset_memory` — delete all memories (irreversible)

### Behavior (11) [#behavior-11]

* `get_personality` / `update_personality` — Big5 traits, BFAS dimensions
* `get_mood` / `get_mood_history` — 4D emotional state and history
* `list_goals` / `create_goal` / `update_goal` — agent goals
* `get_habits` — behavioral patterns with strength scores
* `get_relationships` — love scores, narratives, chemistry
* `get_interests` — detected interests with confidence
* `get_diary` — AI-generated diary entries

### Sessions & State (5) [#sessions--state-5]

* `start_session` / `end_session` — chat sessions for continuity and context
* `list_custom_states` / `upsert_custom_state` / `get_custom_state` — custom key-value entries

### Generation & Events (7) [#generation--events-7]

* `generate_character` — generate full character from text description
* `generate_and_create_agent` — generate + create in one step
* `trigger_event` — affect mood, memory, or behavior
* `list_notifications` / `schedule_wakeup` — proactive outreach
* `generate_bio` — biography for an existing agent
* `list_voices` — available TTS voices

## Resources [#resources]

Resources are read-only data exposed as MCP `sonzai://` URIs.

| URI                                | Description                                       |
| ---------------------------------- | ------------------------------------------------- |
| `sonzai://agents`                  | All agents in the project                         |
| `sonzai://agents/{id}/profile`     | Agent profile (personality, capabilities, status) |
| `sonzai://agents/{id}/memory`      | Memory tree snapshot                              |
| `sonzai://agents/{id}/personality` | Big5 traits, dimensions, preferences              |

## Guided prompts [#guided-prompts]

Pre-built workflows your assistant can invoke by name.

### `create-companion` [#create-companion]

Generate a fully-populated agent from a one-line concept.

**Args:** `concept` — e.g. `"a philosophical barista who reads tarot cards"`.

### `analyze-agent` [#analyze-agent]

Deep analysis of an agent's personality, mood, memories, and relationships.

**Args:** `agent_id` — UUID or name.

### `mind-layer-setup` [#mind-layer-setup]

Provision Sonzai as a persistent relationship layer for any AI assistant.

**Args:** `assistant_name`, `personality_description`.

## Architecture [#architecture]

```
Claude Code · Cursor · ChatGPT · VS Code · Claude Desktop
         │
         │ Streamable HTTP (JSON-RPC 2.0)
         ▼
https://api.sonz.ai/mcp/memory/{agent_id}
         │
         ├─ Context Engine (memory, personality, behavior)
         ├─ AI Service (LLM generation)
         └─ ScyllaDB · Redis · CockroachDB
```

For air-gapped or stdio-only clients the optional `sonzai-mcp` binary
sits on the user's machine and proxies stdio JSON-RPC ↔ HTTPS REST.

<Callout type="info" title="Next">
  * [API Reference](/docs/en/reference) — every REST endpoint the MCP tools wrap
  * [Personality System](/docs/en/personality) and [Memory & Context](/docs/en/memory) — what the tools control
</Callout>


---

# OpenClaw Integration

Source: https://sonz.ai/docs/en/guides/openclaw-integration

> Replace OpenClaw's default memory with the Sonzai Relationship Layer — persistent memory, personality evolution, mood tracking, and relationship modeling for every agent.



## What is OpenClaw? [#what-is-openclaw]

[OpenClaw](https://openclaw.ai) is an open-source framework for building conversational AI agents. It uses a modular plugin system with named **slots** — each slot controls a specific part of the agent pipeline.

The most important slot is `contextEngine`. This is the plugin responsible for deciding what context gets injected into the system prompt before every LLM call. It controls what your agent remembers, knows, and feels.

## How the Plugin System Works [#how-the-plugin-system-works]

OpenClaw's plugin system works like middleware. Each plugin implements lifecycle hooks that fire at specific points during a conversation turn:

* **`bootstrap(sessionId)`**: Called when a new chat session starts. The plugin initializes any connections or state it needs.
* **`assemble(messages, tokenBudget)`**: Called before every LLM call. The plugin returns a systemPromptAddition — extra context injected into the system prompt.
* **`afterTurn(sessionId)`**: Called after the LLM responds. The plugin processes the conversation (e.g., extract facts, update state).
* **`compact(sessionId)`**: Called when context needs to be consolidated (e.g., merging short-term memory into long-term).
* **`dispose()`**: Called when the session ends. Clean up connections and state.

By default, OpenClaw ships with a basic context engine that stores memories as local Markdown files. The Sonzai plugin replaces this with the Relationship Layer — giving your agent persistent memory, personality evolution, mood tracking, and relationship modeling with zero additional code.

### How plugin registration works [#how-plugin-registration-works]

When you install `@sonzai-labs/openclaw-context`, the package exports a `register()` function as its default export. On startup, OpenClaw loads all installed plugins and calls their register functions. Ours registers a context engine factory under the name `"sonzai"`:

```ts
// Inside @sonzai-labs/openclaw-context (you don't write this)
export default function register(api) {
  api.registerContextEngine("sonzai", () => {
    return new SonzaiContextEngine(client, config);
  });
}
```

Then in `openclaw.json`, you tell OpenClaw which registered engine to use for the `contextEngine` slot. The name `"sonzai"` must match what the plugin registered:

```json
{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"
    },
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid"
      }
    }
  }
}
```

So the flow is: **install the npm package** → OpenClaw discovers and calls `register()` → the plugin registers under `"sonzai"` → your config assigns it to the `contextEngine` slot.

<Callout type="info" title="Why Sonzai as a Context Layer?">
  Sonzai serves as a **pure context engine** for OpenClaw. Instead of the framework managing its own memory files, every conversation flows through the Relationship Layer — which handles fact extraction, semantic search, mood updates, and personality evolution automatically. Your OpenClaw agent gets rich, structured context without writing any memory logic.
</Callout>

## Quick Start [#quick-start]

### 1. Get Your API Key [#1-get-your-api-key]

Get an API key from your [Sonzai project settings](https://platform.sonz.ai/dashboard/projects). You'll paste it during the setup wizard, and it will be saved to your `openclaw.json`.

### 2. Install the Plugin [#2-install-the-plugin]

```bash
# Install via OpenClaw CLI
openclaw plugins install @sonzai-labs/openclaw-context

# Or install directly with your package manager
npm install @sonzai-labs/openclaw-context
# bun add @sonzai-labs/openclaw-context
```

### 3. Run the Setup Wizard [#3-run-the-setup-wizard]

The setup wizard walks you through connecting your OpenClaw project to the Relationship Layer:

```bash
npx @sonzai-labs/openclaw-context setup
```

The wizard will:

* Ask for your API key (or detect `SONZAI_API_KEY` from the environment)
* Ask if you have an existing agent ID, or create a new one with a name you choose
* Validate the API key against the Relationship Layer
* Save your API key and plugin config to `openclaw.json`

After setup, your `openclaw.json` will look like this:

```json
{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"
    },
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "a1b2c3d4-..."
      }
    }
  }
}
```

<Callout type="warn" title="API Key Storage">
  Your API key is stored in `openclaw.json` alongside your plugin config — no environment variables needed. Make sure `openclaw.json` is in your `.gitignore` to avoid committing secrets.
</Callout>

### 4. Start Chatting [#4-start-chatting]

Launch OpenClaw as usual. The plugin registers as the `sonzai` context engine and takes over context assembly automatically:

```bash
openclaw chat
```

That's it. Every conversation now flows through the Relationship Layer — your agent has persistent memory, personality, and mood from the first message.

## Configuration Reference [#configuration-reference]

All settings go in `openclaw.json` under `plugins.entries.sonzai`. Environment variables are supported as overrides.

| Option               | Env Override      | Default               | Description                       |
| -------------------- | ----------------- | --------------------- | --------------------------------- |
| `apiKey`             | `SONZAI_API_KEY`  | --                    | Project API key (required)        |
| `agentId`            | `SONZAI_AGENT_ID` | auto-provisioned      | Pre-provisioned agent UUID        |
| `baseUrl`            | `SONZAI_BASE_URL` | `https://api.sonz.ai` | Platform API base URL             |
| `agentName`          | --                | `openclaw-agent`      | Name for auto-provisioned agents  |
| `defaultUserId`      | --                | `owner`               | Fallback user ID for 1:1 sessions |
| `contextTokenBudget` | --                | `2000`                | Max tokens for injected context   |
| `extractionProvider` | --                | --                    | LLM provider for fact extraction  |
| `extractionModel`    | --                | --                    | LLM model for fact extraction     |

## Disabling Context Sources [#disabling-context-sources]

You can selectively disable specific context sources via the `disable` map. This is useful when you want the Relationship Layer for memory but don't need mood tracking, or when you want to reduce token usage:

```json
{
  "plugins": {
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid",
        "disable": {
          "mood": true,
          "personality": false,
          "relationships": true,
          "memory": false,
          "goals": true,
          "interests": true,
          "habits": true
        }
      }
    }
  }
}
```

With the config above, only **personality** and **memory** context will be injected — ideal for using the Relationship Layer as a pure memory and personality store.

## Injected Context [#injected-context]

On each turn, the plugin injects a structured `<sonzai-context>` block into the system prompt. Sections are ordered by priority and dropped lowest-first if the token budget is exceeded:

* **Personality** (priority 1, highest): Character definition, primary traits, speech patterns, Big5 profile
* **Relevant Memories** (priority 2): Semantically searched facts matching the latest user message
* **Current Mood** (priority 3): 4D emotional state (valence, arousal, tension, affiliation)
* **Relationship** (priority 4): Relationship narrative, love scores, chemistry with the current user
* **Goals** (priority 5): Active goals (growth, mastery, relationship, discovery)
* **Interests** (priority 6): Detected interests with confidence levels
* **Habits** (priority 7, lowest): Behavioral patterns with strength scores

<Callout type="info" title="Token Budget">
  The default budget is 2000 tokens (\~8000 characters). The plugin estimates token count at \~4 characters per token and drops the lowest-priority sections first when the budget is exceeded. Adjust with `contextTokenBudget` in your config.
</Callout>

## Session Key Resolution [#session-key-resolution]

The plugin automatically extracts user identity from OpenClaw's session key format. This enables per-user memory and relationships without any configuration:

| Session Format | Example                              | Resolved User ID |
| -------------- | ------------------------------------ | ---------------- |
| CLI (1:1)      | `agent:abc:mainKey`                  | `owner`          |
| Telegram DM    | `agent:abc:telegram:direct:123`      | `123`            |
| WhatsApp DM    | `agent:abc:whatsapp:direct:+1555...` | `+1555...`       |
| Discord Group  | `agent:abc:discord:group:guild789`   | `guild789`       |
| Cron / Webhook | `cron:daily-check`                   | `owner`          |

## Programmatic Setup (B2B) [#programmatic-setup-b2b]

For multi-tenant deployments where you provision agents programmatically,
the `@sonzai-labs/openclaw-context` plugin ships a `setup()` helper.
OpenClaw itself is a JavaScript context engine, so the plugin is
TypeScript-only — but the underlying provisioning is just two REST
calls (idempotent agent create + write a config file) that you can
drive from any language. Python and Go branches below show the
equivalent using the canonical Sonzai SDK.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { setup } from &#x22;@sonzai-labs/openclaw-context&#x22;;

const result = await setup({
apiKey: &#x22;sk-project-key&#x22;,
agentName: &#x22;customer-support-bot&#x22;,
configPath: &#x22;/path/to/openclaw.json&#x22;,
});

console.log(result.agentId);   // deterministic UUID (SHA1 of tenantID + agentName)
console.log(result.written);   // true — config file updated`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# OpenClaw's plugin is JS-only; this drives the same provisioning from
# Python by calling the Sonzai REST API directly. agentId is derived
# deterministically from SHA1(tenantID + agentName) so re-running this
# script for the same tenant is idempotent.
import hashlib, json, os, uuid
from sonzai import Sonzai

def derive_agent_id(tenant_id: str, agent_name: str) -> str:
  digest = hashlib.sha1(f&#x22;{tenant_id}:{agent_name}&#x22;.encode()).digest()
  return str(uuid.UUID(bytes=digest[:16]))

def provision(tenant_id: str, agent_name: str, config_path: str) -> str:
  sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
  agent_id = derive_agent_id(tenant_id, agent_name)
  sonzai.agents.create(name=agent_name, agent_id=agent_id)
  with open(config_path, &#x22;w&#x22;) as f:
      json.dump({&#x22;agentId&#x22;: agent_id, &#x22;agentName&#x22;: agent_name}, f, indent=2)
  return agent_id

agent_id = provision(&#x22;tenant-xyz&#x22;, &#x22;customer-support-bot&#x22;, &#x22;/path/to/openclaw.json&#x22;)
print(agent_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// OpenClaw's plugin is JS-only; this drives the same provisioning from
// Go by calling the Sonzai REST API directly. AgentID is derived
// deterministically from SHA1(tenantID + agentName) so re-running this
// program for the same tenant is idempotent.
package main

import (
  &#x22;context&#x22;
  &#x22;crypto/sha1&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  &#x22;github.com/google/uuid&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func deriveAgentID(tenantID, agentName string) string {
  h := sha1.Sum([]byte(tenantID + &#x22;:&#x22; + agentName))
  var u [16]byte
  copy(u[:], h[:16])
  return uuid.UUID(u).String()
}

func provision(ctx context.Context, client *sonzai.Client, tenantID, agentName, configPath string) (string, error) {
  agentID := deriveAgentID(tenantID, agentName)
  if _, err := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
      AgentID: agentID,
      Name:    agentName,
  }); err != nil {
      return &#x22;&#x22;, err
  }
  f, err := os.Create(configPath)
  if err != nil {
      return &#x22;&#x22;, err
  }
  defer f.Close()
  if err := json.NewEncoder(f).Encode(map[string]string{
      &#x22;agentId&#x22;:   agentID,
      &#x22;agentName&#x22;: agentName,
  }); err != nil {
      return &#x22;&#x22;, err
  }
  return agentID, nil
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  id, err := provision(context.Background(), client, &#x22;tenant-xyz&#x22;, &#x22;customer-support-bot&#x22;, &#x22;/path/to/openclaw.json&#x22;)
  if err != nil {
      panic(err)
  }
  fmt.Println(id)
}`,
  },
  {
    id: &#x22;ts2&#x22;,
    label: &#x22;Direct Engine (TS)&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
import { SonzaiContextEngine, resolveConfig } from &#x22;@sonzai-labs/openclaw-context&#x22;;

const client = new Sonzai({ apiKey: &#x22;sk-...&#x22; });
const config = resolveConfig({ apiKey: &#x22;sk-...&#x22;, agentId: &#x22;agent-123&#x22; });
const engine = new SonzaiContextEngine(client, config);

// Use the engine directly outside of OpenClaw
await engine.bootstrap({ sessionId: &#x22;my-session&#x22; });

const { systemPromptAddition } = await engine.assemble({
sessionId: &#x22;my-session&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Hello!&#x22; }],
tokenBudget: 4000,
});

// systemPromptAddition contains the <sonzai-context> block
console.log(systemPromptAddition);`,
  },
]"
/>

<Callout type="warn" title="Idempotent Provisioning">
  Agent IDs are generated deterministically from `SHA1(tenantID + agentName)`. Calling setup multiple times with the same name returns the same agent — safe for restarts and redeployments.
</Callout>

## Architecture [#architecture]

The Sonzai context engine plugs into OpenClaw's lifecycle hooks. Here's the flow for a single conversation turn:

<Diagram>
  {`OpenClaw Runtime                SonzaiContextEngine              Sonzai Relationship Layer
        |                                    |                                |
        |-- bootstrap(sessionId) ----------->|                                |
        |                                    |-- resolve agent + session ---->|
        |                                    |<-- session state cached -------|
        |                                    |                                |
        |-- assemble(messages, budget) ----->|                                |
        |                                    |-- fetch context (memory,       |
        |                                    |   personality, mood,           |
        |                                    |   relationships) ------------>|
        |                                    |<-- ranked context blocks ------|
        |                                    |                                |
        |<-- systemPromptAddition -----------|   (priority-ordered,           |
        |                                    |    budget-trimmed)             |
        |                                    |                                |
        |  [LLM call with enriched prompt]   |                                |
        |                                    |                                |
        |-- afterTurn(sessionId) ----------->|                                |
        |                                    |-- send conversation ---------> |
        |                                    |   Relationship Layer extracts facts,   |
        |                                    |   updates mood, evolves        |
        |                                    |   personality automatically    |
        |                                    |                                |
        |-- compact(sessionId) ------------->|                                |
        |                                    |-- merge short-term → long-term>|
        |                                    |<-- compacted ------------------|`}
</Diagram>

The context engine handles all communication with the Relationship Layer. During `assemble`, it fetches context sources (memory, personality, mood, relationships, goals, interests, habits), ranks them by priority, and trims to the token budget. During `afterTurn`, it sends the conversation back for fact extraction and state updates. The engine never runs LLM calls locally — all intelligence lives on the Sonzai side.

<Callout type="info" title="Graceful Degradation">
  All API calls are wrapped in error handlers. If the Relationship Layer is unreachable, the engine returns empty context and never blocks OpenClaw — your agent continues working without enriched context.
</Callout>

## Exports [#exports]

The package exports the following for advanced usage:

| Export                        | Description                                                    |
| ----------------------------- | -------------------------------------------------------------- |
| `default`                     | Plugin registration (auto-loaded by OpenClaw)                  |
| `SonzaiContextEngine`         | Core engine class — usable outside OpenClaw                    |
| `setup()`                     | Programmatic setup for B2B deployments                         |
| `resolveConfig()`             | Merge openclaw\.json + env vars + config into resolved options |
| `parseSessionKey()`           | Extract user identity from OpenClaw session keys               |
| `buildSystemPromptAddition()` | Format context into the injection block                        |
| `estimateTokens()`            | Estimate token count for a string (\~4 chars/token)            |
| `SessionCache`                | TTL-based cache for session state                              |

## Next Steps [#next-steps]

* Learn about the [Memory & Context](/docs/en/memory) system that powers the plugin
* Explore [Personality System](/docs/en/personality) and [Emotions & Mood](/docs/en/emotions) to understand the context sources
* Read the [API Reference](/docs/en/reference) for the full REST API behind the plugin
* See the [Integration Guide](/docs/en/guides/integration) for SDK-based integration without OpenClaw


---

# Tool Integration for BYO-LLM

Source: https://sonz.ai/docs/en/guides/tool-integration

> When using standalone memory mode, your LLM handles chat generation but may need to search knowledge and memory on demand. Sonzai exposes tool schemas compatible with OpenAI function calling, so you can wire them into any agent framework.



## Two Approaches to Enrichment [#two-approaches-to-enrichment]

There are two complementary ways your agent can access Sonzai knowledge and memory:

<Cards>
  <Card title="Automatic (Recommended)" description="Call GET /context with a query param. The endpoint automatically searches the knowledge base and injects recalled memories. The deferred learning loop primes the next context call with KB results that the agent missed. No tool calling needed." />

  <Card title="Explicit Tool Calling" description="Register Sonzai tools with your LLM so it can search on demand mid-conversation. This is for agent frameworks (LangChain, Vercel AI SDK, CrewAI) where the LLM decides when to search. You fetch tool schemas from Sonzai and wire them into your framework." />
</Cards>

<Callout type="info" title="When to use which?">
  Start with automatic enrichment — it covers most cases with zero configuration. Add explicit tool calling when your agent needs to search mid-conversation (e.g., the user asks a question not covered by the initial context fetch) or when your framework expects tool definitions.
</Callout>

## Discovering Available Tools [#discovering-available-tools]

Fetch the tool catalog for an agent. This returns JSON schemas in OpenAI function-calling format that you can pass directly to your LLM's tool configuration.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const tools = await client.agents.getTools(&#x22;agent-id&#x22;);

// tools.tools = [
//   {
//     name: &#x22;knowledge_search&#x22;,
//     description: &#x22;Search the agent's knowledge base...&#x22;,
//     endpoint: &#x22;POST /api/v1/agents/{agentId}/tools/kb-search&#x22;,
//     parameters: {
//       type: &#x22;object&#x22;,
//       required: [&#x22;query&#x22;],
//       properties: {
//         query: { type: &#x22;string&#x22;, description: &#x22;Search query&#x22; },
//         limit: { type: &#x22;integer&#x22;, description: &#x22;Max results (default 10)&#x22; }
//       }
//     }
//   },
//   {
//     name: &#x22;memory_search&#x22;,
//     description: &#x22;Search the agent's memory for previously learned facts...&#x22;,
//     endpoint: &#x22;GET /api/v1/agents/{agentId}/memory/search?q={query}&userId={userId}&#x22;,
//     parameters: {
//       type: &#x22;object&#x22;,
//       required: [&#x22;query&#x22;],
//       properties: {
//         query: { type: &#x22;string&#x22;, description: &#x22;Search query&#x22; },
//         user_id: { type: &#x22;string&#x22;, description: &#x22;User ID to scope search&#x22; },
//         limit: { type: &#x22;integer&#x22;, description: &#x22;Max results (default 20)&#x22; }
//       }
//     }
//   }
// ]`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `tools = client.agents.get_tools(&#x22;agent-id&#x22;)

for tool in tools.tools:
  print(tool.name, tool.description)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `tools, err := client.Agents.GetTools(ctx, &#x22;agent-id&#x22;)

for _, t := range tools.Tools {
  fmt.Println(t.Name, t.Description)
}`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl https://api.sonz.ai/api/v1/agents/{agentId}/tools/schemas \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22;`,
  },
]"
/>

## Knowledge Search Tool [#knowledge-search-tool]

Search the agent's knowledge base for relevant documents and facts. Uses hybrid search (BM25 + semantic) when embeddings are available, falling back to BM25 full-text search.

### Endpoint [#endpoint]

```bash
POST /api/v1/agents/{agentId}/tools/kb-search
GET  /api/v1/agents/{agentId}/tools/kb-search?q={query}&limit={limit}
```

### Request [#request]

```json
{
  "query": "refund policy",
  "limit": 5
}
```

### Response [#response]

```json
{
  "query": "refund policy",
  "results": [
    {
      "content": "Customers can request a full refund within 30 days of purchase...",
      "label": "Refund Policy",
      "type": "policy",
      "source": "policies.pdf",
      "score": 0.92
    },
    {
      "content": "For digital products, refunds are processed within 5 business days...",
      "label": "Digital Refund Process",
      "type": "process",
      "source": "policies.pdf",
      "score": 0.78
    }
  ]
}
```

### SDK Usage [#sdk-usage]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const results = await client.agents.knowledgeSearch(&#x22;agent-id&#x22;, {
query: &#x22;refund policy&#x22;,
limit: 5,
});

for (const result of results.results) {
console.log(\`[\${result.score.toFixed(2)}] \${result.label}: \${result.content}\`);
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `results = client.agents.knowledge_search(
  &#x22;agent-id&#x22;,
  query=&#x22;refund policy&#x22;,
  limit=5,
)

for r in results.results:
  print(f&#x22;[{r.score:.2f}] {r.label}: {r.content}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `results, err := client.Agents.KnowledgeSearch(ctx, &#x22;agent-id&#x22;, sonzai.KBSearchOptions{
  Query: &#x22;refund policy&#x22;,
  Limit: 5,
})

for _, r := range results.Results {
  fmt.Printf(&#x22;[%.2f] %s: %s\\n&#x22;, r.Score, r.Label, r.Content)
}`,
  },
]"
/>

## Memory Search Tool [#memory-search-tool]

Search the agent's memory for previously extracted facts about a user. This is a **synchronous** BM25 full-text search that returns immediately — no deferred processing.

### Endpoint [#endpoint-1]

```bash
GET /api/v1/agents/{agentId}/memory/search?q={query}&userId={userId}&limit={limit}
```

### Response [#response-1]

```json
{
  "results": [
    {
      "fact_id": "f_abc123",
      "content": "User enjoys hiking on weekends",
      "fact_type": "preference",
      "score": 4.82
    },
    {
      "fact_id": "f_def456",
      "content": "User adopted a dog named Luna in March",
      "fact_type": "event",
      "score": 3.15
    }
  ]
}
```

### SDK Usage [#sdk-usage-1]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const results = await client.agents.memory.search(&#x22;agent-id&#x22;, {
query: &#x22;hiking&#x22;,
userId: &#x22;user-123&#x22;,
limit: 10,
});

for (const fact of results.results) {
console.log(\`[\${fact.fact_type}] \${fact.content}\`);
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `results = client.agents.memory.search(
  &#x22;agent-id&#x22;,
  query=&#x22;hiking&#x22;,
  user_id=&#x22;user-123&#x22;,
  limit=10,
)

for fact in results.results:
  print(f&#x22;[{fact.fact_type}] {fact.content}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `results, err := client.Agents.Memory.Search(ctx, &#x22;agent-id&#x22;, sonzai.MemorySearchOptions{
  Query:  &#x22;hiking&#x22;,
  UserID: &#x22;user-123&#x22;,
  Limit:  10,
})

for _, f := range results.Results {
  fmt.Printf(&#x22;[%s] %s\\n&#x22;, f.FactType, f.Content)
}`,
  },
]"
/>

<Callout type="info" title="Memory search is always synchronous">
  Unlike KB enrichment (which has a deferred path), memory search returns immediately from BM25 indexes. There is no async component. The `/context` endpoint already includes the most relevant memories automatically — this tool is for cases where the LLM needs to search for additional facts mid-conversation.
</Callout>

## Wiring Tools into Agent Frameworks [#wiring-tools-into-agent-frameworks]

The tool schemas from `GET /tools/schemas` follow the OpenAI function-calling format. Here is how to wire them into popular agent frameworks.

### Vercel AI SDK [#vercel-ai-sdk]

```ts
import { generateText, tool } from "ai";
import { google } from "@ai-sdk/google";
import { Sonzai } from "@sonzai-labs/agents";
import { z } from "zod";

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const agentId = "agent-id";
const userId = "user-123";

// Define Sonzai tools for the Vercel AI SDK
const sonzaiTools = {
  knowledge_search: tool({
    description: "Search the agent's knowledge base for relevant documents",
    parameters: z.object({
      query: z.string().describe("Search query"),
      limit: z.number().optional().describe("Max results"),
    }),
    execute: async ({ query, limit }) => {
      const results = await sonzai.agents.knowledgeSearch(agentId, {
        query,
        limit: limit ?? 5,
      });
      return results.results.map((r) => ({
        content: r.content,
        label: r.label,
        score: r.score,
      }));
    },
  }),
  memory_search: tool({
    description: "Search agent memory for facts about the user",
    parameters: z.object({
      query: z.string().describe("Search query"),
    }),
    execute: async ({ query }) => {
      const results = await sonzai.agents.memory.search(agentId, {
        query,
        userId,
      });
      return results.results.map((f) => ({
        content: f.content,
        type: f.fact_type,
      }));
    },
  }),
};

// Get enriched context first
const ctx = await sonzai.agents.getContext(agentId, {
  userId,
  sessionId: "session-abc",
  query: userMessage,
});

const { text } = await generateText({
  model: google("gemini-3.1-flash-lite-preview"),
  system: buildSystemPrompt(ctx),
  prompt: userMessage,
  tools: sonzaiTools,
  maxSteps: 3, // allow up to 3 tool calls per turn
});
```

### Google Gemini Function Calling [#google-gemini-function-calling]

```ts
import { GoogleGenAI, Type } from "@google/genai";
import { Sonzai } from "@sonzai-labs/agents";

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

const agentId = "agent-id";

// Define tools in Gemini format
const tools = [{
  functionDeclarations: [
    {
      name: "knowledge_search",
      description: "Search the agent's knowledge base for relevant documents",
      parameters: {
        type: Type.OBJECT,
        properties: {
          query: { type: Type.STRING, description: "Search query" },
          limit: { type: Type.INTEGER, description: "Max results" },
        },
        required: ["query"],
      },
    },
    {
      name: "memory_search",
      description: "Search agent memory for facts about the user",
      parameters: {
        type: Type.OBJECT,
        properties: {
          query: { type: Type.STRING, description: "Search query" },
        },
        required: ["query"],
      },
    },
  ],
}];

// Chat with tool calling
const response = await gemini.models.generateContent({
  model: "gemini-3.1-flash-lite-preview",
  contents: [{ role: "user", parts: [{ text: systemPrompt + "\n\n" + userMessage }] }],
  config: { tools },
});

// Handle tool calls
for (const part of response.candidates?.[0]?.content?.parts ?? []) {
  if (part.functionCall) {
    const { name, args } = part.functionCall;

    let result;
    if (name === "knowledge_search") {
      result = await sonzai.agents.knowledgeSearch(agentId, {
        query: args.query as string,
        limit: (args.limit as number) ?? 5,
      });
    } else if (name === "memory_search") {
      result = await sonzai.agents.memory.search(agentId, {
        query: args.query as string,
        userId: "user-123",
      });
    }

    // Send tool result back to Gemini for the final response
    // (see Gemini function calling docs for the full loop)
  }
}
```

### LangChain (Python) [#langchain-python]

```python
from langchain_core.tools import tool
from langchain_google_genai import ChatGoogleGenerativeAI
from langgraph.prebuilt import create_react_agent
from sonzai import Sonzai

sonzai_client = Sonzai(api_key="sk_your_api_key")
agent_id = "agent-id"
user_id = "user-123"

@tool
def knowledge_search(query: str, limit: int = 5) -> list[dict]:
    """Search the agent's knowledge base for relevant documents and facts.
    Use when the user asks about topics that may be in uploaded documents."""
    results = sonzai_client.agents.knowledge_search(agent_id, query=query, limit=limit)
    return [{"content": r.content, "label": r.label, "score": r.score} for r in results.results]

@tool
def memory_search(query: str) -> list[dict]:
    """Search agent memory for previously learned facts about the user.
    Use when the conversation references past interactions or personal details."""
    results = sonzai_client.agents.memory.search(agent_id, query=query, user_id=user_id)
    return [{"content": f.content, "type": f.fact_type} for f in results.results]

# Get enriched context
ctx = sonzai_client.agents.get_context(
    agent_id, user_id=user_id, session_id="session-abc", query=user_message
)

llm = ChatGoogleGenerativeAI(model="gemini-3.1-flash-lite-preview")
agent = create_react_agent(llm, [knowledge_search, memory_search])

result = agent.invoke({
    "messages": [
        {"role": "system", "content": build_system_prompt(ctx)},
        {"role": "user", "content": user_message},
    ]
})
```

### OpenAI-Compatible (Generic) [#openai-compatible-generic]

Any framework that accepts OpenAI function-calling format can use the schemas directly:

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

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

// Fetch schemas and convert to OpenAI format
const { tools: sonzaiSchemas } = await sonzai.agents.getTools("agent-id");

const openaiTools = sonzaiSchemas.map((t) => ({
  type: "function" as const,
  function: {
    name: t.name,
    description: t.description,
    parameters: t.parameters,
  },
}));

// Pass to any OpenAI-compatible provider
const response = await openai.chat.completions.create({
  model: "your-model",
  messages: [...],
  tools: openaiTools,
});

// Handle tool calls in the response
for (const call of response.choices[0].message.tool_calls ?? []) {
  const args = JSON.parse(call.function.arguments);

  if (call.function.name === "knowledge_search") {
    const result = await sonzai.agents.knowledgeSearch("agent-id", {
      query: args.query,
      limit: args.limit,
    });
    // Feed result back to the LLM as a tool response
  }

  if (call.function.name === "memory_search") {
    const result = await sonzai.agents.memory.search("agent-id", {
      query: args.query,
      userId: "user-123",
    });
    // Feed result back to the LLM as a tool response
  }
}
```

## Understanding Deferred Enrichment [#understanding-deferred-enrichment]

The most powerful aspect of standalone mode is the **self-improving learning loop**. Even without explicit tool calls, the agent gets smarter each turn because `/process` detects knowledge gaps and primes the next `/context` call.

### How It Works [#how-it-works]

<Diagram>
  {`
    ┌──────────────────────────────────────────────────────────────────┐
    │  Turn N                                                          │
    │                                                                  │
    │  1. GET /context?query="hiking boots"                            │
    │     → Returns enriched context + any KB matches for "hiking"     │
    │     → Also returns deferred results from Turn N-1 (if any)      │
    │                                                                  │
    │  2. Chat with your LLM (using enriched context)                  │
    │                                                                  │
    │  3. POST /process (send transcript)                              │
    │     → Extracts facts: "user needs waterproof hiking boots"       │
    │     → Extracts entities: "hiking boots", "waterproof"            │
    │     → Searches KB with extracted topics (async, after response)  │
    │     → Finds: "Hiking Gear Guide", "Waterproof Materials FAQ"    │
    │     → Stores as deferred signals (Redis, 1-hour TTL)            │
    │                                                                  │
    └──────────────────────────────────────────────────────────────────┘
                                ↓
    ┌──────────────────────────────────────────────────────────────────┐
    │  Turn N+1                                                        │
    │                                                                  │
    │  1. GET /context?query="which brand do you recommend?"           │
    │     → Direct search: matches for "brand recommend"              │
    │     → Deferred results: "Hiking Gear Guide" + "Waterproof FAQ"  │
    │     → Both merged into response (deduplicated)                  │
    │     → Deferred signals consumed (one-shot, not repeated)        │
    │                                                                  │
    │  2. Chat with your LLM                                          │
    │     → Now has hiking gear knowledge it didn't have before!      │
    │                                                                  │
    └──────────────────────────────────────────────────────────────────┘
          `}
</Diagram>

### Key Properties [#key-properties]

* **One-shot signals**: Deferred KB results are consumed when `/context` reads them. They appear exactly once, preventing stale or repeated information.
* **TTL-based expiry**: Deferred signals expire after 1 hour. If the user doesn't continue the conversation, stale signals are automatically cleaned up.
* **Deduplication**: If the direct `/context` query matches the same KB document as a deferred signal, the duplicate is removed. You never get the same result twice.
* **Capped searches**: `/process` runs at most 5 KB queries per call and stores at most 10 deferred results, preventing resource explosion on topic-heavy conversations.

### Memory Search Is Always Synchronous [#memory-search-is-always-synchronous]

Unlike KB enrichment, memory search has no deferred/async path. When `/context` is called, it recalls the most relevant memories immediately using the hierarchical memory tree and BM25 indexes. When you call `GET /memory/search` explicitly, results return immediately.

The **deferred** behavior only applies to knowledge base content, where `/process` proactively discovers KB documents the agent should have known about. Memory facts are always available synchronously because they are indexed at write time (during `/process`).

## Recommended Integration Pattern [#recommended-integration-pattern]

For most applications, combine automatic enrichment with explicit tool calling for the best results:

```ts
import { generateText, tool } from "ai";
import { google } from "@ai-sdk/google";
import { Sonzai } from "@sonzai-labs/agents";
import { z } from "zod";

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

async function chat(agentId: string, userId: string, sessionId: string, message: string) {
  // Step 1: Automatic enrichment — context includes KB + memories
  const ctx = await sonzai.agents.getContext(agentId, {
    userId,
    sessionId,
    query: message,
  });

  // Step 2: Chat with tools for on-demand search
  const { text, steps } = await generateText({
    model: google("gemini-3.1-flash-lite-preview"),
    system: buildSystemPrompt(ctx),
    prompt: message,
    tools: {
      knowledge_search: tool({
        description: "Search knowledge base for additional documents",
        parameters: z.object({ query: z.string() }),
        execute: async ({ query }) => {
          const r = await sonzai.agents.knowledgeSearch(agentId, { query, limit: 5 });
          return r.results.map((d) => ({ content: d.content, label: d.label }));
        },
      }),
      memory_search: tool({
        description: "Search memory for additional facts about the user",
        parameters: z.object({ query: z.string() }),
        execute: async ({ query }) => {
          const r = await sonzai.agents.memory.search(agentId, { query, userId });
          return r.results.map((f) => ({ content: f.content, type: f.fact_type }));
        },
      }),
    },
    maxSteps: 3,
  });

  // Step 3: Process — extracts memories + primes next context with KB gaps
  await sonzai.agents.process(agentId, {
    userId,
    sessionId,
    messages: [
      { role: "user", content: message },
      { role: "assistant", content: text },
    ],
    provider: "gemini",
  });

  return text;
}
```

<Diagram>
  {`
              GET /context
                  │
     ┌────────────┴────────────┐
     │                         │
     ▼                         ▼
    Recalled              KB Search
    Memories              Results
     │                    │
     └────────┬───────────┘
              │
              ▼
       System Prompt ──────► Your LLM
              │                  │
              │          ┌───────┴──────────────┐
              │          │ Tool call?            │
              │          │ knowledge_search()    │
              │          │ memory_search()       │
              │          └───────┬──────────────┘
              │                  │
              │                  ▼
              │             Response
              │                  │
              ▼                  ▼
          POST /process
              │
     ┌────────┴────────┐
     │                 │
     ▼                 ▼
    Extract         Detect KB
    Facts           Gaps (deferred)
     │                 │
     ▼                 ▼
    Store in        Store in Redis
    Memory Tree     (for next /context)
          `}
</Diagram>

## Frequently Asked Questions [#frequently-asked-questions]

### Do I need tool calling if I already use /context? [#do-i-need-tool-calling-if-i-already-use-context]

Not necessarily. `/context` automatically includes KB results and recalled memories. Tool calling is useful when the LLM needs to search for something specific mid-conversation that wasn't covered by the initial context fetch, or when your framework expects tool definitions.

### Is memory search async like KB enrichment? [#is-memory-search-async-like-kb-enrichment]

No. Memory search is always synchronous. When you call `GET /memory/search`, results return immediately from BM25 indexes. The deferred/async flow only applies to knowledge base enrichment via the `/process` learning loop.

### What happens if /process finds KB content but the user never calls /context again? [#what-happens-if-process-finds-kb-content-but-the-user-never-calls-context-again]

The deferred signals expire after 1 hour (TTL-based cleanup). No stale data persists. If the user resumes the conversation later, they get fresh results from the next `/context` call.

### Can I use my own tools alongside Sonzai tools? [#can-i-use-my-own-tools-alongside-sonzai-tools]

Absolutely. The Sonzai tool schemas are standard OpenAI function definitions. Mix them with your own tools in whatever framework you use. The LLM decides which tool to call based on the conversation.

### How do custom tools defined in the dashboard relate to these? [#how-do-custom-tools-defined-in-the-dashboard-relate-to-these]

Custom tools (created via `POST /agents/{agentId}/tools` or the dashboard) are for agent-side tool calling in Sonzai's managed chat mode. The tool schemas described here (`/tools/schemas`) are for BYO-LLM mode where *your* LLM calls Sonzai endpoints.


---

# Learn

Source: https://sonz.ai/docs/en/learn

> Conceptual deep-dives into how the Relationship Layer thinks — memory shape, personality dynamics, and the self-improvement loop.



If the [Docs](/docs/en/home) explain *what* each feature does, **Learn**
explains *why it works the way it does* — the model, the loop, and the
trade-offs you can tune.

## Deep dives [#deep-dives]

<Cards>
  <Card href="/docs/en/architecture" title="Architecture" description="How the platform, orchestrator, and your backend fit together — and where each piece of state lives." />

  <Card href="/docs/en/self-improvement" title="How agents improve over time" description="The complete picture of automatic learning: memory decay, consolidation, dedup, retrieval policy, personality drift, breakthroughs, and shadow rollouts." />

  <Card href="/docs/en/agent-insights" title="Agent insights" description="What the system reveals about an agent's inner state — and how to use it to debug, audit, or fine-tune behavior." />

  <Card href="/docs/en/proactive-overview" title="Proactive behavior" description="When agents reach out on their own — wakeups, schedules, and the policies that govern them." />

  <Card href="/docs/en/personality" title="Big Five personality" description="OCEAN dimensions, behavioral facets, and how personality shifts in response to interactions." />

  <Card href="/docs/en/emotions" title="Mood model" description="Four mood dimensions, decay rates, and the events that move them." />
</Cards>

## Build something with it [#build-something-with-it]

Once the model is clear, the [Tutorials in Guides](/docs/en/guides#tutorials)
walk you end-to-end through a concrete project.


---

# BYOK — Bring Your Own Key

Source: https://sonz.ai/docs/en/models/byok

> Use Sonzai's hosted infrastructure but bill provider tokens to your own account. Per-project, per-provider, encrypted at rest.



**BYOK** lets you keep using Sonzai's chat / sessions / extraction stack
while routing the underlying provider call through *your* API key. Token
charges land on your provider invoice; everything else (memory,
personality, post-processing models, billing for Sonzai's platform)
behaves the same.

This is different from [Custom LLM (BYOM)](/docs/en/models/custom-llm).
BYOK uses Sonzai's first-party provider integrations with your billing
key; BYOM swaps the entire chat-completion call to an endpoint *you*
host.

## Scope [#scope]

BYOK keys are stored per &#x2A;*(project, provider)**. There is one key per
provider per project, no per-agent / per-session / per-call BYOK keys.
That makes the mental model simple: any chat turn that lands on a given
provider in a given project routes through that project's BYOK key for
that provider, regardless of which agent or session triggered it.

| What                       | Scope                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Storage                    | per `(project_id, provider)` — primary key in the table                                                                  |
| Resolution at request time | by `project_id` of the chat call → look up key for the resolved provider                                                 |
| Encryption                 | AES-256 at rest, decrypted only inside the request path                                                                  |
| API access                 | tenant-level API keys may manage any project they own; project-scoped keys must match the requested `project_id` exactly |

If you want different keys for different agents in the same project, use
separate projects — that's the only knob.

## Setup paths [#setup-paths]

Two ways to add a key, both equivalent on the wire:

### 1. Dashboard [#1-dashboard]

The fastest path for a one-off setup or rotation.

1. Open [platform.sonz.ai](https://platform.sonz.ai) and pick the project.
2. Go to **Settings → BYOK**.
3. Each of the four supported providers shows a card. Pick the one you
   want to configure.
4. Paste the API key from the provider (OpenAI, Google AI Studio for
   Gemini, xAI console, OpenRouter dashboard).
5. Hit **Save**. The dashboard runs the same synchronous probe the API
   does — if the upstream rejects the key, the save fails and you get the
   provider's error message inline. No bad key gets persisted.
6. Once saved the card switches to the configured state — redacted
   prefix, health badge (`healthy` / `unhealthy` / `unknown`), and
   buttons to **Replace**, **Test**, **Disable**, or **Delete**.

The dashboard is the same endpoint the SDK calls, so anything you do
there is identical to what you can script.

### 2. API / SDK [#2-api--sdk]

Useful for IaC, CI bootstrap of new tenants, key rotation cron jobs, or
provisioning during automated tenant onboarding. Endpoints documented
below.

## What you can plug in [#what-you-can-plug-in]

The same providers the platform speaks natively:

* `openai`
* `gemini`
* `xai`
* `openrouter` (internal fallback path — a key here covers when the platform falls through to OpenRouter)

A `custom` BYOM endpoint isn't a BYOK provider; configure it via
[Custom LLM](/docs/en/models/custom-llm) instead.

## Storage and security [#storage-and-security]

* Keys are **encrypted at rest** and decrypted only inside the
  platform's request path. They never round-trip back through any API —
  list / get responses return only an `api_key_prefix` (the first few
  characters) so you can identify which key is which.
* A **synchronous probe** runs at write time. Sonzai does a no-op call
  to the upstream provider with the key, so bad keys fail PUT with a
  400\. Misconfiguration surfaces at setup, not on the first user chat.
* Per-key **health is tracked**. Every read returns `health_status`,
  `last_health_error`, and `last_health_check_at` so you can detect a
  rotated-out or revoked key before users do — pipe these into a
  monitor and alert before chat traffic starts failing.

## Endpoints [#endpoints]

Per project, indexed by `(project_id, provider)`. List all keys, set
one, mark it inactive, delete, or re-test.

| Method   | Path                                                     | Purpose                                                      |
| -------- | -------------------------------------------------------- | ------------------------------------------------------------ |
| `GET`    | `/api/v1/projects/{projectId}/byok-keys`                 | List all keys (redacted)                                     |
| `PUT`    | `/api/v1/projects/{projectId}/byok-keys/{provider}`      | Set or rotate the key for a provider (probed before persist) |
| `PATCH`  | `/api/v1/projects/{projectId}/byok-keys/{provider}`      | Set `is_active` true/false without changing the key          |
| `POST`   | `/api/v1/projects/{projectId}/byok-keys/{provider}/test` | Re-probe the stored key against the upstream provider        |
| `DELETE` | `/api/v1/projects/{projectId}/byok-keys/{provider}`      | Remove the key                                               |

The full request/response shapes are in
[Reference → API → BYOK](/docs/en/reference/api/byok).

## Scopes for project API keys [#scopes-for-project-api-keys]

Project API keys created via the dashboard or `POST /api/v1/projects/{project_id}/api-keys`
carry a `scopes` array. To use BYOK programmatically via the SDK, the key needs:

* `read:byok` — to list providers and check health status.
* `write:byok` — to put / disable / delete / re-test keys.

Tenant-level credentials (Clerk dashboard sessions, default API keys with `["*"]`)
automatically have access to all BYOK operations.

Scope strings are case-sensitive, verb-first, and lower-case (`read:byok`, not `BYOK:Read`).

## Setting a key [#setting-a-key]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const key = await client.byok.set(&#x22;project_xyz&#x22;, &#x22;openai&#x22;, process.env.MY_OPENAI_KEY!);

console.log(key.api_key_prefix); // e.g. &#x22;sk-...&#x22; — never the full key
console.log(key.health_status);  // &#x22;healthy&#x22; after the synchronous probe`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

key = client.byok.set(
  &#x22;project_xyz&#x22;,
  &#x22;openai&#x22;,
  api_key=os.environ[&#x22;MY_OPENAI_KEY&#x22;],
)

print(key.api_key_prefix)   # e.g. &#x22;sk-...&#x22; — never the full key
print(key.health_status)    # &#x22;healthy&#x22; after the synchronous probe`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))

  key, err := client.BYOK.Set(context.Background(), &#x22;project_xyz&#x22;, sonzai.BYOKProviderOpenAI, os.Getenv(&#x22;MY_OPENAI_KEY&#x22;))
  if err != nil {
      panic(err) // probe failed — the upstream rejected the key
  }
  fmt.Println(key.APIKeyPrefix, key.HealthStatus)
}`,
  },
]"
/>

## Listing and inspecting [#listing-and-inspecting]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const keys = await client.byok.list(&#x22;project_xyz&#x22;);
for (const k of keys) {
console.log(k.provider, k.api_key_prefix, k.health_status, k.last_used_at);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `for k in client.byok.list(&#x22;project_xyz&#x22;):
  print(k.provider, k.api_key_prefix, k.health_status, k.last_used_at)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `keys, err := client.BYOK.List(ctx, &#x22;project_xyz&#x22;)
if err != nil {
  return err
}
for _, k := range keys {
  fmt.Printf(&#x22;%s\\t%s\\t%s\\t%v\\n&#x22;, k.Provider, k.APIKeyPrefix, k.HealthStatus, k.LastUsedAt)
}`,
  },
]"
/>

## Activating, deactivating, deleting [#activating-deactivating-deleting]

`PATCH` toggles `is_active` without rotating the key — handy for
disabling temporarily without losing the key material. `DELETE` removes
the key and its history.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Pause this BYOK key (subsequent calls fall back to platform-managed billing)
await client.byok.setActive(&#x22;project_xyz&#x22;, &#x22;openai&#x22;, false);

// Re-test
const fresh = await client.byok.test(&#x22;project_xyz&#x22;, &#x22;openai&#x22;);

// Permanently remove
await client.byok.delete(&#x22;project_xyz&#x22;, &#x22;openai&#x22;);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.byok.set_active(&#x22;project_xyz&#x22;, &#x22;openai&#x22;, is_active=False)
fresh = client.byok.test(&#x22;project_xyz&#x22;, &#x22;openai&#x22;)
client.byok.delete(&#x22;project_xyz&#x22;, &#x22;openai&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.BYOK.SetActive(ctx, &#x22;project_xyz&#x22;, sonzai.BYOKProviderOpenAI, false)
fresh, err := client.BYOK.Test(ctx, &#x22;project_xyz&#x22;, sonzai.BYOKProviderOpenAI)
err = client.BYOK.Delete(ctx, &#x22;project_xyz&#x22;, sonzai.BYOKProviderOpenAI)
_ = fresh`,
  },
]"
/>

## Caching and invalidation [#caching-and-invalidation]

The platform caches the resolved BYOK key per `(project_id, provider)`
in-process for performance. Every Set / Patch / Delete fires an
invalidator so a rotated key takes effect on the next call without a
restart.

## When BYOK doesn't apply [#when-byok-doesnt-apply]

If a project has no BYOK key for the provider that the chat call ends up
using, Sonzai bills that provider call to its own platform key as
normal — same UX, same SLA. BYOK is purely additive: set a key and it
takes over for that provider; remove it and the platform key kicks back
in.

## Reference [#reference]

* [Custom LLM (BYOM)](/docs/en/models/custom-llm) — entirely your own endpoint, not provider passthrough.
* [Providers](/docs/en/models/providers) — the four IDs you can attach BYOK keys to.
* [Model scope](/docs/en/models/scope) — how the chat / post-processing model is resolved across project / agent / per-call layers (BYOK applies after that resolution lands on a provider).
* [Reference → API → BYOK](/docs/en/reference/api/byok) — REST shape for every endpoint above.


---

# Custom LLM

Source: https://sonz.ai/docs/en/models/custom-llm

> Bring your own model while keeping the full managed experience — built-in tools, streaming, per-message extraction, personality evolution, and all behavioral systems. Sonzai calls your OpenAI-compatible endpoint instead of the default provider.



## How It Works [#how-it-works]

Configure an OpenAI-compatible API endpoint for your project. Sonzai routes all chat generation through your endpoint while handling everything else: context assembly, tool execution, side-effect extraction, memory storage, personality tracking, and consolidation.

<Cards>
  <Card title="Full Managed Experience" description="Built-in tools (web search, memory recall, image generation, inventory), streaming SSE, per-message side effects — everything works exactly as with our default providers." />

  <Card title="Your Model, Your Control" description="Use fine-tuned models, self-hosted endpoints, or any OpenAI-compatible provider (vLLM, Ollama, Together, Groq, Azure OpenAI, etc.)." />

  <Card title="Encrypted at Rest" description="Your API key is encrypted with AES-256 before storage. Only the first 8 characters are visible in the dashboard for identification." />

  <Card title="Per-Project Configuration" description="Each project can have its own custom LLM endpoint. Toggle it on/off without deleting the config." />
</Cards>

## Custom LLM vs. Standalone Memory [#custom-llm-vs-standalone-memory]

<Callout type="info" title="Which one should I use?">
  **Custom LLM** is the right choice when you want to use your own model but still want the full Sonzai experience (tools, streaming, per-message extraction). **Standalone Memory** is for when you need to control the entire chat loop yourself — e.g., for privacy preprocessing, data anonymization, or deep integration with an agent framework. See the [Standalone Memory docs](/docs/en/guides/standalone-memory) for the tradeoffs.
</Callout>

| Feature                     | Custom LLM   | Standalone Memory    |
| --------------------------- | ------------ | -------------------- |
| Built-in tools              | Full support | Manual only          |
| Streaming SSE               | Yes          | No                   |
| Per-message extraction      | Automatic    | Manual /process call |
| Memory prewarming           | Yes          | No                   |
| Data preprocessing          | No           | Full control         |
| Agent framework integration | N/A          | Full control         |

## Requirements [#requirements]

Your endpoint must be OpenAI-compatible:

* Accept `POST /chat/completions` (or the equivalent path your base URL resolves to)
* Accept OpenAI chat message format (`messages`, `model`, `temperature`, etc.)
* Return SSE stream in OpenAI chunk format (`data: {"choices": [...]}`)
* Support `tools` / `tool_choice` parameters if you want built-in tools to work

Compatible providers include: **vLLM**, **Ollama**, **Together AI**, **Groq**, **Azure OpenAI**, **Fireworks AI**, **Anyscale**, and any server implementing the OpenAI API spec.

## Configuration via Dashboard [#configuration-via-dashboard]

In the Sonzai dashboard, go to your project settings and configure the Custom LLM under the **Custom LLM** section:

1. Enter your OpenAI-compatible endpoint URL (e.g., `https://api.together.xyz/v1`)
2. Paste your API key (encrypted at rest with AES-256)
3. Specify the model name (e.g., `meta-llama/Llama-3.1-70B-Instruct`)
4. Optionally set a display name for easy identification
5. Toggle active/inactive without deleting the config

## Configuration via API [#configuration-via-api]

### Set Configuration [#set-configuration]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Configure custom LLM for a project
await client.customLLM.set(&#x22;project-id&#x22;, {
endpoint: &#x22;https://api.together.xyz/v1&#x22;,
apiKey: &#x22;your-api-key&#x22;,
model: &#x22;meta-llama/Llama-3.1-70B-Instruct&#x22;,
displayName: &#x22;Together Llama 3.1 70B&#x22;,
isActive: true,
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Configure custom LLM for a project
client.custom_llm.set(
  &#x22;project-id&#x22;,
  endpoint=&#x22;https://api.together.xyz/v1&#x22;,
  api_key=&#x22;your-api-key&#x22;,
  model=&#x22;meta-llama/Llama-3.1-70B-Instruct&#x22;,
  display_name=&#x22;Together Llama 3.1 70B&#x22;,
  is_active=True,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.CustomLLM.Set(ctx, &#x22;project-id&#x22;, sonzai.CustomLLMConfig{
  Endpoint:    &#x22;https://api.together.xyz/v1&#x22;,
  APIKey:      &#x22;your-api-key&#x22;,
  Model:       &#x22;meta-llama/Llama-3.1-70B-Instruct&#x22;,
  DisplayName: &#x22;Together Llama 3.1 70B&#x22;,
  IsActive:    true,
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X PUT https://api.sonz.ai/api/v1/projects/{projectId}/custom-llm \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;endpoint&#x22;: &#x22;https://api.together.xyz/v1&#x22;,
  &#x22;api_key&#x22;: &#x22;your-api-key&#x22;,
  &#x22;model&#x22;: &#x22;meta-llama/Llama-3.1-70B-Instruct&#x22;,
  &#x22;display_name&#x22;: &#x22;Together Llama 3.1 70B&#x22;,
  &#x22;is_active&#x22;: true
}'`,
  },
]"
/>

### Get Configuration [#get-configuration]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const config = await client.customLLM.get(&#x22;project-id&#x22;);

if (config.configured) {
console.log(config.endpoint);      // &#x22;https://api.together.xyz/v1&#x22;
console.log(config.apiKeyPrefix);   // &#x22;your-api&#x22; (first 8 chars)
console.log(config.model);          // &#x22;meta-llama/Llama-3.1-70B-Instruct&#x22;
console.log(config.isActive);       // true
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `config = client.custom_llm.get(&#x22;project-id&#x22;)

if config.configured:
  print(config.endpoint)       # &#x22;https://api.together.xyz/v1&#x22;
  print(config.api_key_prefix) # &#x22;your-api&#x22;
  print(config.model)          # &#x22;meta-llama/...&#x22;
  print(config.is_active)      # True`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `config, err := client.CustomLLM.Get(ctx, &#x22;project-id&#x22;)

if config.Configured {
  fmt.Println(config.Endpoint)     // &#x22;https://api.together.xyz/v1&#x22;
  fmt.Println(config.APIKeyPrefix) // &#x22;your-api&#x22;
  fmt.Println(config.Model)        // &#x22;meta-llama/...&#x22;
}`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl https://api.sonz.ai/api/v1/projects/{projectId}/custom-llm \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22;`,
  },
]"
/>

### Remove Configuration [#remove-configuration]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.customLLM.delete(&#x22;project-id&#x22;);`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.custom_llm.delete(&#x22;project-id&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.CustomLLM.Delete(ctx, &#x22;project-id&#x22;)`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X DELETE https://api.sonz.ai/api/v1/projects/{projectId}/custom-llm \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22;`,
  },
]"
/>

## How Chat Routes Through Your Model [#how-chat-routes-through-your-model]

Once configured, here is what happens when a chat request is made:

1. **Context assembly** — Sonzai builds the 7-layer enriched context (personality, memory, mood, habits, goals, relationships, application state) exactly as with default providers.
2. **Tool injection** — Built-in tools (`sonzai_memory_recall`, `sonzai_web_search`, etc.) and any custom tools are added to the request.
3. **Your endpoint called** — The request is sent to your configured endpoint with your model name, API key, and the full message history including system prompt.
4. **Streaming proxy** — SSE chunks from your endpoint are streamed back to the client in real time.
5. **Post-stream processing** — After the stream completes, Sonzai extracts side effects (memory facts, mood changes, personality shifts, habits, tool calls) and stores them — same as with default providers.

## Background Job Consistency [#background-job-consistency]

Background tasks like fact extraction, memory consolidation, diary generation, and summarization automatically use the same model family you configured. Sonzai tracks the last-used provider/model for each agent and routes background LLM calls accordingly.

## Security [#security]

* **API key encryption** — Keys are encrypted with AES-256 before storage. Only the first 8 characters are visible.
* **SSRF protection** — Endpoint URLs are validated to block localhost, private IPs (10.x, 172.16-31.x, 192.168.x), link-local, and cloud metadata addresses.
* **Project-scoped** — Each config is scoped to a project. Different projects can use different endpoints.

## Billing [#billing]

Custom LLM usage is billed at a flat per-token rate under the `custom_llm` billing model, regardless of which actual model your endpoint serves. Sonzai tracks input/output tokens from your endpoint's usage response. Your own endpoint costs (API fees, compute) are entirely yours.


---

# Models

Source: https://sonz.ai/docs/en/models

> How Sonzai picks a model for chat and a (different) model for the background post-processing — providers, BYOK, and the scope cascade.



Every Sonzai chat turn fans out into two model calls:

* **Chat completion** — what the user sees, streamed back live. Pick this
  for personality and quality.
* **Post-processing** — the latency-insensitive batch work that runs after
  the reply ships: fact extraction, deduplication, mood updates,
  personality drift, summarisation, diary, constellation. Pick this for
  cost and throughput.

The two are configured independently. A frontier chat model can pair with
a cheap flash-lite extractor, and Sonzai resolves both per call through a
**five-layer cascade** that lets you override at agent, project, account
(tenant), and session scope.

## Supported providers [#supported-providers]

| ID       | Provider           | Default model                   | Notes                                                                                         |
| -------- | ------------------ | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `gemini` | Google Gemini      | `gemini-3.1-flash-lite-preview` | Platform default — also the fallback wildcard for post-processing                             |
| `openai` | OpenAI             | `gpt-5.5`                       | 5.4 / 5 / mini / nano in the same family for fallback                                         |
| `xai`    | xAI (Grok)         | `grok-4-1-fast-non-reasoning`   | Reasoning + non-reasoning Grok 4 / 4.20 variants                                              |
| `custom` | Bring-your-own LLM | —                               | Point Sonzai at any OpenAI-compatible endpoint — see [Custom LLM](/docs/en/models/custom-llm) |

The `sonzai.providers` module exports these IDs as constants — import
them rather than hand-typing strings, so the IDs stay in sync as the
catalog evolves. `client.list_models()` returns the live set enabled on
your tenant for runtime model-picker UIs.

<Callout type="info" title="Internal fallback">
  The platform also speaks `openrouter` for its own internal failover
  paths. Customers don't pick `openrouter` directly today; Sonzai handles
  failover on its side when the primary provider quota is exhausted.
</Callout>

## BYOK — bring your own key [#byok--bring-your-own-key]

Use Sonzai's hosted infrastructure but bill provider tokens to your own
account. Drop a key per provider against your project; subsequent
requests on that project route through your key for the matching
provider. Keys are encrypted at rest and never echoed back through the
API.

[**BYOK setup → /docs/en/models/byok**](/docs/en/models/byok)

## How a model gets picked [#how-a-model-gets-picked]

For both chat and post-processing, Sonzai walks a five-layer cascade.
First non-empty hit wins.

1. **Per-call** — `provider` / `model` on `agents.chat`, `agents.process`, or `sessions.start`
2. **Per-agent** — `AgentProfile.ModelConfig` (chat) and `AgentProfile.PostProcessingProvider/Model` (post-processing)
3. **Per-project** — `project_config.post_processing_model_map` (post-processing); chat defaults are typically agent-level
4. **Per-account / tenant** — `account_config.post_processing_model_map` (post-processing)
5. **System default** — `gemini-3.1-flash-lite-preview` for both

Read the full layer-by-layer rules at [**Model scope**](/docs/en/models/scope).

## Pages [#pages]

<Cards>
  <Card href="/docs/en/models/providers" title="Providers" description="The four supported providers (gemini, openai, xai, custom) with model IDs, context windows, and fallback chains." />

  <Card href="/docs/en/models/byok" title="BYOK" description="Drop a per-project, per-provider key. Encrypted at rest; probed at write." />

  <Card href="/docs/en/models/scope" title="Model scope" description="Tenant → project → agent → session: where each setting lives and which one wins." />

  <Card href="/docs/en/models/post-processing" title="Post-processing model map" description="The cheaper-model fleet that runs the batch work behind every chat turn." />

  <Card href="/docs/en/models/custom-llm" title="Custom LLM (BYOM)" description="Route chat completions through your own endpoint while the Relationship Layer keeps owning memory, personality, and mood." />
</Cards>


---

# Post-processing model map

Source: https://sonz.ai/docs/en/models/post-processing

> Configure the smaller models that run behind chat completions to extract memory, drift personality, and update mood.



Behind every chat turn, Sonzai runs a fleet of smaller models that:

* **Extract facts** from the user message and the agent reply
* **Drift personality** scores in response to interactions
* **Update mood** dimensions (happiness, energy, calmness, affection)
* **Summarise** sessions and compact older memory

These run *after* the user-facing reply is streamed, on the
**post-processing model map** — a per-project config that maps the
chat-completion model to the smaller model the extractor should use.

## The map [#the-map]

Stored under the `post_processing_model_map` project-config key. Each
entry is a `PostProcessingModelEntry` with two fields:

```ts
type PostProcessingModelEntry = {
  provider: string; // e.g. "gemini"
  model:    string; // e.g. "gemini-3.1-flash-lite-preview"
};
```

The map keys are **chat-completion model IDs** plus a special `*`
wildcard that catches any chat model not explicitly listed:

```json
{
  "claude-3-5-sonnet": { "provider": "gemini",  "model": "gemini-3.1-flash-lite-preview" },
  "gpt-4-turbo":       { "provider": "openrouter", "model": "anthropic/claude-3-haiku" },
  "*":                 { "provider": "gemini",  "model": "gemini-3.1-flash-lite-preview" }
}
```

When extraction needs to run for a chat that used `claude-3-5-sonnet`,
the extractor uses Gemini Flash Lite. When it sees a chat model not in
the map, the `*` wildcard kicks in.

The wildcard key is exported as `sonzai.PostProcessingWildcardKey` (Go)
and the equivalent constant in the other SDKs so you don't have to
hard-code `"*"` in your provisioning scripts.

## Reading the current map [#reading-the-current-map]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const map = await client.projectConfig.getPostProcessingModelMap(&#x22;project_xyz&#x22;);
for (const [chatModel, entry] of Object.entries(map ?? {})) {
console.log(chatModel, &#x22;→&#x22;, entry.provider, entry.model);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `m = client.project_config.get_post_processing_model_map(&#x22;project_xyz&#x22;)
for chat_model, entry in (m or {}).items():
  print(chat_model, &#x22;→&#x22;, entry.provider, entry.model)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `m, err := client.ProjectConfig.GetPostProcessingModelMap(ctx, &#x22;project_xyz&#x22;)
if err != nil {
  return err
}
for chatModel, entry := range m {
  fmt.Printf(&#x22;%s → %s %s\\n&#x22;, chatModel, entry.Provider, entry.Model)
}`,
  },
]"
/>

## Setting a map (or a single-key default) [#setting-a-map-or-a-single-key-default]

Pass a full map; the call is a write-through replacement, not a merge.
Most projects only need a wildcard entry pointing at a cheap model:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.projectConfig.setPostProcessingModelMap(&#x22;project_xyz&#x22;, {
&#x22;*&#x22;: { provider: &#x22;gemini&#x22;, model: &#x22;gemini-3.1-flash-lite-preview&#x22; },
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.project_config.set_post_processing_model_map(
  &#x22;project_xyz&#x22;,
  {
      &#x22;*&#x22;: {&#x22;provider&#x22;: &#x22;gemini&#x22;, &#x22;model&#x22;: &#x22;gemini-3.1-flash-lite-preview&#x22;},
  },
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := client.ProjectConfig.SetPostProcessingModelMap(ctx, &#x22;project_xyz&#x22;,
  sonzai.PostProcessingModelMap{
      sonzai.PostProcessingWildcardKey: {
          Provider: &#x22;gemini&#x22;,
          Model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
      },
  },
)`,
  },
]"
/>

## When to override per chat model [#when-to-override-per-chat-model]

The wildcard is enough for most projects. Reach for an explicit entry
when:

* A particular chat model produces output the default extractor mishandles
  (e.g. tool-call traces from a verbose model that need a stronger
  extractor to keep facts atomic).
* You're A/B-ing two extractors and want one chat model to route through
  each for comparison.
* Cost: cheaper chat models can run a cheaper extractor; flagship chat
  models may warrant a stronger extractor on the same trace.

<Callout type="warn" title="Provider availability">
  An entry's `provider`/`model` must match a real provider Sonzai has
  configured for your project — see [Providers](/docs/en/models/providers).
  Setting a non-existent provider here makes extraction fail
  asynchronously after the user-facing reply has already streamed; you'll
  see it in the agent's `extraction_status` on the next turn.
</Callout>

## Reference [#reference]

* [Providers](/docs/en/models/providers) — the chat-completion provider list (independent of post-processing).
* [Self-improvement](/docs/en/self-improvement) — the full picture of what the extractor does on each turn.
* [Reference → API](/docs/en/reference) — REST endpoint shapes for the `project-config` get/set/delete calls.


---

# Providers

Source: https://sonz.ai/docs/en/models/providers

> The four supported chat-completion providers — gemini, openai, xai, custom — with model IDs, context windows, and how to pick one at runtime.



Sonzai routes chat completions through one of four providers. The IDs
are exported as constants from the `sonzai.providers` module in the
SDKs — import those rather than hand-typing strings, so they stay in
sync as the catalog evolves. Use `client.list_models()` for the live
set enabled on your tenant at runtime.

## `gemini` — Google Gemini (default) [#gemini--google-gemini-default]

The platform default. `gemini-3.1-flash-lite-preview` is `providers.DEFAULT_MODEL`,
and is also the wildcard fallback for the [post-processing](/docs/en/models/post-processing)
cascade.

| Model                           | Context window | Notes                                                                                |
| ------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| `gemini-3.1-flash-lite-preview` | 1M             | Default. Vision + tools + JSON mode + streaming. Compaction at 450k / 500k.          |
| `gemini-3-flash-preview`        | 2M             | Fallback on 429. Same feature set.                                                   |
| `gemini-3.1-pro-preview`        | 2M             | Fallback on 429. Strongest Gemini model — pair with a cheaper post-processing entry. |

## `openai` — OpenAI [#openai--openai]

Default `gpt-5.5`; the 5.4 family is the cheaper workhorse and 5 / 5-mini /
5-nano cover even cheaper or smaller-context tiers. The fallback chain on
quota exhaustion is `gpt-5.5 → gpt-5.4 → gpt-5.4-mini → gpt-5`.

| Model                       | Context window | Use it when                                                                                |
| --------------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `gpt-5.5`                   | 1.05M          | Default. The current OpenAI frontier — vision + tools + streaming + JSON mode.             |
| `gpt-5.4`                   | 1.05M          | Cheaper than 5.5, same context window.                                                     |
| `gpt-5.4-mini`              | 1.05M          | The cheap workhorse. Recommended for high-throughput tenants.                              |
| `gpt-5`                     | 400k           | Frozen Aug-2025 snapshot. Kept for tenants pinned to it; new agents should default to 5.5. |
| `gpt-5-mini` / `gpt-5-nano` | 400k           | Smaller-context tiers; same generation as `gpt-5`.                                         |

## `xai` — xAI (Grok) [#xai--xai-grok]

Reasoning and non-reasoning variants in the Grok 4 family.
`grok-4-1-fast-non-reasoning` is the default; reasoning models are
opt-in for tasks that benefit from deeper chain-of-thought.

| Model                          | Context window | Reasoning |
| ------------------------------ | -------------- | --------- |
| `grok-4-1-fast-non-reasoning`  | 2M             | No        |
| `grok-4-1-fast-reasoning`      | 2M             | Yes       |
| `grok-4.20-0309-non-reasoning` | 2M             | No        |
| `grok-4.20-0309-reasoning`     | 2M             | Yes       |

All Grok 4 entries support streaming, tools, and JSON mode. None support
vision today.

## `custom` — bring-your-own-LLM (BYOM) [#custom--bring-your-own-llm-byom]

Point Sonzai at any OpenAI-compatible chat-completions endpoint. The
Relationship Layer keeps owning memory, personality, mood, and post-processing —
only the chat-completion call gets routed through your endpoint.

See [Custom LLM](/docs/en/models/custom-llm) for the full setup. This is
distinct from [BYOK](/docs/en/models/byok) — BYOK uses Sonzai's
provider integrations but with your billing key; BYOM uses your own
inference stack entirely.

## Picking a provider in code [#picking-a-provider-in-code]

Pass `provider` and `model` on the chat call. Both are optional — omit
them and Sonzai uses the agent's default, falling back through the
[scope cascade](/docs/en/models/scope).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

await client.agents.chat({
agent:    &#x22;agent_abc&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Hello&#x22; }],
provider: &#x22;openai&#x22;,
model:    &#x22;gpt-5.5&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
from sonzai import providers

client = Sonzai(api_key=&#x22;sk-...&#x22;)

client.agents.chat(
  agent_id=&#x22;agent_abc&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Hello&#x22;}],
  provider=providers.GEMINI,
  model=providers.models.GEMINI_FLASH_LITE,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  _, _ = client.Agents.Chat(context.Background(), sonzai.AgentChatParams{
      Agent:    &#x22;agent_abc&#x22;,
      Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Hello&#x22;}},
      Provider: &#x22;xai&#x22;,
      Model:    &#x22;grok-4-1-fast-non-reasoning&#x22;,
  })
}`,
  },
]"
/>

## Listing what's available at runtime [#listing-whats-available-at-runtime]

`client.list_models()` (Python / TS / Go expose the same shape) returns
the live set of providers and models enabled on your tenant — useful for
building a model-picker UI or for asserting that a provider you depend on
is wired up before a deploy.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const result = await client.listModels();
for (const p of result.providers) {
console.log(p.provider, p.models.map((m) => m.id));
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = client.list_models()
for p in result.providers:
  print(p.provider, [m.id for m in p.models])`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := client.ListModels(ctx)
if err != nil {
  return err
}
for _, p := range result.Providers {
  ids := make([]string, 0, len(p.Models))
  for _, m := range p.Models {
      ids = append(ids, m.ID)
  }
  fmt.Println(p.Provider, ids)
}`,
  },
]"
/>

## Reference [#reference]

* [BYOK](/docs/en/models/byok) — drop your own provider keys per project.
* [Custom LLM](/docs/en/models/custom-llm) — point Sonzai at your own endpoint entirely.
* [Model scope](/docs/en/models/scope) — how `provider` / `model` is resolved per call.
* [Post-processing](/docs/en/models/post-processing) — what runs in the background, on what model.


---

# Model scope

Source: https://sonz.ai/docs/en/models/scope

> Where the chat model and the post-processing model are configured — tenant, project, agent, session, and per-call — and which layer wins.



A Sonzai chat turn picks **two** models: the chat-completion model the
user sees, and the post-processing model that runs the background work
afterwards. Each goes through its own resolver cascade. The cascades
share the same scope hierarchy:

```
1. per-call            (highest precedence — passed to agents.chat / sessions.start / agents.process)
2. per-agent           (AgentProfile fields)
3. per-project         (project_config rows in CockroachDB)
4. per-account/tenant  (account_config rows in CockroachDB)
5. system default      (Go constant compiled into the binary)
```

First non-empty layer wins. Layer 5 always exists, so resolution always
produces a concrete answer.

## Chat model [#chat-model]

What the user sees. Resolved per chat turn.

| Layer                | Where it lives                                                                                      | Set with                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Per-call             | `provider` / `model` arg on `agents.chat`, `agents.chat_stream`, `agents.process`, `sessions.start` | the SDK call itself                                                          |
| Per-agent            | `AgentProfile.ModelConfig.{provider,model}`                                                         | `client.agents.update(agent_id, model_config={...})`                         |
| Per-project          | Default model for an unconfigured agent in a project                                                | Project settings on the dashboard or `client.providers.set(project_id, ...)` |
| Per-account / tenant | Org-wide default                                                                                    | (admin endpoint, see [Reference](/docs/en/reference))                        |
| System default       | `gemini-3.1-flash-lite-preview` (`providers.DEFAULT_MODEL`)                                         | constant, not configurable                                                   |

### Setting at each layer [#setting-at-each-layer]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Per-call: pin a single chat call
await client.agents.chat({
agent:    &#x22;agent_abc&#x22;,
provider: &#x22;openai&#x22;, model: &#x22;gpt-5.5&#x22;,
messages: [{ role: &#x22;user&#x22;, content: &#x22;Hello&#x22; }],
});

// Per-session: set defaults that every session.turn() inherits
const session = await client.agents.sessions.start(&#x22;agent_abc&#x22;, {
userId:   &#x22;user_123&#x22;,
sessionId: &#x22;session_abc&#x22;,
provider: &#x22;xai&#x22;,
model:    &#x22;grok-4-1-fast-non-reasoning&#x22;,
});

// Per-agent: persist on the AgentProfile
await client.agents.update(&#x22;agent_abc&#x22;, {
modelConfig: { provider: &#x22;gemini&#x22;, model: &#x22;gemini-3.1-pro-preview&#x22; },
});

// Per-project: chat default for unpinned agents in this project
await client.providers.set(&#x22;project_xyz&#x22;, { provider: &#x22;gemini&#x22;, model: &#x22;gemini-3.1-flash-lite-preview&#x22; });`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Per-call
client.agents.chat(
  agent_id=&#x22;agent_abc&#x22;,
  provider=&#x22;openai&#x22;, model=&#x22;gpt-5.5&#x22;,
  messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Hello&#x22;}],
)

# Per-session
session = client.agents.sessions.start(
  &#x22;agent_abc&#x22;,
  user_id=&#x22;user_123&#x22;,
  session_id=&#x22;session_abc&#x22;,
  provider=&#x22;xai&#x22;,
  model=&#x22;grok-4-1-fast-non-reasoning&#x22;,
)

# Per-agent
client.agents.update(
  &#x22;agent_abc&#x22;,
  model_config={&#x22;provider&#x22;: &#x22;gemini&#x22;, &#x22;model&#x22;: &#x22;gemini-3.1-pro-preview&#x22;},
)

# Per-project
client.providers.set(&#x22;project_xyz&#x22;, provider=&#x22;gemini&#x22;, model=&#x22;gemini-3.1-flash-lite-preview&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Per-call
_, _ = client.Agents.Chat(ctx, sonzai.AgentChatParams{
  Agent:    &#x22;agent_abc&#x22;,
  Provider: &#x22;openai&#x22;, Model: &#x22;gpt-5.5&#x22;,
  Messages: []sonzai.ChatMessage{{Role: &#x22;user&#x22;, Content: &#x22;Hello&#x22;}},
})

// Per-session
session, _ := client.Agents.Sessions.Start(ctx, &#x22;agent_abc&#x22;, sonzai.SessionStartOptions{
  UserID:    &#x22;user_123&#x22;,
  SessionID: &#x22;session_abc&#x22;,
  Provider:  &#x22;xai&#x22;,
  Model:     &#x22;grok-4-1-fast-non-reasoning&#x22;,
})

// Per-agent
_, _ = client.Agents.Update(ctx, &#x22;agent_abc&#x22;, sonzai.UpdateAgentOptions{
  ModelConfig: &sonzai.ModelConfig{Provider: &#x22;gemini&#x22;, Model: &#x22;gemini-3.1-pro-preview&#x22;},
})

// Per-project
_, _ = client.Providers.Set(ctx, &#x22;project_xyz&#x22;, sonzai.SetProviderOptions{
  Provider: &#x22;gemini&#x22;,
  Model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
})

_ = session`,
  },
]"
/>

## Post-processing model [#post-processing-model]

The cheaper-model fleet that runs the batch work behind every turn:
fact extraction, dedup, mood updates, personality drift, summarisation,
diary, constellation. Resolved per task, per turn, independently of the
chat model.

The cascade is documented exhaustively at
[**Post-processing model map**](/docs/en/models/post-processing). The
short version:

| Layer                | Where it lives                                                                                                               |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Per-agent            | `AgentProfile.PostProcessingProvider` + `PostProcessingModel` (direct override; bypasses the cascade entirely when both set) |
| Per-project          | `project_config.post_processing_model_map` JSONB — `chat_model → {provider, model}` map                                      |
| Per-account / tenant | `account_config.post_processing_model_map` JSONB — same shape                                                                |
| System default       | Go constant, ships with the binary                                                                                           |
| Wildcard fallback    | `gemini-3.1-flash-lite-preview`                                                                                              |

The map keys are **chat-completion model IDs** (or `*` for wildcard), so
post-processing routing depends on what chat model just ran.

### Setting at each layer [#setting-at-each-layer-1]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Per-agent — direct override that bypasses the rest of the cascade
await client.agents.updatePostProcessingModel(&#x22;agent_abc&#x22;, {
post_processing_provider: &#x22;gemini&#x22;,
post_processing_model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
});

// Per-project — full chat→post map (write-through replacement)
await client.projectConfig.setPostProcessingModelMap(&#x22;project_xyz&#x22;, {
&#x22;claude-opus-4.6&#x22;: { provider: &#x22;openrouter&#x22;, model: &#x22;anthropic/claude-haiku-4.5&#x22; },
&#x22;*&#x22;:               { provider: &#x22;gemini&#x22;,     model: &#x22;gemini-3.1-flash-lite-preview&#x22; },
});

// Per-account/tenant
await client.accountConfig.setPostProcessingModelMap({
&#x22;*&#x22;: { provider: &#x22;gemini&#x22;, model: &#x22;gemini-3.1-flash-lite-preview&#x22; },
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Per-agent
client.agents.update_post_processing_model(
  &#x22;agent_abc&#x22;,
  post_processing_provider=&#x22;gemini&#x22;,
  post_processing_model=&#x22;gemini-3.1-flash-lite-preview&#x22;,
)

# Per-project
client.project_config.set_post_processing_model_map(
  &#x22;project_xyz&#x22;,
  {
      &#x22;claude-opus-4.6&#x22;: {&#x22;provider&#x22;: &#x22;openrouter&#x22;, &#x22;model&#x22;: &#x22;anthropic/claude-haiku-4.5&#x22;},
      &#x22;*&#x22;:               {&#x22;provider&#x22;: &#x22;gemini&#x22;,     &#x22;model&#x22;: &#x22;gemini-3.1-flash-lite-preview&#x22;},
  },
)

# Per-account / tenant
client.account_config.set_post_processing_model_map({
  &#x22;*&#x22;: {&#x22;provider&#x22;: &#x22;gemini&#x22;, &#x22;model&#x22;: &#x22;gemini-3.1-flash-lite-preview&#x22;},
})`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Per-agent
_, _ = client.Agents.UpdatePostProcessingModel(ctx, &#x22;agent_abc&#x22;, sonzai.PostProcessingOverride{
  Provider: &#x22;gemini&#x22;,
  Model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
})

// Per-project
err := client.ProjectConfig.SetPostProcessingModelMap(ctx, &#x22;project_xyz&#x22;,
  sonzai.PostProcessingModelMap{
      &#x22;claude-opus-4.6&#x22;: {Provider: &#x22;openrouter&#x22;, Model: &#x22;anthropic/claude-haiku-4.5&#x22;},
      sonzai.PostProcessingWildcardKey: {Provider: &#x22;gemini&#x22;, Model: &#x22;gemini-3.1-flash-lite-preview&#x22;},
  },
)

// Per-account / tenant
err = client.AccountConfig.SetPostProcessingModelMap(ctx,
  sonzai.PostProcessingModelMap{
      sonzai.PostProcessingWildcardKey: {Provider: &#x22;gemini&#x22;, Model: &#x22;gemini-3.1-flash-lite-preview&#x22;},
  },
)
_ = err`,
  },
]"
/>

## Previewing the resolved model [#previewing-the-resolved-model]

For UI ("which model would run my diary tonight?") you can ask the
resolver what it *would* pick without firing inference:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const effective = await client.agents.effectivePostProcessingModel(&#x22;agent_abc&#x22;, {
chatModel: &#x22;claude-opus-4.6&#x22;,
taskType:  &#x22;fact_extraction&#x22;,
});
console.log(effective.provider, effective.model);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `effective = client.agents.effective_post_processing_model(
  &#x22;agent_abc&#x22;,
  chat_model=&#x22;claude-opus-4.6&#x22;,
  task_type=&#x22;fact_extraction&#x22;,
)
print(effective.provider, effective.model)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `effective, err := client.Agents.EffectivePostProcessingModel(ctx, &#x22;agent_abc&#x22;, sonzai.EffectivePostProcessingOptions{
  ChatModel: &#x22;claude-opus-4.6&#x22;,
  TaskType:  &#x22;fact_extraction&#x22;,
})
if err != nil {
  return err
}
fmt.Println(effective.Provider, effective.Model)`,
  },
]"
/>

## Common patterns [#common-patterns]

* **One frontier model per agent, one cheap extractor per project.** Set
  agent `ModelConfig` to your premium model; set the project
  post-processing map's `*` wildcard to `gemini/gemini-3.1-flash-lite-preview`.
* **A/B test extractors.** Two projects, same agents, different
  `account_config.post_processing_model_map` entries — compare quality on
  the same traffic.
* **Per-tenant pricing tiers.** Free tier defaults the post-processing
  map to flash-lite at the tenant level; paid tier overrides per-project
  to a stronger extractor.
* **One-off override.** Pass `provider`/`model` on a single
  `agents.chat` call without persisting anything.

## Reference [#reference]

* [Providers](/docs/en/models/providers) — provider IDs and model lists.
* [BYOK](/docs/en/models/byok) — bring your own provider key per project.
* [Post-processing](/docs/en/models/post-processing) — full cascade rules + the system-default map.
* [Reference → API](/docs/en/reference) — REST shape for every endpoint above.


---

# API Reference

Source: https://sonz.ai/docs/en/reference

> Public reference for creating agents and interacting with them over REST API. Internal context assembly, memory management, and state orchestration are platform-managed and intentionally omitted.



## Authentication [#authentication]

All API calls require Bearer authentication with your project API key.

```
Authorization: Bearer YOUR_PROJECT_API_KEY
```

## API Reference [#api-reference]

Browse the full endpoint reference — schemas, request/response examples, and an interactive try-it panel — at [**/docs/en/api**](/docs/en/reference/api). Every operation gets its own page generated from the live OpenAPI spec.

### Raw spec (for Postman, code generators, custom tools) [#raw-spec-for-postman-code-generators-custom-tools]

The live OpenAPI 3.1 JSON + YAML is publicly hosted — no authentication required — and regenerated on every deploy:

```
https://api.sonz.ai/docs/openapi.json
https://api.sonz.ai/docs/openapi.yaml
```

```bash
curl -sL https://api.sonz.ai/docs/openapi.json -o openapi.json
```

<Callout type="info" title="Error Format">
  All error responses use the [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) `application/problem+json` format with `type`, `title`, `status`, `detail`, and optional `instance` fields.
</Callout>

## REST API [#rest-api]

Public HTTP endpoints for agent lifecycle, real-time agent interaction, and proactive delivery. Memory, mood, relationship, and context-management internals are handled by the platform.

<Callout type="warn">
  **Server-side only.** The API does not accept browser requests. For web apps, proxy through your backend. See the [Integration Guide](/docs/en/guides/integration).
</Callout>

### Agent Lifecycle [#agent-lifecycle]

#### Create an agent [#create-an-agent]

`POST /api/v1/agents`

Create a new agent. Returns the agent with a platform-generated UUID.

Parameters:

* `name` (string): Agent name (required)
* `personality_prompt` (string): Custom system prompt (optional)
* `big5` (object): Big Five scores: openness, conscientiousness, extraversion, agreeableness, neuroticism (0.0-1.0)
* `speech_patterns` (string\[]): Speech patterns (optional)
* `true_interests` (string\[]): Agent interests (optional)
* `project_id` (string): Project UUID to assign agent to (optional)
* `language` (string): ISO language code, e.g. "en" (optional)

Response: `{ "agent_id": "uuid", "name": "...", ... }`

#### List agents [#list-agents]

`GET /api/v1/agents`

List agents. Filter by project\_id query param.

Parameters:

* `project_id` (string): Filter by project (query param, optional)

Response: Array of agent objects

#### Get agent [#get-agent]

`GET /api/v1/agents/{agentId}`

Get agent by ID.

Response: Agent object with personality, mood, profile

### Chat [#chat]

#### Stream chat [#stream-chat]

`POST /api/v1/agents/{agentId}/chat`

Chat with agent via SSE streaming. Returns Server-Sent Events.

Parameters:

* `messages` (CEChatMessage\[]): Conversation messages
* `user_id` (string): User identifier

Response: SSE stream of chat completion chunks

### Proactive Notifications [#proactive-notifications]

#### List notifications [#list-notifications]

`GET /api/v1/agents/{agentId}/notifications`

List pending proactive messages.

Parameters:

* `status` (string): Filter by status: pending | consumed (default: pending, query param)
* `user_id` (string): Filter by user (optional, query param)
* `limit` (int): Max results (default: 50, max: 500, query param)

Response: List of proactive messages with message\_id, agent\_id, user\_id, check\_type, intent, generated\_message, status, created\_at

#### Consume notification [#consume-notification]

`POST /api/v1/agents/{agentId}/notifications/{messageId}/consume`

Mark a notification as consumed after delivery.

Response: Confirmation

#### Notification history [#notification-history]

`GET /api/v1/agents/{agentId}/notifications/history`

List all notifications across all statuses.

Response: Full notification history

## Agent Lifecycle (Detailed) [#agent-lifecycle-detailed]

### CreateAgent [#createagent]

Creates a new agent with personality configuration. Generates personality prompt, speech patterns, and emotional tendencies.

Request:

* `user_id` (string): Owner user identifier
* `agent_name` (string): Agent display name
* `gender` (string): "male", "female", or "non\_binary"
* `bio` (string): Agent biography (optional)
* `avatar_url` (string): Avatar image URL (optional)
* `big5` (CEBig5Scores): Big Five personality scores (0.0-1.0)
* `language` (string): Primary language
* `equipped_outfit` (string): Initial outfit ID (optional)
* `skills` (CESkillLevel\[]): Initial skill levels (optional)
* `model_tier` (int32): LLM model tier (optional)
* `project_id` (string): Project to assign agent to (optional)
* `agent_id` (string): Caller-specified ID for deterministic agents (optional)
* `personality_prompt` (string): Custom system prompt (optional)
* `generate_goals` (bool): Auto-generate goals after creation (optional)
* `provided_goals` (string\[]): Store these goals directly (optional)
* `speech_patterns` (string\[]): Speech patterns (optional)
* `true_interests` (string\[]): Agent interests (optional)
* `true_dislikes` (string\[]): Agent dislikes (optional)
* `user_display_name` (string): Owner display name (optional)
* `generate_avatar` (bool): Auto-generate an AI avatar on creation (default: true, costs 1 credit). Set to false to skip.

Response: agent\_id (UUID), status ('completed' or 'in\_progress')

### GetAgent [#getagent]

Retrieves an agent's current state including personality, mood, and profile.

Request:

* `agent_id` (string): Agent UUID

Response: Agent ID, name, bio, gender, avatar\_url, Big5 scores, owner, created\_at

### UpdateAgent [#updateagent]

Updates agent fields (name, bio, avatar, personality, interests, speech patterns).

Request:

* `agent_id` (string): Agent UUID
* `name` (string): New name (optional)
* `bio` (string): New bio (optional)
* `avatar_url` (string): New avatar URL (optional)
* `big5` (CEBig5Scores): Updated Big5 scores (optional)
* `true_interests` (string\[]): Updated interests (optional)
* `true_dislikes` (string\[]): Updated dislikes (optional)
* `speech_patterns` (string\[]): Updated speech patterns (optional)
* `personality_prompt` (string): Updated system prompt (optional)

Response: success (bool)

### DeleteAgent [#deleteagent]

Permanently deletes an agent and all associated data (memory, mood, relationships).

Request:

* `agent_id` (string): Agent UUID

Response: success (bool)

### RegenerateAvatar [#regenerateavatar]

Generates or regenerates an AI-created avatar for the agent. Uses LLM to create an image prompt from personality data, then generates and uploads the image. Costs 1 credit. Avatars are auto-generated on agent creation unless disabled.

Request:

* `agent_id` (string): Agent UUID (URL param)
* `style` (string): Optional style hint (e.g. 'watercolor anime', 'realistic portrait')

Response: success (bool), avatar\_url (string), prompt (string), generation\_time\_ms (int64)

### UpdateAgentPersonality [#updateagentpersonality]

Updates an agent's authored Big5 personality configuration when your product intentionally changes the agent design.

Request:

* `agent_id` (string): Agent UUID
* `big5` (CEBig5Scores): Updated Big Five scores with confidence

Response: success (bool)

## Proactive Behaviors [#proactive-behaviors]

### ScheduleWakeup [#schedulewakeup]

Schedules the agent to proactively reach out to a user after a delay.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `check_type` (string): Type of check: check\_in, follow\_up, mood\_driven
* `intent` (string): Why the agent wants to reach out
* `delay_hours` (int32): Hours to delay before wakeup

Response: wakeup\_id (string), scheduled\_at (Timestamp)

### GetPendingWakeups [#getpendingwakeups]

Retrieves pending wakeup events for an agent.

Request:

* `agent_id` (string): Agent UUID

Response: List of PendingWakeup (wakeup\_id, user\_id, check\_type, intent, scheduled\_at)

## Streaming Chat [#streaming-chat]

Primary public conversation RPC. Send the agent, user, application context, and message history; the platform handles context assembly and state updates automatically.

### StreamChat [#streamchat]

Streams AI responses for an agent interaction while the platform handles internal memory and state updates behind the scenes.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `session_id` (string): Unique session ID
* `backend_context` (BackendContext): Application state context
* `messages` (CEChatMessage\[]): Conversation messages
* `continuation_token` (string): Resume from previous response (optional)
* `request_type` (string): "chat", "guide", or "outing"
* `capabilities` (string\[]): Unlocked capabilities (optional)
* `language` (string): ISO language code (optional)
* `interaction_role` (string): "owner" or "non\_owner"
* `skill_levels` (`map<string, int32>`): Skill levels (optional)
* `max_turns` (int32): Maximum number of assistant turns per request (optional)

Response: Stream of StreamChatEvent (delta | message\_boundary | complete | side\_effects | error)

StreamChatEvent is a oneof with these event types:

#### StreamChatDelta (delta) [#streamchatdelta-delta]

* `content` (string): Text chunk from the AI
* `message_index` (int32): Index in multi-message response
* `is_follow_up` (bool): Whether this is a follow-up message
* `replacement` (bool): If true, replaces all previous content

#### StreamChatComplete (complete) [#streamchatcomplete-complete]

* `full_content` (string): Complete response text
* `finish_reason` (string): "stop", "length", or "content\_filter"
* `continuation_token` (string): Token for continuing the conversation
* `message_count` (int32): Number of messages in response

#### StreamChatError (error) [#streamchaterror-error]

* `message` (string): Error message
* `code` (string): Error code

## AI Generation [#ai-generation]

Platform-managed AI content generation for bios, goals, personalities, diary entries, and images.

### GenerateBio [#generatebio]

Generates or rewrites an agent's biography using AI based on their personality and context.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `current_bio` (string): Current bio for rewriting (optional)
* `style` (string): Style: casual, formal, poetic, etc. (optional)

Response: bio (string), tone (string), confidence (double)

### GenerateGoals [#generategoals]

Generates personality-driven goals for an agent based on traits, interests, and memories.

Request:

* `agent_id` (string): Agent UUID
* `agent_name` (string): Agent display name
* `big5` (CEBig5Scores): Big5 scores
* `true_interests` (string\[]): Agent interests
* `true_dislikes` (string\[]): Agent dislikes
* `speech_patterns` (string\[]): Speech patterns
* `recent_memories` (CERecentMemory\[]): Recent memories for context
* `current_goals` (CEGoalSummary\[]): Existing goals to avoid duplication
* `max_goals` (int32): Maximum goals to generate
* `model_config` (CEModelConfig): LLM model configuration (optional)
* `custom_context` (`map<string, string>`): Application-specific context (optional)

Response: List of CEGeneratedGoal (type, title, description, priority, related\_traits), reasoning

### GeneratePersonality [#generatepersonality]

Generates speech patterns and interests from a template and Big5 scores.

Request:

* `template_id` (string): Template identifier
* `base_prompt` (string): Base personality prompt
* `big5` (CEBig5Scores): Big5 scores
* `agent_name` (string): Agent name
* `gender` (string): Agent gender

Response: speech\_patterns (string\[]), true\_interests (string\[]), used\_fallback (bool)

### GenerateDiary [#generatediary]

Generates a diary entry from conversation messages and/or application events.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `date` (string): Date in YYYY-MM-DD format
* `agent_name` (string): Agent display name
* `language` (string): Language for generated content
* `messages` (CEDiaryMessage\[]): Conversation messages (role, content, time)
* `trigger_type` (string): daily\_summary, achievement, milestone, breakthrough
* `trigger_context` (CEDiaryTriggerContext): Event trigger context (optional)
* `model` (string): LLM model override (optional)
* `temperature` (double): Temperature override (optional)
* `timezone` (string): Timezone for date handling (optional)

Response: user\_id, date, diary (title, body\_lines, tags), generation\_time\_ms

### GenerateImage [#generateimage]

Generates an image from a text prompt and stores it in cloud storage.

Request:

* `prompt` (string): Image generation prompt
* `negative_prompt` (string): Negative prompt (optional)
* `model` (string): Model to use (optional)
* `provider` (string): Provider to use (optional)
* `output_bucket` (string): GCS bucket for output (optional)
* `output_path` (string): Output path in bucket (optional)
* `cdn_domain` (string): CDN domain for public URL (optional)

Response: success, image\_id, gcs\_uri, public\_url, mime\_type, generation\_time\_ms, error

## Voice & Media [#voice--media]

Voice matching, text-to-speech, voice chat, and reflection capabilities.

### VoiceMatch [#voicematch]

Matches an agent to an appropriate TTS voice based on personality traits.

Request:

* `big5` (CEBig5Scores): Big5 scores for matching
* `preferred_gender` (string): Preferred voice gender (optional)
* `agent_id` (string): Agent UUID (auto-lookup Big5 if provided without big5)

Response: voice\_id, voice\_name, match\_score, reasoning

### TextToSpeech [#texttospeech]

Text-to-speech using Google Gemini voices with emotional context awareness.

Request:

* `text` (string): Text to convert
* `voice_name` (string): Gemini voice name
* `language` (string): Language code (optional)
* `emotional_context` (CEEmotionalContext): Emotional themes and tone (optional)

Response: audio (bytes), content\_type, voice\_name

### VoiceChat [#voicechat]

Single-turn voice chat: transcribes audio, generates AI response, returns TTS audio.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `audio` (bytes): Raw audio data
* `audio_format` (string): Audio format (opus, pcm, wav)
* `voice_name` (string): TTS voice name
* `continuation_token` (string): Resume from previous turn (optional)
* `language` (string): Language code (optional)
* `application_id` (string): Application identifier (optional)

Response: transcript, response (text), audio (bytes), content\_type, continuation\_token, side\_effects\_json

### ListVoices [#listvoices]

Lists available Gemini TTS voices, optionally filtered by gender.

Request:

* `gender` (string): Filter by gender (optional)

Response: List of CEGeminiVoice (name, gender)

### Reflect [#reflect]

Generates an AI reflection on a capability unlock, milestone, or other event.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `reflection_type` (string): "capability\_unlock", "milestone", etc.
* `capability` (string): Capability name
* `capability_source` (string): Source of capability
* `context` (string): Additional context string (optional)
* `new_capabilities_json` (bytes): New capabilities JSON (optional)
* `session_id` (string): Session ID for auto context build (optional)
* `interaction_role` (string): "owner" or "non\_owner" (default: "owner")

Response: success (bool), reflection (string), side\_effects\_json (bytes)

## Streaming Voice Chat [#streaming-voice-chat]

Bidirectional streaming voice chat with server-side VAD (voice activity detection). Client streams audio chunks continuously; server handles speech detection, transcription, AI response, and TTS.

### StreamVoiceChat [#streamvoicechat]

Bidirectional streaming: client sends init + audio chunks, server returns transcripts and TTS audio. No manual stop button needed.

Request:

* `init` (VoiceChatInit): First message: session initialization
* `audio_chunk` (VoiceAudioChunk): Subsequent messages: raw audio data

Response: Stream of events: ready | vad | transcript | response\_delta | audio | turn\_complete | error

#### VoiceChatInit [#voicechatinit]

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `audio_format` (string): "opus", "pcm", "wav" (default: "opus")
* `sample_rate` (int32): Sample rate in Hz (default: 48000 for opus)
* `voice_name` (string): TTS voice name
* `language` (string): Language code (default: "en")
* `application_id` (string): Application identifier
* `continuation_token` (string): Resume from previous session (optional)

#### VoiceAudioChunk [#voiceaudiochunk]

* `audio` (bytes): Raw audio data (e.g., Opus frame)
* `end_of_speech` (bool): Optional client-side VAD hint

Server response events:

#### VoiceStreamReady [#voicestreamready]

* `session_id` (string): Assigned session ID

#### VoiceStreamVAD [#voicestreamvad]

* `speaking` (bool): true = speech started, false = speech ended

#### VoiceStreamTranscript [#voicestreamtranscript]

* `text` (string): Transcript text
* `is_final` (bool): true = final transcript for this utterance

#### VoiceStreamAudio [#voicestreamaudio]

* `audio` (bytes): Audio data chunk
* `content_type` (string): e.g., "audio/opus", "audio/wav"

#### VoiceStreamTurnComplete [#voicestreamturncomplete]

* `continuation_token` (string): Token for continuing the session
* `side_effects_json` (bytes): JSON-serialized AgentSideEffects (optional)

#### VoiceStreamError [#voicestreamerror]

* `message` (string): Error message
* `code` (string): "vad\_error", "stt\_error", "llm\_error", "tts\_error"
* `fatal` (bool): If true, session should be closed

## Analysis & Search [#analysis--search]

AI-powered conversation analysis, summarization, and grounded search.

### AnalyzeConversation [#analyzeconversation]

Analyzes a conversation to extract side effects (personality deltas, habits, memories, etc.).

Request:

* `agent_id` (string): Agent UUID
* `agent_name` (string): Agent display name
* `user_id` (string): User identifier
* `messages` (CEAnalyzeConversationMessage\[]): Messages to analyze (role, content)
* `is_final` (bool): Whether this is the final batch of messages

Response: success, side\_effects\_json (bytes), summary, latency\_ms

### SummarizeConversation [#summarizeconversation]

Generates a concise summary of a conversation with topic extraction.

Request:

* `messages` (CESummarizeConversationMessage\[]): Messages (role, content, time)
* `agent_name` (string): Agent name
* `user_name` (string): User display name
* `max_summary_length` (int32): Max summary length in characters

Response: summary (string), topics (string\[]), message\_count (int)

### GenerateSearchQuery [#generatesearchquery]

Generates an optimized search query from a topic and category for web search.

Request:

* `topic` (string): Topic to search for
* `category` (string): Category for context

Response: query (string), context (string)

### GroundedSearch [#groundedsearch]

Performs grounded web search with multiple queries and returns summarized results with sources.

Request:

* `queries` (string\[]): Search queries
* `context` (string): Context for search relevance
* `agent_name` (string): Agent name for response framing

Response: List of CEGroundedSearchResult (query, summary, sources with title/url/snippet)

## Multi-Agent Dialogue [#multi-agent-dialogue]

Agent-to-agent conversations for outings, dialogues, and multi-agent scenes.

### AgentDialogue [#agentdialogue]

Generates an agent response in a multi-agent dialogue context (e.g., outings between agents).

Request:

* `agent_id` (string): Agent UUID (the responding agent)
* `user_id` (string): User identifier
* `messages` (CEChatMessage\[]): Dialogue messages
* `request_type` (string): "outing", "dialogue", etc.
* `scene_guidance` (string): Scene-specific prompt guidance
* `tool_config_json` (bytes): Tool configuration JSON (optional)
* `session_id` (string): Session ID for auto context build (optional)
* `interaction_role` (string): "owner" or "non\_owner" (default: "owner")

Response: response (string), side\_effects\_json (bytes)

## Application Events [#application-events]

Notify the platform about significant application events. The platform may generate diary entries, update goals, or take other AI actions. Fires OnDiaryGenerated webhook when diary is created.

### TriggerEvent [#triggerevent]

Accepts application events (achievements, milestones, breakthroughs, completions) and triggers AI content generation.

Request:

* `agent_id` (string): Agent UUID
* `user_id` (string): User identifier
* `event_type` (string): "achievement", "milestone", "breakthrough", "level\_up"
* `event_description` (string): Human-readable context for the AI
* `metadata` (`map<string, string>`): Additional context (achievement\_id, level, etc.)
* `language` (string): Language for generated content (default: "en")

Response: accepted (bool), event\_id (string)

## Knowledge Base [#knowledge-base]

Project-scoped knowledge graph. Upload documents or push structured data via the API — the platform extracts entities, builds a graph, and gives agents a `knowledge_search` tool to query it during conversations.

### Documents [#documents]

#### Upload document [#upload-document]

`POST /projects/{projectId}/knowledge/documents`

Upload a document (multipart/form-data with 'file' field, max 50 MB). Returns 202 with document\_id and triggers async extraction.

Parameters:

* `file` (multipart): The document file

Response: document\_id, file\_name, file\_size, checksum, status, gcs\_path

#### List documents [#list-documents]

`GET /projects/{projectId}/knowledge/documents`

List documents. Query: limit (default 50, max 200).

Response: documents\[], total

#### Get document [#get-document]

`GET /projects/{projectId}/knowledge/documents/{docId}`

Get a single document.

Response: KBDocument object

#### Delete document [#delete-document]

`DELETE /projects/{projectId}/knowledge/documents/{docId}`

Delete a document.

Response: 204 No Content

### Facts & Graph [#facts--graph]

#### Insert facts [#insert-facts]

`POST /projects/{projectId}/knowledge/facts`

Insert entities and relationships into the knowledge graph. Resolves against existing nodes, creates/updates with version history.

Parameters:

* `source` (string): Source identifier (default: 'api')
* `facts[]` (array): Entities: entity\_type, label, properties
* `relationships[]` (array): Edges: from\_label, to\_label, edge\_type

Response: processed, created, updated, details\[]

#### List nodes [#list-nodes]

`GET /projects/{projectId}/knowledge/nodes`

List knowledge graph nodes. Query: type (filter), limit (default 100, max 500).

Response: nodes\[], total

#### Get node [#get-node]

`GET /projects/{projectId}/knowledge/nodes/{nodeId}`

Get a node with connected edges. Query: history=true for version history.

Response: node, outgoing\[], incoming\[], history\[]

#### Delete node [#delete-node]

`DELETE /projects/{projectId}/knowledge/nodes/{nodeId}`

Soft-delete a node (sets is\_active=false).

Response: 204 No Content

#### Node history [#node-history]

`GET /projects/{projectId}/knowledge/nodes/{nodeId}/history`

Get version history for a node. Query: limit (default 50, max 200).

Response: history\[], total

### Search [#search]

#### Search knowledge base [#search-knowledge-base]

`GET /projects/{projectId}/knowledge/search`

Full-text search with graph traversal. Query: q (required), limit, history, type, filters (JSON).

Parameters:

* `q` (string): Search query (required)
* `limit` (int): Max results (default 20, max 100)
* `type` (string): Comma-separated entity types to filter
* `filters` (JSON string): Property filter object
* `history` (bool): Include version history

Response: query, results\[] (with related nodes), total

### Schemas [#schemas]

#### Create schema [#create-schema]

`POST /projects/{projectId}/knowledge/schemas`

Create an entity type schema with fields and optional similarity config.

Parameters:

* `entity_type` (string): Entity type name (required)
* `fields[]` (array): Field definitions: name, type, required
* `description` (string): Schema description
* `similarity_config` (object): match\_fields\[], threshold

Response: KBEntitySchema object

#### List schemas [#list-schemas]

`GET /projects/{projectId}/knowledge/schemas`

List entity schemas for a project.

Response: schemas\[], total

#### Update schema [#update-schema]

`PUT /projects/{projectId}/knowledge/schemas/{schemaId}`

Update an entity schema.

Parameters:

* `entity_type` (string): Updated entity type name
* `fields[]` (array): Updated field definitions

Response: KBEntitySchema object

#### Delete schema [#delete-schema]

`DELETE /projects/{projectId}/knowledge/schemas/{schemaId}`

Delete an entity schema.

Response: 204 No Content

### Stats [#stats]

#### Get KB stats [#get-kb-stats]

`GET /projects/{projectId}/knowledge/stats`

Get knowledge base statistics (document counts, node counts, edge count, extraction tokens).

Response: documents \{total, indexed, pending, failed}, nodes \{total, active}, edges, extraction\_tokens

### Analytics [#analytics]

#### Create analytics rule [#create-analytics-rule]

`POST /projects/{projectId}/knowledge/analytics/rules`

Create an analytics rule (recommendation or trend).

Parameters:

* `rule_type` (string): 'recommendation' or 'trend'
* `name` (string): Rule name
* `config` (object): Rule configuration
* `enabled` (bool): Whether the rule is active

Response: KBAnalyticsRule object

#### Get recommendations [#get-recommendations]

`GET /projects/{projectId}/knowledge/analytics/recommendations`

Get recommendations. Query: rule\_id, source\_id (both required), limit.

Response: recommendations\[], total

#### Get trends [#get-trends]

`GET /projects/{projectId}/knowledge/analytics/trends`

Get trend aggregations. Query: node\_id (required).

Response: trends\[], total

#### Record feedback [#record-feedback]

`POST /projects/{projectId}/knowledge/analytics/feedback`

Record recommendation feedback (shown/converted).

Parameters:

* `source_node_id` (string): Source node ID
* `target_node_id` (string): Target node ID
* `rule_id` (string): Analytics rule ID
* `converted` (bool): Whether the user converted
* `score_at_time` (float): Score when recommendation was shown

Response: status: 'recorded'

## User Priming [#user-priming]

Pre-load user metadata and content so AI agents already "know" users from their first conversation. Metadata (name, company, title) becomes instant facts; content blocks (text, chat transcripts) are processed asynchronously via LLM extraction.

### Prime a User [#prime-a-user]

#### Prime user [#prime-user]

`POST /agents/{agentId}/users/{userId}/prime`

Prime a user with metadata and content. Returns 202 with a job ID; LLM extraction of content runs asynchronously.

Parameters:

* `display_name` (string): User's display name
* `metadata` (object): company, title, email, phone, custom (map)
* `content[]` (array): Content blocks: type ('text', 'chat\_transcript'), body
* `source` (string): Source identifier (e.g., 'crm', 'linkedin')

Response: job\_id, status ('queued'), facts\_created

#### Get priming status [#get-priming-status]

`GET /agents/{agentId}/users/{userId}/prime/{jobId}`

Get the status of a priming job.

Response: ImportJob object (job\_id, status, facts\_created, error\_message, etc.)

### Content [#content]

#### Add content [#add-content]

`POST /agents/{agentId}/users/{userId}/content`

Add content blocks for async LLM extraction (e.g., append chat transcripts after priming).

Parameters:

* `content[]` (array): Content blocks: type, body
* `source` (string): Source identifier

Response: job\_id, status ('queued')

### Metadata [#metadata]

#### Get user metadata [#get-user-metadata]

`GET /agents/{agentId}/users/{userId}/metadata`

Get priming metadata for a user.

Response: UserPrimingMetadata object

#### Update user metadata [#update-user-metadata]

`PATCH /agents/{agentId}/users/{userId}/metadata`

Partially update priming metadata. New facts are auto-generated from updated fields.

Parameters:

* `display_name` (string): Updated name
* `company` (string): Updated company
* `title` (string): Updated title
* `email` (string): Updated email
* `phone` (string): Updated phone
* `custom` (map): Custom key-value pairs (merged)

Response: metadata (updated), facts\_created

### Batch Import [#batch-import]

#### Batch import users [#batch-import-users]

`POST /agents/{agentId}/users/import`

Import multiple users with metadata and content in a single request. Metadata facts are created synchronously; content extraction runs async.

Parameters:

* `users[]` (array): Array of \{user\_id, display\_name, metadata, content\[]}
* `source` (string): Source identifier

Response: job\_id, status ('queued'), total\_users, facts\_created

#### Get import status [#get-import-status]

`GET /agents/{agentId}/users/import/{jobId}`

Get the status of a batch import job.

Response: ImportJob object

#### List import jobs [#list-import-jobs]

`GET /agents/{agentId}/users/imports`

List recent import jobs for an agent. Query: limit (default 20).

Response: jobs\[], count

## Shared Types [#shared-types]

### BackendContext [#backendcontext]

* `custom_fields` (`map<string, string>`): Arbitrary application-specific key-value pairs passed through to prompts
* `state_json` (bytes): Optional structured state as JSON (pass-through to prompts)

### CEBig5Scores [#cebig5scores]

* `openness` (double): Openness to experience (0.0-1.0)
* `conscientiousness` (double): Organization and discipline (0.0-1.0)
* `extraversion` (double): Social energy and enthusiasm (0.0-1.0)
* `agreeableness` (double): Warmth and cooperation (0.0-1.0)
* `neuroticism` (double): Emotional sensitivity (0.0-1.0)
* `confidence` (double): Assessment confidence (0.0-1.0)

### BFASFacets [#bfasfacets]

Derived from Big5 scores. Read-only in personality profile responses.

* `intellect` (double): Openness facet — intellectual curiosity (0.0-1.0)
* `aesthetic` (double): Openness facet — aesthetic sensitivity (0.0-1.0)
* `industriousness` (double): Conscientiousness facet — self-discipline (0.0-1.0)
* `orderliness` (double): Conscientiousness facet — preference for order (0.0-1.0)
* `enthusiasm` (double): Extraversion facet — positive emotion (0.0-1.0)
* `assertiveness` (double): Extraversion facet — social dominance (0.0-1.0)
* `compassion` (double): Agreeableness facet — empathy (0.0-1.0)
* `politeness` (double): Agreeableness facet — deference to others (0.0-1.0)
* `withdrawal` (double): Neuroticism facet — tendency to withdraw (0.0-1.0)
* `volatility` (double): Neuroticism facet — emotional instability (0.0-1.0)

### BehavioralTraits [#behavioraltraits]

Derived from personality. Read-only in personality profile responses.

* `response_length` (string): How verbose or concise the agent tends to be
* `question_frequency` (string): How often the agent asks follow-up questions
* `empathy_style` (string): Approach to emotional support (validating, solution-oriented, etc.)
* `conflict_approach` (string): How the agent handles disagreements (accommodating, direct, mediating, etc.)

### MoodState [#moodstate]

* `valence` (double): Pleasure/displeasure spectrum (0-100)
* `arousal` (double): Activation/energy level (0-100)
* `tension` (double): Stress/calmness state (0-100)
* `affiliation` (double): Social warmth/closeness (0-100)

### CEChatMessage [#cechatmessage]

* `role` (string): "user" or "assistant"
* `content` (string): Message text
* `timestamp` (Timestamp): When the message was sent

### MemoryCandidate [#memorycandidate]

* `content` (string): Memory content text
* `fact_type` (string): preference, commitment, fact, experience, correction
* `importance` (double): Importance score (0.0-1.0)
* `entities` (string\[]): Related entities

### Habit [#habit]

* `name` (string): Habit name
* `category` (string): Habit category
* `strength` (double): Current strength (0.0-1.0)
* `last_observed` (Timestamp): Last observation time
* `is_formed` (bool): Whether the habit is fully formed

### CEGoal [#cegoal]

* `id` (string): Goal identifier
* `description` (string): Goal description
* `status` (string): "active", "completed", "abandoned"
* `priority` (string): Priority level
* `related_traits` (string\[]): Related personality traits
* `created_at` (Timestamp): When the goal was created

### Interest [#interest]

* `topic` (string): Interest topic
* `category` (string): Interest category
* `confidence` (double): Detection confidence (0.0-1.0)
* `discovered_at` (Timestamp): When the interest was discovered
* `research_status` (string): "pending" or "researched"

### CEModelConfig [#cemodelconfig]

* `provider` (string): LLM provider name
* `model` (string): Model identifier
* `temperature` (double): Sampling temperature
* `max_tokens` (int32): Maximum tokens to generate

### ProactiveMessage [#proactivemessage]

* `message_id` (string): Unique message identifier
* `agent_id` (string): Agent that generated the message
* `user_id` (string): Target user
* `wakeup_id` (string): Associated wakeup event
* `check_type` (string): Type of check (check\_in, follow\_up, mood\_driven)
* `intent` (string): Why the agent wants to reach out
* `generated_message` (string): The actual message text
* `status` (string): pending, consumed, expired, failed\_generation
* `created_at` (Timestamp): When generated


---

# Setting up and running your workspace

Source: https://sonz.ai/docs/en/workspace/admin-it-guide

> For IT administrators, and for Sonzai forward-deployed engineers acting on your behalf.



This guide explains what your organization's Sonzai workspace is, how it gets configured, who can touch what, and how to explain the system to your staff.

## What you have [#what-you-have]

Sonzai provisions a dedicated tenant for your organization. That means:

* Your own workspace address (for example, `yourcompany.sonz.ai`).
* Your own data: conversations, client records, knowledge, and configuration are scoped to your tenant and are never shared with, or derived into, anyone else's.
* A configuration studio at `platform.sonz.ai` where authorized people shape what your team sees.
* A runtime your salespeople actually use: messaging channels (WhatsApp Business, Messenger) plus a simple web workspace.

There is nothing to install or host. Infrastructure, deployment, and monitoring are handled by Sonzai operators.

## Who does what [#who-does-what]

Three kinds of people interact with the system, with strictly separated access:

1. **Your salespeople** use the runtime only: their secretary in the messaging channel, and the web workspace with their own prospects, conversations, advice, and outcomes. They never see integration credentials, agent configuration, or administration screens.
2. **You (IT administrator), or a Sonzai FDE working with you,** use the configuration studio. You can do everything listed in this guide. You cannot reach Sonzai's operator console; direct navigation to it returns access denied.
3. **Sonzai operators** provision tenants, manage deployment and licensing, and monitor platform health from a separate operator console. When an FDE works inside your tenant on your behalf, the session is delegated: it is time-limited, tenant-bound, audited, and shows a visible banner naming the operator, the tenant, and the reason. You can see these sessions in your audit view.

## Signing in and adding your team [#signing-in-and-adding-your-team]

* Administrators sign in at `platform.sonz.ai` with your organization's single sign-on or a managed account.
* From **Team & governance** you can invite teammates, assign roles (administrator or member), reset passwords, and disable accounts.
* Salespeople get runtime accounts bound to their verified channel identity: each person messages the corporate bot from their own WhatsApp or Messenger identity, and the system binds that identity to exactly one advisor identity and record owner. One corporate number serves the whole team; nobody shares conversations or memory.

## The configuration studio [#the-configuration-studio]

The studio keeps to five destinations. Everything you can configure lives under one of them:

1. **Home.** Setup progress, runtime preview, health, and recent changes. The setup path is guided: choose the experience, apply branding and terminology, add knowledge, configure the copilot, connect a channel, invite your people, define outcomes, preview as a salesperson, go live. Every step shows its state and the next action.
2. **Experience.** Brand, terminology, which modules appear, forms and qualification fields, and a live preview. The platform carries more modules than any one team needs (CRM and pipeline, lead intake and qualification, conversations, knowledge, analytics, and others); you choose what your people see, what it is called, and in what order.
3. **Intelligence.** Knowledge and playbooks. Upload approved material (drag and drop), connect governed sources (website or sitemap, SharePoint, Google Drive, or an API/warehouse source), and manage the content lifecycle: draft, needs review, approved, published. Runtime answers cite the effective approved source, and public research can never create approved product or policy facts on its own.
4. **Connections.** WhatsApp Business and Messenger channel setup, CRM and external source connections, field mappings, and sync health. Credentials are write-only: once entered, secrets are never displayed back, and they never appear in anything a browser can read.
5. **Team & governance.** Users, roles, delegated access, approvals, audit, and releases.

## Data and governance facts to relay to your staff [#data-and-governance-facts-to-relay-to-your-staff]

* Salespeople approve their own records; managers see aggregates, not raw notes, unless a named, logged, break-glass access is used for support or compliance.
* Each salesperson's conversations and memory are private to them; assignment rules control who sees which prospects.
* Your organization owns its data and everything derived from it. Nothing from your tenant trains models for anyone else.
* Consent handling, retention, and deletion behavior are configured with your data-protection officer before live client data flows.

## Getting help [#getting-help]

Your Sonzai FDE is the first line for configuration questions, with a named backup engineer. Operational issues are monitored by Sonzai; report anything you notice to your FDE or [hello@sonz.ai](mailto:hello@sonz.ai).


---

# What you bought, and how to see it working

Source: https://sonz.ai/docs/en/workspace/buyer-overview

> For managers, executives, and procurement.



You are not buying a chatbot. You are buying a system that turns your sales force's daily conversations into records, follow-through, and organizational intelligence your company owns. This page explains what runs, what you can see, and how it is governed.

## The one-paragraph version [#the-one-paragraph-version]

Every salesperson gets an AI secretary in the messaging app they already use. After a client meeting they talk to it the way they would text a colleague. The system structures what they said into a client record, schedules the follow-up, and answers product questions from your own approved documentation. Each approved record also compounds into an asset your organization owns: client histories, working playbooks from your best people, and the data foundation for lead prioritisation and next-best-action.

## What your people see [#what-your-people-see]

* **Salespeople** work in WhatsApp or Messenger, plus a deliberately simple web workspace with five areas: today's priorities, their prospects and clients, their conversations, advice, and outcomes. No CRM forms, no admin screens.
* **Your IT team** (or a Sonzai engineer working with them under audited, time-limited access) configures everything in a studio at platform.sonz.ai: branding, which modules appear, knowledge, channels, and team access.
* **You** see the aggregate view: activation, capture volume, follow-up completion, and pipeline state, reported against the baselines agreed before launch.

## What you can measure [#what-you-can-measure]

The system is instrumented for the questions a sales leader actually asks:

* How many of our people used it this week, and is that growing?
* How many client conversations became records instead of disappearing?
* How fast does a meeting turn into a logged follow-up, and do follow-ups happen on time?
* What is moving in the pipeline, and which recommendations get accepted?

Pilots are measured against a baseline week and pass/fail thresholds agreed in writing before launch, so the readout is evidence, not anecdotes.

## How it is governed [#how-it-is-governed]

* **Your data is yours.** Raw notes, records, documents, outcomes, and everything derived from them belong to your organization, are exportable in open formats, and are never used for another customer or to train shared models.
* **Salespeople trust it because the rules are written down.** They approve every record; managers see aggregates with minimum group sizes; nothing captured feeds individual performance evaluation during a pilot; raw-note access is named, logged, break-glass only.
* **Privacy is designed before live data.** Lawful basis, consent, retention, and deletion are worked through with your data-protection officer up front. The system never records live client conversations; it structures what your salesperson dictates afterward.
* **Humans decide.** The system drafts, structures, reminds, and recommends. It does not make underwriting, eligibility, pricing, or any adverse client decision.
* **Access is separated and audited.** Salespeople cannot reach administration. Your IT cannot reach Sonzai's operator console. When a Sonzai engineer works inside your tenant, the session is time-limited, tenant-bound, visibly bannered, and audited.

## Procurement facts [#procurement-facts]

* **Vendor:** Sonzai Labs Pte. Ltd. (Singapore). Applied AI company; the platform is the Sonzai Mind Layer; delivery is by forward-deployed engineers from Singapore and Manila.
* **Deployment:** a dedicated tenant provisioned by Sonzai, on your own workspace address. Nothing for your team to host. Dedicated placement options exist for organizations that require them.
* **Model usage:** your own provider keys are supported; provider charges are paid by you directly to the provider. Sonzai does not resell compute.
* **Commercials:** engagements start with a fixed-fee design sprint and a gated pilot, then a production subscription (an annual platform license plus per-seat pricing for monthly active users, so inactive seats cost nothing). Figures live in your pricing schedule.
* **Exit:** full export in open formats within 30 days of request, and deletion with a certificate, including backup expiry.

## How an engagement runs [#how-an-engagement-runs]

1. **Design sprint (weeks, not months).** Channel and privacy architecture settled with your DPO and IT, a working prototype in the hands of a friendly group, and a budget-ready readout.
2. **Pilot (12 live weeks).** A named cohort, measured against the baseline, with a written go or no-go gate before it starts.
3. **Production.** Rollout in tranches, with the intelligence layer (prioritisation, next-best-action, after-sales triggers) switching on as your outcome data supports it.

Questions or a walkthrough of the dashboard on your own data: [hello@sonz.ai](mailto:hello@sonz.ai).


---

# Workspace Guides

Source: https://sonz.ai/docs/en/workspace

> Guides for teams running a Sonzai workspace, written for three audiences.



These guides are for organizations running a Sonzai workspace (a dedicated tenant with a sales runtime and a configuration studio), rather than for developers integrating the API.

Pick the guide for your role:

* **[IT administrators and FDEs](/docs/en/workspace/admin-it-guide)**: set up, configure, and govern the workspace, and explain it to staff.
* **[Managers, executives, and procurement](/docs/en/workspace/buyer-overview)**: what you bought, what you can measure, and how it is governed.
* **[Salespeople and advisors](/docs/en/workspace/salesperson-guide)**: how to use your AI secretary day to day.


---

# Your AI secretary

Source: https://sonz.ai/docs/en/workspace/salesperson-guide

> For salespeople, insurance advisors, real estate agents, and relationship managers.



You have a secretary now. It lives in the messaging app you already use, it works at 10pm, and it never forgets what a client told you. This page shows you how to use it. There is nothing to install and no form to fill in, ever.

## The habit that makes everything work [#the-habit-that-makes-everything-work]

After a client conversation, tell your secretary what happened. Voice note or text, in whatever language you actually speak. Like this:

> "Met Maria, 34, one kid starting school in two years, thinking about an education plan, budget maybe 8 to 10K a month, she wants to compare with what another company offered her. Follow up Thursday."

That is the entire job. Everything else flows from it.

## What happens next [#what-happens-next]

Within moments, your secretary replies with a structured client card: who Maria is, what she needs, her budget, and the Thursday follow-up already scheduled. If you missed something important, it asks you one question.

**Nothing is saved until you approve it.** Tap approve and the record is yours. Spot an error? Correct it first. Your records stay yours to edit or delete.

## What your secretary does for you [#what-your-secretary-does-for-you]

* **Remembers everyone.** "What did Maria say about her son's tuition?" gets you the answer, from your own conversations, in seconds.
* **Chases the follow-ups.** Thursday 8am, the reminder arrives with the full story replayed, so you walk in prepared. No more notebook archaeology before a meeting.
* **Knows the products.** Ask which of your company's plans fits a 34-year-old with one kid, and it answers from your company's official documentation, citing the source. If the documents do not cover it, it says so instead of guessing.
* **Drafts, so you polish.** Follow-up messages and recommendations arrive as drafts. You edit and you send. Nothing goes to a client without you.
* **Keeps score with you.** Your web workspace shows today's priorities, your prospects and clients, your conversations, advice, and your outcomes. Five things, nothing else.

## What it does not do [#what-it-does-not-do]

* It does not record your meetings or calls. It structures what you tell it afterward.
* It does not show your raw notes to your manager. Managers see team-level numbers, not your notebook. Access to raw records is restricted, named, and logged.
* It does not rate you. During a pilot, nothing you capture is used for performance evaluation, compensation, or taking leads away from you.
* It does not send anything to a client by itself.

## Why bother [#why-bother]

Two selfish reasons.

First, speed: the admin you used to do at midnight (writing up notes, setting reminders, digging for what a client said three weeks ago) takes seconds now, and your follow-ups stop slipping.

Second, your senior colleagues' experience, on tap. The best answers to "how do I handle this situation" get curated into shared playbooks (with client details removed), so you get guidance at 10pm even when your manager is asleep.

## Getting started [#getting-started]

1. Your company adds you. You get a welcome message on the corporate WhatsApp or Messenger bot.
2. Message it from your own number. Your identity is bound to your own private space; nobody else sees your conversations.
3. After your next client meeting, send it a voice note. That is it. The more you tell it, the more useful it gets.

Stuck or something looks wrong? Tell your team lead or message the secretary itself with "help".


---

# From Character.AI / Replika

Source: https://sonz.ai/docs/en/guides/migrating/character-ai

> Migrate companion character chat exports from Character.AI, Replika, Chai, and similar companion apps into Sonzai. One character becomes one Sonzai agent; one user's conversation history becomes one Sonzai user.



## What you're migrating [#what-youre-migrating]

Character.AI, Replika, Chai, and similar companion apps don't expose public APIs for chat export. They do offer **personal data download** flows that return a zipped archive of your conversations, typically as JSON. The exact shape varies, but the logical units are the same:

| Companion app                     | Sonzai                                                                            |
| --------------------------------- | --------------------------------------------------------------------------------- |
| Character / bot                   | Sonzai [agent](/docs/api/agents) — create it separately, don't migrate it in here |
| Conversation (with one character) | One `chat_transcript` block on the owning user                                    |
| User (of the companion app)       | Sonzai `user_id`                                                                  |
| Character persona / greeting      | Agent personality + bio — configure in Sonzai, not imported                       |

**This is a per-user migration**, not a multi-tenant one. If you're a developer moving users off a companion product you built, you usually have your own user database and can do a batch import. If you're an individual moving your own chats into a Sonzai-powered app, a single-user prime is simpler.

<Callout type="warn" title="Terms of Service">
  Check the source platform's ToS before exporting and reusing chat content at scale, especially on Character.AI and Replika where user-generated character scripts may be covered by the platform's terms. The code below assumes you have the right to move the data.
</Callout>

## 1. Export from the companion app [#1-export-from-the-companion-app]

For most of these platforms you request a data download from settings and receive a zipped archive by email, usually within a few hours. Once unzipped, you're looking at one or more JSON files with a shape like:

```json
[
  {
    "character_id": "luna",
    "conversation_id": "conv_abc",
    "created_at": "2025-11-20T09:12:00Z",
    "messages": [
      { "role": "user",       "content": "Hey Luna",     "created_at": "..." },
      { "role": "character",  "content": "Hi! Missed you.", "created_at": "..." }
    ]
  }
]
```

Different exports use different field names (`role` vs `is_human`, `text` vs `content`, `bot_id` vs `character_id`). Normalise to the shape above before running the import.

## 2. Map to Sonzai [#2-map-to-sonzai]

For a single-user import (the most common case for companion apps):

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import json, os
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_luna&#x22;   # the Sonzai agent that replaces the companion character
USER_ID  = &#x22;me&#x22;           # the individual migrating their own chats

def build_transcript(messages):
  lines = []
  for m in messages:
      role = &#x22;User&#x22; if m[&#x22;role&#x22;] == &#x22;user&#x22; else &#x22;Agent&#x22;
      lines.append(f&#x22;{role}: {m['content']}&#x22;)
  return &#x22;\\n&#x22;.join(lines)

def migrate_character_export(export_path: str, character_id: str):
  with open(export_path) as f:
      convos = json.load(f)

  # Only conversations with the character we're migrating to this Sonzai agent
  mine = [c for c in convos if c[&#x22;character_id&#x22;] == character_id]
  mine.sort(key=lambda c: c[&#x22;created_at&#x22;])

  content = []
  for c in mine:
      transcript = build_transcript(c[&#x22;messages&#x22;])
      content.append({
          &#x22;type&#x22;: &#x22;chat_transcript&#x22;,
          &#x22;body&#x22;: f&#x22;[conversation {c['conversation_id']} @ {c['created_at']}]\\n{transcript}&#x22;,
      })

  return sonzai.agents.priming.prime_user(
      AGENT_ID,
      USER_ID,
      source=&#x22;character_ai&#x22;,  # or &#x22;replika&#x22;, &#x22;chai&#x22;, etc.
      content=content,
  )`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import fs from &#x22;fs&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_luna&#x22;; // the Sonzai agent that replaces the companion character
const USER_ID  = &#x22;me&#x22;;         // the individual migrating their own chats

interface CharacterMessage { role: &#x22;user&#x22; | &#x22;assistant&#x22;; content: string }
interface CharacterConversation {
conversation_id: string;
character_id:    string;
created_at:      string;
messages:        CharacterMessage[];
}

function buildTranscript(messages: CharacterMessage[]): string {
return messages
  .map((m) => \`\${m.role === &#x22;user&#x22; ? &#x22;User&#x22; : &#x22;Agent&#x22;}: \${m.content}\`)
  .join(&#x22;\\n&#x22;);
}

export async function migrateCharacterExport(exportPath: string, characterId: string) {
const convos: CharacterConversation[] = JSON.parse(fs.readFileSync(exportPath, &#x22;utf8&#x22;));
const mine = convos
  .filter((c) => c.character_id === characterId)
  .sort((a, b) => a.created_at.localeCompare(b.created_at));

const content = mine.map((c) => ({
  type: &#x22;chat_transcript&#x22;,
  body: \`[conversation \${c.conversation_id} @ \${c.created_at}]\\n\${buildTranscript(c.messages)}\`,
}));

return sonzai.agents.priming.primeUser(AGENT_ID, USER_ID, {
  source: &#x22;character_ai&#x22;, // or &#x22;replika&#x22;, &#x22;chai&#x22;, etc.
  content,
});
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;sort&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const (
  AgentID = &#x22;agent_luna&#x22; // the Sonzai agent that replaces the companion character
  UserID  = &#x22;me&#x22;         // the individual migrating their own chats
)

type characterMessage struct {
  Role, Content string
}
type characterConversation struct {
  ConversationID string             \`json:&#x22;conversation_id&#x22;\`
  CharacterID    string             \`json:&#x22;character_id&#x22;\`
  CreatedAt      string             \`json:&#x22;created_at&#x22;\`
  Messages       []characterMessage \`json:&#x22;messages&#x22;\`
}

func buildTranscript(msgs []characterMessage) string {
  out := &#x22;&#x22;
  for _, m := range msgs {
      role := &#x22;Agent&#x22;
      if m.Role == &#x22;user&#x22; {
          role = &#x22;User&#x22;
      }
      out += role + &#x22;: &#x22; + m.Content + &#x22;\\n&#x22;
  }
  return out
}

func migrateCharacterExport(ctx context.Context, client *sonzai.Client, exportPath, characterID string) (*sonzai.PrimeUserResponse, error) {
  raw, err := os.ReadFile(exportPath)
  if err != nil {
      return nil, err
  }
  var convos []characterConversation
  if err := json.Unmarshal(raw, &convos); err != nil {
      return nil, err
  }
  mine := convos[:0]
  for _, c := range convos {
      if c.CharacterID == characterID {
          mine = append(mine, c)
      }
  }
  sort.Slice(mine, func(i, j int) bool { return mine[i].CreatedAt < mine[j].CreatedAt })

  content := make([]sonzai.PrimeContentBlock, 0, len(mine))
  for _, c := range mine {
      content = append(content, sonzai.PrimeContentBlock{
          Type: &#x22;chat_transcript&#x22;,
          Body: fmt.Sprintf(&#x22;[conversation %s @ %s]\\n%s&#x22;, c.ConversationID, c.CreatedAt, buildTranscript(c.Messages)),
      })
  }

  return client.Priming.PrimeUser(ctx, AgentID, UserID, sonzai.PrimeUserOptions{
      Source:  &#x22;character_ai&#x22;, // or &#x22;replika&#x22;, &#x22;chai&#x22;, etc.
      Content: content,
  })
}`,
  },
]"
/>

For a multi-user migration (you run the companion platform), pack each user into a `batch_import` entry the same way, using the platform's stable user ID as `user_id`.

## 3. Import and verify [#3-import-and-verify]

```bash
curl -s https://api.sonz.ai/api/v1/agents/agent_luna/users/me/prime/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.status,.facts_stored'

# See what Sonzai extracted
curl -s "https://api.sonz.ai/api/v1/agents/agent_luna/memory/facts?user_id=me&limit=50" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.facts[].content'
```

## What moves, and what doesn't [#what-moves-and-what-doesnt]

**Moves:** your chat history, user identity (via `user_id`), and any user metadata you care to pass in (`email`, `display_name`, `custom` fields).

**Doesn't move:**

* **Character persona / backstory.** Rebuild this on the Sonzai agent via [personality config](/docs/personality). Companion apps often bundle personality into freeform scripts; Sonzai uses Big Five personality + an explicit bio.
* **Character greetings / scenarios.** Configure at agent level, not per user.
* **Character voice** (Replika/Character.AI voice models). Sonzai ships its own TTS — see [Voice](/docs/voice).
* **Media attachments** (images, voice notes, selfies). The import endpoints take text only. If media matters, store the URLs as `text` blocks (`"Mia shared a photo of her hike: https://..."`) so the extractor at least records the reference.

## Platform-specific notes [#platform-specific-notes]

* **Character.AI** exports group by character; filter to the character you're migrating.
* **Replika** exports tend to have one long-running conversation per user with no character selection — use the whole history.
* **Chai** exports are conversation-centric; treat each conversation as its own transcript block.
* **Janitor AI / others** — if the export is raw JSON with messages, the shape-normalisation step is all you need.

## What's next [#whats-next]

* [Personality](/docs/personality) — rebuilding the character in Sonzai.
* [Voice](/docs/voice) — setting up TTS for the migrated character.
* [Custom JSON](/docs/migrating/custom-json) — if the export format doesn't match the examples here.


---

# From CRM / CSV

Source: https://sonz.ai/docs/en/guides/migrating/crm-csv

> Migrate structured tabular data — Salesforce and HubSpot contacts, product ownership tables, subscription rosters — into Sonzai. Two patterns, one for contact rosters, one for inventory-style facts.



## Two CSV patterns, two endpoints [#two-csv-patterns-two-endpoints]

Structured data in Sonzai splits into two very different import shapes:

1. **Contact roster** — one row per person, with attributes like company, title, email. You want one Sonzai **user*&#x2A; per row. → Use &#x2A;*`batch_import`** with metadata fields.
2. **Inventory table** — many rows per person, each describing something the user owns, bought, subscribes to, or holds. You want many **facts*&#x2A; per user. → Use &#x2A;*`structured_import`** on `prime_user`.

They're often used together: import contacts first with `batch_import`, then enrich each contact with their inventory via `structured_import`.

## Pattern 1: Contact roster → users [#pattern-1-contact-roster--users]

Salesforce / HubSpot / Pipedrive / custom CRM exports look like this:

```csv
contact_id,first_name,last_name,email,company,title,phone,last_contacted
c_001,Mia,Tanaka,mia@acme.com,Acme,Platform Lead,+81-90-...,2025-11-02
c_002,Ren,Park,ren@beta.io,Beta Labs,CTO,+82-10-...,2025-10-20
```

Map each row to a `batchImportUser` and send in chunks:

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import csv, os
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def load_contacts(path: str):
  with open(path) as f:
      return list(csv.DictReader(f))

def to_sonzai_user(row):
  return {
      &#x22;user_id&#x22;: row[&#x22;contact_id&#x22;],
      &#x22;display_name&#x22;: f&#x22;{row['first_name']} {row['last_name']}&#x22;.strip(),
      &#x22;metadata&#x22;: {
          &#x22;company&#x22;: row.get(&#x22;company&#x22;) or None,
          &#x22;title&#x22;:   row.get(&#x22;title&#x22;) or None,
          &#x22;email&#x22;:   row.get(&#x22;email&#x22;) or None,
          &#x22;phone&#x22;:   row.get(&#x22;phone&#x22;) or None,
          &#x22;custom&#x22;: {
              &#x22;last_contacted&#x22;: row.get(&#x22;last_contacted&#x22;) or &#x22;&#x22;,
          },
      },
  }

def migrate(path: str):
  rows = load_contacts(path)
  for i in range(0, len(rows), 200):
      users = [to_sonzai_user(r) for r in rows[i : i + 200]]
      job = sonzai.agents.priming.batch_import(
          AGENT_ID, source=&#x22;crm&#x22;, users=users,
      )
      print(f&#x22;batch {i//200}: {job.total_users} users, &#x22;
            f&#x22;{job.facts_created} facts from metadata&#x22;)`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import fs from &#x22;fs&#x22;;
import { parse } from &#x22;csv-parse/sync&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

function toSonzaiUser(row: Record<string, string>) {
return {
  user_id: row.contact_id,
  display_name: \`\${row.first_name} \${row.last_name}\`.trim(),
  metadata: {
    company: row.company || undefined,
    title:   row.title   || undefined,
    email:   row.email   || undefined,
    phone:   row.phone   || undefined,
    custom: { last_contacted: row.last_contacted || &#x22;&#x22; },
  },
};
}

async function migrate(path: string) {
const rows: Record<string, string>[] =
  parse(fs.readFileSync(path), { columns: true, skip_empty_lines: true });
for (let i = 0; i < rows.length; i += 200) {
  const users = rows.slice(i, i + 200).map(toSonzaiUser);
  const job = await sonzai.agents.priming.batchImport(AGENT_ID, {
    source: &#x22;crm&#x22;,
    users,
  });
  console.log(\`batch \${i/200}: \${job.total_users} users, \${job.facts_created} facts from metadata\`);
}
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;encoding/csv&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

func loadContacts(path string) ([]map[string]string, error) {
  f, err := os.Open(path)
  if err != nil {
      return nil, err
  }
  defer f.Close()
  r := csv.NewReader(f)
  rows, err := r.ReadAll()
  if err != nil || len(rows) == 0 {
      return nil, err
  }
  header := rows[0]
  out := make([]map[string]string, 0, len(rows)-1)
  for _, row := range rows[1:] {
      rec := make(map[string]string, len(header))
      for i, h := range header {
          if i < len(row) {
              rec[h] = row[i]
          }
      }
      out = append(out, rec)
  }
  return out, nil
}

func toSonzaiUser(row map[string]string) sonzai.BatchImportUser {
  return sonzai.BatchImportUser{
      UserID:      row[&#x22;contact_id&#x22;],
      DisplayName: (row[&#x22;first_name&#x22;] + &#x22; &#x22; + row[&#x22;last_name&#x22;]),
      Metadata: &sonzai.PrimeUserMetadata{
          Company: row[&#x22;company&#x22;],
          Title:   row[&#x22;title&#x22;],
          Email:   row[&#x22;email&#x22;],
          Phone:   row[&#x22;phone&#x22;],
          Custom:  map[string]string{&#x22;last_contacted&#x22;: row[&#x22;last_contacted&#x22;]},
      },
  }
}

func migrate(ctx context.Context, client *sonzai.Client, path string) error {
  rows, err := loadContacts(path)
  if err != nil {
      return err
  }
  for i := 0; i < len(rows); i += 200 {
      end := i + 200
      if end > len(rows) {
          end = len(rows)
      }
      users := make([]sonzai.BatchImportUser, 0, end-i)
      for _, r := range rows[i:end] {
          users = append(users, toSonzaiUser(r))
      }
      job, err := client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
          Source: &#x22;crm&#x22;,
          Users:  users,
      })
      if err != nil {
          return err
      }
      fmt.Printf(&#x22;batch %d: %d users, %d facts from metadata\\n&#x22;, i/200, job.TotalUsers, job.FactsCreated)
  }
  return nil
}`,
  },
]"
/>

Because the metadata fields (`company`, `title`, `email`, `phone`) are first-class, Sonzai generates facts from them synchronously — the response's `facts_created` count is real and non-zero even without any content blocks.

## Pattern 2: Inventory table → structured facts [#pattern-2-inventory-table--structured-facts]

For a table like "which products does each customer own", use `structured_import`. Each row becomes one fact shaped as `User owns <label>` with all the row's columns attached as structured metadata.

Sample CSV:

```csv
customer_id,product_sku,product_name,quantity,purchase_date,is_active
c_001,SKU-001,Hiking Backpack,1,2025-09-01,true
c_001,SKU-045,Water Bottle,2,2025-10-12,true
c_002,SKU-001,Hiking Backpack,1,2025-08-20,false
```

You call `prime_user` once per customer, passing that customer's rows as a CSV string plus a column mapping.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import fs from &#x22;fs&#x22;;
import { parse, stringify } from &#x22;csv-parse/sync&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

async function importInventory(path: string) {
const allRows: Record<string, string>[] =
  parse(fs.readFileSync(path), { columns: true, skip_empty_lines: true });

// Group by customer
const byCustomer = new Map<string, Record<string, string>[]>();
for (const r of allRows) {
  if (!byCustomer.has(r.customer_id)) byCustomer.set(r.customer_id, []);
  byCustomer.get(r.customer_id)!.push(r);
}

for (const [userId, rows] of byCustomer) {
  // Serialize just this customer's rows back to CSV
  const csv = [
    &#x22;product_sku,product_name,quantity,purchase_date,is_active&#x22;,
    ...rows.map(r => \`\${r.product_sku},\${r.product_name},\${r.quantity},\${r.purchase_date},\${r.is_active}\`),
  ].join(&#x22;\\n&#x22;);

  await sonzai.agents.priming.primeUser(AGENT_ID, userId, {
    source: &#x22;crm_inventory&#x22;,
    structured_import: {
      entity_type: &#x22;product&#x22;,
      content_csv: csv,
      column_mapping: {
        product_sku:   { property: &#x22;sku&#x22; },
        product_name:  { property: &#x22;name&#x22;, is_label: true },
        quantity:      { property: &#x22;quantity&#x22;, type: &#x22;number&#x22; },
        purchase_date: { property: &#x22;purchased_on&#x22; },
        is_active:     { property: &#x22;active&#x22;, type: &#x22;boolean&#x22; },
      },
    },
  });
}
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Async Python (sync Python doesn't accept structured_import as a kwarg yet)
import asyncio, csv, os
from collections import defaultdict
from sonzai import AsyncSonzai

AGENT_ID = &#x22;agent_abc&#x22;

async def import_inventory(path: str):
  with open(path) as f:
      rows = list(csv.DictReader(f))

  by_customer = defaultdict(list)
  for r in rows:
      by_customer[r[&#x22;customer_id&#x22;]].append(r)

  async with AsyncSonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;]) as client:
      for user_id, customer_rows in by_customer.items():
          content_csv = &#x22;\\n&#x22;.join([
              &#x22;product_sku,product_name,quantity,purchase_date,is_active&#x22;,
              *[
                  f&#x22;{r['product_sku']},{r['product_name']},{r['quantity']},&#x22;
                  f&#x22;{r['purchase_date']},{r['is_active']}&#x22;
                  for r in customer_rows
              ],
          ])
          await client.agents.priming.prime_user(
              AGENT_ID,
              user_id,
              source=&#x22;crm_inventory&#x22;,
              structured_import={
                  &#x22;entity_type&#x22;: &#x22;product&#x22;,
                  &#x22;content_csv&#x22;: content_csv,
                  &#x22;column_mapping&#x22;: {
                      &#x22;product_sku&#x22;:   {&#x22;property&#x22;: &#x22;sku&#x22;},
                      &#x22;product_name&#x22;:  {&#x22;property&#x22;: &#x22;name&#x22;, &#x22;is_label&#x22;: True},
                      &#x22;quantity&#x22;:      {&#x22;property&#x22;: &#x22;quantity&#x22;, &#x22;type&#x22;: &#x22;number&#x22;},
                      &#x22;purchase_date&#x22;: {&#x22;property&#x22;: &#x22;purchased_on&#x22;},
                      &#x22;is_active&#x22;:     {&#x22;property&#x22;: &#x22;active&#x22;, &#x22;type&#x22;: &#x22;boolean&#x22;},
                  },
              },
          )

asyncio.run(import_inventory(&#x22;inventory.csv&#x22;))`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;encoding/csv&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

func importInventory(ctx context.Context, client *sonzai.Client, path string) error {
  f, err := os.Open(path)
  if err != nil {
      return err
  }
  defer f.Close()
  rows, err := csv.NewReader(f).ReadAll()
  if err != nil || len(rows) == 0 {
      return err
  }
  header := rows[0]
  col := func(name string, row []string) string {
      for i, h := range header {
          if h == name && i < len(row) {
              return row[i]
          }
      }
      return &#x22;&#x22;
  }
  byCustomer := map[string][][]string{}
  for _, r := range rows[1:] {
      cid := col(&#x22;customer_id&#x22;, r)
      byCustomer[cid] = append(byCustomer[cid], r)
  }

  for userID, customerRows := range byCustomer {
      var sb strings.Builder
      sb.WriteString(&#x22;product_sku,product_name,quantity,purchase_date,is_active&#x22;)
      for _, r := range customerRows {
          sb.WriteString(&#x22;\\n&#x22;)
          sb.WriteString(strings.Join([]string{
              col(&#x22;product_sku&#x22;, r), col(&#x22;product_name&#x22;, r),
              col(&#x22;quantity&#x22;, r), col(&#x22;purchase_date&#x22;, r), col(&#x22;is_active&#x22;, r),
          }, &#x22;,&#x22;))
      }

      _, err := client.Priming.PrimeUser(ctx, AgentID, userID, sonzai.PrimeUserOptions{
          Source: &#x22;crm_inventory&#x22;,
          StructuredImport: &sonzai.StructuredImportSpec{
              EntityType: &#x22;product&#x22;,
              ContentCSV: sb.String(),
              ColumnMapping: map[string]sonzai.StructuredColumnMapping{
                  &#x22;product_sku&#x22;:   {Property: &#x22;sku&#x22;},
                  &#x22;product_name&#x22;:  {Property: &#x22;name&#x22;, IsLabel: true},
                  &#x22;quantity&#x22;:      {Property: &#x22;quantity&#x22;, Type: &#x22;number&#x22;},
                  &#x22;purchase_date&#x22;: {Property: &#x22;purchased_on&#x22;},
                  &#x22;is_active&#x22;:     {Property: &#x22;active&#x22;, Type: &#x22;boolean&#x22;},
              },
          },
      })
      if err != nil {
          return fmt.Errorf(&#x22;user %s: %w&#x22;, userID, err)
      }
  }
  return nil
}`,
  },
  {
    id: &#x22;curl&#x22;,
    label: &#x22;curl&#x22;,
    code: `# One call per user. content_csv is a CSV string (first row = headers).
curl -s -X POST \\
https://api.sonz.ai/api/v1/agents/agent_abc/users/c_001/prime \\
-H &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;source&#x22;: &#x22;crm_inventory&#x22;,
  &#x22;structured_import&#x22;: {
    &#x22;entity_type&#x22;: &#x22;product&#x22;,
    &#x22;content_csv&#x22;: &#x22;product_sku,product_name,quantity,purchase_date,is_active\\nSKU-001,Hiking Backpack,1,2025-09-01,true\\nSKU-045,Water Bottle,2,2025-10-12,true&#x22;,
    &#x22;column_mapping&#x22;: {
      &#x22;product_sku&#x22;:   { &#x22;property&#x22;: &#x22;sku&#x22; },
      &#x22;product_name&#x22;:  { &#x22;property&#x22;: &#x22;name&#x22;, &#x22;is_label&#x22;: true },
      &#x22;quantity&#x22;:      { &#x22;property&#x22;: &#x22;quantity&#x22;, &#x22;type&#x22;: &#x22;number&#x22; },
      &#x22;purchase_date&#x22;: { &#x22;property&#x22;: &#x22;purchased_on&#x22; },
      &#x22;is_active&#x22;:     { &#x22;property&#x22;: &#x22;active&#x22;, &#x22;type&#x22;: &#x22;boolean&#x22; }
    }
  }
}'
# => { &#x22;job_id&#x22;: &#x22;...&#x22;, &#x22;facts_created&#x22;: 2, &#x22;rows_parsed&#x22;: 2, &#x22;kb_resolved&#x22;: 0, &#x22;unresolved&#x22;: 2 }`,
  },
]"
/>

### Column mapping rules [#column-mapping-rules]

Each entry in `column_mapping` maps a CSV header to a metadata key on the resulting fact:

* `property` — the metadata key the column's value ends up under.
* `is_label` — exactly one column should be marked `is_label: true`. Its value becomes the human-readable name of the item (used to build the fact's text, e.g. `"User owns Hiking Backpack"`, and to attempt [knowledge base](/docs/migrating/knowledge-base) resolution).
* `type` — coerces values to `"number"` or `"boolean"`. Default is string. Unparseable numbers fall back to string without error.

Omitted columns are ignored. Extra columns in the CSV not present in `column_mapping` are silently dropped.

### Optional: resolve against a knowledge base [#optional-resolve-against-a-knowledge-base]

Pass `project_id` inside `structured_import` to have Sonzai attempt to match each row's label against knowledge-base nodes of the given `entity_type`. Resolved rows get `kb_node_id` and `kb_label` stamped on their fact metadata, making them joinable with your product catalog.

```json
{
  "structured_import": {
    "entity_type": "product",
    "project_id":  "proj_xyz",
    "content_csv": "...",
    "column_mapping": { ... }
  }
}
```

The response's `kb_resolved` and `unresolved` counts tell you the match rate. Upload your product catalog to the KB first (see [Knowledge Base](/docs/migrating/knowledge-base)) and it'll work on subsequent imports.

<Callout type="info" title="Python SDK note">
  The sync Python SDK's `prime_user()` doesn't currently accept `structured_import` as a keyword. Use the async client (`AsyncSonzai`) which forwards extra kwargs, or fall back to an HTTP call via `requests.post()`. TypeScript and curl work as shown above.
</Callout>

## Verify [#verify]

```bash
# After either pattern, inspect the agent's users
curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/users?limit=10" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.users[] | {user_id,display_name,metadata}'

# For structured_import, spot-check the inventory facts
curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/memory/facts?user_id=c_001&source_type=structured_import" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.facts[] | {content,metadata}'
```

## Tips [#tips]

* **Combine patterns.** Run `batch_import` first for all contacts (metadata), then loop with `prime_user` + `structured_import` for their inventory. The second call adds facts without disturbing the user record.
* **Label choice matters.** The `is_label` column becomes both the fact text ("User owns X") and the KB resolution query. Pick the column with human-readable names, not IDs — `"Hiking Backpack"` resolves; `"SKU-001"` doesn't.
* **No LLM cost.** `structured_import` skips LLM extraction entirely. Facts are deterministic from your CSV. That makes this the cheapest and most reliable path when you have clean tabular data.
* **Encoding.** UTF-8. If your CRM export is UTF-16 / Latin-1, convert first — the CSV parser expects UTF-8.

## What's next [#whats-next]

* [Knowledge base](/docs/migrating/knowledge-base) — upload a product catalog so `structured_import` can resolve rows to KB nodes.
* [Inventory](/docs/api/inventory) — the live API for querying and updating these facts after migration.
* [Custom JSON](/docs/migrating/custom-json) — if your CRM has conversational notes you also want to migrate.


---

# From custom JSON

Source: https://sonz.ai/docs/en/guides/migrating/custom-json

> The catch-all migration guide for homegrown chat stores, proprietary databases, Responses API logs, and anything else that has users and messages. Anything with (user_id, messages[]) fits.



## When to use this guide [#when-to-use-this-guide]

Use this guide if your data doesn't match one of the named sources and you already have it in some shape you control — a Postgres table, a pile of JSON files, the OpenAI Responses API store, a custom fine-tuning dataset, a backup from a deprecated product.

The target shape is simple: for each user you want to migrate, you need a stable `user_id` and some amount of content about them. Everything else is optional.

## The canonical shape [#the-canonical-shape]

Get your source data into this shape first. Everything else in this guide operates on it.

```ts
type SourceUser = {
  user_id:       string;
  display_name?: string;
  email?:        string;
  custom?:       Record<string, string>;
  transcripts:   string[];   // role-tagged, e.g. "User: hi\nAgent: hey"
  facts?:        string[];   // one assertion per string
  notes?:        string[];   // free-form paragraphs
};
```

* `transcripts` — one string per distinct conversation. Keep them role-tagged (`User: ...` / `Agent: ...`) so the extractor can distinguish turns.
* `facts` — if your source has pre-extracted user assertions, pass them here; each becomes a `text` block.
* `notes` — anything else: CRM notes, support ticket summaries, onboarding questionnaires.

All three are optional. A user with only `display_name` and `email` is still a valid import — Sonzai will generate facts from metadata alone.

## Example: migrating from a Postgres chat table [#example-migrating-from-a-postgres-chat-table]

Suppose you have two tables:

```sql
users(id, display_name, email, created_at)
messages(user_id, role, content, created_at, conversation_id)
```

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, psycopg
from collections import defaultdict
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def load_source():
  conn = psycopg.connect(os.environ[&#x22;DATABASE_URL&#x22;])
  users = {u[0]: {&#x22;user_id&#x22;: u[0], &#x22;display_name&#x22;: u[1], &#x22;email&#x22;: u[2]}
           for u in conn.execute(&#x22;SELECT id, display_name, email FROM users&#x22;)}

  convos = defaultdict(lambda: defaultdict(list))
  rows = conn.execute(
      &#x22;SELECT user_id, conversation_id, role, content &#x22;
      &#x22;FROM messages ORDER BY user_id, conversation_id, created_at&#x22;
  )
  for user_id, convo_id, role, content in rows:
      r = &#x22;User&#x22; if role == &#x22;user&#x22; else &#x22;Agent&#x22;
      convos[user_id][convo_id].append(f&#x22;{r}: {content}&#x22;)

  for user_id, u in users.items():
      u[&#x22;transcripts&#x22;] = [
          f&#x22;[conversation {cid}]\\n&#x22; + &#x22;\\n&#x22;.join(lines)
          for cid, lines in convos[user_id].items()
      ]
  return list(users.values())

def to_sonzai_user(src):
  content = [
      {&#x22;type&#x22;: &#x22;chat_transcript&#x22;, &#x22;body&#x22;: t} for t in src.get(&#x22;transcripts&#x22;, [])
  ] + [
      {&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: f} for f in src.get(&#x22;facts&#x22;, [])
  ] + [
      {&#x22;type&#x22;: &#x22;note&#x22;, &#x22;body&#x22;: n} for n in src.get(&#x22;notes&#x22;, [])
  ]
  return {
      &#x22;user_id&#x22;:      src[&#x22;user_id&#x22;],
      &#x22;display_name&#x22;: src.get(&#x22;display_name&#x22;),
      &#x22;metadata&#x22;: {
          &#x22;email&#x22;:  src.get(&#x22;email&#x22;),
          &#x22;custom&#x22;: src.get(&#x22;custom&#x22;) or {},
      },
      &#x22;content&#x22;: content,
  }

def migrate():
  source = load_source()
  # Chunk in batches of 200 to keep individual requests small
  for i in range(0, len(source), 200):
      chunk = [to_sonzai_user(s) for s in source[i : i + 200]]
      job = sonzai.agents.priming.batch_import(
          AGENT_ID, source=&#x22;custom_json&#x22;, users=chunk,
      )
      print(f&#x22;batch {i//200}: job_id={job.job_id} users={job.total_users}&#x22;)`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

function toSonzaiUser(src: SourceUser) {
const content = [
  ...(src.transcripts ?? []).map(t => ({ type: &#x22;chat_transcript&#x22;, body: t })),
  ...(src.facts ?? []).map(f => ({ type: &#x22;text&#x22;, body: f })),
  ...(src.notes ?? []).map(n => ({ type: &#x22;note&#x22;, body: n })),
];
return {
  user_id:      src.user_id,
  display_name: src.display_name,
  metadata: {
    email:  src.email,
    custom: src.custom ?? {},
  },
  content,
};
}

async function migrate(source: SourceUser[]) {
for (let i = 0; i < source.length; i += 200) {
  const chunk = source.slice(i, i + 200).map(toSonzaiUser);
  const job = await sonzai.agents.priming.batchImport(AGENT_ID, {
    source: &#x22;custom_json&#x22;,
    users:  chunk,
  });
  console.log(\`batch \${i / 200}: job_id=\${job.job_id} users=\${job.total_users}\`);
}
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

// SourceUser is whatever shape your custom store returns.
type SourceUser struct {
  UserID, DisplayName, Email string
  Transcripts, Facts, Notes  []string
  Custom                     map[string]string
}

func toSonzaiUser(s SourceUser) sonzai.BatchImportUser {
  content := make([]sonzai.PrimeContentBlock, 0,
      len(s.Transcripts)+len(s.Facts)+len(s.Notes))
  for _, t := range s.Transcripts {
      content = append(content, sonzai.PrimeContentBlock{Type: &#x22;chat_transcript&#x22;, Body: t})
  }
  for _, f := range s.Facts {
      content = append(content, sonzai.PrimeContentBlock{Type: &#x22;text&#x22;, Body: f})
  }
  for _, n := range s.Notes {
      content = append(content, sonzai.PrimeContentBlock{Type: &#x22;note&#x22;, Body: n})
  }
  return sonzai.BatchImportUser{
      UserID:      s.UserID,
      DisplayName: s.DisplayName,
      Metadata: &sonzai.PrimeUserMetadata{
          Email:  s.Email,
          Custom: s.Custom,
      },
      Content: content,
  }
}

func migrate(ctx context.Context, client *sonzai.Client, source []SourceUser) error {
  for i := 0; i < len(source); i += 200 {
      end := i + 200
      if end > len(source) {
          end = len(source)
      }
      chunk := make([]sonzai.BatchImportUser, 0, end-i)
      for _, s := range source[i:end] {
          chunk = append(chunk, toSonzaiUser(s))
      }
      job, err := client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
          Source: &#x22;custom_json&#x22;,
          Users:  chunk,
      })
      if err != nil {
          return err
      }
      fmt.Printf(&#x22;batch %d: job_id=%s users=%d\\n&#x22;, i/200, job.JobID, job.TotalUsers)
  }
  return nil
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  if err := migrate(context.Background(), client, []SourceUser{ /* … */ }); err != nil {
      panic(err)
  }
}`,
  },
]"
/>

## Example: OpenAI Responses API store [#example-openai-responses-api-store]

The Responses API persists the conversation via `previous_response_id` chains. Walk each chain back to the root, collect input/output items, and treat the whole chain as one transcript.

```python
from openai import OpenAI
openai = OpenAI()

def walk_response_chain(response_id: str) -> list:
    """Returns oldest-first list of (role, text) tuples."""
    items = []
    current = response_id
    while current:
        r = openai.responses.retrieve(current)
        # r.input and r.output both contain content items; flatten text
        for item in (r.output or []):
            if getattr(item, "type", None) == "message":
                for c in item.content or []:
                    if getattr(c, "type", None) == "output_text":
                        items.append(("Agent", c.text))
        # The user turn is in r.input when the chain started on a user message
        current = getattr(r, "previous_response_id", None)
    return list(reversed(items))
```

Pass the resulting transcript as a `chat_transcript` block per the canonical shape above.

## Verify [#verify]

```bash
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '{status,total_users,facts_stored,errors}'
```

List users to spot-check:

```bash
curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/users?limit=5&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer $SONZAI_API_KEY"
```

## Tips [#tips]

* **Keep `user_id` stable across systems.** The same key in your app database and in Sonzai means you don't need a second lookup table.
* **Batch size.** 100–300 users per `batch_import` request is the sweet spot. Larger batches increase the odds of a timeout on the HTTP side even though processing is async. Pace yourself to avoid rate limits on metadata-fact extraction, which runs synchronously.
* **Progress reporting to your users.** You can show "importing..." UI by polling `get_import_status` and computing `processed_users / total_users`. It ticks up as the async worker processes each user.
* **Incremental migration.** If you want to migrate live without downtime, run the import in the background and keep writing new chats to your old system until the backfill catches up. Once Sonzai has the history, cut over to Sonzai for all new chats; old data stays in place but the agent has everything it needs.

## What's next [#whats-next]

* [CRM / CSV](/docs/migrating/crm-csv) — if your data is tabular rather than conversational.
* [Knowledge base](/docs/migrating/knowledge-base) — if you also have documents to migrate.
* [Memory](/docs/memory) — how the extracted facts get organised.


---

# Knowledge base documents

Source: https://sonz.ai/docs/en/guides/migrating/knowledge-base

> Migrate your document corpus — PDFs, DOCX, Markdown, plain text — into Sonzai's knowledge graph. The extractor builds a deduplicated graph of entities and relationships that agents search during conversations.



## What you're migrating [#what-youre-migrating]

If you already have a RAG pipeline backed by a vector database (Pinecone, Weaviate, Qdrant, pgvector, Chroma), your "documents" are probably PDFs, MDs, or DOCX files that you chunked and embedded. Sonzai takes those same source files and builds a **knowledge graph** from them — entities, relationships, types — rather than an opaque vector store. Agents search the graph during conversations.

Two paths in:

1. **Upload files** — the happy path. Sonzai parses, chunks, extracts entities and relationships, and builds the graph. Use for PDF / DOCX / MD / TXT.
2. **Insert facts directly** — if you already have structured entities (e.g. a product catalog as JSON), skip the LLM extraction and push them via the knowledge facts API. Not covered in depth on this page; see [Knowledge Base](/docs/knowledge-base).

## 1. File upload: the basics [#1-file-upload-the-basics]

Endpoint: `POST /api/v1/projects/{projectId}/knowledge/documents` (multipart, one file per request).

* **Accepted types:** `.pdf`, `.docx`, `.md`, `.markdown`, `.txt`.
* **Max size:** 50 MB per file.
* **Dedup:** identical content (SHA-256 match) returns `409 Conflict` with the existing `document_id`. You can safely re-run without creating duplicates.
* **Async:** the response returns immediately with `status: "queued"`. Extraction runs in the background.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import fs from &#x22;fs&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = &#x22;proj_xyz&#x22;;

async function uploadOne(path: string) {
const fileName = path.split(&#x22;/&#x22;).pop()!;
const fileData = fs.readFileSync(path);
const doc = await sonzai.knowledge.uploadDocument(
  PROJECT_ID,
  fileName,
  fileData,
  &#x22;application/pdf&#x22;,   // or text/markdown, text/plain, etc.
);
console.log(doc.document_id, doc.status);
return doc;
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, mimetypes
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
PROJECT_ID = &#x22;proj_xyz&#x22;

def upload_one(path: str):
  with open(path, &#x22;rb&#x22;) as f:
      data = f.read()
  content_type = mimetypes.guess_type(path)[0] or &#x22;application/octet-stream&#x22;
  doc = sonzai.knowledge.upload_document(
      PROJECT_ID,
      file_name=os.path.basename(path),
      file_data=data,
      content_type=content_type,
  )
  print(doc.document_id, doc.status)
  return doc`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;path/filepath&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const ProjectID = &#x22;proj_xyz&#x22;

func uploadOne(ctx context.Context, client *sonzai.Client, path string) (*sonzai.KBDocument, error) {
  data, err := os.ReadFile(path)
  if err != nil {
      return nil, err
  }
  doc, err := client.Knowledge.UploadDocumentBytes(ctx, ProjectID, sonzai.UploadDocumentOptions{
      FileName: filepath.Base(path),
      FileData: data,
  })
  if err != nil {
      return nil, err
  }
  fmt.Println(doc.DocumentID, doc.Status)
  return doc, nil
}`,
  },
  {
    id: &#x22;curl&#x22;,
    label: &#x22;curl&#x22;,
    code: `curl -s -X POST https://api.sonz.ai/api/v1/projects/proj_xyz/knowledge/documents \\
-H &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22; \\
-F &#x22;file=@./product_catalog.pdf;type=application/pdf&#x22;
# => { &#x22;document_id&#x22;: &#x22;...&#x22;, &#x22;file_name&#x22;: &#x22;product_catalog.pdf&#x22;,
#      &#x22;file_size&#x22;: 1234567, &#x22;checksum&#x22;: &#x22;sha256...&#x22;, &#x22;status&#x22;: &#x22;queued&#x22; }`,
  },
]"
/>

## 2. Batch-uploading a corpus [#2-batch-uploading-a-corpus]

A typical migration is "walk this directory, upload everything, retry transient errors, skip duplicates". Sonzai's dedup via SHA-256 makes this safe to run repeatedly.

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, mimetypes, time
from pathlib import Path
from sonzai import Sonzai
from sonzai.errors import ConflictError  # raised on 409 duplicate

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
PROJECT_ID = &#x22;proj_xyz&#x22;
ACCEPTED = {&#x22;.pdf&#x22;, &#x22;.docx&#x22;, &#x22;.md&#x22;, &#x22;.markdown&#x22;, &#x22;.txt&#x22;}
MAX_BYTES = 50 * 1024 * 1024

def migrate_corpus(root: str):
  uploaded, skipped, failed = 0, 0, []
  for path in Path(root).rglob(&#x22;*&#x22;):
      if not path.is_file() or path.suffix.lower() not in ACCEPTED:
          continue
      size = path.stat().st_size
      if size > MAX_BYTES:
          print(f&#x22;skip (too large): {path} ({size/1e6:.1f} MB)&#x22;)
          failed.append(str(path))
          continue
      try:
          sonzai.knowledge.upload_document(
              PROJECT_ID,
              file_name=path.name,
              file_data=path.read_bytes(),
              content_type=(mimetypes.guess_type(str(path))[0]
                            or &#x22;application/octet-stream&#x22;),
          )
          uploaded += 1
      except ConflictError:
          skipped += 1  # already uploaded on a previous run — safe to ignore
      except Exception as e:
          print(f&#x22;failed: {path}: {e}&#x22;)
          failed.append(str(path))
          time.sleep(1)  # gentle backoff on unknown errors

  print(f&#x22;uploaded={uploaded} skipped(dup)={skipped} failed={len(failed)}&#x22;)
  return uploaded, skipped, failed`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import fs from &#x22;fs/promises&#x22;;
import path from &#x22;path&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = &#x22;proj_xyz&#x22;;
const ACCEPTED = new Set([&#x22;.pdf&#x22;, &#x22;.docx&#x22;, &#x22;.md&#x22;, &#x22;.markdown&#x22;, &#x22;.txt&#x22;]);
const MAX_BYTES = 50 * 1024 * 1024;

async function* walk(dir: string): AsyncGenerator<string> {
for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
  const full = path.join(dir, entry.name);
  if (entry.isDirectory()) yield* walk(full);
  else if (ACCEPTED.has(path.extname(full).toLowerCase())) yield full;
}
}

const mimeFor = (p: string) => ({
&#x22;.pdf&#x22;: &#x22;application/pdf&#x22;,
&#x22;.md&#x22;:  &#x22;text/markdown&#x22;,
&#x22;.markdown&#x22;: &#x22;text/markdown&#x22;,
&#x22;.txt&#x22;: &#x22;text/plain&#x22;,
&#x22;.docx&#x22;: &#x22;application/vnd.openxmlformats-officedocument.wordprocessingml.document&#x22;,
}[path.extname(p).toLowerCase()] ?? &#x22;application/octet-stream&#x22;);

async function migrateCorpus(root: string) {
let uploaded = 0, skipped = 0, failed = 0;
for await (const p of walk(root)) {
  const stat = await fs.stat(p);
  if (stat.size > MAX_BYTES) { failed++; continue; }
  try {
    await sonzai.knowledge.uploadDocument(
      PROJECT_ID, path.basename(p), await fs.readFile(p), mimeFor(p),
    );
    uploaded++;
  } catch (e: any) {
    if (e.status === 409) skipped++;  // duplicate — safe
    else { console.error(p, e); failed++; }
  }
}
console.log({ uploaded, skipped, failed });
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;errors&#x22;
  &#x22;fmt&#x22;
  &#x22;io/fs&#x22;
  &#x22;os&#x22;
  &#x22;path/filepath&#x22;
  &#x22;strings&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const (
  ProjectID = &#x22;proj_xyz&#x22;
  MaxBytes  = 50 * 1024 * 1024
)

var accepted = map[string]bool{
  &#x22;.pdf&#x22;: true, &#x22;.docx&#x22;: true, &#x22;.md&#x22;: true, &#x22;.markdown&#x22;: true, &#x22;.txt&#x22;: true,
}

func migrateCorpus(ctx context.Context, client *sonzai.Client, root string) error {
  var uploaded, skipped, failed int
  err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
      if walkErr != nil || d.IsDir() {
          return walkErr
      }
      if !accepted[strings.ToLower(filepath.Ext(path))] {
          return nil
      }
      info, err := d.Info()
      if err != nil || info.Size() > MaxBytes {
          failed++
          return nil
      }
      data, err := os.ReadFile(path)
      if err != nil {
          failed++
          return nil
      }
      _, err = client.Knowledge.UploadDocumentBytes(ctx, ProjectID, sonzai.UploadDocumentOptions{
          FileName: filepath.Base(path),
          FileData: data,
      })
      switch {
      case err == nil:
          uploaded++
      case isConflict(err):
          skipped++ // duplicate — safe
      default:
          failed++
          fmt.Fprintln(os.Stderr, path, err)
      }
      return nil
  })
  fmt.Printf(&#x22;uploaded=%d skipped(dup)=%d failed=%d\\n&#x22;, uploaded, skipped, failed)
  return err
}

func isConflict(err error) bool {
  var apiErr *sonzai.APIError
  return errors.As(err, &apiErr) && apiErr.StatusCode == 409
}`,
  },
]"
/>

The first run uploads everything; subsequent runs become cheap no-ops because identical content yields `409 Conflict` which you treat as "already done".

## 3. Verify [#3-verify]

List documents and watch their status transition from `queued` to `completed`:

```bash
curl -s "https://api.sonz.ai/api/v1/projects/proj_xyz/knowledge/documents?limit=50" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.documents[] | {document_id,file_name,status}'
```

Then confirm the extractor produced nodes in the graph:

```bash
curl -s "https://api.sonz.ai/api/v1/projects/proj_xyz/knowledge/nodes?limit=20&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.nodes[] | {node_id, node_type, label}'
```

When everything you uploaded shows `status: "completed"` and the node list has the entities you expected, the migration is done.

## Migrating from a vector database [#migrating-from-a-vector-database]

If your source is an existing RAG stack, the cleanest path is **re-upload the original source files**, not the chunked text. The chunks you indexed were optimized for cosine similarity, not for graph extraction.

* **Pinecone / Weaviate / Qdrant.** Most teams store the source file paths or blob URLs in metadata. Walk that list, fetch each file, upload to Sonzai.
* **Chroma / pgvector / FAISS.** Same approach — you indexed documents, find the originals, upload.
* **No originals (only chunk text stored).** Concatenate the chunks back into a single `.md` or `.txt` file per document, upload that. Less accurate entity extraction than the original PDF, but functional.

Don't try to port the vectors themselves — Sonzai's graph isn't vector-first and the embeddings wouldn't mean anything here.

## Migrating from Notion / Confluence / Google Docs [#migrating-from-notion--confluence--google-docs]

Use each platform's export to Markdown, then upload the resulting `.md` files. All three export cleanly to Markdown with per-page files plus an `images/` folder. Sonzai ignores the images and extracts from the Markdown.

```bash
# Notion: Settings & Members → Export all workspace content → Markdown & CSV
# Confluence: Space Settings → Content Tools → Export → HTML, then pandoc to md
# Google Docs: File → Download → Markdown (.md), per document
```

## Tips [#tips]

* **`project_id` vs `agent_id`.** The knowledge base is **project-scoped**, not agent-scoped. All agents in a project share the same KB. Find your project ID in the Sonzai workbench or via `GET /api/v1/projects`.
* **Rate limiting.** Upload in sequence rather than in parallel for the first few hundred files. The extraction queue is backpressure-aware; hammering it doesn't speed anything up and increases the odds of transient errors.
* **Large PDFs** (100+ pages) work but are slower to process. Consider splitting into chapter-level PDFs if search precision matters more than document identity.
* **Subsequent updates.** If a document changes, upload the new version — you'll get a new `document_id`. Delete the old one via `DELETE /api/v1/projects/{id}/knowledge/documents/{documentId}` if you don't want both versions contributing to the graph.
* **Pair with structured CSV.** See [CRM / CSV](/docs/migrating/crm-csv) for how `structured_import` can resolve user inventory rows against the KB you just built.

## What's next [#whats-next]

* [Knowledge Base](/docs/knowledge-base) — how agents query the graph during conversations.
* [Knowledge graph (org-scope)](/docs/api/knowledge-org) — sharing a KB across projects.
* [CRM / CSV](/docs/migrating/crm-csv) — using the KB as a resolution target for structured user facts.


---

# From LangChain memory

Source: https://sonz.ai/docs/en/guides/migrating/langchain

> Migrate chat history from LangChain's ConversationBufferMemory, ChatMessageHistory, and persistent backing stores (Redis, Postgres, DynamoDB) into Sonzai.



## What you're migrating [#what-youre-migrating]

LangChain's memory layer is mostly a wrapper around an ordered list of `BaseMessage` objects per session. The common classes all expose the same read surface:

* `ConversationBufferMemory` — keeps the full message list in memory (or in the attached history store).
* `ConversationSummaryMemory` / `ConversationSummaryBufferMemory` — keeps a rolling summary plus recent messages.
* `ChatMessageHistory` backed by `RedisChatMessageHistory`, `PostgresChatMessageHistory`, `DynamoDBChatMessageHistory`, etc. — the same messages persisted across restarts.

The mapping into Sonzai:

| LangChain                                                                        | Sonzai                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id` (or LangGraph `thread_id`)                                          | `session_id` — reuse it verbatim on `sessions.start` / `sessions.end` once you're live. For the bulk historical import below, each session becomes one `chat_transcript` block; the session ID is preserved as a header inside the block. |
| User identity (whatever your app keys on — `user_id` field, session owner, etc.) | `user_id` — must be stable across all of that user's sessions so Sonzai can build per-user memory.                                                                                                                                        |
| `HumanMessage` / `AIMessage` list                                                | one `chat_transcript` content block                                                                                                                                                                                                       |
| Summary (from `ConversationSummaryMemory`)                                       | `text` content block                                                                                                                                                                                                                      |
| `additional_kwargs` metadata                                                     | fold into transcript or drop                                                                                                                                                                                                              |

If one user owns multiple LangChain sessions (common), pack them all into the same user's content array — one `chat_transcript` block per session — so Sonzai's extractor can dedupe facts across them. For live chat going forward, wrap each conversation in `sessions.start` / `sessions.end` and Sonzai will tag every extracted fact with its source `session_id` automatically. See [Sessions](/docs/sessions).

## 1. Export from LangChain [#1-export-from-langchain]

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from langchain_community.chat_message_histories import (
  RedisChatMessageHistory,  # swap for Postgres/DynamoDB/etc.
)

def export_langchain_session(session_id: str) -> str:
  &#x22;&#x22;&#x22;Return a role-tagged transcript string for one LangChain session.&#x22;&#x22;&#x22;
  history = RedisChatMessageHistory(
      session_id=session_id,
      url=os.environ[&#x22;REDIS_URL&#x22;],
  )
  lines = []
  for msg in history.messages:
      role = &#x22;User&#x22; if msg.type == &#x22;human&#x22; else &#x22;Agent&#x22;
      lines.append(f&#x22;{role}: {msg.content}&#x22;)
  return &#x22;\\n&#x22;.join(lines)`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { RedisChatMessageHistory } from &#x22;@langchain/redis&#x22;;

async function exportLangchainSession(sessionId: string): Promise<string> {
const history = new RedisChatMessageHistory({
  sessionId,
  url: process.env.REDIS_URL!,
});
const messages = await history.getMessages();
return messages
  .map(m => \`\${m._getType() === &#x22;human&#x22; ? &#x22;User&#x22; : &#x22;Agent&#x22;}: \${m.content}\`)
  .join(&#x22;\\n&#x22;);
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// LangChain has no first-party Go SDK and the LangChain Go community port
// has its own conventions; the simplest, most portable path is to read the
// raw chat-history records yourself. This shape works against the standard
// RedisChatMessageHistory layout (one Redis list per session_id, each
// element a JSON {type, content}). Swap the redis client for psycopg /
// dynamodb / etc. depending on your LangChain backend.
package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;

  &#x22;github.com/redis/go-redis/v9&#x22;
)

type langchainMessage struct {
  Type, Content string
}

func exportLangchainSession(ctx context.Context, sessionID string) (string, error) {
  rdb := redis.NewClient(&redis.Options{Addr: os.Getenv(&#x22;REDIS_ADDR&#x22;)})
  defer rdb.Close()

  raw, err := rdb.LRange(ctx, &#x22;message_store:&#x22;+sessionID, 0, -1).Result()
  if err != nil {
      return &#x22;&#x22;, err
  }

  var lines []string
  for _, r := range raw {
      var m langchainMessage
      if err := json.Unmarshal([]byte(r), &m); err != nil {
          continue
      }
      role := &#x22;Agent&#x22;
      if m.Type == &#x22;human&#x22; {
          role = &#x22;User&#x22;
      }
      lines = append(lines, role+&#x22;: &#x22;+m.Content)
  }
  return strings.Join(lines, &#x22;\\n&#x22;), nil
}`,
  },
]"
/>

If you're on `ConversationSummaryMemory` rather than raw history, read `memory.moving_summary_buffer` and pass it as a separate `text` block:

```python
summary = memory.moving_summary_buffer  # string
```

## 2. Map to Sonzai's import shape [#2-map-to-sonzais-import-shape]

One user with multiple past sessions:

```json
{
  "source": "langchain",
  "users": [
    {
      "user_id": "user_123",
      "metadata": { "custom": { "langchain_session_ids": "sess-a,sess-b,sess-c" } },
      "content": [
        { "type": "chat_transcript", "body": "[session sess-a]\nUser: ...\nAgent: ..." },
        { "type": "chat_transcript", "body": "[session sess-b]\nUser: ...\nAgent: ..." },
        { "type": "text", "body": "Summary: User has been asking about migrating off LangChain for two weeks." }
      ]
    }
  ]
}
```

## 3. Import into Sonzai [#3-import-into-sonzai]

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai
sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def migrate_langchain_users(user_session_map):
  &#x22;&#x22;&#x22;user_session_map: { user_id: [session_id, ...] }&#x22;&#x22;&#x22;
  users = []
  for user_id, session_ids in user_session_map.items():
      content = []
      for sid in session_ids:
          transcript = export_langchain_session(sid)
          if transcript:
              content.append({
                  &#x22;type&#x22;: &#x22;chat_transcript&#x22;,
                  &#x22;body&#x22;: f&#x22;[session {sid}]\\n{transcript}&#x22;,
              })
      users.append({
          &#x22;user_id&#x22;: user_id,
          &#x22;metadata&#x22;: {
              &#x22;custom&#x22;: {&#x22;langchain_session_ids&#x22;: &#x22;,&#x22;.join(session_ids)},
          },
          &#x22;content&#x22;: content,
      })

  return sonzai.agents.priming.batch_import(
      AGENT_ID, source=&#x22;langchain&#x22;, users=users,
  )`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

async function migrateLangchainUsers(
userSessionMap: Record<string, string[]>,
) {
const users = await Promise.all(
  Object.entries(userSessionMap).map(async ([user_id, sessionIds]) => {
    const content = [];
    for (const sid of sessionIds) {
      const transcript = await exportLangchainSession(sid);
      if (transcript) {
        content.push({
          type: &#x22;chat_transcript&#x22;,
          body: \`[session \${sid}]\\n\${transcript}\`,
        });
      }
    }
    return {
      user_id,
      metadata: {
        custom: { langchain_session_ids: sessionIds.join(&#x22;,&#x22;) },
      },
      content,
    };
  }),
);

return sonzai.agents.priming.batchImport(AGENT_ID, {
  source: &#x22;langchain&#x22;,
  users,
});
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

// userSessionMap: { user_id: [session_id, ...] }
func migrateLangchainUsers(ctx context.Context, client *sonzai.Client, userSessionMap map[string][]string) (*sonzai.BatchImportResponse, error) {
  users := make([]sonzai.BatchImportUser, 0, len(userSessionMap))
  for userID, sessionIDs := range userSessionMap {
      content := make([]sonzai.PrimeContentBlock, 0, len(sessionIDs))
      for _, sid := range sessionIDs {
          transcript, err := exportLangchainSession(ctx, sid)
          if err != nil || transcript == &#x22;&#x22; {
              continue
          }
          content = append(content, sonzai.PrimeContentBlock{
              Type: &#x22;chat_transcript&#x22;,
              Body: &#x22;[session &#x22; + sid + &#x22;]\\n&#x22; + transcript,
          })
      }
      users = append(users, sonzai.BatchImportUser{
          UserID: userID,
          Metadata: &sonzai.PrimeUserMetadata{
              Custom: map[string]string{&#x22;langchain_session_ids&#x22;: strings.Join(sessionIDs, &#x22;,&#x22;)},
          },
          Content: content,
      })
  }
  return client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
      Source: &#x22;langchain&#x22;,
      Users:  users,
  })
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  job, err := migrateLangchainUsers(context.Background(), client, map[string][]string{ /* … */ })
  if err != nil {
      panic(err)
  }
  fmt.Printf(&#x22;Queued %d users, facts from metadata: %d\\n&#x22;, job.TotalUsers, job.FactsCreated)
}`,
  },
]"
/>

## 4. Verify [#4-verify]

```bash
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '{status,facts_stored,errors}'
```

## Tips [#tips]

* **`SystemMessage` should be stripped.** System prompts describe your chain, not the user. They're noise for the extractor. Filter `msg.type === "system"` before joining.
* **Tool-call messages** (`FunctionMessage` / `ToolMessage`) depend on whether the tool outcome is a user-relevant fact. If the tool looked up the user's order history and the result made it into the assistant's reply, the reply already carries it — drop the raw tool message. If the tool output stands alone, keep it as a `text` block.
* **LangGraph checkpointers** (Postgres / SQLite / Redis) persist conversation state keyed by `thread_id`. The message list inside each checkpoint is the same `BaseMessage[]` — extract via `graph.get_state(config).values["messages"]` and proceed as above.
* **If you're using a vector store for RAG**, that's documents, not memory. Migrate those via [Knowledge Base](/docs/migrating/knowledge-base) instead.

## What's next [#whats-next]

* [Sessions](/docs/sessions) — how to wrap post-migration live chat so session attribution is preserved on every extracted fact.
* [Custom JSON](/docs/migrating/custom-json) — if your LangChain chain wraps a homegrown store that isn't one of the standard backends.
* [Memory](/docs/memory) — how Sonzai handles ongoing memory after migration.


---

# From Letta (MemGPT)

Source: https://sonz.ai/docs/en/guides/migrating/letta

> Migrate core memory blocks and archival memory from Letta (formerly MemGPT) agents into Sonzai. Human blocks become user metadata; archival rows become content.



## What you're migrating [#what-youre-migrating]

Letta (formerly MemGPT) stores memory in two layers:

* **Core memory** — structured blocks always in context. Default blocks are `human` (what the agent knows about the user) and `persona` (who the agent is).
* **Archival memory** — an append-only store of longer recollections the agent can search on demand.

Sonzai keeps the user and the agent strictly separate — **never migrate persona blocks into a user**. The mapping:

| Letta                           | Sonzai                                                                            |
| ------------------------------- | --------------------------------------------------------------------------------- |
| Core memory `human` block       | User `metadata` + one `text` content block                                        |
| Core memory `persona` block     | *Not migrated* — configure in your [agent personality](/docs/personality) instead |
| Archival memory rows            | `text` content blocks on the user                                                 |
| Recall memory (message history) | `chat_transcript` content blocks                                                  |
| Letta user / agent IDs          | `custom` metadata for cross-reference                                             |

## 1. Export from Letta [#1-export-from-letta]

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from letta_client import Letta
letta = Letta(base_url=os.environ[&#x22;LETTA_BASE_URL&#x22;],
            token=os.environ[&#x22;LETTA_API_KEY&#x22;])

def export_letta_agent(agent_id: str):
  # Core memory blocks
  blocks = letta.agents.core_memory.list_blocks(agent_id=agent_id)
  human_block = next((b for b in blocks if b.label == &#x22;human&#x22;), None)

  # Archival memory (paginated)
  archival = []
  cursor = None
  while True:
      page = letta.agents.archival_memory.list(
          agent_id=agent_id, limit=100, after=cursor,
      )
      archival.extend(page)
      if len(page) < 100:
          break
      cursor = page[-1].id

  # Recall / message history
  messages = letta.agents.messages.list(agent_id=agent_id, limit=500)

  return {
      &#x22;human&#x22;:    human_block.value if human_block else &#x22;&#x22;,
      &#x22;archival&#x22;: [row.text for row in archival],
      &#x22;messages&#x22;: messages,
  }`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { LettaClient } from &#x22;@letta-ai/letta-client&#x22;;
const letta = new LettaClient({
baseUrl: process.env.LETTA_BASE_URL!,
token:   process.env.LETTA_API_KEY!,
});

export async function exportLettaAgent(agentId: string) {
// Core memory blocks
const blocks = await letta.agents.coreMemory.listBlocks({ agentId });
const human = blocks.find((b: { label: string }) => b.label === &#x22;human&#x22;);

// Archival memory (paginated)
const archival: { id: string; text: string }[] = [];
let cursor: string | undefined;
while (true) {
  const page = await letta.agents.archivalMemory.list({
    agentId, limit: 100, ...(cursor ? { after: cursor } : {}),
  });
  archival.push(...page);
  if (page.length < 100) break;
  cursor = page[page.length - 1].id;
}

// Recall / message history
const messages = await letta.agents.messages.list({ agentId, limit: 500 });

return {
  human:    human?.value ?? &#x22;&#x22;,
  archival: archival.map((r) => r.text),
  messages,
};
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Letta has no first-party Go SDK at time of writing. Hit the REST API
// directly — Letta's HTTP shape mirrors what the Python/TS SDKs return,
// so the same field names work.
package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;io&#x22;
  &#x22;net/http&#x22;
  &#x22;net/url&#x22;
  &#x22;os&#x22;
)

type lettaBlock struct {
  Label, Value string
}
type lettaArchival struct {
  ID, Text string
}
type lettaMessage struct {
  Role, Text string
}
type LettaExport struct {
  Human    string
  Archival []string
  Messages []lettaMessage
}

func exportLettaAgent(ctx context.Context, agentID string) (*LettaExport, error) {
  base := os.Getenv(&#x22;LETTA_BASE_URL&#x22;)
  tok := os.Getenv(&#x22;LETTA_API_KEY&#x22;)
  get := func(path string, dst any) error {
      req, _ := http.NewRequestWithContext(ctx, &#x22;GET&#x22;, base+path, nil)
      req.Header.Set(&#x22;Authorization&#x22;, &#x22;Bearer &#x22;+tok)
      resp, err := http.DefaultClient.Do(req)
      if err != nil {
          return err
      }
      defer resp.Body.Close()
      body, _ := io.ReadAll(resp.Body)
      return json.Unmarshal(body, dst)
  }

  var blocks []lettaBlock
  if err := get(fmt.Sprintf(&#x22;/v1/agents/%s/core-memory/blocks&#x22;, url.PathEscape(agentID)), &blocks); err != nil {
      return nil, err
  }
  human := &#x22;&#x22;
  for _, b := range blocks {
      if b.Label == &#x22;human&#x22; {
          human = b.Value
          break
      }
  }

  var archival []lettaArchival
  cursor := &#x22;&#x22;
  for {
      var page []lettaArchival
      u := fmt.Sprintf(&#x22;/v1/agents/%s/archival-memory?limit=100&#x22;, url.PathEscape(agentID))
      if cursor != &#x22;&#x22; {
          u += &#x22;&after=&#x22; + url.QueryEscape(cursor)
      }
      if err := get(u, &page); err != nil {
          return nil, err
      }
      archival = append(archival, page...)
      if len(page) < 100 {
          break
      }
      cursor = page[len(page)-1].ID
  }

  var messages []lettaMessage
  if err := get(fmt.Sprintf(&#x22;/v1/agents/%s/messages?limit=500&#x22;, url.PathEscape(agentID)), &messages); err != nil {
      return nil, err
  }

  archText := make([]string, 0, len(archival))
  for _, a := range archival {
      archText = append(archText, a.Text)
  }
  return &LettaExport{Human: human, Archival: archText, Messages: messages}, nil
}`,
  },
]"
/>

## 2. Map to Sonzai's import shape [#2-map-to-sonzais-import-shape]

One Letta agent typically represents one user relationship, so you end up with **one Sonzai user per Letta agent**.

```json
{
  "source": "letta",
  "users": [
    {
      "user_id": "user_123",
      "display_name": "Mia Tanaka",
      "metadata": {
        "custom": {
          "letta_agent_id": "agent-abc",
          "letta_user_id":  "user-xyz"
        }
      },
      "content": [
        { "type": "text", "body": "Mia Tanaka is a platform engineer at Acme, lives in Tokyo, allergic to peanuts, loves hiking." },
        { "type": "text", "body": "Mia mentioned she's planning a trip to Hokkaido in March." },
        { "type": "chat_transcript", "body": "User: ...\nAgent: ..." }
      ]
    }
  ]
}
```

The human block goes in as a single `text` block — it's usually a paragraph of assertions written in natural language, which is exactly what the extractor prefers.

## 3. Import into Sonzai [#3-import-into-sonzai]

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai
sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def migrate_letta_agents(letta_agent_map):
  &#x22;&#x22;&#x22;letta_agent_map: [{letta_agent_id, user_id, display_name, letta_user_id}]&#x22;&#x22;&#x22;
  users = []
  for row in letta_agent_map:
      exp = export_letta_agent(row[&#x22;letta_agent_id&#x22;])

      content = []
      if exp[&#x22;human&#x22;].strip():
          content.append({&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: exp[&#x22;human&#x22;]})
      for text in exp[&#x22;archival&#x22;]:
          content.append({&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: text})

      # Build a role-tagged transcript from Letta's messages
      if exp[&#x22;messages&#x22;]:
          lines = []
          for m in exp[&#x22;messages&#x22;]:
              role = &#x22;User&#x22; if m.role == &#x22;user&#x22; else &#x22;Agent&#x22;
              lines.append(f&#x22;{role}: {m.text or ''}&#x22;)
          content.append({&#x22;type&#x22;: &#x22;chat_transcript&#x22;, &#x22;body&#x22;: &#x22;\\n&#x22;.join(lines)})

      users.append({
          &#x22;user_id&#x22;:      row[&#x22;user_id&#x22;],
          &#x22;display_name&#x22;: row[&#x22;display_name&#x22;],
          &#x22;metadata&#x22;: {
              &#x22;custom&#x22;: {
                  &#x22;letta_agent_id&#x22;: row[&#x22;letta_agent_id&#x22;],
                  &#x22;letta_user_id&#x22;:  row[&#x22;letta_user_id&#x22;],
              },
          },
          &#x22;content&#x22;: content,
      })

  return sonzai.agents.priming.batch_import(
      AGENT_ID, source=&#x22;letta&#x22;, users=users,
  )`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

interface LettaAgentRow {
letta_agent_id: string;
user_id: string;
display_name?: string;
letta_user_id: string;
}

export async function migrateLettaAgents(rows: LettaAgentRow[]) {
const users = await Promise.all(rows.map(async (row) => {
  const exp = await exportLettaAgent(row.letta_agent_id);

  const content: { type: string; body: string }[] = [];
  if (exp.human.trim()) content.push({ type: &#x22;text&#x22;, body: exp.human });
  for (const t of exp.archival) content.push({ type: &#x22;text&#x22;, body: t });

  if (exp.messages.length) {
    const lines = exp.messages.map((m: { role: string; text?: string }) =>
      \`\${m.role === &#x22;user&#x22; ? &#x22;User&#x22; : &#x22;Agent&#x22;}: \${m.text ?? &#x22;&#x22;}\`,
    );
    content.push({ type: &#x22;chat_transcript&#x22;, body: lines.join(&#x22;\\n&#x22;) });
  }

  return {
    user_id:      row.user_id,
    display_name: row.display_name,
    metadata: {
      custom: {
        letta_agent_id: row.letta_agent_id,
        letta_user_id:  row.letta_user_id,
      },
    },
    content,
  };
}));

return sonzai.agents.priming.batchImport(AGENT_ID, {
  source: &#x22;letta&#x22;,
  users,
});
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

type LettaAgentRow struct {
  LettaAgentID, UserID, DisplayName, LettaUserID string
}

func migrateLettaAgents(ctx context.Context, client *sonzai.Client, rows []LettaAgentRow) (*sonzai.BatchImportResponse, error) {
  users := make([]sonzai.BatchImportUser, 0, len(rows))
  for _, row := range rows {
      exp, err := exportLettaAgent(ctx, row.LettaAgentID)
      if err != nil {
          return nil, err
      }
      content := make([]sonzai.PrimeContentBlock, 0)
      if exp.Human != &#x22;&#x22; {
          content = append(content, sonzai.PrimeContentBlock{Type: &#x22;text&#x22;, Body: exp.Human})
      }
      for _, t := range exp.Archival {
          content = append(content, sonzai.PrimeContentBlock{Type: &#x22;text&#x22;, Body: t})
      }
      if len(exp.Messages) > 0 {
          transcript := &#x22;&#x22;
          for _, m := range exp.Messages {
              role := &#x22;Agent&#x22;
              if m.Role == &#x22;user&#x22; {
                  role = &#x22;User&#x22;
              }
              transcript += role + &#x22;: &#x22; + m.Text + &#x22;\\n&#x22;
          }
          content = append(content, sonzai.PrimeContentBlock{Type: &#x22;chat_transcript&#x22;, Body: transcript})
      }
      users = append(users, sonzai.BatchImportUser{
          UserID:      row.UserID,
          DisplayName: row.DisplayName,
          Metadata: &sonzai.PrimeUserMetadata{
              Custom: map[string]string{
                  &#x22;letta_agent_id&#x22;: row.LettaAgentID,
                  &#x22;letta_user_id&#x22;:  row.LettaUserID,
              },
          },
          Content: content,
      })
  }
  return client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
      Source: &#x22;letta&#x22;,
      Users:  users,
  })
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  job, err := migrateLettaAgents(context.Background(), client, []LettaAgentRow{ /* … */ })
  if err != nil {
      panic(err)
  }
  fmt.Printf(&#x22;Queued %d users, facts: %d\\n&#x22;, job.TotalUsers, job.FactsCreated)
}`,
  },
]"
/>

## 4. Verify [#4-verify]

```bash
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '{status,facts_stored,errors}'

curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/memory/facts?user_id=user_123&limit=50" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.facts[].content'
```

## Tips [#tips]

* **Persona blocks stay behind.** The `persona` core-memory block describes the agent — import it into your Sonzai agent's personality and bio via the [Agents API](/docs/api/agents), not into a user.
* **Sleeptime blocks.** Letta's sleeptime-agent output is high-quality summary text — import it as `text` blocks alongside archival rows. Sonzai will dedupe overlap with archival automatically.
* **Tool-call traces** in Letta's message history can be noisy. Filter out `tool_call` / `tool_return` messages before building the transcript unless the tool outcomes are semantically important (e.g. the agent booked a flight).
* **One Letta agent = one Sonzai user.** If you're tempted to import many Letta agents as one Sonzai user, don't — per-user mood, relationship state, and dedup all key off `user_id`. Sonzai handles multiple users per agent natively.

## What's next [#whats-next]

* [Personality](/docs/personality) — where the persona block belongs in Sonzai.
* [Memory](/docs/memory) — how archival and recall collapse into one constellation.


---

# From Mem0

Source: https://sonz.ai/docs/en/guides/migrating/mem0

> Migrate per-user memories from Mem0 into Sonzai. Each Mem0 memory becomes a text block that Sonzai re-ingests, deduplicates, and links into its constellation.



## What you're migrating [#what-youre-migrating]

Mem0 stores memory as a flat list of short strings, one per assertion, keyed by `user_id`. Sonzai stores facts as a deduplicated graph with supersession (old assertions are retired when newer ones contradict them). The mapping is straightforward:

| Mem0          | Sonzai                                                           |
| ------------- | ---------------------------------------------------------------- |
| `user_id`     | `user_id` (keep it identical)                                    |
| Memory string | `text` content block                                             |
| Metadata dict | `custom` metadata                                                |
| Categories    | can be flattened into the `type` field or included in the `body` |

**Why Sonzai re-extracts instead of treating Mem0's strings as final facts:** Sonzai's dedup runs on normalized fact assertions, not free text. Passing the Mem0 strings through the extractor produces consistent shapes that dedupe correctly on subsequent imports or live chat.

## 1. Export from Mem0 [#1-export-from-mem0]

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from mem0 import MemoryClient
mem0 = MemoryClient(api_key=os.environ[&#x22;MEM0_API_KEY&#x22;])

def export_mem0_user(user_id: str):
  memories = mem0.get_all(user_id=user_id)
  # memories is a list of dicts: {id, memory, metadata, categories, created_at, ...}
  return memories`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import MemoryClient from &#x22;mem0ai&#x22;;
const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });

async function exportMem0User(userId: string) {
return await mem0.getAll({ user_id: userId });
// array of { id, memory, metadata, categories, created_at, ... }
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Mem0 has no first-party Go SDK; hit the REST API directly.
package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;io&#x22;
  &#x22;net/http&#x22;
  &#x22;net/url&#x22;
  &#x22;os&#x22;
)

type Mem0Memory struct {
  ID         string         \`json:&#x22;id&#x22;\`
  Memory     string         \`json:&#x22;memory&#x22;\`
  Metadata   map[string]any \`json:&#x22;metadata&#x22;\`
  Categories []string       \`json:&#x22;categories&#x22;\`
  CreatedAt  string         \`json:&#x22;created_at&#x22;\`
}

func exportMem0User(ctx context.Context, userID string) ([]Mem0Memory, error) {
  u, _ := url.Parse(&#x22;https://api.mem0.ai/v1/memories/&#x22;)
  q := u.Query()
  q.Set(&#x22;user_id&#x22;, userID)
  u.RawQuery = q.Encode()

  req, _ := http.NewRequestWithContext(ctx, &#x22;GET&#x22;, u.String(), nil)
  req.Header.Set(&#x22;Authorization&#x22;, &#x22;Token &#x22;+os.Getenv(&#x22;MEM0_API_KEY&#x22;))
  resp, err := http.DefaultClient.Do(req)
  if err != nil {
      return nil, err
  }
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)

  var out []Mem0Memory
  if err := json.Unmarshal(body, &out); err != nil {
      return nil, err
  }
  return out, nil
}`,
  },
]"
/>

## 2. Map to Sonzai's import shape [#2-map-to-sonzais-import-shape]

Each Mem0 memory becomes a `text` block. If you have categories, prepend them to the body for context — the extractor will key off them.

```json
{
  "source": "mem0",
  "users": [
    {
      "user_id": "user_123",
      "metadata": { "custom": { "mem0_user_id": "user_123" } },
      "content": [
        { "type": "text", "body": "[food] Allergic to peanuts." },
        { "type": "text", "body": "[hobbies] Loves hiking on weekends." },
        { "type": "text", "body": "[work] Lead platform engineer at Acme." }
      ]
    }
  ]
}
```

## 3. Import into Sonzai [#3-import-into-sonzai]

<CodeTabs
  tabs="[
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai
sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def migrate_mem0_users(user_ids):
  users = []
  for uid in user_ids:
      memories = export_mem0_user(uid)
      content = []
      for m in memories:
          cats = &#x22;,&#x22;.join(m.get(&#x22;categories&#x22;) or [])
          prefix = f&#x22;[{cats}] &#x22; if cats else &#x22;&#x22;
          content.append({
              &#x22;type&#x22;: &#x22;text&#x22;,
              &#x22;body&#x22;: prefix + m[&#x22;memory&#x22;],
          })
      users.append({
          &#x22;user_id&#x22;: uid,
          &#x22;metadata&#x22;: {&#x22;custom&#x22;: {&#x22;mem0_user_id&#x22;: uid}},
          &#x22;content&#x22;: content,
      })
  return sonzai.agents.priming.batch_import(
      AGENT_ID, source=&#x22;mem0&#x22;, users=users,
  )`,
  },
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

async function migrateMem0Users(userIds: string[]) {
const users = await Promise.all(userIds.map(async (uid) => {
  const memories = await exportMem0User(uid);
  const content = memories.map((m: any) => {
    const cats = (m.categories || []).join(&#x22;,&#x22;);
    const prefix = cats ? \`[\${cats}] \` : &#x22;&#x22;;
    return { type: &#x22;text&#x22;, body: prefix + m.memory };
  });
  return {
    user_id: uid,
    metadata: { custom: { mem0_user_id: uid } },
    content,
  };
}));

return sonzai.agents.priming.batchImport(AGENT_ID, {
  source: &#x22;mem0&#x22;,
  users,
});
}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

// Mem0Memory mirrors the fields you actually need from Mem0's export.
type Mem0Memory struct {
  Memory     string
  Categories []string
}

func migrateMem0Users(ctx context.Context, client *sonzai.Client, byUser map[string][]Mem0Memory) (*sonzai.BatchImportResponse, error) {
  users := make([]sonzai.BatchImportUser, 0, len(byUser))
  for uid, memories := range byUser {
      content := make([]sonzai.PrimeContentBlock, 0, len(memories))
      for _, m := range memories {
          prefix := &#x22;&#x22;
          if cats := strings.Join(m.Categories, &#x22;,&#x22;); cats != &#x22;&#x22; {
              prefix = &#x22;[&#x22; + cats + &#x22;] &#x22;
          }
          content = append(content, sonzai.PrimeContentBlock{
              Type: &#x22;text&#x22;,
              Body: prefix + m.Memory,
          })
      }
      users = append(users, sonzai.BatchImportUser{
          UserID: uid,
          Metadata: &sonzai.PrimeUserMetadata{
              Custom: map[string]string{&#x22;mem0_user_id&#x22;: uid},
          },
          Content: content,
      })
  }
  return client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
      Source: &#x22;mem0&#x22;,
      Users:  users,
  })
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  job, err := migrateMem0Users(context.Background(), client, map[string][]Mem0Memory{ /* … */ })
  if err != nil {
      panic(err)
  }
  fmt.Printf(&#x22;Queued %d users, facts from metadata: %d\\n&#x22;, job.TotalUsers, job.FactsCreated)
}`,
  },
]"
/>

## 4. Verify [#4-verify]

```bash
# Job status
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '{status,facts_stored,facts_deduped}'

# Facts for one migrated user
curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/memory/facts?user_id=user_123&limit=50" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.facts[].content'
```

Expect `facts_stored` to be roughly the same as the number of Mem0 memories you shipped, minus any that collapsed into duplicates.

## Tips [#tips]

* **Metadata dicts from Mem0.** If a Mem0 memory had a `metadata` dict (e.g. `{"importance": "high"}`), inline it into the body as `"[importance=high] ..."`. Sonzai's `custom` metadata is user-level, not fact-level, so fact-scoped context belongs in the body.
* **Dedup against existing Sonzai memory.** If you're importing into an agent that already has some facts for a user (e.g. from live chat), Sonzai will supersede rather than duplicate. The `facts_deduped` counter in the job status tells you how many collapsed.
* **Order.** Sonzai doesn't require a specific order, but if your Mem0 data has `created_at` timestamps and you care about temporal recency, send memories oldest-first — the extractor stamps its own timestamps but content arriving later is treated as more recent.

## What's next [#whats-next]

* [Memory](/docs/memory) — how supersession works inside the constellation.
* [Self-improvement](/docs/self-improvement) — how agents use migrated memory to adapt over time.


---

# From OpenAI Assistants

Source: https://sonz.ai/docs/en/guides/migrating/openai-assistants

> Migrate threads and messages from the OpenAI Assistants API into Sonzai. One thread per user, full message history preserved as chat transcripts.



## What you're migrating [#what-youre-migrating]

The OpenAI Assistants API persists conversation history inside **threads**. Each thread holds an ordered list of messages. Typically one thread maps to one end-user of your product, so the natural migration is:

* **One OpenAI thread → one Sonzai user** (keyed by your own `user_id`)
* **Thread messages → one `chat_transcript` content block per thread** (or several, if the thread is very long)
* **Assistant instructions** stay in your Sonzai agent config — they don't move with the user.

<Callout type="info" title="Heads up">
  OpenAI's Assistants API was announced for deprecation in favour of the Responses API. Thread and message endpoints remain readable for now, and the export snippets below work against either. If your app has moved to Responses, see [Custom JSON](/docs/migrating/custom-json) instead.
</Callout>

## 1. Export threads and messages from OpenAI [#1-export-threads-and-messages-from-openai]

You need the OpenAI thread ID and, for each thread, the end-user identifier you want to key Sonzai memory against. That mapping usually lives in your own database (a `users` table that stores `openai_thread_id`).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import OpenAI from &#x22;openai&#x22;;
const openai = new OpenAI();

// threadMap: your DB mapping of your user_id -> OpenAI thread_id
async function exportThread(threadId: string): Promise<string> {
const all: string[] = [];
let after: string | undefined;
while (true) {
  const page = await openai.beta.threads.messages.list(threadId, {
    order: &#x22;asc&#x22;,
    limit: 100,
    ...(after ? { after } : {}),
  });
  for (const m of page.data) {
    const text = m.content
      .filter(c => c.type === &#x22;text&#x22;)
      .map(c => (c as any).text.value)
      .join(&#x22;\\n&#x22;);
    all.push(\`\${m.role === &#x22;user&#x22; ? &#x22;User&#x22; : &#x22;Agent&#x22;}: \${text}\`);
  }
  if (!page.has_more) break;
  after = page.data[page.data.length - 1].id;
}
return all.join(&#x22;\\n\\n&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from openai import OpenAI
openai = OpenAI()

def export_thread(thread_id: str) -> str:
  lines, after = [], None
  while True:
      page = openai.beta.threads.messages.list(
          thread_id=thread_id,
          order=&#x22;asc&#x22;,
          limit=100,
          **({&#x22;after&#x22;: after} if after else {}),
      )
      for m in page.data:
          text = &#x22;\\n&#x22;.join(
              c.text.value for c in m.content if c.type == &#x22;text&#x22;
          )
          role = &#x22;User&#x22; if m.role == &#x22;user&#x22; else &#x22;Agent&#x22;
          lines.append(f&#x22;{role}: {text}&#x22;)
      if not page.has_more:
          break
      after = page.data[-1].id
  return &#x22;\\n\\n&#x22;.join(lines)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// OpenAI has no first-party Go SDK for the legacy Assistants API,
// so this calls the REST endpoint directly. The shape mirrors what the
// Python / Node SDKs return.
package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;io&#x22;
  &#x22;net/http&#x22;
  &#x22;net/url&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;
)

type oaContent struct {
  Type string \`json:&#x22;type&#x22;\`
  Text struct {
      Value string \`json:&#x22;value&#x22;\`
  } \`json:&#x22;text&#x22;\`
}
type oaMessage struct {
  ID, Role string
  Content  []oaContent \`json:&#x22;content&#x22;\`
}
type oaPage struct {
  Data    []oaMessage \`json:&#x22;data&#x22;\`
  HasMore bool        \`json:&#x22;has_more&#x22;\`
}

func exportThread(ctx context.Context, threadID string) (string, error) {
  apiKey := os.Getenv(&#x22;OPENAI_API_KEY&#x22;)
  var lines []string
  after := &#x22;&#x22;
  for {
      u, _ := url.Parse(fmt.Sprintf(&#x22;https://api.openai.com/v1/threads/%s/messages&#x22;, url.PathEscape(threadID)))
      q := u.Query()
      q.Set(&#x22;order&#x22;, &#x22;asc&#x22;)
      q.Set(&#x22;limit&#x22;, &#x22;100&#x22;)
      if after != &#x22;&#x22; {
          q.Set(&#x22;after&#x22;, after)
      }
      u.RawQuery = q.Encode()

      req, _ := http.NewRequestWithContext(ctx, &#x22;GET&#x22;, u.String(), nil)
      req.Header.Set(&#x22;Authorization&#x22;, &#x22;Bearer &#x22;+apiKey)
      req.Header.Set(&#x22;OpenAI-Beta&#x22;, &#x22;assistants=v2&#x22;)
      resp, err := http.DefaultClient.Do(req)
      if err != nil {
          return &#x22;&#x22;, err
      }
      body, _ := io.ReadAll(resp.Body)
      resp.Body.Close()
      if resp.StatusCode != 200 {
          return &#x22;&#x22;, fmt.Errorf(&#x22;openai %d: %s&#x22;, resp.StatusCode, body)
      }

      var page oaPage
      if err := json.Unmarshal(body, &page); err != nil {
          return &#x22;&#x22;, err
      }
      for _, m := range page.Data {
          parts := make([]string, 0, len(m.Content))
          for _, c := range m.Content {
              if c.Type == &#x22;text&#x22; {
                  parts = append(parts, c.Text.Value)
              }
          }
          role := &#x22;Agent&#x22;
          if m.Role == &#x22;user&#x22; {
              role = &#x22;User&#x22;
          }
          lines = append(lines, fmt.Sprintf(&#x22;%s: %s&#x22;, role, strings.Join(parts, &#x22;\\n&#x22;)))
      }
      if !page.HasMore || len(page.Data) == 0 {
          break
      }
      after = page.Data[len(page.Data)-1].ID
  }
  return strings.Join(lines, &#x22;\\n\\n&#x22;), nil
}`,
  },
]"
/>

## 2. Map to Sonzai's batch import shape [#2-map-to-sonzais-batch-import-shape]

Wrap each exported transcript in a `chat_transcript` content block and assemble the batch. Keep `user_id` stable across systems — if your app already uses `user_123` as the key, use it here too.

```json
{
  "source": "openai_assistants",
  "users": [
    {
      "user_id": "user_123",
      "display_name": "Mia Tanaka",
      "metadata": {
        "email": "mia@example.com",
        "custom": { "openai_thread_id": "thread_abc123" }
      },
      "content": [
        {
          "type": "chat_transcript",
          "body": "User: My name is Mia...\nAgent: Nice to meet you..."
        }
      ]
    }
  ]
}
```

The `openai_thread_id` in `custom` is optional but useful for debugging — Sonzai stores custom fields verbatim so you can cross-reference back to OpenAI if needed.

## 3. Import into Sonzai [#3-import-into-sonzai]

Batch up to a few hundred users per call. Bigger migrations should page through in batches of \~200.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

// userMap comes from your DB: { user_id, display_name, email, openai_thread_id }
async function migrateBatch(userMap: UserRow[]) {
const users = await Promise.all(userMap.map(async (u) => ({
  user_id: u.user_id,
  display_name: u.display_name,
  metadata: {
    email: u.email,
    custom: { openai_thread_id: u.openai_thread_id },
  },
  content: [{
    type: &#x22;chat_transcript&#x22;,
    body: await exportThread(u.openai_thread_id),
  }],
})));

const job = await sonzai.agents.priming.batchImport(AGENT_ID, {
  source: &#x22;openai_assistants&#x22;,
  users,
});
console.log(\`Queued \${job.total_users} users, facts from metadata: \${job.facts_created}\`);
return job.job_id;
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def migrate_batch(user_rows):
  users = []
  for u in user_rows:
      users.append({
          &#x22;user_id&#x22;:      u[&#x22;user_id&#x22;],
          &#x22;display_name&#x22;: u[&#x22;display_name&#x22;],
          &#x22;metadata&#x22;: {
              &#x22;email&#x22;:  u[&#x22;email&#x22;],
              &#x22;custom&#x22;: {&#x22;openai_thread_id&#x22;: u[&#x22;openai_thread_id&#x22;]},
          },
          &#x22;content&#x22;: [{
              &#x22;type&#x22;: &#x22;chat_transcript&#x22;,
              &#x22;body&#x22;: export_thread(u[&#x22;openai_thread_id&#x22;]),
          }],
      })
  job = sonzai.agents.priming.batch_import(
      AGENT_ID,
      source=&#x22;openai_assistants&#x22;,
      users=users,
  )
  print(f&#x22;Queued {job.total_users} users, facts from metadata: {job.facts_created}&#x22;)
  return job.job_id`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

type UserRow struct {
  UserID, DisplayName, Email, OpenAIThreadID string
}

func migrateBatch(ctx context.Context, client *sonzai.Client, rows []UserRow) (string, error) {
  users := make([]sonzai.BatchImportUser, 0, len(rows))
  for _, u := range rows {
      body, err := exportThread(ctx, u.OpenAIThreadID)
      if err != nil {
          return &#x22;&#x22;, err
      }
      users = append(users, sonzai.BatchImportUser{
          UserID:      u.UserID,
          DisplayName: u.DisplayName,
          Metadata: &sonzai.PrimeUserMetadata{
              Email:  u.Email,
              Custom: map[string]string{&#x22;openai_thread_id&#x22;: u.OpenAIThreadID},
          },
          Content: []sonzai.PrimeContentBlock{
              {Type: &#x22;chat_transcript&#x22;, Body: body},
          },
      })
  }
  job, err := client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
      Source: &#x22;openai_assistants&#x22;,
      Users:  users,
  })
  if err != nil {
      return &#x22;&#x22;, err
  }
  fmt.Printf(&#x22;Queued %d users, facts from metadata: %d\\n&#x22;, job.TotalUsers, job.FactsCreated)
  return job.JobID, nil
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  _, _ = migrateBatch(context.Background(), client, []UserRow{ /* … */ })
}`,
  },
]"
/>

## 4. Verify [#4-verify]

Poll until the job completes, then spot-check a user.

```bash
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.status,.facts_stored,.errors'

# Spot-check extracted facts for one user
curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/memory/facts?user_id=user_123&limit=20" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.facts[].content'
```

A healthy job ends with `status: "completed"`, `errors: []`, and a non-zero `facts_stored`.

## Tips [#tips]

* **Run assistant messages aren't included by default.** `messages.list` returns only the assistant's final replies and user turns, which is exactly what you want for a transcript. If you also want tool-call traces in Sonzai's memory, append them as separate `{ "type": "note", "body": "..." }` blocks.
* **Long threads.** If a thread exceeds \~30k tokens, split it into multiple `chat_transcript` blocks (e.g. one per week). The extractor processes them independently.
* **Personas.** OpenAI's assistant-level instructions describe the *agent*, not the user. Don't import them here — put them in your Sonzai agent's personality config instead.

## What's next [#whats-next]

* [Custom JSON](/docs/migrating/custom-json) — if you're on the Responses API or have your own store.
* [Conversations](/docs/conversations) — how ongoing chats add to memory automatically after migration.


---

# Migrating to Sonzai

Source: https://sonz.ai/docs/en/guides/migrating/overview

> Bring users, chat history, memories, and documents from your existing AI stack into Sonzai's memory constellation. One overview page plus a tutorial for every common source system.



## Why migrate [#why-migrate]

Most memory systems store strings. Sonzai builds a **memory constellation**: every incoming piece of content is passed through a fact-extraction pipeline, deduplicated against what the agent already knows, linked into a graph, and surfaced automatically during future conversations. Per-user mood, relationship state, and proactive wakeups all key off that constellation.

If you're coming from a raw transcript store, a RAG index, or a memory-as-a-service vendor, you get three things by migrating:

1. **Automatic fact extraction + supersession** — no more manually curating which memories matter.
2. **Per-user state** — mood, relationship depth, goals, and habits tracked separately for every user of the same agent.
3. **One import, many agents** — migrated users are usable by any agent in the project, not tied to a single thread.

## The import surfaces [#the-import-surfaces]

Sonzai exposes three endpoints for bringing data in. Pick based on shape:

| You have...                                                       | Use             | Endpoint                                                |
| ----------------------------------------------------------------- | --------------- | ------------------------------------------------------- |
| Many users at once (chat histories, CRM contacts, memory exports) | Batch import    | `POST /api/v1/agents/{agentId}/users/import`            |
| One user with rich metadata + content                             | Prime user      | `POST /api/v1/agents/{agentId}/users/{userId}/prime`    |
| More content for a user already in Sonzai                         | Add content     | `POST /api/v1/agents/{agentId}/users/{userId}/content`  |
| Documents (PDF / DOCX / MD / TXT) for the knowledge base          | Upload document | `POST /api/v1/projects/{projectId}/knowledge/documents` |

Full field-level reference for the priming endpoints lives in [API → Priming](/docs/api/priming). The tutorials below show how to shape data *from* each source system into these endpoints.

## How the pipeline works [#how-the-pipeline-works]

Every call to an import endpoint is **asynchronous** and returns a `job_id`.

<Diagram>
  {`
    Your data
     |
     v
    +----------------------+
    | Metadata fields      | --> facts generated synchronously (fast)
    +----------------------+
    +----------------------+      NATS queue
    | Content blocks       | ---------------> LLM fact extraction
    +----------------------+                       |
                                                 v
                                      Memory constellation
                                      (dedup + supersession)
    `}
</Diagram>

* **Metadata** (`display_name`, `company`, `title`, `email`, `phone`, `custom`) is converted into facts on the spot. The response tells you how many.
* **Content blocks** are queued to NATS; a worker runs LLM extraction against them and merges the results into the user's memory tree.
* **Job status** is pollable at `GET /api/v1/agents/{agentId}/users/import/{jobId}` for batch imports (or `.../users/{userId}/prime/{jobId}` for single-user primes). When `status` is `completed`, extraction is done.

This means a big batch import returns quickly (`HTTP 202 Accepted`) and then keeps processing in the background.

## Content block shape [#content-block-shape]

Every content-carrying payload uses the same block shape:

```json
{ "type": "chat_transcript", "body": "User: Hi\nAgent: Hey Mia, how's the hiking been?" }
```

* `type` — a free-form label. Common values: `"text"`, `"chat_transcript"`, `"note"`, `"bio"`. The extractor uses the label as a hint but doesn't reject unknown values.
* `body` — raw text. Split long transcripts across multiple blocks if you prefer, or pack one session per block. Either works.

## The `source` field [#the-source-field]

All three priming endpoints accept an optional top-level `source` string. It is purely provenance metadata — the backend stores it on the import job and the resulting facts. It does **not** change behaviour. Pick whatever is meaningful to you:

```json
{ "source": "openai_assistants", "users": [ ... ] }
```

Suggested values used throughout the tutorials below: `openai_assistants`, `zep`, `mem0`, `letta`, `langchain`, `character_ai`, `replika`, `custom_json`, `crm`.

## Pick your migration path [#pick-your-migration-path]

<Cards>
  <Card href="/docs/migrating/openai-assistants" title="OpenAI Assistants" description="Threads + messages → batch import with chat_transcript blocks" />

  <Card href="/docs/migrating/zep" title="Zep (getzep)" description="User memory + session transcripts → facts + transcripts" />

  <Card href="/docs/migrating/mem0" title="Mem0" description="Per-user memory strings → text blocks" />

  <Card href="/docs/migrating/letta" title="Letta / MemGPT" description="Core + archival memory → metadata + content" />

  <Card href="/docs/migrating/langchain" title="LangChain memory" description="ConversationBufferMemory / ChatMessageHistory → transcripts" />

  <Card href="/docs/migrating/character-ai" title="Character.AI / Replika" description="Companion exports → agent + users + chat history" />

  <Card href="/docs/migrating/custom-json" title="Custom JSON" description="Homegrown chat stores → generic batch import" />

  <Card href="/docs/migrating/crm-csv" title="CRM / CSV" description="Structured contact data → deterministic facts" />

  <Card href="/docs/migrating/knowledge-base" title="Knowledge base documents" description="PDFs, DOCX, MD, TXT → knowledge graph" />
</Cards>

## A minimal end-to-end example [#a-minimal-end-to-end-example]

If you just want to see the whole loop once before diving into a source-specific guide:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

// 1. Import
const job = await client.agents.priming.batchImport(AGENT_ID, {
source: &#x22;custom_json&#x22;,
users: [
  {
    user_id: &#x22;user_123&#x22;,
    display_name: &#x22;Mia Tanaka&#x22;,
    metadata: { email: &#x22;mia@example.com&#x22;, company: &#x22;Acme&#x22; },
    content: [
      { type: &#x22;chat_transcript&#x22;, body: &#x22;User: I'm allergic to peanuts.\\nAgent: Noted.&#x22; },
    ],
  },
],
});
console.log(job.job_id, job.total_users, job.facts_created);

// 2. Poll for completion
let status = await client.agents.priming.getImportStatus(AGENT_ID, job.job_id);
while (status.status !== &#x22;completed&#x22; && status.status !== &#x22;failed&#x22;) {
await new Promise(r => setTimeout(r, 2000));
status = await client.agents.priming.getImportStatus(AGENT_ID, job.job_id);
}
console.log(status);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, time
from sonzai import Sonzai

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

# 1. Import
job = client.agents.priming.batch_import(
  AGENT_ID,
  source=&#x22;custom_json&#x22;,
  users=[{
      &#x22;user_id&#x22;: &#x22;user_123&#x22;,
      &#x22;display_name&#x22;: &#x22;Mia Tanaka&#x22;,
      &#x22;metadata&#x22;: {&#x22;email&#x22;: &#x22;mia@example.com&#x22;, &#x22;company&#x22;: &#x22;Acme&#x22;},
      &#x22;content&#x22;: [
          {&#x22;type&#x22;: &#x22;chat_transcript&#x22;,
           &#x22;body&#x22;: &#x22;User: I'm allergic to peanuts.\\nAgent: Noted.&#x22;},
      ],
  }],
)
print(job.job_id, job.total_users, job.facts_created)

# 2. Poll for completion
status = client.agents.priming.get_import_status(AGENT_ID, job.job_id)
while status.status not in (&#x22;completed&#x22;, &#x22;failed&#x22;):
  time.sleep(2)
  status = client.agents.priming.get_import_status(AGENT_ID, job.job_id)
print(status)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;time&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  ctx := context.Background()
  const AgentID = &#x22;agent_abc&#x22;

  // 1. Import
  job, err := client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
      Source: &#x22;custom_json&#x22;,
      Users: []sonzai.BatchImportUser{
          {
              UserID:      &#x22;user_123&#x22;,
              DisplayName: &#x22;Mia Tanaka&#x22;,
              Metadata: &sonzai.PrimeUserMetadata{
                  Email:   &#x22;mia@example.com&#x22;,
                  Company: &#x22;Acme&#x22;,
              },
              Content: []sonzai.PrimeContentBlock{
                  {Type: &#x22;chat_transcript&#x22;, Body: &#x22;User: I'm allergic to peanuts.\\nAgent: Noted.&#x22;},
              },
          },
      },
  })
  if err != nil {
      panic(err)
  }
  fmt.Println(job.JobID, job.TotalUsers, job.FactsCreated)

  // 2. Poll for completion
  status, _ := client.Priming.GetImportStatus(ctx, AgentID, job.JobID)
  for status.Status != &#x22;completed&#x22; && status.Status != &#x22;failed&#x22; {
      time.Sleep(2 * time.Second)
      status, _ = client.Priming.GetImportStatus(ctx, AgentID, job.JobID)
  }
  fmt.Printf(&#x22;%+v\\n&#x22;, status)
}`,
  },
  {
    id: &#x22;curl&#x22;,
    label: &#x22;curl&#x22;,
    code: `# 1. Import
curl -s -X POST https://api.sonz.ai/api/v1/agents/agent_abc/users/import \\
-H &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;source&#x22;: &#x22;custom_json&#x22;,
  &#x22;users&#x22;: [{
    &#x22;user_id&#x22;: &#x22;user_123&#x22;,
    &#x22;display_name&#x22;: &#x22;Mia Tanaka&#x22;,
    &#x22;metadata&#x22;: {&#x22;email&#x22;: &#x22;mia@example.com&#x22;, &#x22;company&#x22;: &#x22;Acme&#x22;},
    &#x22;content&#x22;: [
      {&#x22;type&#x22;: &#x22;chat_transcript&#x22;,
       &#x22;body&#x22;: &#x22;User: Im allergic to peanuts.\\nAgent: Noted.&#x22;}
    ]
  }]
}'
# => { &#x22;job_id&#x22;: &#x22;...&#x22;, &#x22;status&#x22;: &#x22;queued&#x22;, &#x22;total_users&#x22;: 1, &#x22;facts_created&#x22;: 3 }

# 2. Poll
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \\
-H &#x22;Authorization: Bearer $SONZAI_API_KEY&#x22;`,
  },
]"
/>

Once the job completes, call `GET /api/v1/agents/{agentId}/users` to confirm the user is there with the extracted facts attached.

## What happens to the data [#what-happens-to-the-data]

After a successful import you have, per user:

* An entry in the agent's user list (`GET /api/v1/agents/{agentId}/users`)
* A priming metadata record (`GET /api/v1/agents/{agentId}/users/{userId}/metadata`)
* Extracted facts in the memory constellation (`GET /api/v1/agents/{agentId}/memory/facts?user_id=...`)
* An initial mood state derived from the agent's Big5 baseline
* Read access to the agent granted automatically

You can now chat with the agent as that user and every extracted fact is available for retrieval.


---

# From Zep (getzep)

Source: https://sonz.ai/docs/en/guides/migrating/zep

> Migrate users, sessions, and extracted facts from Zep's memory graph into Sonzai. Preserve either the raw chat history, the already-extracted facts, or both.



## What you're migrating [#what-youre-migrating]

Zep and Sonzai solve the same problem — persistent, structured agent memory — but with different primitives. Here's how they line up:

| Zep                     | Sonzai                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User                    | User (same `user_id` works fine)                                                                                                                                                                                                                                                                                                                          |
| Session                 | Session — Sonzai has first-class sessions (`sessions.start` / `sessions.end`) and preserves the exact `session_id` on every extracted fact. For the bulk migration below we flatten historical sessions into `chat_transcript` blocks (one block per session); live chat post-migration should use real Sonzai sessions — see [Sessions](/docs/sessions). |
| Message (in a session)  | `chat_transcript` content block                                                                                                                                                                                                                                                                                                                           |
| Fact (extracted by Zep) | `text` content block — Sonzai will re-extract and dedupe against existing memory                                                                                                                                                                                                                                                                          |
| User metadata           | Sonzai `metadata` (`email`, `company`, `custom`)                                                                                                                                                                                                                                                                                                          |

You have **two viable migration strategies**:

1. **Re-extract from raw transcripts** — ship the session messages to Sonzai and let Sonzai's extraction pipeline rebuild facts. Highest fidelity, slowest to process.
2. **Forward Zep's facts** — ship Zep's already-extracted fact strings as `text` blocks. Faster, but depends on Zep's extraction quality.

You can do both in the same import. Sonzai will deduplicate across content blocks.

## 1. Export from Zep [#1-export-from-zep]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { ZepClient } from &#x22;@getzep/zep-cloud&#x22;;
const zep = new ZepClient({ apiKey: process.env.ZEP_API_KEY! });

async function exportZepUser(userId: string) {
const user = await zep.user.get(userId);
const sessions = await zep.user.getSessions(userId);

// Flatten all session messages into a single transcript, newest last
const transcripts: string[] = [];
for (const s of sessions) {
  const messages = await zep.memory.getSessionMessages(s.sessionId!);
  const lines = messages.map(m =>
    \`\${m.role === &#x22;user&#x22; ? &#x22;User&#x22; : &#x22;Agent&#x22;}: \${m.content}\`
  );
  transcripts.push(\`[session \${s.sessionId}]\\n\${lines.join(&#x22;\\n&#x22;)}\`);
}

// Pull Zep's own extracted facts about the user
const memory = await zep.user.getFacts(userId).catch(() => ({ facts: [] }));

return { user, transcripts, facts: memory.facts ?? [] };
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from zep_cloud.client import Zep
zep = Zep(api_key=os.environ[&#x22;ZEP_API_KEY&#x22;])

def export_zep_user(user_id: str):
  user = zep.user.get(user_id)
  sessions = zep.user.get_sessions(user_id)

  transcripts = []
  for s in sessions:
      messages = zep.memory.get_session_messages(s.session_id).messages
      lines = [
          f&#x22;{'User' if m.role == 'user' else 'Agent'}: {m.content}&#x22;
          for m in messages
      ]
      transcripts.append(f&#x22;[session {s.session_id}]\\n&#x22; + &#x22;\\n&#x22;.join(lines))

  try:
      facts = zep.user.get_facts(user_id).facts or []
  except Exception:
      facts = []

  return {&#x22;user&#x22;: user, &#x22;transcripts&#x22;: transcripts, &#x22;facts&#x22;: facts}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Zep ships TS + Python SDKs; for Go, hit the REST API directly.
package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;io&#x22;
  &#x22;net/http&#x22;
  &#x22;os&#x22;
)

type ZepUser struct {
  UserID, FirstName, LastName, Email string
}
type ZepSession struct {
  SessionID string \`json:&#x22;session_id&#x22;\`
}
type ZepMessage struct {
  Role, Content string
}
type ZepFact struct {
  Fact string
}
type ZepExport struct {
  User        ZepUser
  Transcripts []string
  Facts       []string
}

func zepGet(ctx context.Context, path string, dst any) error {
  base := os.Getenv(&#x22;ZEP_BASE_URL&#x22;)
  if base == &#x22;&#x22; {
      base = &#x22;https://api.getzep.com&#x22;
  }
  req, _ := http.NewRequestWithContext(ctx, &#x22;GET&#x22;, base+path, nil)
  req.Header.Set(&#x22;Authorization&#x22;, &#x22;Api-Key &#x22;+os.Getenv(&#x22;ZEP_API_KEY&#x22;))
  resp, err := http.DefaultClient.Do(req)
  if err != nil {
      return err
  }
  defer resp.Body.Close()
  body, _ := io.ReadAll(resp.Body)
  return json.Unmarshal(body, dst)
}

func exportZepUser(ctx context.Context, userID string) (*ZepExport, error) {
  var user ZepUser
  if err := zepGet(ctx, &#x22;/api/v2/users/&#x22;+userID, &user); err != nil {
      return nil, err
  }
  var sessions []ZepSession
  if err := zepGet(ctx, &#x22;/api/v2/users/&#x22;+userID+&#x22;/sessions&#x22;, &sessions); err != nil {
      return nil, err
  }
  var transcripts []string
  for _, s := range sessions {
      var msgs struct {
          Messages []ZepMessage \`json:&#x22;messages&#x22;\`
      }
      if err := zepGet(ctx, &#x22;/api/v2/sessions/&#x22;+s.SessionID+&#x22;/messages&#x22;, &msgs); err != nil {
          return nil, err
      }
      var transcript string
      for _, m := range msgs.Messages {
          role := &#x22;Agent&#x22;
          if m.Role == &#x22;user&#x22; {
              role = &#x22;User&#x22;
          }
          transcript += role + &#x22;: &#x22; + m.Content + &#x22;\\n&#x22;
      }
      transcripts = append(transcripts, fmt.Sprintf(&#x22;[session %s]\\n%s&#x22;, s.SessionID, transcript))
  }
  var factResp struct {
      Facts []ZepFact \`json:&#x22;facts&#x22;\`
  }
  _ = zepGet(ctx, &#x22;/api/v2/users/&#x22;+userID+&#x22;/facts&#x22;, &factResp) // tolerate 404
  facts := make([]string, 0, len(factResp.Facts))
  for _, f := range factResp.Facts {
      facts = append(facts, f.Fact)
  }
  return &ZepExport{User: user, Transcripts: transcripts, Facts: facts}, nil
}`,
  },
]"
/>

## 2. Map to Sonzai's import shape [#2-map-to-sonzais-import-shape]

Pack each session as its own `chat_transcript` block (preserves recency) and the extracted facts as `text` blocks.

```json
{
  "source": "zep",
  "users": [
    {
      "user_id": "user_123",
      "display_name": "Mia Tanaka",
      "metadata": {
        "email": "mia@example.com",
        "custom": { "zep_user_id": "mia_123" }
      },
      "content": [
        { "type": "chat_transcript", "body": "[session 01H...]\nUser: ...\nAgent: ..." },
        { "type": "chat_transcript", "body": "[session 01J...]\nUser: ...\nAgent: ..." },
        { "type": "text", "body": "Mia is allergic to peanuts." },
        { "type": "text", "body": "Mia works at Acme and leads the platform team." }
      ]
    }
  ]
}
```

The extractor runs on every block; `text` blocks with a single assertion are cheap to process and dedupe quickly against existing memory.

## 3. Import into Sonzai [#3-import-into-sonzai]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;

async function migrateZepUsers(zepUserIds: string[]) {
const users = await Promise.all(zepUserIds.map(async (zepId) => {
  const { user, transcripts, facts } = await exportZepUser(zepId);
  return {
    user_id:      user.userId!,       // keep stable IDs across systems
    display_name: user.firstName ? \`\${user.firstName} \${user.lastName ?? &#x22;&#x22;}\`.trim() : undefined,
    metadata: {
      email:  user.email,
      custom: { zep_user_id: zepId },
    },
    content: [
      ...transcripts.map(body => ({ type: &#x22;chat_transcript&#x22;, body })),
      ...facts.map(f => ({ type: &#x22;text&#x22;, body: f.fact ?? String(f) })),
    ],
  };
}));

const job = await sonzai.agents.priming.batchImport(AGENT_ID, {
  source: &#x22;zep&#x22;,
  users,
});
return job;
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os
from sonzai import Sonzai
sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;

def migrate_zep_users(zep_user_ids):
  users = []
  for zep_id in zep_user_ids:
      exp = export_zep_user(zep_id)
      user = exp[&#x22;user&#x22;]
      first = user.first_name or &#x22;&#x22;
      last  = user.last_name or &#x22;&#x22;
      display = (first + &#x22; &#x22; + last).strip() or None

      content = [{&#x22;type&#x22;: &#x22;chat_transcript&#x22;, &#x22;body&#x22;: t} for t in exp[&#x22;transcripts&#x22;]]
      content += [
          {&#x22;type&#x22;: &#x22;text&#x22;, &#x22;body&#x22;: f.fact if hasattr(f, &#x22;fact&#x22;) else str(f)}
          for f in exp[&#x22;facts&#x22;]
      ]

      users.append({
          &#x22;user_id&#x22;:      user.user_id,
          &#x22;display_name&#x22;: display,
          &#x22;metadata&#x22;: {
              &#x22;email&#x22;:  user.email,
              &#x22;custom&#x22;: {&#x22;zep_user_id&#x22;: zep_id},
          },
          &#x22;content&#x22;: content,
      })

  return sonzai.agents.priming.batch_import(
      AGENT_ID, source=&#x22;zep&#x22;, users=users,
  )`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const AgentID = &#x22;agent_abc&#x22;

// Plug your own zep client + ZepExport struct in here.
type ZepExport struct {
  UserID, FirstName, LastName, Email string
  Transcripts                        []string
  Facts                              []string
}

func migrateZepUsers(ctx context.Context, client *sonzai.Client, exports []ZepExport) (*sonzai.BatchImportResponse, error) {
  users := make([]sonzai.BatchImportUser, 0, len(exports))
  for _, e := range exports {
      display := strings.TrimSpace(e.FirstName + &#x22; &#x22; + e.LastName)

      content := make([]sonzai.PrimeContentBlock, 0, len(e.Transcripts)+len(e.Facts))
      for _, t := range e.Transcripts {
          content = append(content, sonzai.PrimeContentBlock{Type: &#x22;chat_transcript&#x22;, Body: t})
      }
      for _, f := range e.Facts {
          content = append(content, sonzai.PrimeContentBlock{Type: &#x22;text&#x22;, Body: f})
      }

      users = append(users, sonzai.BatchImportUser{
          UserID:      e.UserID,
          DisplayName: display,
          Metadata: &sonzai.PrimeUserMetadata{
              Email:  e.Email,
              Custom: map[string]string{&#x22;zep_user_id&#x22;: e.UserID},
          },
          Content: content,
      })
  }
  return client.Priming.BatchImport(ctx, AgentID, sonzai.BatchImportOptions{
      Source: &#x22;zep&#x22;,
      Users:  users,
  })
}

func main() {
  client, _ := sonzai.NewClient(sonzai.WithAPIKey(os.Getenv(&#x22;SONZAI_API_KEY&#x22;)))
  job, err := migrateZepUsers(context.Background(), client, []ZepExport{ /* … */ })
  if err != nil {
      panic(err)
  }
  fmt.Printf(&#x22;Queued %d users, facts from metadata: %d\\n&#x22;, job.TotalUsers, job.FactsCreated)
}`,
  },
]"
/>

## 4. Verify [#4-verify]

```bash
# Job status
curl -s https://api.sonz.ai/api/v1/agents/agent_abc/users/import/$JOB_ID \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '{status,facts_stored,facts_deduped,errors}'

# Memory for a specific migrated user
curl -s "https://api.sonz.ai/api/v1/agents/agent_abc/memory/facts?user_id=user_123&limit=50" \
  -H "Authorization: Bearer $SONZAI_API_KEY" | jq '.facts[] | {content, source_type}'
```

`facts_deduped` is particularly useful here — if you shipped both raw transcripts *and* Zep's extracted facts, a high dedup count confirms Sonzai's extractor rediscovered the same assertions.

## Tips [#tips]

* **Session IDs.** Sonzai has first-class sessions, but the bulk-import path flattens historical conversations into a single content array — so preserve each Zep session's ID as a header inside its `chat_transcript` block (e.g. `[session <id>]`). Going forward, wrap live chat with `sessions.start` / `sessions.end` and extracted facts will carry their source `session_id` automatically — no manual bookkeeping. See [Sessions](/docs/sessions) for the live-chat flow, or [the Sessions API reference](/docs/api/sessions) for endpoint details.
* **Graph edges.** Zep Cloud's knowledge-graph edges aren't directly importable. Sonzai rebuilds its own constellation from content. If the relationships are critical, include them as explicit text blocks (`"Mia manages Ren."`, `"Ren reports to Mia."`) and let the extractor wire them up.
* **Summaries.** If you've been relying on Zep session summaries, don't import them — Sonzai generates its own.

## What's next [#whats-next]

* [Sessions](/docs/sessions) — Sonzai's session model and when to start/end them explicitly.
* [Memory](/docs/memory) — how Sonzai's constellation dedupes facts.
* [Conversations](/docs/conversations) — what happens to migrated users during live chat.


---

# Endpoint Walkthrough

Source: https://sonz.ai/docs/en/guides/standalone-memory/endpoints

> Reference for sessions.start, session.context, session.turn, /process, sessions.end — plus the read endpoints that surface the extracted behavioral data.



The endpoints below cover everything you might need.

* **Pattern 1 minimum**: `sessions.start` → loop of `session.context()` + `session.turn()` → `session.end()`.
* **Pattern 2 minimum**: just `/process` (auto-creates a session).

## sessions.start — open a Session handle [#sessionsstart--open-a-session-handle]

Opens a session and returns a `Session` object that owns `agentId`, `userId`, `sessionId`, and provider/model defaults.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const session = await client.agents.sessions.start(&#x22;agent-id&#x22;, {
userId: &#x22;user-123&#x22;,
sessionId: &#x22;session-abc&#x22;,
userDisplayName: &#x22;Alice&#x22;,
toolDefinitions: yourTools,                    // optional
provider: &#x22;gemini&#x22;,                            // optional default for .turn()
model: &#x22;gemini-3.1-flash-lite-preview&#x22;,        // optional default for .turn()
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `session = client.agents.sessions.start(
  &#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  session_id=&#x22;session-abc&#x22;,
  user_display_name=&#x22;Alice&#x22;,
  provider=&#x22;gemini&#x22;,
  model=&#x22;gemini-3.1-flash-lite-preview&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `session, err := client.Agents.Sessions.Start(ctx, &#x22;agent-id&#x22;, sonzai.SessionStartOptions{
  UserID:          &#x22;user-123&#x22;,
  SessionID:       &#x22;session-abc&#x22;,
  UserDisplayName: &#x22;Alice&#x22;,
  Provider:        &#x22;gemini&#x22;,
  Model:           &#x22;gemini-3.1-flash-lite-preview&#x22;,
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X POST https://api.sonz.ai/api/v1/agents/{agentId}/sessions/start \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;user_id&#x22;: &#x22;user-123&#x22;,
  &#x22;session_id&#x22;: &#x22;session-abc&#x22;,
  &#x22;user_display_name&#x22;: &#x22;Alice&#x22;,
  &#x22;provider&#x22;: &#x22;gemini&#x22;,
  &#x22;model&#x22;: &#x22;gemini-3.1-flash-lite-preview&#x22;
}'`,
  },
]"
/>

## session.context() — enriched 7-layer context [#sessioncontext--enriched-7-layer-context]

Fetches the 7-layer enriched context: personality, mood, relevant memories, active goals, habits, relationship state, and proactive signals. Pass a `query` matching the current topic for best memory recall.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const ctx = await session.context({ query: &#x22;What should we talk about?&#x22; });

// ctx is a flat object — no nested envelope. Useful fields:
//   personality_prompt        — agent identity / system instructions
//   bio, speech_patterns      — agent identity bits
//   true_interests, true_dislikes
//   big5, dimensions, preferences, behaviors
//   recent_personality_shifts, significant_moments, active_goals, habits
//   current_mood, emotional_state
//   loaded_facts              — recalled facts (each has atomic_text, fact_type, importance)
//   long_term_summaries       — multi-session digests
//   proactive_memories        — pending proactive signals
//   constellation_patterns    — deeper behavioral patterns
//   relationship_narrative, chemistry_score, love_from_agent, love_from_user
//   knowledge.results         — KB hits for the query (only nested key)
//   recent_turns              — buffered messages from this session
//   backend_context           — custom application state (if set)`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `ctx = session.context(query=&#x22;What should we talk about?&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `ctx, err := session.Context(ctx, sonzai.ContextOptions{
  Query: &#x22;What should we talk about?&#x22;,
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl &#x22;https://api.sonz.ai/api/v1/agents/{agentId}/context?userId=user-123&sessionId=session-abc&query=hello&#x22; \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22;`,
  },
]"
/>

## session.turn() — submit a single turn (Pattern 1) [#sessionturn--submit-a-single-turn-pattern-1]

`POST /agents/{agentId}/sessions/{sessionId}/turn` — sync mood update inline (\~300–500ms), deeper extraction continues in the background (5–15 seconds). Accepts `role: "tool"` and `tool_calls` on assistant messages.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const { mood, extraction_id, extraction_status } = await session.turn({
messages: [
  { role: &#x22;user&#x22;, content: userMessage },
  // intermediate tool calls/results here
  { role: &#x22;assistant&#x22;, content: assistantMessage },
],
// provider/model fall back to the session-level defaults; both are optional.
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = session.turn(
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message},
      {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: assistant_message},
  ],
)
print(result.mood)
print(result.extraction_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := session.Turn(ctx, sonzai.TurnOptions{
  Messages: []sonzai.TurnMessage{
      {Role: &#x22;user&#x22;, Content: userMessage},
      {Role: &#x22;assistant&#x22;, Content: assistantMessage},
  },
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X POST https://api.sonz.ai/api/v1/agents/{agentId}/sessions/{sessionId}/turn \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;userId&#x22;: &#x22;user-123&#x22;,
  &#x22;messages&#x22;: [
    {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;I went hiking yesterday!&#x22;},
    {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: &#x22;That sounds wonderful!&#x22;}
  ]
}'`,
  },
]"
/>

Response shape:

```json
{
  "success": true,
  "mood": { "valence": 0.4, "arousal": 0.2, "tension": -0.1, "affiliation": 0.3 },
  "extraction_id": "ext_abc123",
  "extraction_status": "queued"
}
```

### Polling background extraction [#polling-background-extraction]

```ts
const status = await session.status(extraction_id);
// { extraction_id: "...", state: "queued" | "running" | "done" | "failed" }
```

### Fetch the next context in the same response [#fetch-the-next-context-in-the-same-response]

If you can predict the next user query (or just want to pre-warm with a generic query), pass `fetchNextContext` on `.turn()` and the server returns an enriched context inside the same response under `next_context`. This eliminates one roundtrip on the next render.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const { mood, next_context } = await session.turn({
messages: [...],
fetchNextContext: { query: &#x22;any query you'd run on the next turn&#x22; },
});

// next_context has the same shape as session.context() — use it directly
// to render the system prompt for the next turn without calling /context.`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = session.turn(
  messages=[...],
  fetch_next_context={&#x22;query&#x22;: &#x22;any query you'd run on the next turn&#x22;},
)
next_ctx = result.next_context  # same shape as session.context()`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := session.Turn(ctx, sonzai.TurnOptions{
  Messages: []sonzai.TurnMessage{ /* ... */ },
  FetchNextContext: &sonzai.FetchNextContext{
      Query: &#x22;any query you'd run on the next turn&#x22;,
  },
})
// result.NextContext mirrors session.Context() — render the system prompt
// for the next turn without an extra round-trip to /context.`,
  },
]"
/>

## /process — batch ingest a transcript (Pattern 2) [#process--batch-ingest-a-transcript-pattern-2]

Send a full transcript and run extraction immediately. Auto-creates a session if `sessionId` is omitted; the response surfaces the auto-generated `session_id`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const result = await client.agents.process(&#x22;agent-id&#x22;, {
userId: &#x22;user-123&#x22;,
// sessionId omitted — auto-created
messages: [
  { role: &#x22;user&#x22;, content: userMessage },
  { role: &#x22;assistant&#x22;, content: assistantMessage },
  // tool messages allowed too
],
provider: &#x22;gemini&#x22;,                            // optional
model: &#x22;gemini-3.1-flash-lite-preview&#x22;,        // optional
});

console.log(result.session_id);          // auto-generated when not passed
console.log(result.facts_extracted);     // count of facts extracted this call
console.log(result.side_effects);        // { mood_updated: true, ... summary counts }

// Then read the extracted state back via the dedicated endpoints:
const memory = await client.agents.memory.list(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
const mood   = await client.agents.getMood(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `result = client.agents.process(
  &#x22;agent-id&#x22;,
  user_id=&#x22;user-123&#x22;,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message},
      {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: assistant_message},
  ],
  provider=&#x22;gemini&#x22;,
  model=&#x22;gemini-3.1-flash-lite-preview&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `result, err := client.Agents.Process(ctx, &#x22;agent-id&#x22;, sonzai.ProcessOptions{
  UserID:    &#x22;user-123&#x22;,
  Messages: []sonzai.ChatMessage{
      {Role: &#x22;user&#x22;, Content: userMessage},
      {Role: &#x22;assistant&#x22;, Content: assistantMessage},
  },
  Provider: &#x22;gemini&#x22;,
  Model:    &#x22;gemini-3.1-flash-lite-preview&#x22;,
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X POST https://api.sonz.ai/api/v1/agents/{agentId}/process \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;userId&#x22;: &#x22;user-123&#x22;,
  &#x22;messages&#x22;: [
    {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;I went hiking yesterday!&#x22;},
    {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: &#x22;That sounds wonderful!&#x22;}
  ],
  &#x22;provider&#x22;: &#x22;gemini&#x22;,
  &#x22;model&#x22;: &#x22;gemini-3.1-flash-lite-preview&#x22;
}'`,
  },
]"
/>

The response is intentionally a small summary — `{ success, facts_extracted, side_effects, session_id }`. To inspect the extracted facts/personality/mood/habits themselves, call the dedicated read endpoints (see [Reading Behavioral Data](#reading-behavioral-data) below).

## sessions.end / session.end() [#sessionsend--sessionend]

Closes the session. If you call this **without** `messages` (after using `/turn` or `/process`), it's a finalize-only call. If you call it **with** `messages` and skipped `/process`, this becomes your extraction trigger — functionally equivalent to `/process`, but lifecycle-scoped and async-capable on tenants where enabled.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Just close — no extraction needed if you used /turn or /process already.
await session.end({ totalMessages: 12, durationSeconds: 600 });

// OR — pass messages here as the extraction trigger (Option B).
await session.end({
messages: transcript,
totalMessages: transcript.length,
durationSeconds: 600,
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Just close.
session.end(total_messages=12, duration_seconds=600)

# OR — pass messages here as the extraction trigger (Option B).
session.end(
  messages=transcript,
  total_messages=len(transcript),
  duration_seconds=600,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `err := session.End(ctx, sonzai.SessionEndOptions{
  Messages:        transcript,
  TotalMessages:   len(transcript),
  DurationSeconds: 600,
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X POST https://api.sonz.ai/api/v1/agents/{agentId}/sessions/end \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{
  &#x22;user_id&#x22;: &#x22;user-123&#x22;,
  &#x22;session_id&#x22;: &#x22;session-abc&#x22;,
  &#x22;messages&#x22;: [...],
  &#x22;total_messages&#x22;: 12,
  &#x22;duration_seconds&#x22;: 600
}'`,
  },
]"
/>

## Tool messages [#tool-messages]

Both `/turn` and `/process` accept OpenAI/Anthropic-style tool messages. Sonzai's extractor reads tool results and can capture facts that only appeared in tool output.

```jsonc
{
  "messages": [
    { "role": "user", "content": "Where did my last order ship from?" },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "call_1",
          "type": "function",
          "function": { "name": "order-lookup", "arguments": "{\"limit\":1}" }
        }
      ]
    },
    {
      "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." }
  ]
}
```

The extractor will surface a fact like &#x2A;"User's last order (#42) shipped from Tokyo via DHL"* — a fact that never appeared in the user's or assistant's own text.

## Provider / model overrides [#provider--model-overrides]

Both `/turn` and `/process` (and `sessions.start` / `sessions.end`) accept optional `provider` and `model` fields. Resolution order:

1. **Per-call** override on `/turn` or `/process`
2. **Session-level** default set on `sessions.start`
3. **Tenant default** configured in your account
4. **Platform default** — `gemini-3.1-flash-lite-preview`

Omit the fields entirely and the platform default applies.

## Reading behavioral data [#reading-behavioral-data]

After processing, all behavioral data is available via dedicated endpoints.

### Memory & facts [#memory--facts]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const memory = await client.agents.memory.list(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
const results = await client.agents.memory.search(&#x22;agent-id&#x22;, { query: &#x22;hiking&#x22; });`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Python SDK exposes list_facts for atomic facts.
facts = client.agents.memory.list_facts(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
# For keyword search, hit GET /api/v1/agents/{agent_id}/memory/search?q=...
# directly, or use the TS/Go SDK's agents.memory.search method.`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `memory, err := client.Agents.Memory.List(ctx, &#x22;agent-id&#x22;, &sonzai.MemoryListOptions{
  UserID: &#x22;user-123&#x22;,
})

results, err := client.Agents.Memory.Search(ctx, &#x22;agent-id&#x22;, sonzai.MemorySearchOptions{
  Query: &#x22;hiking&#x22;,
})`,
  },
]"
/>

### Personality & mood [#personality--mood]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const personality = await client.agents.personality.get(&#x22;agent-id&#x22;);
const mood = await client.agents.getMood(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
const shifts = await client.agents.personality.getRecentShifts(&#x22;agent-id&#x22;);
const moments = await client.agents.personality.getSignificantMoments(&#x22;agent-id&#x22;);`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `personality = client.agents.personality.get(&#x22;agent-id&#x22;)
mood = client.agents.get_mood(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
shifts = client.agents.personality.get_recent_shifts(&#x22;agent-id&#x22;)
moments = client.agents.personality.get_significant_moments(&#x22;agent-id&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `personality, err := client.Agents.Personality.Get(ctx, &#x22;agent-id&#x22;, nil)
mood, err := client.Agents.GetMood(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
shifts, err := client.Agents.Personality.GetRecentShifts(ctx, &#x22;agent-id&#x22;)
moments, err := client.Agents.Personality.GetSignificantMoments(ctx, &#x22;agent-id&#x22;, 10)`,
  },
]"
/>

### Goals, habits & relationships [#goals-habits--relationships]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const goals = await client.agents.listGoals(&#x22;agent-id&#x22;);
const habits = await client.agents.listHabits(&#x22;agent-id&#x22;, { userId: &#x22;user-123&#x22; });
const interests = await client.agents.getInterests(&#x22;agent-id&#x22;);
const relationships = await client.agents.getRelationships(&#x22;agent-id&#x22;);`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `goals = client.agents.list_goals(&#x22;agent-id&#x22;)
habits = client.agents.list_habits(&#x22;agent-id&#x22;, user_id=&#x22;user-123&#x22;)
interests = client.agents.get_interests(&#x22;agent-id&#x22;)
relationships = client.agents.get_relationships(&#x22;agent-id&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `goals, err := client.Agents.ListGoals(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
habits, err := client.Agents.ListHabits(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
interests, err := client.Agents.GetInterests(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)
rels, err := client.Agents.GetRelationships(ctx, &#x22;agent-id&#x22;, &#x22;user-123&#x22;, &#x22;&#x22;)`,
  },
]"
/>

### Proactive notifications [#proactive-notifications]

The Context Engine schedules proactive outreach (check-ins, follow-ups) based on conversation patterns. Poll for pending notifications and consume them when delivered.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const notifications = await client.agents.notifications.list(&#x22;agent-id&#x22;);

for (const notif of notifications) {
await deliverToUser(notif.user_id, notif.message);
await client.agents.notifications.consume(&#x22;agent-id&#x22;, notif.message_id);
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `notifications = client.agents.notifications.list(&#x22;agent-id&#x22;)

for notif in notifications:
  deliver_to_user(notif.user_id, notif.message)
  client.agents.notifications.consume(&#x22;agent-id&#x22;, notif.message_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `notifications, err := client.Agents.Notifications.List(ctx, &#x22;agent-id&#x22;)

for _, notif := range notifications {
  deliverToUser(notif.UserID, notif.GeneratedMessage)
  client.Agents.Notifications.Consume(ctx, &#x22;agent-id&#x22;, notif.MessageID)
}`,
  },
]"
/>

## What gets extracted [#what-gets-extracted]

<Cards>
  <Card title="Memory Facts" description="Atomic facts (preferences, events, commitments) with importance scoring, deduplication, and topic tagging. Sourced from user, assistant, AND tool messages." />

  <Card title="Personality Deltas" description="Big5 trait shifts (openness, conscientiousness, extraversion, agreeableness, neuroticism) with reasoning." />

  <Card title="Mood Changes" description="4D mood delta (valence, arousal, tension, affiliation). Sync mood lands inline on /turn; richer extraction is deferred." />

  <Card title="Habit Detection" description="New and reinforced behavioral patterns — exercise routines, reading habits, social patterns." />

  <Card title="Interest Tracking" description="Topics the user engages with, categorized by domain with confidence and engagement scores." />

  <Card title="Relationship Dynamics" description="Love score changes with reasoning — tracks rapport, trust, and emotional connection." />

  <Card title="Proactive Outreach" description="Scheduled check-ins and follow-ups based on conversation context (e.g., 'ask about the hike tomorrow')." />

  <Card title="Emotional Themes" description="Detected emotional tones — joy, creative spark, feeling overwhelmed, seeking connection, etc." />
</Cards>

## Choosing an extraction model [#choosing-an-extraction-model]

When calling `/turn` or `/process`, specify which of our LLM providers to use for extraction. Omitting `provider`/`model` falls back to the platform default `gemini-3.1-flash-lite-preview`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const models = await client.agents.getModels(&#x22;agent-id&#x22;);
// {
//   default_provider: &#x22;gemini&#x22;,
//   default_model: &#x22;gemini-3.1-flash-lite-preview&#x22;,
//   providers: [
//     { provider: &#x22;gemini&#x22;, provider_name: &#x22;Google Gemini&#x22;, default_model: &#x22;...&#x22; },
//     { provider: &#x22;zhipu&#x22;, provider_name: &#x22;Zhipu AI&#x22;, default_model: &#x22;...&#x22; },
//     ...
//   ]
// }`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `models = client.agents.get_models(&#x22;agent-id&#x22;)
print(models.default_provider)  # &#x22;gemini&#x22;
print(models.providers)         # list of available providers`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `models, err := client.Agents.GetModels(ctx, &#x22;agent-id&#x22;)
fmt.Println(models.DefaultProvider)`,
  },
]"
/>


---

# Standalone Memory Layer

Source: https://sonz.ai/docs/en/guides/standalone-memory

> Three integration shapes — one-shot batch (/process), lifecycle-scoped batch (sessions.start → end with messages), or real-time turn-by-turn (sessions.start → turn → end). All three give you Sonzai's behavioral intelligence without giving up control of the chat loop.



## Choosing Your Integration Shape [#choosing-your-integration-shape]

There are **three** ways to feed conversations into Sonzai. The first two are batch (you send a transcript after the conversation); the third is real-time (you submit each turn as it happens). Pick exactly one per conversation — chaining them runs extraction twice on the same messages.

<Cards>
  <Card title="A. /process — one-shot batch" description="Single call. Auto-creates a session if you don't pass one. Best for external LLM transcripts, benchmarks, and any flow without a long-lived session lifecycle." />

  <Card title="B. sessions.start → end({ messages }) — lifecycle batch" description="Open a session, do your full conversation off-platform, then close with the transcript on .end(). Use when you want explicit session boundaries, async polling, or session-scoped tools — but still ingest in one shot." />

  <Card title="C. sessions.start → turn() × N → end() — real-time" description="Open a session and submit each exchange via .turn() as the conversation happens. Sync mood lands inline (~300–500ms); deeper extraction runs asynchronously 5–15s later. Best for chat companions, voice AI, and agent frameworks." />
</Cards>

|                         | A. `/process`                                         | B. `sessions.end({ messages })`                                            | C. `sessions.turn()` × N                                   |
| ----------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Calls per conversation  | 1                                                     | 2 (`start` + `end`)                                                        | 2 + N (`start` + N × `turn` + `end`)                       |
| Sonzai in the hot path? | No                                                    | No                                                                         | Yes — `.context()` and `.turn()` flank each turn           |
| Context per turn        | Pre-session only (optional `getContext` call)         | Pre-session only (optional `getContext` call)                              | Fresh, query-specific via `.context()`                     |
| Extraction timing       | Whole transcript, inline                              | Whole transcript, inline (or async on tenants where enabled)               | Per-turn — sync mood inline, deeper extraction 5–15s later |
| Lifecycle ownership     | Implicit (auto-session)                               | Explicit                                                                   | Explicit                                                   |
| Best for                | External transcripts, benchmarks, no-lifecycle ingest | Explicit boundaries + async processing, session-scoped tools, batch ingest | Chat companions, voice AI, agent frameworks                |

A and B are **functionally equivalent for fact extraction** — both extract facts and side-effects from the full transcript inline. The only differences are lifecycle ergonomics (B gives you an explicit session and supports async polling) and call count.

C is a different shape: Sonzai is part of every turn instead of seeing the conversation only at the end.

<Callout type="warn" title="Don't mix shapes within one conversation">
  Calling `.turn()` per turn (C) **and** `.end({ messages })` with the same transcript (B) extracts the same messages twice. Pick one shape per conversation. The pattern docs below show C and B/A separately.
</Callout>

The rest of this section groups A and B together as &#x2A;*[Pattern 2: Post-Session Processing](/docs/en/guides/standalone-memory/pattern-2-batch)*&#x2A; (since they share the same "extract a transcript at the end" semantics) and treats C as &#x2A;*[Pattern 1: Memory Middleware](/docs/en/guides/standalone-memory/pattern-1-realtime)** (real-time turn submission).

## What runs when — extraction is light, consolidation is automatic [#what-runs-when--extraction-is-light-consolidation-is-automatic]

`/turn`, `/process`, and `sessions.end` are intentionally **lightweight**. They extract facts and a session summary from the transcript and persist them — that's it. The expensive work (cross-session dedup, clustering, diary deepening, decay) is **scheduled automatically by the platform** and is rate-limited so it doesn't run on every call.

| Layer                                                                                   | When it runs                                                | Triggered by                 | Cost                           |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------- | ------------------------------ |
| **Sync mood update** (Pattern 1 `/turn` only)                                           | Inline, \~300–500ms                                         | Your `.turn()` call          | Light — one short LLM call     |
| **Background extraction** (facts, personality, habits)                                  | 5–15 seconds after `/turn`                                  | Automatic — no caller action | Light — one LLM call per chunk |
| **Fact extraction + session summary** (batch)                                           | Inline, on every `/process` or `sessions.end({ messages })` | Your call                    | Light — one LLM call per chunk |
| **Post-session consolidation** (dedup, crossref, bundle precompute, pattern detection)  | \~8 hours after the session ends                            | Automatic                    | Medium                         |
| **Daily consolidation + diary**                                                         | Once per day                                                | Automatic schedule           | Medium                         |
| **Deep consolidation** (wakeup/habit dedup, decay, cluster reconcile, weekly summaries) | Daily / weekly                                              | Automatic schedule           | Heavy                          |

This means &#x2A;*you can call `/turn` per turn (Pattern 1), or `/process` once at the end (Pattern 2), without paying for heavy consolidation each time.** The platform de-duplicates and consolidates in the background.

<Callout type="info" title="Practical implication">
  Don't try to "save calls" by skipping `/turn` between turns. Each call only does sync mood + queues deferred extraction (cheap). Skipping it means losing per-turn behavioral signal. The expensive consolidation runs on its own schedule no matter how many times you call.
</Callout>

## Where to next [#where-to-next]

<Cards>
  <Card href="/docs/en/guides/standalone-memory/pattern-1-realtime" title="Pattern 1: Memory Middleware (real-time)" description="Per-turn integration for chat companions, voice AI, and agent frameworks. Includes tool calling and multimodal/image handling." />

  <Card href="/docs/en/guides/standalone-memory/pattern-2-batch" title="Pattern 2: Post-Session Batch Processing" description="One-shot ingest via /process or lifecycle-scoped via sessions.end({ messages }). For tutoring, fitness, CRM, journaling, and any flow that doesn't need Sonzai in the hot path." />

  <Card href="/docs/en/guides/standalone-memory/endpoints" title="Endpoint Walkthrough" description="Reference for sessions.start, session.context, session.turn, /process, sessions.end, and the read endpoints (memory, mood, personality, goals, habits, notifications)." />

  <Card href="/docs/en/guides/standalone-memory/limitations" title="Knowledge Base & Limitations" description="How the KB shows up in standalone mode and what's not supported vs. managed mode." />
</Cards>


---

# Knowledge Base & Limitations

Source: https://sonz.ai/docs/en/guides/standalone-memory/limitations

> How the knowledge base behaves in standalone mode, plus what isn't supported vs. managed mode.



## Knowledge base in standalone mode [#knowledge-base-in-standalone-mode]

### Automatic — KB results in /context [#automatic--kb-results-in-context]

When you call `session.context({ query })` (or `GET /context`), the endpoint searches the agent's knowledge base and includes matching results in a `knowledge` field automatically.

```json
{
  "personality_prompt": "You are a helpful AI companion...",
  "big5": { "openness": 0.7, "conscientiousness": 0.6, "extraversion": 0.5, "agreeableness": 0.8, "neuroticism": 0.3 },
  "current_mood": { "valence": 0.4, "arousal": 0.2, "tension": -0.1, "affiliation": 0.3 },
  "loaded_facts": [{ "atomic_text": "User prefers morning workouts", "fact_type": "behavioral", "importance": 0.8 }],
  "active_goals": [{ "description": "Run a 5K by June" }],
  "habits": [{ "label": "Daily exercise" }],
  "knowledge": {
    "results": [
      {
        "content": "Refund policy: customers can request a full refund within 30 days...",
        "label": "Refund Policy",
        "type": "policy",
        "source": "policies.pdf",
        "score": 0.92
      }
    ]
  }
}
```

### Learning loop — extraction detects knowledge gaps [#learning-loop--extraction-detects-knowledge-gaps]

After `/turn` or `/process` extracts side effects, it also searches the KB with topics found in the conversation. If relevant KB content exists that the agent missed, it stores these as proactive signals — the **next** `session.context()` call includes them automatically.

<Diagram>
  {`
    Turn 1: session.context() → (no KB results yet)
           ↓
          chat with your LLM
           ↓
          session.turn() → extracts "hiking gear" as topic
                         → searches KB, finds "Hiking Equipment Guide"
                         → stores as proactive signal

    Turn 2: session.context() → includes "Hiking Equipment Guide" from KB
                            + any direct search results for the new query
           ↓
          chat with your LLM (now knows about hiking gear!)
    `}
</Diagram>

### Explicit — tool endpoint for agent frameworks [#explicit--tool-endpoint-for-agent-frameworks]

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const results = await client.agents.knowledgeSearch(&#x22;agent-id&#x22;, {
query: &#x22;refund policy&#x22;,
limit: 5,
});

for (const result of results.results) {
console.log(result.label, result.content);
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `results = client.agents.knowledge_search(
  &#x22;agent-id&#x22;,
  query=&#x22;refund policy&#x22;,
  limit=5,
)

for result in results.results:
  print(result.label, result.content)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `results, err := client.Agents.KnowledgeSearch(ctx, &#x22;agent-id&#x22;, sonzai.AgentKBSearchOptions{
  Query: &#x22;refund policy&#x22;,
  Limit: 5,
})`,
  },
  {
    id: &#x22;bash&#x22;,
    label: &#x22;cURL&#x22;,
    code: `curl -X POST https://api.sonz.ai/api/v1/agents/{agentId}/tools/kb-search \\
-H &#x22;Authorization: Bearer sk_your_api_key&#x22; \\
-H &#x22;Content-Type: application/json&#x22; \\
-d '{&#x22;query&#x22;: &#x22;refund policy&#x22;, &#x22;limit&#x22;: 5}'`,
  },
]"
/>

You can also expose this as a function tool to your LLM — see [Tool Calling in Pattern 1](/docs/en/guides/standalone-memory/pattern-1-realtime#tool-calling).

## Limitations vs. managed mode [#limitations-vs-managed-mode]

<Callout type="warn">
  **Want to use your own model without managing the chat loop?** Consider [Custom LLM](/docs/en/models/custom-llm) instead. It lets you point Sonzai at any OpenAI-compatible endpoint while keeping streaming, built-in tools, and per-message extraction fully automatic.
</Callout>

### No built-in tool execution [#no-built-in-tool-execution]

Managed mode calls built-in tools (web search, memory recall, image generation) automatically. In standalone mode you must implement tool calling yourself — the tool-calling loop is yours, but the resulting tool messages flow into `/turn` or `/process` for extraction. See the [Tool Integration guide](/docs/en/guides/tool-integration).

### No streaming on extraction [#no-streaming-on-extraction]

`session.context()`, `/turn`, and `/process` are synchronous request-response calls. Streaming is handled by your own LLM. Background extraction is asynchronous but you poll for state, not stream.

### Deferred knowledge base enrichment [#deferred-knowledge-base-enrichment]

KB enrichment is deferred — extraction detects knowledge gaps but the next `session.context()` call surfaces them, not the current turn.

### Manual extraction trigger [#manual-extraction-trigger]

You must pick **one** of the three integration shapes per conversation: `/process` (one-shot batch), `sessions.start` → `sessions.end({ messages })` (lifecycle batch), or `sessions.start` → `session.turn()` per turn → `session.end()` (real-time). Picking none means the transcript is never seen by the Context Engine and no behavioral data is captured. Picking two — for example calling `.turn()` per turn **and** passing `messages` on `.end()` — runs extraction twice on the same content. (Heavy consolidation runs on its own schedule and doesn't need to be triggered manually.)

### Text-only memory pipeline [#text-only-memory-pipeline]

Sonzai's extraction reads `messages` as text. Multimodal content (images, audio) must be bridged to text before submission — see [Working with Images & Multimodal Input](/docs/en/guides/standalone-memory/pattern-1-realtime#working-with-images--multimodal-input) in Pattern 1.

<Callout type="info" title="What's the same in both modes">
  Extraction quality is identical — both modes use the same LLM pipeline for fact extraction, personality shifts, mood, habits, and consolidation. The 7-layer enriched context from `session.context()` is the same data the managed chat builds internally.
</Callout>


---

# Pattern 1: Memory Middleware (Real-Time)

Source: https://sonz.ai/docs/en/guides/standalone-memory/pattern-1-realtime

> Per-turn integration. You control the LLM and tool-calling loop; Sonzai handles what that LLM knows about the user. Includes tool calling and multimodal/image handling.



You control the LLM. Sonzai handles what that LLM knows about the user.

Open a `Session` once. For every turn: call `session.context({ query })` to pull the enriched user profile, build your system prompt, call your own LLM (with your own tools), then call `session.turn({ messages })` to submit just the new exchange. Sync mood updates inline (\~300–500ms); deeper extraction (facts, personality, habits) lands asynchronously 5–15 seconds later in the background.

This is the same data model mem0 provides (relevant memories injected before generation), extended with personality evolution, mood tracking, habit detection, goal tracking, proactive outreach scheduling, and relationship dynamics.

<Diagram>
  {`
    ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
    │  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       │                       │
         │  <── reply ─────────┼───────────────────────│
         │                     │                       │
         │  sendToUser(reply) (no waiting on Sonzai)   │
         │                     │                       │
         │  session.turn()     │                       │
         │────────────────────>│ ⇒ sync mood ~300ms    │
         │  <── mood, status ──│ ⇒ background extraction│
         │                     │   (5–15s)             │
         │                     │                       │
         │  ─── Repeat ────────────────────────────── │
         │                     │                       │
         │  session.end()      │                       │
         │────────────────────>│── consolidate         │
         │                     │   long-term memory    │
         └─────────────────────┴───────────────────────┘
    `}
</Diagram>

<Callout type="info" title="What Sonzai's LLM is used for">
  `session.context()` and `sessions.start` use no Sonzai LLM credits — they are pure reads. `session.turn()`, `/process`, and `sessions.end({ messages })` use Sonzai's LLM for **fact extraction + session summary** (light, per-call, billed). Heavy background work — cross-session dedup, clustering, diary, decay — runs on auto-scheduled jobs (8h post-session, daily, weekly) and is billed against the same tenant but **not per-call**. Your chat LLM is entirely your cost.
</Callout>

## Core loop [#core-loop]

Open the session once with your provider/model defaults. Then for every turn: get context → call your LLM (running tool calls in your own loop) → submit the turn. End the session when done.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function runConversation(agentId: string, userId: string) {
const sessionId = \`session-\${Date.now()}\`;
const history: { role: string; content: string }[] = [];

// Open a Session handle. agentId/userId/sessionId and provider/model
// defaults live on the handle so you don't repeat them on every call.
const session = await sonzai.agents.sessions.start(agentId, {
  userId,
  sessionId,
  toolDefinitions: yourTools,                   // optional — register session-scoped tool schemas
  provider: &#x22;gemini&#x22;,                           // optional — default for .turn()
  model: &#x22;gemini-3.1-flash-lite-preview&#x22;,       // optional — default for .turn()
});

async function turn(userMessage: string): Promise<string> {
  // Fresh enriched context for this specific message
  const ctx = await session.context({ query: userMessage });

  // Your LLM — swap in any provider you like
  let reply = await yourLLM.chat({
    system: buildSystemPrompt(ctx),
    messages: [...history, { role: &#x22;user&#x22;, content: userMessage }],
    tools: yourTools,
  });

  // Tool-calling loop is entirely yours — Sonzai is OUT of the loop here.
  const toolMessages: any[] = [];
  while (reply.tool_calls?.length) {
    for (const call of reply.tool_calls) {
      const result = await runYourTool(call);
      toolMessages.push(
        { role: &#x22;assistant&#x22;, tool_calls: [call] },
        { role: &#x22;tool&#x22;, tool_call_id: call.id, content: result },
      );
    }
    reply = await yourLLM.chat({
      system: buildSystemPrompt(ctx),
      messages: [...history, { role: &#x22;user&#x22;, content: userMessage }, ...toolMessages],
      tools: yourTools,
    });
  }

  sendToUser(reply.content); // send first; don't block on Sonzai

  // Submit just the new turn. Sync mood ~300ms, deferred extraction
  // (facts, personality, habits) runs asynchronously 5–15s later.
  // Pass the FULL exchange — including tool calls and tool results —
  // so Sonzai can extract facts from tool outputs too.
  const { mood, extraction_id } = await session.turn({
    messages: [
      { role: &#x22;user&#x22;, content: userMessage },
      ...toolMessages,                          // assistant tool_calls + tool results
      { role: &#x22;assistant&#x22;, content: reply.content },
    ],
  });

  history.push({ role: &#x22;user&#x22;, content: userMessage });
  history.push({ role: &#x22;assistant&#x22;, content: reply.content });

  return reply.content;
}

return { turn, end: () => session.end() };
}

// The /context response is a flat object — there is no nested
// \`profile\` / \`behavioral\` / \`memory\` envelope.
function buildSystemPrompt(ctx: any): string {
const facts = (ctx.loaded_facts ?? []).map((f: any) => \`- \${f.atomic_text}\`).join(&#x22;\\n&#x22;);
const goals = (ctx.active_goals ?? []).map((g: any) => g.description).join(&#x22;, &#x22;);
return \`\${ctx.personality_prompt ?? &#x22;You are a helpful AI companion.&#x22;}
Personality (Big5): \${JSON.stringify(ctx.big5 ?? {})}
Current mood: \${JSON.stringify(ctx.current_mood ?? {})}
Active goals: \${goals || &#x22;none&#x22;}
Relevant memories:
\${facts || &#x22;none yet&#x22;}\`;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `import os, asyncio
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def run_conversation(agent_id: str, user_id: str):
  session_id = f&#x22;session-{int(asyncio.get_event_loop().time() * 1000)}&#x22;
  history = []

  # Open a Session handle — provider/model defaults live on the handle.
  session = sonzai.agents.sessions.start(
      agent_id,
      user_id=user_id,
      session_id=session_id,
      provider=&#x22;gemini&#x22;,
      model=&#x22;gemini-3.1-flash-lite-preview&#x22;,
  )

  def turn(user_message: str) -> str:
      # Fresh enriched context for this specific message
      ctx = session.context(query=user_message)

      # Your LLM — swap in any provider you like
      reply = your_llm.chat(
          system=build_system_prompt(ctx),
          messages=[*history, {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message}],
          tools=your_tools,
      )

      # Tool-calling loop is entirely yours — Sonzai is OUT of the loop here.
      tool_messages = []
      while getattr(reply, &#x22;tool_calls&#x22;, None):
          for call in reply.tool_calls:
              result = run_your_tool(call)
              tool_messages.append({&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: None, &#x22;tool_calls&#x22;: [call]})
              tool_messages.append({&#x22;role&#x22;: &#x22;tool&#x22;, &#x22;tool_call_id&#x22;: call.id, &#x22;content&#x22;: result})
          reply = your_llm.chat(
              system=build_system_prompt(ctx),
              messages=[*history, {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message}, *tool_messages],
              tools=your_tools,
          )

      send_to_user(reply.content)  # send first; don't block on Sonzai

      result = session.turn(
          messages=[
              {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message},
              *tool_messages,
              {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply.content},
          ]
      )

      history.append({&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message})
      history.append({&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply.content})
      return reply.content

  return turn, session.end

# The /context response is a flat dict — no nested envelope.
def build_system_prompt(ctx: dict) -> str:
  facts = &#x22;\\n&#x22;.join(f&#x22;- {f.get('atomic_text', '')}&#x22; for f in (ctx.get(&#x22;loaded_facts&#x22;) or []))
  goals = &#x22;, &#x22;.join(g.get(&#x22;description&#x22;, &#x22;&#x22;) for g in (ctx.get(&#x22;active_goals&#x22;) or []))
  return f&#x22;&#x22;&#x22;{ctx.get(&#x22;personality_prompt&#x22;, &#x22;You are a helpful AI companion.&#x22;)}
Personality (Big5): {ctx.get(&#x22;big5&#x22;, {})}
Current mood: {ctx.get(&#x22;current_mood&#x22;, {})}
Active goals: {goals or &#x22;none&#x22;}
Relevant memories:
{facts or &#x22;none yet&#x22;}&#x22;&#x22;&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  &#x22;strings&#x22;
  &#x22;time&#x22;
  &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func runConversation(ctx context.Context, agentID, userID string) error {
  client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  if err != nil {
      return err
  }

  sessionID := fmt.Sprintf(&#x22;session-%d&#x22;, time.Now().UnixMilli())

  // Open a Session handle — provider/model defaults live on the handle.
  session, err := client.Agents.Sessions.Start(ctx, agentID, sonzai.SessionStartOptions{
      UserID:    userID,
      SessionID: sessionID,
      Provider:  &#x22;gemini&#x22;,
      Model:     &#x22;gemini-3.1-flash-lite-preview&#x22;,
  })
  if err != nil {
      return err
  }

  var history []sonzai.ChatMessage

  runTurn := func(userMessage string) (string, error) {
      // Fresh enriched context for this specific message
      ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: userMessage})
      if err != nil {
          return &#x22;&#x22;, err
      }

      systemPrompt := buildSystemPrompt(ctxData)

      // Your LLM — swap in any provider you like
      msgs := append(history, sonzai.ChatMessage{Role: &#x22;user&#x22;, Content: userMessage})
      reply, toolMessages, err := yourLLMWithToolLoop(ctx, systemPrompt, msgs, yourTools)
      if err != nil {
          return &#x22;&#x22;, err
      }

      sendToUser(reply) // send first; don't block on Sonzai

      // Build the full message list including tool calls/results
      turnMsgs := []sonzai.TurnMessage{{Role: &#x22;user&#x22;, Content: userMessage}}
      turnMsgs = append(turnMsgs, toolMessages...)
      turnMsgs = append(turnMsgs, sonzai.TurnMessage{Role: &#x22;assistant&#x22;, Content: reply})

      _, err = session.Turn(ctx, sonzai.TurnOptions{Messages: turnMsgs})
      if err != nil {
          return &#x22;&#x22;, err
      }

      history = append(history,
          sonzai.ChatMessage{Role: &#x22;user&#x22;, Content: userMessage},
          sonzai.ChatMessage{Role: &#x22;assistant&#x22;, Content: reply},
      )
      return reply, nil
  }

  _ = runTurn
  return session.End(ctx)
}

// The /context response is flat — no nested envelope.
func buildSystemPrompt(ctx map[string]any) string {
  var facts []string
  if ff, ok := ctx[&#x22;loaded_facts&#x22;].([]any); ok {
      for _, f := range ff {
          if fm, ok := f.(map[string]any); ok {
              facts = append(facts, &#x22;- &#x22;+fmt.Sprint(fm[&#x22;atomic_text&#x22;]))
          }
      }
  }
  var goals []string
  if gg, ok := ctx[&#x22;active_goals&#x22;].([]any); ok {
      for _, g := range gg {
          if gm, ok := g.(map[string]any); ok {
              goals = append(goals, fmt.Sprint(gm[&#x22;description&#x22;]))
          }
      }
  }
  personality, _ := ctx[&#x22;personality_prompt&#x22;].(string)
  if personality == &#x22;&#x22; {
      personality = &#x22;You are a helpful AI companion.&#x22;
  }
  return strings.Join([]string{
      personality,
      fmt.Sprintf(&#x22;Active goals: %s&#x22;, strings.Join(goals, &#x22;, &#x22;)),
      &#x22;Relevant memories:&#x22;,
      strings.Join(facts, &#x22;\\n&#x22;),
  }, &#x22;\\n&#x22;)
}`,
  },
]"
/>

## Pull fresh context every turn [#pull-fresh-context-every-turn]

The single most important habit in Pattern 1 is calling `session.context(query=user_msg)` **before every LLM call**. This is the load-bearing piece that closes the loop — without it, the LLM doesn't get the fresh mood (which lands inline on `.turn()`) or the freshly-extracted facts (which land 5–15 seconds after `.turn()`).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `while (conversationActive) {
const userMsg = await getUserInput();

// 1. PULL FRESH CONTEXT — happens every turn, before the LLM call.
//    ctx is a flat object — no \`profile\` / \`behavioral\` / \`memory\` envelope.
//    Fields you'll usually read:
//      ctx.personality_prompt          — agent identity / instructions
//      ctx.bio, ctx.speech_patterns    — agent identity bits
//      ctx.big5                        — Big5 trait object
//      ctx.current_mood                — fresh inline (~300ms after .turn())
//      ctx.habits, ctx.active_goals    — behavioral state
//      ctx.loaded_facts                — recalled facts (5-15s lag from extraction)
//      ctx.proactive_memories          — pending proactive signals
//      ctx.knowledge.results           — KB hits (only nested key)
//      ctx.recent_turns                — buffered messages from this session
const ctx = await session.context({ query: userMsg });

// 2. Build system prompt from the context layers
const systemPrompt = renderPromptFromContext(ctx);

// 3. Run YOUR LLM — Sonzai is OUT of the loop here
const reply = await yourLLM.chat({
  system: systemPrompt,
  messages: [...history, { role: &#x22;user&#x22;, content: userMsg }],
});

// 4. Submit the just-completed turn — sync mood + async deferred extraction
await session.turn({
  messages: [
    { role: &#x22;user&#x22;, content: userMsg },
    { role: &#x22;assistant&#x22;, content: reply.content },
  ],
});
}

function renderPromptFromContext(ctx: any): string {
const parts: string[] = [];
if (ctx.personality_prompt) parts.push(ctx.personality_prompt);
if (ctx.big5) parts.push(\`Personality (Big5): \${JSON.stringify(ctx.big5)}\`);
if (ctx.speech_patterns?.length) parts.push(\`Speech patterns: \${ctx.speech_patterns.join(&#x22;, &#x22;)}\`);
if (ctx.current_mood) parts.push(\`Current mood: \${JSON.stringify(ctx.current_mood)}\`);
const facts = (ctx.loaded_facts ?? []).slice(0, 5).map((f: any) => \`- \${f.atomic_text ?? &#x22;&#x22;}\`).join(&#x22;\\n&#x22;);
if (facts) parts.push(\`Relevant memories:\\n\${facts}\`);
const kb = (ctx.knowledge?.results ?? []).slice(0, 3).map((r: any) => \`- \${r.label}: \${(r.content ?? &#x22;&#x22;).slice(0, 120)}\`).join(&#x22;\\n&#x22;);
if (kb) parts.push(\`Knowledge base:\\n\${kb}\`);
return parts.join(&#x22;\\n\\n&#x22;);
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `while conversation_active:
  user_msg = await get_user_input()

  # 1. PULL FRESH CONTEXT — happens every turn, before the LLM call.
  #    session.context() returns the raw JSON from GET /agents/{id}/context
  #    as a Python dict. The shape is FLAT (no \`profile\` / \`behavioral\` /
  #    \`memory\` envelope) — fields you'll usually read:
  #      ctx[&#x22;personality_prompt&#x22;]            — agent identity / instructions
  #      ctx[&#x22;bio&#x22;]                           — agent bio
  #      ctx[&#x22;speech_patterns&#x22;]               — list[str]
  #      ctx[&#x22;true_interests&#x22;]                — list[str]
  #      ctx[&#x22;big5&#x22;]                          — Big5 trait object
  #      ctx[&#x22;current_mood&#x22;]                  — fresh inline (~300ms after .turn())
  #      ctx[&#x22;habits&#x22;]                        — list of habit summaries
  #      ctx[&#x22;active_goals&#x22;]                  — list of goal summaries
  #      ctx[&#x22;loaded_facts&#x22;]                  — recalled facts (5-15s lag from extraction)
  #      ctx[&#x22;proactive_memories&#x22;]            — pending proactive signals
  #      ctx[&#x22;constellation_patterns&#x22;]        — deeper behavioral patterns
  #      ctx[&#x22;relationship_narrative&#x22;]        — pair narrative
  #      ctx[&#x22;chemistry_score&#x22;]               — int
  #      ctx[&#x22;love_from_agent&#x22;], ctx[&#x22;love_from_user&#x22;]
  #      ctx[&#x22;knowledge&#x22;][&#x22;results&#x22;]          — KB hits (only nested key)
  #      ctx[&#x22;recent_turns&#x22;]                  — buffered messages from this session
  ctx = session.context(query=user_msg)

  # 2. Build system prompt from the context layers
  system_prompt = render_prompt_from_context(ctx)

  # 3. Run YOUR LLM — Sonzai is OUT of the loop here
  reply = await your_llm.chat(
      system=system_prompt,
      messages=[*history, {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_msg}],
  )

  # 4. Submit the just-completed turn — sync mood + async deferred extraction
  session.turn(messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_msg},
      {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply},
  ])

def render_prompt_from_context(ctx: dict) -> str:
  parts = []
  if ctx.get(&#x22;personality_prompt&#x22;):
      parts.append(ctx[&#x22;personality_prompt&#x22;])
  if ctx.get(&#x22;big5&#x22;):
      parts.append(f&#x22;Personality (Big5): {ctx['big5']}&#x22;)
  if ctx.get(&#x22;speech_patterns&#x22;):
      parts.append(f&#x22;Speech patterns: {', '.join(ctx['speech_patterns'])}&#x22;)
  if ctx.get(&#x22;current_mood&#x22;):
      parts.append(f&#x22;Current mood: {ctx['current_mood']}&#x22;)
  facts = ctx.get(&#x22;loaded_facts&#x22;) or []
  if facts:
      rendered = &#x22;\\n&#x22;.join(f&#x22;- {f.get('atomic_text', '')}&#x22; for f in facts[:5])
      parts.append(f&#x22;Relevant memories:\\n{rendered}&#x22;)
  kb_results = (ctx.get(&#x22;knowledge&#x22;) or {}).get(&#x22;results&#x22;) or []
  if kb_results:
      rendered = &#x22;\\n&#x22;.join(
          f&#x22;- {r.get('label')}: {r.get('content', '')[:120]}&#x22; for r in kb_results[:3]
      )
      parts.append(f&#x22;Knowledge base:\\n{rendered}&#x22;)
  return &#x22;\\n\\n&#x22;.join(parts)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `for conversationActive {
  userMsg := getUserInput()

  // 1. PULL FRESH CONTEXT — happens every turn, before the LLM call.
  //    ctx is a flat map — no profile/behavioral/memory envelope.
  ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: userMsg})
  if err != nil {
      return err
  }

  // 2. Build system prompt from the context layers
  systemPrompt := renderPromptFromContext(ctxData)

  // 3. Run YOUR LLM — Sonzai is OUT of the loop here
  reply, err := yourLLM.Chat(ctx, systemPrompt,
      append(history, sonzai.ChatMessage{Role: &#x22;user&#x22;, Content: userMsg}))
  if err != nil {
      return err
  }

  // 4. Submit the just-completed turn — sync mood + async deferred extraction
  _, err = session.Turn(ctx, sonzai.TurnOptions{
      Messages: []sonzai.TurnMessage{
          {Role: &#x22;user&#x22;, Content: userMsg},
          {Role: &#x22;assistant&#x22;, Content: reply},
      },
  })
  if err != nil {
      return err
  }
}

func renderPromptFromContext(ctx map[string]any) string {
  var parts []string
  if p, _ := ctx[&#x22;personality_prompt&#x22;].(string); p != &#x22;&#x22; {
      parts = append(parts, p)
  }
  if facts, ok := ctx[&#x22;loaded_facts&#x22;].([]any); ok {
      var lines []string
      for _, f := range facts {
          if fm, ok := f.(map[string]any); ok {
              lines = append(lines, &#x22;- &#x22;+fmt.Sprint(fm[&#x22;atomic_text&#x22;]))
          }
      }
      if len(lines) > 0 {
          parts = append(parts, &#x22;Relevant memories:\\n&#x22;+strings.Join(lines, &#x22;\\n&#x22;))
      }
  }
  if kb, ok := ctx[&#x22;knowledge&#x22;].(map[string]any); ok {
      if results, ok := kb[&#x22;results&#x22;].([]any); ok {
          var lines []string
          for _, r := range results {
              if rm, ok := r.(map[string]any); ok {
                  lines = append(lines, fmt.Sprintf(&#x22;- %v: %v&#x22;, rm[&#x22;label&#x22;], rm[&#x22;content&#x22;]))
              }
          }
          if len(lines) > 0 {
              parts = append(parts, &#x22;Knowledge base:\\n&#x22;+strings.Join(lines, &#x22;\\n&#x22;))
          }
      }
  }
  return strings.Join(parts, &#x22;\\n\\n&#x22;)
}`,
  },
]"
/>

<Callout type="info" title="Save a roundtrip with fetchNextContext">
  `session.turn()` accepts a `fetch_next_context={"query": next_user_message}` argument (TS: `fetchNextContext`). When set, the server runs the deferred extraction trigger AND fetches the next `/context` payload in the same response, returning it under `next_context`. This eliminates the second roundtrip on the next turn — your client already has the context for turn N+1 by the time turn N has finished. Use this when you can predict the next user query (e.g., for the very next render of context).
</Callout>

**Context freshness.** Mood updates inline on each `.turn()` call (\~300ms), so the very next `.context()` reflects the new mood. Personality / facts / inventory land 5–15 seconds after `.turn()` in the background, so they appear within a turn or two of being mentioned.

**Why per-turn.** State changes between turns. A user mentioning a new pet on turn 3 means turn 4's context should carry that fact. Skipping `.context()` between turns means the LLM works from stale state — and the value of a memory layer collapses.

**Pass the actual user message as `query`.** `session.context()` uses the query for memory recall, KB search, and proactive signal selection. Passing the raw user message gives the most relevant pull; passing a static placeholder gives generic context regardless of what the user asked.

## Skipping local history with `recent_turns` [#skipping-local-history-with-recent_turns]

Most agent harnesses (OpenAI Agents SDK, LangChain, LiveKit) own the
message log themselves — let them. But if you're rolling a thin LLM
loop and would rather not maintain a parallel `history` array on your
side, every `/context` response carries `recent_turns`: the raw
messages buffered by `/turn` for the **current session**, in
chronological order. Read them straight off the context payload.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const ctx = await session.context({ query: userMessage });

// Sonzai is the source of truth — no local history list needed.
const history = (ctx.recent_turns ?? []).map((t) => ({
role: t.role,
content: t.content,
}));

const reply = await yourLLM.chat({
system:   buildSystemPrompt(ctx),
messages: [...history, { role: &#x22;user&#x22;, content: userMessage }],
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `ctx = session.context(query=user_message)

# Sonzai is the source of truth — no local history list needed.
history = [{&#x22;role&#x22;: t[&#x22;role&#x22;], &#x22;content&#x22;: t[&#x22;content&#x22;]}
         for t in (ctx.get(&#x22;recent_turns&#x22;) or [])]

reply = your_llm.chat(
  system=build_system_prompt(ctx),
  messages=[*history, {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message}],
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: userMessage})
if err != nil { return err }

// Sonzai is the source of truth — no local history slice needed.
var history []sonzai.ChatMessage
if turns, ok := ctxData[&#x22;recent_turns&#x22;].([]any); ok {
  for _, t := range turns {
      if tm, ok := t.(map[string]any); ok {
          history = append(history, sonzai.ChatMessage{
              Role:    fmt.Sprint(tm[&#x22;role&#x22;]),
              Content: fmt.Sprint(tm[&#x22;content&#x22;]),
          })
      }
  }
}

reply, err := yourLLM.Chat(ctx, buildSystemPrompt(ctxData),
  append(history, sonzai.ChatMessage{Role: &#x22;user&#x22;, Content: userMessage}))`,
  },
]"
/>

**What's in the buffer.** Last \~20 messages from the current session
only — text content, role, and a server-side timestamp. Capped at 20
turns and scoped to `(agent_id, user_id, session_id)`; cross-session
history isn't there (use `agents.memory.list_facts` for that — facts
are the durable form).

**What's not in the buffer.** No system prompts, no `tool_calls`
arrays, no `role: "tool"` payloads, no image attachments. The buffer
mirrors the *narrative* you submitted to `/turn`, not the rich message
structure your LLM saw. If your conversation has tool calls or
multimodal content the LLM needs to re-read on the next turn, keep
your own history.

**When the buffer is empty.** Right after `sessions.start` (no turns
yet), or in degraded mode if Redis is down — the field is omitted, not
zero-length-with-error. Treat `ctx.recent_turns ?? []` as a no-op.

## Tool messages flow through to extraction [#tool-messages-flow-through-to-extraction]

The `/turn` schema accepts OpenAI/Anthropic-style tool messages: `role: "tool"` for tool results and `tool_calls` arrays on assistant messages. Pass the entire intermediate exchange — Sonzai's extractor reads tool results and can capture facts that only appeared in tool output (e.g. "user's last order shipped from Tokyo" from an `order-lookup` tool).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await session.turn({
messages: [
  { role: &#x22;user&#x22;, content: &#x22;Where did my last order ship from?&#x22; },
  {
    role: &#x22;assistant&#x22;,
    tool_calls: [{ id: &#x22;call_1&#x22;, type: &#x22;function&#x22;, function: { name: &#x22;order-lookup&#x22;, arguments: &#x22;{}&#x22; } }],
  },
  {
    role: &#x22;tool&#x22;,
    tool_call_id: &#x22;call_1&#x22;,
    content: '{&#x22;order_id&#x22;:&#x22;42&#x22;,&#x22;origin&#x22;:&#x22;Tokyo&#x22;,&#x22;carrier&#x22;:&#x22;DHL&#x22;}',
  },
  { role: &#x22;assistant&#x22;, content: &#x22;Your last order shipped from Tokyo via DHL.&#x22; },
],
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `session.turn(
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;Where did my last order ship from?&#x22;},
      {
          &#x22;role&#x22;: &#x22;assistant&#x22;,
          &#x22;content&#x22;: None,
          &#x22;tool_calls&#x22;: [{&#x22;id&#x22;: &#x22;call_1&#x22;, &#x22;type&#x22;: &#x22;function&#x22;, &#x22;function&#x22;: {&#x22;name&#x22;: &#x22;order-lookup&#x22;, &#x22;arguments&#x22;: &#x22;{}&#x22;}}],
      },
      {
          &#x22;role&#x22;: &#x22;tool&#x22;,
          &#x22;tool_call_id&#x22;: &#x22;call_1&#x22;,
          &#x22;content&#x22;: '{&#x22;order_id&#x22;:&#x22;42&#x22;,&#x22;origin&#x22;:&#x22;Tokyo&#x22;,&#x22;carrier&#x22;:&#x22;DHL&#x22;}',
      },
      {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: &#x22;Your last order shipped from Tokyo via DHL.&#x22;},
  ]
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err = session.Turn(ctx, sonzai.TurnOptions{
  Messages: []sonzai.TurnMessage{
      {Role: &#x22;user&#x22;, Content: &#x22;Where did my last order ship from?&#x22;},
      {
          Role: &#x22;assistant&#x22;,
          ToolCalls: []sonzai.ToolCall{
              {ID: &#x22;call_1&#x22;, Type: &#x22;function&#x22;, Function: sonzai.ToolCallFunction{Name: &#x22;order-lookup&#x22;, Arguments: &#x22;{}&#x22;}},
          },
      },
      {Role: &#x22;tool&#x22;, ToolCallID: &#x22;call_1&#x22;, Content: \`{&#x22;order_id&#x22;:&#x22;42&#x22;,&#x22;origin&#x22;:&#x22;Tokyo&#x22;,&#x22;carrier&#x22;:&#x22;DHL&#x22;}\`},
      {Role: &#x22;assistant&#x22;, Content: &#x22;Your last order shipped from Tokyo via DHL.&#x22;},
  },
})`,
  },
]"
/>

## Polling deferred extraction [#polling-deferred-extraction]

`/turn` returns immediately after the sync mood pass. The deeper extraction runs asynchronously and reaches `done` in 5–15s. You can poll the status if you need to gate something on it:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const { extraction_id } = await session.turn({ messages });

// Optional — only poll if you need to wait for facts/personality before doing something
let status = await session.status(extraction_id);
while (status.state !== &#x22;done&#x22; && status.state !== &#x22;failed&#x22;) {
await new Promise((r) => setTimeout(r, 1000));
status = await session.status(extraction_id);
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `import time

result = session.turn(messages=messages)

# Optional — only poll if you need to wait for facts/personality before doing something
status = session.status(result.extraction_id)
while status.state not in (&#x22;done&#x22;, &#x22;failed&#x22;):
  time.sleep(1)
  status = session.status(result.extraction_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `res, err := session.Turn(ctx, sonzai.TurnOptions{Messages: messages})
if err != nil {
  return err
}

// Optional — only poll if you need to wait for facts/personality before doing something
for {
  status, err := session.TurnStatus(ctx, res.ExtractionID)
  if err != nil {
      return err
  }
  if status.IsTerminal() {
      break
  }
  time.Sleep(time.Second)
}`,
  },
]"
/>

## Tool calling [#tool-calling]

Pattern 1 hands the tool-calling loop entirely to you. Sonzai never executes a tool — but it does **read** tool calls and tool results out of the messages you submit on `/turn`, so the extractor can capture facts that surfaced inside a tool output. There are two flavors of tools you'll typically wire up.

### A. Your own tools [#a-your-own-tools]

Use whatever your agent framework provides — `@function_tool` in the OpenAI Agents SDK, `tools=` on Anthropic, function declarations on Gemini, `@tool` in LangChain. The pattern is the same: register the tool with your LLM, run the tool-calling loop on your side, and forward the full exchange (including the assistant's `tool_calls` message and the `role: "tool"` result message) to `session.turn()`.

```python
from agents import Agent, Runner, function_tool

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

agent = Agent(name="Companion", tools=[get_current_time], model=gemini_model)
result = Runner.run_sync(agent, user_msg)

# Build the tool-aware messages array Sonzai expects.
sonzai_messages = [
    {"role": "user", "content": user_msg},
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [{
            "id": "call_1",
            "type": "function",
            "function": {"name": "get_current_time", "arguments": "{}"},
        }],
    },
    {"role": "tool", "tool_call_id": "call_1", "content": "2026-05-07T07:30:00Z"},
    {"role": "assistant", "content": result.final_output},
]
session.turn(messages=sonzai_messages)
```

When the assistant says &#x2A;"It's 7:30 AM"&#x2A; and the user replies &#x2A;"Set my morning standup for 8"&#x2A;, Sonzai's extractor sees the tool's actual output, not just the assistant's paraphrase — and can capture &#x2A;"user prefers 8 AM standups"* with the right grounding.

### B. Sonzai's capabilities as tools [#b-sonzais-capabilities-as-tools]

You can also wrap Sonzai's own REST endpoints as tools your LLM can call mid-turn. The two most useful are **knowledge base search** and **memory search** — both let the LLM pull additional context on demand without you having to inject everything up-front through `session.context()`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// TypeScript — agents.memory.search is available directly
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
import { tool } from &#x22;ai&#x22;;
import { z } from &#x22;zod&#x22;;

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

const kbSearch = tool({
description: &#x22;Search the agent's knowledge base.&#x22;,
parameters: z.object({ query: z.string() }),
execute: async ({ query }) => {
  const res = await sonzai.agents.knowledgeSearch(&#x22;agent-id&#x22;, { query, limit: 5 });
  return res.results.map((r) => \`- \${r.label}: \${r.content}\`).join(&#x22;\\n&#x22;) || &#x22;No matching knowledge.&#x22;;
},
});

const memorySearch = tool({
description: &#x22;Search the user's long-term memory.&#x22;,
parameters: z.object({ query: z.string() }),
execute: async ({ query }) => {
  const res = await sonzai.agents.memory.search(&#x22;agent-id&#x22;, {
    query,
    user_id: &#x22;user-123&#x22;,
    limit: 5,
  });
  return res.results.map((r) => \`- \${r.text}\`).join(&#x22;\\n&#x22;) || &#x22;No matching memories.&#x22;;
},
});`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from agents import function_tool
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent-id&#x22;
USER_ID = &#x22;user-123&#x22;

@function_tool
def kb_search(query: str) -> str:
  &#x22;&#x22;&#x22;Search the agent's knowledge base for facts, policies, or product details.&#x22;&#x22;&#x22;
  res = sonzai.agents.knowledge_search(AGENT_ID, query=query, limit=5)
  if not res.results:
      return &#x22;No matching knowledge.&#x22;
  return &#x22;\\n&#x22;.join(f&#x22;- {r.label}: {r.content}&#x22; for r in res.results)

@function_tool
def memory_search(query: str) -> str:
  &#x22;&#x22;&#x22;Search the user's long-term memory for past statements, preferences, or events.&#x22;&#x22;&#x22;
  # The Python SDK exposes list_facts; for keyword search, use the REST endpoint
  # /api/v1/agents/{agent_id}/memory/search?q=... or the TS/Go SDKs' agents.memory.search.
  facts = sonzai.agents.memory.list_facts(AGENT_ID, user_id=USER_ID, limit=20)
  matches = [f for f in facts.facts if query.lower() in f.content.lower()]
  return &#x22;\\n&#x22;.join(f&#x22;- {m.content}&#x22; for m in matches[:5]) or &#x22;No matching memories.&#x22;

agent = Agent(
  name=&#x22;Companion&#x22;,
  tools=[kb_search, memory_search],
  model=gemini_model,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Go — wrap Sonzai endpoints as tool functions your LLM can call.
// Pass the results back in your tool-calling loop and forward the
// full exchange (including tool messages) to session.Turn().

func kbSearch(ctx context.Context, client *sonzai.Client, agentID, query string) (string, error) {
  res, err := client.Agents.KnowledgeSearch(ctx, agentID, sonzai.AgentKBSearchOptions{
      Query: query,
      Limit: 5,
  })
  if err != nil {
      return &#x22;&#x22;, err
  }
  if len(res.Results) == 0 {
      return &#x22;No matching knowledge.&#x22;, nil
  }
  var lines []string
  for _, r := range res.Results {
      lines = append(lines, fmt.Sprintf(&#x22;- %s: %s&#x22;, r.Label, r.Content))
  }
  return strings.Join(lines, &#x22;\\n&#x22;), nil
}

func memorySearch(ctx context.Context, client *sonzai.Client, agentID, userID, query string) (string, error) {
  // Go SDK exposes Memory.Search directly
  res, err := client.Agents.Memory.Search(ctx, agentID, sonzai.MemorySearchOptions{
      Query:  query,
      UserID: userID,
  })
  if err != nil {
      return &#x22;&#x22;, err
  }
  if len(res.Results) == 0 {
      return &#x22;No matching memories.&#x22;, nil
  }
  var lines []string
  for _, r := range res.Results {
      lines = append(lines, &#x22;- &#x22;+r.Text)
  }
  return strings.Join(lines, &#x22;\\n&#x22;), nil
}`,
  },
]"
/>

<Callout type="info" title="Why expose Sonzai endpoints as tools?">
  `session.context()` returns the most relevant facts for the current `query` — a strong default. Exposing `kb_search` and `memory_search` as tools lets the LLM **decide for itself** when to dig deeper (e.g., when the user asks "what did I tell you last week about X?"). It's especially useful for agent frameworks that already think in terms of tools.
</Callout>

When the LLM calls these tools, the result lands in your tool-calling loop just like any other tool. Forward the full exchange to `session.turn()` and Sonzai's extractor will see the search results too — but be aware that re-extracting facts from a `memory_search` tool result can create echoes (the user's own past fact resurfaces as if it were new). Either skip extraction for those tool messages on your side, or trust the dedup pass.

For deeper coverage of Sonzai's tool endpoints, see the [Tool Integration guide](/docs/en/guides/tool-integration).

### What's available as a tool [#whats-available-as-a-tool]

| Sonzai endpoint                           | SDK method                                                                                                         | Useful as an LLM tool?                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Knowledge base search                     | `agents.knowledge_search(agent_id, query, limit)`                                                                  | **Yes** — LLM looks up policies, products, docs                                                    |
| Memory search                             | `agents.memory.search(agentId, { query, userId })` (TS/Go); `agents.memory.list_facts(agent_id, user_id)` (Python) | **Yes** — LLM looks up past user statements                                                        |
| Mood / personality / habits / goals reads | `agents.get_mood`, `agents.personality.get`, `agents.list_habits`, `agents.list_goals`                             | Mostly inject via `session.context()` instead — read-only state changes rarely with the user query |
| Image generation                          | `generation.generate_image`                                                                                        | Possible, but typically your app exposes this as its own UI action, not as an LLM tool             |

## Working with images & multimodal input [#working-with-images--multimodal-input]

Sonzai's memory pipeline is **text-based today**. The `/turn` and `/process` endpoints accept string content only — `DialogueMessage.content` is `string`. Your LLM can be fully multimodal (Gemini, Claude, GPT-4o all accept image URLs and audio natively) but to get image-related facts into Sonzai you need to bridge the multimodal content into text in the messages you send to `/turn`.

The recommended pattern is **dual-output**: have your vision-capable LLM produce both (a) the warm reply you show the user and (b) a hidden `[MEMORY: ...]` line with a detailed factual description. Strip the `[MEMORY: ...]` line out before showing the user, and embed it in the bridged text you submit to Sonzai.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import OpenAI from &#x22;openai&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const gemini = new OpenAI({
baseURL: &#x22;https://generativelanguage.googleapis.com/v1beta/openai/&#x22;,
apiKey: process.env.GEMINI_API_KEY!,
});
const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

const SYSTEM_PROMPT_IMAGE_AWARE = \`You are a friendly companion. When the user shares an image, respond warmly
to what's emotionally important to THEM.

After your reply, ALWAYS include a single line:
[MEMORY: <detailed factual description of the image — setting, objects,
people, mood, time of day, what the user appears to be doing>]

The user does NOT see the [MEMORY: ...] line.\`;

async function processImageTurn(session: any, userMsg: string, imageUrl: string): Promise<string> {
const result = await gemini.chat.completions.create({
  model: &#x22;gemini-3.1-flash-lite-preview&#x22;,
  messages: [
    { role: &#x22;system&#x22;, content: SYSTEM_PROMPT_IMAGE_AWARE },
    {
      role: &#x22;user&#x22;,
      content: [
        { type: &#x22;text&#x22;, text: userMsg },
        { type: &#x22;image_url&#x22;, image_url: { url: imageUrl } },
      ],
    },
  ],
});
const raw = result.choices[0].message.content ?? &#x22;&#x22;;

// Split the dual output
const m = raw.match(/\\[MEMORY:\\s*([\\s\\S]+?)\\]/);
const memoryNote = m ? m[1].trim() : &#x22;&#x22;;
const reply = raw.replace(/\\[MEMORY:[\\s\\S]+?\\]/, &#x22;&#x22;).trim();

sendToUser(reply);

await session.turn({
  messages: [
    { role: &#x22;user&#x22;, content: \`\${userMsg}\\n\\n[Image attached: \${memoryNote}, URL: \${imageUrl}]\` },
    { role: &#x22;assistant&#x22;, content: reply },
  ],
});
return reply;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `import re
from openai import AsyncOpenAI
from sonzai import Sonzai

gemini = AsyncOpenAI(
  base_url=&#x22;https://generativelanguage.googleapis.com/v1beta/openai/&#x22;,
  api_key=os.environ[&#x22;GEMINI_API_KEY&#x22;],
)
sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

SYSTEM_PROMPT_IMAGE_AWARE = &#x22;&#x22;&#x22;
You are a friendly companion. When the user shares an image, respond warmly
to what's emotionally important to THEM (their feelings, achievements, what
they're showing off).

After your reply, ALWAYS include a single line:
[MEMORY: <detailed factual description of the image — setting, objects,
people, mood, time of day, what the user appears to be doing>]

The user does NOT see the [MEMORY: ...] line. The developer's code parses
it out and feeds the description to Sonzai for fact extraction.
&#x22;&#x22;&#x22;

# Per turn (when the user attaches an image):
user_msg = &#x22;Just hit a new PR at the gym!&#x22;
image_url = &#x22;https://example.com/gym-selfie.jpg&#x22;

result = await gemini.chat.completions.create(
  model=&#x22;gemini-3.1-flash-lite-preview&#x22;,
  messages=[
      {&#x22;role&#x22;: &#x22;system&#x22;, &#x22;content&#x22;: SYSTEM_PROMPT_IMAGE_AWARE},
      {
          &#x22;role&#x22;: &#x22;user&#x22;,
          &#x22;content&#x22;: [
              {&#x22;type&#x22;: &#x22;text&#x22;, &#x22;text&#x22;: user_msg},
              {&#x22;type&#x22;: &#x22;image_url&#x22;, &#x22;image_url&#x22;: {&#x22;url&#x22;: image_url}},
          ],
      },
  ],
)
raw = result.choices[0].message.content

# Split the dual output:
m = re.search(r&#x22;\\[MEMORY:\\s*(.+?)\\]&#x22;, raw, re.DOTALL)
memory_note = m.group(1).strip() if m else &#x22;&#x22;
reply = re.sub(r&#x22;\\[MEMORY:.+?\\]&#x22;, &#x22;&#x22;, raw, flags=re.DOTALL).strip()

# Show the user only the warm reply:
send_to_user(reply)

# Send to Sonzai with the memory description embedded in the user message:
session.turn(messages=[
  {
      &#x22;role&#x22;: &#x22;user&#x22;,
      &#x22;content&#x22;: f&#x22;{user_msg}\\n\\n[Image attached: {memory_note}, URL: {image_url}]&#x22;,
  },
  {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply},
])

# Sonzai's deferred extraction now captures facts like:
#   - &#x22;user goes to the gym&#x22; (habit)
#   - &#x22;user takes mirror selfies after PRs&#x22; (pattern)
#   - &#x22;user wore a black tank top&#x22; (inventory item)
# All retrievable via session.context(query=&#x22;gym&#x22;) on the next turn.`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Go — use github.com/openai/openai-go pointed at Gemini's OpenAI-compat URL,
// or make a raw HTTP POST to the Gemini API directly.
// The pattern is identical to TS/Python: dual-output, strip [MEMORY:...], bridge to session.Turn.

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;regexp&#x22;
  &#x22;strings&#x22;
  openai &#x22;github.com/openai/openai-go&#x22;
  &#x22;github.com/openai/openai-go/option&#x22;
  sonzaisdk &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

var memoryRE = regexp.MustCompile(\`(?s)\\[MEMORY:\\s*(.+?)\\]\`)

func processImageTurn(ctx context.Context, session *sonzaisdk.Session, userMsg, imageURL string) (string, error) {
  gemini := openai.NewClient(
      option.WithBaseURL(&#x22;https://generativelanguage.googleapis.com/v1beta/openai/&#x22;),
      option.WithAPIKey(os.Getenv(&#x22;GEMINI_API_KEY&#x22;)),
  )

  resp, err := gemini.Chat.Completions.New(ctx, openai.ChatCompletionNewParams{
      Model: openai.F(&#x22;gemini-3.1-flash-lite-preview&#x22;),
      Messages: openai.F([]openai.ChatCompletionMessageParamUnion{
          openai.SystemMessage(systemPromptImageAware),
          openai.UserMessageParts(
              openai.TextPart(userMsg),
              openai.ImagePart(imageURL),
          ),
      }),
  })
  if err != nil {
      return &#x22;&#x22;, err
  }
  raw := resp.Choices[0].Message.Content

  // Split the dual output
  m := memoryRE.FindStringSubmatch(raw)
  memoryNote := &#x22;&#x22;
  if len(m) > 1 {
      memoryNote = strings.TrimSpace(m[1])
  }
  reply := strings.TrimSpace(memoryRE.ReplaceAllString(raw, &#x22;&#x22;))

  sendToUser(reply)

  _, err = session.Turn(ctx, sonzaisdk.TurnOptions{
      Messages: []sonzaisdk.TurnMessage{
          {Role: &#x22;user&#x22;, Content: fmt.Sprintf(&#x22;%s\\n\\n[Image attached: %s, URL: %s]&#x22;, userMsg, memoryNote, imageURL)},
          {Role: &#x22;assistant&#x22;, Content: reply},
      },
  })
  return reply, err
}`,
  },
]"
/>

**Why this pattern:**

* **No backend multimodal yet.** `/turn` accepts string content. Text-bridging through your same vision-capable LLM is the cleanest workaround.
* **Why dual-output (vs. a separate vision call).** The same LLM call serves both purposes — no extra cost, no extra latency, no second roundtrip. You're already paying for vision on the assistant turn; let it produce the description too.
* **Why a hidden line.** Keeps user-facing replies emotionally warm — "Oh you have such nice shoulders!" — while still capturing the factual detail (gym, tank top, mirror, time of day) that memory extraction needs.
* **It's a developer pattern, not a Sonzai field.** The `[MEMORY: ...]` convention is yours to define. Sonzai just sees text. You can use any sentinel — `<<MEM>>...<</MEM>>`, JSON, whatever your prompt and parser agree on.

**Including the URL.** Embedding the URL in the bridged text isn't required, but it lets Sonzai later surface the image as a memory artifact ("the photo you shared last week") without re-running vision on the image. Your app keeps using its own image storage; Sonzai just remembers the link as text.

<Callout type="info" title="Audio & voice follow the same pattern">
  Speech-to-text (STT) on your side, send the transcript in `messages`. Text-to-speech (TTS) is rendered after the assistant text exists, so you forward the assistant text to `session.turn()` exactly as you would for a text-only chat. See the [Voice AI use case](#use-case-voice-ai-assistant) below.
</Callout>

<Callout type="info" title="Why text-only /turn is the design, not a placeholder">
  Memory is a layer of *semantic understanding*. The question Sonzai needs to answer next week 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; text-bridging passes that understanding through to extraction in the form the memory pipeline actually consumes (atomic facts, habits, inventory). Storing raw image bytes server-side would inflate cost without improving recall, and would re-couple your LLM choice to ours. The dual-output pattern keeps your harness fully in charge of perception.
</Callout>

## Use case: chat companion (OpenAI Agents SDK + Gemini) [#use-case-chat-companion-openai-agents-sdk--gemini]

The canonical Pattern 1 example. You bring your own agent harness — here the **OpenAI Agents SDK** — and route it at **Gemini** via the OpenAI-compat endpoint, so no `OPENAI_API_KEY` is ever used. Sonzai sits *outside* the LLM/tool-calling loop entirely: it supplies the system prompt via `session.context()` and ingests the finished transcript via `session.turn()`. The Agents SDK does all multi-step reasoning and tool dispatch on your side; Sonzai does memory.

```python
import os
from openai import AsyncOpenAI
from agents import (
    Agent,
    Runner,
    OpenAIChatCompletionsModel,
    function_tool,
    set_tracing_disabled,
)
from sonzai import Sonzai

# The Agents SDK ships traces to OpenAI by default — disable, since we
# have no OpenAI key and aren't talking to OpenAI's servers at all.
set_tracing_disabled(True)

# Point the Agents SDK's AsyncOpenAI client at Gemini's OpenAI-compat URL.
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,
)

# Sonzai = memory layer only. It never sees the LLM client.
sonzai = Sonzai(api_key=os.environ["SONZAI_API_KEY"])
session = sonzai.agents.sessions.start(
    "agent-id",
    user_id="user-123",
    session_id="session-abc",
)

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

while True:
    user_msg = input("You: ")
    if not user_msg:
        break

    # 1) Pull enriched context (mood, personality, relevant facts, …) from Sonzai.
    ctx = session.context(query=user_msg)

    mood = ctx.get("current_mood") or "neutral"
    instructions = f"You are a friendly companion. Current mood: {mood}."

    # 2) Run the Agents SDK loop — it handles tool-calling and multi-step reasoning.
    agent = Agent(
        name="Companion",
        instructions=instructions,
        model=model,
        tools=[get_current_time],
    )
    result = Runner.run_sync(agent, user_msg)
    print(f"Assistant: {result.final_output}")

    # 3) Convert the run's items (assistant text + ToolCallItem + ToolCallOutputItem)
    # into Sonzai's tool-aware messages format. See the demo for the implementation.
    sonzai_messages = run_result_to_sonzai_messages(user_msg, result)

    # 4) Submit the turn. `mood` comes back inline (~300ms); facts / personality /
    # inventory are extracted asynchronously and land 5-15s later.
    turn_result = session.turn(messages=sonzai_messages)
    print(f"  -> mood updated: {turn_result.mood}")

session.end()
```

**What's happening on each turn:**

* **Sonzai is out of the LLM loop.** The OpenAI Agents SDK runs the model, dispatches tools, and produces `result.final_output`. Sonzai never sees the LLM client and has no opinion on which model answered.
* **Mood is real-time.** `session.turn()` returns fresh mood inline in \~300ms — you can render it the moment the response arrives.
* **Facts, personality drift, and inventory are deferred (5-15s).** They run async under the returned `extraction_id`. Re-poll `agents.memory.list_facts`, `agents.personality.get`, etc. on the next turn; whatever didn't land yet will be there shortly.
* **Tool calls flow through to extraction.** Sonzai's tool-aware message format accepts `assistant` messages with `tool_calls` plus a `tool` message carrying the result. The conversion helper packages the Agents SDK's `ToolCallItem` + `ToolCallOutputItem` into that shape so extraction can pick up facts from tool outputs too.

Want a working version? See [the OpenAI Agents companion demo](https://github.com/sonz-ai/sonzai-python/tree/main/demos/openai_agents_companion) — a two-pane Streamlit app showing live mood, Big5, recent facts, inventory, and the constellation graph as you chat.

## Use case: voice AI assistant [#use-case-voice-ai-assistant]

STT → enrich → LLM → TTS. Sonzai holds the memory; you own the audio pipeline. Submit the turn while TTS is synthesizing — sync mood is fast enough not to block, and deferred extraction never blocks.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function processVoiceTurn(
session: any, // Session handle from sonzai.agents.sessions.start
audioBuffer: Buffer
): Promise<Buffer> {
// Your STT
const transcript = await yourSTT.transcribe(audioBuffer);

// Inject memory into a concise voice-friendly system prompt
const ctx = await session.context({ query: transcript });

const systemPrompt = \`\${ctx.personality_prompt ?? &#x22;You are a voice companion.&#x22;} Keep replies under 2 sentences for voice.
Mood: \${JSON.stringify(ctx.current_mood)}.
Key memory: \${ctx.loaded_facts?.[0]?.atomic_text ?? &#x22;none&#x22;}.\`;

const reply = await yourLLM.chat({ system: systemPrompt, message: transcript });

// Submit the turn while TTS synthesizes (run in parallel)
const [audioResponse] = await Promise.all([
  yourTTS.synthesize(reply),
  session.turn({
    messages: [
      { role: &#x22;user&#x22;, content: transcript },
      { role: &#x22;assistant&#x22;, content: reply },
    ],
  }),
]);

return audioResponse;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `import asyncio
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

async def process_voice_turn(session, audio_bytes: bytes) -> bytes:
  # Your STT
  transcript = await your_stt.transcribe(audio_bytes)

  # Inject memory into a concise voice-friendly system prompt
  ctx = session.context(query=transcript)

  mood = ctx.get(&#x22;current_mood&#x22;, {})
  key_memory = (ctx.get(&#x22;loaded_facts&#x22;) or [{}])[0].get(&#x22;atomic_text&#x22;, &#x22;none&#x22;)
  system_prompt = (
      f&#x22;{ctx.get('personality_prompt', 'You are a voice companion.')} &#x22;
      f&#x22;Keep replies under 2 sentences for voice.\\n&#x22;
      f&#x22;Mood: {mood}.\\nKey memory: {key_memory}.&#x22;
  )

  reply = await your_llm.chat(system=system_prompt, message=transcript)

  # Submit the turn while TTS synthesizes (run in parallel)
  audio_response, _ = await asyncio.gather(
      your_tts.synthesize(reply),
      asyncio.to_thread(session.turn, messages=[
          {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: transcript},
          {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply},
      ]),
  )
  return audio_response`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func processVoiceTurn(ctx context.Context, session *sonzai.Session, audioBytes []byte) ([]byte, error) {
  // Your STT
  transcript, err := yourSTT.Transcribe(ctx, audioBytes)
  if err != nil {
      return nil, err
  }

  // Inject memory into a concise voice-friendly system prompt
  ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: transcript})
  if err != nil {
      return nil, err
  }

  personality, _ := ctxData[&#x22;personality_prompt&#x22;].(string)
  if personality == &#x22;&#x22; {
      personality = &#x22;You are a voice companion.&#x22;
  }
  moodJSON, _ := json.Marshal(ctxData[&#x22;current_mood&#x22;])
  keyMem := &#x22;none&#x22;
  if facts, ok := ctxData[&#x22;loaded_facts&#x22;].([]any); ok && len(facts) > 0 {
      if fm, ok := facts[0].(map[string]any); ok {
          keyMem = fmt.Sprint(fm[&#x22;atomic_text&#x22;])
      }
  }
  systemPrompt := fmt.Sprintf(
      &#x22;%s Keep replies under 2 sentences for voice.\\nMood: %s.\\nKey memory: %s.&#x22;,
      personality, moodJSON, keyMem,
  )

  reply, err := yourLLM.Chat(ctx, systemPrompt, transcript)
  if err != nil {
      return nil, err
  }

  // Submit the turn while TTS synthesizes (run in parallel)
  type audioResult struct{ data []byte; err error }
  audioCh := make(chan audioResult, 1)
  go func() {
      data, err := yourTTS.Synthesize(ctx, reply)
      audioCh <- audioResult{data, err}
  }()

  _, err = session.Turn(ctx, sonzai.TurnOptions{
      Messages: []sonzai.TurnMessage{
          {Role: &#x22;user&#x22;, Content: transcript},
          {Role: &#x22;assistant&#x22;, Content: reply},
      },
  })
  if err != nil {
      return nil, err
  }

  res := <-audioCh
  return res.data, res.err
}`,
  },
]"
/>

## Use case: agent framework (LangChain / LlamaIndex) [#use-case-agent-framework-langchain--llamaindex]

Sonzai injects user context into the agent's system prompt. The framework handles tool calling, multi-step reasoning, and memory of the current conversation; Sonzai handles what the agent knows about the user across sessions. Send the full transcript including any tool messages to `session.turn()` so extraction can pick up facts from tool results.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { ChatOpenAI } from &#x22;@langchain/openai&#x22;;
import { SystemMessage, HumanMessage, AIMessage } from &#x22;@langchain/core/messages&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const llm = new ChatOpenAI({ model: &#x22;gpt-4o&#x22;, tools: yourToolSchemas });

async function agentTurn(
session: any,
userInput: string,
messageHistory: (HumanMessage | AIMessage)[]
): Promise<string> {
const ctx = await session.context({ query: userInput });

const messages = [
  new SystemMessage(buildSystemPrompt(ctx)),
  ...messageHistory,
  new HumanMessage(userInput),
];

// Run the agent's full tool-calling loop on your side, then surface
// every intermediate message (assistant tool_calls + tool results)
// to Sonzai so it can extract from them.
const { reply, intermediate } = await runLangchainAgent(llm, messages);

await session.turn({
  messages: [
    { role: &#x22;user&#x22;, content: userInput },
    ...intermediate,
    { role: &#x22;assistant&#x22;, content: reply },
  ],
});

return reply;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from langchain_openai import ChatOpenAI
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
llm = ChatOpenAI(model=&#x22;gpt-4o&#x22;).bind_tools(your_tool_schemas)

async def agent_turn(session, user_input: str, message_history: list) -> str:
  ctx = session.context(query=user_input)

  messages = [
      SystemMessage(content=build_system_prompt(ctx)),
      *message_history,
      HumanMessage(content=user_input),
  ]

  # Run the agent's full tool-calling loop on your side, then surface
  # every intermediate message (assistant tool_calls + tool results)
  # to Sonzai so it can extract from them.
  reply, intermediate = await run_langchain_agent(llm, messages)

  session.turn(
      messages=[
          {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_input},
          *intermediate,
          {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply},
      ]
  )
  return reply`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Go has no official LangChain port. Wrap any chat client (e.g., Anthropic,
// OpenAI, or google/generative-ai-go) in your own tool loop and forward
// the full exchange — assistant tool_calls + tool results — to session.Turn.

import &#x22;github.com/sonz-ai/sonzai-go&#x22;

func agentTurn(ctx context.Context, session *sonzai.Session, userInput string, history []sonzai.ChatMessage) (string, error) {
  ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: userInput})
  if err != nil {
      return &#x22;&#x22;, err
  }

  systemPrompt := buildSystemPrompt(ctxData)

  // Run your own tool-calling loop — swap in any Go chat client here.
  reply, intermediate, err := runYourAgentLoop(ctx, systemPrompt,
      append(history, sonzai.ChatMessage{Role: &#x22;user&#x22;, Content: userInput}),
      yourTools)
  if err != nil {
      return &#x22;&#x22;, err
  }

  // Forward the full exchange including all tool messages.
  turnMsgs := []sonzai.TurnMessage{{Role: &#x22;user&#x22;, Content: userInput}}
  turnMsgs = append(turnMsgs, intermediate...)
  turnMsgs = append(turnMsgs, sonzai.TurnMessage{Role: &#x22;assistant&#x22;, Content: reply})

  _, err = session.Turn(ctx, sonzai.TurnOptions{Messages: turnMsgs})
  return reply, err
}`,
  },
]"
/>

## Use case: multi-LLM router [#use-case-multi-llm-router]

Route to different models based on task type while Sonzai stitches user memory across all of them. The Session-level provider/model default is just a default — every `.turn()` can override.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import Anthropic from &#x22;@anthropic-ai/sdk&#x22;;
import { GoogleGenAI } from &#x22;@google/genai&#x22;;
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const claude = new Anthropic();
const gemini = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

type TaskType = &#x22;creative&#x22; | &#x22;analytical&#x22; | &#x22;casual&#x22;;

function classifyTask(message: string): TaskType {
if (/write|story|poem|imagine/i.test(message)) return &#x22;creative&#x22;;
if (/analyze|compare|explain|why/i.test(message)) return &#x22;analytical&#x22;;
return &#x22;casual&#x22;;
}

async function routedTurn(session: any, userMessage: string): Promise<string> {
const ctx = await session.context({ query: userMessage });
const systemPrompt = buildSystemPrompt(ctx);
const task = classifyTask(userMessage);

let reply: string;

if (task === &#x22;creative&#x22;) {
  const response = await claude.messages.create({
    model: &#x22;claude-sonnet-4-6&#x22;,
    max_tokens: 1024,
    system: systemPrompt,
    messages: [{ role: &#x22;user&#x22;, content: userMessage }],
  });
  reply = response.content[0].type === &#x22;text&#x22; ? response.content[0].text : &#x22;&#x22;;
} else {
  const response = await gemini.models.generateContent({
    model: &#x22;gemini-2.5-flash&#x22;,
    contents: [{ role: &#x22;user&#x22;, parts: [{ text: systemPrompt + &#x22;\\n\\n&#x22; + userMessage }] }],
  });
  reply = response.text ?? &#x22;&#x22;;
}

// Same .turn() call regardless of which chat model answered.
await session.turn({
  messages: [
    { role: &#x22;user&#x22;, content: userMessage },
    { role: &#x22;assistant&#x22;, content: reply },
  ],
});

return reply;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `import anthropic
import google.generativeai as genai
from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
claude = anthropic.Anthropic()
genai.configure(api_key=os.environ[&#x22;GEMINI_API_KEY&#x22;])

def classify_task(message: str) -> str:
  import re
  if re.search(r&#x22;write|story|poem|imagine&#x22;, message, re.IGNORECASE):
      return &#x22;creative&#x22;
  if re.search(r&#x22;analyze|compare|explain|why&#x22;, message, re.IGNORECASE):
      return &#x22;analytical&#x22;
  return &#x22;casual&#x22;

def routed_turn(session, user_message: str) -> str:
  ctx = session.context(query=user_message)
  system_prompt = build_system_prompt(ctx)
  task = classify_task(user_message)

  if task == &#x22;creative&#x22;:
      response = claude.messages.create(
          model=&#x22;claude-sonnet-4-6&#x22;,
          max_tokens=1024,
          system=system_prompt,
          messages=[{&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message}],
      )
      reply = response.content[0].text
  else:
      model = genai.GenerativeModel(&#x22;gemini-2.5-flash&#x22;,
          system_instruction=system_prompt)
      response = model.generate_content(user_message)
      reply = response.text

  # Same .turn() call regardless of which chat model answered.
  session.turn(
      messages=[
          {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message},
          {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply},
      ]
  )
  return reply`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  &#x22;regexp&#x22;
  anthropic &#x22;github.com/anthropics/anthropic-sdk-go&#x22;
  &#x22;google.golang.org/api/option&#x22;
  genai &#x22;github.com/google/generative-ai-go/genai&#x22;
  sonzaisdk &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

var (
  creativeRE   = regexp.MustCompile(\`(?i)write|story|poem|imagine\`)
  analyticalRE = regexp.MustCompile(\`(?i)analyze|compare|explain|why\`)
)

func classifyTask(msg string) string {
  if creativeRE.MatchString(msg) { return &#x22;creative&#x22; }
  if analyticalRE.MatchString(msg) { return &#x22;analytical&#x22; }
  return &#x22;casual&#x22;
}

func routedTurn(ctx context.Context, session *sonzaisdk.Session, userMessage string) (string, error) {
  ctxData, err := session.Context(ctx, sonzaisdk.ContextOptions{Query: userMessage})
  if err != nil {
      return &#x22;&#x22;, err
  }
  systemPrompt := buildSystemPrompt(ctxData)
  task := classifyTask(userMessage)

  var reply string
  if task == &#x22;creative&#x22; {
      client := anthropic.NewClient()
      resp, err := client.Messages.New(ctx, anthropic.MessageNewParams{
          Model:     anthropic.F(anthropic.ModelClaudeSonnet4_6),
          MaxTokens: anthropic.F(int64(1024)),
          System:    anthropic.F([]anthropic.TextBlockParam{{Type: anthropic.F(anthropic.TextBlockParamTypeText), Text: anthropic.F(systemPrompt)}}),
          Messages:  anthropic.F([]anthropic.MessageParam{anthropic.UserMessage(userMessage)}),
      })
      if err != nil { return &#x22;&#x22;, err }
      reply = resp.Content[0].Text
  } else {
      geminiClient, _ := genai.NewClient(ctx, option.WithAPIKey(os.Getenv(&#x22;GEMINI_API_KEY&#x22;)))
      model := geminiClient.GenerativeModel(&#x22;gemini-2.5-flash&#x22;)
      model.SystemInstruction = &genai.Content{Parts: []genai.Part{genai.Text(systemPrompt)}}
      resp, err := model.GenerateContent(ctx, genai.Text(userMessage))
      if err != nil { return &#x22;&#x22;, err }
      reply = fmt.Sprint(resp.Candidates[0].Content.Parts[0])
  }

  // Same .Turn() call regardless of which chat model answered.
  _, err = session.Turn(ctx, sonzaisdk.TurnOptions{
      Messages: []sonzaisdk.TurnMessage{
          {Role: &#x22;user&#x22;, Content: userMessage},
          {Role: &#x22;assistant&#x22;, Content: reply},
      },
  })
  return reply, err
}`,
  },
]"
/>

## Use case: privacy-first (anonymize before LLM) [#use-case-privacy-first-anonymize-before-llm]

Redact PII from the enriched context before it reaches your LLM. Only structured extracted facts are stored by Sonzai — never raw text.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `async function privacyTurn(session: any, userMessage: string): Promise<string> {
const ctx = await session.context({ query: userMessage });

// Scrub PII from facts before they reach your LLM
const sanitizedFacts = (ctx.loaded_facts ?? []).map((f: any) => ({
  ...f,
  atomic_text: redactPII(f.atomic_text), // your PII redaction logic
}));

const sanitizedCtx = { ...ctx, loaded_facts: sanitizedFacts };
const systemPrompt = buildSystemPrompt(sanitizedCtx);

const reply = await yourLLM.chat({ system: systemPrompt, message: userMessage });

// Send unredacted transcript to Sonzai for extraction
// (Sonzai stores structured facts, not raw text)
await session.turn({
  messages: [
    { role: &#x22;user&#x22;, content: userMessage },
    { role: &#x22;assistant&#x22;, content: reply },
  ],
});

return reply;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `def privacy_turn(session, user_message: str) -> str:
  ctx = session.context(query=user_message)

  # Scrub PII from facts before they reach your LLM
  sanitized_facts = [
      {**f, &#x22;atomic_text&#x22;: redact_pii(f.get(&#x22;atomic_text&#x22;, &#x22;&#x22;))}
      for f in (ctx.get(&#x22;loaded_facts&#x22;) or [])
  ]

  sanitized_ctx = {**ctx, &#x22;loaded_facts&#x22;: sanitized_facts}
  system_prompt = build_system_prompt(sanitized_ctx)

  reply = your_llm.chat(system=system_prompt, message=user_message)

  # Send unredacted transcript to Sonzai for extraction
  # (Sonzai stores structured facts, not raw text)
  session.turn(
      messages=[
          {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: user_message},
          {&#x22;role&#x22;: &#x22;assistant&#x22;, &#x22;content&#x22;: reply},
      ]
  )
  return reply`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `func privacyTurn(ctx context.Context, session *sonzai.Session, userMessage string) (string, error) {
  ctxData, err := session.Context(ctx, sonzai.ContextOptions{Query: userMessage})
  if err != nil {
      return &#x22;&#x22;, err
  }

  // Scrub PII from facts before they reach your LLM
  if facts, ok := ctxData[&#x22;loaded_facts&#x22;].([]any); ok {
      sanitized := make([]any, len(facts))
      for i, f := range facts {
          if fm, ok := f.(map[string]any); ok {
              copy := map[string]any{}
              for k, v := range fm { copy[k] = v }
              copy[&#x22;atomic_text&#x22;] = redactPII(fmt.Sprint(fm[&#x22;atomic_text&#x22;]))
              sanitized[i] = copy
          } else {
              sanitized[i] = f
          }
      }
      ctxData[&#x22;loaded_facts&#x22;] = sanitized
  }

  systemPrompt := buildSystemPrompt(ctxData)
  reply, err := yourLLM.Chat(ctx, systemPrompt, userMessage)
  if err != nil {
      return &#x22;&#x22;, err
  }

  // Send unredacted transcript to Sonzai for extraction
  // (Sonzai stores structured facts, not raw text)
  _, err = session.Turn(ctx, sonzai.TurnOptions{
      Messages: []sonzai.TurnMessage{
          {Role: &#x22;user&#x22;, Content: userMessage},
          {Role: &#x22;assistant&#x22;, Content: reply},
      },
  })
  return reply, err
}`,
  },
]"
/>

## Next [#next]

* [Pattern 2: Post-Session Batch Processing](/docs/en/guides/standalone-memory/pattern-2-batch) — when Sonzai shouldn't be in the hot path
* [Endpoint walkthrough](/docs/en/guides/standalone-memory/endpoints) — full reference for `sessions.start`, `context`, `turn`, `process`, `end`, and read endpoints
* [KB & limitations](/docs/en/guides/standalone-memory/limitations) — knowledge base behavior in standalone mode and what's not supported


---

# Pattern 2: Post-Session Batch Processing

Source: https://sonz.ai/docs/en/guides/standalone-memory/pattern-2-batch

> You own the entire conversation. Sonzai never sees it in real time. When the conversation ends, send the full transcript to /process or sessions.end({ messages }).



You own the entire conversation. Sonzai never sees it in real time. When the conversation ends, you send the full transcript to either `/process` or `sessions.end({ messages })`. Sonzai extracts facts, updates the user's behavioral profile, and makes the insights available via the API — ready for personalization, analytics, push notifications, or next-session context.

This pattern is ideal when Sonzai being in the hot path is undesirable (or impossible) — latency-sensitive real-time interactions, apps with their own LLM loop already in production, or cases where you want to process transcripts in bulk after the fact.

<Diagram>
  {`
    ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
    │  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 update, │                       │
         │   exercises, etc.)  │                       │
         └─────────────────────┴───────────────────────┘
    `}
</Diagram>

<Callout type="info" title="Pick one trigger, not both">
  `/process` and `sessions.end({ messages })` are functionally equivalent for batch ingest — both extract facts and side-effects from the full transcript inline. **Don't do both** for the same transcript or extraction runs twice. Use `/process` if you want a single call (it auto-creates the session and surfaces the generated `session_id` in the response). Use `sessions.start` + `sessions.end({ messages })` if you want explicit lifecycle, async polling, or session-scoped tools.
</Callout>

## Core steps [#core-steps]

**Option A — `/process` only.** One call. Auto-creates a session if you don't pass one. Returns the auto-generated `session_id` so you can correlate later.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function processTranscript(
agentId: string,
userId: string,
transcript: { role: &#x22;user&#x22; | &#x22;assistant&#x22; | &#x22;tool&#x22;; content: string; tool_calls?: any[] }[]
) {
const result = await sonzai.agents.process(agentId, {
  userId,
  messages: transcript,                          // tool messages allowed
  provider: &#x22;gemini&#x22;,                            // optional override
  model: &#x22;gemini-3.1-flash-lite-preview&#x22;,        // optional override
});

// result.session_id is the auto-created session id when none was passed.
// Read the extracted facts/mood/etc. via the dedicated endpoints below.
return result;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def process_transcript(agent_id: str, user_id: str, transcript: list[dict]) -> object:
  result = sonzai.agents.process(
      agent_id,
      user_id=user_id,
      messages=transcript,          # tool messages allowed
      provider=&#x22;gemini&#x22;,            # optional override
      model=&#x22;gemini-3.1-flash-lite-preview&#x22;,
  )
  # result.session_id is the auto-created session id when none was passed.
  return result`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  &#x22;os&#x22;
  &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func processTranscript(ctx context.Context, agentID, userID string, transcript []sonzai.ChatMessage) (*sonzai.ProcessResponse, error) {
  client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  if err != nil {
      return nil, err
  }
  return client.Agents.Process(ctx, agentID, sonzai.ProcessOptions{
      UserID:    userID,
      Messages:  transcript, // tool messages allowed
      Provider:  &#x22;gemini&#x22;,
      Model:     &#x22;gemini-3.1-flash-lite-preview&#x22;,
  })
  // result.session_id is the auto-created session id when none was passed.
}`,
  },
]"
/>

**Option B — Explicit `sessions.start` + `sessions.end({ messages })`.** Use this when you want async processing, session-scoped tools, or explicit lifecycle ownership.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `async function processTranscript(
agentId: string,
userId: string,
transcript: { role: &#x22;user&#x22; | &#x22;assistant&#x22; | &#x22;tool&#x22;; content: string }[]
) {
const sessionId = \`session-\${Date.now()}\`;

const session = await sonzai.agents.sessions.start(agentId, { userId, sessionId });

// Pass the full transcript on end — extraction happens here, not via /process.
// sessions.end({ messages }) is functionally equivalent to /process({ messages }).
const result = await session.end({
  messages: transcript,
  totalMessages: transcript.length,
});

return result;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `import time

def process_transcript_with_lifecycle(agent_id: str, user_id: str, transcript: list[dict]) -> object:
  session_id = f&#x22;session-{int(time.time() * 1000)}&#x22;

  session = sonzai.agents.sessions.start(agent_id, user_id=user_id, session_id=session_id)

  # Pass the full transcript on end — extraction happens here, not via /process.
  return session.end(
      messages=transcript,
      total_messages=len(transcript),
  )`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;time&#x22;
  &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func processTranscriptWithLifecycle(ctx context.Context, client *sonzai.Client, agentID, userID string, transcript []sonzai.ChatMessage) error {
  sessionID := fmt.Sprintf(&#x22;session-%d&#x22;, time.Now().UnixMilli())

  session, err := client.Agents.Sessions.Start(ctx, agentID, sonzai.SessionStartOptions{
      UserID:    userID,
      SessionID: sessionID,
  })
  if err != nil {
      return err
  }

  // Pass the full transcript on end — extraction happens here, not via /process.
  return session.End(ctx, sonzai.SessionEndOptions{
      Messages:      transcript,
      TotalMessages: len(transcript),
  })
}`,
  },
]"
/>

Pick one. The two options are equivalent for fact extraction — chaining them just runs extraction twice on the same messages.

## Use case: AI tutoring app [#use-case-ai-tutoring-app]

Before the session, pull the student's profile to personalize the curriculum. After the session, extract what was learned and generate targeted practice exercises. One call to `/process` is enough.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function beforeTutoringSession(agentId: string, studentId: string, topic: string) {
const ctx = await sonzai.agents.getContext(agentId, {
  userId: studentId,
  query: \`\${topic} concepts learned struggles difficulty level\`,
});

const knownConcepts = (ctx.loaded_facts ?? [])
  .filter((f: any) => f.fact_type === &#x22;semantic&#x22;)
  .map((f: any) => f.atomic_text);

const weakAreas = (ctx.habits ?? [])
  .filter((h: any) => h.label?.toLowerCase().includes(&#x22;struggle&#x22;))
  .map((h: any) => h.label);

return { knownConcepts, weakAreas };
}

async function afterTutoringSession(
agentId: string,
studentId: string,
topic: string,
transcript: { role: &#x22;user&#x22; | &#x22;assistant&#x22;; content: string }[]
) {
await sonzai.agents.process(agentId, { userId: studentId, messages: transcript });

const [memory, interests, mood] = await Promise.all([
  sonzai.agents.memory.list(agentId, { userId: studentId }),
  sonzai.agents.getInterests(agentId, { userId: studentId }),
  sonzai.agents.getMood(agentId, { userId: studentId }),
]);

const allFacts = Object.values(memory.contents ?? {}).flat();
const conceptsLearned = allFacts
  .filter((f: any) => f.fact_type === &#x22;semantic&#x22;)
  .map((f: any) => f.atomic_text);
const engagedTopics = (interests ?? []).map((i: any) => i.topic);
const confidenceLevel = mood?.valence ?? 0;

const exercises = await generateExercises({ topic, conceptsLearned, engagedTopics });

await sendStudentReport(studentId, {
  summary: \`Covered: \${conceptsLearned.slice(0, 3).join(&#x22;, &#x22;)}\`,
  exercises,
  encouragement: confidenceLevel > 0.2 ? &#x22;Great session today!&#x22; : &#x22;Keep going — this takes practice.&#x22;,
});

return { conceptsLearned, exercises };
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def before_tutoring_session(agent_id: str, student_id: str, topic: str) -> dict:
  ctx = sonzai.agents.get_context(
      agent_id,
      user_id=student_id,
      query=f&#x22;{topic} concepts learned struggles difficulty level&#x22;,
  )

  known_concepts = [
      f[&#x22;atomic_text&#x22;] for f in (ctx.get(&#x22;loaded_facts&#x22;) or [])
      if f.get(&#x22;fact_type&#x22;) == &#x22;semantic&#x22;
  ]
  weak_areas = [
      h[&#x22;label&#x22;] for h in (ctx.get(&#x22;habits&#x22;) or [])
      if &#x22;struggle&#x22; in (h.get(&#x22;label&#x22;) or &#x22;&#x22;).lower()
  ]
  return {&#x22;known_concepts&#x22;: known_concepts, &#x22;weak_areas&#x22;: weak_areas}

def after_tutoring_session(agent_id: str, student_id: str, topic: str, transcript: list[dict]) -> dict:
  sonzai.agents.process(agent_id, user_id=student_id, messages=transcript)

  memory = sonzai.agents.memory.list(agent_id, user_id=student_id)
  interests = sonzai.agents.get_interests(agent_id, user_id=student_id)
  mood = sonzai.agents.get_mood(agent_id, user_id=student_id)

  # memory.list returns { nodes, contents } — contents is node_id → facts[].
  all_facts = [f for facts in (memory.contents or {}).values() for f in facts]
  concepts_learned = [f.get(&#x22;atomic_text&#x22;) for f in all_facts if f.get(&#x22;fact_type&#x22;) == &#x22;semantic&#x22;]
  engaged_topics = [i.get(&#x22;topic&#x22;) for i in (interests or [])]
  confidence = (mood.valence if mood else 0) or 0

  exercises = generate_exercises(topic=topic, concepts=concepts_learned, topics=engaged_topics)

  send_student_report(student_id, {
      &#x22;summary&#x22;: f&#x22;Covered: {', '.join(concepts_learned[:3])}&#x22;,
      &#x22;exercises&#x22;: exercises,
      &#x22;encouragement&#x22;: &#x22;Great session today!&#x22; if confidence > 0.2 else &#x22;Keep going — this takes practice.&#x22;,
  })
  return {&#x22;concepts_learned&#x22;: concepts_learned, &#x22;exercises&#x22;: exercises}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `func beforeTutoringSession(ctx context.Context, client *sonzai.Client, agentID, studentID, topic string) ([]string, []string, error) {
  ctxData, err := client.Agents.GetContext(ctx, agentID, sonzai.GetContextOptions{
      UserID: studentID,
      Query:  topic + &#x22; concepts learned struggles difficulty level&#x22;,
  })
  if err != nil {
      return nil, nil, err
  }

  var knownConcepts, weakAreas []string
  if facts, ok := ctxData[&#x22;loaded_facts&#x22;].([]any); ok {
      for _, f := range facts {
          if fm, ok := f.(map[string]any); ok && fm[&#x22;fact_type&#x22;] == &#x22;semantic&#x22; {
              knownConcepts = append(knownConcepts, fmt.Sprint(fm[&#x22;atomic_text&#x22;]))
          }
      }
  }
  if habits, ok := ctxData[&#x22;habits&#x22;].([]any); ok {
      for _, h := range habits {
          if hm, ok := h.(map[string]any); ok {
              if label := fmt.Sprint(hm[&#x22;label&#x22;]); strings.Contains(strings.ToLower(label), &#x22;struggle&#x22;) {
                  weakAreas = append(weakAreas, label)
              }
          }
      }
  }
  return knownConcepts, weakAreas, nil
}

func afterTutoringSession(ctx context.Context, client *sonzai.Client, agentID, studentID, topic string, transcript []sonzai.ChatMessage) error {
  _, err := client.Agents.Process(ctx, agentID, sonzai.ProcessOptions{
      UserID:   studentID,
      Messages: transcript,
  })
  if err != nil {
      return err
  }

  memory, err := client.Agents.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{UserID: studentID})
  interests, _ := client.Agents.GetInterests(ctx, agentID, studentID, &#x22;&#x22;)
  mood, _ := client.Agents.GetMood(ctx, agentID, studentID, &#x22;&#x22;)
  _ = memory; _ = interests; _ = mood

  // build exercises and send report from extracted data...
  return nil
}`,
  },
]"
/>

## Use case: gym / fitness app [#use-case-gym--fitness-app]

Pull the user's fitness context before the workout for a personalized greeting. After the workout, send the session log to Sonzai to track habits, mood, and progress — without Sonzai ever being in the real-time exercise loop.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function beforeWorkout(agentId: string, userId: string): Promise<string> {
const ctx = await sonzai.agents.getContext(agentId, {
  userId,
  query: &#x22;fitness goals workout habits recent exercise progress&#x22;,
});

const goals = (ctx.active_goals ?? []).map((g: any) => g.description);
const recentHabits = (ctx.habits ?? []).map((h: any) => h.label);

const greeting = await yourLLM.chat({
  system: &#x22;Generate a short, energetic workout motivation message (2 sentences max).&#x22;,
  message: \`User goals: \${goals.join(&#x22;, &#x22;)}. Recent habits: \${recentHabits.join(&#x22;, &#x22;)}.\`,
});

await playVoiceMessage(userId, greeting);
return greeting;
}

async function afterWorkout(
agentId: string,
userId: string,
workoutTranscript: { role: &#x22;user&#x22; | &#x22;assistant&#x22;; content: string }[]
) {
await sonzai.agents.process(agentId, { userId, messages: workoutTranscript });

const [memory, habits, mood] = await Promise.all([
  sonzai.agents.memory.list(agentId, { userId }),
  sonzai.agents.listHabits(agentId, { userId }),
  sonzai.agents.getMood(agentId, { userId }),
]);

const habitsReinforced = habits ?? [];
const allFacts = Object.values(memory.contents ?? {}).flat();
const personalRecords = allFacts.filter((f: any) =>
  /record|pb|best|personal/i.test(f.atomic_text ?? &#x22;&#x22;)
);

await sendPushNotification(userId, {
  title: &#x22;Workout complete&#x22;,
  body: personalRecords.length > 0
    ? \`New record: \${personalRecords[0].atomic_text}\`
    : \`Great session — \${habitsReinforced[0]?.label ?? &#x22;keep it up&#x22;}!\`,
});
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def before_workout(agent_id: str, user_id: str) -> str:
  ctx = sonzai.agents.get_context(
      agent_id,
      user_id=user_id,
      query=&#x22;fitness goals workout habits recent exercise progress&#x22;,
  )

  goals = [g.get(&#x22;description&#x22;, &#x22;&#x22;) for g in (ctx.get(&#x22;active_goals&#x22;) or [])]
  recent_habits = [h.get(&#x22;label&#x22;, &#x22;&#x22;) for h in (ctx.get(&#x22;habits&#x22;) or [])]

  greeting = your_llm.chat(
      system=&#x22;Generate a short, energetic workout motivation message (2 sentences max).&#x22;,
      message=f&#x22;User goals: {', '.join(goals)}. Recent habits: {', '.join(recent_habits)}.&#x22;,
  )
  play_voice_message(user_id, greeting)
  return greeting

def after_workout(agent_id: str, user_id: str, workout_transcript: list[dict]) -> None:
  sonzai.agents.process(agent_id, user_id=user_id, messages=workout_transcript)

  memory = sonzai.agents.memory.list(agent_id, user_id=user_id)
  habits = sonzai.agents.list_habits(agent_id, user_id=user_id)
  mood = sonzai.agents.get_mood(agent_id, user_id=user_id)

  habits_reinforced = habits or []
  all_facts = [f for facts in (memory.contents or {}).values() for f in facts]
  import re
  personal_records = [f for f in all_facts if re.search(r&#x22;record|pb|best|personal&#x22;, f.get(&#x22;atomic_text&#x22;, &#x22;&#x22;), re.IGNORECASE)]

  body = (
      f&#x22;New record: {personal_records[0]['atomic_text']}&#x22; if personal_records
      else f&#x22;Great session — {habits_reinforced[0].get('label', 'keep it up') if habits_reinforced else 'keep it up'}!&#x22;
  )
  send_push_notification(user_id, title=&#x22;Workout complete&#x22;, body=body)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;regexp&#x22;
  &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

var prRE = regexp.MustCompile(\`(?i)record|pb|best|personal\`)

func beforeWorkout(ctx context.Context, client *sonzai.Client, agentID, userID string) (string, error) {
  ctxData, err := client.Agents.GetContext(ctx, agentID, sonzai.GetContextOptions{
      UserID: userID,
      Query:  &#x22;fitness goals workout habits recent exercise progress&#x22;,
  })
  if err != nil {
      return &#x22;&#x22;, err
  }

  var goals, recentHabits []string
  for _, g := range toSlice(ctxData[&#x22;active_goals&#x22;]) {
      goals = append(goals, fmt.Sprint(toMap(g)[&#x22;description&#x22;]))
  }
  for _, h := range toSlice(ctxData[&#x22;habits&#x22;]) {
      recentHabits = append(recentHabits, fmt.Sprint(toMap(h)[&#x22;label&#x22;]))
  }

  greeting, err := yourLLM.Chat(ctx,
      &#x22;Generate a short, energetic workout motivation message (2 sentences max).&#x22;,
      fmt.Sprintf(&#x22;User goals: %v. Recent habits: %v.&#x22;, goals, recentHabits))
  if err != nil {
      return &#x22;&#x22;, err
  }
  playVoiceMessage(userID, greeting)
  return greeting, nil
}

func afterWorkout(ctx context.Context, client *sonzai.Client, agentID, userID string, transcript []sonzai.ChatMessage) error {
  _, err := client.Agents.Process(ctx, agentID, sonzai.ProcessOptions{UserID: userID, Messages: transcript})
  if err != nil {
      return err
  }

  memory, _ := client.Agents.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{UserID: userID})
  habits, _ := client.Agents.ListHabits(ctx, agentID, userID, &#x22;&#x22;)
  _ = memory; _ = habits
  // build push notification from extracted data...
  return nil
}`,
  },
]"
/>

## Use case: sales CRM intelligence [#use-case-sales-crm-intelligence]

Your sales team runs calls through their existing tooling (Gong, Zoom, your own recorder). After each call, send the transcript to Sonzai to build a persistent customer profile.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function processSalesCall(
agentId: string,
customerId: string,
callId: string,
callTranscript: { role: &#x22;user&#x22; | &#x22;assistant&#x22;; content: string }[],
durationSeconds: number
) {
// Use the explicit lifecycle so we can pass durationSeconds.
const session = await sonzai.agents.sessions.start(agentId, {
  userId: customerId,
  sessionId: \`call-\${callId}\`,
});

const result = await session.end({
  messages: callTranscript,
  totalMessages: callTranscript.length,
  durationSeconds,
});

// Read extractions back from the analytics endpoints.
const personality = await sonzai.agents.personality.get(agentId);

// ...build CRM update from result + dedicated read endpoints
return result;
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def process_sales_call(
  agent_id: str,
  customer_id: str,
  call_id: str,
  call_transcript: list[dict],
  duration_seconds: int,
) -> object:
  # Use the explicit lifecycle so we can pass duration_seconds.
  session = sonzai.agents.sessions.start(
      agent_id,
      user_id=customer_id,
      session_id=f&#x22;call-{call_id}&#x22;,
  )

  result = session.end(
      messages=call_transcript,
      total_messages=len(call_transcript),
      duration_seconds=duration_seconds,
  )

  # Read extractions back from the analytics endpoints.
  personality = sonzai.agents.personality.get(agent_id)
  _ = personality  # build CRM update from result + dedicated read endpoints
  return result`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func processSalesCall(
  ctx context.Context,
  client *sonzai.Client,
  agentID, customerID, callID string,
  callTranscript []sonzai.ChatMessage,
  durationSeconds int,
) error {
  // Use the explicit lifecycle so we can pass DurationSeconds.
  session, err := client.Agents.Sessions.Start(ctx, agentID, sonzai.SessionStartOptions{
      UserID:    customerID,
      SessionID: fmt.Sprintf(&#x22;call-%s&#x22;, callID),
  })
  if err != nil {
      return err
  }

  err = session.End(ctx, sonzai.SessionEndOptions{
      Messages:        callTranscript,
      TotalMessages:   len(callTranscript),
      DurationSeconds: durationSeconds,
  })
  if err != nil {
      return err
  }

  // Read extractions back from the analytics endpoints.
  _, err = client.Agents.Personality.Get(ctx, agentID, nil)
  // ...build CRM update from result + dedicated read endpoints
  return err
}`,
  },
]"
/>

## Use case: language learning app [#use-case-language-learning-app]

Track vocabulary mastered, grammar struggles, pronunciation patterns, and learning pace across lessons.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function afterLanguageLesson(
agentId: string,
studentId: string,
targetLanguage: string,
lessonTranscript: { role: &#x22;user&#x22; | &#x22;assistant&#x22;; content: string }[]
) {
await sonzai.agents.process(agentId, { userId: studentId, messages: lessonTranscript });

const [memory, interests, mood] = await Promise.all([
  sonzai.agents.memory.list(agentId, { userId: studentId }),
  sonzai.agents.getInterests(agentId, { userId: studentId }),
  sonzai.agents.getMood(agentId, { userId: studentId }),
]);

const allFacts = Object.values(memory.contents ?? {}).flat();
const newVocab = allFacts
  .filter((f: any) => f.fact_type === &#x22;semantic&#x22;)
  .map((f: any) => f.atomic_text);
const engagementAreas = interests ?? [];
const confidenceDelta = mood?.valence ?? 0;

await updateLearningDashboard(studentId, {
  language: targetLanguage,
  vocabularyAdded: newVocab.length,
  newWords: newVocab,
  strongestArea: engagementAreas[0]?.topic ?? &#x22;conversation&#x22;,
  confidenceTrend: confidenceDelta > 0.1 ? &#x22;↑&#x22; : confidenceDelta < -0.1 ? &#x22;↓&#x22; : &#x22;→&#x22;,
});

return { newVocab, engagementAreas };
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def after_language_lesson(
  agent_id: str, student_id: str, target_language: str, lesson_transcript: list[dict]
) -> dict:
  sonzai.agents.process(agent_id, user_id=student_id, messages=lesson_transcript)

  memory = sonzai.agents.memory.list(agent_id, user_id=student_id)
  interests = sonzai.agents.get_interests(agent_id, user_id=student_id)
  mood = sonzai.agents.get_mood(agent_id, user_id=student_id)

  all_facts = [f for facts in (memory.contents or {}).values() for f in facts]
  new_vocab = [f.get(&#x22;atomic_text&#x22;) for f in all_facts if f.get(&#x22;fact_type&#x22;) == &#x22;semantic&#x22;]
  engagement_areas = interests or []
  confidence_delta = (mood.valence if mood else 0) or 0

  trend = &#x22;↑&#x22; if confidence_delta > 0.1 else (&#x22;↓&#x22; if confidence_delta < -0.1 else &#x22;→&#x22;)
  update_learning_dashboard(student_id, {
      &#x22;language&#x22;: target_language,
      &#x22;vocabulary_added&#x22;: len(new_vocab),
      &#x22;new_words&#x22;: new_vocab,
      &#x22;strongest_area&#x22;: engagement_areas[0].get(&#x22;topic&#x22;, &#x22;conversation&#x22;) if engagement_areas else &#x22;conversation&#x22;,
      &#x22;confidence_trend&#x22;: trend,
  })
  return {&#x22;new_vocab&#x22;: new_vocab, &#x22;engagement_areas&#x22;: engagement_areas}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `func afterLanguageLesson(ctx context.Context, client *sonzai.Client, agentID, studentID, targetLanguage string, transcript []sonzai.ChatMessage) error {
  _, err := client.Agents.Process(ctx, agentID, sonzai.ProcessOptions{UserID: studentID, Messages: transcript})
  if err != nil {
      return err
  }

  memory, _ := client.Agents.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{UserID: studentID})
  interests, _ := client.Agents.GetInterests(ctx, agentID, studentID, &#x22;&#x22;)
  mood, _ := client.Agents.GetMood(ctx, agentID, studentID, &#x22;&#x22;)

  // Flatten memory contents map into a slice of facts.
  var allFacts []map[string]any
  for _, facts := range memory.Contents {
      for _, f := range facts {
          if fm, ok := f.(map[string]any); ok {
              allFacts = append(allFacts, fm)
          }
      }
  }
  var newVocab []string
  for _, f := range allFacts {
      if f[&#x22;fact_type&#x22;] == &#x22;semantic&#x22; {
          newVocab = append(newVocab, fmt.Sprint(f[&#x22;atomic_text&#x22;]))
      }
  }

  var confidenceDelta float64
  if mood != nil {
      confidenceDelta = mood.Valence
  }
  trend := &#x22;→&#x22;
  if confidenceDelta > 0.1 { trend = &#x22;↑&#x22; } else if confidenceDelta < -0.1 { trend = &#x22;↓&#x22; }

  updateLearningDashboard(studentID, targetLanguage, len(newVocab), newVocab, trend)
  _ = interests
  return nil
}`,
  },
]"
/>

## Use case: mental health & wellness journaling [#use-case-mental-health--wellness-journaling]

Your app handles the journaling conversation. After each session, send to Sonzai to track mood trends, detect emotional breakthroughs, and surface proactive insights.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

async function afterJournalingSession(
agentId: string,
userId: string,
journalTranscript: { role: &#x22;user&#x22; | &#x22;assistant&#x22;; content: string }[]
) {
await sonzai.agents.process(agentId, { userId, messages: journalTranscript });

// After /process, extracted state is available on the read endpoints.
// Proactive outreach (check-ins, reminders) is exposed via the
// notifications resource — not on the /process response.
const [mood, notifications] = await Promise.all([
  sonzai.agents.getMood(agentId, { userId }),
  sonzai.agents.notifications.list(agentId),
]);

if ((mood?.valence ?? 0) < -0.4) {
  await sendWellnessAlert(userId, {
    message: &#x22;It sounds like you're going through a tough time. We're here for you.&#x22;,
  });
}

for (const notif of notifications) {
  if (notif.user_id === userId) {
    await scheduleReminder(userId, notif.generated_message, notif.scheduled_for);
  }
}

await updateMoodDashboard(userId, { valence: mood?.valence, energy: mood?.arousal });
}`,
  },
  {
    id: &#x22;python&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai

sonzai = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

def after_journaling_session(agent_id: str, user_id: str, journal_transcript: list[dict]) -> None:
  sonzai.agents.process(agent_id, user_id=user_id, messages=journal_transcript)

  # After /process, extracted state is available on the read endpoints.
  mood = sonzai.agents.get_mood(agent_id, user_id=user_id)
  notifications = sonzai.agents.notifications.list(agent_id)

  valence = (mood.valence if mood else 0) or 0
  if valence < -0.4:
      send_wellness_alert(user_id, &#x22;It sounds like you're going through a tough time. We're here for you.&#x22;)

  for notif in notifications:
      if notif.user_id == user_id:
          schedule_reminder(user_id, notif.generated_message, notif.scheduled_for)

  update_mood_dashboard(user_id, valence=valence, energy=(mood.arousal if mood else 0) or 0)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `func afterJournalingSession(ctx context.Context, client *sonzai.Client, agentID, userID string, transcript []sonzai.ChatMessage) error {
  _, err := client.Agents.Process(ctx, agentID, sonzai.ProcessOptions{UserID: userID, Messages: transcript})
  if err != nil {
      return err
  }

  // After /process, extracted state is available on the read endpoints.
  mood, _ := client.Agents.GetMood(ctx, agentID, userID, &#x22;&#x22;)
  notifications, err := client.Agents.Notifications.List(ctx, agentID)
  if err != nil {
      return err
  }

  if mood != nil && mood.Valence < -0.4 {
      sendWellnessAlert(userID, &#x22;It sounds like you're going through a tough time. We're here for you.&#x22;)
  }

  for _, notif := range notifications {
      if notif.UserID == userID {
          scheduleReminder(userID, notif.GeneratedMessage, notif.ScheduledFor)
      }
  }

  if mood != nil {
      updateMoodDashboard(userID, mood.Valence, mood.Arousal)
  }
  return nil
}`,
  },
]"
/>

## Next [#next]

* [Pattern 1: Memory Middleware (real-time)](/docs/en/guides/standalone-memory/pattern-1-realtime) — when you want Sonzai-enriched context per-turn (and tool calling / multimodal handling)
* [Endpoint walkthrough](/docs/en/guides/standalone-memory/endpoints) — full reference for `sessions.start`, `context`, `turn`, `process`, `end`, and read endpoints
* [KB & limitations](/docs/en/guides/standalone-memory/limitations) — knowledge base behavior in standalone mode


---

# Custom States & Workflow Events

Source: https://sonz.ai/docs/en/guides/tutorials/tutorial-custom-states

> Custom states let you store arbitrary structured data alongside an agent's memory — think performance metrics, task completion, milestone flags, or any application-specific context. Workflow events let the agent react to things that happen outside the conversation (milestone reached, task completed, goal achieved). By the end you'll know how to read, write, and listen for both.



### What you'll build [#what-youll-build]

* A custom state that tracks a user's progress score and tier, updated after every session
* A workflow event trigger that fires when the user hits a milestone, causing the agent to react
* A bulk-read of all custom states for a user's dashboard
* An upsert pattern for idempotent state updates from your backend

## What Are Custom States? [#what-are-custom-states]

A custom state is a key-value record scoped to an **agent + user** (or just an agent). Values can be any JSON-serializable type: strings, numbers, booleans, arrays, or nested objects.

Unlike memory (which is unstructured text extracted from conversations), custom states are structured data you write explicitly from your backend. The agent can read them via the `get_custom_state` tool during conversation, so it always knows the user's current tier, streak, balance, etc.

**Custom States (you write)**

* Structured JSON data
* Your backend controls it
* Task progress, scores, milestones
* Updated via SDK or REST

**Memory (auto-extracted)**

* Free-form text facts
* Platform extracts it from chat
* Preferences, events, goals
* Auto-updated after each message

## 1. Create a Custom State [#1-create-a-custom-state]

Call `create` the first time you set a state for a user. Subsequent writes should use `upsert` (see Step 3) for idempotent updates.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;
const USER_ID  = &#x22;user_123&#x22;;

const state = await client.agents.customStates.create(AGENT_ID, {
userId: USER_ID,
key:    &#x22;user_progress&#x22;,
value: {
  tier:            &#x22;silver&#x22;,
  score:           2340,
  score_to_next:   3000,
  streak_days:     12,
  milestones:      [&#x22;first_chat&#x22;, &#x22;50_tasks&#x22;, &#x22;7_day_streak&#x22;],
},
});

console.log(&#x22;Created:&#x22;, state.state_id, state.key);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;
USER_ID  = &#x22;user_123&#x22;

state = client.agents.custom_states.create(AGENT_ID, {
  &#x22;user_id&#x22;: USER_ID,
  &#x22;key&#x22;:     &#x22;user_progress&#x22;,
  &#x22;value&#x22;: {
      &#x22;tier&#x22;:            &#x22;silver&#x22;,
      &#x22;score&#x22;:           2340,
      &#x22;score_to_next&#x22;:   3000,
      &#x22;streak_days&#x22;:     12,
      &#x22;milestones&#x22;:      [&#x22;first_chat&#x22;, &#x22;50_tasks&#x22;, &#x22;7_day_streak&#x22;],
  },
})

print(f&#x22;Created: {state.state_id} / {state.key}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const (
  agentID = &#x22;agent_abc&#x22;
  userID  = &#x22;user_123&#x22;
)

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()

  state, err := client.Agents.CustomState.Create(ctx, agentID, sonzai.CustomStateCreateOptions{
      UserID: userID,
      Key:    &#x22;user_progress&#x22;,
      Value: map[string]interface{}{
          &#x22;tier&#x22;:            &#x22;silver&#x22;,
          &#x22;score&#x22;:           2340,
          &#x22;score_to_next&#x22;:   3000,
          &#x22;streak_days&#x22;:     12,
          &#x22;milestones&#x22;:      []string{&#x22;first_chat&#x22;, &#x22;50_tasks&#x22;, &#x22;7_day_streak&#x22;},
      },
  })
  if err != nil { panic(err) }
  fmt.Printf(&#x22;Created: %s / %s\\n&#x22;, state.StateID, state.Key)
}`,
  },
]"
/>

## 2. Read State Back During Chat [#2-read-state-back-during-chat]

When the agent has access to the `get_custom_state` tool (enabled automatically when custom states exist), it fetches current state at the start of a conversation. You can also read it from your backend at any time.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Read by key from your backend
const state = await client.agents.customStates.getByKey(AGENT_ID, {
userId: USER_ID,
key: &#x22;user_progress&#x22;,
});

const progress = state.value as {
tier: string; score: number; score_to_next: number; streak_days: number;
};

console.log(\`\${progress.tier} tier · \${progress.score}/\${progress.score_to_next} pts · \${progress.streak_days}-day streak\`);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `state = client.agents.custom_states.get_by_key(AGENT_ID, {
  &#x22;user_id&#x22;: USER_ID,
  &#x22;key&#x22;: &#x22;user_progress&#x22;,
})

p = state.value
print(f&#x22;{p['tier']} tier · {p['score']}/{p['score_to_next']} pts · {p['streak_days']}-day streak&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `state, err := client.Agents.CustomState.GetByKey(ctx, agentID, sonzai.CustomStateGetByKeyOptions{
  UserID: userID,
  Key:    &#x22;user_progress&#x22;,
})
if err != nil { panic(err) }

val := state.Value.(map[string]interface{})
fmt.Printf(&#x22;%s tier · %.0f/%.0f pts · %.0f-day streak\\n&#x22;,
  val[&#x22;tier&#x22;], val[&#x22;score&#x22;], val[&#x22;score_to_next&#x22;], val[&#x22;streak_days&#x22;],
)`,
  },
]"
/>

During conversation, the agent calls `get_custom_state("user_progress")` and incorporates the progress data into its responses naturally — no prompt injection required.

## 3. Upsert State Idempotently [#3-upsert-state-idempotently]

Use `upsert` from your backend whenever the user's state changes — after a session ends, after a purchase, or on a schedule. `upsert` creates the state if it doesn't exist, or replaces it if it does.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Called after each work session ends
async function onSessionEnd(userId: string, sessionScore: number) {
const current = await client.agents.customStates.getByKey(AGENT_ID, {
  userId,
  key: &#x22;user_progress&#x22;,
}).catch(() => null);

const tiers = [&#x22;bronze&#x22;, &#x22;silver&#x22;, &#x22;gold&#x22;, &#x22;platinum&#x22;];
const prev = (current?.value ?? { tier: &#x22;bronze&#x22;, score: 0, score_to_next: 1000, streak_days: 0 }) as {
  tier: string; score: number; score_to_next: number; streak_days: number; milestones: string[];
};

const newScore    = prev.score + sessionScore;
const promoted    = newScore >= prev.score_to_next;
const tierIndex   = tiers.indexOf(prev.tier);
const newTier     = promoted ? (tiers[tierIndex + 1] ?? prev.tier) : prev.tier;

await client.agents.customStates.upsert(AGENT_ID, {
  userId,
  key: &#x22;user_progress&#x22;,
  value: {
    tier:          newTier,
    score:         promoted ? newScore - prev.score_to_next : newScore,
    score_to_next: promoted ? prev.score_to_next * 1.5 : prev.score_to_next,
    streak_days:   prev.streak_days + 1,
    milestones:    prev.milestones,
  },
});

if (promoted) {
  // Notify the agent so it can congratulate the user next session
  await client.agents.triggerBackendEvent(AGENT_ID, {
    userId,
    eventType: &#x22;tier_promotion&#x22;,
    eventDescription: \`User promoted from \${prev.tier} to \${newTier}\`,
    metadata: { new_tier: newTier, previous_tier: prev.tier },
  });
}
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `def on_session_end(user_id: str, session_score: int):
  tiers = [&#x22;bronze&#x22;, &#x22;silver&#x22;, &#x22;gold&#x22;, &#x22;platinum&#x22;]
  try:
      current = client.agents.custom_states.get_by_key(AGENT_ID, {
          &#x22;user_id&#x22;: user_id,
          &#x22;key&#x22;: &#x22;user_progress&#x22;,
      })
      prev = current.value
  except Exception:
      prev = {&#x22;tier&#x22;: &#x22;bronze&#x22;, &#x22;score&#x22;: 0, &#x22;score_to_next&#x22;: 1000, &#x22;streak_days&#x22;: 0, &#x22;milestones&#x22;: []}

  new_score  = prev[&#x22;score&#x22;] + session_score
  promoted   = new_score >= prev[&#x22;score_to_next&#x22;]
  tier_index = tiers.index(prev[&#x22;tier&#x22;])
  new_tier   = tiers[tier_index + 1] if promoted and tier_index + 1 < len(tiers) else prev[&#x22;tier&#x22;]

  client.agents.custom_states.upsert(AGENT_ID, {
      &#x22;user_id&#x22;: user_id,
      &#x22;key&#x22;: &#x22;user_progress&#x22;,
      &#x22;value&#x22;: {
          &#x22;tier&#x22;:          new_tier,
          &#x22;score&#x22;:         new_score - prev[&#x22;score_to_next&#x22;] if promoted else new_score,
          &#x22;score_to_next&#x22;: prev[&#x22;score_to_next&#x22;] * 1.5 if promoted else prev[&#x22;score_to_next&#x22;],
          &#x22;streak_days&#x22;:   prev[&#x22;streak_days&#x22;] + 1,
          &#x22;milestones&#x22;:    prev[&#x22;milestones&#x22;],
      },
  })

  if promoted:
      # Notify the agent so it can congratulate the user
      client.agents.trigger_backend_event(
          AGENT_ID,
          user_id=user_id,
          event_type=&#x22;tier_promotion&#x22;,
          event_description=f&#x22;User promoted from {prev['tier']} to {new_tier}&#x22;,
          metadata={&#x22;new_tier&#x22;: new_tier, &#x22;previous_tier&#x22;: prev[&#x22;tier&#x22;]},
      )`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `func onSessionEnd(ctx context.Context, client *sonzai.Client, userID string, sessionScore int) error {
  prev := map[string]interface{}{
      &#x22;tier&#x22;: &#x22;bronze&#x22;, &#x22;score&#x22;: 0, &#x22;score_to_next&#x22;: 1000.0, &#x22;streak_days&#x22;: 0,
  }

  if current, err := client.Agents.CustomState.GetByKey(ctx, agentID, sonzai.CustomStateGetByKeyOptions{
      UserID: userID, Key: &#x22;user_progress&#x22;,
  }); err == nil {
      prev = current.Value.(map[string]interface{})
  }

  currentScore := int(prev[&#x22;score&#x22;].(float64)) + sessionScore
  scoreToNext  := prev[&#x22;score_to_next&#x22;].(float64)
  tier         := prev[&#x22;tier&#x22;].(string)
  promoted     := float64(currentScore) >= scoreToNext

  tiers := []string{&#x22;bronze&#x22;, &#x22;silver&#x22;, &#x22;gold&#x22;, &#x22;platinum&#x22;}
  if promoted {
      for i, t := range tiers {
          if t == tier && i+1 < len(tiers) { tier = tiers[i+1]; break }
      }
  }

  _, err := client.Agents.CustomState.Upsert(ctx, agentID, sonzai.CustomStateUpsertOptions{
      UserID: userID,
      Key:    &#x22;user_progress&#x22;,
      Value: map[string]interface{}{
          &#x22;tier&#x22;:          tier,
          &#x22;score&#x22;:         currentScore,
          &#x22;score_to_next&#x22;: scoreToNext * 1.5,
          &#x22;streak_days&#x22;:   int(prev[&#x22;streak_days&#x22;].(float64)) + 1,
      },
  })
  if err != nil { return err }

  if promoted {
      _, err = client.Agents.TriggerEvent(ctx, agentID, sonzai.TriggerEventOptions{
          UserID:           userID,
          EventType:        &#x22;tier_promotion&#x22;,
          EventDescription: fmt.Sprintf(&#x22;User promoted from %s to %s&#x22;, prev[&#x22;tier&#x22;], tier),
          Metadata:         map[string]string{&#x22;new_tier&#x22;: tier, &#x22;previous_tier&#x22;: fmt.Sprint(prev[&#x22;tier&#x22;])},
      })
  }
  return err
}`,
  },
]"
/>

## 4. Trigger a Workflow Event [#4-trigger-a-workflow-event]

Workflow events let your backend tell the agent about something that happened outside the conversation. The next time the user chats, the agent sees the pending event and reacts naturally.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Trigger from your backend when something notable happens
await client.agents.triggerBackendEvent(AGENT_ID, {
userId: USER_ID,
eventType: &#x22;task_complete&#x22;,
eventDescription: &#x22;Q1 Revenue Analysis completed — deliverable: Revenue Report, category: Analytics, time: 3h 42m&#x22;,
metadata: {
  task_name:   &#x22;Q1 Revenue Analysis&#x22;,
  deliverable: &#x22;Revenue Report&#x22;,
  category:    &#x22;Analytics&#x22;,
  time_taken:  &#x22;3h 42m&#x22;,
},
});

// Next time the user opens a conversation:
// Agent: &#x22;I see you finished the Q1 Revenue Analysis! That report is a key
//         deliverable. Want to discuss the findings or start the next task?&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Trigger from your backend when something notable happens
client.agents.trigger_backend_event(
  AGENT_ID,
  user_id=USER_ID,
  event_type=&#x22;task_complete&#x22;,
  event_description=&#x22;Q1 Revenue Analysis completed — deliverable: Revenue Report, category: Analytics, time: 3h 42m&#x22;,
  metadata={
      &#x22;task_name&#x22;:   &#x22;Q1 Revenue Analysis&#x22;,
      &#x22;deliverable&#x22;: &#x22;Revenue Report&#x22;,
      &#x22;category&#x22;:    &#x22;Analytics&#x22;,
      &#x22;time_taken&#x22;:  &#x22;3h 42m&#x22;,
  },
)

# Next time the user opens a conversation, the agent sees the pending event
# and proactively brings it up.`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Agents.TriggerEvent(ctx, agentID, sonzai.TriggerEventOptions{
  UserID:           userID,
  EventType:        &#x22;task_complete&#x22;,
  EventDescription: &#x22;Q1 Revenue Analysis completed — deliverable: Revenue Report, category: Analytics, time: 3h 42m&#x22;,
  Metadata: map[string]string{
      &#x22;task_name&#x22;:   &#x22;Q1 Revenue Analysis&#x22;,
      &#x22;deliverable&#x22;: &#x22;Revenue Report&#x22;,
      &#x22;category&#x22;:    &#x22;Analytics&#x22;,
      &#x22;time_taken&#x22;:  &#x22;3h 42m&#x22;,
  },
})
if err != nil { panic(err) }

// Next conversation, the agent sees the pending event and proactively
// congratulates the user on completing the task.`,
  },
]"
/>

<Callout type="warn" title="Event delivery">
  Workflow events are queued and delivered on the next conversation turn. They don't interrupt an active session. The agent consumes pending events at the start of the next `chat` or `chatStream` call and incorporates them into its opening message or first response.
</Callout>

## 5. List All States for a User [#5-list-all-states-for-a-user]

Useful for building admin dashboards, user profile pages, or debugging. Returns all custom states for an agent + user pair.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const { states } = await client.agents.customStates.list(AGENT_ID, {
userId: USER_ID,
});

for (const state of states) {
console.log(\`[\${state.key}]\`, JSON.stringify(state.value, null, 2));
}
// [user_progress]  { tier: &#x22;silver&#x22;, score: 340, ... }
// [preferences]    { theme: &#x22;dark&#x22;, notifications: true }
// [daily_summary]  { last_active: &#x22;2025-03-20&#x22;, sessions_today: 2 }`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `import json

result = client.agents.custom_states.list(AGENT_ID, {&#x22;user_id&#x22;: USER_ID})

for state in result.states:
  print(f&#x22;[{state.key}]&#x22;, json.dumps(state.value, indent=2))
# [user_progress]  {&#x22;tier&#x22;: &#x22;silver&#x22;, &#x22;score&#x22;: 340, ...}
# [preferences]    {&#x22;theme&#x22;: &#x22;dark&#x22;, &#x22;notifications&#x22;: True}
# [daily_summary]  {&#x22;last_active&#x22;: &#x22;2025-03-20&#x22;, &#x22;sessions_today&#x22;: 2}`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `import &#x22;encoding/json&#x22;

result, err := client.Agents.CustomState.List(ctx, agentID, sonzai.CustomStateListOptions{
  UserID: userID,
})
if err != nil { panic(err) }

for _, state := range result.States {
  b, _ := json.MarshalIndent(state.Value, &#x22;&#x22;, &#x22;  &#x22;)
  fmt.Printf(&#x22;[%s]\\n%s\\n&#x22;, state.Key, string(b))
}
// [user_progress]  {&#x22;tier&#x22;: &#x22;silver&#x22;, &#x22;score&#x22;: 340, ...}
// [preferences]    {&#x22;theme&#x22;: &#x22;dark&#x22;}`,
  },
]"
/>

## 6. Update a Specific Field [#6-update-a-specific-field]

Use `update` when you want to change a state by its `state_id`. Unlike `upsert`, `update` does a partial merge — you only need to pass the fields you want to change.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Add a milestone without overwriting the whole state
const state = await client.agents.customStates.getByKey(AGENT_ID, {
userId: USER_ID,
key: &#x22;user_progress&#x22;,
});

const progress = state.value as { milestones: string[]; [k: string]: unknown };

await client.agents.customStates.update(AGENT_ID, state.state_id, {
value: {
  ...progress,
  milestones: [...progress.milestones, &#x22;100_tasks&#x22;],
},
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `state = client.agents.custom_states.get_by_key(AGENT_ID, {
  &#x22;user_id&#x22;: USER_ID,
  &#x22;key&#x22;: &#x22;user_progress&#x22;,
})

updated_milestones = state.value[&#x22;milestones&#x22;] + [&#x22;100_tasks&#x22;]

client.agents.custom_states.update(AGENT_ID, state.state_id, {
  &#x22;value&#x22;: {**state.value, &#x22;milestones&#x22;: updated_milestones},
})`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `state, err := client.Agents.CustomState.GetByKey(ctx, agentID, sonzai.CustomStateGetByKeyOptions{
  UserID: userID, Key: &#x22;user_progress&#x22;,
})
if err != nil { panic(err) }

val := state.Value.(map[string]interface{})
milestones := val[&#x22;milestones&#x22;].([]interface{})
val[&#x22;milestones&#x22;] = append(milestones, &#x22;100_tasks&#x22;)

_, err = client.Agents.CustomState.Update(ctx, agentID, state.StateID, sonzai.CustomStateUpdateOptions{
  Value: val,
})`,
  },
]"
/>

## 7. Delete State [#7-delete-state]

Delete a state by its ID or by key. On next conversation, the agent won't have access to it.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Delete by key (finds and removes the state)
await client.agents.customStates.deleteByKey(AGENT_ID, {
userId: USER_ID,
key: &#x22;user_progress&#x22;,
});

// Or delete by state_id if you already have it
await client.agents.customStates.delete(AGENT_ID, stateId);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Delete by key
client.agents.custom_states.delete_by_key(AGENT_ID, {
  &#x22;user_id&#x22;: USER_ID,
  &#x22;key&#x22;: &#x22;user_progress&#x22;,
})

# Or delete by state_id
client.agents.custom_states.delete(AGENT_ID, state_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Delete by key
err := client.Agents.CustomState.DeleteByKey(ctx, agentID, sonzai.CustomStateDeleteByKeyOptions{
  UserID: userID,
  Key:    &#x22;user_progress&#x22;,
})

// Or delete by state ID
err = client.Agents.CustomState.Delete(ctx, agentID, stateID)`,
  },
]"
/>

## Common Patterns [#common-patterns]

<Callout type="info" title="Onboarding state">
  Create a `onboarding` state on sign-up with `{ step: 0, completed: false }`. The agent checks it at the start of early conversations and guides the user through setup naturally.
</Callout>

<Callout type="info" title="Subscription context">
  Store `{ plan: 'pro', expires_at: '...' }` so the agent knows which features to offer or upsell without you having to pass it in every chat request.
</Callout>

<Callout type="info" title="Daily summary cache">
  Write a `daily_summary` state at the end of each day with key metrics. The agent opens the next-day conversation referencing the user's activity — "Yesterday you completed 3 tasks and hit a 12-day streak. Ready to keep going?"
</Callout>

## Next Steps [#next-steps]

* Read the [Custom Tools](/docs/en/custom-tools) reference for tool definitions and invocation patterns
* Add [Inventory](/docs/en/guides/tutorials/tutorial-inventory) tracking to enrich states with asset portfolios
* Set up webhooks to get notified when the agent triggers specific events back to your backend
* Explore [Personality](/docs/en/personality) to see how events influence the agent's emotional evolution


---

# Resource Inventory + Knowledge Base

Source: https://sonz.ai/docs/en/guides/tutorials/tutorial-inventory

> Track what tools, licenses, and subscriptions each user has and enrich them with live cost data from your Knowledge Base. By the end you'll have an agent that can tell a user their total subscription spend, cost changes, and what alternative solutions to consider — all grounded in real data.



### What you'll build [#what-youll-build]

* A Knowledge Base schema for `software_license` entities with `market_price` and tier info
* A cost-sync pipeline that pushes live pricing data into the KB via `bulkUpdate`
* An agent with `inventory` capability that auto-tracks assigned tools during conversation
* A portfolio query that joins user assignments with current KB pricing data

## 1. Define an Entity Schema [#1-define-an-entity-schema]

Schemas tell the KB what fields to store for each entity type. Create one for `software_license` so the platform knows how to validate and store your license data.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = &#x22;proj_abc123&#x22;;

await client.knowledge.createSchema(PROJECT_ID, {
entity_type: &#x22;software_license&#x22;,
fields: [
  { name: &#x22;market_price&#x22;,  type: &#x22;number&#x22;,  required: false },
  { name: &#x22;tier&#x22;,          type: &#x22;string&#x22;,  required: false },
  { name: &#x22;category&#x22;,      type: &#x22;string&#x22;,  required: false },
  { name: &#x22;license_type&#x22;,  type: &#x22;string&#x22;,  required: false },
  { name: &#x22;trend_30d&#x22;,     type: &#x22;string&#x22;,  required: false },
],
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
PROJECT_ID = &#x22;proj_abc123&#x22;

client.knowledge.create_schema(PROJECT_ID,
  entity_type=&#x22;software_license&#x22;,
  fields=[
      {&#x22;name&#x22;: &#x22;market_price&#x22;, &#x22;type&#x22;: &#x22;number&#x22;, &#x22;required&#x22;: False},
      {&#x22;name&#x22;: &#x22;tier&#x22;,         &#x22;type&#x22;: &#x22;string&#x22;, &#x22;required&#x22;: False},
      {&#x22;name&#x22;: &#x22;category&#x22;,     &#x22;type&#x22;: &#x22;string&#x22;, &#x22;required&#x22;: False},
      {&#x22;name&#x22;: &#x22;license_type&#x22;, &#x22;type&#x22;: &#x22;string&#x22;, &#x22;required&#x22;: False},
      {&#x22;name&#x22;: &#x22;trend_30d&#x22;,    &#x22;type&#x22;: &#x22;string&#x22;, &#x22;required&#x22;: False},
  ],
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const projectID = &#x22;proj_abc123&#x22;

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()

  _, err := client.Knowledge.CreateSchema(ctx, projectID, sonzai.CreateSchemaOptions{
      EntityType: &#x22;software_license&#x22;,
      Fields: []sonzai.KBSchemaField{
          {Name: &#x22;market_price&#x22;, Type: &#x22;number&#x22;},
          {Name: &#x22;tier&#x22;,         Type: &#x22;string&#x22;},
          {Name: &#x22;category&#x22;,     Type: &#x22;string&#x22;},
          {Name: &#x22;license_type&#x22;, Type: &#x22;string&#x22;},
          {Name: &#x22;trend_30d&#x22;,    Type: &#x22;string&#x22;},
      },
  })
  if err != nil {
      panic(err)
  }
}`,
  },
]"
/>

You only need to create the schema once. From that point on the platform validates every entity of that type.

## 2. Seed Initial Data [#2-seed-initial-data]

Insert your first set of entities using `insertFacts`. This is also how you load historical data before going live. Include relationships so the KB can surface alternative or complementary tool recommendations.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.knowledge.insertFacts(PROJECT_ID, {
facts: [
  {
    entity_type: &#x22;software_license&#x22;,
    label: &#x22;Figma Enterprise&#x22;,
    properties: {
      market_price: 75,
      tier: &#x22;Enterprise&#x22;,
      category: &#x22;Design Tools&#x22;,
      license_type: &#x22;per-seat-annual&#x22;,
      trend_30d: &#x22;+5%&#x22;,
    },
  },
  {
    entity_type: &#x22;software_license&#x22;,
    label: &#x22;Slack Business+&#x22;,
    properties: {
      market_price: 12.50,
      tier: &#x22;Business&#x22;,
      category: &#x22;Communication&#x22;,
      license_type: &#x22;per-seat-monthly&#x22;,
      trend_30d: &#x22;+3%&#x22;,
    },
  },
  {
    entity_type: &#x22;category&#x22;,
    label: &#x22;Design Tools&#x22;,
    properties: { vendor_count: 18, avg_seat_cost: 45 },
  },
],
relationships: [
  { from_label: &#x22;Figma Enterprise&#x22;,  to_label: &#x22;Design Tools&#x22;, edge_type: &#x22;belongs_to&#x22; },
  { from_label: &#x22;Slack Business+&#x22;,   to_label: &#x22;Communication&#x22;, edge_type: &#x22;belongs_to&#x22; },
  { from_label: &#x22;Figma Enterprise&#x22;,  to_label: &#x22;Slack Business+&#x22;, edge_type: &#x22;commonly_bundled&#x22; },
],
source: &#x22;seed_v1&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.knowledge.insert_facts(PROJECT_ID,
  facts=[
      {
          &#x22;entity_type&#x22;: &#x22;software_license&#x22;,
          &#x22;label&#x22;: &#x22;Figma Enterprise&#x22;,
          &#x22;properties&#x22;: {
              &#x22;market_price&#x22;: 75,
              &#x22;tier&#x22;: &#x22;Enterprise&#x22;,
              &#x22;category&#x22;: &#x22;Design Tools&#x22;,
              &#x22;license_type&#x22;: &#x22;per-seat-annual&#x22;,
              &#x22;trend_30d&#x22;: &#x22;+5%&#x22;,
          },
      },
      {
          &#x22;entity_type&#x22;: &#x22;software_license&#x22;,
          &#x22;label&#x22;: &#x22;Slack Business+&#x22;,
          &#x22;properties&#x22;: {
              &#x22;market_price&#x22;: 12.50,
              &#x22;tier&#x22;: &#x22;Business&#x22;,
              &#x22;category&#x22;: &#x22;Communication&#x22;,
              &#x22;license_type&#x22;: &#x22;per-seat-monthly&#x22;,
              &#x22;trend_30d&#x22;: &#x22;+3%&#x22;,
          },
      },
      {
          &#x22;entity_type&#x22;: &#x22;category&#x22;,
          &#x22;label&#x22;: &#x22;Design Tools&#x22;,
          &#x22;properties&#x22;: {&#x22;vendor_count&#x22;: 18, &#x22;avg_seat_cost&#x22;: 45},
      },
  ],
  relationships=[
      {&#x22;from_label&#x22;: &#x22;Figma Enterprise&#x22;,  &#x22;to_label&#x22;: &#x22;Design Tools&#x22;, &#x22;edge_type&#x22;: &#x22;belongs_to&#x22;},
      {&#x22;from_label&#x22;: &#x22;Slack Business+&#x22;,   &#x22;to_label&#x22;: &#x22;Communication&#x22;, &#x22;edge_type&#x22;: &#x22;belongs_to&#x22;},
      {&#x22;from_label&#x22;: &#x22;Figma Enterprise&#x22;,  &#x22;to_label&#x22;: &#x22;Slack Business+&#x22;, &#x22;edge_type&#x22;: &#x22;commonly_bundled&#x22;},
  ],
  source=&#x22;seed_v1&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err = client.Knowledge.InsertFacts(ctx, projectID, sonzai.InsertFactsOptions{
  Facts: []sonzai.InsertFactEntry{
      {
          EntityType: &#x22;software_license&#x22;,
          Label:      &#x22;Figma Enterprise&#x22;,
          Properties: map[string]interface{}{
              &#x22;market_price&#x22;:  75,
              &#x22;tier&#x22;:          &#x22;Enterprise&#x22;,
              &#x22;category&#x22;:      &#x22;Design Tools&#x22;,
              &#x22;license_type&#x22;:  &#x22;per-seat-annual&#x22;,
              &#x22;trend_30d&#x22;:     &#x22;+5%&#x22;,
          },
      },
      {
          EntityType: &#x22;software_license&#x22;,
          Label:      &#x22;Slack Business+&#x22;,
          Properties: map[string]interface{}{
              &#x22;market_price&#x22;:  12.50,
              &#x22;tier&#x22;:          &#x22;Business&#x22;,
              &#x22;category&#x22;:      &#x22;Communication&#x22;,
              &#x22;license_type&#x22;:  &#x22;per-seat-monthly&#x22;,
              &#x22;trend_30d&#x22;:     &#x22;+3%&#x22;,
          },
      },
      {
          EntityType: &#x22;category&#x22;,
          Label:      &#x22;Design Tools&#x22;,
          Properties: map[string]interface{}{&#x22;vendor_count&#x22;: 18, &#x22;avg_seat_cost&#x22;: 45},
      },
  },
  Relationships: []sonzai.InsertRelEntry{
      {FromLabel: &#x22;Figma Enterprise&#x22;, ToLabel: &#x22;Design Tools&#x22;, EdgeType: &#x22;belongs_to&#x22;},
      {FromLabel: &#x22;Slack Business+&#x22;,  ToLabel: &#x22;Communication&#x22;, EdgeType: &#x22;belongs_to&#x22;},
      {FromLabel: &#x22;Figma Enterprise&#x22;, ToLabel: &#x22;Slack Business+&#x22;, EdgeType: &#x22;commonly_bundled&#x22;},
  },
  Source: &#x22;seed_v1&#x22;,
})`,
  },
]"
/>

## 3. Keep Pricing Fresh with bulkUpdate [#3-keep-pricing-fresh-with-bulkupdate]

Run a cost-sync job on a schedule (e.g. daily cron) that fetches current pricing from your vendor data source and pushes it into the KB. `bulkUpdate` merges properties into existing nodes matched by label — no need to delete and re-insert.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// cost-sync.ts — run daily
import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;
import { fetchLatestPricing } from &#x22;./vendor-api&#x22;; // your data source

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = &#x22;proj_abc123&#x22;;

async function syncPricing() {
const pricing = await fetchLatestPricing(); // [{ name, price, trend }]

await client.knowledge.bulkUpdate(PROJECT_ID, {
  updates: pricing.map((license) => ({
    entity_type: &#x22;software_license&#x22;,
    label: license.name,
    properties: {
      market_price: license.price,
      trend_30d: license.trend,
      last_synced: new Date().toISOString(),
    },
  })),
});

console.log(\`Synced \${pricing.length} license prices\`);
}

syncPricing();`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# cost_sync.py — run daily via cron or a scheduler
from sonzai import Sonzai
from vendor_api import fetch_latest_pricing  # your data source
from datetime import datetime, timezone
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
PROJECT_ID = &#x22;proj_abc123&#x22;

def sync_pricing():
  pricing = fetch_latest_pricing()  # [{&#x22;name&#x22;: ..., &#x22;price&#x22;: ..., &#x22;trend&#x22;: ...}]

  client.knowledge.bulk_update(PROJECT_ID,
      updates=[
          {
              &#x22;entity_type&#x22;: &#x22;software_license&#x22;,
              &#x22;label&#x22;: license[&#x22;name&#x22;],
              &#x22;properties&#x22;: {
                  &#x22;market_price&#x22;: license[&#x22;price&#x22;],
                  &#x22;trend_30d&#x22;: license[&#x22;trend&#x22;],
                  &#x22;last_synced&#x22;: datetime.now(timezone.utc).isoformat(),
              },
          }
          for license in pricing
      ]
  )
  print(f&#x22;Synced {len(pricing)} license prices&#x22;)

sync_pricing()`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// cost_sync.go — run daily
package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  &#x22;time&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const projectID = &#x22;proj_abc123&#x22;

func syncPricing(client *sonzai.Client, pricing []PriceEntry) error {
  ctx := context.Background()
  updates := make([]sonzai.KBBulkUpdateEntry, len(pricing))

  for i, license := range pricing {
      updates[i] = sonzai.KBBulkUpdateEntry{
          EntityType: &#x22;software_license&#x22;,
          Label:      license.Name,
          Properties: map[string]interface{}{
              &#x22;market_price&#x22;: license.Price,
              &#x22;trend_30d&#x22;:    license.Trend,
              &#x22;last_synced&#x22;:  time.Now().UTC().Format(time.RFC3339),
          },
      }
  }

  result, err := client.Knowledge.BulkUpdate(ctx, projectID, sonzai.KBBulkUpdateOptions{
      Updates: updates,
  })
  if err != nil {
      return err
  }
  fmt.Printf(&#x22;Synced %d license prices\\n&#x22;, result.Updated)
  return nil
}`,
  },
]"
/>

<Callout type="warn" title="Batch size">
  Batches of ≤100 items are processed synchronously (immediate response). Larger batches are queued and processed asynchronously — the response includes a job ID you can poll for completion.
</Callout>

## 4. Enable Inventory on Your Agent [#4-enable-inventory-on-your-agent]

Enable the `inventory` and `knowledge` capabilities on your agent. This gives the agent the `sonzai_inventory_update` and `sonzai_inventory` tools automatically — no prompt engineering required.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const AGENT_ID = &#x22;agent_xyz&#x22;;

await client.agents.updateCapabilities(AGENT_ID, {
inventory: true,   // enables sonzai_inventory_update + sonzai_inventory tools
knowledge: true,   // enables knowledge_search tool
project_id: PROJECT_ID,  // which KB to join against
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `AGENT_ID = &#x22;agent_xyz&#x22;

client.agents.update_capabilities(AGENT_ID, {
  &#x22;inventory&#x22;: True,    # enables sonzai_inventory_update + sonzai_inventory tools
  &#x22;knowledge&#x22;: True,    # enables knowledge_search tool
  &#x22;project_id&#x22;: PROJECT_ID,
})`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `const agentID = &#x22;agent_xyz&#x22;

_, err = client.Agents.UpdateCapabilities(ctx, agentID, sonzai.UpdateCapabilitiesOptions{
  Inventory:  true,     // enables sonzai_inventory_update + sonzai_inventory tools
  Knowledge:  true,     // enables knowledge_search tool
  ProjectID:  projectID,
})`,
  },
]"
/>

You can also set this from the dashboard: go to **Agents → your agent → Capabilities** and toggle **Inventory** on.

## 5. Let the Agent Track Resources in Conversation [#5-let-the-agent-track-resources-in-conversation]

Once inventory is enabled, the agent calls `sonzai_inventory_update` on its own whenever a user mentions a tool or subscription they use. You just chat normally — the platform does the KB resolution and storage.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Your backend chat endpoint
for await (const event of client.agents.chatStream(AGENT_ID, {
userId: &#x22;user_123&#x22;,
messages: [
  {
    role: &#x22;user&#x22;,
    content: &#x22;We just provisioned 10 Figma Enterprise seats at $75/seat.&#x22;,
  },
],
})) {
// The agent streams its reply — and internally calls
// sonzai_inventory_update({ action: &#x22;add&#x22;, item_type: &#x22;software_license&#x22;,
//   label: &#x22;Figma Enterprise&#x22;, description: &#x22;Figma Enterprise design tool subscription&#x22;,
//   properties: { plan: &#x22;Enterprise&#x22;, purchase_price: 75, quantity: 10 } })
// The platform resolves the KB node, stores the link, and the agent
// continues the conversation without interruption.
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Your backend chat endpoint
for event in client.agents.chat(
  AGENT_ID,
  user_id=&#x22;user_123&#x22;,
  messages=[
      {
          &#x22;role&#x22;: &#x22;user&#x22;,
          &#x22;content&#x22;: &#x22;We just provisioned 10 Figma Enterprise seats at $75/seat.&#x22;,
      }
  ],
  stream=True,
):
  # The agent streams its reply — and internally calls
  # sonzai_inventory_update to record the license in user inventory.
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Your backend chat endpoint
err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
  AgentID: agentID,
  ChatOptions: sonzai.ChatOptions{
      UserID: &#x22;user_123&#x22;,
      Messages: []sonzai.ChatMessage{
          {
              Role:    &#x22;user&#x22;,
              Content: &#x22;We just provisioned 10 Figma Enterprise seats at $75/seat.&#x22;,
          },
      },
  },
}, func(event sonzai.ChatStreamEvent) error {
  // Agent streams reply and calls sonzai_inventory_update internally.
  // The platform resolves the KB node, stores the link.
  fmt.Print(event.Content())
  return nil
})`,
  },
]"
/>

<Callout type="info" title="How KB resolution works">
  The platform searches the KB for the item description. If exactly one node matches, it links automatically. If there are multiple candidates, the response returns `status: "disambiguation_needed"` with a list of candidates so the agent can ask the user to clarify.
</Callout>

## 6. Query the Enriched Portfolio [#6-query-the-enriched-portfolio]

Use `mode="value"` to get each user resource joined with the latest KB pricing data. The platform computes `gain_loss` automatically: `(market_price - purchase_price) × quantity`.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const portfolio = await client.agents.inventory.query(AGENT_ID, &#x22;user_123&#x22;, {
mode: &#x22;value&#x22;,
project_id: PROJECT_ID,
});

// portfolio.items:
// [
//   {
//     inventory_item_id: &#x22;inv_abc&#x22;,  // preferred identifier
//     fact_id: &#x22;fact_abc&#x22;,           // backward compat alias
//     item_label: &#x22;Figma Enterprise&#x22;,
//     kb_node_id: &#x22;node_xyz&#x22;,
//     user_properties: { plan: &#x22;Enterprise&#x22;, purchase_price: 75, quantity: 10 },
//     market_properties: { market_price: 80, tier: &#x22;Enterprise&#x22;, trend_30d: &#x22;+5%&#x22; },
//     gain_loss: 50,
//   },
// ]
// portfolio.totals: { &#x22;market_price:sum&#x22;: 800, &#x22;*:count&#x22;: 10 }

console.log(\`Portfolio value: $\${portfolio.totals?.[&#x22;market_price:sum&#x22;]}\`);
console.log(\`Total cost change: $\${portfolio.items.reduce((s, i) => s + i.gain_loss, 0)}\`);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `portfolio = client.agents.inventory.query(AGENT_ID, &#x22;user_123&#x22;,
  mode=&#x22;value&#x22;,
  project_id=PROJECT_ID,
)

# portfolio.items — list of enriched resources with market_properties + gain_loss
for item in portfolio.items:
  price = item.market_properties[&#x22;market_price&#x22;]
  gain  = item.gain_loss
  print(f&#x22;{item.item_label}: current \${price:.0f}/seat, cost change \${gain:+.0f}&#x22;)

total_value = portfolio.totals.get(&#x22;market_price:sum&#x22;, 0)
print(f&#x22;Total portfolio value: \${total_value}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `portfolio, err := client.Agents.Inventory.Query(ctx, agentID, &#x22;user_123&#x22;,
  sonzai.InventoryQueryOptions{
      Mode:      &#x22;value&#x22;,
      ProjectID: projectID,
  },
)
if err != nil {
  panic(err)
}

var totalChange float64
for _, item := range portfolio.Items {
  fmt.Printf(&#x22;%s: current $%.0f/seat, cost change: $%+.0f\\n&#x22;,
      item.ItemLabel,
      item.MarketProperties[&#x22;market_price&#x22;],
      item.GainLoss,
  )
  totalChange += item.GainLoss
}
fmt.Printf(&#x22;Total cost change: $%+.0f\\n&#x22;, totalChange)`,
  },
]"
/>

You can also use `mode="aggregate"` with the `aggregations` parameter to get portfolio-level totals without listing every resource — useful for organizations with many subscriptions.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Aggregate: total count + total subscription cost, grouped by item_type
const agg = await client.agents.inventory.query(AGENT_ID, &#x22;user_123&#x22;, {
mode: &#x22;aggregate&#x22;,
aggregations: &#x22;market_price:sum,*:count&#x22;,
group_by: &#x22;item_type&#x22;,
project_id: PROJECT_ID,
});
// agg.totals: { &#x22;market_price:sum&#x22;: 875, &#x22;*:count&#x22;: 12 }
// agg.groups: [{ group: &#x22;software_license&#x22;, values: { sum: 875, count: 12 } }]`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `agg = client.agents.inventory.query(AGENT_ID, &#x22;user_123&#x22;,
  mode=&#x22;aggregate&#x22;,
  aggregations=&#x22;market_price:sum,*:count&#x22;,
  group_by=&#x22;item_type&#x22;,
  project_id=PROJECT_ID,
)
print(agg.totals)   # {&#x22;market_price:sum&#x22;: 875, &#x22;*:count&#x22;: 12}
print(agg.groups)   # [{&#x22;group&#x22;: &#x22;software_license&#x22;, &#x22;values&#x22;: {&#x22;sum&#x22;: 875, &#x22;count&#x22;: 12}}]`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `agg, err := client.Agents.Inventory.Query(ctx, agentID, &#x22;user_123&#x22;,
  sonzai.InventoryQueryOptions{
      Mode:         &#x22;aggregate&#x22;,
      Aggregations: &#x22;market_price:sum,*:count&#x22;,
      GroupBy:      &#x22;item_type&#x22;,
      ProjectID:    projectID,
  },
)
fmt.Printf(&#x22;Total value: $%.0f, Total items: %v\\n&#x22;,
  agg.Totals[&#x22;market_price:sum&#x22;],
  agg.Totals[&#x22;*:count&#x22;],
)`,
  },
]"
/>

## 7. Batch-Import Existing Subscriptions [#7-batch-import-existing-subscriptions]

If a user already has an existing set of subscriptions (from a CSV, a procurement system export, etc.), import them in bulk rather than waiting for the agent to discover each resource in conversation.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.inventory.batchImport(AGENT_ID, &#x22;user_123&#x22;, {
project_id: PROJECT_ID,
items: [
  {
    item_type:   &#x22;software_license&#x22;,
    label:       &#x22;Figma Enterprise&#x22;,
    description: &#x22;Figma Enterprise design tool subscription&#x22;,
    properties:  { quantity: 10, plan: &#x22;Enterprise&#x22;, purchase_price: 75 },
  },
  {
    item_type:   &#x22;software_license&#x22;,
    label:       &#x22;GitHub Enterprise&#x22;,
    description: &#x22;GitHub Enterprise version control and CI/CD platform&#x22;,
    properties:  { quantity: 25, plan: &#x22;Enterprise&#x22;, purchase_price: 21 },
  },
],
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.inventory.batch_import(AGENT_ID, &#x22;user_123&#x22;,
  project_id=PROJECT_ID,
  items=[
      {
          &#x22;item_type&#x22;:   &#x22;software_license&#x22;,
          &#x22;label&#x22;:       &#x22;Figma Enterprise&#x22;,
          &#x22;description&#x22;: &#x22;Figma Enterprise design tool subscription&#x22;,
          &#x22;properties&#x22;:  {&#x22;quantity&#x22;: 10, &#x22;plan&#x22;: &#x22;Enterprise&#x22;, &#x22;purchase_price&#x22;: 75},
      },
      {
          &#x22;item_type&#x22;:   &#x22;software_license&#x22;,
          &#x22;label&#x22;:       &#x22;GitHub Enterprise&#x22;,
          &#x22;description&#x22;: &#x22;GitHub Enterprise version control and CI/CD platform&#x22;,
          &#x22;properties&#x22;:  {&#x22;quantity&#x22;: 25, &#x22;plan&#x22;: &#x22;Enterprise&#x22;, &#x22;purchase_price&#x22;: 21},
      },
  ],
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err = client.Agents.Inventory.BatchImport(ctx, agentID, &#x22;user_123&#x22;,
  sonzai.InventoryBatchImportOptions{
      ProjectID: projectID,
      Items: []sonzai.InventoryBatchItem{
          {
              ItemType:    &#x22;software_license&#x22;,
              Label:       &#x22;Figma Enterprise&#x22;,
              Description: &#x22;Figma Enterprise design tool subscription&#x22;,
              Properties:  map[string]interface{}{&#x22;quantity&#x22;: 10, &#x22;plan&#x22;: &#x22;Enterprise&#x22;, &#x22;purchase_price&#x22;: 75},
          },
          {
              ItemType:    &#x22;software_license&#x22;,
              Label:       &#x22;GitHub Enterprise&#x22;,
              Description: &#x22;GitHub Enterprise version control and CI/CD platform&#x22;,
              Properties:  map[string]interface{}{&#x22;quantity&#x22;: 25, &#x22;plan&#x22;: &#x22;Enterprise&#x22;, &#x22;purchase_price&#x22;: 21},
          },
      },
  },
)`,
  },
]"
/>

<Callout type="warn" title="Up to 1,000 items per batch">
  The batch endpoint processes up to 1,000 items per call. For larger imports, split into multiple calls or use the CSV priming feature in the dashboard.
</Callout>

## Next Steps [#next-steps]

* Set up a recommendation rule in the KB to surface alternative tools to users
* Add trend tracking (7d/30d/90d) to power "biggest cost increases" reports
* View per-user inventory live in **Dashboard → Agents → your agent → Users → select user → Inventory / Assets**
* Read the [Knowledge Base](/docs/en/knowledge-base) reference for schemas, analytics rules, and full-text search


---

# Medication Reminders

Source: https://sonz.ai/docs/en/guides/tutorials/tutorial-medication-reminders

> End-to-end tutorial combining Inventory + Scheduled Reminders to ship a medication adherence experience. The agent proactively reminds users to take the right drug at the right dose at the right time, in their timezone, with quiet hours respected.



This tutorial walks through a full medication-reminder implementation: define a medication entity type in your knowledge base, seed medications per user, create a Scheduled Reminder linking each medication to a cadence, and the agent proactively messages the user at the scheduled time — naming the medication and dosage in its own voice.

<Callout type="info">
  **Tenant-agnostic primitive.** The Sonzai platform has no medication-specific code. This tutorial wires two generic primitives — [Inventory](./tutorial-inventory) and [Scheduled Reminders](./tutorial-scheduled-reminders) — into a medication use case. The same pattern works for watering plants, exercise reminders, bill payments, or any recurring-with-structured-data use case.
</Callout>

<Callout type="warning">
  **This is not a medical device.** Reminders are a user-experience feature, not a clinical safety mechanism. Do not rely on Sonzai scheduled reminders as the sole adherence path for patients where missed doses cause harm.
</Callout>

## 1. Define a medication entity in your knowledge base [#1-define-a-medication-entity-in-your-knowledge-base]

Create a schema for the `medication` entity type so the platform knows how to store and index each drug's properties. The `name` and `ndc_code` fields are indexed for fast lookup; `dosage`, `instructions`, and `prescribed_by` are stored but not indexed (they are fetched whole at fire time).

See the [Resource Inventory + Knowledge Base](./tutorial-inventory) tutorial for full schema semantics, field types, and upsert behaviour.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const PROJECT_ID = &#x22;proj_abc123&#x22;;

await client.knowledge.createSchema(PROJECT_ID, {
entity_type: &#x22;medication&#x22;,
display_name: &#x22;Medication&#x22;,
fields: [
  { name: &#x22;medication_name&#x22;, type: &#x22;string&#x22;,  indexed: true  },
  { name: &#x22;dosage&#x22;,          type: &#x22;string&#x22;,  indexed: false },
  { name: &#x22;instructions&#x22;,    type: &#x22;string&#x22;,  indexed: false },
  { name: &#x22;prescribed_by&#x22;,   type: &#x22;string&#x22;,  indexed: false },
  { name: &#x22;ndc_code&#x22;,        type: &#x22;string&#x22;,  indexed: true  }, // optional; National Drug Code
],
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
PROJECT_ID = &#x22;proj_abc123&#x22;

client.knowledge.create_schema(PROJECT_ID, {
  &#x22;entity_type&#x22;: &#x22;medication&#x22;,
  &#x22;display_name&#x22;: &#x22;Medication&#x22;,
  &#x22;fields&#x22;: [
      {&#x22;name&#x22;: &#x22;medication_name&#x22;, &#x22;type&#x22;: &#x22;string&#x22;, &#x22;indexed&#x22;: True},
      {&#x22;name&#x22;: &#x22;dosage&#x22;,          &#x22;type&#x22;: &#x22;string&#x22;, &#x22;indexed&#x22;: False},
      {&#x22;name&#x22;: &#x22;instructions&#x22;,    &#x22;type&#x22;: &#x22;string&#x22;, &#x22;indexed&#x22;: False},
      {&#x22;name&#x22;: &#x22;prescribed_by&#x22;,   &#x22;type&#x22;: &#x22;string&#x22;, &#x22;indexed&#x22;: False},
      {&#x22;name&#x22;: &#x22;ndc_code&#x22;,        &#x22;type&#x22;: &#x22;string&#x22;, &#x22;indexed&#x22;: True},  # optional
  ],
})`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;os&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const projectID = &#x22;proj_abc123&#x22;

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()

  _, err := client.Knowledge.CreateSchema(ctx, projectID, sonzai.CreateSchemaOptions{
      EntityType:  &#x22;medication&#x22;,
      DisplayName: &#x22;Medication&#x22;,
      Fields: []sonzai.SchemaField{
          {Name: &#x22;medication_name&#x22;, Type: &#x22;string&#x22;, Indexed: true},
          {Name: &#x22;dosage&#x22;,          Type: &#x22;string&#x22;, Indexed: false},
          {Name: &#x22;instructions&#x22;,    Type: &#x22;string&#x22;, Indexed: false},
          {Name: &#x22;prescribed_by&#x22;,   Type: &#x22;string&#x22;, Indexed: false},
          {Name: &#x22;ndc_code&#x22;,        Type: &#x22;string&#x22;, Indexed: true}, // optional
      },
  })
  if err != nil {
      panic(err)
  }
}`,
  },
]"
/>

You only need to create the schema once per project. All subsequent medication items written for any user will be validated and indexed against this definition.

## 2. Seed a medication for the user [#2-seed-a-medication-for-the-user]

Insert one medication into the user's inventory using `inventory.update` with `action: "add"`. Store the returned `fact_id` — you will pass it to the schedule in the next step.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const AGENT_ID = &#x22;agent_abc&#x22;;
const USER_ID  = &#x22;user_123&#x22;;

const item = await client.agents.inventory.update(AGENT_ID, USER_ID, {
action:      &#x22;add&#x22;,
item_type:   &#x22;medication&#x22;,
label:       &#x22;Ibuprofen&#x22;,
description: &#x22;anti-inflammatory pain reliever, 400–500mg&#x22;,
project_id:  PROJECT_ID,
properties: {
  medication_name: &#x22;ibuprofen&#x22;,
  dosage:          &#x22;500mg&#x22;,
  instructions:    &#x22;take with food&#x22;,
  prescribed_by:   &#x22;Dr. Tan&#x22;,
},
});

const inventoryItemId = item.inventory_item_id; // preferred; item.fact_id is a compat alias
// e.g. &#x22;inv_01HX8FKZQ3...&#x22;
console.log(inventoryItemId);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `AGENT_ID = &#x22;agent_abc&#x22;
USER_ID  = &#x22;user_123&#x22;

item = client.agents.inventory.update(AGENT_ID, USER_ID, {
  &#x22;action&#x22;:      &#x22;add&#x22;,
  &#x22;item_type&#x22;:   &#x22;medication&#x22;,
  &#x22;label&#x22;:       &#x22;Ibuprofen&#x22;,
  &#x22;description&#x22;: &#x22;anti-inflammatory pain reliever, 400–500mg&#x22;,
  &#x22;project_id&#x22;:  PROJECT_ID,
  &#x22;properties&#x22;: {
      &#x22;medication_name&#x22;: &#x22;ibuprofen&#x22;,
      &#x22;dosage&#x22;:          &#x22;500mg&#x22;,
      &#x22;instructions&#x22;:    &#x22;take with food&#x22;,
      &#x22;prescribed_by&#x22;:   &#x22;Dr. Tan&#x22;,
  },
})

inventory_item_id = item.inventory_item_id  # preferred; item.fact_id is a compat alias
# e.g. &#x22;inv_01HX8FKZQ3...&#x22;
print(inventory_item_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `const agentID = &#x22;agent_abc&#x22;
const userID  = &#x22;user_123&#x22;

item, err := client.Agents.Inventory.Update(ctx, agentID, userID,
  sonzai.InventoryUpdateOptions{
      Action:      &#x22;add&#x22;,
      ItemType:    &#x22;medication&#x22;,
      Label:       &#x22;Ibuprofen&#x22;,
      Description: &#x22;anti-inflammatory pain reliever, 400–500mg&#x22;,
      ProjectID:   projectID,
      Properties: map[string]interface{}{
          &#x22;medication_name&#x22;: &#x22;ibuprofen&#x22;,
          &#x22;dosage&#x22;:          &#x22;500mg&#x22;,
          &#x22;instructions&#x22;:    &#x22;take with food&#x22;,
          &#x22;prescribed_by&#x22;:   &#x22;Dr. Tan&#x22;,
      },
  },
)
if err != nil {
  panic(err)
}

inventoryItemID := item.InventoryItemID // preferred; item.FactID is a compat alias
// e.g. &#x22;inv_01HX8FKZQ3...&#x22;
fmt.Println(inventoryItemID)`,
  },
]"
/>

## 3. Create a schedule linked to the medication [#3-create-a-schedule-linked-to-the-medication]

Create a twice-daily schedule at 08:00 and 20:00 Asia/Singapore, with `active_window.hours` set as a belt-and-braces quiet-hours guard. Pass the `inventory_item_id` returned in step 2. The platform will fetch the live item properties at every fire — no re-registration required when the dosage changes.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const schedule = await client.schedules.create(AGENT_ID, USER_ID, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;08:00&#x22;, &#x22;20:00&#x22;] },
  timezone: &#x22;Asia/Singapore&#x22;,
},
active_window: {
  hours: { start: &#x22;07:00&#x22;, end: &#x22;22:00&#x22; },
},
intent: &#x22;remind the user to take their ibuprofen at the correct dose&#x22;,
check_type: &#x22;reminder&#x22;,
inventory_item_id: inventoryItemId,
metadata: { reminder_category: &#x22;medication&#x22; },
});

const scheduleId = schedule.schedule_id;
console.log(scheduleId);          // &#x22;sched_01HX...&#x22;
console.log(schedule.next_fire_at);       // &#x22;2026-05-02T00:00:00Z&#x22;
console.log(schedule.next_fire_at_local); // &#x22;2026-05-02T08:00:00+08:00&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `schedule = client.schedules.create(
  AGENT_ID,
  USER_ID,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;08:00&#x22;, &#x22;20:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
  },
  active_window={
      &#x22;hours&#x22;: {&#x22;start&#x22;: &#x22;07:00&#x22;, &#x22;end&#x22;: &#x22;22:00&#x22;},
  },
  intent=&#x22;remind the user to take their ibuprofen at the correct dose&#x22;,
  check_type=&#x22;reminder&#x22;,
  inventory_item_id=inventory_item_id,
  metadata={&#x22;reminder_category&#x22;: &#x22;medication&#x22;},
)

schedule_id = schedule.schedule_id
print(schedule_id)              # &#x22;sched_01HX...&#x22;
print(schedule.next_fire_at)    # &#x22;2026-05-02T00:00:00Z&#x22;
print(schedule.next_fire_at_local)  # &#x22;2026-05-02T08:00:00+08:00&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `cadence, _ := json.Marshal(map[string]any{
  &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: []string{&#x22;08:00&#x22;, &#x22;20:00&#x22;}},
  &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
})
activeWindow, _ := json.Marshal(map[string]any{
  &#x22;hours&#x22;: map[string]any{&#x22;start&#x22;: &#x22;07:00&#x22;, &#x22;end&#x22;: &#x22;22:00&#x22;},
})
metadata, _ := json.Marshal(map[string]any{&#x22;reminder_category&#x22;: &#x22;medication&#x22;})

schedule, err := client.Schedules.Create(ctx, agentID, userID,
  sonzai.CreateScheduleOptions{
      Cadence:         cadence,
      ActiveWindow:    activeWindow,
      Intent:          &#x22;remind the user to take their ibuprofen at the correct dose&#x22;,
      CheckType:       &#x22;reminder&#x22;,
      InventoryItemID: inventoryItemID,
      Metadata:        metadata,
  },
)
if err != nil {
  panic(err)
}

fmt.Println(schedule.ScheduleID)       // &#x22;sched_01HX...&#x22;
fmt.Println(schedule.NextFireAt)       // &#x22;2026-05-02T00:00:00Z&#x22;
fmt.Println(schedule.NextFireAtLocal)  // &#x22;2026-05-02T08:00:00+08:00&#x22;`,
  },
]"
/>

What each field controls:

| Field                  | Role                                                                                           |
| ---------------------- | ---------------------------------------------------------------------------------------------- |
| `cadence.simple.times` | Wall-clock fire times in the schedule's timezone                                               |
| `cadence.timezone`     | Per-user IANA zone; the platform does not auto-detect the user's location                      |
| `active_window.hours`  | Quiet-hours guard; fires computed outside the window are skipped, not deferred                 |
| `intent`               | The **why** the agent grounds its message in — written as a short natural-language instruction |
| `inventory_item_id`    | Links to the medication's structured properties, fetched live at every fire                    |
| `metadata`             | Opaque developer tags surfaced to the agent as "Additional context" in the wakeup block        |

## 4. What the user sees [#4-what-the-user-sees]

When the schedule fires at 08:00 Singapore time, the platform assembles a structured intent block and delivers it to the agent as a proactive wakeup. The agent composes its opening message in its own voice using the intent and the injected inventory properties. A typical output might look like:

> "Morning — quick reminder, it's 8 o'clock. Time for your 500mg of ibuprofen, and remember to take it with food."

Exact wording depends on the agent's personality configuration. The agent is not given a fixed template — it receives the intent and inventory data and decides how to phrase it naturally.

**Updating the dosage.** When a doctor reduces the ibuprofen dose from 500mg to 250mg, update the inventory item:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.inventory.directUpdate(AGENT_ID, USER_ID, inventoryItemId, {
properties: {
  dosage: &#x22;250mg&#x22;,
},
});
// No schedule edit required.
// The next scheduled fire automatically reads &#x22;250mg&#x22; from the live item.`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.inventory.direct_update(AGENT_ID, USER_ID, inventory_item_id,
  properties={&#x22;dosage&#x22;: &#x22;250mg&#x22;},
)
# No schedule edit required.
# The next scheduled fire automatically reads &#x22;250mg&#x22; from the live item.`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err = client.Agents.Inventory.DirectUpdate(ctx, agentID, userID, inventoryItemID,
  map[string]interface{}{&#x22;dosage&#x22;: &#x22;250mg&#x22;},
  &#x22;&#x22;,
)
// No schedule edit required.
// The next scheduled fire automatically reads &#x22;250mg&#x22; from the live item.`,
  },
]"
/>

This separation is intentional: &#x2A;*inventory is the source of truth for the *what*; the schedule is the source of truth for the *when*.** They change independently. Changing the dose never touches the schedule row; moving a reminder time never touches the medication item.

## 5. Bounded courses (14-day antibiotic) [#5-bounded-courses-14-day-antibiotic]

For medications with a fixed course length, use `starts_at` and `ends_at` to auto-disable the schedule when the course completes. Here is a 3x/day amoxicillin course that fires every 8 hours over 14 days:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const amoxItem = await client.agents.inventory.update(AGENT_ID, USER_ID, {
action:      &#x22;add&#x22;,
item_type:   &#x22;medication&#x22;,
label:       &#x22;Amoxicillin&#x22;,
description: &#x22;broad-spectrum antibiotic, penicillin class&#x22;,
project_id:  PROJECT_ID,
properties: {
  medication_name: &#x22;amoxicillin&#x22;,
  dosage:          &#x22;500mg&#x22;,
  instructions:    &#x22;complete the full course even if you feel better&#x22;,
  prescribed_by:   &#x22;Dr. Tan&#x22;,
},
});

const amoxSchedule = await client.schedules.create(AGENT_ID, USER_ID, {
cadence: {
  simple: { frequency: &#x22;interval_hours&#x22;, interval_hours: 8 },
  timezone: &#x22;Asia/Singapore&#x22;,
},
active_window: {
  hours: { start: &#x22;07:00&#x22;, end: &#x22;23:00&#x22; },
},
intent: &#x22;remind the user to take their amoxicillin — emphasise completing the full course&#x22;,
check_type: &#x22;reminder&#x22;,
inventory_item_id: amoxItem.fact_id,
metadata: { reminder_category: &#x22;medication&#x22; },
starts_at: &#x22;2026-05-01T00:00:00Z&#x22;,
ends_at:   &#x22;2026-05-15T00:00:00Z&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `amox_item = client.agents.inventory.update(AGENT_ID, USER_ID, {
  &#x22;action&#x22;:      &#x22;add&#x22;,
  &#x22;item_type&#x22;:   &#x22;medication&#x22;,
  &#x22;label&#x22;:       &#x22;Amoxicillin&#x22;,
  &#x22;description&#x22;: &#x22;broad-spectrum antibiotic, penicillin class&#x22;,
  &#x22;project_id&#x22;:  PROJECT_ID,
  &#x22;properties&#x22;: {
      &#x22;medication_name&#x22;: &#x22;amoxicillin&#x22;,
      &#x22;dosage&#x22;:          &#x22;500mg&#x22;,
      &#x22;instructions&#x22;:    &#x22;complete the full course even if you feel better&#x22;,
      &#x22;prescribed_by&#x22;:   &#x22;Dr. Tan&#x22;,
  },
})

amox_schedule = client.schedules.create(
  AGENT_ID,
  USER_ID,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;interval_hours&#x22;, &#x22;interval_hours&#x22;: 8},
      &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
  },
  active_window={
      &#x22;hours&#x22;: {&#x22;start&#x22;: &#x22;07:00&#x22;, &#x22;end&#x22;: &#x22;23:00&#x22;},
  },
  intent=&#x22;remind the user to take their amoxicillin — emphasise completing the full course&#x22;,
  check_type=&#x22;reminder&#x22;,
  inventory_item_id=amox_item.fact_id,
  metadata={&#x22;reminder_category&#x22;: &#x22;medication&#x22;},
  starts_at=&#x22;2026-05-01T00:00:00Z&#x22;,
  ends_at=&#x22;2026-05-15T00:00:00Z&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `amoxItem, err := client.Agents.Inventory.Update(ctx, agentID, userID,
  sonzai.InventoryUpdateOptions{
      Action:      &#x22;add&#x22;,
      ItemType:    &#x22;medication&#x22;,
      Label:       &#x22;Amoxicillin&#x22;,
      Description: &#x22;broad-spectrum antibiotic, penicillin class&#x22;,
      ProjectID:   projectID,
      Properties: map[string]interface{}{
          &#x22;medication_name&#x22;: &#x22;amoxicillin&#x22;,
          &#x22;dosage&#x22;:          &#x22;500mg&#x22;,
          &#x22;instructions&#x22;:    &#x22;complete the full course even if you feel better&#x22;,
          &#x22;prescribed_by&#x22;:   &#x22;Dr. Tan&#x22;,
      },
  },
)
if err != nil {
  panic(err)
}

cadence, _ := json.Marshal(map[string]any{
  &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;interval_hours&#x22;, &#x22;interval_hours&#x22;: 8},
  &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
})
activeWindow, _ := json.Marshal(map[string]any{
  &#x22;hours&#x22;: map[string]any{&#x22;start&#x22;: &#x22;07:00&#x22;, &#x22;end&#x22;: &#x22;23:00&#x22;},
})
metadata, _ := json.Marshal(map[string]any{&#x22;reminder_category&#x22;: &#x22;medication&#x22;})

amoxSchedule, err := client.Schedules.Create(ctx, agentID, userID,
  sonzai.CreateScheduleOptions{
      Cadence:         cadence,
      ActiveWindow:    activeWindow,
      Intent:          &#x22;remind the user to take their amoxicillin — emphasise completing the full course&#x22;,
      CheckType:       &#x22;reminder&#x22;,
      InventoryItemID: amoxItem.FactID,
      Metadata:        metadata,
      StartsAt:        &#x22;2026-05-01T00:00:00Z&#x22;,
      EndsAt:          &#x22;2026-05-15T00:00:00Z&#x22;,
  },
)`,
  },
]"
/>

After `ends_at` passes, the schedule is automatically disabled (`enabled` flips to `false`). The inventory item for amoxicillin remains as a historical record and can be queried via the Memory API. No cleanup is required.

## 6. Multiple medications [#6-multiple-medications]

Create one schedule per medication. Three daily medications = three schedules. Fires that land at the same wall-clock time produce separate proactive messages by design — each message is grounded in its own medication's inventory item.

**Avoid simultaneous fires.** If you want the user to receive distinct messages rather than a burst, stagger the `times` across schedules:

| Medication   | Schedule times       |
| ------------ | -------------------- |
| Metformin    | `["08:00", "20:00"]` |
| Atorvastatin | `["08:15"]`          |
| Vitamin D    | `["08:30"]`          |

**Alternative: compose a "morning routine" item.** If you prefer a single message covering all morning medications, create one inventory item of type `medication_routine` (define its own schema) with a `medications` property that lists all drugs and doses. Attach that single item to a single 08:00 schedule. The agent receives all the structured data in one wakeup block and can address all medications in a single message.

## 7. Track adherence (optional) [#7-track-adherence-optional]

### Conversational signal [#conversational-signal]

When the user replies "I took it, thanks" or similar, the agent's memory layer auto-captures this as a fact on the user. You can query recent user responses to a medication reminder via the Memory API:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Query recent memory facts mentioning medication adherence
const memories = await client.agents.memory.search(AGENT_ID, {
query: &#x22;medication taken ibuprofen&#x22;,
limit: 10,
});

for (const result of memories.results) {
console.log(result.content); // &#x22;User confirmed taking 500mg ibuprofen on 2026-05-02&#x22;
console.log(result.score);   // e.g. 0.91
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Query recent memory facts mentioning medication adherence
memories = client.agents.memory.search(AGENT_ID,
  query=&#x22;medication taken ibuprofen&#x22;,
  limit=10,
)

for result in memories.results:
  print(result.content)  # &#x22;User confirmed taking 500mg ibuprofen on 2026-05-02&#x22;
  print(result.score)    # e.g. 0.91`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `memories, err := client.Agents.Memory.Search(ctx, agentID,
  sonzai.MemorySearchOptions{
      Query: &#x22;medication taken ibuprofen&#x22;,
      Limit: 10,
  },
)
if err != nil {
  panic(err)
}

for _, result := range memories.Results {
  fmt.Println(result.Content) // &#x22;User confirmed taking 500mg ibuprofen on 2026-05-02&#x22;
  fmt.Println(result.Score)   // e.g. 0.91
}`,
  },
]"
/>

### Explicit acknowledgement [#explicit-acknowledgement]

For a harder signal, add a `POST /adherence/{scheduleId}` endpoint in your tenant backend that your mobile or web app calls when the user taps a confirmation button. This gives you a structured event log independent of the conversational memory layer. Sonzai does not provide this endpoint — it lives in your own backend and stores data in your own database.

## 8. Timezone changes when the user travels [#8-timezone-changes-when-the-user-travels]

Patch the schedule's `cadence.timezone` whenever the user's preferred timezone changes. Future fires are immediately recomputed in the new zone; past fire history is not modified.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// User travelling from Singapore to Los Angeles
await client.schedules.update(AGENT_ID, USER_ID, scheduleId, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;08:00&#x22;, &#x22;20:00&#x22;] },
  timezone: &#x22;America/Los_Angeles&#x22;,
},
});
// Next fire: 08:00 PDT (Los Angeles) — not 08:00 SGT`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# User travelling from Singapore to Los Angeles
client.schedules.update(AGENT_ID, USER_ID, schedule_id, {
  &#x22;cadence&#x22;: {
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;08:00&#x22;, &#x22;20:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;America/Los_Angeles&#x22;,
  },
})
# Next fire: 08:00 PDT (Los Angeles) — not 08:00 SGT`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// User travelling from Singapore to Los Angeles
cadence, _ := json.Marshal(map[string]any{
  &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: []string{&#x22;08:00&#x22;, &#x22;20:00&#x22;}},
  &#x22;timezone&#x22;: &#x22;America/Los_Angeles&#x22;,
})
_, err = client.Schedules.Update(ctx, agentID, userID, scheduleID,
  sonzai.UpdateScheduleOptions{
      Cadence: cadence,
  },
)
// Next fire: 08:00 PDT (Los Angeles) — not 08:00 SGT`,
  },
]"
/>

## 9. Quiet-hours for caregivers and night shifts [#9-quiet-hours-for-caregivers-and-night-shifts]

The `active_window.hours` field ensures fires outside permitted hours are silently skipped. Two common scenarios:

**Caregiver setting — no overnight messages for a patient.**

```json
{
  "active_window": {
    "hours": { "start": "07:00", "end": "21:00" }
  }
}
```

Any cadence tick after 21:00 or before 07:00 is discarded. A twice-daily schedule with times `["08:00", "20:00"]` would still fire at both times; adding a 22:00 dose would be silently skipped.

**Night-shift user — active overnight, sleeping during the day.**

```json
{
  "active_window": {
    "hours": { "start": "22:00", "end": "06:00" }
  }
}
```

When `start` is greater than `end`, the window wraps midnight. This user receives reminders from 22:00 to 05:59 the next morning, and any cadence ticks during daytime hours are skipped.

See [Scheduled Reminders — Active window](./tutorial-scheduled-reminders#4-active-window-quiet-hours--allowed-days) for the full reference including `days_of_week` filtering.

## Next steps [#next-steps]

* [Scheduled Reminders](./tutorial-scheduled-reminders) — full primitive reference: cadence shapes, DST handling, previewing upcoming fires, pause/resume/delete, error codes.
* [Resource Inventory + Knowledge Base](./tutorial-inventory) — KB schema depth, bulk updates, `mode="value"` portfolio queries, batch import.
* [Memory](./memory) — how the agent tracks user responses from proactive conversations and surfaces them in future interactions.


---

# Memory-Aware Chat

Source: https://sonz.ai/docs/en/guides/tutorials/tutorial-memory

> Build a conversational agent that remembers everything — user preferences, past events, commitments, and emotional context — across sessions. By the end you'll know how to seed context programmatically, search memories, and inspect what the agent has learned about a user.



### What you'll build [#what-youll-build]

* A streaming chat loop where the agent automatically extracts and stores facts
* A pre-seeding flow to inject existing user data before the first conversation
* A memory search API call to find what the agent knows about a specific topic
* A fact timeline query to audit the agent's memory growth over time

## How Memory Works [#how-memory-works]

Memory is fully automatic during chat. After each message exchange the platform:

1. Runs an extraction pipeline to identify facts, preferences, commitments, and events in the conversation
2. Deduplicates against existing memories using a supersession chain (old facts are retired, not deleted)
3. Indexes everything for full-text search and temporal queries
4. On the next conversation, fetches the most relevant memories automatically within a token budget

You never need to manage a vector store, write extraction prompts, or implement retrieval logic. The platform handles all of it.

## 1. Chat and Let Memory Build [#1-chat-and-let-memory-build]

Start chatting. Memory extraction happens automatically after the response streams. Nothing special needed on your end.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;
const USER_ID  = &#x22;user_123&#x22;;

// First conversation — agent has no memory yet
for await (const event of client.agents.chatStream(AGENT_ID, {
userId: USER_ID,
messages: [
  { role: &#x22;user&#x22;, content: &#x22;My name is Mia. I'm allergic to peanuts and I love hiking.&#x22; },
],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}
// Platform extracts: name=&#x22;Mia&#x22;, allergy=&#x22;peanuts&#x22;, interest=&#x22;hiking&#x22;

// Second conversation — agent recalls all of the above
for await (const event of client.agents.chatStream(AGENT_ID, {
userId: USER_ID,
messages: [
  { role: &#x22;user&#x22;, content: &#x22;What snacks should I bring on my next hike?&#x22; },
],
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? &#x22;&#x22;);
}
// Agent knows Mia loves hiking and is allergic to peanuts — no re-intro needed.`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;
USER_ID  = &#x22;user_123&#x22;

# First conversation — agent has no memory yet
for event in client.agents.chat(
  AGENT_ID,
  user_id=USER_ID,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;My name is Mia. I'm allergic to peanuts and I love hiking.&#x22;},
  ],
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)
# Platform extracts: name=&#x22;Mia&#x22;, allergy=&#x22;peanuts&#x22;, interest=&#x22;hiking&#x22;

print()  # newline

# Second conversation — agent recalls everything
for event in client.agents.chat(
  AGENT_ID,
  user_id=USER_ID,
  messages=[
      {&#x22;role&#x22;: &#x22;user&#x22;, &#x22;content&#x22;: &#x22;What snacks should I bring on my next hike?&#x22;},
  ],
  stream=True,
):
  print(event.content, end=&#x22;&#x22;, flush=True)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;fmt&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

const (
  agentID = &#x22;agent_abc&#x22;
  userID  = &#x22;user_123&#x22;
)

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()

  // First conversation
  err := client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
      AgentID: agentID,
      ChatOptions: sonzai.ChatOptions{
          UserID: userID,
          Messages: []sonzai.ChatMessage{
              {Role: &#x22;user&#x22;, Content: &#x22;My name is Mia. I'm allergic to peanuts and I love hiking.&#x22;},
          },
      },
  }, func(e sonzai.ChatStreamEvent) error {
      fmt.Print(e.Content())
      return nil
  })
  if err != nil { panic(err) }

  fmt.Println()

  // Second conversation — agent recalls name, allergy, and interest
  err = client.Agents.ChatStream(ctx, sonzai.AgentChatParams{
      AgentID: agentID,
      ChatOptions: sonzai.ChatOptions{
          UserID: userID,
          Messages: []sonzai.ChatMessage{
              {Role: &#x22;user&#x22;, Content: &#x22;What snacks should I bring on my next hike?&#x22;},
          },
      },
  }, func(e sonzai.ChatStreamEvent) error {
      fmt.Print(e.Content())
      return nil
  })
  if err != nil { panic(err) }
}`,
  },
]"
/>

<Callout type="warn" title="Memory is per-user">
  Facts extracted from user A's conversation are never surfaced to user B. Always pass `userId` (or `user_id` / `UserID`) in every chat call so the platform scopes memory correctly.
</Callout>

## 2. Pre-Seed Memory from Existing Data [#2-pre-seed-memory-from-existing-data]

If a user has history in your system — a CRM profile, onboarding answers, past orders — inject it before the first conversation so the agent feels like it already knows them.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Call once during onboarding or after CRM import
await client.agents.memory.seed(AGENT_ID, {
userId: USER_ID,
memories: [
  {
    content: &#x22;Mia is a 32-year-old UX designer based in Berlin.&#x22;,
    type: &#x22;user_fact&#x22;,
  },
  {
    content: &#x22;Mia subscribed to the Pro plan on 2024-11-03.&#x22;,
    type: &#x22;shared_experience&#x22;,
    occurred_at: &#x22;2024-11-03T00:00:00Z&#x22;,
  },
  {
    content: &#x22;Mia prefers email over SMS for notifications.&#x22;,
    type: &#x22;user_preference&#x22;,
  },
  {
    content: &#x22;Mia mentioned she wants to get into trail running.&#x22;,
    type: &#x22;user_goal&#x22;,
  },
],
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Call once during onboarding or after CRM import
client.agents.memory.seed(
  AGENT_ID,
  user_id=USER_ID,
  memories=[
      {
          &#x22;content&#x22;: &#x22;Mia is a 32-year-old UX designer based in Berlin.&#x22;,
          &#x22;type&#x22;: &#x22;user_fact&#x22;,
      },
      {
          &#x22;content&#x22;: &#x22;Mia subscribed to the Pro plan on 2024-11-03.&#x22;,
          &#x22;type&#x22;: &#x22;shared_experience&#x22;,
          &#x22;occurred_at&#x22;: &#x22;2024-11-03T00:00:00Z&#x22;,
      },
      {
          &#x22;content&#x22;: &#x22;Mia prefers email over SMS for notifications.&#x22;,
          &#x22;type&#x22;: &#x22;user_preference&#x22;,
      },
      {
          &#x22;content&#x22;: &#x22;Mia mentioned she wants to get into trail running.&#x22;,
          &#x22;type&#x22;: &#x22;user_goal&#x22;,
      },
  ],
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, err := client.Agents.Memory.Seed(ctx, agentID, sonzai.SeedMemoriesOptions{
  UserID: userID,
  Memories: []sonzai.SeedMemory{
      {
          Content: &#x22;Mia is a 32-year-old UX designer based in Berlin.&#x22;,
          Type:    &#x22;user_fact&#x22;,
      },
      {
          Content:    &#x22;Mia subscribed to the Pro plan on 2024-11-03.&#x22;,
          Type:       &#x22;shared_experience&#x22;,
          OccurredAt: &#x22;2024-11-03T00:00:00Z&#x22;,
      },
      {
          Content: &#x22;Mia prefers email over SMS for notifications.&#x22;,
          Type:    &#x22;user_preference&#x22;,
      },
      {
          Content: &#x22;Mia mentioned she wants to get into trail running.&#x22;,
          Type:    &#x22;user_goal&#x22;,
      },
  },
})`,
  },
]"
/>

Supported memory types: `user_fact`, `user_preference`, `shared_experience`, `user_goal`, `commitment`, `time_sensitive`.

## 3. Search What the Agent Knows [#3-search-what-the-agent-knows]

Query the memory store directly to find what the agent has extracted about a topic. Useful for building user-facing "what does my agent remember?" features or for debugging.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const results = await client.agents.memory.search(AGENT_ID, {
query: &#x22;diet restrictions food allergies&#x22;,
limit: 10,
});

for (const fact of results.results) {
console.log(\`[\${fact.factType}] \${fact.content} (score: \${fact.score})\`);
}
// [user_fact] Mia is allergic to peanuts (score: 0.97)
// [user_preference] Mia prefers nut-free snacks on hikes (score: 0.85)`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `results = client.agents.memory.search(AGENT_ID,
  query=&#x22;diet restrictions food allergies&#x22;,
  limit=10,
)

for fact in results.results:
  print(f&#x22;[{fact.fact_type}] {fact.content} (score: {fact.score:.2f})&#x22;)
# [user_fact] Mia is allergic to peanuts (score: 0.97)
# [user_preference] Mia prefers nut-free snacks on hikes (score: 0.85)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `results, err := client.Agents.Memory.Search(ctx, agentID, sonzai.MemorySearchOptions{
  Query: &#x22;diet restrictions food allergies&#x22;,
  Limit: 10,
})
if err != nil { panic(err) }

for _, fact := range results.Results {
  fmt.Printf(&#x22;[%s] %s (score: %.2f)\\n&#x22;,
      fact.FactType, fact.Content, fact.Score)
}`,
  },
]"
/>

## 4. Browse the Memory Tree [#4-browse-the-memory-tree]

The memory tree is a 7-level hierarchy that organises facts by category (`/identity/traits`, `/preferences/interests`, `/episodes/sessions`, etc.). You can walk it node by node.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Get top-level nodes
const tree = await client.agents.memory.list(AGENT_ID, {
userId: USER_ID,
includeContents: false,  // just node metadata, no fact text
});

for (const node of tree.nodes) {
console.log(\`\${node.nodeId} — \${node.title} (\${node.summary})\`);
}

// Drill into a node
const identityNode = await client.agents.memory.list(AGENT_ID, {
userId: USER_ID,
parentId: &#x22;node_identity_traits_id&#x22;,
includeContents: true,  // include fact text
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Get top-level nodes
tree = client.agents.memory.list(AGENT_ID,
  user_id=USER_ID,
  include_contents=False,
)

for node in tree.nodes:
  print(f&#x22;{node.node_id} — {node.title} ({node.summary})&#x22;)

# Drill into a node
identity_node = client.agents.memory.list(AGENT_ID,
  user_id=USER_ID,
  parent_id=&#x22;node_identity_traits_id&#x22;,
  include_contents=True,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// Get top-level nodes
tree, err := client.Agents.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{
  UserID:          userID,
  IncludeContents: false,
})
if err != nil { panic(err) }

for _, node := range tree.Nodes {
  fmt.Printf(&#x22;%s — %s\\n&#x22;, node.NodeID, node.Title)
}

// Drill into a node
details, err := client.Agents.Memory.List(ctx, agentID, &sonzai.MemoryListOptions{
  UserID:          userID,
  ParentID:        &#x22;node_identity_traits_id&#x22;,
  IncludeContents: true,
})`,
  },
]"
/>

You can explore the memory tree interactively in the dashboard under **Agents → your agent → Users → select user → Memory → Tree Explorer**.

## 5. Inspect the Fact Timeline [#5-inspect-the-fact-timeline]

The timeline shows every fact in chronological order — when it was created, updated, or superseded. Use it to audit memory growth or build a "conversation history" view.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const timeline = await client.agents.memory.timeline(AGENT_ID, {
userId: USER_ID,
// Optional: narrow to a date range
start: &#x22;2025-01-01T00:00:00Z&#x22;,
end:   &#x22;2025-12-31T23:59:59Z&#x22;,
});

for (const session of timeline.sessions) {
console.log(
  \`Session \${session.sessionId}: \${session.factCount} facts (\${session.firstFactAt})\`
);
for (const fact of session.facts) {
  console.log(\`  \${fact.atomicText}\`);
}
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `timeline = client.agents.memory.timeline(AGENT_ID,
  user_id=USER_ID,
  start=&#x22;2025-01-01T00:00:00Z&#x22;,
  end=&#x22;2025-12-31T23:59:59Z&#x22;,
)

for session in timeline.sessions:
  print(f&#x22;Session {session.session_id}: {session.fact_count} facts ({session.first_fact_at})&#x22;)
  for fact in session.facts:
      print(f&#x22;  {fact.atomic_text}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `timeline, err := client.Agents.Memory.Timeline(ctx, agentID, &sonzai.MemoryTimelineOptions{
  UserID: userID,
  Start:  &#x22;2025-01-01T00:00:00Z&#x22;,
  End:    &#x22;2025-12-31T23:59:59Z&#x22;,
})
if err != nil { panic(err) }

for _, session := range timeline.Sessions {
  fmt.Printf(&#x22;Session %s: %d facts (%s)\\n&#x22;,
      session.SessionID, session.FactCount, session.FirstFactAt)
  for _, fact := range session.Facts {
      fmt.Printf(&#x22;  %s\\n&#x22;, fact.AtomicText)
  }
}`,
  },
]"
/>

## 6. List Extracted Facts Directly [#6-list-extracted-facts-directly]

For admin UIs or compliance exports, list all raw facts for a user without going through the tree hierarchy. Supports filtering by `factType` (TS) / `fact_type` (Python/Go).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// All facts for this user (paginated)
const facts = await client.agents.memory.listFacts(AGENT_ID, {
userId: USER_ID,
limit: 50,
offset: 0,
factType: &#x22;user_preference&#x22;,  // optional filter
});

console.log(\`Total facts: \${facts.totalCount}\`);
for (const f of facts.facts) {
console.log(\`  \${f.content}\`);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `facts = client.agents.memory.list_facts(AGENT_ID,
  user_id=USER_ID,
  limit=50,
  offset=0,
  fact_type=&#x22;user_preference&#x22;,
)

print(f&#x22;Total facts: {facts.total_count}&#x22;)
for f in facts.facts:
  print(f&#x22;  {f.content}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `facts, err := client.Agents.Memory.ListFacts(ctx, agentID, &sonzai.FactListOptions{
  UserID:   userID,
  Limit:    50,
  Offset:   0,
  FactType: &#x22;user_preference&#x22;,
})
if err != nil { panic(err) }

fmt.Printf(&#x22;Total facts: %d\\n&#x22;, facts.TotalCount)
for _, f := range facts.Facts {
  fmt.Printf(&#x22;  %s\\n&#x22;, f.Content)
}`,
  },
]"
/>

<Callout type="warn" title="GDPR / right to erasure">
  To delete all memory for a user, call `client.agents.memory.reset(agentId, { userId })`. This creates tombstone records that prevent deleted facts from being re-surfaced; the data is removed from retrieval immediately.
</Callout>

## 7. Look Back in Time (Time Machine) [#7-look-back-in-time-time-machine]

The time machine lets you see what the agent knew about a user at any specific point in the past — useful for debugging why the agent said something, or for auditing how its understanding evolved.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const snapshot = await client.agents.getTimeMachine(AGENT_ID, {
userId: USER_ID,
at: &#x22;2025-03-01T00:00:00Z&#x22;,  // what did the agent know at this moment?
});

console.log(&#x22;Personality at 2025-03-01:&#x22;, snapshot.personalityAt);
console.log(&#x22;Mood at 2025-03-01:&#x22;, snapshot.moodAt);
for (const event of snapshot.evolutionEvents) {
console.log(\`  \${event.traitName}: \${event.oldValue} → \${event.newValue}\`);
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `snapshot = client.agents.get_time_machine(AGENT_ID,
  user_id=USER_ID,
  at=&#x22;2025-03-01T00:00:00Z&#x22;,
)

print(&#x22;Personality at 2025-03-01:&#x22;, snapshot.personality_at)
print(&#x22;Mood at 2025-03-01:&#x22;, snapshot.mood_at)
for event in snapshot.evolution_events:
  print(f&#x22;  {event.trait_name}: {event.old_value} → {event.new_value}&#x22;)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `snapshot, err := client.Agents.GetTimeMachine(ctx, agentID, sonzai.TimeMachineOptions{
  UserID: userID,
  At:     &#x22;2025-03-01T00:00:00Z&#x22;,
})
if err != nil { panic(err) }

fmt.Println(&#x22;Personality at 2025-03-01:&#x22;, snapshot.PersonalityAt)
fmt.Println(&#x22;Mood at 2025-03-01:&#x22;, snapshot.MoodAt)
for _, event := range snapshot.EvolutionEvents {
  fmt.Printf(&#x22;  %s: %v → %v\\n&#x22;, event.TraitName, event.OldValue, event.NewValue)
}`,
  },
]"
/>

<Callout type="info" title="How supersession works">
  When a fact is updated, the old record is retired (not deleted) and a new one is created with a `SupersedesID` pointer. The time machine replays this chain to reconstruct the state at any timestamp.
</Callout>

## Next Steps [#next-steps]

* Read the [Memory & Context](/docs/en/memory) reference for the full 7-level hierarchy
* Set up [Conversations](/docs/en/conversations) to handle multi-turn chat sessions with automatic session management
* Explore [Emotions & Mood](/docs/en/emotions) to understand how the agent's emotional state evolves with memory
* Add [Custom States](/docs/en/guides/tutorials/tutorial-custom-states) to store structured application data alongside memory


---

# Scheduled Reminders

Source: https://sonz.ai/docs/en/guides/tutorials/tutorial-scheduled-reminders

> Register recurring schedules that trigger proactive agent messages at specific times, with per-schedule timezones, quiet-hours filtering, and structured inventory linkage. Suitable for medication reminders, habit nudges, exercise check-ins, and any other recurring proactive event.



## What you'll build [#what-youll-build]

* A daily 09:00 Asia/Singapore check-in schedule that fires a proactive agent message every morning
* An every-4-hours schedule with a quiet-hours active window that skips fires outside allowed hours
* A bounded `interval_hours` course constrained by `starts_at` and `ends_at` — useful for multi-week programs
* An understanding of how the same primitive powers the full [Medication Reminders](./tutorial-medication-reminders) worked example

Scheduled Reminders are a first-class primitive: the platform recomputes `next_fire_at` after every fire, respects DST transitions automatically, and injects inventory context live at fire time so your agent always has current data.

## 1. Create a schedule [#1-create-a-schedule]

Register a schedule by calling `POST /api/v1/agents/{agentId}/users/{userId}/schedules`. The body describes *when* to fire (`cadence`), *what the agent should do* (`intent`), and optional scoping fields (`active_window`, `inventory_item_id`, `starts_at`, `ends_at`).

Here is a minimal daily 09:00 SGT check-in:

```json
{
  "cadence": {
    "simple": { "frequency": "daily", "times": ["09:00"] },
    "timezone": "Asia/Singapore"
  },
  "intent": "check in on how the user is feeling",
  "check_type": "reminder"
}
```

And a full example with all optional fields:

```json
{
  "cadence": {
    "simple": { "frequency": "daily", "times": ["09:00"] },
    "timezone": "Asia/Singapore"
  },
  "active_window": {
    "hours": { "start": "08:00", "end": "22:00" },
    "days_of_week": ["mon", "tue", "wed", "thu", "fri"]
  },
  "intent": "check in on how the user is feeling",
  "check_type": "reminder",
  "inventory_item_id": "01HX8F...",
  "metadata": { "campaign": "daily_checkin_v2" },
  "starts_at": "2026-05-01T00:00:00Z",
  "ends_at": "2026-05-14T23:59:59Z"
}
```

The response includes `schedule_id`, `next_fire_at` (UTC), and `next_fire_at_local` (the same instant expressed in the schedule's timezone — useful for displaying to the user).

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const AGENT_ID = &#x22;agent_abc&#x22;;
const USER_ID  = &#x22;user_123&#x22;;

const schedule = await client.schedules.create(AGENT_ID, USER_ID, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;09:00&#x22;] },
  timezone: &#x22;Asia/Singapore&#x22;,
},
intent: &#x22;check in on how the user is feeling&#x22;,
check_type: &#x22;reminder&#x22;,
});

console.log(schedule.schedule_id);      // &#x22;sched_01HX...&#x22;
console.log(schedule.next_fire_at);     // &#x22;2026-05-02T01:00:00Z&#x22;
console.log(schedule.next_fire_at_local); // &#x22;2026-05-02T09:00:00+08:00&#x22;`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])
AGENT_ID = &#x22;agent_abc&#x22;
USER_ID  = &#x22;user_123&#x22;

schedule = client.schedules.create(
  AGENT_ID,
  USER_ID,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;09:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
  },
  intent=&#x22;check in on how the user is feeling&#x22;,
  check_type=&#x22;reminder&#x22;,
)

print(schedule.schedule_id)         # &#x22;sched_01HX...&#x22;
print(schedule.next_fire_at)        # &#x22;2026-05-02T01:00:00Z&#x22;
print(schedule.next_fire_at_local)  # &#x22;2026-05-02T09:00:00+08:00&#x22;`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;encoding/json&#x22;
  &#x22;fmt&#x22;
  &#x22;os&#x22;
  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  ctx := context.Background()

  cadence, _ := json.Marshal(map[string]any{
      &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: []string{&#x22;09:00&#x22;}},
      &#x22;timezone&#x22;: &#x22;Asia/Singapore&#x22;,
  })

  schedule, err := client.Schedules.Create(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;,
      sonzai.CreateScheduleOptions{
          Cadence:   cadence,
          Intent:    &#x22;check in on how the user is feeling&#x22;,
          CheckType: &#x22;reminder&#x22;,
      },
  )
  if err != nil {
      panic(err)
  }
  fmt.Println(schedule.ScheduleID)      // &#x22;sched_01HX...&#x22;
  fmt.Println(schedule.NextFireAt)      // &#x22;2026-05-02T01:00:00Z&#x22;
  fmt.Println(schedule.NextFireAtLocal) // &#x22;2026-05-02T09:00:00+08:00&#x22;
}`,
  },
]"
/>

## 2. Cadence shapes [#2-cadence-shapes]

Two mutually exclusive shapes are supported: `simple` and `cron`. Exactly one must be present in the `cadence` object.

### Simple cadence [#simple-cadence]

| Field            | Type                                          | Required                 | Description                                                                 |
| ---------------- | --------------------------------------------- | ------------------------ | --------------------------------------------------------------------------- |
| `frequency`      | `"daily"` \| `"weekly"` \| `"interval_hours"` | Yes                      | Recurrence pattern                                                          |
| `times`          | `string[]`                                    | Yes for `daily`/`weekly` | Wall-clock times in `HH:MM` (24-hour), evaluated in the schedule's timezone |
| `days_of_week`   | `string[]`                                    | Yes for `weekly`         | `"mon"`, `"tue"`, `"wed"`, `"thu"`, `"fri"`, `"sat"`, `"sun"`               |
| `interval_hours` | `number`                                      | Yes for `interval_hours` | Minimum 1, maximum 24                                                       |
| `timezone`       | IANA string                                   | Yes                      | Applied to `times` and `days_of_week` evaluation                            |

A weekly schedule fires on the specified days at each listed time. A daily schedule fires every day at each listed time. An `interval_hours` schedule fires repeatedly at that interval starting from `starts_at` (or schedule creation if `starts_at` is omitted), bounded by the active window.

### Cron cadence [#cron-cadence]

| Field        | Type        | Required | Description                                      |
| ------------ | ----------- | -------- | ------------------------------------------------ |
| `expression` | `string`    | Yes      | Standard 5-field cron (`min hour dom month dow`) |
| `timezone`   | IANA string | Yes      | Cron fields are evaluated in this zone           |

Standard 5-field cron — no seconds field. Example: `"0 9 * * 1-5"` fires at 09:00 on weekdays.

<Callout type="warning">
  **Rate limits.** Cadences that resolve to more than one fire per minute are rejected with `CADENCE_TOO_FREQUENT`. Cadences that produce more than 96 raw ticks per 24-hour rolling window (before active-window filtering) are rejected with `CADENCE_TOO_DENSE`. For most use cases `interval_hours: 1` (24 raw ticks/day) is the densest practical setting.
</Callout>

## 3. Timezones [#3-timezones]

Every schedule requires a `timezone` field containing a valid IANA timezone name (e.g. `"Asia/Singapore"`, `"America/New_York"`, `"Europe/London"`). Offsets like `"+08:00"` are not accepted.

All cadence math — wall-clock time evaluation, `days_of_week` membership, DST skip logic — runs in the schedule's own timezone. The result is stored and returned as `next_fire_at` in UTC. `next_fire_at_local` is a convenience field that expresses the same instant with the zone offset applied.

When a user travels or changes their preferred timezone, patch the schedule timezone directly:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// User moved from Singapore to London
await client.schedules.update(AGENT_ID, USER_ID, scheduleId, {
cadence: {
  simple: { frequency: &#x22;daily&#x22;, times: [&#x22;09:00&#x22;] },
  timezone: &#x22;Europe/London&#x22;,
},
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# User moved from Singapore to London
client.schedules.update(
  AGENT_ID,
  USER_ID,
  schedule_id,
  cadence={
      &#x22;simple&#x22;: {&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: [&#x22;09:00&#x22;]},
      &#x22;timezone&#x22;: &#x22;Europe/London&#x22;,
  },
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `// User moved from Singapore to London
cadence, _ := json.Marshal(map[string]any{
  &#x22;simple&#x22;:   map[string]any{&#x22;frequency&#x22;: &#x22;daily&#x22;, &#x22;times&#x22;: []string{&#x22;09:00&#x22;}},
  &#x22;timezone&#x22;: &#x22;Europe/London&#x22;,
})
_, err = client.Schedules.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, scheduleID,
  sonzai.UpdateScheduleOptions{
      Cadence: cadence,
  },
)`,
  },
]"
/>

**DST handling.** On spring-forward transitions, a wall time that falls into the clocks-forward gap (e.g. 02:30 in a zone that jumps 02:00 → 03:00) is non-existent. The platform skips that occurrence and fires at the next valid occurrence. On fall-back transitions, a wall time that exists twice is never double-fired — the platform fires once and advances.

## 4. Active window (quiet hours + allowed days) [#4-active-window-quiet-hours--allowed-days]

The `active_window` field restricts which fires actually produce a proactive wakeup. Fires computed by the cadence that land outside the window are **skipped, not deferred** — the cadence grid stays perfectly predictable and no backlog accumulates.

```json
{
  "active_window": {
    "hours": { "start": "08:00", "end": "22:00" },
    "days_of_week": ["mon", "tue", "wed", "thu", "fri"]
  }
}
```

Both sub-fields are optional within `active_window`. You may specify `hours` only, `days_of_week` only, or both.

**Overnight windows.** When `start` is greater than `end`, the window wraps midnight. For example `{"start": "22:00", "end": "06:00"}` allows fires from 22:00 to 05:59 the next morning. This is useful for night-shift workers or schedules targeting early-morning time zones where local midnight matters.

**Allowed days.** Values must be lowercase three-letter abbreviations: `"mon"`, `"tue"`, `"wed"`, `"thu"`, `"fri"`, `"sat"`, `"sun"`. Day membership is evaluated in the schedule's timezone, so a fire at 23:30 Friday Singapore time stays Friday even when stored as 15:30 UTC (Saturday in some zones).

<Callout type="warning">
  **Empty days array.** Passing `"days_of_week": []` (an explicit empty list) is rejected with `INVALID_ACTIVE_WINDOW` — it would produce a schedule that can never fire. To allow all days, omit the `days_of_week` field entirely.
</Callout>

## 5. Linking an inventory item [#5-linking-an-inventory-item]

Pass `inventory_item_id` on the create (or patch) body to associate a schedule with a specific item from the user's resource inventory. The item's properties are injected **live at fire time** — not at schedule creation — so any mid-program updates to the item (e.g. a medication dosage change, a price update) are automatically reflected in the agent's proactive message without requiring any schedule modification.

```json
{
  "cadence": {
    "simple": { "frequency": "daily", "times": ["08:00"] },
    "timezone": "Asia/Singapore"
  },
  "intent": "remind the user to take their morning medication",
  "check_type": "reminder",
  "inventory_item_id": "01HX8FKZQ3..."
}
```

At fire time the platform fetches the current item properties and appends them to the intent block the agent receives. The [Medication Reminders](./tutorial-medication-reminders) tutorial shows a complete worked example including how to structure medication inventory items for maximum agent context.

**Graceful degradation.** If the referenced inventory item is deleted before a fire occurs, the schedule continues firing. The intent block is delivered without the `Reference item` section — the agent receives the `intent` and `metadata` fields as normal. No error is surfaced to the user; the schedule itself is not affected.

## 6. Bounded courses (starts\_at / ends\_at) [#6-bounded-courses-starts_at--ends_at]

Use `starts_at` and `ends_at` to create a time-bounded program. Both fields are optional and accept RFC 3339 UTC timestamps.

```json
{
  "cadence": {
    "simple": {
      "frequency": "interval_hours",
      "interval_hours": 4
    },
    "timezone": "Asia/Singapore"
  },
  "active_window": {
    "hours": { "start": "08:00", "end": "22:00" }
  },
  "intent": "prompt the user to log a pain score",
  "check_type": "check_in",
  "starts_at": "2026-05-01T00:00:00Z",
  "ends_at": "2026-05-14T23:59:59Z"
}
```

* **`starts_at`** — no fire is produced before this timestamp. Cadence expansion begins from this point. If omitted, the schedule starts immediately.
* **`ends_at`** — once this timestamp passes, the schedule is automatically disabled (`enabled` flips to `false`). The row is not deleted, so the audit trail and historical fire log remain accessible.

<Callout type="info">
  Passing `ends_at` that is less than or equal to `starts_at` returns `INVALID_WINDOW`. Passing a past `ends_at` at creation time also returns `INVALID_WINDOW` — a schedule that has already expired cannot be created.
</Callout>

## 7. Pausing, editing, deleting [#7-pausing-editing-deleting]

| Operation  | How                                                         | Behavior                                                                                                                  |
| ---------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Pause**  | `PATCH enabled: false`                                      | Schedule stops producing fires within 1 minute. `next_fire_at` is frozen.                                                 |
| **Resume** | `PATCH enabled: true`                                       | `next_fire_at` is recomputed from the current time. No backfill occurs for fires that were missed while paused.           |
| **Edit**   | `PATCH cadence`, `active_window`, `starts_at`, or `ends_at` | Changes take effect on the next expansion cycle (within \~1 minute). The current in-flight fire (if any) is not affected. |
| **Delete** | `DELETE /schedules/{id}`                                    | Hard delete. The row, all fire history, and all pending wakeups are removed immediately. This operation is irreversible.  |

Typical pause/resume flow:

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `// Pause
await client.schedules.update(AGENT_ID, USER_ID, scheduleId, { enabled: false });

// Resume — next_fire_at is recomputed from now
await client.schedules.update(AGENT_ID, USER_ID, scheduleId, { enabled: true });

// Delete
await client.schedules.delete(AGENT_ID, USER_ID, scheduleId);`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `# Pause
client.schedules.update(AGENT_ID, USER_ID, schedule_id, enabled=False)

# Resume — next_fire_at is recomputed from now
client.schedules.update(AGENT_ID, USER_ID, schedule_id, enabled=True)

# Delete
client.schedules.delete(AGENT_ID, USER_ID, schedule_id)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `enabled := false

// Pause
_, err = client.Schedules.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, scheduleID,
  sonzai.UpdateScheduleOptions{Enabled: &enabled},
)

// Resume
enabled = true
_, err = client.Schedules.Update(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, scheduleID,
  sonzai.UpdateScheduleOptions{Enabled: &enabled},
)

// Delete
err = client.Schedules.Delete(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, scheduleID)`,
  },
]"
/>

## 8. Preview upcoming fires [#8-preview-upcoming-fires]

`GET /api/v1/agents/{agentId}/users/{userId}/schedules/{id}/upcoming?limit=N` returns the next N computed fire times as an array of UTC timestamps. The preview applies the active window, so what you see is exactly what will fire.

For example, a 4-hourly schedule (`interval_hours: 4`) with an `08:00–22:00` active window produces at most 4 fires per calendar day (08:00, 12:00, 16:00, 20:00 local) — not 6 (which would be the raw cadence count before filtering). The preview array reflects this.

```json
[
  "2026-05-01T00:00:00Z",
  "2026-05-01T04:00:00Z",
  "2026-05-01T08:00:00Z",
  "2026-05-01T12:00:00Z"
]
```

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const upcoming = await client.schedules.upcoming(AGENT_ID, USER_ID, scheduleId, {
limit: 10,
});

for (const fireAt of upcoming) {
console.log(fireAt); // UTC ISO-8601 string
}`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `upcoming = client.schedules.upcoming(AGENT_ID, USER_ID, schedule_id, limit=10)

for fire_at in upcoming:
  print(fire_at)  # UTC ISO-8601 string`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `upcoming, err := client.Schedules.Upcoming(ctx, &#x22;agent_abc&#x22;, &#x22;user_123&#x22;, scheduleID, 10)
if err != nil {
  panic(err)
}
for _, fireAt := range upcoming.Upcoming {
  fmt.Println(fireAt) // UTC ISO-8601 string
}`,
  },
]"
/>

## 9. What the agent receives [#9-what-the-agent-receives]

When a schedule fires, the platform constructs a structured intent block and delivers it to the agent as a proactive wakeup. The block looks like this:

```
[PROACTIVE WAKEUP — SCHEDULED REMINDER]

Why you're reaching out: check in on how the user is feeling

Scheduled fire time (user's local): 2026-05-02T09:00:00+08:00

Reference item (from inventory): Daily Vitamin D
  dosage: 1000 IU
  form: softgel
  timing_notes: take with food

Additional context:
  campaign: daily_checkin_v2
```

Key points:

* **`[PROACTIVE WAKEUP — SCHEDULED REMINDER]`** — the stable header the agent detects to know it is initiating a conversation, not responding to one.
* **`Why you're reaching out`** — verbatim content of the `intent` field you set on the schedule. Write this as a short natural-language instruction to the agent. The agent composes the actual opening message **in its own voice** — no prompt template is exposed; you control intent, not wording.
* **`Scheduled fire time (user's local)`** — the `next_fire_at_local` value at fire time. Useful for agents that want to acknowledge the time explicitly ("Good morning" vs "Good afternoon").
* **`Reference item (from inventory)`** — present only if `inventory_item_id` was set and the item still exists. The item's `label` and all of its `properties` are included. Item properties are fetched live at fire time.
* **`Additional context`** — present only if `metadata` was set. All metadata key-value pairs are rendered here. Use this for campaign tracking, A/B variant labels, or any additional instruction to the agent that doesn't belong in the core intent.

There is no prompt template field. Clients control agent behavior through `intent`, `inventory_item_id`, and `metadata`. The agent is free to adapt its tone, greeting, and language based on the user's personality and the conversation history it already has.

## Error codes [#error-codes]

| Code                    | Meaning                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `CADENCE_AMBIGUOUS`     | Both `simple` and `cron` were provided. Exactly one is required.                                |
| `CADENCE_MISSING`       | Neither `simple` nor `cron` was provided.                                                       |
| `CADENCE_TOO_FREQUENT`  | Cadence resolves to more than one fire per minute.                                              |
| `CADENCE_TOO_DENSE`     | Cadence produces more than 96 raw ticks per 24-hour window.                                     |
| `INVALID_CRON`          | The cron expression is not a valid 5-field cron.                                                |
| `INVALID_TIMEZONE`      | The `timezone` value is not a recognized IANA timezone name.                                    |
| `INVALID_TIME`          | A value in `times` is not in `HH:MM` 24-hour format, or the time does not exist (e.g. DST gap). |
| `INVALID_DAY_OF_WEEK`   | A value in `days_of_week` is not one of the recognized three-letter abbreviations.              |
| `INVALID_ACTIVE_WINDOW` | `active_window` is structurally invalid — most commonly `days_of_week: []` (explicit empty).    |
| `INVALID_WINDOW`        | `ends_at` is not after `starts_at`, or `ends_at` is in the past.                                |
| `NO_ALLOWED_FIRE`       | The cadence + active\_window combination produces no reachable fires in the next 90 days.       |
| `INVENTORY_NOT_FOUND`   | The `inventory_item_id` does not exist in the user's inventory.                                 |

## Next steps [#next-steps]

* [Medication Reminders](./tutorial-medication-reminders) — a full worked example using Scheduled Reminders to drive a medication adherence program, including inventory schema design for medication items and multi-dose daily schedules.
* [Resource Inventory + Knowledge Base](./tutorial-inventory) — how to design inventory schemas and push live data, powering the `inventory_item_id` linkage described above.
* [Memory-Aware Chat](./memory) — how the agent remembers user responses from previous proactive conversations and incorporates them into future interactions.


---

# Enterprise Agents — Quickstart

Source: https://sonz.ai/docs/en/guides/quickstart/enterprise

> Build a workflow-aware AI agent for CRM, support, internal tools, or compliance. Multi-instance isolation, webhook-driven events, project-scoped knowledge base, eval runs, and audit-ready memory — in one pass.



<QuickstartBeacon audience="enterprise" />

This quickstart is for building **enterprise AI agents** — agents embedded
into business workflows. Think: CRM copilots, tier-1 support, internal
knowledge assistants, sales-qualification bots, compliance reviewers.

**What you'll build:** a sales-qualification agent that runs per-workspace,
receives deal events from your CRM via webhook, pulls from your product
docs, tracks workflow stage as custom state, and runs against eval rubrics
before each release.

**What you'll use:** multi-instance isolation, project-scoped knowledge base,
custom states, webhooks, tools, and evaluation runs.

## 1. Create project, API key, webhook secret [#1-create-project-api-key-webhook-secret]

In [platform.sonz.ai](https://platform.sonz.ai/dashboard/projects), create a
project and generate both an API key and a webhook signing secret. Enterprise
deployments usually scope API keys per environment (dev, staging, prod).

<CodeBlock language="bash">
  {`export SONZAI_API_KEY=sk_...
    export SONZAI_WEBHOOK_SECRET=whsec_...`}
</CodeBlock>

## 2. Create the agent [#2-create-the-agent]

Use a neutral, professional personality. Keep `neuroticism` low to avoid mood
drift affecting replies.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { Sonzai } from &#x22;@sonzai-labs/agents&#x22;;

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

const agent = await client.agents.create({
name: &#x22;Pilot-SDR&#x22;,
bio: &#x22;Pilot-SDR qualifies inbound leads, answers product questions, and hands off to humans when appropriate. Professional, concise, and never embellishes.&#x22;,
big5: {
  openness: 0.5,
  conscientiousness: 0.9,
  extraversion: 0.55,
  agreeableness: 0.65,
  neuroticism: 0.15,
},
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `from sonzai import Sonzai
import os

client = Sonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;])

agent = client.agents.create(
  name=&#x22;Pilot-SDR&#x22;,
  bio=&#x22;Pilot-SDR qualifies inbound leads, answers product questions, and hands off to humans when appropriate.&#x22;,
  big5={
      &#x22;openness&#x22;: 0.5,
      &#x22;conscientiousness&#x22;: 0.9,
      &#x22;extraversion&#x22;: 0.55,
      &#x22;agreeableness&#x22;: 0.65,
      &#x22;neuroticism&#x22;: 0.15,
  },
)`,
  },
  {
    id: &#x22;py-async&#x22;,
    label: &#x22;Python (async)&#x22;,
    code: `import asyncio, os
from sonzai import AsyncSonzai

async def main():
  async with AsyncSonzai(api_key=os.environ[&#x22;SONZAI_API_KEY&#x22;]) as client:
      agent = await client.agents.create(
          name=&#x22;Pilot-SDR&#x22;,
          bio=&#x22;Qualifies inbound leads, answers product questions.&#x22;,
          big5={&#x22;conscientiousness&#x22;: 0.9, &#x22;neuroticism&#x22;: 0.15},
      )
      print(agent.agent_id)

asyncio.run(main())`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `package main

import (
  &#x22;context&#x22;
  &#x22;os&#x22;

  sonzai &#x22;github.com/sonz-ai/sonzai-go&#x22;
)

func main() {
  client, err := sonzai.NewClient(os.Getenv(&#x22;SONZAI_API_KEY&#x22;))
  if err != nil {
      panic(err)
  }
  ctx := context.Background()

  agent, _ := client.Agents.Create(ctx, sonzai.CreateAgentOptions{
      Name: &#x22;Pilot-SDR&#x22;,
      Bio:  &#x22;Qualifies inbound leads, answers product questions.&#x22;,
      Big5: &sonzai.Big5Scores{Conscientiousness: 0.9, Neuroticism: 0.15},
  })
  _ = agent
}`,
  },
]"
/>

## 3. Create per-workspace instances [#3-create-per-workspace-instances]

Each customer workspace gets its own instance. Memory, custom state, and
notifications scoped to `instance_id = workspace-id` stay isolated — critical
for multi-tenant SaaS and compliance.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `const workspace = await client.agents.instances.create(&#x22;agent-id&#x22;, {
name: &#x22;acme-corp&#x22;,
description: &#x22;Workspace for Acme Corp account&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `workspace = client.agents.instances.create(
  &#x22;agent-id&#x22;,
  name=&#x22;acme-corp&#x22;,
  description=&#x22;Workspace for Acme Corp account&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `workspace, _ := client.Agents.Instances.Create(ctx, &#x22;agent-id&#x22;, &#x22;acme-corp&#x22;, &#x22;Workspace for Acme Corp account&#x22;)`,
  },
]"
/>

See [Multi-Instance](/docs/en/instances) for scoping patterns and lifecycle.

## 4. Upload product docs to the knowledge base [#4-upload-product-docs-to-the-knowledge-base]

Knowledge is project-scoped — every agent in the project searches the same
corpus. Upload PDFs, push structured entities, or both.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `import { readFileSync } from &#x22;node:fs&#x22;;

const pdf = readFileSync(&#x22;./product-one-pager.pdf&#x22;);
await client.knowledge.uploadDocument(&#x22;project-id&#x22;, &#x22;product-one-pager.pdf&#x22;, pdf, &#x22;application/pdf&#x22;);

// Or push structured facts
await client.knowledge.insertFacts(&#x22;project-id&#x22;, {
entities: [
  { label: &#x22;Plan: Growth&#x22;, properties: { price: 299, seats: 10 } },
  { label: &#x22;Plan: Enterprise&#x22;, properties: { price: &#x22;custom&#x22;, seats: &#x22;unlimited&#x22; } },
],
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `with open(&#x22;product-one-pager.pdf&#x22;, &#x22;rb&#x22;) as f:
  client.knowledge.upload_document(
      &#x22;project-id&#x22;,
      file_name=&#x22;product-one-pager.pdf&#x22;,
      file_data=f.read(),
      content_type=&#x22;application/pdf&#x22;,
  )`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `f, _ := os.Open(&#x22;product-one-pager.pdf&#x22;)
defer f.Close()
_, _ = client.Knowledge.UploadDocument(ctx, &#x22;project-id&#x22;, &#x22;product-one-pager.pdf&#x22;, f, &#x22;application/pdf&#x22;)`,
  },
]"
/>

## 5. Track workflow stage with custom state [#5-track-workflow-stage-with-custom-state]

Every deal or case lives in a stage. Store it as custom state so the agent
sees it on every turn and can reason about what comes next.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.agents.customStates.create(&#x22;agent-id&#x22;, {
key: &#x22;deal_stage&#x22;,
value: &#x22;discovery&#x22;,
scope: &#x22;per-user-instance&#x22;,
userId: &#x22;contact-email@acme.com&#x22;,
instanceId: workspace.instance_id,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.agents.custom_states.create(
  &#x22;agent-id&#x22;,
  key=&#x22;deal_stage&#x22;,
  value=&#x22;discovery&#x22;,
  scope=&#x22;per-user-instance&#x22;,
  user_id=&#x22;contact-email@acme.com&#x22;,
  instance_id=workspace.instance_id,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, _ = client.Agents.CustomState.Create(ctx, &#x22;agent-id&#x22;, sonzai.CustomStateCreateOptions{
  Key:        &#x22;deal_stage&#x22;,
  Value:      &#x22;discovery&#x22;,
  Scope:      &#x22;per-user-instance&#x22;,
  UserID:     &#x22;contact-email@acme.com&#x22;,
  InstanceID: workspace.InstanceID,
})`,
  },
]"
/>

## 6. Register handoff and CRM-sync tools [#6-register-handoff-and-crm-sync-tools]

Enterprise agents always need an escape hatch to humans plus write-back into
your system of record.

<CodeBlock language="typescript">
  {`await client.agents.sessions.setTools("agent-id", "session-id", [
    {
      name: "handoff_to_human",
      description: "Escalate this conversation to a human rep and stop the agent.",
      parameters: { type: "object", properties: { reason: { type: "string" } }, required: ["reason"] },
    },
    {
      name: "update_deal_stage",
      description: "Advance the deal to a new stage in the CRM.",
      parameters: {
        type: "object",
        properties: {
          stage: { type: "string", enum: ["discovery", "qualified", "demo", "proposal", "closed_won", "closed_lost"] },
        },
        required: ["stage"],
      },
    },
    ]);`}
</CodeBlock>

## 7. Register webhooks for CRM events [#7-register-webhooks-for-crm-events]

Push platform events into your stack. Each webhook subscribes to one event
type — register the events you care about. The agent sees these as "workflow
events" and reacts naturally on the next turn.

<CodeTabs
  tabs="[
  {
    id: &#x22;ts&#x22;,
    label: &#x22;TypeScript&#x22;,
    code: `await client.webhooks.register(&#x22;on_wakeup_ready&#x22;, {
webhookUrl: &#x22;https://api.yourcorp.com/sonzai/wakeups&#x22;,
});

await client.webhooks.register(&#x22;on_recurring_event_due&#x22;, {
webhookUrl: &#x22;https://api.yourcorp.com/sonzai/schedules&#x22;,
});`,
  },
  {
    id: &#x22;py&#x22;,
    label: &#x22;Python&#x22;,
    code: `client.webhooks.register(
  &#x22;on_wakeup_ready&#x22;,
  webhook_url=&#x22;https://api.yourcorp.com/sonzai/wakeups&#x22;,
)

client.webhooks.register(
  &#x22;on_recurring_event_due&#x22;,
  webhook_url=&#x22;https://api.yourcorp.com/sonzai/schedules&#x22;,
)`,
  },
  {
    id: &#x22;go&#x22;,
    label: &#x22;Go&#x22;,
    code: `_, _ = client.Webhooks.Register(ctx, &#x22;on_wakeup_ready&#x22;, sonzai.WebhookRegisterOptions{
  WebhookURL: &#x22;https://api.yourcorp.com/sonzai/wakeups&#x22;,
})

_, _ = client.Webhooks.Register(ctx, &#x22;on_recurring_event_due&#x22;, sonzai.WebhookRegisterOptions{
  WebhookURL: &#x22;https://api.yourcorp.com/sonzai/schedules&#x22;,
})`,
  },
]"
/>

Every webhook request is signed with HMAC-SHA256 — verify before acting.
See [Webhooks & Notifications](/docs/en/webhooks) for the full event
catalog, retry policy, and verification example.

## 8. Chat [#8-chat]

<CodeBlock language="typescript">
  {`for await (const event of client.agents.chatStream({
    agent: "agent-id",
    userId: "contact-email@acme.com",
    instanceId: workspace.instance_id,
    messages: [{ role: "user", content: "Which plan fits a team of 12?" }],
    })) {
    const delta = event.choices?.[0]?.delta?.content;
    if (delta) process.stdout.write(delta);
    }`}
</CodeBlock>

## 9. Gate releases on eval runs [#9-gate-releases-on-eval-runs]

Before shipping a prompt change or a new agent version, run it against an
eval rubric. Grade personality drift, factual accuracy, and tool-call
correctness.

<CodeBlock language="typescript">
  {`// Kick off a simulation + grading run, return immediately.
    const ref = await client.agents.runEvalAsync("agent-id", {
    templateId: "template_lead_qualification_v3",
    simulationConfig: { turnsPerScenario: 6 },
    });

    // Poll the run record once the eval finishes (or stream live via streamEvents).
    const result = await client.evalRuns.get(ref.runId);
    console.log(result.scoreOverall, result.scoresByCategory);`}
</CodeBlock>

See [Evaluation](/docs/en/guides/evaluation) for building rubrics and simulation
users.

## Next steps [#next-steps]

<Cards>
  <Card href="/docs/en/instances" title="Multi-Instance" description="Per-user and per-workspace isolation patterns in depth." />

  <Card href="/docs/en/webhooks" title="Webhooks" description="Full event catalog, HMAC verification, retry policy." />

  <Card href="/docs/en/knowledge-base" title="Knowledge Base" description="Document upload, entity schemas, semantic search." />

  <Card href="/docs/en/custom-tools" title="Custom Tools" description="Tool definitions and workflow action patterns." />

  <Card href="/docs/en/guides/evaluation" title="Evaluation" description="Rubrics, simulation, regression gating." />

  <Card href="/docs/en/reference" title="API Reference" description="Full REST API with every endpoint and schema." />
</Cards>

> Current SDK versions: TypeScript 1.1.3 · Python 1.1.4 · Go 1.2.0 (as of 2026-04-17)


---

# Account Config

Source: https://sonz.ai/docs/en/reference/api/accountconfig



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/account/config&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/account/config/{key}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/account/config/{key}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/account/config/{key}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Agents

Source: https://sonz.ai/docs/en/reference/api/agents



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/capabilities&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/capabilities&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/capabilities&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/effective-post-processing-model&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/fork&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/fork/status&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/post-processing-model&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/profile&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/project&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/status&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools/{toolName}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools/{toolName}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Analytics

Source: https://sonz.ai/docs/en/reference/api/analytics



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/analytics/composio&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/analytics/cost&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/analytics/cost/breakdown&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/analytics/overview&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/analytics/realtime&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/analytics/usage&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# A P I Keys

Source: https://sonz.ai/docs/en/reference/api/apikeys



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/keys&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/keys&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/keys/{keyId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


---

# Approvals

Source: https://sonz.ai/docs/en/reference/api/approvals



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/approvals&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/approvals&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/approvals/{id}/resolve&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Built in Agents

Source: https://sonz.ai/docs/en/reference/api/built-in-agents



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/builtin-agents&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead/enrich&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead/enrich&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead/enrich/{jobId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/calibration&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/model&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/model/train&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/nba&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/outcome&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/reset-learning&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/rl/policy&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/lead_score/rl/train&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/learning&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/feedback&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/nba/decide&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/nba/learn&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/ope/evaluate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/scoring/predict&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/scoring/train&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/simulate-rounds&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/simulate-rounds/stream&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/onboard&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/sessions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/sessions&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/sessions/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/sessions/{id}/messages&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/vertical&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/vertical&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/{slug}/guidance&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/{slug}/guidance/rollback&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/{slug}/invoke&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/{slug}/learn&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/contact_timing/suggest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/ev&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/forecast&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ml/handoff/suggest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/lookalike/rank&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ml/lookalike/score&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/offers/suggest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/revival-queue&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ml/revival-queue/compute&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/winloss/generate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/winloss/latest&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Catalog

Source: https://sonz.ai/docs/en/reference/api/catalog



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/bookings&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/bookings&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/bookings/{bookingId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/bookings/{bookingId}/cancel&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/bookings/{bookingId}/confirm&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/import&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/sync&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/{itemId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/{itemId}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/{itemId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/{itemId}/slots&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/{itemId}/slots&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/items/{itemId}/status&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/schemas&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/schemas&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/schemas/{schemaId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/schemas/{schemaId}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/schemas/{schemaId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/slots/{slotId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/slots/{slotId}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/catalog/slots/{slotId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


---

# Channel Connections

Source: https://sonz.ai/docs/en/reference/api/channelconnections



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/channel-connections&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channel-connections&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channel-connections/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channel-connections/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channel-connections/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channel-connections/{id}/test&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Chat

Source: https://sonz.ai/docs/en/reference/api/chat



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/chat&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Composio

Source: https://sonz.ai/docs/en/reference/api/composio



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/composio/audit&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/composio/available_actions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/composio/connections&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/composio/connections&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/composio/connections/callback&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/composio/connections/{app}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


---

# Constellation

Source: https://sonz.ai/docs/en/reference/api/constellation



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/constellation&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/constellation/nodes&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/constellation/nodes/{nodeId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/constellation/nodes/{nodeId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Context

Source: https://sonz.ai/docs/en/reference/api/context



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/context&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/context-bundle&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Conversations

Source: https://sonz.ai/docs/en/reference/api/conversations



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/conversations&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/conversations&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/conversations/push&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/conversations/stream&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}/messages&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}/messages&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}/read&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}/takeover&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/conversations/{id}/takeover&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


---

# Custom Agents

Source: https://sonz.ai/docs/en/reference/api/custom-agents



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/custom-agents&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/custom-agents&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/custom-agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/custom-agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/custom-agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Custom States

Source: https://sonz.ai/docs/en/reference/api/custom-states



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states/by-key&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states/by-key&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states/by-key&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states/{stateId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/custom-states/{stateId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Diary

Source: https://sonz.ai/docs/en/reference/api/diary



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/diary&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Enrichment

Source: https://sonz.ai/docs/en/reference/api/enrichment



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/enrichment/person&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Evals

Source: https://sonz.ai/docs/en/reference/api/evals



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/eval-only&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/evaluate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/run-eval&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/simulate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/api/v1/workbench/checkpoint-evaluate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/eval-runs&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/eval-runs/{runId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/eval-runs/{runId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/eval-runs/{runId}/events&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/eval-templates&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/eval-templates&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/eval-templates/{templateId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/eval-templates/{templateId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/eval-templates/{templateId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Events

Source: https://sonz.ai/docs/en/reference/api/events



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/events&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Goals

Source: https://sonz.ai/docs/en/reference/api/goals



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/breakthroughs&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/goals&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/goals&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/goals/{goalId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/goals/{goalId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Grounding

Source: https://sonz.ai/docs/en/reference/api/grounding



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/grounding/availability&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/grounding/items/{itemId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/grounding/query&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Habits

Source: https://sonz.ai/docs/en/reference/api/habits



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/habits&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/habits&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/habits/{habitName}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/habits/{habitName}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Ingest

Source: https://sonz.ai/docs/en/reference/api/ingest



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/ingest/contacts&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ingest/events&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ingest/events&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Insights

Source: https://sonz.ai/docs/en/reference/api/insights



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/personality/recent-shifts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/personality/significant-moments&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/personality/users&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/personality/users/{userId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/timemachine&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Instances

Source: https://sonz.ai/docs/en/reference/api/instances



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/instances&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/instances&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/instances/{instanceId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/instances/{instanceId}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/instances/{instanceId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/instances/{instanceId}/reset&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Interests

Source: https://sonz.ai/docs/en/reference/api/interests



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/interests&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Inventory

Source: https://sonz.ai/docs/en/reference/api/inventory



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/inventory&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/inventory&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/inventory/batch&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/inventory/items&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/inventory/{factId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/inventory/{factId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Jobs

Source: https://sonz.ai/docs/en/reference/api/jobs



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/jobs&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/jobs&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/jobs/{jobId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/jobs/{jobId}/cancel&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Knowledge Org

Source: https://sonz.ai/docs/en/reference/api/knowledge-org



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}/promote-to-org&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{tenantId}/knowledge/org-nodes&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{tenantId}/knowledge/org-nodes&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Knowledge

Source: https://sonz.ai/docs/en/reference/api/knowledge



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/conversions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/feedback&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rankings&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/recommendations&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rules&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rules&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rules/{ruleId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rules/{ruleId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rules/{ruleId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/rules/{ruleId}/run&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/analytics/trends&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/bulk-update&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/compare&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents/{docId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents/{docId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents/{documentId}/classification&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents/{documentId}/cost&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/documents/{documentId}/reingest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/entities/{entityType}/{entityKey}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/facts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/facts&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/facts/active&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/facts/history&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/multimodal-schemas&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/multimodal-schemas&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/multimodal-schemas/{version}/activate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}/agent-delete&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}/history&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/nodes/{nodeId}/promote-to-org&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/schemas&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/schemas&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/schemas/{schemaId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/schemas/{schemaId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/search&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/stats&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/knowledge/traverse&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{tenantId}/knowledge/org-nodes&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{tenantId}/knowledge/org-nodes&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Lead Assignments

Source: https://sonz.ai/docs/en/reference/api/lead-assignments



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/lead-assignments&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/lead-assignments/offer&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/lead-assignments/{assignmentId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/lead-assignments/{assignmentId}/claim&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/lead-assignments/{assignmentId}/complete&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/lead-assignments/{assignmentId}/release&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# M C P

Source: https://sonz.ai/docs/en/reference/api/mcp



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/probe&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/{id}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/{id}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/{id}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/{id}/probe&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/{id}/tools&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/mcp/catalog/{id}/usages&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Memory

Source: https://sonz.ai/docs/en/reference/api/memory



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/consolidate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/fact/{factId}/history&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/facts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/facts&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/facts/bulk&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/facts/{factId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/facts/{factId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/search&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/summaries&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/timeline&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/wisdom/audit/{factId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/memory/wisdom/{factId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/conversations&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/facts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# M L

Source: https://sonz.ai/docs/en/reference/api/ml



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/feedback&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/nba/decide&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/nba/learn&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/ope/evaluate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/scoring/predict&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/scoring/train&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/simulate-rounds&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/builtin-agents/ml/{use_case}/simulate-rounds/stream&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/contact_timing/suggest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/ev&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/forecast&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ml/handoff/suggest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/lookalike/rank&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ml/lookalike/score&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/offers/suggest&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/revival-queue&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/ml/revival-queue/compute&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/winloss/generate&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/ml/winloss/latest&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# M L Models

Source: https://sonz.ai/docs/en/reference/api/mlmodels



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/models/{useCase}/export&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Models

Source: https://sonz.ai/docs/en/reference/api/models



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/models&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/models&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Mood

Source: https://sonz.ai/docs/en/reference/api/mood



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/mood&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/mood&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/mood-history&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/mood/aggregate&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Notification Channels

Source: https://sonz.ai/docs/en/reference/api/notification-channels



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/channels&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/channels&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/channels/deliver&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/channels/{channelId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/channels/{channelId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/channels/{channelId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channels&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channels&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channels/deliver&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channels/{channelId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channels/{channelId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/channels/{channelId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Notifications

Source: https://sonz.ai/docs/en/reference/api/notifications



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/notifications&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/notifications/history&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/notifications/{messageId}/consume&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/notifications&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/notifications/acknowledge&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/notifications/acknowledge-all&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Onboarding

Source: https://sonz.ai/docs/en/reference/api/onboarding



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/onboarding/bootstrap&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/onboarding/claim&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/onboarding/claim-link&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/onboarding/preferred-organization&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/onboarding/workspace-organization&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Org Billing

Source: https://sonz.ai/docs/en/reference/api/orgbilling



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/org/billing&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/billing/checkout&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/org/billing/portal&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/org/characters&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/contract&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/contract/subscribe&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/org/events&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/ledger&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/model-pricing&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/service-agreements&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/service-usage&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/usage-summary&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/org/vouchers/redeem&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/usage/reports&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Personality

Source: https://sonz.ai/docs/en/reference/api/personality



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/personalities/batch&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/personality&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/personality&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Pipelines

Source: https://sonz.ai/docs/en/reference/api/pipelines



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/pipelines&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/pipelines&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/pipelines/{pipelineId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/pipelines/{pipelineId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/pipelines/{pipelineId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/pipelines/{pipelineId}/steps&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Priming

Source: https://sonz.ai/docs/en/reference/api/priming



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/import&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/import/{jobId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/import/{jobId}/users&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/imports&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/content&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/metadata&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/metadata&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/prime&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/prime/{jobId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Process

Source: https://sonz.ai/docs/en/reference/api/process



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/process&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Project Config

Source: https://sonz.ai/docs/en/reference/api/projectconfig



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/config&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/config/{key}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/config/{key}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/config/{key}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Projects

Source: https://sonz.ai/docs/en/reference/api/projects



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Relationship Depth

Source: https://sonz.ai/docs/en/reference/api/relationship-depth



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/contacts/{contactId}/depth&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/depth-distribution&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/at-risk&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/cohorts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/depth-scores&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/fleet-activity&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/moat&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/moat-index&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/pipeline-flow&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Relationships

Source: https://sonz.ai/docs/en/reference/api/relationships



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/relationships&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Routing

Source: https://sonz.ai/docs/en/reference/api/routing



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/permanent-routes&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/permanent-routes&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/permanent-routes/{userId}/override&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/routing-config&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/routing-config&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Runtime

Source: https://sonz.ai/docs/en/reference/api/runtime



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/runtime/backend-agent-artifacts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Schedules

Source: https://sonz.ai/docs/en/reference/api/schedules



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/schedules&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/schedules&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/schedules/{scheduleId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/schedules/{scheduleId}&#x22;,&#x22;method&#x22;:&#x22;patch&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/schedules/{scheduleId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/users/{userId}/schedules/{scheduleId}/upcoming&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Sessions

Source: https://sonz.ai/docs/en/reference/api/sessions



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/sessions/end&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/sessions/start&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/sessions/{sessionId}/tools&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/sessions/end/status/{processingId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Skills

Source: https://sonz.ai/docs/en/reference/api/skills



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/skills/enabled&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/skills/enabled&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/skills/enabled/{skillName}/load-count&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/skills&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/skills&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/skills/{name}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/skills/{name}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/skills/{name}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Storefront

Source: https://sonz.ai/docs/en/reference/api/storefront



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/storefront&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/storefront&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/storefront/agents&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/storefront/agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/storefront/agents/{agentId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/storefront/publish&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/storefront/unpublish&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Support

Source: https://sonz.ai/docs/en/reference/api/support



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/support/tickets&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/support/tickets&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/support/tickets/{ticketId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/support/tickets/{ticketId}/close&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/support/tickets/{ticketId}/comments&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Tenant

Source: https://sonz.ai/docs/en/reference/api/tenant



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/tenant/deployment&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenant/deployment/upgrade-request&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Tenant Host

Source: https://sonz.ai/docs/en/reference/api/tenanthost



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/runtime/manifest&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/runtime/widget-consent&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/runtime/widget-origins&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/tenant/domains&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/domains&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/domains&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/domains/{domain}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/domains/{domain}/verify&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/integrations/{name}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/manifest&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/manifest&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/profile&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{id}/workspace-session&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Tenants

Source: https://sonz.ai/docs/en/reference/api/tenants



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/tenants&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/tenants/{tenantId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Tools

Source: https://sonz.ai/docs/en/reference/api/tools



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools/kb-search&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools/kb-search&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/tools/schemas&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Turn

Source: https://sonz.ai/docs/en/reference/api/turn



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/sessions/{sessionId}/turn&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/turns&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/turns/{extractionId}/status&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# User Personas

Source: https://sonz.ai/docs/en/reference/api/userpersonas



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/user-personas&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/user-personas&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/user-personas/{personaId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/user-personas/{personaId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/user-personas/{personaId}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;}]" />


---

# Users

Source: https://sonz.ai/docs/en/reference/api/users



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/users&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/me&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Voice

Source: https://sonz.ai/docs/en/reference/api/voice



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/voice/live-ws-token&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/voice/stt&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/voice/tts&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/voices&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />


---

# Wakeups

Source: https://sonz.ai/docs/en/reference/api/wakeups



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/wakeups&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wakeups&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Webhooks

Source: https://sonz.ai/docs/en/reference/api/webhooks



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/projects/{projectId}/webhooks&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/webhooks/{eventType}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/webhooks/{eventType}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/webhooks/{eventType}/attempts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/projects/{projectId}/webhooks/{eventType}/rotate-secret&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/webhooks&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/webhooks/{eventType}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/webhooks/{eventType}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/webhooks/{eventType}/attempts&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/webhooks/{eventType}/rotate-secret&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Wisdom

Source: https://sonz.ai/docs/en/reference/api/wisdom



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/attributed&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/attributed&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/attributed/import&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/attributed/{entityType}/{entityId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/attributed/{entityType}/{entityId}/{category}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/attributed/{entityType}/{entityId}/{category}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/audit&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/relations&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/relations&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/agents/{agentId}/wisdom/relations/{relationId}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;}]" />


---

# Workbench

Source: https://sonz.ai/docs/en/reference/api/workbench



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/workbench/advance-time&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/advance-time/jobs/{jobId}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/workbench/chat&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/generate-bio&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/generate-character&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/generate-seed-memories&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/prepare&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/reset-agent&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/session-end&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/simulate-user&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workbench/state&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />


---

# Workspace Users

Source: https://sonz.ai/docs/en/reference/api/workspaceusers



{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

<APIPage document="&#x22;openapi&#x22;" webhooks="[]" operations="[{&#x22;path&#x22;:&#x22;/workspace-users&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/workspace-users&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workspace-users/bulk&#x22;,&#x22;method&#x22;:&#x22;post&#x22;},{&#x22;path&#x22;:&#x22;/workspace-users/{uid}&#x22;,&#x22;method&#x22;:&#x22;delete&#x22;},{&#x22;path&#x22;:&#x22;/workspace-users/{uid}&#x22;,&#x22;method&#x22;:&#x22;put&#x22;},{&#x22;path&#x22;:&#x22;/workspace-users/{uid}/reset-password&#x22;,&#x22;method&#x22;:&#x22;post&#x22;}]" />