​
Node.js Client

The official Node.js client library for the Nebula Memory API provides a simple and intuitive interface for storing, retrieving, and searching memories with advanced clustering capabilities.

​
Installation & Setup

Install: 
npm install @nebula-ai/sdk
Environment setup: 
export NEBULA_API_KEY="your_api_key_here"

​
Client Initialization

Basic usage: 
import { NebulaClient } from '@nebula-ai/sdk';
// or
const { NebulaClient } = require('@nebula-ai/sdk');

const client = new NebulaClient({
  apiKey: 'your_api_key_here'
});
Advanced configuration: 
const client = new NebulaClient({
  apiKey: 'your_api_key_here',
  baseUrl: 'https://api.nebulacloud.app', // Default
  timeout: 30000 // Default timeout in ms
});

​
Cluster Management

Create cluster: 
const cluster = await client.createCluster({
  name: 'research_notes',
  description: 'Cluster for research-related memories',
  metadata: { category: 'academic', priority: 'high' }
});
Get cluster: 
const cluster = await client.getCluster('cluster_id_here');
List clusters: 
const clusters = await client.listClusters({
  limit: 100, // Default: 100
  offset: 0   // Default: 0
});
Update cluster: 
const updatedCluster = await client.updateCluster({
  clusterId: 'cluster_id_here',
  name: 'new_name', // Optional
  description: 'new_description', // Optional
  metadata: { updated: true } // Optional
});
Delete cluster: 
const success = await client.deleteCluster('cluster_id_here');

​
Memory Storage

Store memory: 
// Using plain object (recommended)
const memoryId = await client.storeMemory({
  cluster_id: 'user_preferences', // Required
  content: 'User prefers email communication over phone calls',
  metadata: {
    userId: 'user_123',
    preferenceType: 'communication',
    importance: 'high'
  }
});

// Using Memory interface
const memory = {
  cluster_id: 'user_preferences',
  content: 'User prefers email communication over phone calls',
  role: undefined,
  parent_id: undefined,
  metadata: {
    userId: 'user_123',
    preferenceType: 'communication'
  }
};
const memoryId = await client.storeMemory(memory);
Store conversation message: 
const messageId = await client.storeMemory({
  cluster_id: 'conversations',
  content: 'Hello, how can I help you?',
  role: 'assistant', // For conversation messages
  parent_id: 'conv_123', // Optional conversation ID
  metadata: { session: 'user_session' }
});
Store multiple memories: 
const memories = [
  {
    cluster_id: 'research',
    content: 'AI research findings',
    metadata: { topic: 'ai' }
  },
  {
    cluster_id: 'research',
    content: 'Machine learning insights',
    metadata: { topic: 'ml' }
  }
];

const memoryIds = await client.storeMemories(memories);

​
Memory Retrieval

Get specific memory: 
const memory = await client.getMemory('memory_id_here');
List memories: 
const memories = await client.listMemories(
  ['cluster_123', 'cluster_456'], // Required array of cluster IDs
  100, // limit (optional, default: 100)
  0    // offset (optional, default: 0)
);
Get cluster memories: 
const memories = await client.getClusterMemories({
  clusterId: 'cluster_id_here',
  limit: 100,    // Default: 100
  offset: 0      // Default: 0
});

​
Search Operations

Search memories: 
const results = await client.search({
  query: 'artificial intelligence',
  cluster_ids: ['research_cluster'],         // Required
  limit: 10,                                 // Default: 10
  retrievalType: 'simple',                   // Default: 'simple'
  filters: { 'metadata.topic': 'ai' }        // Optional
});
Search types:
  • simple: Basic semantic search
  • reasoning: Enhanced reasoning-based search
  • planning: Planning-oriented search

​
Memory Management

Delete memory: 
const success = await client.delete('memory_id_here');

​
TypeScript Interfaces

Memory interface (for writing): 
interface Memory {
  cluster_id: string;        // Required: cluster to store in
  content: string;           // Required: text content
  role?: string;             // Optional: 'user', 'assistant', or custom (for conversations)
  parent_id?: string;        // Optional: conversation ID (for conversations)
  metadata?: Record<string, any>; // Optional: additional metadata
}
MemoryResponse interface (for reading): 
interface MemoryResponse {
  id: string;
  content?: string;
  chunks?: string[];
  metadata: Record<string, any>;
  cluster_ids: string[];
  created_at?: string;
  updated_at?: string;
}

​
Error Handling

Exception types:
  • NebulaException - Base exception
  • NebulaClientException - Client-side errors
  • NebulaAuthenticationException - Authentication errors
  • NebulaRateLimitException - Rate limiting errors
  • NebulaValidationException - Validation errors
Error handling: 
try {
  const memory = await client.storeMemory({
    content: 'Test memory',
    cluster_id: 'test_cluster'
  });
} catch (error) {
  if (error instanceof NebulaAuthenticationException) {
    console.error('Invalid API key');
  } else if (error instanceof NebulaRateLimitException) {
    console.error('Rate limit exceeded');
  } else if (error instanceof NebulaValidationException) {
    console.error('Validation error:', error.message);
  } else if (error instanceof NebulaException) {
    console.error('API error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Quick Example

const { NebulaClient } = require('@nebula-ai/sdk');

(async () => {
  const client = new NebulaClient({ apiKey: 'your_api_key' });

  // Create cluster and store memory
  const cluster = await client.createCluster({
    name: 'customer_support',
    description: 'Customer support interactions'
  });

  const memory = await client.storeMemory({
    content: 'Customer prefers email communication over phone calls',
    cluster_id: cluster.id,
    metadata: { userId: 'user_123', preferenceType: 'communication' }
  });

  // Search
  const results = await client.search({
    query: 'communication preferences',
    cluster_ids: [cluster.id],
    limit: 5
  });

  console.log('Search results:', results.length);
})();

​
Next Steps