feat(skills): add Mem0 Platform Claude Code skill (#4309)
This commit is contained in:
Kartik
@@ -0,0 +1,189 @@
|
|||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but not
|
||||||
|
limited to compiled object code, generated documentation, and
|
||||||
|
conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work.
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to the Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by the Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding any notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
|
|
||||||
|
Copyright 2024 Mem0.ai
|
||||||
|
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License");
|
||||||
|
you may not use this file except in compliance with the License.
|
||||||
|
You may obtain a copy of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||||
|
See the License for the specific language governing permissions and
|
||||||
|
limitations under the License.
|
||||||
@@ -0,0 +1,79 @@
|
|||||||
|
# Mem0 Skill for Claude
|
||||||
|
|
||||||
|
Add persistent memory to any AI application in minutes using [Mem0 Platform](https://app.mem0.ai).
|
||||||
|
|
||||||
|
## What This Skill Does
|
||||||
|
|
||||||
|
When installed, Claude can:
|
||||||
|
|
||||||
|
- **Set up Mem0** in your Python or TypeScript project
|
||||||
|
- **Integrate memory** into your existing AI app (LangChain, CrewAI, Vercel AI, OpenAI Agents, LangGraph, LlamaIndex, etc.)
|
||||||
|
- **Generate working code** using real API references and tested patterns
|
||||||
|
- **Search live docs** on demand for the latest Mem0 documentation
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Claude.ai
|
||||||
|
|
||||||
|
1. Download this `skills/mem0` folder as a ZIP
|
||||||
|
2. Go to **Settings > Capabilities > Skills**
|
||||||
|
3. Click **Upload skill** and select the ZIP
|
||||||
|
|
||||||
|
### Claude API (Skills API)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST https://api.anthropic.com/v1/skills \
|
||||||
|
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"name": "mem0", "source": "https://github.com/mem0ai/mem0/tree/main/skills/mem0"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- A Mem0 Platform API key ([Get one here](https://app.mem0.ai/dashboard/api-keys))
|
||||||
|
- Python 3.10+ or Node.js 18+
|
||||||
|
- Set the environment variable:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export MEM0_API_KEY="m0-your-api-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
After installing, just ask Claude:
|
||||||
|
|
||||||
|
- "Set up mem0 in my project"
|
||||||
|
- "Add memory to my chatbot"
|
||||||
|
- "Help me search user memories with filters"
|
||||||
|
- "Integrate mem0 with my LangChain app"
|
||||||
|
- "Add graph memory to track entity relationships"
|
||||||
|
|
||||||
|
## What's Inside
|
||||||
|
|
||||||
|
```text
|
||||||
|
skills/mem0/
|
||||||
|
├── SKILL.md # Skill definition and instructions
|
||||||
|
├── README.md # This file
|
||||||
|
├── LICENSE # Apache-2.0
|
||||||
|
├── scripts/
|
||||||
|
│ └── mem0_doc_search.py # Search live Mem0 docs on demand
|
||||||
|
└── references/ # Documentation (loaded on demand)
|
||||||
|
├── quickstart.md # Full quickstart (Python, TS, cURL)
|
||||||
|
├── sdk-guide.md # All SDK methods (Python + TypeScript)
|
||||||
|
├── api-reference.md # REST endpoints, filters, memory object
|
||||||
|
├── architecture.md # Processing pipeline, lifecycle, scoping, performance
|
||||||
|
├── features.md # Retrieval, graph, categories, MCP, webhooks, multimodal
|
||||||
|
├── integration-patterns.md # LangChain, CrewAI, Vercel AI, LangGraph, LlamaIndex, etc.
|
||||||
|
└── use-cases.md # 7 real-world patterns with Python + TypeScript code
|
||||||
|
```
|
||||||
|
|
||||||
|
## Links
|
||||||
|
|
||||||
|
- [Mem0 Platform Dashboard](https://app.mem0.ai)
|
||||||
|
- [Mem0 Documentation](https://docs.mem0.ai)
|
||||||
|
- [Mem0 GitHub](https://github.com/mem0ai/mem0)
|
||||||
|
- [API Reference](https://docs.mem0.ai/api-reference)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Apache-2.0
|
||||||
@@ -0,0 +1,156 @@
|
|||||||
|
---
|
||||||
|
name: mem0
|
||||||
|
description: >
|
||||||
|
Integrate Mem0 Platform into AI applications for persistent memory, personalization, and semantic search.
|
||||||
|
Use this skill when the user mentions "mem0", "memory layer", "remember user preferences",
|
||||||
|
"persistent context", "personalization", or needs to add long-term memory to chatbots, agents,
|
||||||
|
or AI apps. Covers Python and TypeScript SDKs, framework integrations (LangChain, CrewAI,
|
||||||
|
Vercel AI SDK, OpenAI Agents SDK, Pipecat), and the full Platform API. Use even when the user
|
||||||
|
doesn't explicitly say "mem0" but describes needing conversation memory, user context retention,
|
||||||
|
or knowledge retrieval across sessions.
|
||||||
|
license: Apache-2.0
|
||||||
|
metadata:
|
||||||
|
author: mem0ai
|
||||||
|
version: "1.0.0"
|
||||||
|
category: ai-memory
|
||||||
|
tags: "memory, personalization, ai, python, typescript, vector-search"
|
||||||
|
compatibility: Requires Python 3.10+ or Node.js 18+, pip install mem0ai or npm install mem0ai, MEM0_API_KEY env var, and internet access to api.mem0.ai
|
||||||
|
---
|
||||||
|
|
||||||
|
# Mem0 Platform Integration
|
||||||
|
|
||||||
|
Mem0 is a managed memory layer for AI applications. It stores, retrieves, and manages user memories via API — no infrastructure to deploy.
|
||||||
|
|
||||||
|
## Step 1: Install and authenticate
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```bash
|
||||||
|
pip install mem0ai
|
||||||
|
export MEM0_API_KEY="m0-your-api-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript/JavaScript:**
|
||||||
|
```bash
|
||||||
|
npm install mem0ai
|
||||||
|
export MEM0_API_KEY="m0-your-api-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
Get an API key at: https://app.mem0.ai/dashboard/api-keys
|
||||||
|
|
||||||
|
## Step 2: Initialize the client
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
client = MemoryClient(api_key="m0-xxx")
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
const client = new MemoryClient({ apiKey: 'm0-xxx' });
|
||||||
|
```
|
||||||
|
|
||||||
|
For async Python, use `AsyncMemoryClient`.
|
||||||
|
|
||||||
|
## Step 3: Core operations
|
||||||
|
|
||||||
|
Every Mem0 integration follows the same pattern: **retrieve → generate → store**.
|
||||||
|
|
||||||
|
### Add memories
|
||||||
|
```python
|
||||||
|
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")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Search memories
|
||||||
|
```python
|
||||||
|
results = client.search("dietary preferences", user_id="alice")
|
||||||
|
for mem in results.get("results", []):
|
||||||
|
print(mem["memory"])
|
||||||
|
```
|
||||||
|
|
||||||
|
### Get all memories
|
||||||
|
```python
|
||||||
|
all_memories = client.get_all(user_id="alice")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Update a memory
|
||||||
|
```python
|
||||||
|
client.update("memory-uuid", text="Updated: vegetarian, nut allergy, prefers organic")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Delete a memory
|
||||||
|
```python
|
||||||
|
client.delete("memory-uuid")
|
||||||
|
client.delete_all(user_id="alice") # delete all for a user
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common integration pattern
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
from openai import OpenAI
|
||||||
|
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
openai = OpenAI()
|
||||||
|
|
||||||
|
def chat(user_input: str, user_id: str) -> str:
|
||||||
|
# 1. Retrieve relevant memories
|
||||||
|
memories = mem0.search(user_input, user_id=user_id)
|
||||||
|
context = "\n".join([m["memory"] for m in memories.get("results", [])])
|
||||||
|
|
||||||
|
# 2. Generate response with memory context
|
||||||
|
response = openai.chat.completions.create(
|
||||||
|
model="gpt-4.1-nano-2025-04-14",
|
||||||
|
messages=[
|
||||||
|
{"role": "system", "content": f"User context:\n{context}"},
|
||||||
|
{"role": "user", "content": user_input},
|
||||||
|
]
|
||||||
|
)
|
||||||
|
reply = response.choices[0].message.content
|
||||||
|
|
||||||
|
# 3. Store interaction for future context
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": user_input}, {"role": "assistant", "content": reply}],
|
||||||
|
user_id=user_id
|
||||||
|
)
|
||||||
|
return reply
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common edge cases
|
||||||
|
|
||||||
|
- **Search returns empty:** Memories process asynchronously. Wait 2-3s after `add()` before searching. Also verify `user_id` matches exactly (case-sensitive).
|
||||||
|
- **AND filter with user_id + agent_id returns empty:** Entities are stored separately. Use `OR` instead, or query separately.
|
||||||
|
- **Duplicate memories:** Don't mix `infer=True` (default) and `infer=False` for the same data. Stick to one mode.
|
||||||
|
- **Wrong import:** Always use `from mem0 import MemoryClient` (or `AsyncMemoryClient` for async). Do not use `from mem0 import Memory`.
|
||||||
|
- **Immutable memories:** Cannot be updated or deleted once created. Use `client.history(memory_id)` to track changes over time.
|
||||||
|
|
||||||
|
## Live documentation search
|
||||||
|
|
||||||
|
For the latest docs beyond what's in the references, use the doc search tool:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python scripts/mem0_doc_search.py --query "topic"
|
||||||
|
python scripts/mem0_doc_search.py --page "/platform/features/graph-memory"
|
||||||
|
python scripts/mem0_doc_search.py --index
|
||||||
|
```
|
||||||
|
|
||||||
|
No API key needed — searches docs.mem0.ai directly.
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
Load these on demand for deeper detail:
|
||||||
|
|
||||||
|
| Topic | File |
|
||||||
|
|-------|------|
|
||||||
|
| Quickstart (Python, TS, cURL) | [references/quickstart.md](references/quickstart.md) |
|
||||||
|
| SDK guide (all methods, both languages) | [references/sdk-guide.md](references/sdk-guide.md) |
|
||||||
|
| API reference (endpoints, filters, object schema) | [references/api-reference.md](references/api-reference.md) |
|
||||||
|
| Architecture (pipeline, lifecycle, scoping, performance) | [references/architecture.md](references/architecture.md) |
|
||||||
|
| Platform features (retrieval, graph, categories, MCP, etc.) | [references/features.md](references/features.md) |
|
||||||
|
| Framework integrations (LangChain, CrewAI, Vercel AI, etc.) | [references/integration-patterns.md](references/integration-patterns.md) |
|
||||||
|
| Use cases & examples (real-world patterns with code) | [references/use-cases.md](references/use-cases.md) |
|
||||||
@@ -0,0 +1,140 @@
|
|||||||
|
# Mem0 Platform API Reference
|
||||||
|
|
||||||
|
REST API endpoints for the Mem0 Platform. Base URL: `https://api.mem0.ai`
|
||||||
|
|
||||||
|
All endpoints require: `Authorization: Token <MEM0_API_KEY>`
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
| Operation | Method | URL |
|
||||||
|
|-----------|--------|-----|
|
||||||
|
| Add Memories | `POST` | `/v1/memories/` |
|
||||||
|
| Search Memories | `POST` | `/v2/memories/search/` |
|
||||||
|
| Get All Memories | `POST` | `/v2/memories/` |
|
||||||
|
| Get Single Memory | `GET` | `/v1/memories/{memory_id}/` |
|
||||||
|
| Update Memory | `PUT` | `/v1/memories/{memory_id}/` |
|
||||||
|
| Delete Memory | `DELETE` | `/v1/memories/{memory_id}/` |
|
||||||
|
|
||||||
|
## Memory Object Structure
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `id` | string (UUID) | Unique memory identifier |
|
||||||
|
| `memory` | string | Text content of the memory |
|
||||||
|
| `user_id` | string | Associated user |
|
||||||
|
| `agent_id` | string (nullable) | Agent identifier |
|
||||||
|
| `app_id` | string (nullable) | Application identifier |
|
||||||
|
| `run_id` | string (nullable) | Run/session identifier |
|
||||||
|
| `metadata` | object | Custom key-value pairs |
|
||||||
|
| `categories` | array of strings | Auto-assigned category tags |
|
||||||
|
| `immutable` | boolean | If true, prevents modification |
|
||||||
|
| `expiration_date` | datetime (nullable) | Auto-expiry date |
|
||||||
|
| `hash` | string | Content hash |
|
||||||
|
| `created_at` | datetime | Creation timestamp |
|
||||||
|
| `updated_at` | datetime | Last modification timestamp |
|
||||||
|
|
||||||
|
Search results additionally include `score` (relevance metric).
|
||||||
|
|
||||||
|
## Scoping Identifiers
|
||||||
|
|
||||||
|
Memories can be scoped to different levels:
|
||||||
|
|
||||||
|
| Scope | Parameter | Use Case |
|
||||||
|
|-------|-----------|----------|
|
||||||
|
| User | `user_id` | Per-user memory isolation |
|
||||||
|
| Agent | `agent_id` | Per-agent memory partitioning |
|
||||||
|
| Application | `app_id` | Cross-agent app-level memory |
|
||||||
|
| Run/Session | `run_id` | Session-scoped temporary memory |
|
||||||
|
|
||||||
|
**Critical:** Combining `user_id` and `agent_id` in a single AND filter yields empty results. Entities are stored separately. Use `OR` logic or separate queries.
|
||||||
|
|
||||||
|
## Processing Model
|
||||||
|
|
||||||
|
- Memories are processed **asynchronously by default** (`async_mode=true`)
|
||||||
|
- Add responses return queued events (`ADD`, `UPDATE`, `DELETE`) for tracking
|
||||||
|
- Set `async_mode=false` for synchronous processing when needed
|
||||||
|
- Graph metadata is processed asynchronously -- use `get_all()` for complete graph data
|
||||||
|
|
||||||
|
## Filter System
|
||||||
|
|
||||||
|
Filters use nested JSON with a logical operator at the root:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"AND": [
|
||||||
|
{"user_id": "alice"},
|
||||||
|
{"categories": {"contains": "finance"}},
|
||||||
|
{"created_at": {"gte": "2024-01-01"}}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Root must be `AND`, `OR`, or `NOT`. Simple shorthand `{"user_id": "alice"}` also works.
|
||||||
|
|
||||||
|
### Supported Operators
|
||||||
|
|
||||||
|
| Operator | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| `eq` | Equal to (default) |
|
||||||
|
| `ne` | Not equal to |
|
||||||
|
| `in` | Matches any value in array |
|
||||||
|
| `gt`, `gte` | Greater than / greater than or equal |
|
||||||
|
| `lt`, `lte` | Less than / less than or equal |
|
||||||
|
| `contains` | Case-sensitive containment |
|
||||||
|
| `icontains` | Case-insensitive containment |
|
||||||
|
| `*` | Wildcard -- matches any non-null value |
|
||||||
|
|
||||||
|
### Filterable Fields
|
||||||
|
|
||||||
|
| Field | Valid Operators |
|
||||||
|
|-------|-----------------|
|
||||||
|
| `user_id`, `agent_id`, `app_id`, `run_id` | `eq`, `ne`, `in`, `*` |
|
||||||
|
| `created_at`, `updated_at`, `timestamp` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` |
|
||||||
|
| `categories` | `eq`, `ne`, `in`, `contains` |
|
||||||
|
| `metadata` | `eq`, `ne`, `contains` (top-level keys only) |
|
||||||
|
| `keywords` | `contains`, `icontains` |
|
||||||
|
| `memory_ids` | `in` |
|
||||||
|
|
||||||
|
### Filter Constraints
|
||||||
|
|
||||||
|
1. **Entity scope partitioning:** `user_id` AND `agent_id` in one `AND` block yields empty results.
|
||||||
|
2. **Metadata limitations:** Only top-level keys. Only `eq`, `contains`, `ne`. No `in` or `gt`.
|
||||||
|
3. **Operator syntax:** Use `gte`, `lt`, `ne`. SQL-style (`>=`, `!=`) rejected.
|
||||||
|
4. **Entity filter required for get-all:** At least one of `user_id`, `agent_id`, `app_id`, or `run_id`.
|
||||||
|
5. **Wildcard excludes null:** `*` matches only non-null values.
|
||||||
|
6. **Date format:** ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). Timezone-naive defaults to UTC.
|
||||||
|
|
||||||
|
## Response Formats
|
||||||
|
|
||||||
|
### Add Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
|
||||||
|
"event": "ADD",
|
||||||
|
"data": { "memory": "The user moved to Austin in 2025." }
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Event types: `ADD`, `UPDATE`, `DELETE`. A single add can trigger multiple events.
|
||||||
|
|
||||||
|
### Search Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"results": [
|
||||||
|
{
|
||||||
|
"id": "ea925981-...",
|
||||||
|
"memory": "Is a vegetarian and allergic to nuts.",
|
||||||
|
"user_id": "user123",
|
||||||
|
"categories": ["food", "health"],
|
||||||
|
"score": 0.89,
|
||||||
|
"created_at": "2024-07-26T10:29:36.630547-07:00"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
With `enable_graph=true`, includes additional `relations` array with entity relationships.
|
||||||
@@ -0,0 +1,386 @@
|
|||||||
|
# Mem0 Platform Architecture
|
||||||
|
|
||||||
|
How Mem0 processes, stores, and retrieves memories under the hood.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Core Concept](#core-concept)
|
||||||
|
- [Memory Processing Pipeline](#memory-processing-pipeline)
|
||||||
|
- [Retrieval Pipeline](#retrieval-pipeline)
|
||||||
|
- [Memory Lifecycle](#memory-lifecycle)
|
||||||
|
- [Memory Object Structure](#memory-object-structure)
|
||||||
|
- [Scoping & Multi-Tenancy](#scoping--multi-tenancy)
|
||||||
|
- [Memory Layers](#memory-layers)
|
||||||
|
- [Performance Characteristics](#performance-characteristics)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Concept
|
||||||
|
|
||||||
|
Mem0 is a managed memory layer that sits between your AI application and users. Every integration follows the same 3-step loop:
|
||||||
|
|
||||||
|
```
|
||||||
|
User Input → Retrieve relevant memories → Enrich LLM prompt → Generate response → Store new memories
|
||||||
|
```
|
||||||
|
|
||||||
|
Mem0 handles the complexity of extraction, deduplication, conflict resolution, and semantic retrieval so your application only needs to call `search()` and `add()`.
|
||||||
|
|
||||||
|
**Dual storage architecture:**
|
||||||
|
- **Vector store**: Embeddings for semantic similarity search
|
||||||
|
- **Graph store** (optional): Entity nodes and relationship edges for structured knowledge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory Processing Pipeline
|
||||||
|
|
||||||
|
### What happens when you call `client.add()`
|
||||||
|
|
||||||
|
```
|
||||||
|
Messages In
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 1. EXTRACTION │ LLM analyzes messages, extracts key facts
|
||||||
|
│ (infer=True) │ If infer=False, stores raw text as-is
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 2. CONFLICT │ Checks existing memories for duplicates
|
||||||
|
│ RESOLUTION │ Latest truth wins (newer overrides older)
|
||||||
|
│ │ Only runs when infer=True
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 3. STORAGE │ Generates embeddings → vector store
|
||||||
|
│ │ Optional: entity extraction → graph store
|
||||||
|
│ │ Indexes metadata, categories, timestamps
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Memory Object
|
||||||
|
(id, memory, categories, structured_attributes)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Processing modes
|
||||||
|
|
||||||
|
**Async (default, `async_mode=True`):**
|
||||||
|
- API returns immediately: `{"status": "PENDING", "event_id": "..."}`
|
||||||
|
- Processing happens in background
|
||||||
|
- Use webhooks for completion notifications
|
||||||
|
- Best for: high-throughput, non-blocking workflows
|
||||||
|
|
||||||
|
**Sync (`async_mode=False`):**
|
||||||
|
- API waits for full processing
|
||||||
|
- Returns complete memory object with `id`, `event`, `memory`
|
||||||
|
- Best for: real-time access immediately after add
|
||||||
|
|
||||||
|
### Extraction modes
|
||||||
|
|
||||||
|
**Inferred (`infer=True`, default):**
|
||||||
|
- LLM extracts structured facts from conversation
|
||||||
|
- Conflict resolution deduplicates and resolves contradictions
|
||||||
|
- Best for: natural conversation → memory
|
||||||
|
|
||||||
|
**Raw (`infer=False`):**
|
||||||
|
- Stores text exactly as provided, no LLM processing
|
||||||
|
- Skips conflict resolution — same fact can be stored twice
|
||||||
|
- Only `user` role messages are stored; `assistant` messages ignored
|
||||||
|
- Best for: bulk imports, pre-structured data, migrations
|
||||||
|
|
||||||
|
**Warning:** Don't mix `infer=True` and `infer=False` for the same data — the same fact will be stored twice.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Retrieval Pipeline
|
||||||
|
|
||||||
|
### What happens when you call `client.search()`
|
||||||
|
|
||||||
|
```
|
||||||
|
Query In
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 1. QUERY EMBEDDING │ Convert query to vector representation
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 2. VECTOR SEARCH │ Cosine similarity across stored embeddings
|
||||||
|
│ │ Scoped by filters (user_id, agent_id, etc.)
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼ (optional enhancements)
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 3a. KEYWORD SEARCH │ Expands results with specific terms (+10ms)
|
||||||
|
│ 3b. RERANKING │ Deep semantic reordering (+150-200ms)
|
||||||
|
│ 3c. FILTER MEMORIES │ Precision filtering, removes low-relevance (+200-300ms)
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼ (if enable_graph=True)
|
||||||
|
┌─────────────────────┐
|
||||||
|
│ 4. GRAPH LOOKUP │ Finds entity relationships
|
||||||
|
│ │ Appends relations WITHOUT reranking vector results
|
||||||
|
└─────────┬───────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
Results + Relations
|
||||||
|
```
|
||||||
|
|
||||||
|
### Retrieval enhancement combinations
|
||||||
|
|
||||||
|
| Configuration | Latency | Best for |
|
||||||
|
|--------------|---------|----------|
|
||||||
|
| Base search only | ~100ms | Simple lookups |
|
||||||
|
| `keyword_search=True` | ~110ms | Entity-heavy queries, broad coverage |
|
||||||
|
| `rerank=True` | ~250-300ms | User-facing results, top-N precision |
|
||||||
|
| `keyword_search=True` + `rerank=True` | ~310ms | Balanced (recommended for most apps) |
|
||||||
|
| `rerank=True` + `filter_memories=True` | ~400-500ms | Safety-critical, production systems |
|
||||||
|
|
||||||
|
### Implicit null scoping
|
||||||
|
|
||||||
|
When you search with `user_id="alice"` only, Mem0 returns memories where `agent_id`, `app_id`, and `run_id` are all null. This prevents cross-scope leakage by default.
|
||||||
|
|
||||||
|
To include memories with non-null fields, use explicit filters:
|
||||||
|
```python
|
||||||
|
# Gets memories for alice regardless of agent/app/run
|
||||||
|
filters={"OR": [{"user_id": "alice"}]}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
CREATE ──→ ACTIVE ──→ UPDATE ──→ ACTIVE
|
||||||
|
│ │ │
|
||||||
|
│ ▼ ▼
|
||||||
|
│ EXPIRED EXPIRED
|
||||||
|
│ (still stored, (still stored,
|
||||||
|
│ not retrieved) not retrieved)
|
||||||
|
│ │ │
|
||||||
|
▼ ▼ ▼
|
||||||
|
DELETE DELETE DELETE
|
||||||
|
(permanent)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Creation
|
||||||
|
- Triggered by `client.add(messages, user_id="...")`
|
||||||
|
- Messages processed through extraction → conflict resolution → storage
|
||||||
|
- Gets unique UUID, `created_at` timestamp
|
||||||
|
- Optional: custom `timestamp`, `expiration_date`, `metadata`, `immutable`
|
||||||
|
|
||||||
|
### Updates
|
||||||
|
- `client.update(memory_id, text="...")` replaces text and reindexes
|
||||||
|
- `client.batch_update([...])` for up to 1000 memories at once
|
||||||
|
- Immutable memories (`immutable=True`) cannot be updated — must delete and re-add
|
||||||
|
|
||||||
|
### Deduplication
|
||||||
|
- Automatic during `add()` with `infer=True`
|
||||||
|
- Conflict resolution merges duplicate facts
|
||||||
|
- Latest truth wins when contradictions detected
|
||||||
|
- Prevents memory bloat from repeated information
|
||||||
|
|
||||||
|
### Expiration
|
||||||
|
- Optional `expiration_date` parameter (ISO 8601 or `YYYY-MM-DD`)
|
||||||
|
- After expiration: memory NOT returned in searches but remains in storage
|
||||||
|
- Useful for time-sensitive info (events, temporary preferences, session state)
|
||||||
|
|
||||||
|
### Deletion
|
||||||
|
- Single: `client.delete(memory_id)` — permanent, no recovery
|
||||||
|
- Batch: `client.batch_delete([memory_ids])` — up to 1000
|
||||||
|
- Bulk: `client.delete_all(user_id="alice")` — all memories for entity
|
||||||
|
- `delete_all()` without filters raises error to prevent accidental data loss
|
||||||
|
|
||||||
|
### History tracking
|
||||||
|
- `client.history(memory_id)` returns version timeline
|
||||||
|
- Shows all changes: `{previous_value, new_value, action, timestamps}`
|
||||||
|
- Useful for audit trails and debugging
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory Object Structure
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "uuid-string",
|
||||||
|
"memory": "Extracted memory text",
|
||||||
|
"user_id": "user-identifier",
|
||||||
|
"agent_id": null,
|
||||||
|
"app_id": null,
|
||||||
|
"run_id": null,
|
||||||
|
"metadata": { "source": "chat", "priority": "high" },
|
||||||
|
"categories": ["health", "preferences"],
|
||||||
|
"created_at": "2025-03-12T12:34:56Z",
|
||||||
|
"updated_at": "2025-03-12T12:34:56Z",
|
||||||
|
"expiration_date": null,
|
||||||
|
"immutable": false,
|
||||||
|
"structured_attributes": {
|
||||||
|
"day": 12, "month": 3, "year": 2025,
|
||||||
|
"hour": 12, "minute": 34,
|
||||||
|
"day_of_week": "wednesday",
|
||||||
|
"is_weekend": false,
|
||||||
|
"quarter": 1, "week_of_year": 11
|
||||||
|
},
|
||||||
|
"score": 0.85
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `id` | UUID | Unique identifier, used for update/delete |
|
||||||
|
| `memory` | string | Extracted or stored text content |
|
||||||
|
| `user_id` | string | Primary entity scope |
|
||||||
|
| `agent_id` | string | Agent scope |
|
||||||
|
| `app_id` | string | Application scope |
|
||||||
|
| `run_id` | string | Session/run scope |
|
||||||
|
| `metadata` | object | Custom key-value pairs for filtering |
|
||||||
|
| `categories` | array | Auto-assigned or custom category tags |
|
||||||
|
| `created_at` | datetime | Creation timestamp |
|
||||||
|
| `updated_at` | datetime | Last modification timestamp |
|
||||||
|
| `expiration_date` | datetime | Auto-expiry date (stops retrieval, data persists) |
|
||||||
|
| `immutable` | boolean | If true, prevents modification |
|
||||||
|
| `structured_attributes` | object | Temporal breakdown for time-based queries |
|
||||||
|
| `score` | float | Semantic similarity (search results only, 0-1) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scoping & Multi-Tenancy
|
||||||
|
|
||||||
|
Mem0 separates memories across four dimensions to prevent data mixing:
|
||||||
|
|
||||||
|
| Dimension | Field | Purpose | Example |
|
||||||
|
|-----------|-------|---------|---------|
|
||||||
|
| User | `user_id` | Persistent persona or account | `"customer_6412"` |
|
||||||
|
| Agent | `agent_id` | Distinct agent or tool | `"meal_planner"` |
|
||||||
|
| App | `app_id` | Product surface or deployment | `"ios_retail_app"` |
|
||||||
|
| Session | `run_id` | Short-lived flow or thread | `"ticket-9241"` |
|
||||||
|
|
||||||
|
### Storage model
|
||||||
|
|
||||||
|
Each entity combination creates separate records. A memory with `user_id="alice"` is stored separately from one with `user_id="alice"` + `agent_id="bot"`.
|
||||||
|
|
||||||
|
### Critical: cross-entity queries
|
||||||
|
|
||||||
|
```python
|
||||||
|
# This returns NOTHING — user and agent memories are stored separately
|
||||||
|
filters={"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]}
|
||||||
|
|
||||||
|
# Use OR to query multiple scopes
|
||||||
|
filters={"OR": [{"user_id": "alice"}, {"agent_id": "bot"}]}
|
||||||
|
|
||||||
|
# Use wildcard to include any non-null value
|
||||||
|
filters={"AND": [{"user_id": "*"}]} # All users (excludes null)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recommended scoping patterns
|
||||||
|
|
||||||
|
```python
|
||||||
|
# User-level: persistent preferences
|
||||||
|
client.add(messages, user_id="alice")
|
||||||
|
|
||||||
|
# Session-level: temporary context
|
||||||
|
client.add(messages, user_id="alice", run_id="session_123")
|
||||||
|
# Clean up when done: client.delete_all(run_id="session_123")
|
||||||
|
|
||||||
|
# Agent-level: agent-specific knowledge
|
||||||
|
client.add(messages, agent_id="support_bot", app_id="helpdesk")
|
||||||
|
|
||||||
|
# Multi-tenant: full isolation
|
||||||
|
client.add(messages, user_id="alice", agent_id="bot", app_id="acme_corp", run_id="ticket_42")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory Layers
|
||||||
|
|
||||||
|
Mem0 supports three layers of memory, from shortest to longest lived:
|
||||||
|
|
||||||
|
### Conversation memory
|
||||||
|
- In-flight messages within a single turn
|
||||||
|
- Tool calls, chain-of-thought reasoning
|
||||||
|
- **Lifetime:** Single response — lost after turn finishes
|
||||||
|
- **Managed by:** Your application, not Mem0
|
||||||
|
|
||||||
|
### Session memory
|
||||||
|
- Short-lived facts for current task or channel
|
||||||
|
- Multi-step flows (onboarding, debugging, support tickets)
|
||||||
|
- **Lifetime:** Minutes to hours
|
||||||
|
- **Managed by:** Mem0 via `run_id` parameter
|
||||||
|
- Clean up with `client.delete_all(run_id="session_id")`
|
||||||
|
|
||||||
|
### User memory
|
||||||
|
- Long-lived knowledge tied to a person or account
|
||||||
|
- Personal preferences, account state, compliance details
|
||||||
|
- **Lifetime:** Weeks to forever
|
||||||
|
- **Managed by:** Mem0 via `user_id` parameter
|
||||||
|
- Persists across all sessions and interactions
|
||||||
|
|
||||||
|
### How layering works in practice
|
||||||
|
|
||||||
|
```python
|
||||||
|
def chat(user_input: str, user_id: str, session_id: str) -> str:
|
||||||
|
# 1. Retrieve user memories (long-term preferences)
|
||||||
|
user_mems = mem0.search(user_input, user_id=user_id)
|
||||||
|
|
||||||
|
# 2. Retrieve session memories (current task context)
|
||||||
|
session_mems = mem0.search(user_input, filters={
|
||||||
|
"AND": [{"user_id": user_id}, {"run_id": session_id}]
|
||||||
|
})
|
||||||
|
|
||||||
|
# 3. Combine both layers for LLM context
|
||||||
|
context = format_memories(user_mems) + format_memories(session_mems)
|
||||||
|
|
||||||
|
# 4. Generate response
|
||||||
|
response = llm.generate(context=context, input=user_input)
|
||||||
|
|
||||||
|
# 5. Store in session scope (temporary) + user scope (persistent)
|
||||||
|
messages = [{"role": "user", "content": user_input}, {"role": "assistant", "content": response}]
|
||||||
|
mem0.add(messages, user_id=user_id, run_id=session_id)
|
||||||
|
|
||||||
|
return response
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance Characteristics
|
||||||
|
|
||||||
|
### Latency
|
||||||
|
|
||||||
|
| Operation | Typical Latency |
|
||||||
|
|-----------|----------------|
|
||||||
|
| Base vector search | ~100ms |
|
||||||
|
| + keyword_search | +10ms |
|
||||||
|
| + reranking | +150-200ms |
|
||||||
|
| + filter_memories | +200-300ms |
|
||||||
|
| Add (async, default) | < 50ms response, background processing |
|
||||||
|
| Add (sync) | 500ms-2s depending on extraction complexity |
|
||||||
|
| Graph operations | Slight overhead for large stores |
|
||||||
|
|
||||||
|
### Processing
|
||||||
|
|
||||||
|
- **Async mode (default):** Returns immediately, processes in background
|
||||||
|
- **Sync mode:** Waits for full extraction + storage pipeline
|
||||||
|
- **Batch operations:** Up to 1000 memories per batch_update/batch_delete
|
||||||
|
- **Webhooks:** Real-time notifications when async processing completes
|
||||||
|
|
||||||
|
### Scoping strategy for performance
|
||||||
|
|
||||||
|
- Use `user_id` for all user-facing queries (most common, fastest)
|
||||||
|
- Add `run_id` for session isolation (narrows search space)
|
||||||
|
- Avoid wildcard `"*"` filters on large datasets (scans all non-null records)
|
||||||
|
- Use `top_k` to limit result count when you only need a few memories
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Comparison with Alternatives
|
||||||
|
|
||||||
|
| Approach | Pros | Cons |
|
||||||
|
|----------|------|------|
|
||||||
|
| **Raw vector DB** | Fast, full control | No extraction, no dedup, no conflict resolution |
|
||||||
|
| **In-memory chat history** | Zero latency | Lost on restart, no cross-session, grows unbounded |
|
||||||
|
| **RAG over documents** | Good for static knowledge | No personalization, no memory updates |
|
||||||
|
| **Mem0 Platform** | Managed extraction + dedup + graph + scoping | External dependency, async processing delay |
|
||||||
|
|
||||||
|
Mem0 combines the best of vector search (semantic retrieval) with automatic extraction (LLM-powered), conflict resolution (deduplication), and structured scoping (multi-tenancy) — in a single managed API.
|
||||||
@@ -0,0 +1,496 @@
|
|||||||
|
# Platform Features -- Mem0 Platform
|
||||||
|
|
||||||
|
Additional platform capabilities beyond core CRUD operations.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Advanced Retrieval](#advanced-retrieval)
|
||||||
|
- [Graph Memory](#graph-memory)
|
||||||
|
- [Custom Categories](#custom-categories)
|
||||||
|
- [Custom Instructions](#custom-instructions)
|
||||||
|
- [Criteria Retrieval](#criteria-retrieval)
|
||||||
|
- [Feedback Mechanism](#feedback-mechanism)
|
||||||
|
- [Memory Export](#memory-export)
|
||||||
|
- [Group Chat](#group-chat)
|
||||||
|
- [MCP Integration](#mcp-integration)
|
||||||
|
- [Webhooks](#webhooks)
|
||||||
|
- [Multimodal Support](#multimodal-support)
|
||||||
|
|
||||||
|
## Advanced Retrieval
|
||||||
|
|
||||||
|
Three enhancement options for tuning search precision, recall, and latency.
|
||||||
|
|
||||||
|
### Keyword Search (`keyword_search=True`)
|
||||||
|
|
||||||
|
Expands results to include memories with specific terms, names, and technical keywords.
|
||||||
|
|
||||||
|
- Latency: +10ms
|
||||||
|
- Recall: Significantly increased
|
||||||
|
- Best for: entity-heavy queries, comprehensive coverage
|
||||||
|
|
||||||
|
### Reranking (`rerank=True`)
|
||||||
|
|
||||||
|
Deep semantic reordering of results — most relevant first.
|
||||||
|
|
||||||
|
- Latency: +150-200ms
|
||||||
|
- Accuracy: Significantly improved
|
||||||
|
- Best for: user-facing results, top-N precision
|
||||||
|
|
||||||
|
### Filter Memories (`filter_memories=True`)
|
||||||
|
|
||||||
|
Precision filtering — removes low-relevance results entirely.
|
||||||
|
|
||||||
|
- Latency: +200-300ms
|
||||||
|
- Precision: Maximized
|
||||||
|
- Best for: safety-critical applications, production systems
|
||||||
|
|
||||||
|
### Recommended Combinations
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
# Fast & broad
|
||||||
|
results = client.search(query, keyword_search=True, user_id="user123")
|
||||||
|
|
||||||
|
# Balanced (recommended for most apps)
|
||||||
|
results = client.search(query, keyword_search=True, rerank=True, user_id="user123")
|
||||||
|
|
||||||
|
# High precision (critical apps)
|
||||||
|
results = client.search(query, rerank=True, filter_memories=True, user_id="user123")
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
const results = await client.search(query, {
|
||||||
|
user_id: 'user123',
|
||||||
|
keyword_search: true,
|
||||||
|
rerank: true,
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Graph Memory
|
||||||
|
|
||||||
|
Entity-level knowledge graph that creates relationships between memories.
|
||||||
|
|
||||||
|
### How It Works
|
||||||
|
|
||||||
|
1. **Extraction**: LLM analyzes conversation and identifies entities and relationships
|
||||||
|
2. **Storage**: Embeddings go to vector store; entity nodes and edges go to graph store
|
||||||
|
3. **Retrieval**: Vector search returns semantic matches; graph relations are appended to results
|
||||||
|
|
||||||
|
Graph relations **augment** vector results without reordering them. Vector similarity always determines hit sequence.
|
||||||
|
|
||||||
|
### Enabling Graph Memory
|
||||||
|
|
||||||
|
**Per request:**
|
||||||
|
```python
|
||||||
|
client.add(messages, user_id="alice", enable_graph=True)
|
||||||
|
client.search("query", user_id="alice", enable_graph=True)
|
||||||
|
client.get_all(filters={"AND": [{"user_id": "alice"}]}, enable_graph=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Project-level (default for all operations):**
|
||||||
|
```python
|
||||||
|
client.project.update(enable_graph=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
await client.updateProject({ enable_graph: true });
|
||||||
|
```
|
||||||
|
|
||||||
|
### Relation Structure
|
||||||
|
|
||||||
|
Each relation in the response contains:
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| `source` | string | Source entity name |
|
||||||
|
| `source_type` | string | Source entity type (e.g., "Person") |
|
||||||
|
| `relationship` | string | Relationship label (e.g., "lives_in") |
|
||||||
|
| `target` | string | Target entity name |
|
||||||
|
| `target_type` | string | Target entity type (e.g., "City") |
|
||||||
|
| `score` | number | Confidence score |
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"relations": [
|
||||||
|
{
|
||||||
|
"source": "Joseph",
|
||||||
|
"source_type": "Person",
|
||||||
|
"relationship": "lives_in",
|
||||||
|
"target": "Seattle",
|
||||||
|
"target_type": "City",
|
||||||
|
"score": 0.92
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Technical Notes
|
||||||
|
|
||||||
|
- Graph Memory adds processing time; see docs for current plan availability
|
||||||
|
- Works optimally with rich conversation histories containing entity relationships
|
||||||
|
- Best suited for long-running assistants tracking evolving information
|
||||||
|
- Graph writes and reads toggle independently per request
|
||||||
|
- Multi-agent context supported via `user_id`, `agent_id`, `run_id` scoping
|
||||||
|
- Add operations are asynchronous; graph metadata may not be immediately available
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 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:**
|
||||||
|
```python
|
||||||
|
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)
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
await client.updateProject({ custom_categories: new_categories });
|
||||||
|
```
|
||||||
|
|
||||||
|
**Retrieve active categories:**
|
||||||
|
```python
|
||||||
|
categories = client.project.get(fields=["custom_categories"])
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Constraint
|
||||||
|
|
||||||
|
Per-request overrides (`custom_categories=...` on `client.add`) are **not supported** on the managed API. Only project-level configuration works. Workaround: store ad-hoc labels in `metadata` field.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Custom Instructions
|
||||||
|
|
||||||
|
Natural language filters that control what information Mem0 extracts when creating memories.
|
||||||
|
|
||||||
|
### Set Instructions
|
||||||
|
|
||||||
|
```python
|
||||||
|
client.project.update(custom_instructions="Your guidelines here...")
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
await client.updateProject({ custom_instructions: "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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Criteria Retrieval
|
||||||
|
|
||||||
|
Custom attribute-based memory ranking using LLM-evaluated criteria with weights. Goes beyond semantic similarity to prioritize memories based on domain-specific signals.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Define criteria at project level
|
||||||
|
retrieval_criteria = [
|
||||||
|
{"name": "joy", "description": "Positive emotions like happiness and excitement", "weight": 3},
|
||||||
|
{"name": "curiosity", "description": "Inquisitiveness and desire to learn", "weight": 2},
|
||||||
|
{"name": "urgency", "description": "Time-sensitive or high-priority items", "weight": 4},
|
||||||
|
]
|
||||||
|
client.project.update(retrieval_criteria=retrieval_criteria)
|
||||||
|
```
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
await client.updateProject({
|
||||||
|
retrieval_criteria: [
|
||||||
|
{ name: 'joy', description: 'Positive emotions', weight: 3 },
|
||||||
|
{ name: 'urgency', description: 'Time-sensitive items', weight: 4 },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
Once configured, `client.search()` automatically applies criteria ranking:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Criteria-weighted results returned automatically
|
||||||
|
results = client.search("Why am I feeling happy?", filters={"user_id": "alice"})
|
||||||
|
```
|
||||||
|
|
||||||
|
**Best for:** Wellness assistants, tutoring platforms, productivity tools — any app needing intent-aware retrieval.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feedback Mechanism
|
||||||
|
|
||||||
|
Provide feedback on extracted memories to improve system quality over time.
|
||||||
|
|
||||||
|
### Feedback Types
|
||||||
|
|
||||||
|
| Type | Meaning |
|
||||||
|
|------|---------|
|
||||||
|
| `POSITIVE` | Memory is useful and accurate |
|
||||||
|
| `NEGATIVE` | Memory is not useful |
|
||||||
|
| `VERY_NEGATIVE` | Memory is harmful or completely wrong |
|
||||||
|
| `None` | Clear existing feedback |
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```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:**
|
||||||
|
```typescript
|
||||||
|
await client.feedback('mem-123', {
|
||||||
|
feedback: 'POSITIVE',
|
||||||
|
feedback_reason: 'Accurately captured dietary preference',
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory Export
|
||||||
|
|
||||||
|
Create structured exports of memories using customizable schemas with filters.
|
||||||
|
|
||||||
|
### Usage
|
||||||
|
|
||||||
|
```python
|
||||||
|
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
|
||||||
|
|
||||||
|
```python
|
||||||
|
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 Desktop, Cursor, custom agents) to manage Mem0 memory autonomously.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"mem0": {
|
||||||
|
"command": "uvx",
|
||||||
|
"args": ["mem0-mcp-server"],
|
||||||
|
"env": {
|
||||||
|
"MEM0_API_KEY": "m0-your-api-key",
|
||||||
|
"MEM0_DEFAULT_USER_ID": "your-user-id"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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. Configure the MCP server in your AI client
|
||||||
|
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
|
||||||
|
|
||||||
|
| Event | Trigger |
|
||||||
|
|-------|---------|
|
||||||
|
| `memory_add` | Memory created |
|
||||||
|
| `memory_update` | Memory modified |
|
||||||
|
| `memory_delete` | Memory removed |
|
||||||
|
| `memory_categorize` | Memory tagged |
|
||||||
|
|
||||||
|
### Create Webhook
|
||||||
|
|
||||||
|
Note: `project_id` here refers to the Mem0 dashboard project scope for webhooks — not the deprecated client init parameter.
|
||||||
|
|
||||||
|
```python
|
||||||
|
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
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```python
|
||||||
|
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
|
||||||
|
|
||||||
|
```python
|
||||||
|
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)
|
||||||
|
|
||||||
|
```python
|
||||||
|
doc_message = {
|
||||||
|
"role": "user",
|
||||||
|
"content": {"type": "mdx_url", "mdx_url": {"url": document_url}}
|
||||||
|
}
|
||||||
|
client.add([doc_message], user_id="alice")
|
||||||
|
```
|
||||||
|
|
||||||
|
### PDF Document
|
||||||
|
|
||||||
|
```python
|
||||||
|
pdf_message = {
|
||||||
|
"role": "user",
|
||||||
|
"content": {"type": "pdf_url", "pdf_url": {"url": pdf_url}}
|
||||||
|
}
|
||||||
|
client.add([pdf_message], user_id="alice")
|
||||||
|
```
|
||||||
@@ -0,0 +1,444 @@
|
|||||||
|
# Mem0 Integration Patterns
|
||||||
|
|
||||||
|
Working code examples for integrating Mem0 Platform with popular AI frameworks.
|
||||||
|
All examples use `MemoryClient` (Platform API key).
|
||||||
|
|
||||||
|
Code examples are sourced from official Mem0 integration docs at docs.mem0.ai, simplified for quick reference.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Pattern
|
||||||
|
|
||||||
|
Every integration follows the same 3-step loop:
|
||||||
|
|
||||||
|
1. **Retrieve** -- search relevant memories before generating a response
|
||||||
|
2. **Generate** -- include memories as context in the LLM prompt
|
||||||
|
3. **Store** -- save the interaction back to Mem0 for future use
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## LangChain
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/langchain](https://docs.mem0.ai/integrations/langchain)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from langchain_openai import ChatOpenAI
|
||||||
|
from langchain_core.messages import SystemMessage, HumanMessage
|
||||||
|
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
llm = ChatOpenAI(model="gpt-4.1-nano-2025-04-14")
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
|
||||||
|
prompt = ChatPromptTemplate.from_messages([
|
||||||
|
SystemMessage(content="You are a helpful travel agent AI. Use the provided context to personalize your responses."),
|
||||||
|
MessagesPlaceholder(variable_name="context"),
|
||||||
|
HumanMessage(content="{input}")
|
||||||
|
])
|
||||||
|
|
||||||
|
def retrieve_context(query: str, user_id: str):
|
||||||
|
"""Retrieve relevant memories from Mem0"""
|
||||||
|
memories = mem0.search(query, user_id=user_id)
|
||||||
|
memory_list = memories['results']
|
||||||
|
serialized = ' '.join([m["memory"] for m in memory_list])
|
||||||
|
return [
|
||||||
|
{"role": "system", "content": f"Relevant information: {serialized}"},
|
||||||
|
{"role": "user", "content": query}
|
||||||
|
]
|
||||||
|
|
||||||
|
def chat_turn(user_input: str, user_id: str) -> str:
|
||||||
|
# 1. Retrieve
|
||||||
|
context = retrieve_context(user_input, user_id)
|
||||||
|
# 2. Generate
|
||||||
|
chain = prompt | llm
|
||||||
|
response = chain.invoke({"context": context, "input": user_input})
|
||||||
|
# 3. Store
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": user_input}, {"role": "assistant", "content": response.content}],
|
||||||
|
user_id=user_id
|
||||||
|
)
|
||||||
|
return response.content
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CrewAI
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/crewai](https://docs.mem0.ai/integrations/crewai)
|
||||||
|
|
||||||
|
CrewAI has native Mem0 integration via `memory_config`:
|
||||||
|
|
||||||
|
```python
|
||||||
|
from crewai import Agent, Task, Crew, Process
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
client = MemoryClient()
|
||||||
|
|
||||||
|
# Store user preferences first
|
||||||
|
messages = [
|
||||||
|
{"role": "user", "content": "I am more of a beach person than a mountain person."},
|
||||||
|
{"role": "assistant", "content": "Noted! I'll recommend beach destinations."},
|
||||||
|
{"role": "user", "content": "I like Airbnb more than hotels."},
|
||||||
|
]
|
||||||
|
client.add(messages, user_id="crew_user_1")
|
||||||
|
|
||||||
|
# Create agent
|
||||||
|
travel_agent = Agent(
|
||||||
|
role="Personalized Travel Planner",
|
||||||
|
goal="Plan personalized travel itineraries",
|
||||||
|
backstory="You are a seasoned travel planner.",
|
||||||
|
memory=True,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Create task
|
||||||
|
task = Task(
|
||||||
|
description="Find places to live, eat, and visit in San Francisco.",
|
||||||
|
expected_output="A detailed list of places to live, eat, and visit.",
|
||||||
|
agent=travel_agent,
|
||||||
|
)
|
||||||
|
|
||||||
|
# Setup crew with Mem0 memory
|
||||||
|
crew = Crew(
|
||||||
|
agents=[travel_agent],
|
||||||
|
tasks=[task],
|
||||||
|
process=Process.sequential,
|
||||||
|
memory=True,
|
||||||
|
memory_config={
|
||||||
|
"provider": "mem0",
|
||||||
|
"config": {"user_id": "crew_user_1"},
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
result = crew.kickoff()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Vercel AI SDK
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/vercel-ai-sdk](https://docs.mem0.ai/integrations/vercel-ai-sdk)
|
||||||
|
|
||||||
|
Install: `npm install @mem0/vercel-ai-provider`
|
||||||
|
|
||||||
|
### Basic Text Generation with Memory
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { generateText } from "ai";
|
||||||
|
import { createMem0 } from "@mem0/vercel-ai-provider";
|
||||||
|
|
||||||
|
const mem0 = createMem0({
|
||||||
|
provider: "openai",
|
||||||
|
mem0ApiKey: "m0-xxx",
|
||||||
|
apiKey: "openai-api-key",
|
||||||
|
});
|
||||||
|
|
||||||
|
const { text } = await generateText({
|
||||||
|
model: mem0("gpt-4-turbo", { user_id: "borat" }),
|
||||||
|
prompt: "Suggest me a good car to buy!",
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Streaming with Memory
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { streamText } from "ai";
|
||||||
|
import { createMem0 } from "@mem0/vercel-ai-provider";
|
||||||
|
|
||||||
|
const mem0 = createMem0();
|
||||||
|
|
||||||
|
const { textStream } = streamText({
|
||||||
|
model: mem0("gpt-4-turbo", { user_id: "borat" }),
|
||||||
|
prompt: "Suggest me a good car to buy!",
|
||||||
|
});
|
||||||
|
|
||||||
|
for await (const textPart of textStream) {
|
||||||
|
process.stdout.write(textPart);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using Memory Utilities Standalone
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { openai } from "@ai-sdk/openai";
|
||||||
|
import { generateText } from "ai";
|
||||||
|
import { retrieveMemories, addMemories } from "@mem0/vercel-ai-provider";
|
||||||
|
|
||||||
|
// Retrieve memories and inject into any provider
|
||||||
|
const prompt = "Suggest me a good car to buy.";
|
||||||
|
const memories = await retrieveMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
|
||||||
|
|
||||||
|
const { text } = await generateText({
|
||||||
|
model: openai("gpt-4-turbo"),
|
||||||
|
prompt: prompt,
|
||||||
|
system: memories,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Store new memories
|
||||||
|
await addMemories(
|
||||||
|
[{ role: "user", content: [{ type: "text", text: "I love red cars." }] }],
|
||||||
|
{ user_id: "borat", mem0ApiKey: "m0-xxx" }
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Supported Providers
|
||||||
|
|
||||||
|
`openai`, `anthropic`, `google`, `groq`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## OpenAI Agents SDK
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/openai-agents-sdk](https://docs.mem0.ai/integrations/openai-agents-sdk)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from agents import Agent, Runner, function_tool
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
|
||||||
|
@function_tool
|
||||||
|
def search_memory(query: str, user_id: str) -> str:
|
||||||
|
"""Search through past conversations and memories"""
|
||||||
|
memories = mem0.search(query, user_id=user_id, top_k=3)
|
||||||
|
if memories and memories.get('results'):
|
||||||
|
return "\n".join([f"- {mem['memory']}" for mem in memories['results']])
|
||||||
|
return "No relevant memories found."
|
||||||
|
|
||||||
|
@function_tool
|
||||||
|
def save_memory(content: str, user_id: str) -> str:
|
||||||
|
"""Save important information to memory"""
|
||||||
|
mem0.add([{"role": "user", "content": content}], user_id=user_id)
|
||||||
|
return "Information saved to memory."
|
||||||
|
|
||||||
|
agent = Agent(
|
||||||
|
name="Personal Assistant",
|
||||||
|
instructions="""You are a helpful personal assistant with memory capabilities.
|
||||||
|
Use search_memory to recall past conversations.
|
||||||
|
Use save_memory to store important information.""",
|
||||||
|
tools=[search_memory, save_memory],
|
||||||
|
model="gpt-4.1-nano-2025-04-14"
|
||||||
|
)
|
||||||
|
|
||||||
|
result = Runner.run_sync(agent, "I love Italian food and I'm planning a trip to Rome next month")
|
||||||
|
print(result.final_output)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multi-Agent with Handoffs
|
||||||
|
|
||||||
|
```python
|
||||||
|
from agents import Agent, Runner, function_tool
|
||||||
|
|
||||||
|
travel_agent = Agent(
|
||||||
|
name="Travel Planner",
|
||||||
|
instructions="You are a travel planning specialist. Use search_memory and save_memory tools.",
|
||||||
|
tools=[search_memory, save_memory],
|
||||||
|
model="gpt-4.1-nano-2025-04-14"
|
||||||
|
)
|
||||||
|
|
||||||
|
health_agent = Agent(
|
||||||
|
name="Health Advisor",
|
||||||
|
instructions="You are a health and wellness advisor. Use search_memory and save_memory tools.",
|
||||||
|
tools=[search_memory, save_memory],
|
||||||
|
model="gpt-4.1-nano-2025-04-14"
|
||||||
|
)
|
||||||
|
|
||||||
|
triage_agent = Agent(
|
||||||
|
name="Personal Assistant",
|
||||||
|
instructions="""Route travel questions to Travel Planner, health questions to Health Advisor.""",
|
||||||
|
handoffs=[travel_agent, health_agent],
|
||||||
|
model="gpt-4.1-nano-2025-04-14"
|
||||||
|
)
|
||||||
|
|
||||||
|
result = Runner.run_sync(triage_agent, "Plan a healthy meal for my Italy trip")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pipecat (Voice / Real-Time)
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/pipecat](https://docs.mem0.ai/integrations/pipecat)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from pipecat.services.mem0 import Mem0MemoryService
|
||||||
|
|
||||||
|
memory = Mem0MemoryService(
|
||||||
|
api_key=os.getenv("MEM0_API_KEY"),
|
||||||
|
user_id="alice",
|
||||||
|
agent_id="voice_bot",
|
||||||
|
params={
|
||||||
|
"search_limit": 10,
|
||||||
|
"search_threshold": 0.1,
|
||||||
|
"system_prompt": "Here are your past memories:",
|
||||||
|
"add_as_system_message": True,
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
# Use in pipeline
|
||||||
|
pipeline = Pipeline([
|
||||||
|
transport.input(),
|
||||||
|
stt,
|
||||||
|
user_context,
|
||||||
|
memory, # Memory enhances context automatically
|
||||||
|
llm,
|
||||||
|
transport.output(),
|
||||||
|
assistant_context
|
||||||
|
])
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## LangGraph
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/langgraph](https://docs.mem0.ai/integrations/langgraph)
|
||||||
|
|
||||||
|
State-based agent workflows with memory persistence. Best for complex conversation flows with branching logic.
|
||||||
|
|
||||||
|
```python
|
||||||
|
from typing import Annotated, TypedDict, List
|
||||||
|
from langgraph.graph import StateGraph, START
|
||||||
|
from langgraph.graph.message import add_messages
|
||||||
|
from langchain_openai import ChatOpenAI
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
|
||||||
|
|
||||||
|
llm = ChatOpenAI(model="gpt-4")
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
|
||||||
|
class State(TypedDict):
|
||||||
|
messages: Annotated[List[HumanMessage | AIMessage], add_messages]
|
||||||
|
mem0_user_id: str
|
||||||
|
|
||||||
|
def chatbot(state: State):
|
||||||
|
messages = state["messages"]
|
||||||
|
user_id = state["mem0_user_id"]
|
||||||
|
|
||||||
|
# Retrieve relevant memories
|
||||||
|
memories = mem0.search(messages[-1].content, user_id=user_id)
|
||||||
|
context = "Relevant context:\n"
|
||||||
|
for memory in memories["results"]:
|
||||||
|
context += f"- {memory['memory']}\n"
|
||||||
|
|
||||||
|
system_message = SystemMessage(content=f"""You are a helpful support assistant.
|
||||||
|
{context}""")
|
||||||
|
|
||||||
|
response = llm.invoke([system_message] + messages)
|
||||||
|
|
||||||
|
# Store the interaction
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": messages[-1].content},
|
||||||
|
{"role": "assistant", "content": response.content}],
|
||||||
|
user_id=user_id
|
||||||
|
)
|
||||||
|
return {"messages": [response]}
|
||||||
|
|
||||||
|
graph = StateGraph(State)
|
||||||
|
graph.add_node("chatbot", chatbot)
|
||||||
|
graph.add_edge(START, "chatbot")
|
||||||
|
app = graph.compile()
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
result = app.invoke({
|
||||||
|
"messages": [HumanMessage(content="I need help with my order")],
|
||||||
|
"mem0_user_id": "customer_123"
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## LlamaIndex
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/llama-index](https://docs.mem0.ai/integrations/llama-index)
|
||||||
|
|
||||||
|
Install: `pip install llama-index-core llama-index-memory-mem0`
|
||||||
|
|
||||||
|
LlamaIndex has native Mem0 support via `Mem0Memory`. Works with ReAct and FunctionCalling agents.
|
||||||
|
|
||||||
|
```python
|
||||||
|
from llama_index.memory.mem0 import Mem0Memory
|
||||||
|
|
||||||
|
context = {"user_id": "alice", "agent_id": "llama_agent_1"}
|
||||||
|
memory = Mem0Memory.from_client(
|
||||||
|
context=context,
|
||||||
|
search_msg_limit=4, # messages from chat history used for retrieval (default: 5)
|
||||||
|
)
|
||||||
|
|
||||||
|
# Use with LlamaIndex agent
|
||||||
|
from llama_index.core.agent import FunctionCallingAgent
|
||||||
|
from llama_index.llms.openai import OpenAI
|
||||||
|
|
||||||
|
llm = OpenAI(model="gpt-4")
|
||||||
|
agent = FunctionCallingAgent.from_tools(
|
||||||
|
tools=[],
|
||||||
|
llm=llm,
|
||||||
|
memory=memory,
|
||||||
|
verbose=True,
|
||||||
|
)
|
||||||
|
|
||||||
|
response = agent.chat("I prefer vegetarian restaurants")
|
||||||
|
# Memory automatically stores and retrieves context
|
||||||
|
response = agent.chat("What kind of food do I like?")
|
||||||
|
# Agent retrieves the vegetarian preference from Mem0
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## AutoGen
|
||||||
|
|
||||||
|
Source: [docs.mem0.ai/integrations/autogen](https://docs.mem0.ai/integrations/autogen)
|
||||||
|
|
||||||
|
Install: `pip install autogen mem0ai`
|
||||||
|
|
||||||
|
Multi-agent conversational systems with memory persistence.
|
||||||
|
|
||||||
|
```python
|
||||||
|
from autogen import ConversableAgent
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
memory_client = MemoryClient()
|
||||||
|
USER_ID = "alice"
|
||||||
|
|
||||||
|
agent = ConversableAgent(
|
||||||
|
"chatbot",
|
||||||
|
llm_config={"config_list": [{"model": "gpt-4", "api_key": os.environ["OPENAI_API_KEY"]}]},
|
||||||
|
code_execution_config=False,
|
||||||
|
human_input_mode="NEVER",
|
||||||
|
)
|
||||||
|
|
||||||
|
def get_context_aware_response(question: str) -> str:
|
||||||
|
# Retrieve memories for context
|
||||||
|
relevant_memories = memory_client.search(question, user_id=USER_ID)
|
||||||
|
context = "\n".join([m["memory"] for m in relevant_memories.get("results", [])])
|
||||||
|
|
||||||
|
prompt = f"""Answer considering previous interactions:
|
||||||
|
Previous context: {context}
|
||||||
|
Question: {question}"""
|
||||||
|
|
||||||
|
reply = agent.generate_reply(messages=[{"content": prompt, "role": "user"}])
|
||||||
|
|
||||||
|
# Store the new interaction
|
||||||
|
memory_client.add(
|
||||||
|
[{"role": "user", "content": question}, {"role": "assistant", "content": reply}],
|
||||||
|
user_id=USER_ID
|
||||||
|
)
|
||||||
|
return reply
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## All Supported Frameworks
|
||||||
|
|
||||||
|
Beyond the examples above, Mem0 integrates with:
|
||||||
|
|
||||||
|
| Framework | Type | Install |
|
||||||
|
|-----------|------|---------|
|
||||||
|
| [Mastra](https://docs.mem0.ai/integrations/mastra) | TS agent framework | `npm install @mastra/mem0` |
|
||||||
|
| [ElevenLabs](https://docs.mem0.ai/integrations/elevenlabs) | Voice AI | `pip install elevenlabs mem0ai` |
|
||||||
|
| [LiveKit](https://docs.mem0.ai/integrations/livekit) | Real-time voice/video | `pip install livekit-agents mem0ai` |
|
||||||
|
| [Camel AI](https://docs.mem0.ai/integrations/camel-ai) | Multi-agent framework | `pip install camel-ai[all] mem0ai` |
|
||||||
|
| [AWS Bedrock](https://docs.mem0.ai/integrations/aws-bedrock) | Cloud LLM provider | `pip install boto3 mem0ai` |
|
||||||
|
| [Dify](https://docs.mem0.ai/integrations/dify) | Low-code AI platform | Plugin-based |
|
||||||
|
| [Google AI ADK](https://docs.mem0.ai/integrations/google-ai-adk) | Google agent framework | `pip install google-adk mem0ai` |
|
||||||
|
|
||||||
|
For the general Python pattern (no framework), see the "Common integration pattern" in [SKILL.md](../SKILL.md).
|
||||||
@@ -0,0 +1,119 @@
|
|||||||
|
# Mem0 Platform Quickstart
|
||||||
|
|
||||||
|
Get running with Mem0 in 2 minutes. No infrastructure to deploy -- just an API key.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Python 3.10+ or Node.js 18+
|
||||||
|
- A Mem0 Platform API key ([Get one here](https://app.mem0.ai/dashboard/api-keys))
|
||||||
|
|
||||||
|
## Python Setup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install mem0ai
|
||||||
|
export MEM0_API_KEY="m0-your-api-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
client = MemoryClient(api_key="your-api-key")
|
||||||
|
|
||||||
|
# Add a memory
|
||||||
|
messages = [
|
||||||
|
{"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
|
||||||
|
{"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
|
||||||
|
]
|
||||||
|
client.add(messages, user_id="user123")
|
||||||
|
|
||||||
|
# Search memories
|
||||||
|
results = client.search("What are my dietary restrictions?", user_id="user123")
|
||||||
|
print(results)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Async Client
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import AsyncMemoryClient
|
||||||
|
|
||||||
|
client = AsyncMemoryClient(api_key="your-api-key")
|
||||||
|
|
||||||
|
await client.add(messages, user_id="user123")
|
||||||
|
results = await client.search("query", user_id="user123")
|
||||||
|
```
|
||||||
|
|
||||||
|
## TypeScript / JavaScript Setup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install mem0ai
|
||||||
|
export MEM0_API_KEY="m0-your-api-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
|
||||||
|
const client = new MemoryClient({ apiKey: 'your-api-key' });
|
||||||
|
|
||||||
|
// Add a memory
|
||||||
|
const messages = [
|
||||||
|
{"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
|
||||||
|
{"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
|
||||||
|
];
|
||||||
|
await client.add(messages, { user_id: "user123" });
|
||||||
|
|
||||||
|
// Search memories
|
||||||
|
const results = await client.search("What are my dietary restrictions?", {
|
||||||
|
user_id: "user123"
|
||||||
|
});
|
||||||
|
console.log(results);
|
||||||
|
```
|
||||||
|
|
||||||
|
## cURL
|
||||||
|
|
||||||
|
```bash
|
||||||
|
export MEM0_API_KEY="m0-your-api-key"
|
||||||
|
|
||||||
|
# Add memory
|
||||||
|
curl -X POST https://api.mem0.ai/v1/memories/ \
|
||||||
|
-H "Authorization: Token $MEM0_API_KEY" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"messages": [
|
||||||
|
{"role": "user", "content": "I am a vegetarian and allergic to nuts."},
|
||||||
|
{"role": "assistant", "content": "Got it! I will remember your dietary preferences."}
|
||||||
|
],
|
||||||
|
"user_id": "user123"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# Search memories
|
||||||
|
curl -X POST https://api.mem0.ai/v2/memories/search/ \
|
||||||
|
-H "Authorization: Token $MEM0_API_KEY" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"query": "What are my dietary restrictions?",
|
||||||
|
"filters": {"user_id": "user123"}
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Sample Response
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"results": [
|
||||||
|
{
|
||||||
|
"id": "14e1b28a-2014-40ad-ac42-69c9ef42193d",
|
||||||
|
"memory": "Allergic to nuts",
|
||||||
|
"user_id": "user123",
|
||||||
|
"categories": ["health"],
|
||||||
|
"created_at": "2025-10-22T04:40:22.864647-07:00",
|
||||||
|
"score": 0.30
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
- [SDK Guide](sdk-guide.md) -- all methods for Python and TypeScript
|
||||||
|
- [API Reference](api-reference.md) -- REST endpoints and memory object structure
|
||||||
|
- [Integration Patterns](integration-patterns.md) -- LangChain, CrewAI, Vercel AI, etc.
|
||||||
@@ -0,0 +1,308 @@
|
|||||||
|
# Mem0 SDK Guide
|
||||||
|
|
||||||
|
Complete SDK reference for Python and TypeScript. All methods use `MemoryClient` (Platform API).
|
||||||
|
|
||||||
|
## Initialization
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
client = MemoryClient(api_key="m0-your-api-key")
|
||||||
|
```
|
||||||
|
|
||||||
|
**Python (Async):**
|
||||||
|
```python
|
||||||
|
from mem0 import AsyncMemoryClient
|
||||||
|
client = AsyncMemoryClient(api_key="m0-your-api-key")
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
const client = new MemoryClient({ apiKey: 'm0-your-api-key' });
|
||||||
|
```
|
||||||
|
|
||||||
|
Constructor accepts `apiKey` (required) and `host` (optional, default: `https://api.mem0.ai`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## add() -- Store Memories
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
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")
|
||||||
|
|
||||||
|
# With metadata
|
||||||
|
client.add(messages, user_id="alice", metadata={"source": "onboarding"})
|
||||||
|
|
||||||
|
# With graph memory
|
||||||
|
client.add(messages, user_id="alice", enable_graph=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
await client.add(messages, { user_id: "alice" });
|
||||||
|
await client.add(messages, { user_id: "alice", metadata: { source: "onboarding" } });
|
||||||
|
await client.add(messages, { user_id: "alice", enable_graph: true });
|
||||||
|
```
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
| Name | Type | Description |
|
||||||
|
|------|------|-------------|
|
||||||
|
| `messages` | array | `[{"role": "user", "content": "..."}]` |
|
||||||
|
| `user_id` | string | User identifier (recommended) |
|
||||||
|
| `agent_id` | string | Agent identifier |
|
||||||
|
| `run_id` | string | Session identifier |
|
||||||
|
| `metadata` | object | Custom key-value pairs |
|
||||||
|
| `enable_graph` | boolean | Activate knowledge graph |
|
||||||
|
| `infer` | boolean | If `false`, store raw text without inference (default: `true`) |
|
||||||
|
| `immutable` | boolean | Prevents modification after creation |
|
||||||
|
| `expiration_date` | string | Auto-expiry date (`YYYY-MM-DD`) |
|
||||||
|
| `includes` | string | Preference filters for inclusion |
|
||||||
|
| `excludes` | string | Preference filters for exclusion |
|
||||||
|
| `async_mode` | boolean | Async processing (default: `true`). Set `false` to wait |
|
||||||
|
|
||||||
|
### Advanced Add Options
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Immutable -- cannot be modified or overwritten
|
||||||
|
client.add(messages, user_id="alice", immutable=True)
|
||||||
|
|
||||||
|
# Expiring memory
|
||||||
|
client.add(messages, user_id="alice", expiration_date="2025-12-31")
|
||||||
|
|
||||||
|
# Selective extraction
|
||||||
|
client.add(messages, user_id="alice", includes="dietary preferences", excludes="payment info")
|
||||||
|
|
||||||
|
# Agent + session scoping
|
||||||
|
client.add(messages, user_id="alice", agent_id="nutrition-agent", run_id="session-456")
|
||||||
|
|
||||||
|
# Synchronous processing (wait for completion)
|
||||||
|
client.add(messages, user_id="alice", async_mode=False)
|
||||||
|
|
||||||
|
# Raw text -- skip LLM inference
|
||||||
|
client.add(
|
||||||
|
[{"role": "user", "content": "User prefers dark mode."}],
|
||||||
|
user_id="alice",
|
||||||
|
infer=False,
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## search() -- Find Memories
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
results = client.search("dietary preferences?", user_id="alice")
|
||||||
|
|
||||||
|
# With filters and reranking
|
||||||
|
results = client.search(
|
||||||
|
query="work experience",
|
||||||
|
filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "professional_details"}}]},
|
||||||
|
top_k=5,
|
||||||
|
rerank=True,
|
||||||
|
threshold=0.5
|
||||||
|
)
|
||||||
|
|
||||||
|
# With graph relations
|
||||||
|
results = client.search("colleagues", user_id="alice", enable_graph=True)
|
||||||
|
|
||||||
|
# Keyword search
|
||||||
|
results = client.search("vegetarian", user_id="alice", keyword_search=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
const results = await client.search("dietary preferences", { user_id: "alice" });
|
||||||
|
const results = await client.search("work experience", {
|
||||||
|
filters: { AND: [{ user_id: "alice" }, { categories: { contains: "professional_details" } }] },
|
||||||
|
top_k: 5,
|
||||||
|
rerank: true,
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Parameters
|
||||||
|
|
||||||
|
| Name | Type | Description |
|
||||||
|
|------|------|-------------|
|
||||||
|
| `query` | string | Natural language search query |
|
||||||
|
| `user_id` | string | Filter by user |
|
||||||
|
| `filters` | object | V2 filter object (AND/OR operators) |
|
||||||
|
| `top_k` | number | Number of results (default: 10) |
|
||||||
|
| `rerank` | boolean | Enable reranking for better relevance |
|
||||||
|
| `threshold` | number | Minimum similarity score (default: 0.3) |
|
||||||
|
| `keyword_search` | boolean | Use keyword-based search |
|
||||||
|
| `enable_graph` | boolean | Include graph relations |
|
||||||
|
|
||||||
|
### Common Filter Patterns
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Single user (shorthand)
|
||||||
|
client.search("query", user_id="alice")
|
||||||
|
|
||||||
|
# OR across agents
|
||||||
|
filters={"OR": [{"user_id": "alice"}, {"agent_id": {"in": ["travel-agent", "sports-agent"]}}]}
|
||||||
|
|
||||||
|
# Category filtering (partial match)
|
||||||
|
filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "finance"}}]}
|
||||||
|
|
||||||
|
# Category filtering (exact match)
|
||||||
|
filters={"AND": [{"user_id": "alice"}, {"categories": {"in": ["personal_information"]}}]}
|
||||||
|
|
||||||
|
# Wildcard (match any non-null run)
|
||||||
|
filters={"AND": [{"user_id": "alice"}, {"run_id": "*"}]}
|
||||||
|
|
||||||
|
# Date range
|
||||||
|
filters={"AND": [
|
||||||
|
{"user_id": "alice"},
|
||||||
|
{"created_at": {"gte": "2024-01-01T00:00:00Z"}},
|
||||||
|
{"created_at": {"lt": "2024-02-01T00:00:00Z"}}
|
||||||
|
]}
|
||||||
|
|
||||||
|
# Exclude categories with NOT
|
||||||
|
filters={"AND": [{"user_id": "user_123"}, {"NOT": {"categories": {"in": ["spam", "test"]}}}]}
|
||||||
|
|
||||||
|
# Multi-dimensional query
|
||||||
|
filters={"AND": [
|
||||||
|
{"user_id": "user_123"},
|
||||||
|
{"keywords": {"icontains": "invoice"}},
|
||||||
|
{"categories": {"in": ["finance"]}},
|
||||||
|
{"created_at": {"gte": "2024-01-01T00:00:00Z"}}
|
||||||
|
]}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## get() / getAll() -- Retrieve Memories
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
# Single memory by ID
|
||||||
|
memory = client.get(memory_id="ea925981-...")
|
||||||
|
|
||||||
|
# All memories for a user
|
||||||
|
memories = client.get_all(filters={"AND": [{"user_id": "alice"}]})
|
||||||
|
|
||||||
|
# With date range
|
||||||
|
memories = client.get_all(
|
||||||
|
filters={"AND": [
|
||||||
|
{"user_id": "alex"},
|
||||||
|
{"created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}}
|
||||||
|
]}
|
||||||
|
)
|
||||||
|
|
||||||
|
# With graph data
|
||||||
|
memories = client.get_all(filters={"AND": [{"user_id": "alice"}]}, enable_graph=True)
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
const memory = await client.get("ea925981-...");
|
||||||
|
const memories = await client.getAll({ filters: { AND: [{ user_id: "alice" }] } });
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** `get_all` requires at least one of `user_id`, `agent_id`, `app_id`, or `run_id` in filters.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## update() -- Modify Memories
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
client.update(memory_id="ea925981-...", text="Updated: vegan since 2024")
|
||||||
|
client.update(memory_id="ea925981-...", text="Updated", metadata={"verified": True})
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
await client.update("ea925981-...", { text: "Updated: vegan since 2024" });
|
||||||
|
```
|
||||||
|
|
||||||
|
Cannot update immutable memories.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## delete() / deleteAll() -- Remove Memories
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
client.delete(memory_id="ea925981-...")
|
||||||
|
client.delete_all(user_id="alice") # Irreversible bulk delete
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
await client.delete("ea925981-...");
|
||||||
|
await client.deleteAll({ user_id: "alice" });
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## history() -- Track Changes
|
||||||
|
|
||||||
|
**Python:**
|
||||||
|
```python
|
||||||
|
history = client.history(memory_id="ea925981-...")
|
||||||
|
# Returns: [{previous_value, new_value, action, timestamps}]
|
||||||
|
```
|
||||||
|
|
||||||
|
**TypeScript:**
|
||||||
|
```typescript
|
||||||
|
const history = await client.history("ea925981-...");
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Batch Operations (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Batch update
|
||||||
|
await client.batchUpdate([
|
||||||
|
{ memoryId: "uuid-1", text: "Updated text" },
|
||||||
|
{ memoryId: "uuid-2", text: "Another updated text" },
|
||||||
|
]);
|
||||||
|
|
||||||
|
// Batch delete
|
||||||
|
await client.batchDelete(["uuid-1", "uuid-2", "uuid-3"]);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Additional Methods
|
||||||
|
|
||||||
|
```python
|
||||||
|
# List all users/agents/sessions with memories
|
||||||
|
users = client.users()
|
||||||
|
|
||||||
|
# Delete a user/agent entity
|
||||||
|
client.delete_users(user_id="alice")
|
||||||
|
|
||||||
|
# Submit feedback on a memory
|
||||||
|
client.feedback(memory_id="...", feedback="POSITIVE", feedback_reason="Accurate extraction")
|
||||||
|
|
||||||
|
# Export memories
|
||||||
|
export = client.create_memory_export(filters={"AND": [{"user_id": "alice"}]})
|
||||||
|
data = client.get_memory_export(memory_export_id=export["id"])
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
1. **Entity cross-filtering fails silently** -- `AND` with `user_id` + `agent_id` returns empty. Use `OR`.
|
||||||
|
2. **SQL operators rejected** -- use `gte`, `lt`, etc. Not `>=`, `<`.
|
||||||
|
3. **Metadata filtering is limited** -- only top-level keys with `eq`, `contains`, `ne`.
|
||||||
|
4. **Wildcard `*` excludes null** -- only matches non-null values.
|
||||||
|
5. **Default threshold is 0.3** -- increase for stricter matching.
|
||||||
|
6. **Async processing** -- memories process asynchronously. Wait 2-3s after `add()` before searching.
|
||||||
|
7. **Immutable memories** -- cannot be updated or deleted once created.
|
||||||
|
|
||||||
|
## Naming Conventions
|
||||||
|
|
||||||
|
Python uses `snake_case` (`user_id`, `memory_id`, `get_all`). TypeScript uses `camelCase` for methods (`getAll`, `deleteAll`, `batchUpdate`) but `snake_case` for API parameters (`user_id`, `agent_id`).
|
||||||
@@ -0,0 +1,720 @@
|
|||||||
|
# Mem0 Use Cases & Examples
|
||||||
|
|
||||||
|
Real-world implementation patterns for Mem0 Platform. Each use case includes complete, runnable code in both Python and TypeScript.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Personalized AI Companion](#1-personalized-ai-companion)
|
||||||
|
- [Customer Support with Categories](#2-customer-support-with-categories)
|
||||||
|
- [Healthcare Coach](#3-healthcare-coach)
|
||||||
|
- [Content Creation Workflow](#4-content-creation-workflow)
|
||||||
|
- [Multi-Agent / Multi-Tenant](#5-multi-agent--multi-tenant)
|
||||||
|
- [Personalized Search](#6-personalized-search)
|
||||||
|
- [Email Intelligence](#7-email-intelligence)
|
||||||
|
- [Common Patterns Across Use Cases](#common-patterns-across-use-cases)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Personalized AI Companion
|
||||||
|
|
||||||
|
A fitness coach that remembers goals, preferences, and progress across sessions. Mem0 persists context across app restarts — no session state needed.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
from openai import OpenAI
|
||||||
|
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
openai_client = OpenAI()
|
||||||
|
|
||||||
|
def chat(user_input: str, user_id: str) -> str:
|
||||||
|
# 1. Retrieve relevant memories
|
||||||
|
memories = mem0.search(user_input, user_id=user_id)
|
||||||
|
context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
|
||||||
|
|
||||||
|
# 2. Generate response with memory context
|
||||||
|
system_prompt = f"""You are Ray, a personal fitness coach.
|
||||||
|
Use these known facts about the user to personalize your response:
|
||||||
|
{context if context else 'No prior context yet.'}"""
|
||||||
|
|
||||||
|
response = openai_client.chat.completions.create(
|
||||||
|
model="gpt-4.1-nano-2025-04-14",
|
||||||
|
messages=[
|
||||||
|
{"role": "system", "content": system_prompt},
|
||||||
|
{"role": "user", "content": user_input},
|
||||||
|
]
|
||||||
|
)
|
||||||
|
reply = response.choices[0].message.content
|
||||||
|
|
||||||
|
# 3. Store interaction for future context
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": user_input}, {"role": "assistant", "content": reply}],
|
||||||
|
user_id=user_id
|
||||||
|
)
|
||||||
|
return reply
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
chat("I want to run a marathon in under 4 hours", user_id="max")
|
||||||
|
# Next day, app restarted:
|
||||||
|
chat("What should I focus on today?", user_id="max")
|
||||||
|
# Ray remembers the sub-4 marathon goal
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
import OpenAI from 'openai';
|
||||||
|
|
||||||
|
const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
const openai = new OpenAI();
|
||||||
|
|
||||||
|
async function chat(userInput: string, userId: string): Promise<string> {
|
||||||
|
// 1. Retrieve relevant memories
|
||||||
|
const memories = await mem0.search(userInput, { user_id: userId });
|
||||||
|
const context = memories.results
|
||||||
|
?.map((m: any) => `- ${m.memory}`)
|
||||||
|
.join('\n') || 'No prior context yet.';
|
||||||
|
|
||||||
|
// 2. Generate response with memory context
|
||||||
|
const response = await openai.chat.completions.create({
|
||||||
|
model: 'gpt-4.1-nano-2025-04-14',
|
||||||
|
messages: [
|
||||||
|
{ role: 'system', content: `You are Ray, a personal fitness coach.\nUser context:\n${context}` },
|
||||||
|
{ role: 'user', content: userInput },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
const reply = response.choices[0].message.content!;
|
||||||
|
|
||||||
|
// 3. Store interaction
|
||||||
|
await mem0.add(
|
||||||
|
[{ role: 'user', content: userInput }, { role: 'assistant', content: reply }],
|
||||||
|
{ user_id: userId }
|
||||||
|
);
|
||||||
|
return reply;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- Context persists across app restarts — no session management needed
|
||||||
|
- Memories are automatically deduplicated and updated
|
||||||
|
- Works with any LLM provider (OpenAI, Anthropic, etc.)
|
||||||
|
|
||||||
|
**Best for:** Fitness coaches, tutors, therapists — any assistant that needs to remember goals across sessions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Customer Support with Categories
|
||||||
|
|
||||||
|
Auto-categorize support data so teams retrieve the right facts fast. Uses custom categories for structured retrieval.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
client = MemoryClient()
|
||||||
|
|
||||||
|
# 1. Define categories at the project level (one-time setup)
|
||||||
|
custom_categories = [
|
||||||
|
{"support_tickets": "Customer issues and resolutions"},
|
||||||
|
{"account_info": "Account details and preferences"},
|
||||||
|
{"billing": "Payment history and billing questions"},
|
||||||
|
{"product_feedback": "Feature requests and feedback"},
|
||||||
|
]
|
||||||
|
client.project.update(custom_categories=custom_categories)
|
||||||
|
|
||||||
|
# 2. Store interactions — auto-classified into categories
|
||||||
|
def log_support_interaction(user_id: str, message: str, priority: str = "normal"):
|
||||||
|
client.add(
|
||||||
|
[{"role": "user", "content": message}],
|
||||||
|
user_id=user_id,
|
||||||
|
metadata={"priority": priority, "source": "support_chat"}
|
||||||
|
)
|
||||||
|
|
||||||
|
# 3. Retrieve by category
|
||||||
|
def get_billing_issues(user_id: str):
|
||||||
|
return client.get_all(
|
||||||
|
filters={
|
||||||
|
"AND": [
|
||||||
|
{"user_id": user_id},
|
||||||
|
{"categories": {"in": ["billing"]}}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
def search_support_history(user_id: str, query: str):
|
||||||
|
return client.search(
|
||||||
|
query,
|
||||||
|
filters={
|
||||||
|
"AND": [
|
||||||
|
{"user_id": user_id},
|
||||||
|
{"categories": {"contains": "support_tickets"}}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
top_k=5
|
||||||
|
)
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
log_support_interaction("maria", "I was charged twice for last month's subscription", priority="high")
|
||||||
|
log_support_interaction("maria", "The dashboard is loading slowly on mobile")
|
||||||
|
billing = get_billing_issues("maria") # Returns only billing-related memories
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
|
||||||
|
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
|
||||||
|
// Setup categories (one-time)
|
||||||
|
await client.updateProject({
|
||||||
|
custom_categories: [
|
||||||
|
{ support_tickets: 'Customer issues and resolutions' },
|
||||||
|
{ billing: 'Payment history and billing questions' },
|
||||||
|
{ product_feedback: 'Feature requests and feedback' },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
|
||||||
|
async function logInteraction(userId: string, message: string, priority = 'normal') {
|
||||||
|
await client.add(
|
||||||
|
[{ role: 'user', content: message }],
|
||||||
|
{ user_id: userId, metadata: { priority, source: 'support_chat' } }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function getBillingIssues(userId: string) {
|
||||||
|
return client.getAll({
|
||||||
|
filters: { AND: [{ user_id: userId }, { categories: { in: ['billing'] } }] },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- Automatic categorization — no manual tagging
|
||||||
|
- Filter by category for structured retrieval
|
||||||
|
- Metadata (`priority`, `source`) enables multi-dimensional queries
|
||||||
|
|
||||||
|
**Best for:** Help desks, SaaS support, e-commerce — structured retrieval by category eliminates manual scanning.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Healthcare Coach
|
||||||
|
|
||||||
|
Guide patients with an assistant that remembers medical history. Uses high `threshold` for confident retrieval in safety-critical contexts.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
from openai import OpenAI
|
||||||
|
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
openai_client = OpenAI()
|
||||||
|
|
||||||
|
def save_patient_info(user_id: str, information: str):
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": information}],
|
||||||
|
user_id=user_id,
|
||||||
|
run_id="healthcare_session",
|
||||||
|
metadata={"type": "patient_information"}
|
||||||
|
)
|
||||||
|
|
||||||
|
def consult(user_id: str, question: str) -> str:
|
||||||
|
# High threshold for medical accuracy
|
||||||
|
memories = mem0.search(question, user_id=user_id, top_k=5, threshold=0.7)
|
||||||
|
context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
|
||||||
|
|
||||||
|
response = openai_client.chat.completions.create(
|
||||||
|
model="gpt-4.1-nano-2025-04-14",
|
||||||
|
messages=[
|
||||||
|
{"role": "system", "content": f"You are a health coach. Patient context:\n{context}"},
|
||||||
|
{"role": "user", "content": question},
|
||||||
|
]
|
||||||
|
)
|
||||||
|
reply = response.choices[0].message.content
|
||||||
|
|
||||||
|
# Store the interaction
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": question}, {"role": "assistant", "content": reply}],
|
||||||
|
user_id=user_id,
|
||||||
|
run_id="healthcare_session",
|
||||||
|
)
|
||||||
|
return reply
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
save_patient_info("alex", "I'm allergic to penicillin and take metformin for type 2 diabetes")
|
||||||
|
consult("alex", "Can I take amoxicillin for my sore throat?")
|
||||||
|
# Remembers penicillin allergy — amoxicillin is a penicillin-type antibiotic
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
import OpenAI from 'openai';
|
||||||
|
|
||||||
|
const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
const openai = new OpenAI();
|
||||||
|
|
||||||
|
async function savePatientInfo(userId: string, info: string) {
|
||||||
|
await mem0.add(
|
||||||
|
[{ role: 'user', content: info }],
|
||||||
|
{ user_id: userId, run_id: 'healthcare_session', metadata: { type: 'patient_information' } }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function consult(userId: string, question: string): Promise<string> {
|
||||||
|
const memories = await mem0.search(question, {
|
||||||
|
user_id: userId,
|
||||||
|
top_k: 5,
|
||||||
|
threshold: 0.7,
|
||||||
|
});
|
||||||
|
const context = memories.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
|
||||||
|
|
||||||
|
const response = await openai.chat.completions.create({
|
||||||
|
model: 'gpt-4.1-nano-2025-04-14',
|
||||||
|
messages: [
|
||||||
|
{ role: 'system', content: `You are a health coach. Patient context:\n${context}` },
|
||||||
|
{ role: 'user', content: question },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
const reply = response.choices[0].message.content!;
|
||||||
|
|
||||||
|
await mem0.add(
|
||||||
|
[{ role: 'user', content: question }, { role: 'assistant', content: reply }],
|
||||||
|
{ user_id: userId, run_id: 'healthcare_session' }
|
||||||
|
);
|
||||||
|
return reply;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- High threshold (0.7) ensures only confident matches for safety-critical retrieval
|
||||||
|
- Session scoping via `run_id` groups related health interactions
|
||||||
|
- Metadata tagging separates patient info from conversation history
|
||||||
|
|
||||||
|
**Best for:** Telehealth, wellness apps, patient management — persistent health context across visits.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Content Creation Workflow
|
||||||
|
|
||||||
|
Store voice guidelines once and apply them across every draft. Uses `run_id` and `metadata` to scope writing preferences per session.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
from openai import OpenAI
|
||||||
|
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
openai_client = OpenAI()
|
||||||
|
|
||||||
|
def store_writing_preferences(user_id: str, preferences: str):
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": preferences}],
|
||||||
|
user_id=user_id,
|
||||||
|
run_id="editing_session",
|
||||||
|
metadata={"type": "preferences", "category": "writing_style"}
|
||||||
|
)
|
||||||
|
|
||||||
|
def draft_content(user_id: str, topic: str) -> str:
|
||||||
|
# Retrieve writing preferences
|
||||||
|
prefs = mem0.search(
|
||||||
|
"writing style preferences",
|
||||||
|
filters={"AND": [{"user_id": user_id}, {"run_id": "editing_session"}]}
|
||||||
|
)
|
||||||
|
style_context = "\n".join([f"- {m['memory']}" for m in prefs.get("results", [])])
|
||||||
|
|
||||||
|
response = openai_client.chat.completions.create(
|
||||||
|
model="gpt-4.1-nano-2025-04-14",
|
||||||
|
messages=[
|
||||||
|
{"role": "system", "content": f"Write content matching these style preferences:\n{style_context}"},
|
||||||
|
{"role": "user", "content": f"Write a blog post about: {topic}"},
|
||||||
|
]
|
||||||
|
)
|
||||||
|
return response.choices[0].message.content
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
store_writing_preferences("writer_01", "I prefer short sentences. Active voice. No jargon. Use analogies.")
|
||||||
|
draft_content("writer_01", "Why AI memory matters for chatbots")
|
||||||
|
# Drafts content matching the stored voice guidelines
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
import OpenAI from 'openai';
|
||||||
|
|
||||||
|
const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
const openai = new OpenAI();
|
||||||
|
|
||||||
|
async function storePreferences(userId: string, preferences: string) {
|
||||||
|
await mem0.add(
|
||||||
|
[{ role: 'user', content: preferences }],
|
||||||
|
{ user_id: userId, run_id: 'editing_session', metadata: { type: 'preferences' } }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function draftContent(userId: string, topic: string): Promise<string> {
|
||||||
|
const prefs = await mem0.search('writing style preferences', {
|
||||||
|
filters: { AND: [{ user_id: userId }, { run_id: 'editing_session' }] },
|
||||||
|
});
|
||||||
|
const styleContext = prefs.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
|
||||||
|
|
||||||
|
const response = await openai.chat.completions.create({
|
||||||
|
model: 'gpt-4.1-nano-2025-04-14',
|
||||||
|
messages: [
|
||||||
|
{ role: 'system', content: `Write content matching these preferences:\n${styleContext}` },
|
||||||
|
{ role: 'user', content: `Write a blog post about: ${topic}` },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
return response.choices[0].message.content!;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- Voice consistency across all content without repeating guidelines
|
||||||
|
- Scoped sessions let you maintain different style profiles
|
||||||
|
- Preferences update automatically as you refine them
|
||||||
|
|
||||||
|
**Best for:** Marketing teams, technical writers, agencies — consistent voice across all content.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Multi-Agent / Multi-Tenant
|
||||||
|
|
||||||
|
Keep memories separate using `user_id`, `agent_id`, `app_id`, and `run_id` scoping. Critical for multi-agent workflows and multi-tenant apps.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
client = MemoryClient()
|
||||||
|
|
||||||
|
# Store memories scoped to user + agent + session
|
||||||
|
def store_scoped_memory(messages: list, user_id: str, agent_id: str, run_id: str, app_id: str):
|
||||||
|
client.add(
|
||||||
|
messages,
|
||||||
|
user_id=user_id,
|
||||||
|
agent_id=agent_id,
|
||||||
|
run_id=run_id,
|
||||||
|
app_id=app_id
|
||||||
|
)
|
||||||
|
|
||||||
|
# Query within a specific scope
|
||||||
|
def search_user_session(query: str, user_id: str, app_id: str, run_id: str):
|
||||||
|
"""Search memories for a specific user within a specific session."""
|
||||||
|
return client.search(
|
||||||
|
query,
|
||||||
|
filters={
|
||||||
|
"AND": [
|
||||||
|
{"user_id": user_id},
|
||||||
|
{"app_id": app_id},
|
||||||
|
{"run_id": run_id}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
def search_agent_knowledge(query: str, agent_id: str, app_id: str):
|
||||||
|
"""Search all memories an agent has across all users."""
|
||||||
|
return client.search(
|
||||||
|
query,
|
||||||
|
filters={
|
||||||
|
"AND": [
|
||||||
|
{"agent_id": agent_id},
|
||||||
|
{"app_id": app_id}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
# Usage: Travel concierge app with multiple agents
|
||||||
|
store_scoped_memory(
|
||||||
|
[{"role": "user", "content": "I'm vegetarian and prefer window seats"}],
|
||||||
|
user_id="traveler_cam",
|
||||||
|
agent_id="travel_planner",
|
||||||
|
run_id="tokyo-2025",
|
||||||
|
app_id="concierge_app"
|
||||||
|
)
|
||||||
|
|
||||||
|
# User-scoped query: "What does Cam prefer?"
|
||||||
|
user_mems = search_user_session("dietary restrictions?", "traveler_cam", "concierge_app", "tokyo-2025")
|
||||||
|
|
||||||
|
# Agent-scoped query: "What do all travelers prefer?" (across users)
|
||||||
|
agent_mems = search_agent_knowledge("common dietary restrictions?", "travel_planner", "concierge_app")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
|
||||||
|
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
|
||||||
|
async function storeScopedMemory(
|
||||||
|
messages: Array<{ role: string; content: string }>,
|
||||||
|
userId: string, agentId: string, runId: string, appId: string
|
||||||
|
) {
|
||||||
|
await client.add(messages, {
|
||||||
|
user_id: userId,
|
||||||
|
agent_id: agentId,
|
||||||
|
run_id: runId,
|
||||||
|
app_id: appId,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
async function searchUserSession(query: string, userId: string, appId: string, runId: string) {
|
||||||
|
return client.search(query, {
|
||||||
|
filters: { AND: [{ user_id: userId }, { app_id: appId }, { run_id: runId }] },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
async function searchAgentKnowledge(query: string, agentId: string, appId: string) {
|
||||||
|
return client.search(query, {
|
||||||
|
filters: { AND: [{ agent_id: agentId }, { app_id: appId }] },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- Full isolation between users, agents, sessions, and apps
|
||||||
|
- Query at any scope level — user, agent, session, or app-wide
|
||||||
|
- No memory leakage between tenants
|
||||||
|
|
||||||
|
**Best for:** Multi-agent workflows, multi-tenant SaaS — proper isolation at every level.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Personalized Search
|
||||||
|
|
||||||
|
Blend real-time search results with personal context. Uses `custom_instructions` to infer preferences from queries.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
from openai import OpenAI
|
||||||
|
|
||||||
|
mem0 = MemoryClient()
|
||||||
|
openai_client = OpenAI()
|
||||||
|
|
||||||
|
# One-time setup: configure Mem0 to infer from queries
|
||||||
|
mem0.project.update(
|
||||||
|
custom_instructions="""Infer user preferences and facts from their search queries.
|
||||||
|
Extract dietary preferences, location, interests, and purchase history."""
|
||||||
|
)
|
||||||
|
|
||||||
|
def personalized_search(user_id: str, query: str, search_results: list) -> str:
|
||||||
|
# Get user context from memory
|
||||||
|
memories = mem0.search(query, user_id=user_id, top_k=5)
|
||||||
|
user_context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
|
||||||
|
|
||||||
|
response = openai_client.chat.completions.create(
|
||||||
|
model="gpt-4.1-nano-2025-04-14",
|
||||||
|
messages=[
|
||||||
|
{"role": "system", "content": f"Personalize search results using user context:\n{user_context}"},
|
||||||
|
{"role": "user", "content": f"Query: {query}\n\nSearch results:\n{search_results}"},
|
||||||
|
]
|
||||||
|
)
|
||||||
|
reply = response.choices[0].message.content
|
||||||
|
|
||||||
|
# Store the query to learn preferences over time
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": query}],
|
||||||
|
user_id=user_id
|
||||||
|
)
|
||||||
|
return reply
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
personalized_search("user_42", "best restaurants nearby", ["Restaurant A", "Restaurant B"])
|
||||||
|
# Over time, Mem0 learns: "user prefers vegetarian, lives in Austin"
|
||||||
|
# Future searches are automatically personalized
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
import OpenAI from 'openai';
|
||||||
|
|
||||||
|
const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
const openai = new OpenAI();
|
||||||
|
|
||||||
|
async function personalizedSearch(userId: string, query: string, searchResults: string[]): Promise<string> {
|
||||||
|
const memories = await mem0.search(query, { user_id: userId, top_k: 5 });
|
||||||
|
const context = memories.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
|
||||||
|
|
||||||
|
const response = await openai.chat.completions.create({
|
||||||
|
model: 'gpt-4.1-nano-2025-04-14',
|
||||||
|
messages: [
|
||||||
|
{ role: 'system', content: `Personalize results using user context:\n${context}` },
|
||||||
|
{ role: 'user', content: `Query: ${query}\nResults: ${searchResults.join(', ')}` },
|
||||||
|
],
|
||||||
|
});
|
||||||
|
const reply = response.choices[0].message.content!;
|
||||||
|
|
||||||
|
await mem0.add([{ role: 'user', content: query }], { user_id: userId });
|
||||||
|
return reply;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- Learns preferences from queries automatically via `custom_instructions`
|
||||||
|
- Personalizes any search provider (Tavily, Google, Bing)
|
||||||
|
- Zero manual preference setup — improves over time
|
||||||
|
|
||||||
|
**Best for:** Personalized search engines, recommendation systems — search results tailored to individual users.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Email Intelligence
|
||||||
|
|
||||||
|
Capture, categorize, and recall inbox threads using persistent memories with rich metadata.
|
||||||
|
|
||||||
|
### Implementation (Python)
|
||||||
|
|
||||||
|
```python
|
||||||
|
from mem0 import MemoryClient
|
||||||
|
|
||||||
|
client = MemoryClient()
|
||||||
|
|
||||||
|
def store_email(user_id: str, sender: str, subject: str, body: str, date: str):
|
||||||
|
client.add(
|
||||||
|
[{"role": "user", "content": f"Email from {sender}: {subject}\n\n{body}"}],
|
||||||
|
user_id=user_id,
|
||||||
|
metadata={"email_type": "incoming", "sender": sender, "subject": subject, "date": date}
|
||||||
|
)
|
||||||
|
|
||||||
|
def search_emails(user_id: str, query: str):
|
||||||
|
return client.search(
|
||||||
|
query,
|
||||||
|
filters={"AND": [{"user_id": user_id}, {"categories": {"contains": "email"}}]},
|
||||||
|
top_k=10
|
||||||
|
)
|
||||||
|
|
||||||
|
def get_emails_from_sender(user_id: str, sender: str):
|
||||||
|
return client.get_all(
|
||||||
|
filters={
|
||||||
|
"AND": [
|
||||||
|
{"user_id": user_id},
|
||||||
|
{"metadata": {"contains": sender}}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
# Usage
|
||||||
|
store_email("alice", "bob@acme.com", "Q3 Budget Review", "Attached is the Q3 budget...", "2025-01-15")
|
||||||
|
store_email("alice", "carol@acme.com", "Sprint Planning", "Here are the priorities...", "2025-01-16")
|
||||||
|
|
||||||
|
results = search_emails("alice", "budget discussions")
|
||||||
|
sender_emails = get_emails_from_sender("alice", "bob@acme.com")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation (TypeScript)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import MemoryClient from 'mem0ai';
|
||||||
|
|
||||||
|
const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
|
||||||
|
|
||||||
|
async function storeEmail(userId: string, sender: string, subject: string, body: string, date: string) {
|
||||||
|
await client.add(
|
||||||
|
[{ role: 'user', content: `Email from ${sender}: ${subject}\n\n${body}` }],
|
||||||
|
{ user_id: userId, metadata: { email_type: 'incoming', sender, subject, date } }
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function searchEmails(userId: string, query: string) {
|
||||||
|
return client.search(query, {
|
||||||
|
filters: { AND: [{ user_id: userId }, { categories: { contains: 'email' } }] },
|
||||||
|
top_k: 10,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Benefits
|
||||||
|
|
||||||
|
- Rich metadata enables multi-dimensional queries (sender, date, subject)
|
||||||
|
- Category filtering separates emails from other memory types
|
||||||
|
- Semantic search across all email content
|
||||||
|
|
||||||
|
**Best for:** Inbox management, email automation — searchable email memories with metadata filtering.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Patterns Across Use Cases
|
||||||
|
|
||||||
|
### Pattern 1: Retrieve → Generate → Store
|
||||||
|
|
||||||
|
Every use case follows the same 3-step loop:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# 1. Retrieve relevant context
|
||||||
|
memories = mem0.search(user_input, user_id=user_id)
|
||||||
|
context = "\n".join([m["memory"] for m in memories.get("results", [])])
|
||||||
|
|
||||||
|
# 2. Generate with context
|
||||||
|
response = llm.generate(system_prompt=f"Context:\n{context}", user_input=user_input)
|
||||||
|
|
||||||
|
# 3. Store the interaction
|
||||||
|
mem0.add(
|
||||||
|
[{"role": "user", "content": user_input}, {"role": "assistant", "content": response}],
|
||||||
|
user_id=user_id
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 2: Scope with Entity Identifiers
|
||||||
|
|
||||||
|
Use `user_id`, `agent_id`, `app_id`, and `run_id` to isolate memories:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# User-level: personal preferences
|
||||||
|
client.add(messages, user_id="alice")
|
||||||
|
|
||||||
|
# Session-level: conversation within one session
|
||||||
|
client.add(messages, user_id="alice", run_id="session_123")
|
||||||
|
|
||||||
|
# Agent-level: agent-specific knowledge
|
||||||
|
client.add(messages, agent_id="support_bot", app_id="helpdesk")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 3: Rich Metadata for Filtering
|
||||||
|
|
||||||
|
Attach structured metadata for multi-dimensional queries:
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Store with metadata
|
||||||
|
client.add(messages, user_id="alice", metadata={"priority": "high", "source": "phone_call"})
|
||||||
|
|
||||||
|
# Filter by category + metadata
|
||||||
|
client.search("billing issues", filters={
|
||||||
|
"AND": [{"user_id": "alice"}, {"categories": {"contains": "billing"}}]
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 4: Custom Instructions for Domain-Specific Extraction
|
||||||
|
|
||||||
|
Control what Mem0 extracts from conversations:
|
||||||
|
|
||||||
|
```python
|
||||||
|
client.project.update(
|
||||||
|
custom_instructions="Extract medical conditions, medications, and allergies. Exclude billing info."
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## More Examples
|
||||||
|
|
||||||
|
For 30+ cookbooks with complete working code: [docs.mem0.ai/cookbooks](https://docs.mem0.ai/cookbooks)
|
||||||
Executable
+224
@@ -0,0 +1,224 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Mem0 Documentation Search Agent (Mintlify-based)
|
||||||
|
On-demand search tool for querying Mem0 documentation without storing content locally.
|
||||||
|
|
||||||
|
This tool leverages Mintlify's documentation structure to perform just-in-time
|
||||||
|
retrieval of technical information from docs.mem0.ai.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python mem0_doc_search.py --query "how to add graph memory"
|
||||||
|
python mem0_doc_search.py --query "filter syntax for categories"
|
||||||
|
python mem0_doc_search.py --page "/platform/features/graph-memory"
|
||||||
|
python mem0_doc_search.py --index
|
||||||
|
python mem0_doc_search.py --query "webhook events" --section platform
|
||||||
|
|
||||||
|
Purpose:
|
||||||
|
- Avoid bloating local context with full documentation
|
||||||
|
- Enable just-in-time retrieval of technical details
|
||||||
|
- Query specific documentation pages on demand
|
||||||
|
- Search across the full Mem0 documentation site
|
||||||
|
"""
|
||||||
|
|
||||||
|
import argparse
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
import urllib.error
|
||||||
|
import urllib.parse
|
||||||
|
import urllib.request
|
||||||
|
|
||||||
|
DOCS_BASE = "https://docs.mem0.ai"
|
||||||
|
SEARCH_ENDPOINT = f"{DOCS_BASE}/api/search"
|
||||||
|
LLMS_INDEX = f"{DOCS_BASE}/llms.txt"
|
||||||
|
|
||||||
|
# Known documentation sections for targeted retrieval
|
||||||
|
SECTION_MAP = {
|
||||||
|
"platform": [
|
||||||
|
"/platform/overview",
|
||||||
|
"/platform/quickstart",
|
||||||
|
"/platform/features",
|
||||||
|
"/platform/features/graph-memory",
|
||||||
|
"/platform/features/selective-memory",
|
||||||
|
"/platform/features/custom-categories",
|
||||||
|
"/platform/features/v2-memory-filters",
|
||||||
|
"/platform/features/async-client",
|
||||||
|
"/platform/features/webhooks",
|
||||||
|
"/platform/features/multimodal",
|
||||||
|
],
|
||||||
|
"api": [
|
||||||
|
"/api-reference/memory/add-memories",
|
||||||
|
"/api-reference/memory/v2-search-memories",
|
||||||
|
"/api-reference/memory/v2-get-memories",
|
||||||
|
"/api-reference/memory/get-memory",
|
||||||
|
"/api-reference/memory/update-memory",
|
||||||
|
"/api-reference/memory/delete-memory",
|
||||||
|
],
|
||||||
|
"open-source": [
|
||||||
|
"/open-source/overview",
|
||||||
|
"/open-source/python-quickstart",
|
||||||
|
"/open-source/node-quickstart",
|
||||||
|
"/open-source/features",
|
||||||
|
"/open-source/features/graph-memory",
|
||||||
|
"/open-source/features/rest-api",
|
||||||
|
"/open-source/configure-components",
|
||||||
|
],
|
||||||
|
"openmemory": [
|
||||||
|
"/openmemory/overview",
|
||||||
|
"/openmemory/quickstart",
|
||||||
|
],
|
||||||
|
"sdks": [
|
||||||
|
"/sdks/python",
|
||||||
|
"/sdks/js",
|
||||||
|
],
|
||||||
|
"integrations": [
|
||||||
|
"/integrations",
|
||||||
|
],
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def fetch_url(url: str) -> str:
|
||||||
|
"""Fetch content from a URL."""
|
||||||
|
req = urllib.request.Request(url, headers={"User-Agent": "Mem0DocSearchAgent/1.0"})
|
||||||
|
try:
|
||||||
|
with urllib.request.urlopen(req, timeout=15) as resp:
|
||||||
|
return resp.read().decode("utf-8")
|
||||||
|
except urllib.error.HTTPError as e:
|
||||||
|
return f"HTTP Error {e.code}: {e.reason}"
|
||||||
|
except urllib.error.URLError as e:
|
||||||
|
return f"URL Error: {e.reason}"
|
||||||
|
|
||||||
|
|
||||||
|
def search_docs(query: str, section: str | None = None) -> dict:
|
||||||
|
"""
|
||||||
|
Search Mem0 documentation using Mintlify's search API.
|
||||||
|
Falls back to the llms.txt index for keyword matching if the API is unavailable.
|
||||||
|
"""
|
||||||
|
# Try Mintlify search API first
|
||||||
|
params = urllib.parse.urlencode({"query": query})
|
||||||
|
search_url = f"{SEARCH_ENDPOINT}?{params}"
|
||||||
|
|
||||||
|
try:
|
||||||
|
result = fetch_url(search_url)
|
||||||
|
data = json.loads(result)
|
||||||
|
if isinstance(data, dict) and data.get("results"):
|
||||||
|
results = data["results"]
|
||||||
|
if section and section in SECTION_MAP:
|
||||||
|
section_paths = SECTION_MAP[section]
|
||||||
|
results = [r for r in results if any(r.get("url", "").startswith(p) for p in section_paths)]
|
||||||
|
return {"source": "mintlify_search", "results": results}
|
||||||
|
except (json.JSONDecodeError, Exception):
|
||||||
|
pass
|
||||||
|
|
||||||
|
# Fallback: search llms.txt index for matching URLs
|
||||||
|
index_content = fetch_url(LLMS_INDEX)
|
||||||
|
query_lower = query.lower()
|
||||||
|
matching_urls = []
|
||||||
|
|
||||||
|
for line in index_content.splitlines():
|
||||||
|
line = line.strip()
|
||||||
|
if not line or line.startswith("#"):
|
||||||
|
continue
|
||||||
|
if query_lower in line.lower():
|
||||||
|
matching_urls.append(line)
|
||||||
|
|
||||||
|
if section and section in SECTION_MAP:
|
||||||
|
section_paths = SECTION_MAP[section]
|
||||||
|
matching_urls = [u for u in matching_urls if any(p in u for p in section_paths)]
|
||||||
|
|
||||||
|
return {
|
||||||
|
"source": "llms_txt_index",
|
||||||
|
"query": query,
|
||||||
|
"matching_urls": matching_urls[:20],
|
||||||
|
"suggestion": "Fetch specific URLs for detailed content",
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def fetch_page(page_path: str) -> dict:
|
||||||
|
"""Fetch a specific documentation page."""
|
||||||
|
url = f"{DOCS_BASE}{page_path}" if page_path.startswith("/") else page_path
|
||||||
|
content = fetch_url(url)
|
||||||
|
return {"url": url, "content": content[:10000], "truncated": len(content) > 10000}
|
||||||
|
|
||||||
|
|
||||||
|
def get_index() -> dict:
|
||||||
|
"""Fetch the full documentation index from llms.txt."""
|
||||||
|
content = fetch_url(LLMS_INDEX)
|
||||||
|
urls = [line.strip() for line in content.splitlines() if line.strip() and not line.startswith("#")]
|
||||||
|
return {"total_pages": len(urls), "urls": urls, "sections": list(SECTION_MAP.keys())}
|
||||||
|
|
||||||
|
|
||||||
|
def list_section(section: str) -> dict:
|
||||||
|
"""List all known pages in a documentation section."""
|
||||||
|
if section not in SECTION_MAP:
|
||||||
|
return {"error": f"Unknown section: {section}", "available": list(SECTION_MAP.keys())}
|
||||||
|
return {
|
||||||
|
"section": section,
|
||||||
|
"pages": [f"{DOCS_BASE}{p}" for p in SECTION_MAP[section]],
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
def main():
|
||||||
|
parser = argparse.ArgumentParser(description="Search Mem0 documentation on demand")
|
||||||
|
parser.add_argument("--query", help="Search query for documentation")
|
||||||
|
parser.add_argument("--page", help="Fetch a specific page path (e.g., /platform/features/graph-memory)")
|
||||||
|
parser.add_argument("--index", action="store_true", help="Show full documentation index")
|
||||||
|
parser.add_argument("--section", help="Filter by section or list section pages")
|
||||||
|
parser.add_argument("--json", action="store_true", help="Output as JSON")
|
||||||
|
|
||||||
|
args = parser.parse_args()
|
||||||
|
|
||||||
|
if args.index:
|
||||||
|
result = get_index()
|
||||||
|
elif args.section and not args.query:
|
||||||
|
result = list_section(args.section)
|
||||||
|
elif args.page:
|
||||||
|
result = fetch_page(args.page)
|
||||||
|
elif args.query:
|
||||||
|
result = search_docs(args.query, section=args.section)
|
||||||
|
else:
|
||||||
|
parser.print_help()
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
if args.json:
|
||||||
|
print(json.dumps(result, indent=2))
|
||||||
|
else:
|
||||||
|
if isinstance(result, dict):
|
||||||
|
if "results" in result:
|
||||||
|
print(f"Source: {result.get('source', 'unknown')}")
|
||||||
|
for r in result["results"]:
|
||||||
|
print(f" - {r.get('title', 'N/A')}: {r.get('url', 'N/A')}")
|
||||||
|
if r.get("description"):
|
||||||
|
print(f" {r['description'][:200]}")
|
||||||
|
elif "matching_urls" in result:
|
||||||
|
print(f"Source: {result['source']}")
|
||||||
|
print(f"Query: {result['query']}")
|
||||||
|
for url in result["matching_urls"]:
|
||||||
|
print(f" - {url}")
|
||||||
|
if result.get("suggestion"):
|
||||||
|
print(f"\n{result['suggestion']}")
|
||||||
|
elif "urls" in result:
|
||||||
|
print(f"Total documentation pages: {result['total_pages']}")
|
||||||
|
print(f"Sections: {', '.join(result['sections'])}")
|
||||||
|
for url in result["urls"][:30]:
|
||||||
|
print(f" - {url}")
|
||||||
|
if result["total_pages"] > 30:
|
||||||
|
print(f" ... and {result['total_pages'] - 30} more")
|
||||||
|
elif "pages" in result:
|
||||||
|
print(f"Section: {result['section']}")
|
||||||
|
for page in result["pages"]:
|
||||||
|
print(f" - {page}")
|
||||||
|
elif "content" in result:
|
||||||
|
print(f"URL: {result['url']}")
|
||||||
|
if result.get("truncated"):
|
||||||
|
print("[Content truncated to 10000 chars]")
|
||||||
|
print(result["content"])
|
||||||
|
elif "error" in result:
|
||||||
|
print(f"Error: {result['error']}")
|
||||||
|
if result.get("available"):
|
||||||
|
print(f"Available sections: {', '.join(result['available'])}")
|
||||||
|
else:
|
||||||
|
print(json.dumps(result, indent=2))
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
Reference in New Issue
Block a user