> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations Guide

> Build chat applications with conversation memories

## How Conversations Work

Conversations are stored as **conversation memories**. Create one with `kind="conversation"` and a `messages` list, then append more messages to the same `memory_id` over time.

* **`kind="conversation"`**: Marks the memory as a conversation (set on `memories.create`).
* **`messages`**: A list of message objects, each with `role` (`user`, `assistant`, or `system`) and `content`.
* **`memory_id`**: The `id` returned from `memories.create()`. Pass it as the first argument to `memories.append()` to add more messages.

<Info>Conversation memories contain the full message history. See [Core Concepts](/guides/concepts) for the memory/source model.</Info>

## Creating and Adding Messages

<CodeGroup>
  ```python Python theme={null}
  from nebula import Nebula
  nebula = Nebula()

  # Get or create your collection
  collection = nebula.collections.create(name="Support Chats").results

  # Create conversation with initial message
  conv = nebula.memories.create(
      collection_id=collection.id,
      kind="conversation",
      messages=[{"content": "Hello! How can I help?", "role": "assistant"}],
      metadata={"conversation_name": "Support Chat"},
  ).results
  conv_id = conv.id

  # Add a message to the same conversation
  nebula.memories.append(
      conv_id,
      collection_id=collection.id,
      messages=[{"content": "I need help with my account", "role": "user"}],
  )

  # Add multiple messages at once
  nebula.memories.append(
      conv_id,
      collection_id=collection.id,
      messages=[
          {"content": "What issue are you having?", "role": "assistant"},
          {"content": "I can't log in", "role": "user"},
      ],
  )
  ```

  ```javascript JavaScript theme={null}
  import Nebula from '@nebula-ai/sdk';
  const client = new Nebula({ apiKey: process.env.NEBULA_API_KEY });

  // Get or create your collection
  const { results: collection } = await client.collections.create({
    name: 'Support Chats',
  });

  // Create conversation
  const { results: conv } = await client.memories.create({
    collection_id: collection.id,
    kind: 'conversation',
    messages: [{ content: 'Hello! How can I help?', role: 'assistant' }],
    metadata: { conversation_name: 'Support Chat' },
  });
  const convId = conv.id;

  // Add a message to the same conversation
  await client.memories.append(convId, {
    collection_id: collection.id,
    messages: [{ content: 'I need help with my account', role: 'user' }],
  });

  // Add multiple messages at once
  await client.memories.append(convId, {
    collection_id: collection.id,
    messages: [
      { content: 'What issue are you having?', role: 'assistant' },
      { content: "I can't log in", role: 'user' },
    ],
  });
  ```

  ```bash cURL theme={null}
  # Create conversation
  curl -X POST "https://api.zeroset.com/v1/memories" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "collection_id": "COLLECTION_ID",
      "kind": "conversation",
      "messages": [{"content": "Hello! How can I help?", "role": "assistant"}]
    }'

  # Append messages (use the id from the create response)
  curl -X POST "https://api.zeroset.com/v1/memories/CONVERSATION_ID/append" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "collection_id": "COLLECTION_ID",
      "messages": [
        {"content": "I need help", "role": "user"},
        {"content": "What issue?", "role": "assistant"}
      ]
    }'
  ```
</CodeGroup>

## Retrieving Conversations

Use `memories.list()` to retrieve conversations with their message chunks, or `memories.retrieve()` for a single conversation.

<CodeGroup>
  ```python Python theme={null}
  # List conversations in a collection — each chunk is one message: {"text", "role"}
  conversations = nebula.memories.list(
      collection_ids=[collection.id],
  ).results
  for conv in conversations:
      for chunk in conv.chunks or []:
          print(f"{chunk['role']}: {chunk['text']}")

  # Get a single conversation
  memory = nebula.memories.retrieve(conv_id).results
  ```

  ```javascript JavaScript theme={null}
  // List conversations in a collection — each chunk is one message: {text, role}
  const { results: conversations } = await client.memories.list({
    collection_ids: [collection.id],
  });
  conversations.forEach(conv =>
    conv.chunks?.forEach(chunk => console.log(`${chunk.role}: ${chunk.text}`))
  );

  // Get a single conversation
  const { results: memory } = await client.memories.retrieve(convId);
  ```

  ```bash cURL theme={null}
  # List memories in a collection
  curl -G "https://api.zeroset.com/v1/memories" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode 'collection_ids=COLLECTION_ID'

  # Get a single conversation
  curl -X GET "https://api.zeroset.com/v1/memories/CONVERSATION_ID" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

## Next Steps

* [Core Concepts](/guides/concepts) - Understanding memories and sources
* [Memory Operations](/guides/memory-operations) - Store and search memories