Platform Features Fresh

Comprehensive reference for all Mem0 platform features.

---

V2 Memory Filters

Precise control over memory retrieval using logical operators and field-level filtering.

Filter Structure

Filters use nested JSON with a logical operator at the root:

{
    "AND": [
        {"user_id": "user_123"},
        {"created_at": {"gte": "2024-01-01"}}
    ]
}

Root operators: AND, OR, NOT (required).

Field Categories

Entity Fields (user_id, agent_id, app_id, run_id):

• Operators: eq, ne, in, * (wildcard)

Time Fields (created_at, updated_at, timestamp):

• Operators: gt, gte, lt, lte, eq, ne

Content Fields (categories, metadata, keywords):

• Operators: eq, ne, in, contains, icontains

Special Fields (memory_ids):

• Operator: in

Constraints

• Wildcard "*" matches non-null values only
• Use keyword operators (gte, not >=)
• Metadata supports only eq, contains, ne
• Memories are stored per-entity; combining user_id AND agent_id yields no results
• Top-level metadata keys only; nested filtering not supported

---

Entity-Scoped Memory

Scope conversations by user, agent, app, and session.

Four Dimensions

Scope	Purpose	Lifecycle
user_id	Persistent personas, preferences	Long-lived
agent_id	Distinct agent personas or tools	Long-lived
app_id	White-label apps, tenant separation	Long-lived
run_id	Tickets, conversation threads	Short-lived

Passing only {"user_id": "alice"} automatically restricts results to records where agent_id, app_id, and run_id are null.

client.add(
    messages,
    user_id="teacher_872",
    agent_id="study_planner",
    app_id="district_dashboard",
    run_id="prep-period-2025-09-02"
)

---

Custom Instructions

Natural language guidelines for controlling what Mem0 captures.

# Set instructions
client.project.update(custom_instructions="Only capture dietary preferences and allergies.")

# Retrieve
response = client.project.get(fields=["custom_instructions"])

Structure your instructions with: task description, categories to extract, processing guidelines, and explicit exclusions.

---

Async Client & Async Mode

Async Client (Python)

from mem0 import AsyncMemoryClient

client = AsyncMemoryClient()
await client.add(messages, user_id="alice")
results = await client.search("preferences", user_id="alice")

Async Mode (Default)

Memories are processed asynchronously by default (async_mode=true). The API returns event IDs for tracking:

result = client.add(messages, user_id="alice")
# Returns event IDs for tracking progress

Set async_mode=false to process synchronously (waits for completion).

---

Advanced Retrieval

Enhanced search with reranking and keyword search:

results = client.search(
    query="food preferences",
    user_id="alice",
    rerank=True,
    keyword_search=True,
    threshold=0.5,
    top_k=10
)

---

Criteria Retrieval

Filter memories by specific criteria during retrieval using output_format="v1.1" for graph-enriched results.

---

Contextual Add

Use includes and excludes parameters to control what gets extracted:

client.add(
    messages,
    user_id="alice",
    includes="dietary preferences, allergies",
    excludes="general greetings, small talk"
)

---

Direct Import

Store text directly without inference:

client.add(
    messages,
    user_id="alice",
    infer=False  # Store as-is without AI extraction
)

---

Memory Export

Export memories in structured formats:

# Create export
export = client.create_export(schema=your_schema, user_id="alice")

# Retrieve export
data = client.get_export(export_id=export["id"])

---

Timestamp

Associate Unix timestamps with memories:

client.add(
    messages,
    user_id="alice",
    timestamp=1704067200  # Unix timestamp
)

---

Expiration Date

Set automatic expiry for memories:

client.add(
    messages,
    user_id="alice",
    expiration_date="2025-12-31"  # YYYY-MM-DD format
)

---

Feedback Mechanism

Provide feedback on memory quality:

client.feedback(
    memory_id="mem_id",
    feedback="POSITIVE",  # POSITIVE, NEGATIVE, VERY_NEGATIVE
    feedback_reason="Accurate memory"
)

---

Group Chat

Support multi-participant conversations by scoping memories with run_id for the session and individual user_id values for each participant.

---

MCP Integration

Connect AI clients to Mem0 using Model Context Protocol for universal memory access.

Quick Setup

npx mcp-add --name mem0-mcp --type http --url "https://mcp.mem0.ai/mcp"

Available Tools (9)

Tool	Function
add_memory	Save user/agent information
search_memories	Semantic search with filters
get_memories	List with pagination
get_memory	Retrieve by ID
update_memory	Modify existing
delete_memory	Remove single entry
delete_all_memories	Bulk deletion
delete_entities	Remove user/agent/app/run
list_entities	Enumerate stored entities

Works with Claude, Cursor, Windsurf, VS Code, and other MCP-compatible clients.

---

Graph Threshold

Control entity relationship extraction sensitivity with enable_graph: true when adding memories.