# Mem0 TypeScript SDK
Learn more
·
Join Discord
·
Demo
Mem0 gives AI assistants and agents persistent memory. It extracts useful facts from conversations, scopes them to a user, agent, or run, and retrieves the relevant facts for later interactions. The TypeScript package, `mem0ai` on npm, includes `MemoryClient` for the hosted Mem0 Platform, imported from `mem0ai`, and `Memory` for open-source, in-process memory, imported from `mem0ai/oss`.
## Requirements
- Node.js 20 or later
- Hosted Platform: `MEM0_API_KEY` from the [Mem0 dashboard](https://app.mem0.ai/dashboard/api-keys)
- Open source with the default providers: `OPENAI_API_KEY`
## Install
```bash
npm install mem0ai
```
## Platform or open source
| | Platform (`MemoryClient`) | Open source (`Memory`) |
| ------------------- | --------------------------------------- | --------------------------------------------------------------------- |
| Import | `import { MemoryClient } from "mem0ai"` | `import { Memory } from "mem0ai/oss"` |
| Where memories live | Mem0's hosted API | Your configured vector store |
| Required key | `MEM0_API_KEY` | `OPENAI_API_KEY` with the defaults, or keys for your chosen providers |
| Extraction | Managed and asynchronous | Runs against your configured LLM |
| Best for | Zero-ops production use | Local development and custom infrastructure |
## Platform quickstart
Set `MEM0_API_KEY`, then add a conversation:
```ts
import { MemoryClient, type Message } from "mem0ai";
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
const messages: Message[] = [
{ role: "user", content: "I am vegetarian and allergic to nuts." },
{ role: "assistant", content: "I will remember that." },
];
await client.add(messages, { userId: "alex" });
```
Hosted `add()` queues extraction and usually returns an `eventId` with `status: "PENDING"`. Do not search immediately after `add()`. Wait for processing to finish in the dashboard, or use a [`memory_add` webhook](https://docs.mem0.ai/platform/features/webhooks), then search:
```ts
import { MemoryClient } from "mem0ai";
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
const results = await client.search("What does Alex eat?", {
filters: { user_id: "alex" },
topK: 5,
});
console.log(results.results);
```
`search()` and `getAll()` take entity IDs inside `filters` with snake_case keys. `add()` and `deleteAll()` take `userId`, `agentId`, or `runId` as top-level camelCase options.
## Open-source quickstart
Set `OPENAI_API_KEY` before using the default OpenAI LLM and embedder:
```ts
import { Memory } from "mem0ai/oss";
const memory = new Memory();
const messages = [
{ role: "user", content: "I am vegetarian and allergic to nuts." },
{ role: "assistant", content: "I will remember that." },
];
await memory.add(messages, { userId: "alex" });
const results = await memory.search("What does Alex eat?", {
filters: { user_id: "alex" },
topK: 5,
});
console.log(results.results);
```
The default `Memory` configuration uses OpenAI `gpt-5-mini`, OpenAI `text-embedding-3-small`, a SQLite-backed vector store at `~/.mem0/vector_store.db`, and a SQLite history database at `memory.db`. Pass a config object to `Memory` to change the LLM, embedder, vector store, history path, or reranker.
## Configuration and features
| Feature | Documentation |
| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Memory operations: `add`, `search`, `get`, `getAll`, `update`, `delete`, `deleteAll`, `history`, all async and Promise-based | [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart) |
| Entity scoping with `userId`, `agentId`, and `runId` | [Entity-scoped memory](https://docs.mem0.ai/platform/features/entity-scoped-memory) |
| Metadata and filters | [Metadata filtering](https://docs.mem0.ai/open-source/features/metadata-filtering) |
| LLMs, embedders, vector stores, and rerankers | [Components](https://docs.mem0.ai/components/llms/overview) |
| Graph memory | [Graph memory](https://docs.mem0.ai/platform/features/graph-memory) |
| Custom instructions | [Custom instructions](https://docs.mem0.ai/open-source/features/custom-instructions) |
| Multimodal input | [Multimodal support](https://docs.mem0.ai/open-source/features/multimodal-support) |
| Platform webhooks, export, feedback, expiration, and custom categories | [Platform features](https://docs.mem0.ai/platform/features) |
## Benchmarks
Benchmarking Mem0's token-efficient memory algorithm
| Benchmark | Old | New | Tokens | Latency p50 |
| --------------- | ---: | -------: | -----: | ----------: |
| **LoCoMo** | 71.4 | **92.5** | 7.0K | 0.88s |
| **LongMemEval** | 67.8 | **94.4** | 6.8K | 1.09s |
| **BEAM (1M)** | n/a | **64.1** | 6.7K | 1.00s |
| **BEAM (10M)** | n/a | **48.6** | 6.9K | 1.05s |
All benchmarks use the same production-representative model stack, single-pass retrieval, and a top-200 retrieval budget. Scores reflect the managed Platform, which includes proprietary optimizations not available in the open-source SDK. Open-source results should show similar directional gains, but may not match these scores.
The current algorithm uses single-pass ADD-only extraction, first-class agent facts, entity linking, multi-signal retrieval, and temporal reasoning. Read the [research paper](https://mem0.ai/research), the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3), or the open-source [evaluation framework](https://github.com/mem0ai/memory-benchmarks).
## Self-hosted server
Run Mem0 as a FastAPI service with PostgreSQL, pgvector, and Neo4j:
```bash
# Recommended: start the stack, create an admin, and issue the first API key.
cd server && make bootstrap
# Manual: start the stack, then finish setup in the browser wizard.
cd server && docker compose up -d
```
Self-hosted authentication is enabled by default. See the [self-hosted documentation](https://docs.mem0.ai/open-source/overview) and [upgrade notes](https://docs.mem0.ai/open-source/setup#upgrade-notes).
## CLI
Manage hosted memories from your terminal:
```bash
npm install -g @mem0/cli
mem0 init
mem0 add "Prefers dark mode and vim keybindings" --user-id alice
mem0 search "What does Alice prefer?" --user-id alice
```
AI agents can create an account without email or a dashboard:
```bash
mem0 init --agent --agent-caller claude-code
```
The human owner can claim the account later with `mem0 init --email `. The API key and memories remain unchanged. See the [CLI documentation](https://docs.mem0.ai/platform/cli) and [agent signup guide](https://docs.mem0.ai/platform/agent-signup).
## Agent skills
Install reference skills to give compatible coding assistants Mem0 context:
```bash
npx skills add https://github.com/mem0ai/mem0 --skill mem0
npx skills add https://github.com/mem0ai/mem0 --skill mem0-cli
```
Install pipeline skills for end-to-end workflows:
```bash
npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate
npx skills add https://github.com/mem0ai/mem0 --skill mem0-test-integration
npx skills add https://github.com/mem0ai/mem0 --skill mem0-oss-to-platform
```
See the [skills catalog](../skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding).
## Integrations and demos
- [ChatGPT with Memory demo](https://mem0.dev/demo)
- [Browser extension](https://chromewebstore.google.com/detail/onihkkbipkfeijkadecaafbgagkhglop?utm_source=item-share-cb)
- [LangGraph integration](https://docs.mem0.ai/integrations/langgraph)
- [CrewAI integration](https://docs.mem0.ai/integrations/crewai)
## Documentation and help
- [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart)
- [Platform quickstart](https://docs.mem0.ai/platform/quickstart)
- [API reference](https://docs.mem0.ai/api-reference)
- [Discord](https://mem0.dev/DiG)
- [GitHub issues](https://github.com/mem0ai/mem0/issues)
- Email: founders@mem0.ai
## Contributing
Read [CONTRIBUTING.md](https://github.com/mem0ai/mem0/blob/main/CONTRIBUTING.md) before opening an issue or pull request.
## Citation
```bibtex
@article{mem0,
title={Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory},
author={Chhikara, Prateek and Khant, Dev and Aryan, Saket and Singh, Taranjeet and Yadav, Deshraj},
journal={arXiv preprint arXiv:2504.19413},
year={2025}
}
```
## License
Apache 2.0. See [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE).