Sonzai Docs

Memory & Context

Agents remember what matters. Every conversation is analyzed to extract facts, events, and commitments — stored and recalled automatically.

Memory Categories

Memories are stored in four categories:

FactsPermanent knowledge: user preferences, personal details, background. Example: 'User is a software engineer who loves Thai food.'
EventsEpisodic memories of shared experiences. Example: 'We talked about their trip to Japan last week.'
CommitmentsPromises and plans the agent made. Example: 'Promised to ask about their job interview next time.'
SummariesConsolidated conversation summaries. Auto-generated between sessions.

How Memory Works

Memory is fully automatic — you don't need to manage it. The platform analyzes each conversation and extracts facts, events, and commitments. Before each response, the most relevant memories are assembled and included in context automatically.

No orchestration needed

Just call chat. The platform handles memory extraction, storage, and retrieval on every interaction.

Seed Memory

Pre-load what an agent knows about a user before their first conversation using memory.seed().

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

const client = new Sonzai({ apiKey: "sk-..." });

await client.agents.memory.seed("agent-id", "user-123", {
  facts: [
    "User's name is Jane Smith",
    "Jane is a senior product manager at Acme Corp",
    "Jane lives in San Francisco and enjoys hiking",
  ],
});

Search Memory

Search memories for a user-agent pair by keyword or semantic query.

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

for (const mem of results.memories) {
  console.log(mem.content, mem.type, mem.createdAt);
}

List & Browse

List all memories or browse them by category.

// List all memories (paginated)
const memories = await client.agents.memory.list("agent-id", {
  userId: "user-123",
  type: "fact",   // "fact" | "event" | "commitment" | "summary"
  limit: 20,
  offset: 0,
});

// Browse by category
const facts = await client.agents.memory.listFacts("agent-id", {
  userId: "user-123",
});

Memory Timeline

Get a chronological view of a user's memory history.

const timeline = await client.agents.memory.timeline("agent-id", {
  userId: "user-123",
  from: "2026-01-01",
  to:   "2026-03-31",
});

for (const entry of timeline.entries) {
  console.log(entry.date, entry.summary);
}

Browse Memory Tree

Navigate the hierarchical memory structure for a user.

// Browse the memory tree at a given path
const nodes = await client.agents.memory.browse("agent-id", {
  userId: "user-123",
  path: "/facts",   // optional: filter by path
});

Reset Memory

Clear all memories for a user-agent pair — useful for testing or when a user wants a fresh start.

await client.agents.memory.reset("agent-id", {
  userId: "user-123",
});
← Personality SystemEmotions & Mood→