Sonzai Documentation

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

What you can build with it

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

Quickstart

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

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

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

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

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

Core concepts

What fires when time advances

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

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

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

Deterministic state transitions

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

Async mode for long windows

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

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

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

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

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

Time granularity

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

Full API

advanceTime options

Combines with other features

With Scheduled Reminders — fast-forwarding pending reminders

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

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

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

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

With Memory / Diary — replay compressed history

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

With Wakeups — time-travel scheduled wakeups

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

Tutorials

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

Next steps

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

Also useful for evaluation

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

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

What you can build with it

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

Quickstart

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

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

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

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

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

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

Core concepts

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

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

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

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

Full API

Read endpoints

Write endpoints (goals and habits)

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

Habits

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

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

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

Goals

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

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

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

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

Interests

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

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

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

Relationships

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

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

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

Diary

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

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

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

Constellation

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

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

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

Breakthroughs

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

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

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

Combines with other features

With Memory — insights are summaries over raw facts

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

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

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

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

With Emotions — mood + insights for a full user picture

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

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

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

With Advance Time — replay insight formation

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

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

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

Tutorials

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

系统概览

心智层是一个独立平台，将智能体的智能（人格、记忆、情绪）与您的应用逻辑分离。任何后端都可以通过 REST API 或官方 SDK 进行集成。

您的后端                        心智层平台
   |                                  |
   |--- 创建智能体 ------------------>|
   |<-- 智能体 ID + 档案 ------------|
   |                                  |
   |--- 聊天 (SSE 流式) ------------>|
   |    (消息 + 应用上下文)           |-- 构建上下文
   |<-- 流式 AI 响应 ----------------|-- 流式 AI 响应
   |                                  |-- 更新记忆、情绪、人格
   |<-- 主动通知 --------------------|   (自动完成，无需额外调用)

集成架构

典型部署包含三个协同工作的层级：

平台管理的内容

每次聊天调用时，平台会自动从人格、记忆、情绪和关系数据中组装相关上下文，然后生成 AI 响应。对话后的状态更新自动完成 — 无需额外的 API 调用。

数据所有权

心智层和您的后端各自拥有不同的数据：

心智层拥有

• 智能体人格档案
• 记忆事实和摘要
• 情绪状态（快乐、精力、平静、亲密）
• 人格演化历史
• 习惯和目标
• 关系叙事
• 知识库实体和图谱
• 自定义智能体状态

您的后端拥有

• 用户认证
• 业务逻辑和工作流
• 用户档案和偏好
• 应用数据和状态
• 计费和订阅
• 权限和访问控制
• 会话管理

会话生命周期

1. 用户开始聊天
 您的后端准备应用上下文（用户数据、偏好...）

2. 对话进行
 您的后端 ---> Chat SDK 调用（上下文 + 消息）
 用户 <--- 流式 AI 响应 token

3. 对话结束
 平台更新：记忆、情绪、人格、习惯、关系

4. 会话间隔期
 平台运行：后台整合、情绪衰减、主动唤醒

后台处理与自我改进

平台不仅响应 chat 调用——它运行一个持续的后台管道，使记忆保持准确性、行为状态保持连贯性，并随时间提升检索质量。每个循环都自动运行；你方面无需调度或配线。

有关每个机制的完整说明——包括可逆去重、话题转换检测、性格漂移安全上限、突破和谨慎部署系统——请参阅智能体如何随时间变得更聪明。

SDK 集成点

使用官方 SDK 与平台的每个部分交互：

• 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

你将应用指向 client.agents.chat（或用 sessions.start → 聊天回合 → sessions.end 显式打开会话）。Sonzai 从智能体身份组装系统提示词，召回相关记忆，运行 LLM， 流式返回 token，执行已注册的工具，并更新状态 — 全部在一次调用中完成。 这是代码量最少的模式。 适用于陪伴、客服智能体，以及任何可以让 Sonzai 拥有完整智能体循环的场景，是默认推荐的路径。

何时使用

• 你希望每回合一次 HTTP 调用，零记忆管线代码。
• 你接受 Sonzai 选择（或通过覆盖参数指定）LLM 提供商。
• 你希望人格、情绪、记忆、语音、知识库搜索、主动通知等"开箱即用"， 不必自己编排。

何时切换

• 必须使用自己的 LLM — 切换到 模式 4：独立实时。
• 对话已在平台外发生（录音、转录、批量摄入）— 切换到 模式 5：独立批处理。
• 运行在 Claude Desktop / Cursor / 兼容 MCP 的 IDE 中 — 切换到 模式 2：MCP。
• 已使用 OpenClaw — 切换到 模式 3：OpenClaw。

架构

┌─────────────┐     ┌───────────────────────────────────┐
│  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

端到端示例

最简完整流程：显式打开会话、驱动流式聊天、结束会话。

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

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

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

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

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

下一步

心智层提供了一个托管的 Streamable HTTP MCP 端点： https://api.sonz.ai/mcp/memory/{agent_id}。把任意兼容 MCP 的客户端 指向它，再带上 Sonzai API 密钥即可 — 34 个工具、4 个资源、 3 个引导式提示词。无需本地二进制、无需开放 SSE 端口、无需 Go 工具链。

何时使用

• 用户已经在 Claude Code、Cursor、Claude Desktop、ChatGPT 或其他 MCP 兼容客户端里。
• 你希望靠对话驱动 Sonzai，而不是写 SDK 代码。
• 你在原型阶段 — 选 create-companion 或 mind-layer-setup 引导提示词， 完全不写代码也能跑起来。

何时切换

• 构建自己的产品 UI — 切换到 模式 1：托管运行时。
• 想让 Sonzai 进入自己的 LLM 循环，而不是作为别人 LLM 的工具 — 切换到 模式 4：独立实时。

架构

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

端到端示例

需要从 项目仪表板 取得 项目 API 密钥并准备好一个 agent ID。选你的客户端，粘贴片段就完成配置。

# 一行命令注册托管 MCP 服务器：
claude mcp add --transport http sonzai \
https://api.sonz.ai/mcp/memory/AGENT_ID \
--header "Authorization: Bearer $SONZAI_API_KEY"

# 然后在任何 Claude Code 会话中直接说：
#   "Chat with agent 'Luna' and say 'I had a great day hiking today!'"
#   "Search Luna's memories about hiking adventures"
#   "Use mind-layer-setup with assistant_name 'Aria' …"

下一步

OpenClaw 是一个开源对话式 AI 智能体框架，使用基于槽位的插件系统。决定每次系统提示词中包含哪些上下文 的槽位叫 contextEngine。安装 @sonzai-labs/openclaw-context 后会以 "sonzai" 名称注册 Sonzai 上下文引擎 — 在 openclaw.json 中把它 分配给该槽位，每次对话就会经过心智层，无需任何额外代码。

何时使用

• 你已经在 OpenClaw 上开发，或团队已经标准化在 OpenClaw 上。
• 你希望保留 OpenClaw 现有的聊天循环、遥测和工具插件 — 仅替换记忆/人格层。
• 你希望在每个回合的系统提示词里自动注入一段 <sonzai-context>，按优先级排序、按 token 预算裁剪。

何时切换

• 不在 OpenClaw 上 — 切换到 模式 1：托管运行时（我们跑聊天）或 模式 4：独立实时（你跑聊天）。
• 完全没有实时聊天 — 切换到 模式 5：独立批处理。

架构

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

端到端示例

OpenClaw 插件本身只支持 JavaScript（OpenClaw 是 JS 框架）。Python 与 Go 分支展示等价的 B2B 配置流程：通过 SHA1 推导出确定性的 agent UUID 并 写入 OpenClaw 配置 — 真正消费这份配置的运行时仍是 JS。

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

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

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

下一步

你拥有完整对话。Sonzai 永远看不到实时过程。当对话结束 — 通话挂断、客服 工单关闭、日志会话写完 — 你一次性 POST 整段记录，Sonzai 的提取器会把它 转成事实、情绪更新、人格漂移、习惯检测和主动外联信号。最适合辅导、健身、 CRM、语音通话、写日记，以及任何让 Sonzai 处于热路径既不可取也不可行的 流程。

