diff --git a/README.md b/README.md index 8ec498d55..a5bf395df 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ +# Mem0 Python SDK +

- Mem0 - The Memory Layer for Personalized AI + Mem0, the memory layer for personalized AI

@@ -22,165 +24,187 @@ Mem0 Discord - Mem0 PyPI - Downloads + Mem0 PyPI downloads GitHub commit activity - Package version - - - Npm package + PyPI package version Y Combinator S24

-

- ๐Ÿ“„ Benchmarking Mem0's token-efficient memory algorithm โ†’ -

+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 Python package includes `MemoryClient` for the hosted Mem0 Platform and `Memory` for open-source, in-process memory. -## New Memory Algorithm (April 2026) +## Requirements -| 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 | +- Python 3.10 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` -All benchmarks run on the same production-representative model stack. Single-pass retrieval (one call, no agentic loops) at a top_200 retrieval budget. Scores reflect Mem0's managed platform, which includes proprietary optimizations not available in the open-source SDK; open-source users should expect directionally similar gains but not identical numbers. - -**What changed:** -- **Single-pass ADD-only extraction**: one LLM call, no UPDATE/DELETE. Memories accumulate; nothing is overwritten. -- **Agent-generated facts are first-class**: when an agent confirms an action, that information is now stored with equal weight. -- **Entity linking**: entities are extracted, embedded, and linked across memories for retrieval boosting. -- **Multi-signal retrieval**: semantic, BM25 keyword, and entity matching scored in parallel and fused. -- **Temporal Reasoning**: time-aware retrieval that ranks the right dated instance for queries about current state, past events, and upcoming plans. - -See the [migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for upgrade instructions. The [evaluation framework](https://github.com/mem0ai/memory-benchmarks) is open-sourced so anyone can reproduce the numbers. - -## Research Highlights -- **92.5 on LoCoMo**: +21 points over the previous algorithm -- **94.4 on LongMemEval**: +27 points, with 98.2 on assistant memory recall -- **64.1 on BEAM (1M)**: production-scale memory evaluation at 1M tokens -- [Read the full paper](https://mem0.ai/research) - -# Introduction - -[Mem0](https://mem0.ai) ("mem-zero") gives AI assistants and agents persistent memory. It stores facts extracted from conversations, scopes them to a user, agent, or run, and retrieves the relevant ones on the next query. - -### Key Features & Use Cases - -**Core capabilities:** -- Memory scoped to `user_id`, `agent_id`, or `run_id`, with metadata and filters on top -- The same API across the OSS library, self-hosted server, and hosted Platform, plus Python and TypeScript SDKs - -**Use cases:** -- AI assistants and chatbots that keep context across sessions -- Customer support tools that recall a user's past tickets and preferences -- Coding agents that remember project conventions and prior decisions ([Agent Skills](#agent-skills)) - -## ๐Ÿš€ Quickstart Guide - -### Sign up as an agent - -AI agents can mint a working Mem0 API key in under five seconds: no email, no dashboard, no OTP. Four commands end-to-end: - -```bash -# 1. Install -npm install -g @mem0/cli # or: pip install mem0-cli - -# 2. Sign up as an agent (replace `claude-code` with your name) -mem0 init --agent --agent-caller claude-code - -# 3. Add a memory -mem0 add "I am using mem0" - -# 4. Search -mem0 search "am I using mem0" -``` - -The human owner can claim the account later with `mem0 init --email ` (same key, memories preserved). Full guide: [Sign up as an agent](https://docs.mem0.ai/platform/agent-signup). - -| | Library | Self-Hosted Server | Cloud Platform | -|---|---------|-------------------|----------------| -| **Best for** | Testing, prototyping | Teams running on their own infrastructure | Zero-ops production use | -| **Setup** | `pip install mem0ai` | `docker compose up` | Sign up at [app.mem0.ai](https://app.mem0.ai?utm_source=oss&utm_medium=readme) | -| **Dashboard** | n/a | [Yes](https://docs.mem0.ai/open-source/setup) | Yes | -| **Auth & API Keys** | n/a | Yes | Yes | -| **Advanced Features** | n/a | Teasers | All included | - -Just testing? Use the library. Building for a team? Self-hosted. Want zero ops? Cloud. - -### Library (pip / npm) +## Install ```bash pip install mem0ai ``` -For enhanced hybrid search with BM25 keyword matching and entity extraction, install with NLP support: +For enhanced hybrid search with BM25 keyword matching and entity extraction: ```bash -pip install mem0ai[nlp] +pip install "mem0ai[nlp]" python -m spacy download en_core_web_sm ``` -Install sdk via npm: +## Platform or open source -```bash -npm install mem0ai +| | Platform (`MemoryClient`) | Open source (`Memory`) | +|---|---|---| +| Import | `from mem0 import MemoryClient` | `from mem0 import Memory` | +| 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 synchronously 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: + +```python +import os + +from mem0 import MemoryClient + +client = MemoryClient(api_key=os.environ["MEM0_API_KEY"]) + +messages = [ + {"role": "user", "content": "I am vegetarian and allergic to nuts."}, + {"role": "assistant", "content": "I will remember that."}, +] +result = client.add(messages, user_id="alex") +print(result) ``` -### Self-Hosted Server +Hosted `add()` queues extraction and usually returns an `event_id` 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: -> **Note:** Self-hosted auth is on by default. Upgrading from a pre-auth build? Set `ADMIN_API_KEY`, register an admin through the wizard, or `AUTH_DISABLED=true` for local dev only. See [upgrade notes](https://docs.mem0.ai/open-source/setup#upgrade-notes). +```python +import os + +from mem0 import MemoryClient + +client = MemoryClient(api_key=os.environ["MEM0_API_KEY"]) +results = client.search( + "What does Alex eat?", + filters={"user_id": "alex"}, + top_k=5, +) +print(results["results"]) +``` + +`search()` and `get_all()` take entity IDs inside `filters`. `add()` and `delete_all()` take `user_id`, `agent_id`, or `run_id` as top-level keyword arguments. + +## Open-source quickstart + +Set `OPENAI_API_KEY` before using the default OpenAI LLM and embedder: + +```python +from mem0 import Memory + +memory = Memory() + +messages = [ + {"role": "user", "content": "I am vegetarian and allergic to nuts."}, + {"role": "assistant", "content": "I will remember that."}, +] +memory.add(messages, user_id="alex") + +results = memory.search( + "What does Alex eat?", + filters={"user_id": "alex"}, + top_k=5, +) +print(results["results"]) +``` + +The default `Memory` configuration uses OpenAI `gpt-5-mini`, OpenAI `text-embedding-3-small`, local Qdrant storage, and a SQLite history database. Pass a `MemoryConfig` or use `Memory.from_config()` to change the LLM, embedder, vector store, history path, or reranker. + +## Configuration and features + +| Feature | Documentation | +|---|---| +| Memory operations: `add`, `search`, `get`, `get_all`, `update`, `delete`, `delete_all`, `history` | [Python quickstart](https://docs.mem0.ai/open-source/python-quickstart) | +| Entity scoping with `user_id`, `agent_id`, and `run_id` | [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) | +| Async clients: `AsyncMemory` and `AsyncMemoryClient` | [Async memory](https://docs.mem0.ai/open-source/features/async-memory) | +| 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: one command starts the stack, creates an admin, and issues the first API key. +# Recommended: start the stack, create an admin, and issue the first API key. cd server && make bootstrap -# Manual: start the stack and finish setup via the browser wizard. -cd server && docker compose up -d # http://localhost:3000 +# Manual: start the stack, then finish setup in the browser wizard. +cd server && docker compose up -d ``` -See the [self-hosted docs](https://docs.mem0.ai/open-source/overview) for configuration. +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). -### Cloud Platform +## CLI -1. Sign up on [Mem0 Platform](https://app.mem0.ai?utm_source=oss&utm_medium=readme) -2. Embed the memory layer via SDK or API keys -3. Using hosted Qdrant vectors? See the [Platform migration guide](https://docs.mem0.ai/migration/oss-to-platform) to import them into Mem0 Platform. - -### CLI - -Manage memories from your terminal: +Manage hosted memories from your terminal: ```bash -npm install -g @mem0/cli # or: pip install mem0-cli +pip install mem0-cli mem0 init mem0 add "Prefers dark mode and vim keybindings" --user-id alice mem0 search "What does Alice prefer?" --user-id alice ``` -See the [CLI documentation](https://docs.mem0.ai/platform/cli) for the full command reference. +AI agents can create an account without email or a dashboard: -### Agent Skills +```bash +mem0 init --agent --agent-caller claude-code +``` -Teach your AI coding assistant (Claude Code, Codex, Cursor, Windsurf, OpenCode, OpenClaw, and any tool that supports the skills standard) how to build with Mem0. Two categories: +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). -**Reference skills, always on** (SDK knowledge loaded into the assistant's context): +## 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 -npx skills add https://github.com/mem0ai/mem0 --skill mem0-vercel-ai-sdk ``` -**Pipeline skills, run on demand** (execute an end-to-end workflow in an existing repo): +Install pipeline skills for end-to-end workflows: ```bash npx skills add https://github.com/mem0ai/mem0 --skill mem0-integrate @@ -188,111 +212,30 @@ 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 ``` -Use `/mem0-integrate` to wire Mem0 into an existing repo via a test-first pipeline, then `/mem0-test-integration` to verify. Use `/mem0-oss-to-platform` to migrate an existing project from Mem0 OSS to the hosted Platform SDK. See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding) for the full picture. +See the [skills catalog](./skills/) or [Vibecoding with Mem0](https://docs.mem0.ai/vibecoding). -### Basic Usage +## Integrations and demos -Mem0 requires an LLM to function, with `gpt-5-mini` from OpenAI as the default. It supports a variety of LLMs; see [Supported LLMs](https://docs.mem0.ai/components/llms/overview). +- [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) -The default embedding model is `text-embedding-3-small` from OpenAI. For best results with hybrid search (semantic + keyword + entity boosting), use at least [Qwen 600M](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct) or a comparable embedding model. See [Supported Embeddings](https://docs.mem0.ai/components/embedders/overview) for configuration details. +## Documentation and help -**Self-hosted (`Memory`, `pip install mem0ai`):** +- [Python quickstart](https://docs.mem0.ai/open-source/python-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 -```python -from openai import OpenAI -from mem0 import Memory +## Contributing -openai_client = OpenAI() -memory = Memory() - -def chat_with_memories(message: str, user_id: str = "default_user") -> str: - relevant_memories = memory.search(query=message, filters={"user_id": user_id}, top_k=3) - memories_str = "\n".join(f"- {entry['memory']}" for entry in relevant_memories["results"]) - - system_prompt = f"You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n{memories_str}" - messages = [{"role": "system", "content": system_prompt}, {"role": "user", "content": message}] - response = openai_client.chat.completions.create(model="gpt-5-mini", messages=messages) - assistant_response = response.choices[0].message.content - - messages.append({"role": "assistant", "content": assistant_response}) - memory.add(messages, user_id=user_id) - - return assistant_response - -print(chat_with_memories("I prefer dark mode and vim keybindings")) -print(chat_with_memories("What editor settings do I like?")) -``` - -**Hosted Platform (`MemoryClient`, `MEM0_API_KEY` from [app.mem0.ai](https://app.mem0.ai?utm_source=oss&utm_medium=readme)):** - -```python -import os -from mem0 import MemoryClient - -client = MemoryClient(api_key=os.environ["MEM0_API_KEY"]) - -messages = [{"role": "user", "content": "I prefer dark mode and vim keybindings"}] -client.add(messages, user_id="alice") - -results = client.search("What does Alice prefer?", filters={"user_id": "alice"}, top_k=3) -all_memories = client.get_all(filters={"user_id": "alice"}) -``` - -**TypeScript** (`npm install mem0ai`; see [`mem0-ts/README.md`](https://github.com/mem0ai/mem0/blob/main/mem0-ts/README.md) and the [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart)): - -```typescript -import { MemoryClient, type Message } from "mem0ai"; -import { Memory } from "mem0ai/oss"; - -const messages: Message[] = [{ role: "user", content: "I prefer dark mode and vim keybindings" }]; - -const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! }); -await client.add(messages, { userId: "alice" }); -const results = await client.search("What does Alice prefer?", { filters: { user_id: "alice" } }); - -const memory = new Memory(); -await memory.add(messages, { userId: "alice" }); -const local = await memory.search("What does Alice prefer?", { filters: { user_id: "alice" } }); -``` - -For detailed integration steps, see the [Python Quickstart](https://docs.mem0.ai/open-source/python-quickstart), [Platform Quickstart](https://docs.mem0.ai/platform/quickstart), and [API Reference](https://docs.mem0.ai/api-reference). - -### What the SDK Covers - -| Feature | Docs | -|---|---| -| Memory ops: `add`, `search`, `get`, `get_all`, `update`, `delete`, `delete_all`, `history` | [Python Quickstart](https://docs.mem0.ai/open-source/python-quickstart) | -| Entity scoping (`user_id`, `agent_id`, `run_id`) | [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) | -| Async clients (`AsyncMemory`, `AsyncMemoryClient`) | [Async memory](https://docs.mem0.ai/open-source/features/async-memory) | -| Graph memory | [Graph memory](https://docs.mem0.ai/platform/features/graph-memory) | -| Rerankers | [Reranker-enhanced search](https://docs.mem0.ai/open-source/features/reranker-search) | -| Custom instructions | [Custom instructions](https://docs.mem0.ai/open-source/features/custom-instructions) | -| Multimodal (images, files) | [Multimodal support](https://docs.mem0.ai/open-source/features/multimodal-support) | -| Webhooks (Platform) | [Webhooks](https://docs.mem0.ai/platform/features/webhooks) | -| Memory export (Platform) | [Memory export](https://docs.mem0.ai/platform/features/memory-export) | -| Feedback (Platform) | [Feedback mechanism](https://docs.mem0.ai/platform/features/feedback-mechanism) | -| Memory expiration (Platform) | [Memory expiration](https://docs.mem0.ai/platform/features/memory-expiration) | -| Custom categories (Platform) | [Custom categories](https://docs.mem0.ai/platform/features/custom-categories) | -| Dream, memory synthesis (Platform) | [Dream](https://docs.mem0.ai/platform/features/dream) | - -## ๐Ÿ”— Integrations & Demos - -- **ChatGPT with Memory**: Personalized chat powered by Mem0 ([Live Demo](https://mem0.dev/demo)) -- **Browser Extension**: Store memories across ChatGPT, Perplexity, and Claude ([Chrome Extension](https://chromewebstore.google.com/detail/onihkkbipkfeijkadecaafbgagkhglop?utm_source=item-share-cb)) -- **Langgraph Support**: Build a customer bot with Langgraph + Mem0 ([Guide](https://docs.mem0.ai/integrations/langgraph)) -- **CrewAI Integration**: Tailor CrewAI outputs with Mem0 ([Example](https://docs.mem0.ai/integrations/crewai)) - -## ๐Ÿ“š Documentation & Support - -- Full docs: https://docs.mem0.ai -- Community: [Discord](https://mem0.dev/DiG) ยท [X (formerly Twitter)](https://x.com/mem0ai) -- Contact: founders@mem0.ai +Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening an issue or pull request. ## Citation -We now have a paper you can cite: - ```bibtex @article{mem0, title={Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory}, @@ -302,6 +245,6 @@ We now have a paper you can cite: } ``` -## โš–๏ธ License +## License -Apache 2.0. See the [LICENSE](https://github.com/mem0ai/mem0/blob/main/LICENSE) file for details. +Apache 2.0. See [LICENSE](./LICENSE). diff --git a/mem0-ts/README.md b/mem0-ts/README.md index 56f6cca7e..b76461390 100644 --- a/mem0-ts/README.md +++ b/mem0-ts/README.md @@ -1,11 +1,15 @@ -# mem0ai +# Mem0 TypeScript SDK [![npm version](https://img.shields.io/npm/v/mem0ai.svg)](https://www.npmjs.com/package/mem0ai) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/mem0ai/mem0/blob/main/LICENSE) -Mem0 is a memory layer for AI agents: it extracts, stores, and retrieves facts from conversations so an LLM app can stay personalized across sessions instead of re-reading the full chat history on every call. This package gives you two clients: a hosted `MemoryClient` backed by the Mem0 Platform, and a self-hosted `Memory` you run in-process against your own LLM, embedder, and vector store. +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 `mem0ai` package includes `MemoryClient` for the hosted Mem0 Platform and `Memory` for open-source, in-process memory. -Docs: [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) +## Requirements + +- Hosted `MemoryClient`: Node.js 18 or later and `MEM0_API_KEY` from the [Mem0 dashboard](https://app.mem0.ai/dashboard/api-keys) +- Open-source `Memory` with the default storage: Node.js 20 or later because `better-sqlite3` v12 requires Node 20+ +- Open source with the default providers: `OPENAI_API_KEY` ## Install @@ -13,96 +17,50 @@ Docs: [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart) ยท [Pl npm install mem0ai ``` -Requires Node 18 or later. - ## 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 own vector store, in-process | -| Setup | `MEM0_API_KEY` from [app.mem0.ai/dashboard/api-keys](https://app.mem0.ai/dashboard/api-keys) | `OPENAI_API_KEY` (default LLM and embedder), or any [supported provider](#supported-providers) | -| Extraction | Managed, asynchronous, includes graph memory | Runs against the LLM you configure, no graph memory | +| | 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'm a vegetarian and I'm allergic to nuts." }, - { role: "assistant", content: "Got it, I'll remember that." }, + { role: "user", content: "I am vegetarian and allergic to nuts." }, + { role: "assistant", content: "I will remember that." }, ]; - await client.add(messages, { userId: "alex" }); ``` -`add()` queues extraction and returns `{ eventId, status: "PENDING" }` right away. The extracted memories become searchable a few seconds later: +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 -const found = await client.search("What does Alex eat?", { +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, }); - -const page = await client.getAll({ - filters: { user_id: "alex" }, - pageSize: 20, -}); - -const memory = await client.get(found.results[0].id); -const history = await client.history(memory.id); - -await client.update(memory.id, { - text: "Alex is a vegetarian, allergic to nuts and shellfish.", -}); -await client.delete(memory.id); -await client.deleteAll({ userId: "alex" }); +console.log(results.results); ``` -Note that `search` and `getAll` reject top-level `userId`/`agentId`/`appId`/`runId`: those go inside `filters`, and `filters` keys are always snake_case (`user_id`, not `userId`). `add` and `deleteAll` are the opposite: they take entity ids as top-level camelCase options. +`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. -### More platform operations +## Open-source quickstart -```ts -import { MemoryClient, Feedback, WebhookEvent } from "mem0ai"; - -const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! }); - -const users = await client.users(); -await client.deleteUsers({ userId: "alex" }); - -await client.batchUpdate([{ memoryId: "mem-1", text: "Updated text" }]); -await client.batchDelete(["mem-1", "mem-2"]); - -const project = await client.getProject({ - fields: ["customInstructions", "customCategories"], -}); -await client.updateProject({ customInstructions: "Always answer in French." }); - -const webhook = await client.createWebhook({ - name: "memory-events", - url: "https://example.com/webhooks/mem0", - eventTypes: [WebhookEvent.MEMORY_ADDED, WebhookEvent.MEMORY_UPDATED], -}); -await client.deleteWebhook({ webhookId: webhook.webhookId! }); - -await client.feedback({ memoryId: "mem-1", feedback: Feedback.POSITIVE }); - -const { id: exportId } = await client.createMemoryExport({ - schema: { name: "string", preferences: "string[]" }, - filters: { user_id: "alex" }, -}); -const exportResult = await client.getMemoryExport({ memoryExportId: exportId }); - -await client.ping(); -``` - -`getProject`/`updateProject` need an API key scoped to a single organization and project. `getWebhooks`/`createWebhook` resolve the project from the client automatically; there is no `projectId` field on the create payload. - -## Open source quickstart +Set `OPENAI_API_KEY` before using the default OpenAI LLM and embedder: ```ts import { Memory } from "mem0ai/oss"; @@ -110,75 +68,23 @@ import { Memory } from "mem0ai/oss"; const memory = new Memory(); const messages = [ - { role: "user", content: "I'm a vegetarian and I'm allergic to nuts." }, - { role: "assistant", content: "Got it, I'll remember that." }, + { role: "user", content: "I am vegetarian and allergic to nuts." }, + { role: "assistant", content: "I will remember that." }, ]; - await memory.add(messages, { userId: "alex" }); -const found = await memory.search("What does Alex eat?", { +const results = await memory.search("What does Alex eat?", { filters: { user_id: "alex" }, + topK: 5, }); -const all = await memory.getAll({ filters: { user_id: "alex" } }); - -await memory.update( - found.results[0].id, - "Alex is a vegetarian, allergic to nuts and shellfish.", -); -const history = await memory.history(found.results[0].id); -await memory.delete(found.results[0].id); -await memory.reset(); +console.log(results.results); ``` -With no config, `Memory` uses OpenAI `gpt-5-mini` for extraction, OpenAI `text-embedding-3-small` for embeddings, an in-memory (non-persistent) vector store, and a SQLite history log at `memory.db`. `add`, `search`, and `getAll` all require at least one of `userId`/`agentId`/`runId` (top-level for `add`, inside `filters` as `user_id`/`agent_id`/`run_id` for `search` and `getAll`). +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`. -### Chat loop example +## Configuration and features -```ts -import OpenAI from "openai"; -import { Memory } from "mem0ai/oss"; - -const openai = new OpenAI(); -const memory = new Memory(); - -async function chatWithMemories( - message: string, - userId = "default_user", -): Promise { - const relevant = await memory.search(message, { - filters: { user_id: userId }, - topK: 3, - }); - const memoriesStr = relevant.results - .map((entry) => `- ${entry.memory}`) - .join("\n"); - - const systemPrompt = `You are a helpful AI. Answer the question based on query and memories.\nUser Memories:\n${memoriesStr}`; - const messages = [ - { role: "system" as const, content: systemPrompt }, - { role: "user" as const, content: message }, - ]; - - const response = await openai.chat.completions.create({ - model: "gpt-5-mini", - messages, - }); - const assistantResponse = response.choices[0].message.content ?? ""; - - await memory.add( - [...messages, { role: "assistant" as const, content: assistantResponse }], - { userId }, - ); - - return assistantResponse; -} -``` - -Requires `npm install openai` alongside `mem0ai`. - -### Configuration - -Pass a config object to `new Memory()` to swap the LLM, embedder, vector store, history store, or reranker: +Pass a config object to `Memory` to change providers or storage: ```ts import { Memory } from "mem0ai/oss"; @@ -207,64 +113,71 @@ const memory = new Memory({ dimension: 1536, }, }, - reranker: { - provider: "cohere", - config: { - apiKey: process.env.COHERE_API_KEY, - model: "rerank-english-v3.0", - }, - }, - historyDbPath: "memory.db", }); ``` -Set `rerank: true` on `search()` to use the configured reranker. There is no `graphStore` option: graph memory is a Platform-only feature, not part of the OSS TypeScript SDK. +Provider integrations use a mix of bundled dependencies and peer dependencies. OpenAI is bundled. Most provider peers are optional, but `package.json` also declares required peers such as `better-sqlite3`, `pg`, `compromise`, and `natural`. Install the SDK for any optional provider you configure. -### Supported providers +### Memory operations -Provider SDKs are optional peer dependencies. Install the package for the provider you use (for example `npm install @qdrant/js-client-rest` for Qdrant); the rest stay out of your bundle. +Both clients expose asynchronous memory operations. The open-source methods finish their work before resolving. Hosted `add()` only confirms that the extraction job was queued. -| Kind | Provider strings | -| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| LLMs | `openai`, `openai_structured`, `anthropic`, `groq`, `mistral`, `google` (`gemini`), `azure_openai`, `ollama`, `lmstudio`, `together`, `deepseek`, `xai`, `sarvam`, `aws_bedrock`, `litellm`, `minimax`, `vllm`, `langchain` | -| Embedders | `openai`, `azure_openai`, `google` (`gemini`), `aws_bedrock`, `vertexai`, `huggingface`, `fastembed`, `ollama`, `lmstudio`, `together`, `langchain` | -| Vector stores | `memory`, `qdrant`, `chroma`, `pgvector`, `pinecone`, `milvus`, `mongodb`, `weaviate`, `redis`, `valkey`, `supabase`, `cassandra`, `elasticsearch`, `opensearch`, `turbopuffer`, `upstash_vector`, `vectorize`, `s3_vectors`, `baidu`, `databricks`, `oracledb`, `azure-ai-search`, `azure_mysql`, `neptune-analytics`, `vertex_ai_vector_search`, `langchain` | -| Rerankers | `cohere`, `zero_entropy`, `llm_reranker`, `sentence_transformer`, `huggingface` | +| Operation | Platform | Open source | +| ---------------------- | ----------------------------------- | ----------------------------------- | +| Add | `client.add(messages, { userId })` | `memory.add(messages, { userId })` | +| Search | `client.search(query, { filters })` | `memory.search(query, { filters })` | +| List | `client.getAll({ filters })` | `memory.getAll({ filters })` | +| Get | `client.get(memoryId)` | `memory.get(memoryId)` | +| Update | `client.update(memoryId, { text })` | `memory.update(memoryId, { text })` | +| Delete | `client.delete(memoryId)` | `memory.delete(memoryId)` | +| Delete scoped memories | `client.deleteAll({ userId })` | `memory.deleteAll({ userId })` | +| History | `client.history(memoryId)` | `memory.history(memoryId)` | -## Filters +### Filters -`filters` selects which memories a search, `getAll`, or export applies to. Keys are snake_case. A flat object ANDs its keys together; wrap conditions in `AND`/`OR` for explicit grouping: +Use snake_case keys inside `filters`. A flat object combines conditions with AND. Use `AND`, `OR`, or `NOT` for explicit grouping: ```ts -{ filters: { user_id: "alex", categories: { contains: "food" } } } - -{ - filters: { - OR: [{ agent_id: "assistant-1" }, { run_id: "session-42" }], - }, -} +const filters = { + AND: [{ user_id: "alex" }, { categories: { contains: "food" } }], +}; ``` -Comparison operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `icontains`. The open-source `Memory` also supports `nin`; the Platform client does not. See [Memory filters](https://docs.mem0.ai/platform/features/v2-memory-filters) for the full grammar. +Pass this object as `filters` to `search()` or `getAll()`. -## CLI and integrations +Comparison operators include `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, and `icontains`. Open-source `Memory` also supports `nin`. See [memory filters](https://docs.mem0.ai/platform/features/v2-memory-filters). + +### Platform features + +`MemoryClient` also supports users, batch operations, project settings, webhooks, feedback, and memory exports. See the [Platform API reference](https://docs.mem0.ai/api-reference). + +### Open-source providers + +The TypeScript SDK supports configurable LLMs, embedders, vector stores, history stores, and rerankers. See the [Node quickstart](https://docs.mem0.ai/open-source/node-quickstart) and [component documentation](https://docs.mem0.ai/components/llms/overview) for supported provider names and configuration. + +### CLI and integrations + +Use the Node CLI to manage hosted memories from your terminal: ```bash npm install -g @mem0/cli ``` -The CLI wraps both clients from your shell. See [CLI reference](https://docs.mem0.ai/platform/cli). +See the [CLI reference](https://docs.mem0.ai/platform/cli) and [Vercel AI SDK integration](https://docs.mem0.ai/integrations/vercel-ai-sdk). -Using the Vercel AI SDK? See the [Vercel AI SDK integration](https://docs.mem0.ai/integrations/vercel-ai-sdk). +## 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](../CONTRIBUTING.md) before opening an issue or pull request. ## License -Apache-2.0 - -## Getting Help - -If you have any questions or need assistance, please reach out to us: - -- Email: founders@mem0.ai -- [Join our discord community](https://mem0.ai/discord) -- GitHub Issues: [Report bugs or request features](https://github.com/mem0ai/mem0/issues) +Apache 2.0. See [LICENSE](../LICENSE).