/skills/mem0/client/python.md

Mem0 Python SDK Reference

Complete reference for the mem0ai Python package. Covers both the Platform client (managed API) and the Open Source self-hosted variant.

---

Platform Client

Installation

pip install mem0ai
export MEM0_API_KEY="m0-your-api-key"

MemoryClient (Synchronous)

from mem0 import MemoryClient

client = MemoryClient(api_key="m0-xxx")

Constructor: MemoryClient(api_key=None). If api_key is not provided, reads from MEM0_API_KEY environment variable. Raises ValueError if no key found.

• HTTP library: httpx
• Timeout: 300 seconds
• Base URL: https://api.mem0.ai

AsyncMemoryClient (Asynchronous)

from mem0 import AsyncMemoryClient

client = AsyncMemoryClient(api_key="m0-xxx")

# Or use as context manager
async with AsyncMemoryClient(api_key="m0-xxx") as client:
    results = await client.search("query", filters={"user_id": "alice"})

Same methods as MemoryClient, all async/await. Supports async context manager.

---

Memory Methods

add(messages, **kwargs)

Store new memories from messages.

messages = [
    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
    {"role": "assistant", "content": "Got it! I'll remember that."}
]
client.add(messages, user_id="alice")

Parameter	Type	Default	Description
messages	str | dict | list[dict]	required	Message content. Strings auto-convert to user messages
user_id	str	None	User identifier
agent_id	str	None	Agent identifier
app_id	str	None	Application identifier
run_id	str	None	Session/run identifier
metadata	dict	None	Custom key-value pairs
infer	bool	True	If False, store raw text without LLM inference
custom_categories	list	None	Override project categories
custom_instructions	str	None	Override extraction instructions
timestamp	int | float | str	None	Custom timestamp (Unix epoch or ISO 8601)

Returns: dict -- list of events: [{"id": "...", "event": "ADD", "data": {"memory": "..."}}]

search(query, **kwargs)

Search memories by semantic similarity.

results = client.search("dietary preferences", filters={"user_id": "alice"})
for mem in results.get("results", []):
    print(mem["memory"], mem["score"])

Parameter	Type	Default	Description
query	str	required	Natural language search query
filters	dict	None	Filter object with entity IDs and/or AND/OR/NOT conditions (e.g., {"user_id": "alice"})
top_k	int	10	Number of results
rerank	bool	False	Enable deep semantic reranking (+150-200ms)
threshold	float	0.1	Minimum similarity score
fields	list	None	Specific fields to return
categories	list	None	Filter by category

Returns: dict -- {"results": [{id, memory, user_id, categories, score, created_at, ...}]}

get(memory_id)

Retrieve a single memory by ID.

memory = client.get(memory_id="ea925981-...")

Returns: dict -- full memory object

get_all(**kwargs)

Retrieve all memories with optional filtering. Requires at least one entity identifier.

memories = client.get_all(filters={"user_id": "alice"})
# With compound filters
memories = client.get_all(filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "health"}}]})

Parameter	Type	Default	Description
filters	dict	None	Filter object with entity IDs and/or AND/OR/NOT conditions
top_k	int	None	Limit results
page	int	None	Page number
page_size	int	None	Results per page

Returns: dict -- {"results": [...]}

update(memory_id, text=None, metadata=None, timestamp=None)

Update a memory's content, metadata, or timestamp. At least one parameter required.

client.update("ea925981-...", text="Updated: vegan since 2024")
client.update("ea925981-...", metadata={"verified": True})

Returns: dict -- updated memory

delete(memory_id)

Permanently delete a single memory.

client.delete("ea925981-...")

delete_all(**kwargs)

Delete all memories matching filters. Irreversible.

client.delete_all(user_id="alice")

history(memory_id)

Get the change history of a memory.

history = client.history("ea925981-...")
# Returns: [{previous_value, new_value, action, timestamps}]

---

Batch Methods

batch_update(memories)

Update up to 1000 memories in a single request.

client.batch_update([
    {"memory_id": "uuid-1", "text": "Updated text"},
    {"memory_id": "uuid-2", "text": "Another update", "metadata": {"verified": True}},
])

batch_delete(memories)

Delete up to 1000 memories in a single request.

client.batch_delete([
    {"memory_id": "uuid-1"},
    {"memory_id": "uuid-2"},
])

---

User/Entity Management

users()

List all users, agents, and sessions that have memories.

users = client.users()
# Returns: {"results": [{"type": "user", "name": "alice"}, ...]}

delete_users(user_id=None, agent_id=None, app_id=None, run_id=None)

Delete a specific entity and all its memories.

client.delete_users(user_id="alice")

reset()

Delete ALL users, agents, sessions, and memories. Complete data reset.

client.reset()

---

Export & Summary

create_memory_export(schema, **kwargs)

Create a structured export of memories.

import json

schema = json.dumps({
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "preferences": {"type": "array", "items": {"type": "string"}},
    }
})
export = client.create_memory_export(schema=schema, user_id="alice")

get_memory_export(**kwargs)

Retrieve a previously created export.

result = client.get_memory_export(memory_export_id=export["id"])

get_summary(filters=None)

Get a summary of memories.

summary = client.get_summary(filters={"user_id": "alice"})

---

Feedback

feedback(memory_id, feedback=None, feedback_reason=None)

Provide quality feedback on a memory.

