Collections Guide

A collection is a named container that groups related memories together. You create collections, assign memories to them, and scope searches to them.

Why Use Collections?

Separate contexts: Keep work, personal, and project memories distinct
Targeted search: Search only within relevant collections
Access control: Different API keys can have different collection permissions
Multi-tenancy: Isolate data for different users or customers

Creating Collections

Collection names are case-insensitive. “Work” and “work” are treated as duplicates.

from nebula import Nebula
nebula = Nebula()

collection = nebula.collections.create(
    name="Research Papers",
    description="Academic research documents",
).results

import Nebula from '@nebula-ai/sdk';
const client = new Nebula({ apiKey: process.env.NEBULA_API_KEY });

const { results: collection } = await client.collections.create({
  name: 'Research Papers',
  description: 'Academic research documents',
});

curl -X POST "https://api.zeroset.com/v1/collections" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Research Papers", "description": "Academic research documents"}'

For hosted SaaS workspaces that need graph data stored in customer-owned object storage, create the collection with a workspace storage target. See Customer-Owned Object Storage.

Storing Memories in Collections

Always specify collection_id when storing memories:

nebula.memories.create(
    collection_id=collection.id,
    raw_text="Q4 planning meeting notes",
    metadata={"type": "meeting"},
)

await client.memories.create({
  collection_id: collection.id,
  raw_text: 'Q4 planning meeting notes',
  metadata: { type: 'meeting' },
});

curl -X POST "https://api.zeroset.com/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "collection_id": "COLLECTION_ID",
    "kind": "document",
    "raw_text": "Q4 planning meeting notes",
    "metadata": {"type": "meeting"}
  }'

Searching Within Collections

# Search specific collection
results = nebula.memories.search(query="deadlines", collection_ids=["Work"]).results

# Search multiple collections
results = nebula.memories.search(query="notes", collection_ids=["Work", "Personal"]).results

# Search all accessible collections
results = nebula.memories.search(query="important").results

// Search specific collection
const { results } = await client.memories.search({
  query: 'deadlines',
  collection_ids: ['Work'],
});

// Search multiple collections
const { results: results2 } = await client.memories.search({
  query: 'notes',
  collection_ids: ['Work', 'Personal'],
});

// Search all accessible collections
const { results: results3 } = await client.memories.search({ query: 'important' });

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "deadlines", "collection_ids": ["Work"]}'

Search accepts collection names or UUIDs. When storing memories, collection_id must be a UUID.

Managing Collections

List
Get
Update
Delete

collections = nebula.collections.list(limit=50).results
work_collections = nebula.collections.list(name="Work").results

const { results: collections } = await client.collections.list({ limit: 50 });
const { results: workCollections } = await client.collections.list({ name: 'Work' });

curl -X GET "https://api.zeroset.com/v1/collections?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

collection = nebula.collections.retrieve(collection_id).results

const { results: collection } = await client.collections.retrieve(collectionId);

curl -X GET "https://api.zeroset.com/v1/collections/YOUR_COLLECTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

nebula.collections.update(
    collection.id,
    name="Updated Name",
    description="New description",
)

await client.collections.update(collection.id, {
  name: 'Updated Name',
  description: 'New description',
});

curl -X POST "https://api.zeroset.com/v1/collections/YOUR_COLLECTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Updated Name", "description": "New description"}'

nebula.collections.delete(collection_id)

await client.collections.delete(collectionId);

curl -X DELETE "https://api.zeroset.com/v1/collections/YOUR_COLLECTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting a collection removes its graph data and vector sources. The underlying memory records are disassociated from the collection, not deleted.

Patterns and Tips

Pattern	When to Use
One collection per user	User-specific memory/context
One collection per project	Project-scoped documentation
One collection per data type	Different content types (docs, chats, notes)

​Why Use Collections?

​Creating Collections

​Storing Memories in Collections

​Searching Within Collections

​Managing Collections

​Patterns and Tips

Why Use Collections?

Creating Collections

Storing Memories in Collections

Searching Within Collections

Managing Collections

Patterns and Tips