​
Clusters Guide

Organize and manage memory clusters in Nebula for better organization and access control. Clusters in Nebula are organizational units for your memories. Think of them like projects or workspaces — a way to keep related sets of data grouped together. A cluster doesn’t imply that the memories inside are similar or connected; it’s simply a container you define. For example, you might keep separate clusters for Research, Work Notes, and Personal Ideas. These clusters don’t interact unless you explicitly search or manage across them.
Clusters here are not the same as graph clustering algorithms or automatic similarity-based grouping (We still run them under the hood). They’re a manual, developer-controlled way to structure memory.

​
How It Works

When you create memories, you assign them to specific clusters using the cluster ID. This allows you to:
  1. Store memories in different clusters for manual organization
  2. Search within specific clusters to find relevant information
  3. Keep different types of content separate (e.g., work vs personal, different projects)

​
Creating Clusters

from nebula_client import NebulaClient

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

# Create a cluster
cluster = client.create_cluster(
    name="Research Papers",
    description="Academic research documents",
    metadata={
        "category": "academic",
        "domain": "computer_science"
    }
)
print(f"Created cluster: {cluster.name} with ID: {cluster.id}")

# Create multiple clusters
clusters = [
    client.create_cluster("Business", "Corporate documents"),
    client.create_cluster("Projects", "Project documentation"),
]

​
Managing Memories in Clusters

Store memories in specific clusters using cluster IDs: 
from nebula_client import NebulaClient

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

# Create different clusters for manual separation
work_cluster = client.create_cluster("Work", "Work-related memories")
personal_cluster = client.create_cluster("Personal", "Personal memories")

# Store memories in different clusters using cluster IDs
work_memory = client.store_memory({
    "cluster_id": work_cluster.id,  # Send to work cluster
    "content": "Meeting notes about Q4 planning",
    "metadata": {
        "type": "meeting_notes",
        "date": "2024-01-15"
    }
})

personal_memory = client.store_memory({
    "cluster_id": personal_cluster.id,  # Send to personal cluster
    "content": "Recipe for chocolate chip cookies",
    "metadata": {
        "type": "recipe",
        "cuisine": "dessert"
    }
})

# Store multiple memories to different clusters
memories = [
    {
        "cluster_id": work_cluster.id,  # Work cluster
        "content": "Project deadline is next Friday",
        "metadata": {"priority": "high", "project": "Q4"}
    },
    {
        "cluster_id": personal_cluster.id,  # Personal cluster
        "content": "Book recommendation: 'The Pragmatic Programmer'",
        "metadata": {"category": "books", "genre": "technical"}
    }
]
memory_ids = client.store_memories(memories)

​
Searching Clusters

from nebula_client import NebulaClient

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

# Assuming you have created work_cluster and personal_cluster
work_cluster = client.create_cluster("Work", "Work-related memories")
personal_cluster = client.create_cluster("Personal", "Personal memories")

# Search only in work cluster
work_results = client.search(
    query="project deadlines",
    cluster_ids=[work_cluster.id],  # Only search work memories
    limit=10
)

print(f"Found {len(work_results)} work-related results:")
for result in work_results:
    print(f"- {result.content[:50]}...")

# Search only in personal cluster
personal_results = client.search(
    query="recipe",
    cluster_ids=[personal_cluster.id],  # Only search personal memories
    limit=5
)

print(f"Found {len(personal_results)} personal results:")
for result in personal_results:
    print(f"- {result.content[:50]}...")

# Search across multiple specific clusters
all_results = client.search(
    query="important notes",
    cluster_ids=[work_cluster.id, personal_cluster.id],  # Search both clusters
    limit=15
)

​
Cluster Management

List all clusters: 
from nebula_client import NebulaClient

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

# List clusters
clusters = client.list_clusters(limit=50)

for cluster in clusters:
    print(f"{cluster.name} ({cluster.memory_count} memories)")
    print(f"  Description: {cluster.description}")
    print(f"  Created: {cluster.created_at}")
Update cluster: 
from nebula_client import NebulaClient

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

# Update cluster metadata
updated_cluster = client.update_cluster(
    cluster_id=cluster.id,
    name="Updated Research Papers",
    description="Updated description",
    metadata={
        "category": "updated_category",
        "last_updated": "2024-01-01"
    }
)

​
Best Practices

  • Manual Separation: Create separate clusters for different types of content (work vs personal, different projects, etc.)
  • Consistent Cluster IDs: Always use specific cluster IDs when storing and searching memories
  • Clear Naming: Use descriptive names that make it obvious what each cluster contains
  • Purpose-Driven Organization: Group memories by their intended use or context
  • Targeted Searches: Always specify cluster IDs in your API calls to get relevant results
  • Reasonable Sizes: Keep clusters focused and manageable (avoid putting everything in one cluster)

​
Advanced Examples

Multi-cluster search: 
from nebula_client import NebulaClient

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

# Search across multiple clusters
results = client.search(
    query="machine learning",
    cluster_ids=["research-cluster-1", "research-cluster-2"],
    limit=20
)
Cluster analytics: 
from nebula_client import NebulaClient

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

# Analyze cluster contents
cluster_id = "your-cluster-id"  # Replace with actual cluster ID
cluster = client.get_cluster(cluster_id)
memories = client.list_memories(cluster_ids=[cluster_id], limit=1000)

print(f"Cluster: {cluster.name}")
print(f"Total memories: {len(memories)}")

​
Next Steps