JavaScript SDK

Installation

npm install memoid
# or
pnpm add memoid
# or
yarn add memoid

Quick Start

import { MemoryClient } from 'memoid';

const client = new MemoryClient('your-api-key');

// Add memory
await client.add({
  messages: [
    { role: 'user', content: 'I love hiking' }
  ],
  userId: 'user_123'
});

// Search
const results = await client.search({
  query: 'hobbies',
  userId: 'user_123'
});

Client Configuration

import { MemoryClient } from 'memoid';

const client = new MemoryClient('your-api-key', {
  baseUrl: 'https://api.memoid.dev', // Custom endpoint
  timeout: 30000, // Request timeout in ms
});

Memory Operations

Add Memories

const result = await client.add({
  messages: [
    { role: 'user', content: 'My name is Alex' },
    { role: 'assistant', content: 'Nice to meet you!' }
  ],
  userId: 'user_123',
  agentId: 'assistant_1', // Optional
  metadata: { source: 'chat' }, // Optional
  infer: true, // Extract facts (default)
  extractGraph: false // Extract entities (default)
});

result.memories.forEach(m => {
  console.log(`Added: ${m.memory}`);
});

List Memories

const memories = await client.list({
  userId: 'user_123',
  limit: 50
});

memories.forEach(m => {
  console.log(`${m.id}: ${m.memory}`);
});

Get Memory

const memory = await client.get('mem_abc123');
console.log(memory.memory);

Update Memory

await client.update('mem_abc123', {
  memory: 'Updated text',
  metadata: { updated: true }
});

Delete Memory

await client.delete('mem_abc123');

Delete All

await client.deleteAll({ userId: 'user_123' });

Search

const results = await client.search({
  query: 'What does the user like?',
  userId: 'user_123',
  limit: 10,
  threshold: 0.7
});

results.forEach(r => {
  console.log(`${r.memory} (score: ${r.score.toFixed(2)})`);
});

Knowledge Graph

Extract Knowledge

const result = await client.extractKnowledge({
  text: 'John works at Acme Corp',
  store: true
});

result.entities.forEach(e => {
  console.log(`Entity: ${e.name} (${e.type})`);
});

Add Entity

await client.addEntity({
  name: 'Acme Corp',
  type: 'organization',
  attributes: { industry: 'tech' }
});

Add Relationship

await client.addRelationship({
  source: 'John',
  relation: 'works_at',
  target: 'Acme Corp'
});

Query Graph

const result = await client.graphQuery({
  entity: 'John',
  depth: 2
});

result.entities.forEach(e => console.log(e.name));

TypeScript Types

import type {
  Memory,
  SearchResult,
  Entity,
  Relationship,
  AddOptions,
  SearchOptions
} from 'memoid';

const memory: Memory = {
  id: 'mem_123',
  memory: 'User likes hiking',
  userId: 'user_123',
  createdAt: new Date()
};

Error Handling

import { MemoryClient, MemoidError, RateLimitError } from 'memoid';

const client = new MemoryClient('your-api-key');

try {
  await client.add({ messages: [...], userId: 'user_123' });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof MemoidError) {
    console.log(`Error: ${error.message}`);
  }
}

Complete Example

import OpenAI from 'openai';
import { MemoryClient } from 'memoid';

const memory = new MemoryClient('memoid-key');
const openai = new OpenAI({ apiKey: 'openai-key' });

async function chat(userId: string, message: string): Promise<string> {
  // Get context
  const memories = await memory.search({
    query: message,
    userId,
    limit: 5
  });

  const context = memories.map(m => `- ${m.memory}`).join('\n');

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

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

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

  return reply;
}