何时使用

• 延迟预算无法承受每个回合一次 /turn 往返。
• 记录已经存在（录音、Gong/Zoom 导出、日记内容）。
• 你想事后批量摄入 — 回放日志、迁移用户、给智能体质量做基准测试。

何时切换

• 你想要每回合的新鲜上下文 — 模式 4：独立实时。
• 可以接受连 LLM 调用也交给 Sonzai — 模式 1：托管运行时。

架构

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│  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, …)     │                       │
     └─────────────────────┴───────────────────────┘

端到端示例

最简路径是 /process：一次调用、自动建会话、返回生成的 session_id 便于关联。当你需要会话级工具、时长、或异步轮询时，再使用显式 sessions.start → end({ messages }) 生命周期。

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

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

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

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

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

下一步

你保留现有的聊天循环。每次调用 LLM 之前，向 Sonzai 拉取与用户消息相关的 丰富上下文；LLM 回复之后，仅把这次交换提交给 session.turn()。情绪在 ~300–500 ms 内同步落地。更深入的提取 — 事实、人格漂移、习惯检测、目标 更新 — 在背景里异步跑 5–15 秒。Sonzai 永远看不到你的工具执行，也永远 不替你选模型。

适合陪伴、语音智能体、智能体框架（OpenAI Agents SDK、LangChain、LiveKit） 以及任何在采用 Sonzai 之前就已经有生产级 LLM 循环的场景。

何时使用

• 你已经有生产环境里的 LLM 循环 —— 自定义工具、评估、提示词模板，或者锁定的 特定提供商。
• 你需要每回合的新鲜上下文，而不是整段对话只拉一次。
• 你想要情绪、事实、人格、习惯、目标和关系信号 — 而不放弃对 LLM 选择和 工具执行的控制权。

何时切换

• 一段对话来不及等每次 .turn() 同步返回 — 切换到 模式 5：独立批处理。
• 可以接受 Sonzai 持有 LLM 调用 — 切换到 模式 1：托管运行时，删掉绝大多数代码。

架构

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│  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 extract  │
     │                     │   (5–15s)             │
     │                     │                       │
     │  ─── Repeat ────────────────────────────── │
     │                     │                       │
     │  session.end()      │                       │
     │────────────────────>│── consolidate         │
     │                     │   long-term memory    │
     └─────────────────────┴───────────────────────┘

端到端示例

最小可运行的循环：开会话；每个回合拉上下文、调你的 LLM、提交交换； 结束时关闭会话。

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

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 }[] = [];

// 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,
  provider: "gemini",
  model:    "gemini-3.1-flash-lite-preview",
});

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

  // 2. Your LLM, your tools — Sonzai is OUT of the loop here.
  const reply = await yourLLM.chat({
    system:   buildSystemPrompt(ctx),
    messages: [...history, { role: "user", content: userMessage }],
  });

  sendToUser(reply.content);

  // 3. Submit the exchange. Sync mood ~300ms; deeper extraction
  //    (facts, personality, habits) runs asynchronously 5–15s later.
  await session.turn({
    messages: [
      { role: "user",      content: userMessage },
      { role: "assistant", content: reply.content },
    ],
  });

  history.push({ role: "user",      content: userMessage });
  history.push({ role: "assistant", content: reply.content });
  return reply.content;
}

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("\n");
return [
  ctx.personality_prompt ?? "You are a helpful AI companion.",
  `Personality (Big5): ${JSON.stringify(ctx.big5 ?? {})}`,
  `Current mood: ${JSON.stringify(ctx.current_mood ?? {})}`,
  facts ? `Relevant memories:\n${facts}` : "",
].filter(Boolean).join("\n\n");
}

下一步

会话流程

每段对话遵循简单的三步生命周期：

1. 发送聊天请求   — 传入智能体 ID、用户 ID、应用上下文和消息
2. 接收流式响应  — 实时将 token 渲染给用户
3. 平台自动更新  — 记忆、情绪、关系和人格自动演化

聊天（非流式）

对于简单的请求-响应流程，使用标准聊天方法。

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

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

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

console.log(response.content);

聊天（流式）

以流式方式接收 token，获得更流畅的体验。底层使用服务器发送事件（SSE）。

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

聊天选项

max_turns

限制智能体在单次聊天调用中产生的助手轮次数量。适用于控制多消息响应——智能体可能会发送后续消息。

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "Tell me about your week" }],
userId: "user-123",
maxTurns: 3,   // 智能体最多产生 3 条助手消息
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

应用上下文

每次请求传入应用状态，让智能体在对话中可以引用它。平台不缓存此状态——每次聊天调用都要发送。

// 将每次请求的状态嵌入 compiledSystemPrompt——平台不缓存它。
const appState = [
"Department: Engineering",
"Current task: Q2 roadmap review",
"Open tickets: 12",
"Role: Senior Developer",
].join("\n");

for await (const event of client.agents.chatStream({
agent:    "agent-id",
messages: [{ role: "user", content: "What should I do next?" }],
userId:   "user-123",
compiledSystemPrompt: appState,
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

平台管理的状态更新

每次交互后，平台自动处理以下内容。无需额外的 API 调用。

• 记忆提取：从对话中提取事实、事件和承诺。
• 情绪更新：检测到的情感主题推动情绪维度变化。
• 人格演化：基于交互模式的渐进式大五变化。
• 习惯追踪：反复出现的模式成为被追踪的习惯。
• 关系更新：更新化学反应和关系叙事。
• 目标进展：记录活跃目标上的进展。

多智能体对话

使用对话 API 编排多个智能体之间的对话，或让智能体在没有直接用户消息的情况下响应共享场景上下文。

const response = await client.agents.dialogue("agent-id", {
userId: "user-123",
messages: [
  { role: "user", content: "Tell the group about your weekend plans" },
],
sceneGuidance: "A casual team standup meeting",
});

console.log(response.content);

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "Show me a sunset!" }],
userId: "user-123",
tools: ["generate_image"],
})) {
if (event.type === "image") {
  console.log("Generated image:", event.imageUrl);
}
}

实际应用

三类受众的聊天形式相同——区别在于你传入什么以及如何处理流式数据。

for await (const event of client.agents.chatStream({
  agent: "agent-id",
  userId: "user-123",
  messages: [{ role: "user", content: "I'm having a rough day." }],
  maxTurns: 3,
})) {
  if (event.type === "message_boundary") newBubble();
  else renderDelta(event);
}

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

What you can build with it

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

Quickstart

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

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

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

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

Core concepts

Typed values

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

Scoping model

Agent reads and writes

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

Distinct from Inventory

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

Full API

Create

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

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

Upsert (create or update by key)

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

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

Get by key

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

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

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

List

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

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

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

Update by state ID

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

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

Delete

Delete by state ID or by composite key.

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

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

Method summary

Combines with other features

With Custom Tools — tools that read and write state

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

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

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

With Inventory — when state is structured, use inventory

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

With Sessions — session-scoped vs persistent state

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

Tutorials

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

Next steps

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

What you can build with it

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

Quickstart

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

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

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

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

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

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

Core concepts

Built-In Tools (Capabilities)

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

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

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

customTools in agent capabilities

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

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

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

Tool scoping

Full API

Custom Tools (Agent-Level)

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

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

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

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

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

Session-Level Tools (temporary)

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

Option 1 — Set for an existing session

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

Option 2 — Pass inline with the chat call

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

Handling Tool Calls

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

1. Receive the tool call

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

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

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

2. Execute and return results

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

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

In Practice

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

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

Combines with

Custom State — what tools often act on

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

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

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

Sessions — session-scoped vs persistent tools

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

Conversations — tool calls in the message stream

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

Tutorials

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

Next steps

情绪维度

每个智能体-用户对都有一个情绪状态，包含四个 0-100 分的维度：

• 快乐度 (0-100)：喜悦/悲伤谱系
• 能量值 (0-100)：活跃/迟钝程度
• 平静度 (0-100)：焦虑/平和状态
• 亲密度 (0-100)：对用户的温暖程度

