Matilda
Contact
Client SDK · State and data

Multi-turn conversations.

Carry context across turns with conversationId.

The client SDK does not have a Session class. Multi-turn conversations are managed by passing a conversationId to each chat call. The server reconstructs the full conversation history server-side from the session store.

Pattern

  1. Generate a conversation ID (any unique string, e.g. a UUID).
  2. Pass it to every chat.create() or chat.stream() call.
  3. The server maintains the conversation history — you only send the latest message.
TypeScript
import { randomUUID } from 'node:crypto';
import Matilda from '@maincode-ai/matilda-client-sdk';

const client = new Matilda({ baseUrl: 'https://matilda.maincode.com/api' });

// Authenticate with device flow — token refresh is handled automatically
if (!(await client.auth.getTokens())) {
  await client.auth.loginWithDeviceFlow({ clientId: 'matilda-code' });
}

const conversationId = randomUUID();

// Turn 1
const r1 = await client.chat.create({ input: 'What is the capital of France?', conversationId });
console.log(r1.outputText); // "Paris"

// Turn 2 — server remembers the previous turn
const r2 = await client.chat.create({ input: 'What about Germany?', conversationId });
console.log(r2.outputText); // "Berlin"

// Turn 3
const r3 = await client.chat.create({ input: 'And Italy?', conversationId });
console.log(r3.outputText); // "Rome"

Contrasting with the agent SDK

The Matilda agent SDK provides a Session class that wraps an Agent with auto-managed conversationId, a turns[] array, and session-level defaults. If you need client-side tool execution, approval loops, or session state management, consider the agent SDK. For simple chatbot integrations, the client SDK's conversationId pattern is sufficient.

Retrieving conversation history

TypeScript
// List all conversations
const list = await client.conversations.list({ limit: 50 });

// Retrieve a specific conversation with full message history
const conv = await client.conversations.retrieve(conversationId);
for (const msg of conv.messages) {
  console.log(`[${msg.role}] ${msg.content}`);
}