Skip to main content

​
Conversations Guide

Build chat applications using conversation memories - containers that hold entire conversations.

​
How Conversations Work

Conversations are stored as conversation memories. Each conversation has a memory_id, and you add messages to that container over time.
  • role: Who said the message (user, assistant, etc.)
  • memory_id: The conversation container to append to
  • content: Message text (single message or a list of message objects)
Conversation memories contain the full message history. See Core Concepts for the memory/chunk model.

​
Creating and Adding Messages

from nebula import Nebula
nebula = Nebula(api_key="your-api-key")

# Create conversation with initial message
conv_id = nebula.store_memory({
    "collection_id": "chat-collection",
    "content": "Hello! How can I help?",
    "role": "assistant",
    "metadata": {"conversation_name": "Support Chat"}
})

# Add messages to same conversation
nebula.store_memory({
    "memory_id": conv_id,
    "collection_id": "chat-collection",
    "content": "I need help with my account",
    "role": "user"
})

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

​
Retrieving Conversations

# Get all messages in a conversation
messages = nebula.get_conversation_messages(conv_id)
for msg in messages:
    print(f"[{msg.metadata.get('source_role')}]: {msg.content}")

# List all conversations
conversations = nebula.list_conversations(limit=50)

​
Best Practices

  • Use descriptive metadata: Add conversation_name and topic information
  • Link messages properly: Always use memory_id to maintain conversation flow
  • Organize by collections: Group conversations by purpose or project

​
Next Steps