Sonzai Docs

Architecture

How the Mind Layer Platform fits into your application architecture.

System Overview

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

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

Three-Service Architecture

A typical deployment has three layers that work together:

Your Backend

Handles auth, application state, user sessions, and business logic. Owns all application data. Calls the Mind Layer via SDK or REST API for AI interactions.

Express, Django, custom backend

Mind Layer Platform

Owns agent intelligence: personality, memory, mood, habits, goals, and relationships. A single chat call handles context assembly, AI streaming, and post-chat learning.

Sonzai Mind Layer Platform

AI Service

Stateless LLM layer. Takes enriched context and generates AI responses, images, video, and audio.

Sonzai AI Service

What the Platform Manages

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

Context AssemblyPersonality, mood, memories, relationship narrative, and application state — all assembled per request.
Memory ExtractionFacts, events, and commitments are extracted from each conversation and stored automatically.
Mood & Personality EvolutionMood and Big5 personality drift naturally based on interaction patterns.
Proactive NotificationsAgents can schedule proactive outreach between sessions. Deliver via polling or webhook.

Data Ownership

The Mind Layer and your backend each own distinct data:

Mind Layer Owns

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

Your Backend Owns

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

Session Lifecycle

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

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

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

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

SDK Integration Points

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

Agentscreate, get, list, update
Chatchat, chatStream (SSE)
Memoryseed, search, list, browse, timeline, listFacts, reset
Personalityget, update, history
Moodget, history, aggregate
Knowledge BasecreateSchema, insertFacts, bulkUpdate, search, recommendations, trends
Custom Statescreate, get, upsert, list, delete
Custom Toolscreate, list, delete (agent-level and session-level)
Notificationslist, consume, history
User PrimingprimeUser, batchImport, getMetadata, updateMetadata
← QuickstartIntegration Guide→