---
name: mem0
description: Use Mem0 when building AI agents and applications that need
  persistent, searchable memory across sessions. Reach for this skill when
  implementing user personalization, context retrieval, multi-turn
  conversations, or any workflow where agents must remember facts, preferences,
  and decisions over time. Works with both managed Platform (hosted API) and
  Open Source (self-hosted) deployments.
metadata:
  mintlify-proj: mem0
  version: "1.0"
---

# Mem0 Skill Reference

## Product Summary

Mem0 is a memory layer for AI agents that extracts, stores, and retrieves facts from conversations. It sits between your application and LLM, automatically converting raw messages into structured memories that agents can search and reuse across sessions. Use Mem0 Platform for a managed API (zero infrastructure) or Mem0 Open Source to self-host on your infrastructure.

**Key files and commands:**
- **Platform SDK**: `from mem0 import MemoryClient` (Python) or `import MemoryClient from 'mem0ai'` (JavaScript)
- **OSS SDK**: `from mem0 import Memory` (Python) or `import { Memory } from 'mem0ai/oss'` (JavaScript)
- **REST API**: `POST /v3/memories/add/`, `POST /v3/memories/search/`, `PUT /v3/memories/{id}/`, `DELETE /v3/memories/{id}/`
- **CLI**: `mem0 add`, `mem0 search`, `mem0 init`
- **Primary docs**: https://docs.mem0.ai

## When to Use

Reach for Mem0 when:
- **Building multi-turn agents** that need context from earlier conversations
- **Personalizing responses** based on stored user preferences, history, or decisions
- **Implementing user profiles** that persist across sessions, apps, or agents
- **Scoping memories** by user, agent, app, or session (run_id)
- **Searching for relevant facts** using natural language queries
- **Updating or deleting stale memories** when facts change or users request erasure
- **Integrating with frameworks** like LangChain, CrewAI, LlamaIndex, or OpenAI Agents SDK
- **Choosing between managed vs self-hosted**: Platform for zero infrastructure, OSS for full control

Do not use Mem0 for: storing raw transcripts (use a database), secrets or credentials, or unredacted sensitive data.

## Quick Reference

### Core Operations

| Operation | Platform | OSS | Purpose |
|-----------|----------|-----|---------|
| **Add** | `client.add(messages, user_id=...)` | `memory.add(messages, user_id=...)` | Extract and store facts from conversation |
| **Search** | `client.search(query, filters={...})` | `memory.search(query, filters={...})` | Retrieve relevant memories by natural language |
| **Update** | `client.update(memory_id, text=...)` | `memory.update(memory_id, text=...)` | Modify stored memory content |
| **Delete** | `client.delete(memory_id)` | `memory.delete(memory_id)` | Remove a single memory |
| **Delete All** | `client.delete_all(user_id=...)` | `memory.delete_all(user_id=...)` | Remove memories matching filters |
| **Get** | `client.get(memory_id)` | `memory.get(memory_id)` | Fetch a memory by ID |
| **Get All** | `client.get_all(filters={...})` | `memory.get_all(filters={...})` | List memories matching filters |

### Entity Scoping (Organize Memories)

| Identifier | Use Case | Example |
|-----------|----------|---------|
| `user_id` | Persistent user/account | `"customer_6412"` |
| `agent_id` | Distinct agent persona | `"travel_planner"` |
| `app_id` | White-label app or product | `"ios_retail_demo"` |
| `run_id` | Session, ticket, or flow | `"ticket-9241"` |

Always pass at least `user_id` to scope searches and prevent cross-contamination between users.

### Configuration (OSS Only)

```python
config = {
    "llm": {"provider": "openai", "config": {"model": "gpt-5-mini"}},
    "embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
    "vector_store": {"provider": "qdrant", "config": {"host": "localhost", "port": 6333}},
    "reranker": {"provider": "cohere", "config": {"model": "rerank-v3.5"}},
}
memory = Memory.from_config(config)
```

Supported: 18+ LLM providers, 11+ embedders, 25+ vector stores, 5+ rerankers.

### Filter Syntax

**Platform (JSON logic):**
```python
filters = {
    "AND": [
        {"user_id": "alice"},
        {"agent_id": "chatbot"},
        {"created_at": {"gte": "2024-07-01"}}
    ]
}
```

**OSS (flat dict):**
```python
filters = {
    "user_id": "alice",
    "agent_id": "chatbot",
    "categories": {"contains": "food"}
}
```

## Decision Guidance

### Platform vs Open Source

| Decision | Choose Platform | Choose OSS |
|----------|-----------------|-----------|
| **Infrastructure** | Want zero setup (managed vector DB, LLM, embedder) | Need full control over data and components |
| **Cost** | Usage-based billing acceptable | Prefer fixed costs or local LLMs |
| **Features** | Need Graph Memory, Memory Decay, Temporal Reasoning, Dream | Standard add/search/update/delete sufficient |
| **Scoping** | Need `app_id` for multi-tenant separation | `user_id`, `agent_id`, `run_id` enough |
| **Time to first memory** | Minutes (API key only) | Hours (setup vector DB, LLM, embedder) |