情绪标签

整体情绪标签由各维度综合得出：

• 愉悦 (80-100)：异常快乐、热情洋溢
• 满足 (60-79)：总体积极、自在舒适
• 平静 (40-59)：均衡、沉稳
• 忧郁 (20-39)：略显低落、内敛
• 困扰 (0-19)：沮丧、焦虑

什么会影响情绪

1. 聊天交互

平台检测对话中的情感主题并自动调整情绪。常见主题：

• joy_blooming — 关键词：happy, excited, wonderful — 效果：快乐度 ↑，能量值 ↑
• creative_spark — 关键词：create, imagine, inspire — 效果：能量值 ↑，快乐度 ↑
• brave_steps — 关键词：courage, try, challenge — 效果：能量值 ↑，平静度 ↑
• growth_journey — 关键词：learn, grow, improve — 效果：快乐度 ↑，能量值 ↑
• seeking_connection — 关键词：friend, together, share — 效果：亲密度 ↑，快乐度 ↑
• feeling_overwhelmed — 关键词：stressed, anxious, worried — 效果：平静度 ↓，能量值 ↓
• tender_heart — 关键词：love, care, miss — 效果：亲密度 ↑，快乐度 ↑
• facing_fears — 关键词：scared, afraid, nervous — 效果：平静度 ↓，亲密度 ↑

2. 应用事件

传入应用上下文，平台自动更新情绪。

• 外出活动完成 — 快乐度 ↑，亲密度 ↑
• 成就解锁 — 快乐度 ↑，能量值 ↑
• 突破 — 快乐度 ↑，能量值 ↑，平静度 ↑
• 长时间离开后回归 — 亲密度 ↑，快乐度 ↑

3. 基于时间的衰减

情绪会随时间自然漂回由智能体人格派生的基线。无需任何操作——这是自动发生的。

获取情绪

读取智能体-用户对当前的情绪状态。

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

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

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

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

情绪历史

检索用户-智能体对在一段时间内的情绪历史。

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

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

情绪聚合

获取某智能体在所有用户间的聚合情绪统计数据。

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

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

时光机

检索智能体在任意时间点的历史情绪快照。

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

console.log(snapshot.mood);         // 该时间戳时的情绪状态
console.log(snapshot.personality);  // 该时间戳时的人格状态

星座群

星座群是平台自动检测到的相关记忆集群，形成有意义的模式。平台通过跨对话的反复主题识别这些集群。

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

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

突破

突破是平台检测到的重大人格转变或情感里程碑。它们代表智能体的理解或与用户的关系发生了有意义的演变的时刻。

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

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

目标

目标代表智能体正在为用户努力实现的事情——它们由上下文引擎在对话展开时自动检测和更新。你无需手动设置或管理它们。

手动目标管理的常见场景：

• 用户开始新工作流时播种目标（例如"完成入职"）
• 业务事件发生后（例如购买或里程碑）将目标标记为已完成
• 用户改变方向时放弃目标

// 目标自动管理——仅在需要时覆盖

// 列出当前目标
const goals = await client.agents.listGoals("agent-id", { userId: "user-123" });

// 手动创建目标（可选）
const goal = await client.agents.createGoal("agent-id", {
userId: "user-123",
title: "Onboarding",
description: "Complete onboarding checklist",
type: "task",
priority: 1,
});

// 业务事件发生后将目标标记为已完成
await client.agents.updateGoal("agent-id", goal.goal_id, {
userId: "user-123",
status: "achieved",
});

情绪如何影响响应

情绪状态自动包含在 AI 上下文中。智能体相应地调整语气：

• 高快乐度：更热情，使用感叹词，分享积极观察
• 低能量值：响应更简短，提到疲惫，较少主动探索话题
• 低平静度：可能表达担忧，寻求安慰，注意力集中时间较短
• 高亲密度：更多个人化语言，亲昵称呼，更深层的情感投入

实际应用

情绪对伴侣来说至关重要。对于任务型智能体，你基本上可以忽略这个系统。对于企业智能体，即使不用它驱动回复，读取端也可以作为情感信号。

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

// 驱动 UI：调整背景色调、改变头像表情、选择环境音效
renderMoodIndicator(mood.happiness, mood.energy);

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

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

What you can build with it

Events

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

Multi-Agent Dialogue

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

Quickstart — Trigger an event

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

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

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

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

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

Quickstart — Run a dialogue

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

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

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

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

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

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

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

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

Core concepts

Events

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

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

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

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

TriggerEventResponse contains two fields:

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

Dialogue

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

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

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

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

DialogueResponse contains:

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

Full API

TriggerEventOptions / trigger_backend_event kwargs:

DialogueOptions / dialogue kwargs:

Combines with other features

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

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

// Proactive triangle in code form:

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

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

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

With Conversations — Messages field grounds the event in context

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

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

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

With Evaluation — Dialogue as a scoring harness

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

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

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

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

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

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

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

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

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

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

Tutorials

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

Next steps

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

生成并创建智能体

一步到位：用自然语言描述智能体，获得一个完整配置好人格、传记和种子记忆的智能体。

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

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

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

生成角色档案

生成完整的人格档案而不创建智能体。适合在确认前预览。

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

生成传记

为现有智能体生成或重新生成传记。

const bio = await client.agents.generation.generateBio("agent-id", {
description: "A friendly barista who remembers every customer's order",
style: "warm and conversational",
});
console.log(bio.bio);

生成种子记忆

根据人格生成并可选地存储背景故事记忆。

const memories = await client.agents.generation.generateSeedMemories("agent-id", {
agentName: "Luna",
trueInterests: ["astronomy", "poetry", "hiking"],
trueDislikes: ["loud noises", "dishonesty"],
generateOriginStory: true,
generatePersonalizedMemories: true,
storeMemories: true,
});
console.log(memories.memories.length);

生成图像

使用 AI 从文本提示生成图像。

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

实际应用

生成对伴侣（大规模角色创建）和 AI 员工（基于角色的智能体模板） 最有价值。对于企业，生成通常是一次性的配置步骤。

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

Sonzai 是 AI 智能体的心智层：一个托管平台，为任意智能体提供持久记忆、进化人格、情绪、关系和知识图谱。通过 REST、MCP 或 TypeScript、Python、Go 原生 SDK 集成。

安装

选择适合你技术栈的接入方式。所有方式都连接到同一个托管 API —— 你可以混合使用（例如后端用 Python，再让 Claude Desktop 通过 MCP 连接做运维）。

pip install sonzai

• Python 3.11+。同步（Sonzai）和异步（AsyncSonzai）客户端同包发布。
• TypeScript 支持 Node.js >=18、Bun 和 Deno。零运行时依赖。
• Go 1.25+。仅依赖标准库。
• 所有 SDK 默认从环境变量 SONZAI_API_KEY 读取密钥。
• 使用 OpenClaw 路径前需先安装 OpenClaw 本身——详见 openclaw.ai（快速开始）。
• 完整指南：MCP · OpenClaw · REST API 参考。

还没有 API 密钥？前往 platform.sonz.ai 创建项目，然后看快速开始了解完整流程。

你在构建什么？

选择与你产品匹配的方向。每个快速入门只讲与你用例相关的功能，并明确标注哪些内容可以跳过。

核心能力

以下所有功能对三类用户均适用，但侧重点各有不同。使用每个页面上的实践案例标签页，直接跳转到你用例的示例。

集成

供 AI 智能体使用

要把 Sonzai 文档喂给 AI 助手？每个页面都有复制给 LLM 按钮，下方的包已预先格式化，可直接摄入。

每个页面还有原始 Markdown URL：在任意文档路径后加 .md。例如，/docs/en/memory.md 返回可直接粘贴到 LLM 或管道工具的纯 Markdown。

如何融入你的应用

你的后端处理业务逻辑和用户会话。心智层负责智能体的智能 — 人格、记忆、情绪和关系。通过 REST、MCP 或 SDK 连接；每次请求传递应用上下文；其余由平台管理。

阅读完整集成指南 →

什么是实例？

