Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 kartik-mem0
|
3d6bac1af6 | ||
|
kartik-mem0
|
443895110b | ||
|
kartik-mem0
|
8af9cc5793 | ||
|
kartik-mem0
|
74570ead11 | ||
|
kartik-mem0
|
5020fa1a0d | ||
|
kartik-mem0
|
3ea7cc82cd |
@@ -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,166 +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)** | — | **64.1** | 6.7K | 1.00s |
|
||||
| **BEAM (10M)** | — | **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") enhances AI assistants and agents with an intelligent memory layer, enabling personalized AI interactions. It remembers user preferences, adapts to individual needs, and continuously learns over time—ideal for customer support chatbots, AI assistants, and autonomous systems.
|
||||
|
||||
### Key Features & Use Cases
|
||||
|
||||
**Core Capabilities:**
|
||||
- **Multi-Level Memory**: Seamlessly retains User, Session, and Agent state with adaptive personalization
|
||||
- **Developer-Friendly**: Intuitive API, cross-platform SDKs, and a fully managed service option
|
||||
|
||||
**Applications:**
|
||||
- **AI Assistants**: Consistent, context-rich conversations
|
||||
- **Customer Support**: Recall past tickets and user history for tailored help
|
||||
- **Healthcare**: Track patient preferences and history for personalized care
|
||||
- **Productivity & Gaming**: Adaptive workflows and environments based on user behavior
|
||||
|
||||
## 🚀 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** | -- | [Yes](https://docs.mem0.ai/open-source/setup) | Yes |
|
||||
| **Auth & API Keys** | -- | Yes | Yes |
|
||||
| **Advanced Features** | -- | 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 — start the stack, create an admin, issue 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
|
||||
@@ -189,72 +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. However, it supports a variety of LLMs; for details, refer to our [Supported LLMs documentation](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)
|
||||
|
||||
Mem0 uses `text-embedding-3-small` from OpenAI as the default embedding model. For best results with hybrid search (semantic + keyword + entity boosting), we recommend using 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
|
||||
|
||||
First step is to instantiate the memory:
|
||||
- [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:
|
||||
# Retrieve relevant memories
|
||||
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"])
|
||||
|
||||
# Generate Assistant response
|
||||
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
|
||||
|
||||
# Create new memories from the conversation
|
||||
messages.append({"role": "assistant", "content": assistant_response})
|
||||
memory.add(messages, user_id=user_id)
|
||||
|
||||
return assistant_response
|
||||
|
||||
def main():
|
||||
print("Chat with AI (type 'exit' to quit)")
|
||||
while True:
|
||||
user_input = input("You: ").strip()
|
||||
if user_input.lower() == 'exit':
|
||||
print("Goodbye!")
|
||||
break
|
||||
print(f"AI: {chat_with_memories(user_input)}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
For detailed integration steps, see the [Quickstart](https://docs.mem0.ai/quickstart) and [API Reference](https://docs.mem0.ai/api-reference).
|
||||
|
||||
## 🔗 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](https://github.com/mem0ai/mem0/blob/main/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},
|
||||
@@ -264,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](https://github.com/mem0ai/mem0/blob/main/LICENSE).
|
||||
|
||||
+207
-36
@@ -1,64 +1,235 @@
|
||||
# Mem0 - The Memory Layer for Your AI Apps
|
||||
# Mem0 TypeScript SDK
|
||||
|
||||
Mem0 is a self-improving memory layer for LLM applications, enabling personalized AI experiences that save costs and delight users. We offer both cloud and open-source solutions to cater to different needs.
|
||||
<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">
|
||||
</a>
|
||||
</p>
|
||||
<p align="center" style="display: flex; justify-content: center; gap: 20px; align-items: center;">
|
||||
<a href="https://trendshift.io/repositories/11194" target="blank">
|
||||
<img src="https://trendshift.io/api/badge/repositories/11194" alt="mem0ai%2Fmem0 | Trendshift" width="250" height="55"/>
|
||||
</a>
|
||||
</p>
|
||||
|
||||
See the complete [OSS Docs](https://docs.mem0.ai/open-source/node-quickstart).
|
||||
See the complete [Platform API Reference](https://docs.mem0.ai/api-reference).
|
||||
<p align="center">
|
||||
<a href="https://mem0.ai">Learn more</a>
|
||||
·
|
||||
<a href="https://mem0.dev/DiG">Join Discord</a>
|
||||
·
|
||||
<a href="https://mem0.dev/demo">Demo</a>
|
||||
</p>
|
||||
|
||||
## 1. Installation
|
||||
<p align="center">
|
||||
<a href="https://mem0.dev/DiG">
|
||||
<img src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white" alt="Mem0 Discord">
|
||||
</a>
|
||||
<a href="https://www.npmjs.com/package/mem0ai">
|
||||
<img src="https://img.shields.io/npm/dm/mem0ai" alt="Mem0 npm 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://www.npmjs.com/package/mem0ai" target="blank">
|
||||
<img src="https://img.shields.io/npm/v/mem0ai?color=%2334D058&label=npm%20package" alt="npm 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>
|
||||
|
||||
For the open-source version, you can install the Mem0 package using npm:
|
||||
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 i mem0ai
|
||||
npm install mem0ai
|
||||
```
|
||||
|
||||
## 2. API Key Setup
|
||||
## Platform or open source
|
||||
|
||||
For the cloud offering, sign in to [Mem0 Platform](https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=mem0-ts-readme) to obtain your API Key.
|
||||
| | 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 |
|
||||
|
||||
## 3. Client Features
|
||||
## Platform quickstart
|
||||
|
||||
### Cloud Offering
|
||||
Set `MEM0_API_KEY`, then add a conversation:
|
||||
|
||||
The cloud version provides a comprehensive set of features, including:
|
||||
```ts
|
||||
import { MemoryClient, type Message } from "mem0ai";
|
||||
|
||||
- **Memory Operations**: Perform CRUD operations on memories.
|
||||
- **Search Capabilities**: Search for relevant memories using advanced filters.
|
||||
- **Memory History**: Track changes to memories over time.
|
||||
- **Error Handling**: Robust error handling for API-related issues.
|
||||
- **Async/Await Support**: All methods return promises for easy integration.
|
||||
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||
|
||||
### Open-Source Offering
|
||||
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" });
|
||||
```
|
||||
|
||||
The open-source version includes the following top features:
|
||||
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:
|
||||
|
||||
- **Memory Management**: Add, update, delete, and retrieve memories.
|
||||
- **Vector Store Integration**: Supports various vector store providers for efficient memory retrieval.
|
||||
- **LLM Support**: Integrates with multiple LLM providers for generating responses.
|
||||
- **Customizable Configuration**: Easily configure memory settings and providers.
|
||||
- **SQLite Storage**: Use SQLite for memory history management.
|
||||
```ts
|
||||
import { MemoryClient } from "mem0ai";
|
||||
|
||||
## 4. Memory Operations
|
||||
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);
|
||||
```
|
||||
|
||||
Mem0 provides a simple and customizable interface for performing memory operations. You can create long-term and short-term memories, search for relevant memories, and manage memory history.
|
||||
`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.
|
||||
|
||||
## 5. Error Handling
|
||||
## Open-source quickstart
|
||||
|
||||
The MemoryClient throws errors for any API-related issues. You can catch and handle these errors effectively.
|
||||
Set `OPENAI_API_KEY` before using the default OpenAI LLM and embedder:
|
||||
|
||||
## 6. Using with async/await
|
||||
```ts
|
||||
import { Memory } from "mem0ai/oss";
|
||||
|
||||
All methods of the MemoryClient return promises, allowing for seamless integration with async/await syntax.
|
||||
const memory = new Memory();
|
||||
|
||||
## 7. Testing the Client
|
||||
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" });
|
||||
|
||||
To test the MemoryClient in a Node.js environment, you can create a simple script to verify the functionality of memory operations.
|
||||
const results = await memory.search("What does Alex eat?", {
|
||||
filters: { user_id: "alex" },
|
||||
topK: 5,
|
||||
});
|
||||
console.log(results.results);
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
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.
|
||||
|
||||
If you have any questions or need assistance, please reach out to us:
|
||||
## 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
|
||||
|
||||
<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: 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 <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).
|
||||
|
||||
## 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
|
||||
- [Join our discord community](https://mem0.ai/discord)
|
||||
- GitHub Issues: [Report bugs or request features](https://github.com/mem0ai/mem0/issues)
|
||||
|
||||
## 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).
|
||||
|
||||
Reference in New Issue
Block a user