Platform Features -- Mem0 Platform

Additional platform capabilities beyond core CRUD operations.

Table of Contents

• Advanced Retrieval
• Entity Linking
• Custom Categories
• Custom Instructions
• Feedback Mechanism
• Memory Export
• Group Chat
• MCP Integration
• Webhooks
• Multimodal Support

Advanced Retrieval

Hybrid Search (v3 Default)

v3 uses multi-signal hybrid search combining:

• Semantic search (vector similarity)
• BM25 keyword search (normalized term matching)
• Entity matching (entity graph boost)

This is automatic — no configuration needed.

Reranking (rerank=True)

Deep semantic reordering of results — most relevant first.

• Latency: +150-200ms
• Default: False (was True in v2)
• Best for: user-facing results, top-N precision

Python:

results = client.search(query, filters={"user_id": "user123"}, rerank=True)

TypeScript:

const results = await client.search(query, {
    filters: { user_id: 'user123' },
    rerank: true,
});

---

Entity Linking

v3 replaces graph memory with built-in entity linking. Entities (proper nouns, quoted text, compound noun phrases) are automatically extracted and linked across memories.

How It Works

1. Extraction: During add(), entities are automatically extracted from memory text
2. Storage: Entities are stored in a parallel collection ({collection}_entities)
3. Retrieval: During search(), query entities are matched and used to boost relevant memories

Entity linking is automatic — no configuration required. The boost is folded into the combined score on each result.

v2 Migration Note

If you were using enable_graph=True in v2:

• Remove enable_graph from all API calls
• Remove graph_store from OSS configuration
• Entity relationships are now consumed through retrieval ranking, not exposed as a separate relations array

See the v2 to v3 migration guide for details.

---

Custom Categories

Replace Mem0's default 15 labels with domain-specific categories. The system automatically tags memories to the closest matching category.

Default Categories (15)

personal_details, family, professional_details, sports, travel, food, music, health, technology, hobbies, fashion, entertainment, milestones, user_preferences, misc

Configuration

Set project-level categories:

new_categories = [
    {"lifestyle_management": "Tracks daily routines, habits, wellness activities"},
    {"seeking_structure": "Documents goals around creating routines and systems"},
    {"personal_information": "Basic information about the user"}
]
client.project.update(custom_categories=new_categories)

await client.updateProject({ customCategories: newCategories });

Retrieve active categories:

categories = client.project.get(fields=["custom_categories"])

Override categories for a single add call:

client.add(messages, user_id="alice", custom_categories=per_call_categories)

await client.add(messages, { userId: "alice", customCategories: perCallCategories });

Resolution Order

1. custom_categories passed on the add call
2. custom_categories set on the project
3. Built-in default catalog

Key Constraints

• A per-call list fully replaces the project list for that call. The lists are not merged.
• Categories are applied at ingestion time. Changing the list later does not re-tag existing memories.

Main Use Case

Per-call lists give different users or entities their own vocabulary inside a single project, without splitting them across projects.

---

Custom Instructions

Natural language filters that control what information Mem0 extracts when creating memories.

Set Instructions

client.project.update(custom_instructions="Your guidelines here...")

await client.updateProject({ customInstructions: "Your guidelines here..." });

Template Structure

1. Task Description -- brief extraction overview
2. Information Categories -- numbered sections with specific details to capture
3. Processing Guidelines -- quality and handling rules
4. Exclusion List -- sensitive/irrelevant data to filter out

Domain Examples

E-commerce: Capture product issues, preferences, service experience; exclude payment data.

Education: Extract learning progress, student preferences, performance patterns; exclude specific grades.

Finance: Track financial goals, life events, investment interests; exclude account numbers and SSNs.

Best Practices

• Start simply, test with sample messages, iterate based on results
• Avoid overly lengthy instructions
• Be specific about what to include AND exclude

---

Feedback Mechanism

Provide feedback on extracted memories to improve system quality over time.

Feedback Types

Usage

Python:

client.feedback(
    memory_id="mem-123",
    feedback="POSITIVE",
    feedback_reason="Accurately captured dietary preference"
)

# Bulk feedback
for item in feedback_data:
    client.feedback(**item)

TypeScript:

