@memory-os/sdk

Official SDK for MemoryOS - Persistent semantic memory for AI applications.

Installation

npm install @memory-os/sdk

Quick Start

import { MemoryOS } from '@memory-os/sdk';

const memory = new MemoryOS({ apiKey: 'mos_live_xxx' });

// Store a memory
await memory.store({
  content: 'User mentioned they prefer morning meetings',
  tier: 'long',
  importance: 0.8
});

// Semantic search
const results = await memory.search('meeting preferences');
console.log(results.results);

// Get context for LLM prompts
const { context } = await memory.getContext('What time does the user prefer meetings?');
console.log(context);

API Reference

Constructor

const memory = new MemoryOS({
  apiKey: 'mos_live_xxx',     // Required
  baseUrl: 'https://...',     // Optional, for self-hosted
  timeout: 30000              // Optional, request timeout in ms
});

Memory Operations

store(input) - Store a new memory

const memory = await client.store({
  content: 'The user likes TypeScript',
  tier: 'long',        // 'short' | 'medium' | 'long'
  importance: 0.9,     // 0-1
  metadata: { source: 'chat' }
});

get(id) - Get a memory by ID

const memory = await client.get('memory-uuid');

update(id, input) - Update a memory

await client.update('memory-uuid', {
  importance: 1.0,
  metadata: { verified: true }
});

delete(id) - Delete a memory

await client.delete('memory-uuid');

list(options?) - List memories

const { data, meta } = await client.list({
  limit: 50,
  offset: 0,
  tier: 'long',
  sort_by: 'created_at',
  sort_order: 'desc'
});

Search Operations

search(query, options?) - Semantic search

const results = await client.search('user preferences', {
  threshold: 0.3,  // Similarity threshold (default: 0.3)
  limit: 10,       // Max results
  tier: 'long'     // Filter by tier
});

results.results.forEach(r => {
  console.log(r.content, r.similarity);
});

getContext(query, options?) - Get LLM context

const { context, memories, token_count } = await client.getContext(
  'What are the user preferences?',
  { maxTokens: 2000 }
);

// Use in your LLM prompt
const prompt = `Context:\n${context}\n\nQuestion: ${userQuestion}`;

Utility Operations

getUsage() - Get usage statistics

const stats = await client.getUsage();
console.log(stats.memories.total);

health() - Check API health

const { status, latency_ms } = await client.health();

Memory Tiers

| Tier | Duration | Use Case | |------|----------|----------| | short | Hours | Session context, temporary notes | | medium | Days | Recent interactions, short-term preferences | | long | Permanent | Core facts, important preferences |

Error Handling

import { MemoryOS, MemoryOSError } from '@memory-os/sdk';

try {
  await memory.store({ content: 'test' });
} catch (error) {
  if (error instanceof MemoryOSError) {
    console.error(error.code);      // 'UNAUTHORIZED', 'RATE_LIMITED', etc.
    console.error(error.message);   // Human-readable message
    console.error(error.requestId); // For debugging
  }
}

TypeScript

Full TypeScript support with exported types:

import type {
  Memory,
  CreateMemoryInput,
  SearchResult,
  ContextResponse,
  MemoryTier
} from '@memory-os/sdk';

License

MIT