client.feedback(
    memory_id="mem-123",
    feedback="POSITIVE",  # POSITIVE | NEGATIVE | VERY_NEGATIVE | None (clear)
    feedback_reason="Accurately captured preference"
)

---

Webhooks

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

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

# Update
client.update_webhook(webhook_id=123, name="Updated", url="https://new-url.com")

# Delete
client.delete_webhook(webhook_id=123)

---

Project Management

Access via client.project.*:

# Get project config
config = client.project.get(fields=["custom_categories", "custom_instructions"])

# Update project settings
client.project.update(
    custom_instructions="Extract dietary preferences and health info",
    custom_categories=[{"health": "Medical and dietary info"}],
    multilingual=True,
)

# Create/delete project
client.project.create(name="My Project", description="...")
client.project.delete()

# Member management
members = client.project.get_members()
client.project.add_member(email="user@example.com", role="READER")  # READER or OWNER
client.project.update_member(email="user@example.com", role="OWNER")
client.project.remove_member(email="user@example.com")

---

Open Source / Self-Hosted

Installation

pip install mem0ai

Memory Class

from mem0 import Memory

m = Memory()  # Uses default config (OpenAI embedder + in-memory vector store)

Import: from mem0 import Memory (NOT MemoryClient -- that is the Platform client)

Configuration

config = {
    "llm": {
        "provider": "openai",        # openai, groq, azure, ollama, lmstudio, google, anthropic, mistral
        "config": {
            "model": "gpt-5-mini",
            "api_key": "sk-xxx",
        }
    },
    "embedder": {
        "provider": "openai",        # openai, ollama, azure, lmstudio, google, huggingface
        "config": {
            "model": "text-embedding-3-small",
            "api_key": "sk-xxx",
        }
    },
    "vector_store": {
        "provider": "qdrant",        # faiss, qdrant, pgvector, redis, supabase, azure_ai_search, memory
        "config": {
            "collection_name": "my_memories",
            "host": "localhost",
            "port": 6333,
        }
    },
    "history_db_path": "history.db",              # SQLite path for change history
    "custom_instructions": "...",                  # Custom LLM prompt for extraction
}

m = Memory.from_config(config)

Context Manager

with Memory(config) as m:
    m.add("I prefer dark mode", user_id="alice")
    results = m.search("preferences", filters={"user_id": "alice"})
# SQLite connections released automatically

Methods

All methods mirror the Platform client but run locally:

add(messages, *, user_id, agent_id, run_id, metadata, infer=True)

m.add("I'm a vegetarian", user_id="alice")
m.add([
    {"role": "user", "content": "I like hiking"},
    {"role": "assistant", "content": "Great outdoor activity!"}
], user_id="alice")

At least one of user_id, agent_id, run_id required.

Returns: {"results": [...], "relations": [...]}

search(query, *, filters=None, top_k=20, threshold=0.1, rerank=False)

results = m.search("dietary preferences", filters={"user_id": "alice"}, top_k=5)

Entity IDs (user_id, agent_id, run_id) must be passed inside the filters dict.

Supports filter operators: eq, ne, in, nin, gt, gte, lt, lte, contains, not_contains.

get(memory_id) / get_all(**kwargs) / update(memory_id, data, metadata=None) / delete(memory_id) / delete_all(**kwargs) / history(memory_id)

Same interface as Platform client.

reset()

Clear the entire vector store collection and history database. Recreates the vector store.

m.reset()

close()

Release SQLite connections. Called automatically when using context manager.

AsyncMemory

from mem0 import AsyncMemory

m = AsyncMemory(config)
await m.add("text", user_id="alice")
results = await m.search("query", filters={"user_id": "alice"})

---

Key Differences: Platform vs OSS

Aspect	Platform (MemoryClient)	OSS (Memory)
Import	from mem0 import MemoryClient	from mem0 import Memory
Auth	API key required (MEM0_API_KEY)	No API key -- config-based
Execution	API calls to api.mem0.ai	Local execution
Infrastructure	Fully managed	Self-managed vector DB, embedder, LLM
Entity filtering	filters={"user_id": "..."}	filters={"user_id": "..."}
Batch ops	batch_update, batch_delete	Not available
Webhooks	Full CRUD	Not available
Export	create_memory_export, get_memory_export	Not available
Feedback	feedback()	Not available
Project mgmt	client.project.*	Not available
User listing	users(), delete_users()	Not available
Custom prompts	Via project settings	Direct config (custom_instructions)
History	Platform-managed	SQLite (configurable)
Async	AsyncMemoryClient	AsyncMemory

---

v2 Compatibility

If you're using SDK v2.x or the v2 API:

API Changes:

• Entity IDs in search/get_all: Pass user_id, agent_id as top-level kwargs instead of inside filters

  # v2
  results = client.search("query", user_id="alice")
  # v3
  results = client.search("query", filters={"user_id": "alice"})
  

• add() returns: v2 returns ADD, UPDATE, DELETE events; v3 returns ADD only

Default Changes:

Param	v2	v3
top_k	100	20
threshold	None	0.1
rerank	True	False

Removed Parameters:

• Constructor: org_id, project_id
• add(): async_mode, output_format, enable_graph, immutable, expiration_date, filter_memories, batch_size, force_add_only, includes, excludes, keyword_search
• search()/get_all(): enable_graph
• Config: enable_graph, graph_store, custom_fact_extraction_prompt (renamed to custom_instructions)

See the v2 to v3 migration guide for full details.