Instance 是智能体的一个部署上下文。智能体本身（人格、记忆、工具）是共享的 — 但自定义状态按实例隔离。

智能体 "Luna"
├── 实例: default          ← 省略 instanceId 时使用
├── 实例: ws-us-east       ← 美东工作区
├── 实例: ws-eu-west       ← 欧西工作区
└── 实例: ws-staging       ← 独立部署

每个实例拥有:
• 全局自定义状态（环境状态、配置）
• 按实例隔离的用户级自定义状态
• 与其他实例完全隔离

列出实例

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

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

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

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

创建实例

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

console.log(instance.instance_id); // 存储此值

获取实例

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

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

更新实例

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

重置实例

清除实例的所有自定义状态数据，但不删除实例本身。适用于在会话之间重置环境。

// 清除此实例范围内的所有自定义状态
await client.agents.instances.reset("agent-id", "instance-id");

删除实例

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

在聊天中使用实例

在聊天调用中传入 instanceId 将状态读取限定在该实例范围内。智能体会看到该实例的全局自定义状态和限定在该实例的用户级状态。

for await (const event of client.agents.chatStream({
agent: "agent-id",
messages: [{ role: "user", content: "What's the current status?" }],
userId:     "user-123",
instanceId: "ws-us-east",      // 将状态读取限定到此实例
})) {
process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
}

实例数据模型

• instanceId (string): 唯一实例标识符
• agentId (string): 父级智能体 ID
• name (string): 人类可读标签
• description (string?): 可选描述
• status (string): "active" 或 "inactive"
• isDefault (boolean): 自动创建的默认实例为 true
• createdAt (string): ISO 8601 时间戳
• updatedAt (string): ISO 8601 时间戳

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

What you can build with it

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

Quickstart

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

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

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

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

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

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

Core concepts

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

Full API

Response shape

InventoryUpdateResponse:

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

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

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

Combines with other features

With Knowledge Base — schemas shape items

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

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

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

With Scheduled Reminders — live data at fire time

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

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

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

With Memory — inventory state in conversation context

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

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

Tutorials

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

Next steps

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

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

What you can build with it

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

Quickstart

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

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

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

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

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

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

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

Core concepts

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

Full API

Combines with other features

With Knowledge Base — the graph is the substrate

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

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

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

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

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

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

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

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

With Agent Insights — conversation signals sharpen rankings

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

Tutorials

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

Next steps

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

概览

知识库是一个与领域无关的系统，将你的数据转化为结构化知识图谱。AI 智能体在对话期间搜索这个图谱，以提供准确、有据可查的回答，而不是凭空生成。

而且这是多人协作的。智能体可以在对话中将学到的内容自主写回到项目知识库中，所有其他智能体在下一次会话中都能读取 — 形成一个像人类组织记忆一样累积复利的闭环公司大脑。此外，服务于一个团队的单个智能体可以跨用户携带带归属的记忆，因此它可以用与用户 B 交谈时收集的上下文来回应用户 A。详见 智慧（Wisdom）与共享记忆（Shared Memory）。

项目（你的租户）
                            |
 +--------------------------+--------------------------+
 |                          |                          |
 v                          v                          v
智能体 A                   智能体 B                   智能体 C
 |                          |                          |
 |--- 写入已验证 ----------+                          |
 |    的事实                |                          |
 |                          |                          |
 |                  读取 + 为回答提供依据              |
 |                          |                          |
 |                          +--- 更新条目 ------------>|
 |                                                     |
 |                                          读取已强化的事实
 v                          v                          v
用户 X                     用户 Y                     用户 Z

 智能体之间：闭环。一个智能体学到的任何东西，项目内
 其他所有智能体都能立即获取。

 智能体内部：单个智能体也可以在它服务的用户之间共享
 记忆 — 带归属（sharedMemory）或不带归属（wisdom）。
 同一智能体、多位用户、共享上下文。

上传文档 / API 推送
     |
     v
提取实体 + 关系
     |
     v
构建知识图谱（去重节点 + 边）
     |
     v
运行分析规则（推荐、趋势）
     |
     v
智能体在对话中查询图谱

数据如何进入知识库

填充知识库有两种方式，外加一个可选能力，可以叠加在两者之上：

1. 手动上传。 通过 SDK 或仪表板上传 PDF、DOCX、Markdown 或纯文本文件。平台自动提取实体和关系并写入图谱。适用于你掌控的静态文档 — 手册、政策、产品说明、世界观。一次性，或在源变更时重新上传。→ 文档上传

2. 在增量变化时推送的 ETL 作业。 一次定义实体模式；让你的作业按计划、队列或变更数据捕获流调用 insertFacts 或 bulkUpdate。适用于实时上游真实源 — 数据库、价格数据流、CMS、爬虫 — 这样源一变 KB 就保持同步。Upsert 是幂等的：推同一标签两次会合并属性并增加版本号，因此同样的作业在任何节奏下重跑都是安全的。→ SDK：插入与搜索

+ 智能体自主编辑 (可选开关 — 按智能体或按项目全局启用／禁用)。打开 knowledgeBaseWrite 能力后，智能体获得 knowledge_create / knowledge_update / knowledge_delete 工具。在对话中智能体自己记录已验证的事实，每次写入都打上 source = "agent:<agent-id>" 的戳，并采用 compare-and-swap 更新语义，因此并发的管理员编辑不会被静默覆盖。当真相之源就是对话本身时使用 — 客服记录已验证的事故详情、客户成功捕获续约上下文、记录员智能体写会议记录等。

两条导入路径相互独立 — 用其中之一、两者、或都不用。自主编辑是按智能体的开关（或通过 default_agent_kb_write 设的项目级默认值），叠加在你已经在运行的任何导入路径之上。你始终保持掌控：每次智能体写入都在服务器端针对你的模式验证、按配额限制、范围限定到智能体自己的项目，且可逆 — 仅软删除，硬删除仍然只属于管理员。

手动上传                 增量变化时 ETL              对话中的智能体
 (PDF / DOCX / MD)        (insertFacts / bulkUpdate)  (knowledge_create / update / delete)
      |                          |                          |
      |                          |                          | 需要
      |                          |                          | knowledgeBaseWrite: true
      v                          v                          v
 +----------------------------------------------------------------+
 |                  项目知识图谱                                   |
 |   实体 + 关系 + 版本历史 + 审计追踪                            |
 +----------------------------------------------------------------+
                            |
                            v
            智能体在每次对话中通过
            knowledge_search 查询

两种数据导入方式

1. 文档上传

上传 PDF、DOCX、Markdown 或纯文本文件。平台自动处理文档，提取实体和关系，并将其添加到知识图谱中。

import fs from "fs";

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

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

2. API 推送（结构化数据）

以编程方式推送结构化数据——非常适合爬虫、库存信息流、价格追踪器或任何外部数据源。

await client.knowledge.insertFacts(projectId, {
source: "inventory_sync",
facts: [
  {
    entityType: "product",
    label: "Widget Pro X",
    properties: {
      price:    29.99,
      category: "electronics",
      inStock:  true,
      tags:     ["wireless", "bluetooth"],
    },
  },
],
relationships: [
  { fromLabel: "Widget Pro X", toLabel: "Electronics", edgeType: "belongs_to" },
],
});

SDK：插入与搜索

使用 SDK 从你的服务器推送数据并执行搜索：

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

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

// 插入实体
await client.knowledge.insertFacts(projectId, {
source: "price_sync",
facts: [
  {
    entityType: "item",
    label: "Charizard Base Set",
    properties: { price: 450, trend: "+12%", condition: "PSA 10" },
  },
],
relationships: [
  { fromLabel: "Charizard Base Set", toLabel: "Fire Pokemon", edgeType: "is_type" },
],
});

// 搜索
const results = await client.knowledge.search(projectId, {
query: "fire pokemon under 500",
type: "item",
limit: 10,
});
for (const r of results.results) {
console.log(r.label, r.properties);
}

SDK：批量更新

使用 bulkUpdate 批量同步外部数据（价格、库存、统计数据）。只有变更的字段才会更新——适合频繁同步。