### Search Strategy

| Scenario | Approach |
|----------|----------|
| **Top result must be most relevant** | Use `rerank=True` (adds ~150-200ms latency) |
| **User scans a list of results** | Use basic search (no reranking overhead) |
| **Need exact field matches** | Use metadata filters with `contains` or `in` operators |
| **Temporal queries** ("when did...") | Platform: use `timestamp` field; OSS: no temporal support |

### Inference vs Raw Storage

| Mode | Use Case | Tradeoff |
|------|----------|---------|
| **`infer=True` (default)** | Extract structured facts from conversations | Deduplicates, cleans data; may lose raw context |
| **`infer=False`** | Store raw messages verbatim | Preserves exact text; can create duplicates |

## Workflow

### Typical Agent Memory Loop

1. **Initialize client**
   ```python
   from mem0 import MemoryClient
   client = MemoryClient(api_key="m0-...")
   ```

2. **After agent responds, add memories**
   ```python
   messages = [
       {"role": "user", "content": "I prefer aisle seats and avoid shellfish."},
       {"role": "assistant", "content": "Got it, I'll remember that."}
   ]
   client.add(messages, user_id="alice", metadata={"category": "preferences"})
   ```

3. **Before next agent turn, search for context**
   ```python
   results = client.search(
       "What are my dietary restrictions?",
       filters={"user_id": "alice"},
       rerank=True  # Optional: boost top result accuracy
   )
   ```

4. **Pass retrieved memories to prompt**
   ```python
   context = "\n".join([m["memory"] for m in results["results"]])
   prompt = f"User context:\n{context}\n\nUser: {user_input}"
   ```

5. **Update or delete if facts change**
   ```python
   client.update(memory_id, text="Updated fact")
   client.delete_all(user_id="alice", run_id="session-123")  # Clean up session
   ```

### Multi-Agent Setup

1. Scope each agent with `agent_id`
2. Use `run_id` for session isolation
3. Search with filters matching your agent's scope
4. Clean up with `delete_all(agent_id=..., run_id=...)`

## Common Gotchas

- **Forgetting `user_id` in filters**: Searches without `user_id` may return memories from other users. Always scope.
- **Mixing `infer=True` and `infer=False`**: Same fact stored twice if you switch modes. Pick one and stick with it.
- **AND-ing `user_id` and `agent_id`**: Platform default extraction splits facts by speaker, so `{"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]}` returns nothing. Use `OR` instead.
- **Metadata keys are case-sensitive**: `{"trip": "japan"}` and `{"Trip": "japan"}` are different filters. Use lowercase snake_case.
- **Expired memories still exist**: `expiration_date` hides memories from search/get_all but doesn't delete them. Fetch by ID or call `delete` to remove.
- **Reranking adds latency**: ~150-200ms per search. Use only when top result quality matters.
- **OSS vector store mismatch**: Dimension errors occur if embedder model name doesn't match. Verify model names in config.
- **Platform API key in client code**: Never expose API keys in frontend or public repos. Use server-side requests only.
- **Batch operations**: Platform supports `batch_update` and `batch_delete` (up to 1000); OSS requires looping.
- **Graph Memory is Platform-only**: OSS extracts entities but has no queryable graph. Platform's Graph Memory is built-in.

## Verification Checklist

Before submitting work with Mem0:

- [ ] API key is set and valid (test with `client.project.get()` on Platform)
- [ ] `user_id` is always passed to `add`, `search`, and `delete_all` calls
- [ ] Filters are syntactically correct (test in dashboard or with `explain=True` on OSS)
- [ ] Metadata keys use consistent naming (lowercase snake_case)
- [ ] Memories appear in dashboard or via `get_all` with correct scoping
- [ ] Search returns expected results (not empty, not cross-contaminated)
- [ ] Updates and deletes work without errors
- [ ] Expiration dates are in `YYYY-MM-DD` format if used
- [ ] Reranking is enabled only where latency is acceptable
- [ ] OSS config has all required provider keys in environment variables
- [ ] No secrets, credentials, or unredacted PII stored in memories

## Resources

- **Comprehensive navigation**: https://docs.mem0.ai/llms.txt
- **Platform Quickstart**: https://docs.mem0.ai/platform/quickstart (5-minute setup)
- **Core Concepts**: https://docs.mem0.ai/core-concepts/how-it-works (extraction and retrieval pipeline)
- **Entity Scoping**: https://docs.mem0.ai/platform/features/entity-scoped-memory (user/agent/app/run organization)
- **API Reference**: https://docs.mem0.ai/api-reference (all endpoints and parameters)
- **Open Source Setup**: https://docs.mem0.ai/open-source/configuration (LLM, vector store, embedder config)
- **Integrations**: https://docs.mem0.ai/integrations (LangChain, CrewAI, LlamaIndex, etc.)
- **Cookbooks**: https://docs.mem0.ai/cookbooks/overview (end-to-end examples)

---

> For additional documentation and navigation, see: https://docs.mem0.ai/llms.txt