Standalone Memory Layer

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk_your_api_key" });

await client.agents.sessions.start("agent-id", {
  userId: "user-123",
  sessionId: "session-abc",
  userDisplayName: "Alice",
});

const context = await client.agents.getContext("agent-id", {
  userId: "user-123",
  sessionId: "session-abc",
  query: "What should we talk about?", // current user message
});

// context.layers contains:
//   profile     — agent identity, Big5 personality, speech patterns
//   behavioral  — current mood, habits, goals, interests
//   relationship — love scores, narrative arc
//   evolution   — recent personality shifts
//   memory      — recalled facts, long-term summaries
//   proactive   — pending wakeup intents
//   game        — custom game state (if set)

// Build your own system prompt with this context
const systemPrompt = `You are ${context.profile.name}.
Personality: ${JSON.stringify(context.profile.big5)}
Current mood: ${JSON.stringify(context.behavioral.mood)}
Relevant memories: ${context.memory.facts.map(f => f.text).join("\n")}
`;

// Example: using Google Gemini with Sonzai context
import { GoogleGenAI } from "@google/genai";

const gemini = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await gemini.models.generateContent({
  model: "gemini-3.1-flash-lite-preview",
  contents: [
    { role: "user", parts: [{ text: systemPrompt + "\n\n" + userMessage }] },
  ],
});

const assistantMessage = response.text;

const result = await client.agents.process("agent-id", {
  userId: "user-123",
  sessionId: "session-abc",
  messages: [
    { role: "user", content: userMessage },
    { role: "assistant", content: assistantMessage },
  ],
  provider: "gemini",           // our LLM for extraction
  model: "gemini-3.1-flash-lite-preview",
  includeExtractions: true,     // get full extraction details back
});

console.log(result.memories_created);      // 3
console.log(result.side_effects);          // { mood_updated: true, ... }
console.log(result.extractions);           // full details (when requested)

// Extraction includes:
//   memory_facts          — new facts extracted from conversation
//   personality_deltas    — Big5 trait shifts with reasoning
//   mood_delta            — 4D mood change (happiness, energy, calmness, affection)
//   habit_observations    — detected behavioral patterns
//   interests_detected    — topics the user engaged with
//   relationship_delta    — love score change with reason
//   proactive_suggestions — scheduled check-ins or follow-ups
//   emotional_themes      — detected emotional tones

await client.agents.sessions.end("agent-id", {
  userId: "user-123",
  sessionId: "session-abc",
  totalMessages: 12,
  durationSeconds: 600,
});

// List all memories
const memory = await client.agents.memory.list("agent-id", {
  userId: "user-123",
});
// memory.facts — array of extracted atomic facts
// memory.tree  — hierarchical memory structure

// Search memories
const results = await client.agents.memory.search("agent-id", {
  userId: "user-123",
  query: "hiking",
});

// Big5 personality
const personality = await client.agents.personality.get("agent-id");
// { openness: 72, conscientiousness: 65, extraversion: 80, ... }

// Current mood (4D)
const mood = await client.agents.getMood("agent-id", { userId: "user-123" });
// { valence: 0.7, arousal: 0.3, tension: -0.1, affiliation: 0.5 }

// Recent personality shifts
const shifts = await client.agents.personality.recentShifts("agent-id");

// Significant moments (breakthroughs)
const moments = await client.agents.personality.significantMoments("agent-id");

// Goals and breakthroughs
const goals = await client.agents.getGoals("agent-id");
const breakthroughs = await client.agents.getBreakthroughs("agent-id");

// Habits
const habits = await client.agents.getHabits("agent-id", { userId: "user-123" });

// Interests
const interests = await client.agents.getInterests("agent-id");

// Relationships
const relationships = await client.agents.getRelationships("agent-id");

// Daily/weekly consolidation summaries
const summaries = await client.agents.getConsolidation("agent-id", {
  period: "daily",
});

// AI-generated diary entries
const diary = await client.agents.getDiary("agent-id", {
  userId: "user-123",
});

// List pending notifications
const notifications = await client.agents.notifications.list("agent-id");

for (const notif of notifications) {
  // Deliver to user via your channel (push, email, in-app, etc.)
  await deliverToUser(notif.user_id, notif.message);

  // Mark as consumed
  await client.agents.notifications.consume("agent-id", notif.message_id);
}

// View notification history
const history = await client.agents.notifications.history("agent-id");

const models = await client.agents.getModels("agent-id");
// {
//   default_provider: "gemini",
//   default_model: "gemini-3.1-flash-lite-preview",
//   providers: [
//     { provider: "gemini", provider_name: "Google Gemini", default_model: "..." },
//     { provider: "zhipu", provider_name: "Zhipu AI", default_model: "..." },
//     ...
//   ]
// }

{
  "profile": { ... },
  "memory": { ... },
  "knowledge": {
    "results": [
      {
        "content": "Refund policy: customers can request a full refund within 30 days...",
        "label": "Refund Policy",
        "type": "policy",
        "source": "policies.pdf",
        "score": 0.92
      }
    ]
  }
}

const results = await client.agents.knowledgeSearch("agent-id", {
  query: "refund policy",
  limit: 5,
});

for (const result of results.results) {
  console.log(result.label, result.content);
}

import { Sonzai } from "@sonzai-labs/agents";
import { GoogleGenAI } from "@google/genai";

const sonzai = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });
const gemini = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });

async function chat(agentId: string, userId: string, userMessage: string) {
  const sessionId = `session-${Date.now()}`;

  // 1. Start session
  await sonzai.agents.sessions.start(agentId, { userId, sessionId });

  // 2. Get enriched context
  const ctx = await sonzai.agents.getContext(agentId, {
    userId,
    sessionId,
    query: userMessage,
  });

  // 3. Chat with your own LLM
  const completion = await gemini.models.generateContent({
    model: "gemini-3.1-flash-lite-preview",
    contents: [
      { role: "user", parts: [{ text: buildPrompt(ctx) + "\n\n" + userMessage }] },
    ],
  });
  const reply = completion.text!;

  // 4. Process — extract memories, mood, personality, habits
  const result = await sonzai.agents.process(agentId, {
    userId,
    sessionId,
    messages: [
      { role: "user", content: userMessage },
      { role: "assistant", content: reply },
    ],
    provider: "gemini",
    includeExtractions: true,
  });

  console.log(`Memories created: ${result.memories_created}`);
  console.log(`Mood updated: ${result.side_effects.mood_updated}`);

  // 5. End session
  await sonzai.agents.sessions.end(agentId, {
    userId,
    sessionId,
    totalMessages: 2,
    durationSeconds: 30,
  });

  return reply;
}

function buildPrompt(ctx: any): string {
  return `You are ${ctx.profile?.name || "an AI companion"}.
Personality: ${JSON.stringify(ctx.profile?.big5 || {})}
Mood: ${JSON.stringify(ctx.behavioral?.mood || {})}
Memories:\n${(ctx.memory?.facts || []).map((f: any) => `- ${f.text}`).join("\n")}
`;
}