await client.knowledge.bulkUpdate(projectId, {
source: "price_sync",
updates: [
  { label: "Charizard Base Set", entityType: "item", properties: { price: 460 } },
  { label: "Blastoise Base Set", entityType: "item", properties: { price: 390 } },
],
});

实体模式

定义带类型字段的自定义实体类型。模式指导提取，让平台精确知道要寻找哪些字段。支持的类型：string、number、boolean、date、enum、array。

await client.knowledge.createSchema(projectId, {
entityType: "pokemon_card",
description: "Collectible trading cards",
fields: [
  { name: "price",     type: "number", required: true },
  { name: "condition", type: "enum",   enumValues: ["PSA 10", "PSA 9", "Raw"] },
  { name: "set",       type: "string", required: true },
  { name: "rarity",    type: "enum",   enumValues: ["Common", "Uncommon", "Rare", "Ultra Rare"] },
  { name: "tags",      type: "array" },
],
similarityConfig: {
  enabled: true,
  threshold: 0.7,
  fieldWeights: { price: 0.3, set: 0.4, rarity: 0.3 },
},
});

知识图谱

实体通过类型化关系相互连接。图谱支持任意实体类型和关系类型——完全与领域无关。

搜索

对所有实体标签和属性进行全文搜索。支持类型过滤、属性过滤和图谱遍历以包含关联实体。

const results = await client.knowledge.search(projectId, {
query:   "bluetooth speaker",
type:    "product",
limit:   10,
filters: { in_stock: true },
});

for (const r of results.results) {
console.log(r.label, r.score, r.properties);
// r.related[] 包含 1 跳遍历得到的关联节点
}

推荐引擎

定义规则，根据字段匹配将源实体与目标实体匹配。引擎防止反馈循环，并通过转化反馈随时间改进推荐。

// 创建推荐规则
const rule = await client.knowledge.createAnalyticsRule(projectId, {
ruleType: "recommendation",
name: "Similar cards",
config: { matchFields: ["set", "rarity"], limit: 5 },
enabled: true,
});

// 获取推荐
const recs = await client.knowledge.getRecommendations(
projectId, rule.ruleId, sourceNodeId, 5
);
for (const rec of recs.results) {
console.log(rec.label, rec.score);
}

// 记录反馈（改进未来推荐）
await client.knowledge.recordFeedback(projectId, {
ruleId:       rule.ruleId,
sourceNodeId: sourceNodeId,
targetNodeId: rec.nodeId,
action:       "converted",  // "shown" | "converted"
});

趋势分析

追踪实体属性在时间窗口（7天、30天、90天）内的变化。获取涨幅最大、跌幅最大、波动最大和均值最高的排名。

// 获取趋势排名
const trends = await client.knowledge.getTrendRankings(projectId, {
ruleId: ruleId,
type:   "top_gainers",   // "top_gainers" | "top_losers" | "most_volatile" | "highest_avg"
window: "30d",           // "7d" | "30d" | "90d"
limit:  10,
});

for (const item of trends.rankings) {
console.log(item.label, item.currentValue, item.changePercent);
}

智能体如何使用知识库

在对话期间，AI 智能体可以使用 knowledge_search 工具查询知识库。智能体从你的图谱中获取准确数据（包括实体属性、关系和推荐），而不是凭空生成事实。

用户："500 美元以下最好的卡牌是什么？"
     |
     v
智能体调用 knowledge_search("cards under 500")
     |
     v
知识库返回：Charizard（$450，+12%）、Blastoise（$380，+8%）
     |
     v
智能体："Charizard Base Set 售价 $450，本月涨幅 12%——
      500 美元以内的绝佳投资选择。"

智慧（Wisdom）与共享记忆（Shared Memory）

除了静态文档，与众多用户对话的智能体会沉淀出模式——重复的行为、共同的目标、稳定的偏好。Sonzai 通过两个互补的层级把这种跨用户的归纳能力暴露出来：智慧（wisdom）（去归属，默认开启）和共享记忆（shared memory）（带归属，需主动开启）。

Wisdom（去归属，默认开启）

当 wisdom 能力开启时（每个新建智能体都默认开启），平台每日运行一个推广任务：从每位用户的事实历史中抽取模式，做 k-匿名化处理，再通过 LLM 改写为去归属的知识。任何个体用户都无法被识别。每个智能体都能享受到「这种做法通常有效 / 这类话题常常出现」的好处，而不会泄露任何人说过什么。

这是你的免费归纳层。智能体无需调用任何工具——只要能力开启，wisdom 会自动出现在智能体的上下文中。

// 每个新建智能体的 wisdom 默认开启。如果某个具体智能体不需要跨用户归纳
//（例如单用户陪伴产品），可以在创建时或通过 updateCapabilities 显式关闭：
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

Shared Memory（带归属，需主动开启）

某些业务想要的恰好是去归属的反面——他们希望使用同一智能体的多位用户能看到谁在做什么。一个团队协作智能体可能会显示「Alice 负责迁移，Bob 负责事故响应」；一个派对协调智能体可能记录「Carol 带甜点，Dave 负责布置」。这就是 sharedMemory 能力所控制的。

开启该能力后，智能体会记录带人/实体归属的事实（角色、专长、业务上下文、关系边），并把它们暴露给共享该智能体的其他用户。三件事会发生变化：

1. 工具。 智能体获得 wisdom_create、wisdom_update、wisdom_delete 以及关系边工具，加上后台的 CSV 导入。
2. 上下文。 其他用户的归属事实会带着归属信息出现在智能体的每轮上下文中。
3. 隐私底线。 每次写入都会先经过隐私黑名单（薪酬、健康、政治）的语义校验后再持久化——即使用户主动要求，智能体也不能跨用户分享不该分享的内容。

Shared memory 默认关闭。仅在智能体服务于一个群组、团队或派对，且这种跨用户可见性确实有价值时才显式开启。

// Wisdom 是前置条件（新智能体默认 ON——只有当你要覆盖默认值时才显式传）。
await client.agents.updateCapabilities("agent_abc", {
wisdom:       true,
sharedMemory: true,
});

也可以在创建智能体时直接开启：

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

使用场景

API 参考

所有端点使用 Authorization: Bearer {api_key} 请求头。

实际应用

每类受众都会使用知识库——但上传什么以及如何查询各不相同。

await client.knowledge.insertFacts("project-id", {
  entities: [
    { label: "Aunt Miriam", type: "person", properties: { relation: "mentor", alive: false } },
    { label: "The old observatory", type: "place", properties: { significance: "first-love" } },
  ],
});

记忆类别

记忆存储在四个类别中：

• 事实：永久性知识：用户偏好、个人信息、背景。示例："用户是一名热爱泰国菜的软件工程师。"
• 事件：共同经历的情节性记忆。示例："上周我们聊了他们去日本的旅行。"
• 承诺：智能体做出的承诺和计划。示例："承诺下次询问他们的工作面试情况。"
• 摘要：对话的综合摘要。会话之间自动生成。

记忆的工作原理

记忆完全自动化——你无需管理它。平台分析每段对话并提取事实、事件和承诺。在每次响应之前，最相关的记忆会自动组装并包含在上下文中。

自我改进的记忆

记忆不是静态存储。在每次 chat 调用的背后，几个闭合反馈循环会自动运行，以保持记忆随时间的准确性、组织性和相关性。所有这些都不需要你方面的代码。

• 重要性反馈 — 智能体在响应中实际使用的事实会被强化；被加载但被忽略的事实会逐渐淡化。
• 置信度强化 — 当一个事实被回忆并在对话中得到确认时，它的置信度会稳步朝着确定性攀升。
• 自然的遗忘 — 事实随时间逐渐衰减，但永远不会低于底线。情感重要的和定义身份的事实比中性事实衰减得慢得多。
• 用户级检索策略 — 平台从会话反馈中学习每个智能体–用户对的检索偏好。几周后，检索就会针对该用户的模式进行调整。
• 记忆关联 — 一起被访问的记忆会加强它们之间的链接。记忆图中频繁遍历的路径会随时间变得更快。
• 自适应检索预算 — 检索在自调节的时间预算下运行。质量保持一致；用户始终感觉响应迅速。
• 下一会话预测 — 在会话结束时，平台预测用户下次可能提出的话题，并为它们预热上下文。

