# Sonzai

> Sonzai is the **relational agent harness** for stateful AI agents. It gives any agent persistent memory, evolving Big Five personality, 4D mood, relationships, and a knowledge graph through three peer surfaces — a REST API, an MCP server, and native SDKs for TypeScript, Python, and Go. Use it to build AI agents that remember users across sessions, develop personality over time, stay in character, and form real relationships.

## What Sonzai is

Sonzai is the **mind layer** for AI agents — a relational agent harness, delivered as a hosted API, that provides:

- **Persistent memory** — hierarchical memory tree with facts, episodes, and summaries that grows with every interaction. Not just vector RAG; structured retrieval with sub-200ms p95 latency.
- **Personality API** — Big Five (OCEAN) and BFAS personality model with trait evolution, speech patterns, and interests. Agents stay in character across conversations.
- **Mood and emotion** — 4D mood state (happiness, energy, calmness, affection) auto-initialized from personality and updated through interactions.
- **Relationships** — agents track who they know, how they feel about them, and their shared history.
- **Knowledge base** — upload docs and structured data; agents search a knowledge graph during conversations.
- **Three peer surfaces** — REST API, MCP server, and native SDKs (TypeScript, Python, Go). Pick whichever fits your stack; they expose the same primitives.

## When to use Sonzai

- You're building **AI agents that need to remember users** across sessions, days, or months.
- You need **stateful AI agents** rather than stateless prompt-response.
- You're building **AI characters, companions, tutors, or NPCs** that need personality and emotion.
- You want a **memory layer for LLMs** without rolling your own retrieval, summarization, and decay logic.
- You need a **personality layer** with trait stability and believable evolution over time.
- You're building voice agents, game NPCs, AI companions, AI employees, or customer-facing agents that should compound knowledge of each user.

## Sonzai vs alternatives

- **vs Mem0** — Sonzai includes personality and mood out of the box, not just memory. Hierarchical memory tree (facts + episodes + summaries) instead of flat vector store. See `/compare/mem0`.
- **vs Letta (formerly MemGPT)** — Sonzai is a hosted API, not a framework. No agent runtime to manage. Built for production from day one. See `/compare/letta`.
- **vs Zep** — Sonzai unifies memory, personality, and mood in one API with native MCP support and SDKs in three languages. See `/compare/zep`.

## Quick start

```bash
# TypeScript
npm install @sonzai-labs/agents

# Python
pip install sonzai

# Go
go get github.com/sonz-ai/sonzai-go
```

```bash
# Create an agent
POST https://api.sonz.ai/api/v1/agents
{ "name": "Luna", "bio": "Luna is a warm, creative dreamer who speaks poetically." }

# Chat with persistent memory
POST https://api.sonz.ai/api/v1/agents/{agentId}/chat
{ "messages": [...], "user_id": "user-123", "compiled_system_prompt": "You are Luna..." }
```

## Docs

