# Sonzai Mind Layer

> AI characters with persistent memory, evolving personalities, and relationship tracking. Integrates with any game or app via REST API.

The Mind Layer tracks personality, memory, mood, habits, goals, and relationships for AI characters, updating them through user interactions. Your game connects via REST API, sends events, and gets back enriched context for AI conversations.

## Quick Reference: Making Characters Respond In-Character

The most common mistake is creating an agent without a `bio` or `compiled_system_prompt`, which results in generic assistant-like responses. To get in-character responses:

1. **Create the agent with a `bio`** — the bio defines who the character IS (personality, background, speech style)
2. **Pass `compiled_system_prompt` in chat requests** — this is the system prompt the LLM uses to stay in character

```bash
# Create agent with bio
POST /api/v1/agents
{ "name": "Luna", "bio": "Luna is a warm, creative dreamer who speaks poetically...", "gender": "female" }

# Chat with compiled_system_prompt for in-character responses
POST /api/v1/agents/{agentId}/chat
{ "messages": [...], "user_id": "user-123", "compiled_system_prompt": "You are Luna, a warm creative soul..." }
```

Without a bio or compiled_system_prompt, agents will respond as a generic AI assistant.

## REST API Endpoints

```
POST /api/v1/agents                              Create agent
GET  /api/v1/agents                              List agents
GET  /api/v1/agents/{agentId}                    Get agent (includes bio, big5, dimensions, speech_patterns)
POST /api/v1/agents/{agentId}/chat               Chat (SSE streaming)
GET  /api/v1/agents/{agentId}/personality         Get personality profile (Big5, BFAS, speech patterns, interests)
PUT  /api/v1/agents/{agentId}/personality         Update Big5 scores
GET  /api/v1/agents/{agentId}/mood               Get mood state (valence, arousal, tension, affiliation — auto-initialized from Big5)
GET  /api/v1/agents/{agentId}/memory             Get memory tree
GET  /api/v1/agents/{agentId}/notifications       Pending notifications
POST /api/v1/agents/{agentId}/notifications/{id}/consume  Consume notification
GET  /api/v1/agents/{agentId}/notifications/history       Notification history
```

## Docs

- [Overview](https://sonz.ai/docs/en/home): Platform overview and core capabilities
- [Quickstart](https://sonz.ai/docs/en/getting-started): Create a project, spin up an agent, and start chatting
- [Architecture](https://sonz.ai/docs/en/architecture): How the platform, orchestrator, and AI service fit together
- [Integration Guide](https://sonz.ai/docs/en/integration): Connect your game server to the Mind Layer end-to-end
- [API Reference](https://sonz.ai/docs/en/api-reference): Full REST API reference
- [Personality System](https://sonz.ai/docs/en/personality): Big Five model with trait evolution
- [Memory & Context](https://sonz.ai/docs/en/memory): Hierarchical memory tree with facts, episodes, summaries
- [Emotions & Mood](https://sonz.ai/docs/en/emotions): 4D mood system (valence, arousal, tension, affiliation)
- [Conversations](https://sonz.ai/docs/en/conversations): Real-time streaming chat with side effect processing
- [Custom States & Tools](https://sonz.ai/docs/en/custom-states-tools): Attach game state and define custom tools the LLM can invoke
- [Knowledge Base](https://sonz.ai/docs/en/knowledge-base): Upload documents and structured data to build a knowledge graph agents can search during conversations
- [User Priming](https://sonz.ai/docs/en/api-reference#user-priming): Pre-load user metadata and content so agents already "know" users from day one

## Important: Server-Side Only

The Sonzai API does not accept browser (client-side) requests. API keys must never be exposed in frontend code. Browser/frontend apps must proxy through a backend server. See the [Integration Guide](https://sonz.ai/docs/en/integration) for Next.js and Express proxy examples.

## Optional

- [Dashboard](https://platform.sonz.ai/dashboard): Web dashboard for managing projects, agents, and observability