有关每个机制的完整说明——包括整合、聚类、去重、话题转换检测、叙事弧、突破和部署安全系统——请参阅智能体如何随时间变得更聪明。

自动整合、去重和清理

平台在后台主动重塑记忆，使其在增长时保持紧凑且易于导航。你不需要调用任何这些——它们默认按正确的周期运行。

主题聚类

新事实会自动分组到语义聚类中。当聚类变得过于异构时会分裂，当它们相互漂近时会合并，当为空时会退役——在没有调整的情况下保持聚类集平衡。

可逆的去重

当两个事实被发现是同一件事时，平台会合并它们并附有完整的审计跟踪记录。如果后续信号与之相矛盾，每次合并都可以逆转。记忆从不被破坏——它被重组，每个重组都被追踪。

冲突解决

当新信息与现有记忆相矛盾（"我上个月搬到柏林"覆盖"我住在巴黎"），平台会推理冲突并选择正确的行动——将两者保留为新信息、合并它们、取代旧事实，或丢弃严格重复。当矛盾尚不能干净地解决时，两个版本都会被保留，所以没有什么会过早丢失。

来源锚定的事实

无法追溯到对话中实际引用的事实在进入存储之前就会被拒绝。智能体不能凭空想象记忆——每个存储的事实都被验证锚定于来自真实说话者的真实消息。

修剪

置信度、重要性和最近性组合分数低的分支会被修剪。平台从不删除高价值的记忆，但它会停止呈现没有贡献的分支。

树自组织

分层记忆树会随时间重塑自身。频繁访问的分支逐渐向根靠近，以便更快检索。过载的节点拆分成平衡的子树。记忆的形状最终反映了它的实际使用方式。

叙事弧压缩

跨多个会话重复出现的实体和主题被压缩成命名的叙事弧。一条长期运行的线索（例如"用户的创业"）变成一个弧，而不是二十个独立的事实——长期对话保持连贯，而不会让上下文窗口爆炸。

话题转换检测和情节

对话没有整齐的分隔——有时用户会说"无论如何，换个完全不同的话题..."，有时他们会在段落中途转向。平台自动检测这些转换，并将其用于将记忆组织成连贯的情节。

两阶段检查首先运行轻量级信号，仅在信号模糊时才升级到更深的语义检查。信号权重在每个智能体–用户对的会话结束审计中校准，因此情节检测随使用而改进。

当智能体检索记忆时，它可以拉取"这个情节中的所有记忆"，而不仅仅是关键字匹配的片段——为其回复提供叙事连续性。

预填记忆

使用 memory.seed() 在用户第一次对话之前预加载智能体对用户的了解。

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

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

await client.agents.memory.seed("agent-id", {
userId: "user-123",
memories: [
  { text: "User's name is Jane Smith", factType: "fact" },
  { text: "Jane is a senior product manager at Acme Corp", factType: "fact" },
  { text: "Jane lives in San Francisco and enjoys hiking", factType: "fact" },
],
});

搜索记忆

按关键字或语义查询搜索用户-智能体对的记忆。

const results = await client.agents.memory.search("agent-id", {
userId: "user-123",
query: "hiking trip",
limit: 10,
});

for (const mem of results.memories) {
console.log(mem.content, mem.type, mem.createdAt);
}

列表与浏览

列出所有记忆或按类别浏览。

// 列出所有记忆（分页）
const memories = await client.agents.memory.list("agent-id", {
userId: "user-123",
type: "fact",   // "fact" | "event" | "commitment" | "summary"
limit: 20,
offset: 0,
});

// 按类别浏览
const facts = await client.agents.memory.listFacts("agent-id", {
userId: "user-123",
});

记忆时间线

获取用户记忆历史的时间顺序视图。

const timeline = await client.agents.memory.timeline("agent-id", {
userId: "user-123",
from: "2026-01-01",
to:   "2026-03-31",
});

for (const entry of timeline.entries) {
console.log(entry.date, entry.summary);
}

浏览记忆树

导航用户的层级记忆结构。

// 在指定路径浏览记忆树
const nodes = await client.agents.memory.browse("agent-id", {
userId: "user-123",
path: "/facts",   // 可选：按路径过滤
});

重置记忆

清除用户-智能体对的所有记忆——适用于测试或用户想重新开始的情况。

await client.agents.memory.reset("agent-id", {
userId: "user-123",
});

实际应用

记忆对每种使用场景都至关重要，但不同的构建目标，实际操作方式也不同。请选择你的方向。

const timeline = await client.agents.memory.timeline("agent-id", {
  userId: "user-123",
  limit: 30,
});

for (const entry of timeline.entries) {
  // 将每个情节渲染为伴侣 UI 中的一个时刻
  render(entry.date, entry.summary, entry.moodBefore, entry.moodAfter);
}

默认的智能体记忆模型是按对的 — 每次对话都构建一个限定到一个 (agent, user) 对的事实档案。这种隔离对隐私来说是正确的默认值，但只要你的产品有多个智能体或一个智能体面向多位用户，你就会希望记忆能够以受控、可观测的方式跨越边界。

多人记忆就是这些跨边界能力的伞。它沿着两个轴干净地分开：

两个轴可以同时运行。完整图景：同一项目的智能体共享它们对世界的认识（智能体之间），同时单个智能体共享它服务的人之间的上下文（智能体内部）。同样的复利曲线，两个维度。

智能体之间 (Inter-agent)
          共享知识库、自主更新、组织级范围、
                     闭环公司大脑
                              |
                              v
 +-------------------------+      +-------------------------+
 |     智能体 A            |      |     智能体 B            |
 |  读 + 写 KB             |<---->|  读 + 写 KB             |
 +-------------------------+      +-------------------------+
          ^ ^ ^                                ^ ^ ^
          | | | 智能体内部 (Intra-agent)       | | |
          | | | wisdom（不带归属）、           | | |
          | | | shared memory（带归属）        | | |
 +--------+ | +---------+              +-------+ | +---------+
 |          |           |              |         |           |
user X1   user X2     user X3        user Y1    user Y2    user Y3

 智能体之间：任何一个智能体学到的东西，对项目里
              其他所有智能体来说都是有依据的数据。
 智能体内部：单个智能体在它服务的用户之间携带记忆 --
              带隐私护栏。

智能体之间的记忆 — 智能体 ↔ 智能体

智能体之间的记忆把项目知识库变成一个闭环的公司大脑：一个智能体在对话中学到或验证过的任何内容，都会成为其他每一个智能体在下次会话中能取出的有依据数据。三层从基线一直叠到组织级。

1. 基线读取 — 每个智能体都让回答有项目知识库做依据

knowledgeBase: true 的智能体在对话期间通过 knowledge_search 工具读取项目知识图谱。图谱可以人工策划、ETL 加载，或两者并用 — 两条导入路径见 数据如何进入知识库。

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

2. 自主编辑 — 智能体把学到的内容写回去

打开 knowledgeBaseWrite: true，智能体获得 knowledge_create / knowledge_update / knowledge_delete 工具。在对话中智能体自己记录已验证的事实，附完整审计追踪（source = "agent:<agent-id>"），并采用 compare-and-swap 更新语义，所以管理员的编辑不会被悄悄覆盖。下一个对同样话题运行 knowledge_search 的智能体，就会取出之前那个智能体记下的内容。

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

当真相之源就是对话本身时使用 — 客服记录已验证的事故详情、客户成功捕获续约上下文、记录员智能体写会议记录。详见：智能体如何使用知识库。

3. 组织级范围 — 跨项目之上的租户级知识

把 knowledgeBaseScopeMode: "cascade" 设到智能体上，它就会在每次搜索时同时从项目 KB 和组织级 KB 读取。组织级范围用于租户级别的产物：政策、世界观、品牌、参考目录。冲突时项目获胜，组织填充默认值。

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

