Skip to main content

​
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/source model.

​
Creating and Adding Messages

from nebula import Nebula, Memory
nebula = Nebula()

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

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

# Add messages to same conversation
nebula.store_memory(
    Memory(
        memory_id=conv_id,
        collection_id=collection.id,
        content="I need help with my account",
        role="user"
    )
)

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

​
Retrieving Conversations

Use list_memories() to retrieve conversations with message roles, or get_memory() for a single conversation’s metadata. 
# List conversations in a collection (includes message roles)
conversations = nebula.list_memories(
    collection_ids=[collection.id]
)
for conv in conversations:
    for source in conv.sources or []:
        print(f"[{source.role}]: {source.content}")

# Get a single conversation's metadata
memory = nebula.get_memory(conv_id)

​
Next Steps