Mem0 Node.js / TypeScript SDK Reference

Complete reference for the mem0ai npm package. Covers both the Platform client (managed API) and the Open Source self-hosted variant.

---

Platform Client

Installation

npm install mem0ai
export MEM0_API_KEY="m0-your-api-key"

MemoryClient

import MemoryClient from 'mem0ai';

const client = new MemoryClient({ apiKey: 'm0-xxx' });

Constructor: new MemoryClient({ apiKey }). If apiKey is not provided, reads from MEM0_API_KEY environment variable.

• HTTP library: axios
• Timeout: 60 seconds
• Base URL: https://api.mem0.ai
• All methods are async (return Promise)

---

Memory Methods

add(messages, options?)

Store new memories from messages.

const messages = [
    { role: 'user', content: "I'm a vegetarian and allergic to nuts." },
    { role: 'assistant', content: "Got it! I'll remember that." },
];
await client.add(messages, { userId: 'alice' });

Returns: Promise<any> -- list of events

search(query, options?)

Search memories by semantic similarity.

const results = await client.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 20 });
for (const mem of results.results) {
    console.log(mem.memory, mem.score);
}

Returns: Promise<SearchResult> -- {results: [{id, memory, score, ...}]}

get(memoryId)

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

getAll(options?)

Retrieve all memories. Requires at least one entity identifier in filters.

const memories = await client.getAll({ filters: { user_id: 'alice' } });
// With filters
const filtered = await client.getAll({
    filters: { AND: [{ user_id: 'alice' }, { categories: { contains: 'health' } }] },
});

update(memoryId, data)

await client.update('ea925981-...', { text: 'Updated: vegan since 2024' });
await client.update('ea925981-...', { text: 'Updated', metadata: { verified: true } });

delete(memoryId)

await client.delete('ea925981-...');

deleteAll(options?)

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

history(memoryId)

const history = await client.history('ea925981-...');
// Returns: [{previousValue, newValue, action, timestamps}]

---

Batch Methods

batchUpdate(memories)

await client.batchUpdate([
    { memoryId: 'uuid-1', text: 'Updated text' },
    { memoryId: 'uuid-2', text: 'Another update' },
]);

batchDelete(memories)

await client.batchDelete(['uuid-1', 'uuid-2', 'uuid-3']);

---

User/Entity Management

users()

const users = await client.users();
// Returns: {results: [{type: "user", name: "alice"}, ...]}

deleteUser(data) / deleteUsers(data)

await client.deleteUser({ userId: 'alice' });  // Single entity
await client.deleteUsers({ agentId: 'bot-1' }); // Flexible

---

Project Management

// Get project config
const config = await client.getProject({ fields: ['customCategories'] });

// Update project settings
await client.updateProject({
    customInstructions: 'Extract dietary preferences and health info',
    customCategories: [{ health: 'Medical and dietary info' }],
});

---

Webhooks

// List
const webhooks = await client.getWebhooks({ projectId: 'proj_123' });

// Create
const webhook = await client.createWebhook({
    url: 'https://your-app.com/webhook',
    name: 'Memory Logger',
    projectId: 'proj_123',
    eventTypes: ['memory_add', 'memory_update'],
});

// Update
await client.updateWebhook({
    webhookId: 'wh_123',
    name: 'Updated Logger',
    url: 'https://new-url.com',
});

// Delete
await client.deleteWebhook({ webhookId: 'wh_123' });

---

Feedback

await client.feedback({
    memoryId: 'mem-123',
    feedback: 'POSITIVE',
    feedbackReason: 'Accurately captured preference',
});

---

Export

const exportReq = await client.createMemoryExport({
    schema: JSON.stringify({ type: 'object', properties: { name: { type: 'string' } } }),
    filters: { user_id: 'alice' },
});

const result = await client.getMemoryExport({ memoryExportId: exportReq.id });

---

TypeScript Types

Key interfaces from mem0.types.ts:

interface Message { role: string; content: string; }
interface Memory { id: string; memory: string; userId: string; categories: string[]; score?: number; /* ... */ }
interface MemoryOptions { userId?: string; agentId?: string; appId?: string; runId?: string; metadata?: object; /* ... */ }
interface SearchOptions { filters?: object; topK?: number; rerank?: boolean; threshold?: number; /* ... */ }
interface MemoryHistory { id: string; memoryId: string; previousValue: string; newValue: string; action: string; /* ... */ }
interface FeedbackPayload { memoryId: string; feedback: string; feedbackReason?: string; }
interface WebhookCreatePayload { url: string; name: string; projectId: string; eventTypes: string[]; }

---

Open Source / Self-Hosted

Installation

npm install mem0ai

Memory Class

import { Memory } from 'mem0ai/oss';

const m = new Memory();  // Uses default config

Import: from 'mem0ai/oss' (NOT the default export -- that is MemoryClient for Platform)

Configuration

const config = {
    llm: {
        provider: 'openai',        // openai, groq, anthropic, google, ollama, lmstudio, mistral, azure
        config: {
            model: 'gpt-5-mini',
            apiKey: 'sk-xxx',
        },
    },
    embedder: {
        provider: 'openai',        // openai, ollama, lmstudio, google, azure, langchain, anthropic
        config: {
            model: 'text-embedding-3-small',
            apiKey: 'sk-xxx',
        },
    },
    vectorStore: {
        provider: 'qdrant',        // memory, qdrant, redis, supabase, langchain, azure_ai_search, pgvector
        config: {
            collectionName: 'my_memories',
            host: 'localhost',
            port: 6333,
        },
    },
    historyDbPath: 'history.db',
    customInstructions: '...',
    disableHistory: false,
};

const m = new Memory(config);
// Or from dict with validation:
const m2 = Memory.fromConfig(config);

Methods

All methods are async (return Promise):

add(messages, config)

await m.add('I prefer dark mode', { userId: 'alice' });
await m.add([
    { role: 'user', content: 'I like hiking' },
    { role: 'assistant', content: 'Great outdoor activity!' },
], { userId: 'alice' });

Returns: Promise<{results: [...], relations?: [...]}>

search(query, config)

const results = await m.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 5 });

get(memoryId) / getAll(config) / update(memoryId, data) / delete(memoryId) / deleteAll(config) / history(memoryId)

Same interface patterns. Note: OSS update takes a string for data, not an object.

await m.update('mem-id', 'new content');

reset()

Clear the entire vector store and history.

await m.reset();

---

Key Differences: Platform vs OSS

---

v2 Compatibility

If you're using SDK v2.x:

Naming Changes:

• Top-level params now use camelCase: topK, rerank (not top_k)
• Filter keys use snake_case: user_id, agent_id
• OSS: limit renamed to topK

API Changes:

// v2 - top-level entity IDs, snake_case
await client.search("query", { user_id: "alice", top_k: 20 });

// v3 - filters object with snake_case keys, camelCase top-level params
await client.search("query", { filters: { user_id: "alice" }, topK: 20 });

Default Changes:

Removed:

• OutputFormat and API_VERSION enums
• organizationId, projectId from constructor
• enableGraph, asyncMode, outputFormat, immutable, expirationDate, filterMemories, batchSize, forceAddOnly, includes, excludes, keywordSearch

See the v2 to v3 migration guide for details.