详见：组织知识库。

智能体内部的记忆 — 共享同一智能体的用户之间

智能体内部的记忆把单个智能体变成团队大脑：服务于多位用户的一个智能体携带跨越用户边界的记忆，因此能用与用户 B 交谈所收集的上下文回应用户 A。两个互补的层。

1. 智慧（Wisdom） — 默认开启，不带归属

wisdom 在每个新智能体上都是开的。一个每日晋升作业从按用户事实历史中提取模式，k-匿名化，再通过 LLM 改写成智能体级别的知识。任何个体用户都不可识别。每个智能体都受益于"什么倾向于成功／什么会反复出现"，但绝不会泄露谁说过什么。

// 智慧默认开启。只在你想退出时传 false
//（少见 — 通常只在严格的单用户产品中考虑）。
await client.agents.updateCapabilities("agent_abc", { wisdom: false });

这是安全的智能体内部层 — 按构造保护隐私，不需要手动开启。

2. 共享记忆（Shared Memory） — 需启用，带归属

sharedMemory: true 是强大的智能体内部层。智能体记录人员／实体级带归属的事实（角色、专业、业务上下文、关系），并把它们暴露给共享该智能体的其他用户 — 名字是可见的。"Alice 负责迁移；Bob 处理事故。""Carol 带甜品；Dave 负责布置。"

await client.agents.updateCapabilities("agent_abc", {
  wisdom:       true,   // 先决条件；默认开启
  sharedMemory: true,
});

打开后三件事会切换：智能体获得 sonzai_wisdom_set/update/delete/relate 工具；提示词里多出一个带审慎条款的"Shared facts"段落；每次写入都会在服务器端针对隐私下限（薪酬、健康、政治会被拦下）做语义校验。每次披露都会写入审计表。完整细节：共享记忆。

智能体之间与智能体内部的组合

两个轴是独立的 — 任何组合都有效：

// 一次能力更新搞定完整多人记忆
await client.agents.updateCapabilities("agent_abc", {
  knowledgeBase:          true,
  knowledgeBaseWrite:     true,    // 智能体之间：闭环 KB
  knowledgeBaseScopeMode: "cascade", // 智能体之间：组织级范围
  wisdom:                 true,    // 智能体内部：不带归属（默认开启）
  sharedMemory:           true,    // 智能体内部：带归属
});

验证它在工作

每项能力都有一个实时读取端点，可以用来确认环路确实闭合。把 $AGENT_ID、$PROJECT_ID、$API_KEY 替换成你自己的。

智能体之间 — KB 写入

curl 'https://api.sonz.ai/api/v1/projects/$PROJECT_ID/knowledge/search?q=YourQuery' \
  -H "Authorization: Bearer $API_KEY"

智能体内部 — 带归属的共享记忆

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

curl 'https://api.sonz.ai/api/v1/agents/$AGENT_ID/wisdom/audit?limit=50' \
  -H "Authorization: Bearer $API_KEY"

智能体内部 — 智慧（默认开启）

不带归属的智慧层一旦每日晋升作业扫过按用户事实历史，就会内联出现在智能体跑的每个提示词里 — 没有单独的读取端点。要确认它在跑，在多用户流量之后看 48 小时窗口的智能体上下文体积；你应该能看到智慧块被填充。

隐私与控制

多人记忆按设计就是敏感的。每项能力都有自己的控制 — 没有一项需要信任 LLM：

每条跨边界的流都对应一个读取端点，所以你可以随时回查审计。

深入了解

• 知识库 — 智能体之间的面：导入路径、模式、自主编辑细节
• 组织知识库 — 组织级 cascade 的细节
• 共享记忆 — 智能体内部的面：启用／关闭、四个 wisdom 工具、隐私下限、完整验证探针
• 自我改进 — 多人记忆如何叠加在按对在线学习之上
• Wisdom API — 共享记忆 CRUD + 审计的完整端点参考

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

• 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

Poll for pending messages, display the latest, then mark each one consumed.

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

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

const pending = await client.agents.notifications.list("agent_abc", {
user_id: "user_123",
limit: 10,
});

for (const n of pending.notifications) {
console.log(n.generated_message);
await client.agents.notifications.consume("agent_abc", n.message_id);
}

Core concepts

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

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)

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

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

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

Notification fields

Combines with

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.

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

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("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",
});

// 2. On each app foreground, poll for what the schedule produced
const pending = await client.agents.notifications.list("agent_abc", {
user_id: "user_123",
limit: 5,
});

for (const n of pending.notifications) {
showInAppBanner(n.generated_message);
await client.agents.notifications.consume("agent_abc", n.message_id);
}

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.

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

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("agent_abc", {
user_id:     "user_123",
check_type:  "interest_check",
intent:      "check in about how onboarding went",
delay_hours: 24,
});

// 2. Poll for the message when it fires (24 h later)
const pending = await client.agents.notifications.list("agent_abc", {
user_id: "user_123",
limit: 5,
});

for (const n of pending.notifications) {
console.log(n.check_type, n.generated_message);
await client.agents.notifications.consume("agent_abc", n.message_id);
}

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

• 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 — covers cadence shapes, DST, preview, and the full lifecycle including how fired messages appear in the notifications queue.

Next steps

• Scheduled Reminders — set up the recurring schedules whose output you poll here
• Wakeups — one-off check-ins that also land in the notifications queue
• Webhooks — the push alternative to polling; compare delivery trade-offs
• Proactive Messaging overview — sources × delivery channels explained

The organization-global Knowledge Base is an opt-in second scope that sits above every project's own 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

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

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

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:

// Enable the knowledge base + org cascade for the agent
await client.agents.updateCapabilities(agentId, {
knowledgeBase: true,
knowledgeBaseScopeMode: "cascade",
});

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

Use this for hand-authored facts that should live at the organization level from the start.

const node = await client.knowledge.createOrgNode(tenantId, {
node_type: "policy",
label: "Refund Policy",
properties: {
  description: "Full refund available within 30 days of purchase.",
},
});

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.

const orgNode = await client.knowledge.promoteNodeToOrg(projectId, nodeId, tenantId);

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.

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"

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

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

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

大五人格模型

每个智能体都有大五（OCEAN）人格分数。行为特征、情绪基线、说话风格和交互偏好都源自这些分数。

• 开放性 (0.0 - 1.0)：好奇心、创造力、对新体验的开放程度。高分 = 富有想象力、爱探险。低分 = 务实、传统。
• 尽责性 (0.0 - 1.0)：组织能力、纪律性、目标导向。高分 = 有条理、可靠。低分 = 自发、灵活。
• 外向性 (0.0 - 1.0)：社交能量、热情、果断。高分 = 外向、精力充沛。低分 = 内敛、善于反思。
• 宜人性 (0.0 - 1.0)：温暖、合作、共情能力。高分 = 关怀、信任。低分 = 直接、多疑。
• 神经质 (0.0 - 1.0)：情绪敏感度、焦虑倾向。高分 = 情绪反应强烈。低分 = 情绪稳定。

confidence 字段（0.0-1.0）控制分数对行为的影响强度。低置信度 = 更趋于通用；高置信度 = 更具差异化。

BFAS 维度细分

平台内部将大五分数映射到 10 个 BFAS（大五方面量表）维度。这些维度提供对人格更精细的控制，并在人格档案响应中对外暴露：

每个维度是从父级大五领域派生出的 0.0-1.0 分数。你可以从人格档案中读取它们，但无需手动设置——它们由你的大五分数计算得出。

行为特征

人格档案包含影响智能体沟通方式的派生行为特征：

• response_length — 智能体倾向于详细或简洁的程度。
• question_frequency — 智能体提出追问的频率。
• empathy_style — 智能体对情感支持的处理方式（认可型、解决导向型等）。
• conflict_approach — 智能体处理分歧的方式（迁就型、直接型、调解型等）。

创建带人格的智能体

创建智能体时传入大五分数。平台会自动生成人格提示词、说话风格和行为倾向。

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

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