await client.feedback('mem-123', {
    feedback: 'POSITIVE',
    feedbackReason: 'Accurately captured dietary preference',
});

---

Memory Export

Create structured exports of memories using customizable schemas with filters.

Usage

import json

# Define export schema
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "preferences": {"type": "array", "items": {"type": "string"}},
        "health_info": {"type": "string"},
    }
}

# Create export
response = client.create_memory_export(
    schema=json.dumps(schema),
    filters={"user_id": "alice"},
    export_instructions="Create comprehensive profile based on all memories"
)

# Retrieve export (may take a moment to process)
result = client.get_memory_export(memory_export_id=response["id"])

Best for: Data analytics, user profile generation, compliance audits, CRM sync.

---

Group Chat

Process multi-participant conversations and automatically attribute memories to individual speakers.

Usage

messages = [
    {"role": "user", "name": "Alice", "content": "I think we should use React for the frontend"},
    {"role": "user", "name": "Bob", "content": "I prefer Vue.js, it's simpler for our use case"},
    {"role": "assistant", "content": "Both are great choices. Let me note your preferences."},
]

# Mem0 automatically attributes memories to each speaker
response = client.add(messages, run_id="team_meeting_1")

# Retrieve Alice's memories from that session
alice_mems = client.get_all(
    filters={"AND": [{"user_id": "alice"}, {"run_id": "team_meeting_1"}]}
)

Use the name field in messages to identify speakers. Mem0 maps names to entity scopes automatically.

---

MCP Integration

Model Context Protocol integration enables AI clients (Claude, Claude Code, Cursor, Windsurf, VS Code, OpenCode) to manage Mem0 memory autonomously.

Setup

Add Mem0 MCP to your clients with a single command:

npx mcp-add \
  --name mem0-mcp \
  --type http \
  --url "https://mcp.mem0.ai/mcp" \
  --clients "claude,claude code,cursor,windsurf,vscode,opencode"

Available MCP Tools

The MCP server exposes 9 memory tools that AI agents can use autonomously:

• Add, search, get, update, delete memories
• Get history, list users, delete users
• Search Mem0 documentation

How It Works

1. Add Mem0 MCP to your AI client using the setup command above
2. The agent autonomously decides when to store/retrieve memories
3. No manual API calls needed — the agent manages memory as part of its reasoning

Best for: Universal AI client integration — one protocol works everywhere.

---

Webhooks

Real-time event notifications for memory operations.

Supported Events

Create Webhook

Note: project_id here refers to the Mem0 dashboard project scope for webhooks — not the deprecated client init parameter.

webhook = client.create_webhook(
    url="https://your-app.com/webhook",
    name="Memory Logger",
    project_id="proj_123",
    event_types=["memory_add", "memory_categorize"]
)

Manage Webhooks

# Retrieve
webhooks = client.get_webhooks(project_id="proj_123")

# Update
client.update_webhook(
    name="Updated Logger",
    url="https://your-app.com/new-webhook",
    event_types=["memory_update", "memory_add"],
    webhook_id="wh_123"
)

# Delete
client.delete_webhook(webhook_id="wh_123")

Payload Structure

Memory events contain: ID, data object with memory content, event type (ADD/UPDATE/DELETE). Categorization events contain: memory ID, event type (CATEGORIZE), assigned category labels.

---

Multimodal Support

Mem0 can process images and documents alongside text.

Supported Media Types

• Images: JPG, PNG
• Documents: MDX, TXT, PDF

Image via URL

image_message = {
    "role": "user",
    "content": {
        "type": "image_url",
        "image_url": {"url": "https://example.com/image.jpg"}
    }
}
client.add([image_message], user_id="alice")

Image via Base64

import base64
with open("photo.jpg", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode("utf-8")

image_message = {
    "role": "user",
    "content": {
        "type": "image_url",
        "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}
    }
}
client.add([image_message], user_id="alice")

Document (MDX/TXT)

doc_message = {
    "role": "user",
    "content": {"type": "mdx_url", "mdx_url": {"url": document_url}}
}
client.add([doc_message], user_id="alice")

PDF Document

pdf_message = {
    "role": "user",
    "content": {"type": "pdf_url", "pdf_url": {"url": pdf_url}}
}
client.add([pdf_message], user_id="alice")