The Relationship Layer for consumer AI agents — how it actually works.

Eight modules. Pick one, pick all.

Each layer is independently consumable through the same SDK. The Memory Layer can stand alone. Personality, Mood, and Relationships compose on top. Learning Systems rewrite every layer below them. Agent Runtime caps the stack with provider-agnostic orchestration.

A production agent stack is a dozen distributed systems wired together. Sonzai operates all of them.

The Relationship Layer is the part visible through the API. Underneath sits the infrastructure that makes a multi-tenant, evolving, learning agent platform actually work in production. Transactional and columnar stores for state, a hybrid index for retrieval, a cache for hot context, a queue with DLQ and retries for async work, a worker pool for extraction and embedding, a versioned per-user weight store for RL policies, a scheduler for cadence-driven jobs, a key vault for credentials, a cost ledger for guardrails, observability for traces and metrics, and an eval gate for releases.

If you DIY vs. with Sonzai

Plain RAG embeds, top-k's, and hopes. Sonzai's retrieval is agentic.

The model reasons about what it needs to know, chooses which memory tools to call, inspects the results, and iterates until it has enough context. This is the ReAct loop applied to memory — not just to web search.

Vector RAG vs. agentic retrieval

Five patterns. Same Relationship Layer. Pick the shape that fits your stack.

Each pattern is independently usable. Adopt one and you can graduate to another without re-platforming — the surface area changes, the substrate doesn't. Start with Process for the lightest touch, move to Sessions when you want lifecycle, or go straight to Agent Chat for the full hosted runtime. Hermes and OpenClaw are config-flips if you're already on those agent frameworks.

from sonzai import Client
sz = Client(api_key=os.environ["SONZAI_API_KEY"])

async def handle_turn(user_id, agent_id, messages):
    # Sonzai extracts facts, persists memory, applies deltas — returns audit info.
    deltas = await sz.agents.process(
        agent_id=agent_id, user_id=user_id, messages=messages,
    )
    return deltas  # { memories_created, facts_extracted, mood, personality, relationship }

const s = await client.agents.sessions.start({ agent, user, sessionId });

for (const message of stream) {
  const ctx = await s.context({ query: message });   // 7-layer enriched system block
  const reply = await yourLLM([ctx.systemBlock, message]);
  await s.turn({ messages: [message, reply] });      // async extract + learn
}
await s.end({ messages });                            // triggers consolidation

async for evt in client.agents.chat(
    agent=agent, messages=[...], stream=True, tools=[...]
):
    if   evt.type == "delta":     render(evt.text)
    elif evt.type == "tool_call": handle_tool(evt)
    elif evt.type == "complete":  show_usage(evt.usage)

# Two plugins, cooperating:
# Memory Provider runs every turn; Context Engine fires only on token-budget hit.
plugins:
  memory: sonzai
  context: sonzai
sonzai:
  api_key: ${SONZAI_API_KEY}

{
  "contextEngine": "sonzai",
  "sonzai": {
    "apiKey": "<your-key>",
    "audit": true           // composio_app + request_id captured
  }
}

Choosing a flow

Match your existing stack to the flow that touches it least. All five share the same backend, the same primitives, and the same per-user state — moving between them is a code change, not a re-platforming.

The agent on day 90 is not the agent on day 1. It has learned this user specifically.

Most platforms ship a single model that serves every user the same. Sonzai stores per-user reinforcement-learning policy weights and personality overlays, hot-loaded into the inference path. The substrate to do this safely — shadow rollouts, promotion gates, versioning, rollback — is the kind of thing teams spend a year building. Sonzai ships it.

One request in. One response out. Eleven things in between.

The full lifecycle of a single user turn in Managed Runtime mode. Steps 1–6 are synchronous (in the request path). Steps 7–11 are asynchronous (queued, eventually consistent).

Same primitives. Six surfaces. Pick what fits your stack.

import { Sonzai } from "@sonzai-labs/agents";
const sz = new Sonzai({ apiKey: process.env.SONZAI_API_KEY });

const stream = await sz.agents.stream({
  userId,
  message,
  scene: "front_of_house",
  providers: ["claude-3.5", "gpt-4o"],
  tools: ["composio.gmail", "kb.search"],
});
for await (const chunk of stream) yield chunk.text;

import sonzai "github.com/sonz-ai/sonzai-go"

sz, _ := sonzai.New(sonzai.WithAPIKey(os.Getenv("SONZAI_API_KEY")))

facts, _ := sz.Memory.Recall(ctx, &sonzai.RecallReq{ UserID: uid, Query: msg })
// ... your LLM call, with facts injected ...
sz.Memory.ExtractAsync(ctx, uid, transcript)

Deployment modes — adopt what you need

None of this is one feature. It's nine choices that compound.

Each item below is a deliberate design choice in the substrate. None of them is novel in isolation — retrieval, evals, RL, fallback all exist elsewhere. The substrate is what's hard: making them work together, per-tenant, under production load, with rollback. Read these as the nine commitments the platform has already made, so applications built on top don't have to.

Built so the on-call rotation doesn't become your problem.

The questions that actually decide whether a stack ships to production aren't about features. They're about what happens at p99, what happens when a provider 429s, what happens when finance asks where the bill came from, and what happens when legal asks where the data sits. Sonzai answers each one before you have to.

Security & isolation by construction

Isolation lives in the storage layer, not the API. BYOK belongs in the platform, not the wrapper. Audit lives in the substrate, not the integration. The boundaries an architect cares about are drawn before the request reaches the model.

The fastest way to die in this space is to lock customers in. So we didn't.

Every place a vendor could insert a wedge — the model, the provider keys, the SDK, the data format, the protocol — we left open. Sonzai is worth using because it's better, not because you can't leave.

The nine questions your architect is going to ask.

We've been through enough security reviews and vendor assessments to know the questions before they're asked. Here's the short answer to each — read this as the section you forward to your platform-ops counterpart.