docs: align Python and TypeScript SDK READMEs
This commit is contained in:
kartik-mem0
@@ -1,6 +1,8 @@
|
||||
# Mem0 Python SDK
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/mem0ai/mem0">
|
||||
<img src="docs/images/banner-sm.png" width="800px" alt="Mem0 - The Memory Layer for Personalized AI">
|
||||
<img src="docs/images/banner-sm.png" width="800px" alt="Mem0, the memory layer for personalized AI">
|
||||
</a>
|
||||
</p>
|
||||
<p align="center" style="display: flex; justify-content: center; gap: 20px; align-items: center;">
|
||||
@@ -22,165 +24,187 @@
|
||||
<img src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white" alt="Mem0 Discord">
|
||||
</a>
|
||||
<a href="https://pepy.tech/project/mem0ai">
|
||||
<img src="https://img.shields.io/pypi/dm/mem0ai" alt="Mem0 PyPI - Downloads">
|
||||
<img src="https://img.shields.io/pypi/dm/mem0ai" alt="Mem0 PyPI downloads">
|
||||
</a>
|
||||
<a href="https://github.com/mem0ai/mem0">
|
||||
<img src="https://img.shields.io/github/commit-activity/m/mem0ai/mem0?style=flat-square" alt="GitHub commit activity">
|
||||
</a>
|
||||
<a href="https://pypi.org/project/mem0ai" target="blank">
|
||||
<img src="https://img.shields.io/pypi/v/mem0ai?color=%2334D058&label=pypi%20package" alt="Package version">
|
||||
</a>
|
||||
<a href="https://www.npmjs.com/package/mem0ai" target="blank">
|
||||
<img src="https://img.shields.io/npm/v/mem0ai" alt="Npm package">
|
||||
<img src="https://img.shields.io/pypi/v/mem0ai?color=%2334D058&label=pypi%20package" alt="PyPI package version">
|
||||
</a>
|
||||
<a href="https://www.ycombinator.com/companies/mem0">
|
||||
<img src="https://img.shields.io/badge/Y%20Combinator-S24-orange?style=flat-square" alt="Y Combinator S24">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://mem0.ai/research"><strong>📄 Benchmarking Mem0's token-efficient memory algorithm →</strong></a>
|
||||
</p>
|
||||
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 <a name="quickstart"></a>
|
||||
|
||||
### 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 <their-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
|
||||
|
||||
<p align="center">
|
||||
<a href="https://mem0.ai/research"><strong>Benchmarking Mem0's token-efficient memory algorithm</strong></a>
|
||||
</p>
|
||||
|
||||
| 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 <their-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).
|
||||
|
||||
+81
-168
@@ -1,11 +1,15 @@
|
||||
# mem0ai
|
||||
# Mem0 TypeScript SDK
|
||||
|
||||
[](https://www.npmjs.com/package/mem0ai)
|
||||
[](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<string> {
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user