@molroo-io/sdk

Thin Client SDK for molroo emotion engine

Simplified API client with LLM integration for the molroo emotion engine.

Quick Start

import { Molroo } from '@molroo-io/sdk';
import { createOpenAI } from '@ai-sdk/openai';

const molroo = new Molroo({ apiKey: 'mk_live_...' });

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

// Create persona from description
const sera = await molroo.createPersona(
  'A kind and curious barista named Sera who remembers customer names',
  { llm: openai }
);

// Chat
let history: Message[] = [];
const result = await sera.chat('Hello!', { history });
console.log(result.text);  // "Hello! Welcome to our cafe."
history = result.updatedHistory;  // Manage externally

Installation

npm install @molroo-io/sdk
npm install ai @ai-sdk/openai  # or @ai-sdk/anthropic, @ai-sdk/google-vertex

Features

• Unified API — Molroo class for persona and world management
• Vercel AI SDK Integration — Use any LLM provider (OpenAI, Anthropic, Google, etc.)
• External History Management — Simple mode: manage conversation history yourself
• Advanced Memory (Optional) — Implement MemoryAdapter for semantic search, reflections
• World Simulation — Multi-agent environments with channels and interactions

Usage Modes

1. Simple Mode (External History)

const molroo = new Molroo({ apiKey: 'mk_...' });
const sera = await molroo.createPersona('...', { llm: openai });

let history = [];
const result = await sera.chat('Hello', { history });
history = result.updatedHistory;

2. Advanced Mode (MemoryAdapter)

class MyPostgresAdapter implements MemoryAdapter {
  async saveEpisode(episode: Episode): Promise<void> {
    // Save to PostgreSQL
  }
  
  async recall(query: RecallQuery): Promise<Episode[]> {
    // Query by filters
  }
  
  async semanticRecall(query: string): Promise<Episode[]> {
    // Vector similarity search
  }
}

const sera = await molroo.createPersona('...', {
  llm: openai,
  memory: new MyPostgresAdapter()
});

World Simulation

const world = await molroo.createWorld({ name: 'Cafe' });
const sera = await molroo.createPersona('Barista Sera', { llm: openai });
await world.addPersona({ personaConfigId: sera.id, config: {...} });

Migration from v0.5.x

Breaking Changes

1. Unified create() method

   // Before
   await MolrooPersona.create({...}, {personality: {...}});
   await MolrooPersona.generate({...}, "description");
      
   // After
   await molroo.createPersona({personality: {...}}, {llm});
   await molroo.createPersona("description", {llm});

2. External history management

   // Before
   await persona.chat("Hello");  // MemoryAdapter required
      
   // After
   let history = [];
   const result = await persona.chat("Hello", {history});
   history = result.updatedHistory;

3. Vercel AI SDK directly

   // Before
   createVercelAIAdapter({provider: 'openai', ...})
      
   // After
   createOpenAI({...})  // Pass directly

4. Removed adapter implementations

   • SQLite, Supabase, Pinecone adapters removed
   • Implement MemoryAdapter interface yourself
   • Or wait for API-hosted memory (coming soon)

API Reference

See API documentation for full reference.

License

MIT