# Multi-turn conversations

> Carry context across turns with conversationId.

Source: https://maincode.com/docs/client-sdk-multi-turn
Section: Client SDK · Matilda documentation

---

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.

```ts title="conversation.ts"
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](https://maincode.com/docs/agent-sdk-overview) 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

```ts
// 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}`);
}
```