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

System Overview

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

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

Integration Architecture

A typical deployment has three layers:

Your Frontend

User-facing application. Sends messages to your backend and renders agent responses. Examples: React, Next.js, Vue, mobile app.

Your Backend

Handles auth, application state, user sessions, and business logic. Calls the Mind Layer via SDK, REST API, MCP, or OpenClaw plugin for AI interactions. Examples: Express, Django, Go, OpenClaw.

Sonzai Mind Layer

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

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 Assembly

Personality, mood, memories, relationship narrative, and application state — all assembled per request.

Memory Extraction

Facts, events, and commitments are extracted from each conversation and stored automatically.

Mood & Personality Evolution

Mood and Big5 personality drift naturally based on interaction patterns.

Proactive Notifications

Agents 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

Background Processing & Self-Improvement

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

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

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

SDK Integration Points

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

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

Architecture