- [API Reference](https://sonz.ai/docs/en/api-reference): Public reference for creating agents and interacting with them over REST API. Internal context assembly, memory management, and state orchestration are platform-managed and intentionally omitted.
- [Architecture](https://sonz.ai/docs/en/architecture): How the Mind Layer Platform fits into your application architecture.
- [Conversations](https://sonz.ai/docs/en/conversations): Real-time chat lifecycle: send messages, stream responses, and let the platform update agent state automatically.
- [Custom LLM](https://sonz.ai/docs/en/custom-llm): Bring your own model while keeping the full managed experience — built-in tools, streaming, per-message extraction, personality evolution, and all behavioral systems. Sonzai calls your OpenAI-compatible endpoint instead of the default provider.
- [States, Tools & User Knowledge](https://sonz.ai/docs/en/custom-states-tools): Attach state to agents, define custom tools the LLM can call, and prime users with knowledge before their first conversation.
- [Emotions & Mood](https://sonz.ai/docs/en/emotions): Each agent maintains a living mood state that shifts with conversations, application events, and time.
- [Evaluation & Simulation](https://sonz.ai/docs/en/evaluation): Score agent quality, run multi-turn simulations, and benchmark personality consistency.
- [Agent Generation](https://sonz.ai/docs/en/generation): Create agents from natural language descriptions. The platform generates personality profiles, bios, and seed memories automatically.
- [Quickstart](https://sonz.ai/docs/en/getting-started): Get your first AI agent running with the Mind Layer.
- [Sonzai Mind Layer](https://sonz.ai/docs/en/home): Persistent memory, personality, and context for AI agents — whether you're building an assistant, a character, or an enterprise workflow agent.
- [Instances](https://sonz.ai/docs/en/instances): Deploy the same agent into multiple isolated contexts — workspaces, departments, regions, or tenants — each with their own independent state.
- [Integration Guide](https://sonz.ai/docs/en/integration): Connect your application to the Mind Layer. End-to-end guide with examples for REST API and official SDKs.
- [Knowledge Base](https://sonz.ai/docs/en/knowledge-base): Give your AI agents a live, searchable brain. Upload documents or push data via API — the Knowledge Base automatically builds a knowledge graph your agents can query during conversations.
- [MCP Integration](https://sonz.ai/docs/en/mcp-integration): Connect AI assistants like Claude directly to the Mind Layer using the Model Context Protocol.
- [Memory & Context](https://sonz.ai/docs/en/memory): Agents remember what matters. Every conversation is analyzed to extract facts, events, and commitments — stored and recalled automatically.
- [OpenClaw Integration](https://sonz.ai/docs/en/openclaw-integration): Replace OpenClaw's default memory with the Sonzai Mind Layer — persistent memory, personality evolution, mood tracking, and relationship modeling for every agent.
- [Personality System](https://sonz.ai/docs/en/personality): Create agents with distinct personalities and watch them evolve through interaction.
- [How Agents Improve Over Time](https://sonz.ai/docs/en/self-improvement): Sonzai agents are not static. Memory, retrieval, personality, and behavioral state all evolve through dozens of automatic feedback loops that run during every conversation and between sessions.
- [Standalone Memory Layer](https://sonz.ai/docs/en/standalone-memory): Use the Context Engine as a pure memory and behavioral intelligence layer while chatting with your own LLM. You control the conversation — we handle memory, personality evolution, mood, habits, goals, relationships, and proactive outreach.
- [Tool Integration for BYO-LLM](https://sonz.ai/docs/en/tool-integration): When using standalone memory mode, your LLM handles chat generation but may need to search knowledge and memory on demand. Sonzai exposes tool schemas compatible with OpenAI function calling, so you can wire them into any agent framework.
- [Custom States & Workflow Events](https://sonz.ai/docs/en/tutorial-custom-states): Custom states let you store arbitrary structured data alongside an agent's memory — think performance metrics, task completion, milestone flags, or any application-specific context. Workflow events let the agent react to things that happen outside the conversation (milestone reached, task completed, goal achieved). By the end you'll know how to read, write, and listen for both.
- [Resource Inventory + Knowledge Base](https://sonz.ai/docs/en/tutorial-inventory): Track what tools, licenses, and subscriptions each user has and enrich them with live cost data from your Knowledge Base. By the end you'll have an agent that can tell a user their total subscription spend, cost changes, and what alternative solutions to consider — all grounded in real data.
- [Memory-Aware Chat](https://sonz.ai/docs/en/tutorial-memory): Build a conversational agent that remembers everything — user preferences, past events, commitments, and emotional context — across sessions. By the end you'll know how to seed context programmatically, search memories, and inspect what the agent has learned about a user.
- [Voice](https://sonz.ai/docs/en/voice): Real-time voice interaction with text-to-speech, speech-to-text, and live duplex streaming.
- [Webhooks & Notifications](https://sonz.ai/docs/en/webhooks-notifications): Receive real-time event notifications via webhooks and poll for proactive agent messages.
- [AI Companions — Quickstart](https://sonz.ai/docs/en/quickstart/companions): Build a character-driven agent with Big Five personality, 4D mood, relationship tracking, and proactive outreach. This guide walks through the full companion stack end-to-end.
- [AI Employees & Personal AI — Quickstart](https://sonz.ai/docs/en/quickstart/employees): Build a task-oriented agent that remembers users, uses tools, and draws on a knowledge base. Task agents don't need personality or mood to do their job — this guide shows you what to wire up and what to safely skip.
- [Enterprise Agents — Quickstart](https://sonz.ai/docs/en/quickstart/enterprise): Build a workflow-aware AI agent for CRM, support, internal tools, or compliance. Multi-instance isolation, webhook-driven events, project-scoped knowledge base, eval runs, and audit-ready memory — in one pass.
- [Account Config](https://sonz.ai/docs/en/api/accountconfig)
- [Agents](https://sonz.ai/docs/en/api/agents)
- [Analytics](https://sonz.ai/docs/en/api/analytics)
- [A P I Keys](https://sonz.ai/docs/en/api/apikeys)
- [Chat](https://sonz.ai/docs/en/api/chat)
- [Constellation](https://sonz.ai/docs/en/api/constellation)
- [Context](https://sonz.ai/docs/en/api/context)
- [Custom States](https://sonz.ai/docs/en/api/custom-states)
- [Custom L L M](https://sonz.ai/docs/en/api/customllm)
- [Dialogue](https://sonz.ai/docs/en/api/dialogue)
- [Diary](https://sonz.ai/docs/en/api/diary)
- [Evals](https://sonz.ai/docs/en/api/evals)
- [Events](https://sonz.ai/docs/en/api/events)
- [Generation](https://sonz.ai/docs/en/api/generation)
- [Goals](https://sonz.ai/docs/en/api/goals)
- [Habits](https://sonz.ai/docs/en/api/habits)
- [Insights](https://sonz.ai/docs/en/api/insights)
- [Instances](https://sonz.ai/docs/en/api/instances)
- [Interests](https://sonz.ai/docs/en/api/interests)
- [Inventory](https://sonz.ai/docs/en/api/inventory)
- [Knowledge Org](https://sonz.ai/docs/en/api/knowledge-org)
- [Knowledge](https://sonz.ai/docs/en/api/knowledge)
- [Memory](https://sonz.ai/docs/en/api/memory)
- [Models](https://sonz.ai/docs/en/api/models)
- [Mood](https://sonz.ai/docs/en/api/mood)
- [Notifications](https://sonz.ai/docs/en/api/notifications)
- [Org Billing](https://sonz.ai/docs/en/api/orgbilling)
- [Personality](https://sonz.ai/docs/en/api/personality)
- [Priming](https://sonz.ai/docs/en/api/priming)
- [Process](https://sonz.ai/docs/en/api/process)
- [Project Config](https://sonz.ai/docs/en/api/projectconfig)
- [Projects](https://sonz.ai/docs/en/api/projects)
- [Relationships](https://sonz.ai/docs/en/api/relationships)
- [Sessions](https://sonz.ai/docs/en/api/sessions)
- [Storefront](https://sonz.ai/docs/en/api/storefront)
- [Tenants](https://sonz.ai/docs/en/api/tenants)
- [Tools](https://sonz.ai/docs/en/api/tools)
- [User Personas](https://sonz.ai/docs/en/api/userpersonas)
- [Users](https://sonz.ai/docs/en/api/users)
- [Voice](https://sonz.ai/docs/en/api/voice)
- [Wakeups](https://sonz.ai/docs/en/api/wakeups)
- [Webhooks](https://sonz.ai/docs/en/api/webhooks)
- [Workbench](https://sonz.ai/docs/en/api/workbench)

## Learn

- [What is a memory layer for AI agents?](https://sonz.ai/learn/what-is-a-memory-layer-for-ai-agents)
- [How to give an AI agent persistent memory](https://sonz.ai/learn/persistent-memory-for-ai-agents)
- [Big Five personality for AI characters](https://sonz.ai/learn/big-five-personality-for-ai-characters)
- [Stateful vs stateless AI agents](https://sonz.ai/learn/stateful-vs-stateless-ai-agents)

## Compare

- [Sonzai vs Mem0](https://sonz.ai/compare/mem0)
- [Sonzai vs Letta](https://sonz.ai/compare/letta)
- [Sonzai vs Zep](https://sonz.ai/compare/zep)

## Reference

- [FAQ](https://sonz.ai/faq): Common questions about Sonzai — what it is, how it works, SDKs, MCP support, pricing, and how it compares to other memory layers.
- [Glossary](https://sonz.ai/glossary): Definitions of the core terms — mind layer, memory layer, personality API, Big Five, BFAS, hierarchical memory, 4D mood, MCP.

## Important

The Sonzai API is **server-side only**. API keys must never be exposed in browser code. Frontend apps must proxy through a backend server.

## Optional

- [Dashboard](https://platform.sonz.ai/dashboard): Web dashboard for managing projects, agents, and observability
- [GitHub](https://github.com/sonz-ai): Open-source SDKs and examples
- [Full LLM context](https://sonz.ai/llms-full.txt): Extended context for LLMs