​
Conversations Guide

Create and manage conversational AI interactions using Nebula’s conversation system for context-aware chat experiences. Conversations are not a separate storage type—they are regular memories differentiated by message role. You “toggle” conversation behavior by providing a role field when using store_memory() or store_memories() (and optionally linking turns with parent_id). Storage, indexing, and retrieval work the same way as normal memories; the primary differentiator is the speaker via the role parameter (e.g., user, assistant).

​
Understanding Conversations

Conversations in Nebula are persistent chat sessions that maintain context and history. They enable:
  • Contextual AI Responses: AI remembers previous messages in the conversation
  • Document Integration: Reference documents and collections for informed responses
  • Multi-turn Interactions: Build complex conversations over multiple exchanges
  • History Management: Track and review conversation history
Purpose: Conversations store conversational data for raw text retrieval, focusing on chronological flow and context, while memory operations are optimized for semantic search across stored information. Under the hood, both are stored the same; use conversations when you need roles and turn-by-turn context.
Use conversations when you need to capture the speaker with a role and link turns via parent_id. See the examples under “Conversation messages” in the Memory Operations guide for how to store conversational memories with store_memory()/store_memories().

​
Creating Conversations

Conversations are created implicitly when you store the first message with a role. Use store_memory() or store_memories() to create and manage conversations. 
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Create a cluster first
cluster = client.create_cluster(
    name="Research Discussions",
    description="Cluster for research-related conversations"
)

# Create a conversation by storing the first message
conversation_id = client.store_memory({
    "cluster_id": cluster.id,
    "content": "Starting a research discussion about AI",
    "role": "assistant",
    "metadata": {
        "conversation_name": "Research Discussion",
        "topic": "artificial_intelligence"
    }
})
print(f"Created conversation with ID: {conversation_id}")

​
Sending Messages

Use store_memory() or store_memories() to add messages to existing conversations. Provide the conversation ID as the parent_id parameter. 
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Add a message to an existing conversation
conversation_id = client.store_memory({
    "cluster_id": "your-cluster-id",
    "content": "Hello, how can you help me?",
    "role": "user",
    "parent_id": "conversation-uuid"  # Existing conversation ID
})
print(f"Added message to conversation: {conversation_id}")

# Add multiple messages at once
message_ids = client.store_memories([
    {
        "cluster_id": "your-cluster-id",
        "content": "Hello, how can you help me?",
        "role": "user",
        "parent_id": "conversation-uuid"
    },
    {
        "cluster_id": "your-cluster-id",
        "content": "I'd be happy to help! What do you need assistance with?",
        "role": "assistant",
        "parent_id": "conversation-uuid"
    }
])
print(f"Added {len(message_ids)} messages to conversation")

​
Managing Conversation History

Get conversation history: 
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Get conversation messages
messages = client.get_conversation_messages("conversation-uuid")

print(f"Conversation history ({len(messages)} messages):")
for message in messages:
    role = message.metadata.get("source_role", message.metadata.get("role", "unknown")).upper()
    content = message.content[:100] + "..." if len(message.content) > 100 else message.content
    print(f"  [{role}]: {content}")
    print(f"    Created: {message.created_at}")
    print(f"    ID: {message.id}")

​
Conversation Management

List conversations: 
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

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

print(f"Found {len(conversations)} conversations:")
for conv in conversations:
    conversation_name = conv.get("name", "Unnamed Conversation")
    print(f"{conversation_name}")
    print(f"  Created: {conv.get('created_at', 'Unknown')}")
    print(f"  ID: {conv.get('id')}")
    print()

# List conversations filtered by cluster
filtered_conversations = client.list_conversations(
    limit=20,
    cluster_ids=["your-cluster-id"]
)
print(f"Found {len(filtered_conversations)} conversations in specified clusters")

​
Update Conversation Metadata

The Python SDK does not currently support updating existing conversation metadata or message content. This functionality is planned for future releases.
If you need to modify conversation metadata, you would need to:
  1. Create a new conversation with the updated metadata
  2. Copy existing messages to the new conversation (if supported by future API)
  3. Update your application to reference the new conversation ID
For now, consider conversation metadata as immutable once created.

​
Best Practices

  • Clear Titles: Use descriptive titles for easy identification
  • Metadata Strategy: Use metadata to categorize conversations
  • Context Management: Include relevant documents and collections
  • Message Limits: Keep conversations at a reasonable size
  • Regular Cleanup: Archive or delete old conversations

​
Next Steps