Create a collection

collection = nebula.create_collection(name="notes", description="My notes")

Store a memory

memory_id = nebula.store_memory({ "collection_id": collection.id, "content": "Machine learning is transforming healthcare", "metadata": {"topic": "AI"} })

Search

results = nebula.search(query="healthcare AI", collection_ids=[collection.id]) for r in results: print(f"{r.score:.2f}: {r.content}")


### JavaScript / TypeScript

```bash
npm install @nebula-ai/sdk

import { Nebula } from '@nebula-ai/sdk';

const nebula = new Nebula({ apiKey: 'your-api-key' });
// Or set NEBULA_API_KEY env var and call new Nebula()

const collection = await nebula.createCollection({
  name: 'notes', description: 'My notes'
});

const memoryId = await nebula.storeMemory({
  collection_id: collection.id,
  content: 'Machine learning is transforming healthcare',
  metadata: { topic: 'AI' }
});

const results = await nebula.search({
  query: 'healthcare AI',
  collection_ids: [collection.id]
});

Core Concepts

Collections: Organizational containers for memories (like projects/workspaces). Always specify collection_id when storing.
Memories: Universal information containers. Three types:
- Document: Entire documents, auto-chunked. Upload text, pre-chunked text, or files (PDF, DOCX, images, audio).
- Conversation: Multi-turn chat. Use memory_id to append messages to the same conversation.
- Simple: Single pieces of information.
Chunks: Individual pieces within a memory (messages in conversations, sections in documents). Each has a unique ID for granular operations.
Search: Hybrid semantic + full-text search with metadata filtering. Scores range 0-1.
Authority: Score (0-1) to prioritize content in search results. Default 0.5.

Authentication

API Key: Get from trynebula.ai -> Settings -> API Keys
Environment variable: NEBULA_API_KEY (auto-read by both SDKs)
Explicit: Pass api_key (Python) or apiKey (JS) to constructor
Base URL: https://api.trynebula.ai (default, configurable via base_url/baseUrl)

Conversation Pattern

Conversations use memory_id to append messages to the same container:

# Python
conv_id = nebula.store_memory({
    "collection_id": "support",
    "content": "Hello!", "role": "assistant"
})
nebula.store_memory({
    "memory_id": conv_id,
    "collection_id": "support",
    "content": "I need help", "role": "user"
})

# Retrieve full conversation
messages = nebula.get_conversation_messages(conv_id)

// JavaScript
const convId = await nebula.storeMemory({
  collection_id: 'support', content: 'Hello!', role: 'assistant'
});
await nebula.storeMemory({
  memory_id: convId, collection_id: 'support',
  content: 'I need help', role: 'user'
});
const messages = await nebula.getConversationMessages(convId);

Search with Filters

results = nebula.search(
    query="bug reports",
    collection_ids=["issues"],
    filters={
        "severity": {"$in": ["critical", "high"]},
        "status": {"$ne": "closed"}
    },
    effort="medium"
)

Operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $like, $ilike, $overlap, $contains, $and, $or. Prefix metadata fields with metadata. in REST API.

For full filter reference, see references/search-and-filtering.md.

Reference Files

Load these as needed for detailed API information:

references/python-sdk.md: Full Python SDK reference (sync + async clients, all methods, error handling)
references/javascript-sdk.md: Full JavaScript/TypeScript SDK reference (all methods, Memory helpers, error handling)
references/search-and-filtering.md: Search configuration, hybrid weights, effort levels, metadata filter operators, authority scores
references/mcp-setup.md: MCP server setup for Cursor, VS Code, Windsurf, Claude Desktop, Claude Code
references/rest-api.md: Direct HTTP/cURL API reference for all endpoints

nebula

Nebula Integration

Quick Start

Python