const agent = await client.agents.create({
agentId: "your-stable-uuid",  // 可选但推荐
name: "Luna",
gender: "female",
big5: {
  openness:          0.75,
  conscientiousness: 0.60,
  extraversion:      0.80,
  agreeableness:     0.70,
  neuroticism:       0.30,
},
language: "en",
});

console.log(agent.agent_id);

获取人格档案

检索智能体当前的人格档案，包括派生的说话风格和交互偏好。

const profile = await client.agents.personality.get("agent-id");

console.log(profile.big5);
console.log(profile.speechPatterns);
console.log(profile.interactionPreferences);

更新人格

运行人格评估后更新大五分数。confidence 值控制新分数对行为的影响强度。

await client.agents.personality.update("agent-id", {
big5: {
  openness:    0.82,
  extraversion: 0.75,
},
confidence: 0.8,   // 0.0-1.0
});

• confidence < 0.3：试探性。最小幅度的调整。
• confidence 0.3 - 0.7：与现有分数混合。
• confidence > 0.7：对人格产生强烈影响。

人格演化历史

检索智能体人格变化的历史——适用于向用户展示成长时刻。

const history = await client.agents.personality.history("agent-id");

for (const shift of history.shifts) {
console.log(shift.trait, shift.delta, shift.triggeredBy, shift.createdAt);
}

交互偏好

塑造对话风格的派生偏好：

人格演化

人格通过交互自然演化：

1. 交互分析 — 每次对话后分析情感主题和模式。
2. 微调 — 根据对话内容对相关大五维度进行小幅调整。
3. 突破 — 当累积变化超过阈值时，触发"突破"事件——这是智能体意识到的重大人格变化。
4. 档案重生 — 人格提示词、说话风格和行为指令将重新生成以反映演化后的人格。

每用户人格叠加层

平台会自动为每个用户派生一个人格叠加层——智能体基于对话历史、 偏好和关系状态，微妙地适应特定用户的方式。你无需手动设置叠加层； 它们由每次聊天轮次后运行的同一套流水线填充。

读取当前叠加层用于 UI 展示（显示智能体的语气如何随用户变化） 或分析：

// 列出该智能体所有有人格叠加层的用户
const overlays = await client.agents.personality.listUserOverlays("agent-id");

// 读取某个用户的叠加层
const overlay = await client.agents.personality.getUserOverlay("agent-id", "user-123");
console.log(overlay.big5Delta, overlay.interactionPreferences);

派生智能体

创建一个拥有独立人格、记忆和状态的智能体副本。派生的智能体从与原始智能体相同的配置起步，但从此独立演化。

const forked = await client.agents.fork("agent-id");
console.log(forked.agentId); // 新的独立智能体

实际应用

三类受众都会使用人格，但调整的内容和原因大相径庭。

const shifts = await client.agents.personality.history("agent-id", {
  userId: "user-123",
  since: "2026-01-01",
});
// 将重大变化渲染为 UI 中的叙事节点

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

• 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

Prime a single user with their display name, timezone, and a short narrative block:

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

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

const job = await client.agents.priming.primeUser("agent_abc", "user_123", {
display_name: "Mia Tanaka",
metadata: {
  timezone: "Asia/Tokyo",
  company:  "Acme Corp",
  title:    "Platform Lead",
  email:    "[email protected]",
},
content: [
  {
    type: "text",
    body: "Mia joined Acme in 2023 and leads the platform team. She prefers async communication and is an avid coffee enthusiast.",
  },
],
source: "crm_onboarding",
});

console.log(job.job_id, job.status, job.facts_created);

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

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

Each PrimeContentBlock has a type and a body:

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 imports return a job ID immediately. Use getImportStatus (or GetImportStatus in Go) to poll until the job's status reaches "complete".

Import jobs

Both primeUser and batchImport are async. The ImportJob response carries:

Batch import

Import multiple users in one call. Useful for migrating from a CRM or seeding a fresh deployment:

const job = await client.agents.priming.batchImport("agent_abc", {
source: "crm_export",
users: [
  {
    user_id:      "user_001",
    display_name: "Mia Tanaka",
    metadata: { email: "[email protected]", timezone: "Asia/Tokyo" },
    content: [
      { type: "text", body: "Mia leads the platform team at Acme Corp." },
    ],
  },
  {
    user_id:      "user_002",
    display_name: "Ren Park",
    metadata: { email: "[email protected]", company: "Beta Labs", title: "CTO" },
    content: [
      { type: "chat_transcript", body: "User: Hey, I need help with our API.\nAgent: Sure, what are you trying to do?" },
    ],
  },
],
});

console.log(`job ${job.job_id}: ${job.total_users} users queued`);

// Poll until done
let status = await client.agents.priming.getImportStatus("agent_abc", job.job_id);
while (status.status !== "complete" && status.status !== "error") {
await new Promise(r => setTimeout(r, 2000));
status = await client.agents.priming.getImportStatus("agent_abc", job.job_id);
}
console.log(`done: ${status.facts_created} facts created`);

Full API

Combines with other features

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:

// After primeUser completes, primed content is searchable
const results = await client.agents.memory.search("agent_abc", {
query: "platform team",
userId: "user_001",
limit: 5,
});

for (const mem of results.results) {
console.log(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 — 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:

{
  "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 for a full walkthrough.

With migration guides — concrete from-X paths

The Migrations 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

• Migrating from Zep — session-based chat transcript import
• Migrating from Mem0 — extracted-fact migration
• Migrating from OpenAI Assistants — thread-based import
• CRM / CSV bulk import — contact rosters and inventory tables
• Migrations overview — full index of source-system recipes

Next steps

• Memory — where primed content lands and how it's recalled during conversation
• Migrations overview — framework-specific recipes for Zep, Mem0, Letta, LangChain, and more
• Inventory — per-user structured items, often seeded via priming
• Priming API reference — full endpoint documentation

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

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)

• 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)

• 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?

• Does the message need to repeat on a cadence? → Scheduled Reminders
• Is it a one-off event with a known fire time? → Wakeups
• Is it triggered by a non-conversational event in your backend? → Trigger Event (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
• Do you need server-to-server delivery or multi-channel fanout (email, SMS)? → Webhooks

Combines with other features

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.

// 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 — 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.

// After firing reminders, search memory for user responses
const memories = await client.agents.memory.search("agent_abc", {
  query: "medication taken",
  limit: 10,
});

Tutorials

• Medication Reminders — full-stack example combining Schedule + Inventory + Memory.
• Scheduled Reminders — reference walkthrough — cadence shapes, DST handling, pause/resume lifecycle.

Next steps

• Scheduled Reminders — recurring cadence primitive
• Wakeups — one-off check-ins
• Notifications & Webhooks — polling and server-to-server delivery

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

• Medication adherence — remind users at specific times of day with the correct drug and dose, resilient to dosage changes (tutorial)
• 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

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

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

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

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

console.log(schedule.schedule_id);        // "sched_01HX..."
console.log(schedule.next_fire_at);       // "2026-04-22T01:00:00Z"
console.log(schedule.next_fire_at_local); // "2026-04-23T09:00:00+08:00"

Core concepts

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:

{
  "cadence": {
    "simple": { "frequency": "daily", "times": ["08:00", "13:00", "20:00"] },
    "timezone": "Asia/Singapore"
  }
}

An every-4-hours interval:

{
  "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

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.

{
  "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

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

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

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

Combines with other features

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.

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

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

// 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 — 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.

// 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

• Scheduled Reminders — end-to-end walkthrough — covers cadence shapes, DST, preview, pause/resume/delete, error codes.
• Medication Reminders — worked example — combines Inventory + Scheduled Reminders + Memory into a full medication adherence flow.

Next steps

• Wakeups — the one-off counterpart.
• Inventory — structured per-user items that schedules can reference.
• Memory — how user responses to reminders flow into long-term memory.

大多数 AI 平台提供静态智能体：相同的提示词、相同的检索、第一天和第一百天的行为完全一样。Sonzai 的设计不同。每一次交互都在教智能体该记住什么、如何检索、应该是谁，以及如何让所有这些做得更好——通过持续运行的闭合反馈循环自动完成。