Skip to main content

​
Conversations Guide

Create and manage conversational AI interactions with context-aware chat experiences using Nebula’s memory system.

​
How Conversations Work

Conversations are stored as conversation memories - containers that hold entire conversations with all their messages. Each conversation gets its own memory ID, and you add messages to that container using store_memory():
  • role: Speaker identifier (user, assistant, etc.)
  • memory_id: The conversation container to add messages to
  • content: The message text (can be single message or multiple messages)
A conversation memory contains the complete chat history. Use memory_id to add messages to the same conversation container. See Core Concepts to understand how memories work.

​
Creating Conversations

from nebula import Nebula

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

# Create conversation with initial message
conversation_memory_id = nebula.store_memory({
    "collection_id": "chat-collection",
    "content": "Hello! How can I help you today?",
    "role": "assistant",
    "metadata": {
        "conversation_name": "Support Chat",
        "topic": "customer_support"
    }
})
# This creates a conversation container

​
Adding Messages

Add more messages to the conversation container: 
# Add single message to conversation
nebula.store_memory({
    "memory_id": conversation_memory_id,  # Same conversation container
    "collection_id": "chat-collection",
    "content": "I need help with my account",
    "role": "user"
})

# Add multiple messages to same conversation
nebula.store_memory({
    "memory_id": conversation_memory_id,  # Same container
    "collection_id": "chat-collection",
    "content": [
        {
            "content": "What specific issue are you having?",
            "role": "assistant"
        },
        {
            "content": "I can't log in to my account",
            "role": "user"
        }
    ]
})
# The conversation now contains all 4 messages

​
Retrieving Messages

# Get entire conversation (all messages)
messages = nebula.get_conversation_messages(conversation_memory_id)

for message in messages:
    role = message.metadata.get('source_role', 'unknown')
    print(f"[{role.upper()}]: {message.content}")

​
Listing Conversations

# List conversations
conversations = nebula.list_conversations(limit=50, offset=0)

for conv in conversations:
    name = conv.get("name", "Unnamed Conversation")
    print(f"{name} - ID: {conv.get('id')}")

# Filter by collection
filtered_conversations = nebula.list_conversations(
    collection_ids=["chat-collection"]
)

​
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
  • Consider message limits: Keep conversations at reasonable sizes for performance

​
Next Steps