Overview

• Writes are queued. memories.add returns an event_id with status PENDING, because extraction runs in the background. Poll events.get until the status is SUCCEEDED or FAILED. Passing infer: false stores the messages verbatim instead, which answers immediately with the stored memories.
• A queued delete finishes before its event updates. memories.deleteAll answers with an event_id, but that event can still read PENDING after the memories are gone. To confirm a delete, re-read with memories.list and check that count is 0, passing show_expired: true and wrapping the scope in filters. Both are needed: without show_expired an expired memory is hidden, and memories.list rejects a filter with no entity ID, so a delete scoped only by metadata, org_id or project_id cannot be re-read this way. For those, check events.get instead.
• Entity IDs. A memory belongs to a user, agent, app or run. memories.add takes those IDs at the top level; memories.search and memories.list require them inside filters, and Mem0 rejects a top-level entity ID with 400.
• Deletes are permanent. memories.delete removes one memory, and memories.deleteAll removes every memory matching a filter. Mem0 queues memories.deleteAll and answers before the deletion happens. Neither can be undone.
• The run ID has two names. memories.list returns it as session_id and memories.search returns the same value as run_id.
• Expiration. A memory past its expiration_date stays stored but is hidden from search and list unless you pass show_expired: true. To clear an expiration date, pass expiration_date: null to memories.update.
• Rate limits and quotas. Mem0 answers 429 when a project is over its rate limit, and the plugin retries that up to three times with backoff. A free or paid plan’s monthly add and retrieval limits are separate: calls past those fail with a 413, which the plugin does not retry because the limits reset on the billing date.
• Webhooks. The plugin can register, list, change and remove Mem0 webhooks with webhooks.create, webhooks.list, webhooks.update and webhooks.delete, so Mem0 posts memory events to your URL. It does not receive those posts itself: Mem0 publishes no signing secret or signature header, so a receiver built here could not tell a genuine post from a forged one. Verify deliveries in your own endpoint, and poll events.list or events.get if you would rather not run one.

• 16 typed API operations

​

Setup

npm install corsair @corsair-dev/mem0

yarn add corsair @corsair-dev/mem0

pnpm install corsair @corsair-dev/mem0

bun add corsair @corsair-dev/mem0

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { mem0 } from '@corsair-dev/mem0';

export const corsair = createCorsair({
	plugins: [
		mem0(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

mem0()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'mem0',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.mem0.api.memories.list({
	filters: { user_id: 'alice' },
	page_size: 20,
});

const tenant = corsair.withTenant('acme');
await tenant.mem0.api.memories.add({
	user_id: 'alice',
	messages: [{ role: 'user', content: 'I moved to Austin last month.' }],
});

​

What’s next