MemoryStack - Node.js SDK

Official Node.js SDK for MemoryStack - The memory layer for AI applications.

What is MemoryStack?

MemoryStack is a semantic memory layer that gives your AI applications persistent, searchable memory. Instead of losing context between conversations, your AI can:

• Remember user preferences, facts, and conversation history
• Search through memories using natural language
• Learn from past interactions to provide personalized responses
• Scale from personal assistants to multi-tenant B2B applications

Think of it as a brain for your AI - it stores information intelligently and retrieves it when needed.

Installation

npm install @memorystack/sdk

Quick Start

import { MemoryStackClient } from '@memorystack/sdk';

const client = new MemoryStackClient({
  apiKey: 'your-api-key',
});

// Store a memory
await client.add('User prefers dark mode');

// Search memories
const results = await client.search('user preferences');
console.log(results.results);

That's it! Two methods - add() and search() - handle 90% of use cases.

Core API

add() - Store Memories

The add() method accepts either a simple string or an array of messages:

// Simple text
await client.add('User likes TypeScript');

// With user ID (for B2B apps)
await client.add('User prefers morning meetings', { userId: 'user_123' });

// Conversation format
await client.add([
  { role: 'user', content: 'What is my favorite color?' },
  { role: 'assistant', content: 'Based on our conversations, you prefer blue!' }
]);

// With metadata
await client.add('Important project deadline is Friday', {
  userId: 'user_123',
  metadata: { category: 'work', priority: 'high' }
});

search() - Find Memories

The search() method finds relevant memories using semantic search:

// Simple search
const results = await client.search('user preferences');

// With user ID filter
const results = await client.search('favorite color', { userId: 'user_123' });

// Limit results
const results = await client.search('meetings', { limit: 5 });

Common Use Cases

Chatbot with Memory

import { MemoryStackClient } from '@memorystack/sdk';
import OpenAI from 'openai';

const memory = new MemoryStackClient({ apiKey: process.env.MEMORYSTACK_API_KEY! });
const openai = new OpenAI();

async function chat(userId: string, message: string) {
  // Get relevant context from memory
  const context = await memory.search(message, { userId, limit: 5 });
  
  // Build prompt with memory context
  const systemPrompt = `You are a helpful assistant. Here's what you remember about this user:
${context.results.map(m => `- ${m.content}`).join('\n')}`;

  // Generate response
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: message }
    ]
  });

  const reply = response.choices[0].message.content!;

  // Save conversation to memory
  await memory.add([
    { role: 'user', content: message },
    { role: 'assistant', content: reply }
  ], { userId });

  return reply;
}

Personal Assistant

// Store preferences
await client.add('I wake up at 6am every day');
await client.add('I prefer coffee over tea');
await client.add('My favorite restaurant is Olive Garden');

// Later, retrieve relevant info
const results = await client.search('morning routine');
// Returns: "I wake up at 6am every day"

const results = await client.search('food preferences');
// Returns: "My favorite restaurant is Olive Garden", "I prefer coffee over tea"

Multi-Tenant B2B App

// Each user has isolated memories
await client.add('Prefers dark mode', { userId: 'alice_123' });
await client.add('Prefers light mode', { userId: 'bob_456' });

// Search only returns that user's memories
const alicePrefs = await client.search('theme preference', { userId: 'alice_123' });
// Returns: "Prefers dark mode"

Additional Methods

While add() and search() cover most needs, the SDK also provides:

// List all memories with pagination
const memories = await client.listMemories({ limit: 50 });

// Get usage statistics
const stats = await client.getStats();
console.log(`Total memories: ${stats.totals.total_memories}`);

// Update a memory
await client.updateMemory('memory-id', { content: 'Updated content' });

// Delete a memory
await client.deleteMemory('memory-id');

Error Handling

import { 
  MemoryStackError, 
  AuthenticationError, 
  RateLimitError,
  ValidationError 
} from '@memorystack/sdk';

try {
  await client.add('Hello world');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, retry later');
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  }
}

Configuration Options

const client = new MemoryStackClient({
  apiKey: process.env.MEMORYSTACK_API_KEY!,
  
  // Optional settings
  baseUrl: 'https://www.memorystack.app',  // Custom API URL
  timeout: 30000,                           // Request timeout (ms)
  enableLogging: true,                      // Enable debug logging
  
  // Retry configuration
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
  }
});

Links

• 🌐 Website: https://memorystack.app
• 📚 Documentation: https://memorystack.app/docs
• 🚀 Quick Start: https://memorystack.app/docs/quickstart
• 💰 Pricing: https://memorystack.app/pricing
• 📧 Support: [email protected]

License

MIT