refactor: consolidate agent/editor plugins under integrations/ (#5491)
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Kartik
@@ -0,0 +1,129 @@
|
||||
# Python vs TypeScript SDK Differences
|
||||
|
||||
Quick-reference cheatsheet for developers working across both Mem0 SDKs.
|
||||
|
||||
## Constructor
|
||||
|
||||
| Aspect | Python | TypeScript |
|
||||
|--------|--------|------------|
|
||||
| Import (Platform) | `from mem0 import MemoryClient` | `import MemoryClient from 'mem0ai'` |
|
||||
| Import (OSS) | `from mem0 import Memory` | `import { Memory } from 'mem0ai/oss'` |
|
||||
| Constructor | `MemoryClient(api_key="m0-xxx")` | `new MemoryClient({ apiKey: 'm0-xxx' })` |
|
||||
| Required param | `api_key` (positional or kwarg) | `apiKey` (in options object) |
|
||||
|
||||
Both read from `MEM0_API_KEY` env var if no key provided.
|
||||
|
||||
## Method Naming
|
||||
|
||||
| Operation | Python | TypeScript |
|
||||
|-----------|--------|------------|
|
||||
| Add | `add()` | `add()` |
|
||||
| Search | `search()` | `search()` |
|
||||
| Get | `get()` | `get()` |
|
||||
| Get all | `get_all()` | `getAll()` |
|
||||
| Update | `update()` | `update()` |
|
||||
| Delete | `delete()` | `delete()` |
|
||||
| Delete all | `delete_all()` | `deleteAll()` |
|
||||
| History | `history()` | `history()` |
|
||||
| Batch update | `batch_update()` | `batchUpdate()` |
|
||||
| Batch delete | `batch_delete()` | `batchDelete()` |
|
||||
| List users | `users()` | `users()` |
|
||||
| Delete users | `delete_users()` | `deleteUsers()` |
|
||||
| Get project | `project.get()` | `getProject()` |
|
||||
| Update project | `project.update()` | `updateProject()` |
|
||||
| Create webhook | `create_webhook()` | `createWebhook()` |
|
||||
| Get webhooks | `get_webhooks()` | `getWebhooks()` |
|
||||
| Update webhook | `update_webhook()` | `updateWebhook()` |
|
||||
| Delete webhook | `delete_webhook()` | `deleteWebhook()` |
|
||||
| Create export | `create_memory_export()` | `createMemoryExport()` |
|
||||
| Get export | `get_memory_export()` | `getMemoryExport()` |
|
||||
| Feedback | `feedback()` | `feedback()` |
|
||||
|
||||
**Rule:** Python uses `snake_case`, TypeScript uses `camelCase` for method names.
|
||||
|
||||
## Parameter Passing
|
||||
|
||||
```python
|
||||
# Python: kwargs
|
||||
client.add(messages, user_id="alice", metadata={"source": "chat"})
|
||||
client.search("query", filters={"user_id": "alice"}, top_k=5, rerank=True)
|
||||
```
|
||||
|
||||
```typescript
|
||||
// TypeScript: options object with camelCase for top-level params, snake_case for filter keys
|
||||
await client.add(messages, { userId: 'alice', metadata: { source: 'chat' } });
|
||||
await client.search('query', { filters: { user_id: 'alice' }, topK: 5, rerank: true });
|
||||
```
|
||||
|
||||
**v3:** Python uses `snake_case` everywhere. TypeScript uses `camelCase` for top-level params (`userId`, `topK`) but `snake_case` for filter keys (`user_id`, `agent_id`).
|
||||
|
||||
## Architectural Differences
|
||||
|
||||
| Aspect | Python | TypeScript |
|
||||
|--------|--------|------------|
|
||||
| HTTP library | httpx | axios |
|
||||
| Default timeout | 300s | 60s |
|
||||
| Sync support | Yes (`MemoryClient`) | No (all async) |
|
||||
| Async support | Yes (`AsyncMemoryClient`) | All methods are async |
|
||||
| Project management | `client.project.*` (separate class) | `client.getProject()` / `client.updateProject()` |
|
||||
| Context manager | `async with AsyncMemoryClient()` | Not supported |
|
||||
|
||||
## Platform Features: Python-only
|
||||
|
||||
These methods exist in Python but not TypeScript:
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `get_summary(filters)` | Get summary of memories |
|
||||
| `reset()` | Delete ALL data (users + memories) |
|
||||
| `project.create(name)` | Create a new project |
|
||||
| `project.delete()` | Delete current project |
|
||||
| `project.get_members()` | List project members |
|
||||
| `project.add_member(email, role)` | Add member to project |
|
||||
| `project.update_member(email, role)` | Change member role |
|
||||
| `project.remove_member(email)` | Remove member |
|
||||
|
||||
## Platform Features: TypeScript-only
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `deleteUser(data)` | Convenience method for single entity deletion |
|
||||
| `ping()` | Health check endpoint |
|
||||
|
||||
## OSS Config Naming
|
||||
|
||||
| Python config key | TypeScript config key |
|
||||
|-------------------|----------------------|
|
||||
| `vector_store` | `vectorStore` |
|
||||
| `history_db_path` | `historyDbPath` |
|
||||
| `custom_instructions` | `customInstructions` |
|
||||
|
||||
## OSS Scope Parameter Naming
|
||||
|
||||
| Python | TypeScript |
|
||||
|--------|------------|
|
||||
| `user_id="alice"` | `userId: 'alice'` |
|
||||
| `agent_id="bot"` | `agentId: 'bot'` |
|
||||
| `run_id="session"` | `runId: 'session'` |
|
||||
|
||||
## Entity ID Passing (v3)
|
||||
|
||||
| Method | Python | TypeScript |
|
||||
|--------|--------|------------|
|
||||
| add() | Top-level: `user_id="alice"` | Top-level: `{ userId: 'alice' }` |
|
||||
| search() | In filters: `filters={"user_id": "alice"}` | In filters: `{ filters: { user_id: 'alice' } }` |
|
||||
| get_all() | In filters: `filters={"user_id": "alice"}` | In filters: `{ filters: { user_id: 'alice' } }` |
|
||||
|
||||
## Common Gotcha
|
||||
|
||||
When searching/filtering, both Python and TypeScript use `snake_case` for filter keys. TypeScript only uses `camelCase` for top-level method parameters:
|
||||
|
||||
```python
|
||||
# Python - snake_case in filters
|
||||
results = client.search("query", filters={"user_id": "alice"})
|
||||
```
|
||||
|
||||
```typescript
|
||||
// TypeScript - snake_case in filters, camelCase for top-level params
|
||||
const results = await client.search('query', { filters: { user_id: 'alice' }, topK: 20 });
|
||||
```
|
||||
@@ -0,0 +1,418 @@
|
||||
# Mem0 Node.js / TypeScript SDK Reference
|
||||
|
||||
Complete reference for the `mem0ai` npm package. Covers both the Platform client (managed API) and the Open Source self-hosted variant.
|
||||
|
||||
---
|
||||
|
||||
## Platform Client
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
npm install mem0ai
|
||||
export MEM0_API_KEY="m0-your-api-key"
|
||||
```
|
||||
|
||||
### MemoryClient
|
||||
|
||||
```typescript
|
||||
import MemoryClient from 'mem0ai';
|
||||
|
||||
const client = new MemoryClient({ apiKey: 'm0-xxx' });
|
||||
```
|
||||
|
||||
**Constructor:** `new MemoryClient({ apiKey })`. If `apiKey` is not provided, reads from `MEM0_API_KEY` environment variable.
|
||||
|
||||
- HTTP library: `axios`
|
||||
- Timeout: 60 seconds
|
||||
- Base URL: `https://api.mem0.ai`
|
||||
- All methods are async (return `Promise`)
|
||||
|
||||
---
|
||||
|
||||
### Memory Methods
|
||||
|
||||
#### add(messages, options?)
|
||||
|
||||
Store new memories from messages.
|
||||
|
||||
```typescript
|
||||
const messages = [
|
||||
{ role: 'user', content: "I'm a vegetarian and allergic to nuts." },
|
||||
{ role: 'assistant', content: "Got it! I'll remember that." },
|
||||
];
|
||||
await client.add(messages, { userId: 'alice' });
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `messages` | `Message[]` | Array of `{role, content}` objects |
|
||||
| `options.userId` | string | User identifier |
|
||||
| `options.agentId` | string | Agent identifier |
|
||||
| `options.appId` | string | Application identifier |
|
||||
| `options.runId` | string | Session identifier |
|
||||
| `options.metadata` | object | Custom key-value pairs |
|
||||
| `options.infer` | boolean | If false, store raw text (default: true) |
|
||||
|
||||
**Returns:** `Promise<any>` -- list of events
|
||||
|
||||
#### search(query, options?)
|
||||
|
||||
Search memories by semantic similarity.
|
||||
|
||||
```typescript
|
||||
const results = await client.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 20 });
|
||||
for (const mem of results.results) {
|
||||
console.log(mem.memory, mem.score);
|
||||
}
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `query` | string | Natural language search query |
|
||||
| `options.filters` | object | Filter object with entity IDs (`user_id`, `agent_id`, etc.) and/or `AND`/`OR`/`NOT` conditions |
|
||||
| `options.topK` | number | Number of results (default: 20) |
|
||||
| `options.rerank` | boolean | Enable semantic reranking (default: false) |
|
||||
| `options.threshold` | number | Minimum similarity (default: 0.1) |
|
||||
|
||||
**Returns:** `Promise<SearchResult>` -- `{results: [{id, memory, score, ...}]}`
|
||||
|
||||
#### get(memoryId)
|
||||
|
||||
```typescript
|
||||
const memory = await client.get('ea925981-...');
|
||||
```
|
||||
|
||||
#### getAll(options?)
|
||||
|
||||
Retrieve all memories. Requires at least one entity identifier in filters.
|
||||
|
||||
```typescript
|
||||
const memories = await client.getAll({ filters: { user_id: 'alice' } });
|
||||
// With filters
|
||||
const filtered = await client.getAll({
|
||||
filters: { AND: [{ user_id: 'alice' }, { categories: { contains: 'health' } }] },
|
||||
});
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `options.filters` | object | Filter object with entity IDs (`user_id`, `agent_id`, etc.) and/or `AND`/`OR`/`NOT` conditions |
|
||||
| `options.page` | number | Page number |
|
||||
| `options.pageSize` | number | Results per page |
|
||||
|
||||
#### update(memoryId, data)
|
||||
|
||||
```typescript
|
||||
await client.update('ea925981-...', { text: 'Updated: vegan since 2024' });
|
||||
await client.update('ea925981-...', { text: 'Updated', metadata: { verified: true } });
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `memoryId` | string | Memory ID |
|
||||
| `data.text` | string | New content |
|
||||
| `data.metadata` | object | New metadata |
|
||||
| `data.timestamp` | string | New timestamp |
|
||||
|
||||
#### delete(memoryId)
|
||||
|
||||
```typescript
|
||||
await client.delete('ea925981-...');
|
||||
```
|
||||
|
||||
#### deleteAll(options?)
|
||||
|
||||
```typescript
|
||||
await client.deleteAll({ userId: 'alice' });
|
||||
```
|
||||
|
||||
#### history(memoryId)
|
||||
|
||||
```typescript
|
||||
const history = await client.history('ea925981-...');
|
||||
// Returns: [{previousValue, newValue, action, timestamps}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Batch Methods
|
||||
|
||||
#### batchUpdate(memories)
|
||||
|
||||
```typescript
|
||||
await client.batchUpdate([
|
||||
{ memoryId: 'uuid-1', text: 'Updated text' },
|
||||
{ memoryId: 'uuid-2', text: 'Another update' },
|
||||
]);
|
||||
```
|
||||
|
||||
#### batchDelete(memories)
|
||||
|
||||
```typescript
|
||||
await client.batchDelete(['uuid-1', 'uuid-2', 'uuid-3']);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### User/Entity Management
|
||||
|
||||
#### users()
|
||||
|
||||
```typescript
|
||||
const users = await client.users();
|
||||
// Returns: {results: [{type: "user", name: "alice"}, ...]}
|
||||
```
|
||||
|
||||
#### deleteUser(data) / deleteUsers(data)
|
||||
|
||||
```typescript
|
||||
await client.deleteUser({ userId: 'alice' }); // Single entity
|
||||
await client.deleteUsers({ agentId: 'bot-1' }); // Flexible
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Project Management
|
||||
|
||||
```typescript
|
||||
// Get project config
|
||||
const config = await client.getProject({ fields: ['customCategories'] });
|
||||
|
||||
// Update project settings
|
||||
await client.updateProject({
|
||||
customInstructions: 'Extract dietary preferences and health info',
|
||||
customCategories: [{ health: 'Medical and dietary info' }],
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Webhooks
|
||||
|
||||
```typescript
|
||||
// List
|
||||
const webhooks = await client.getWebhooks({ projectId: 'proj_123' });
|
||||
|
||||
// Create
|
||||
const webhook = await client.createWebhook({
|
||||
url: 'https://your-app.com/webhook',
|
||||
name: 'Memory Logger',
|
||||
projectId: 'proj_123',
|
||||
eventTypes: ['memory_add', 'memory_update'],
|
||||
});
|
||||
|
||||
// Update
|
||||
await client.updateWebhook({
|
||||
webhookId: 'wh_123',
|
||||
name: 'Updated Logger',
|
||||
url: 'https://new-url.com',
|
||||
});
|
||||
|
||||
// Delete
|
||||
await client.deleteWebhook({ webhookId: 'wh_123' });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Feedback
|
||||
|
||||
```typescript
|
||||
await client.feedback({
|
||||
memoryId: 'mem-123',
|
||||
feedback: 'POSITIVE',
|
||||
feedbackReason: 'Accurately captured preference',
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Export
|
||||
|
||||
```typescript
|
||||
const exportReq = await client.createMemoryExport({
|
||||
schema: JSON.stringify({ type: 'object', properties: { name: { type: 'string' } } }),
|
||||
filters: { user_id: 'alice' },
|
||||
});
|
||||
|
||||
const result = await client.getMemoryExport({ memoryExportId: exportReq.id });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### TypeScript Types
|
||||
|
||||
Key interfaces from `mem0.types.ts`:
|
||||
|
||||
```typescript
|
||||
interface Message { role: string; content: string; }
|
||||
interface Memory { id: string; memory: string; userId: string; categories: string[]; score?: number; /* ... */ }
|
||||
interface MemoryOptions { userId?: string; agentId?: string; appId?: string; runId?: string; metadata?: object; /* ... */ }
|
||||
interface SearchOptions { filters?: object; topK?: number; rerank?: boolean; threshold?: number; /* ... */ }
|
||||
interface MemoryHistory { id: string; memoryId: string; previousValue: string; newValue: string; action: string; /* ... */ }
|
||||
interface FeedbackPayload { memoryId: string; feedback: string; feedbackReason?: string; }
|
||||
interface WebhookCreatePayload { url: string; name: string; projectId: string; eventTypes: string[]; }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Open Source / Self-Hosted
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
npm install mem0ai
|
||||
```
|
||||
|
||||
### Memory Class
|
||||
|
||||
```typescript
|
||||
import { Memory } from 'mem0ai/oss';
|
||||
|
||||
const m = new Memory(); // Uses default config
|
||||
```
|
||||
|
||||
**Import:** `from 'mem0ai/oss'` (NOT the default export -- that is `MemoryClient` for Platform)
|
||||
|
||||
### Configuration
|
||||
|
||||
```typescript
|
||||
const config = {
|
||||
llm: {
|
||||
provider: 'openai', // openai, groq, anthropic, google, ollama, lmstudio, mistral, azure
|
||||
config: {
|
||||
model: 'gpt-5-mini',
|
||||
apiKey: 'sk-xxx',
|
||||
},
|
||||
},
|
||||
embedder: {
|
||||
provider: 'openai', // openai, ollama, lmstudio, google, azure, langchain, anthropic
|
||||
config: {
|
||||
model: 'text-embedding-3-small',
|
||||
apiKey: 'sk-xxx',
|
||||
},
|
||||
},
|
||||
vectorStore: {
|
||||
provider: 'qdrant', // memory, qdrant, redis, supabase, langchain, azure_ai_search, pgvector
|
||||
config: {
|
||||
collectionName: 'my_memories',
|
||||
host: 'localhost',
|
||||
port: 6333,
|
||||
},
|
||||
},
|
||||
historyDbPath: 'history.db',
|
||||
customInstructions: '...',
|
||||
disableHistory: false,
|
||||
};
|
||||
|
||||
const m = new Memory(config);
|
||||
// Or from dict with validation:
|
||||
const m2 = Memory.fromConfig(config);
|
||||
```
|
||||
|
||||
### Methods
|
||||
|
||||
All methods are async (return `Promise`):
|
||||
|
||||
#### add(messages, config)
|
||||
|
||||
```typescript
|
||||
await m.add('I prefer dark mode', { userId: 'alice' });
|
||||
await m.add([
|
||||
{ role: 'user', content: 'I like hiking' },
|
||||
{ role: 'assistant', content: 'Great outdoor activity!' },
|
||||
], { userId: 'alice' });
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `messages` | `string \| Message[]` | Content to store |
|
||||
| `config.userId` | string | User identifier (at least one scope required) |
|
||||
| `config.agentId` | string | Agent identifier |
|
||||
| `config.runId` | string | Session identifier |
|
||||
| `config.metadata` | object | Custom key-value pairs |
|
||||
| `config.filters` | object | Additional filters |
|
||||
| `config.infer` | boolean | LLM inference (default: true) |
|
||||
|
||||
**Returns:** `Promise<{results: [...], relations?: [...]}>`
|
||||
|
||||
#### search(query, config)
|
||||
|
||||
```typescript
|
||||
const results = await m.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 5 });
|
||||
```
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `query` | string | Search query |
|
||||
| `config.filters` | object | Filter object with entity IDs (`user_id`, `agent_id`, `run_id`, etc.) |
|
||||
| `config.topK` | number | Max results (default: 20) |
|
||||
|
||||
#### get(memoryId) / getAll(config) / update(memoryId, data) / delete(memoryId) / deleteAll(config) / history(memoryId)
|
||||
|
||||
Same interface patterns. Note: OSS `update` takes a string for data, not an object.
|
||||
|
||||
```typescript
|
||||
await m.update('mem-id', 'new content');
|
||||
```
|
||||
|
||||
#### reset()
|
||||
|
||||
Clear the entire vector store and history.
|
||||
|
||||
```typescript
|
||||
await m.reset();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Differences: Platform vs OSS
|
||||
|
||||
| Aspect | Platform (`MemoryClient`) | OSS (`Memory`) |
|
||||
|--------|--------------------------|----------------|
|
||||
| **Import** | `import MemoryClient from 'mem0ai'` | `import { Memory } from 'mem0ai/oss'` |
|
||||
| **Auth** | API key required (`MEM0_API_KEY`) | No API key -- config-based |
|
||||
| **Execution** | API calls to `api.mem0.ai` | Local execution |
|
||||
| **Infrastructure** | Fully managed | Self-managed vector DB, embedder, LLM |
|
||||
| **Param style** | Top-level: `camelCase` (`userId`, `topK`), filter keys: `snake_case` (`user_id`) | Top-level: `camelCase` (`userId`, `topK`), filter keys: `snake_case` (`user_id`) |
|
||||
| **Batch ops** | `batchUpdate`, `batchDelete` | Not available |
|
||||
| **Webhooks** | Full CRUD | Not available |
|
||||
| **Export** | `createMemoryExport` | Not available |
|
||||
| **Feedback** | `feedback()` | Not available |
|
||||
| **Project mgmt** | `getProject`, `updateProject` | Not available |
|
||||
| **User listing** | `users()`, `deleteUser()` | Not available |
|
||||
| **History** | Platform-managed | SQLite (configurable) |
|
||||
|
||||
---
|
||||
|
||||
## v2 Compatibility
|
||||
|
||||
If you're using SDK v2.x:
|
||||
|
||||
**Naming Changes:**
|
||||
- Top-level params now use camelCase: `topK`, `rerank` (not `top_k`)
|
||||
- Filter keys use snake_case: `user_id`, `agent_id`
|
||||
- OSS: `limit` renamed to `topK`
|
||||
|
||||
**API Changes:**
|
||||
```typescript
|
||||
// v2 - top-level entity IDs, snake_case
|
||||
await client.search("query", { user_id: "alice", top_k: 20 });
|
||||
|
||||
// v3 - filters object with snake_case keys, camelCase top-level params
|
||||
await client.search("query", { filters: { user_id: "alice" }, topK: 20 });
|
||||
```
|
||||
|
||||
**Default Changes:**
|
||||
| Param | v2 | v3 |
|
||||
|-------|----|----|
|
||||
| `topK` | 100 | 20 |
|
||||
| `threshold` | none | 0.1 |
|
||||
| `rerank` | true | false |
|
||||
|
||||
**Removed:**
|
||||
- `OutputFormat` and `API_VERSION` enums
|
||||
- `organizationId`, `projectId` from constructor
|
||||
- `enableGraph`, `asyncMode`, `outputFormat`, `immutable`, `expirationDate`, `filterMemories`, `batchSize`, `forceAddOnly`, `includes`, `excludes`, `keywordSearch`
|
||||
|
||||
See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for details.
|
||||
@@ -0,0 +1,487 @@
|
||||
# Mem0 Python SDK Reference
|
||||
|
||||
Complete reference for the `mem0ai` Python package. Covers both the Platform client (managed API) and the Open Source self-hosted variant.
|
||||
|
||||
---
|
||||
|
||||
## Platform Client
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install mem0ai
|
||||
export MEM0_API_KEY="m0-your-api-key"
|
||||
```
|
||||
|
||||
### MemoryClient (Synchronous)
|
||||
|
||||
```python
|
||||
from mem0 import MemoryClient
|
||||
|
||||
client = MemoryClient(api_key="m0-xxx")
|
||||
```
|
||||
|
||||
**Constructor:** `MemoryClient(api_key=None)`. If `api_key` is not provided, reads from `MEM0_API_KEY` environment variable. Raises `ValueError` if no key found.
|
||||
|
||||
- HTTP library: `httpx`
|
||||
- Timeout: 300 seconds
|
||||
- Base URL: `https://api.mem0.ai`
|
||||
|
||||
### AsyncMemoryClient (Asynchronous)
|
||||
|
||||
```python
|
||||
from mem0 import AsyncMemoryClient
|
||||
|
||||
client = AsyncMemoryClient(api_key="m0-xxx")
|
||||
|
||||
# Or use as context manager
|
||||
async with AsyncMemoryClient(api_key="m0-xxx") as client:
|
||||
results = await client.search("query", filters={"user_id": "alice"})
|
||||
```
|
||||
|
||||
Same methods as `MemoryClient`, all `async`/`await`. Supports async context manager.
|
||||
|
||||
---
|
||||
|
||||
### Memory Methods
|
||||
|
||||
#### add(messages, **kwargs)
|
||||
|
||||
Store new memories from messages.
|
||||
|
||||
```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")
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `messages` | str \| dict \| list[dict] | required | Message content. Strings auto-convert to user messages |
|
||||
| `user_id` | str | None | User identifier |
|
||||
| `agent_id` | str | None | Agent identifier |
|
||||
| `app_id` | str | None | Application identifier |
|
||||
| `run_id` | str | None | Session/run identifier |
|
||||
| `metadata` | dict | None | Custom key-value pairs |
|
||||
| `infer` | bool | True | If False, store raw text without LLM inference |
|
||||
| `custom_categories` | list | None | Override project categories |
|
||||
| `custom_instructions` | str | None | Override extraction instructions |
|
||||
| `timestamp` | int \| float \| str | None | Custom timestamp (Unix epoch or ISO 8601) |
|
||||
|
||||
**Returns:** `dict` -- list of events: `[{"id": "...", "event": "ADD", "data": {"memory": "..."}}]`
|
||||
|
||||
#### search(query, **kwargs)
|
||||
|
||||
Search memories by semantic similarity.
|
||||
|
||||
```python
|
||||
results = client.search("dietary preferences", filters={"user_id": "alice"})
|
||||
for mem in results.get("results", []):
|
||||
print(mem["memory"], mem["score"])
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `query` | str | required | Natural language search query |
|
||||
| `filters` | dict | None | Filter object with entity IDs and/or `AND`/`OR`/`NOT` conditions (e.g., `{"user_id": "alice"}`) |
|
||||
| `top_k` | int | 10 | Number of results |
|
||||
| `rerank` | bool | False | Enable deep semantic reranking (+150-200ms) |
|
||||
| `threshold` | float | 0.1 | Minimum similarity score |
|
||||
| `fields` | list | None | Specific fields to return |
|
||||
| `categories` | list | None | Filter by category |
|
||||
|
||||
**Returns:** `dict` -- `{"results": [{id, memory, user_id, categories, score, created_at, ...}]}`
|
||||
|
||||
#### get(memory_id)
|
||||
|
||||
Retrieve a single memory by ID.
|
||||
|
||||
```python
|
||||
memory = client.get(memory_id="ea925981-...")
|
||||
```
|
||||
|
||||
**Returns:** `dict` -- full memory object
|
||||
|
||||
#### get_all(**kwargs)
|
||||
|
||||
Retrieve all memories with optional filtering. Requires at least one entity identifier.
|
||||
|
||||
```python
|
||||
memories = client.get_all(filters={"user_id": "alice"})
|
||||
# With compound filters
|
||||
memories = client.get_all(filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "health"}}]})
|
||||
```
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `filters` | dict | None | Filter object with entity IDs and/or `AND`/`OR`/`NOT` conditions |
|
||||
| `top_k` | int | None | Limit results |
|
||||
| `page` | int | None | Page number |
|
||||
| `page_size` | int | None | Results per page |
|
||||
|
||||
**Returns:** `dict` -- `{"results": [...]}`
|
||||
|
||||
#### update(memory_id, text=None, metadata=None, timestamp=None)
|
||||
|
||||
Update a memory's content, metadata, or timestamp. At least one parameter required.
|
||||
|
||||
```python
|
||||
client.update("ea925981-...", text="Updated: vegan since 2024")
|
||||
client.update("ea925981-...", metadata={"verified": True})
|
||||
```
|
||||
|
||||
**Returns:** `dict` -- updated memory
|
||||
|
||||
#### delete(memory_id)
|
||||
|
||||
Permanently delete a single memory.
|
||||
|
||||
```python
|
||||
client.delete("ea925981-...")
|
||||
```
|
||||
|
||||
#### delete_all(**kwargs)
|
||||
|
||||
Delete all memories matching filters. Irreversible.
|
||||
|
||||
```python
|
||||
client.delete_all(user_id="alice")
|
||||
```
|
||||
|
||||
#### history(memory_id)
|
||||
|
||||
Get the change history of a memory.
|
||||
|
||||
```python
|
||||
history = client.history("ea925981-...")
|
||||
# Returns: [{previous_value, new_value, action, timestamps}]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Batch Methods
|
||||
|
||||
#### batch_update(memories)
|
||||
|
||||
Update up to 1000 memories in a single request.
|
||||
|
||||
```python
|
||||
client.batch_update([
|
||||
{"memory_id": "uuid-1", "text": "Updated text"},
|
||||
{"memory_id": "uuid-2", "text": "Another update", "metadata": {"verified": True}},
|
||||
])
|
||||
```
|
||||
|
||||
#### batch_delete(memories)
|
||||
|
||||
Delete up to 1000 memories in a single request.
|
||||
|
||||
```python
|
||||
client.batch_delete([
|
||||
{"memory_id": "uuid-1"},
|
||||
{"memory_id": "uuid-2"},
|
||||
])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### User/Entity Management
|
||||
|
||||
#### users()
|
||||
|
||||
List all users, agents, and sessions that have memories.
|
||||
|
||||
```python
|
||||
users = client.users()
|
||||
# Returns: {"results": [{"type": "user", "name": "alice"}, ...]}
|
||||
```
|
||||
|
||||
#### delete_users(user_id=None, agent_id=None, app_id=None, run_id=None)
|
||||
|
||||
Delete a specific entity and all its memories.
|
||||
|
||||
```python
|
||||
client.delete_users(user_id="alice")
|
||||
```
|
||||
|
||||
#### reset()
|
||||
|
||||
Delete ALL users, agents, sessions, and memories. Complete data reset.
|
||||
|
||||
```python
|
||||
client.reset()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Export & Summary
|
||||
|
||||
#### create_memory_export(schema, **kwargs)
|
||||
|
||||
Create a structured export of memories.
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
schema = json.dumps({
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"name": {"type": "string"},
|
||||
"preferences": {"type": "array", "items": {"type": "string"}},
|
||||
}
|
||||
})
|
||||
export = client.create_memory_export(schema=schema, user_id="alice")
|
||||
```
|
||||
|
||||
#### get_memory_export(**kwargs)
|
||||
|
||||
Retrieve a previously created export.
|
||||
|
||||
```python
|
||||
result = client.get_memory_export(memory_export_id=export["id"])
|
||||
```
|
||||
|
||||
#### get_summary(filters=None)
|
||||
|
||||
Get a summary of memories.
|
||||
|
||||
```python
|
||||
summary = client.get_summary(filters={"user_id": "alice"})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Feedback
|
||||
|
||||
#### feedback(memory_id, feedback=None, feedback_reason=None)
|
||||
|
||||
Provide quality feedback on a memory.
|
||||
|
||||
```python
|
||||
client.feedback(
|
||||
memory_id="mem-123",
|
||||
feedback="POSITIVE", # POSITIVE | NEGATIVE | VERY_NEGATIVE | None (clear)
|
||||
feedback_reason="Accurately captured preference"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Webhooks
|
||||
|
||||
```python
|
||||
# List
|
||||
webhooks = client.get_webhooks(project_id="proj_123")
|
||||
|
||||
# Create
|
||||
webhook = client.create_webhook(
|
||||
url="https://your-app.com/webhook",
|
||||
name="Memory Logger",
|
||||
project_id="proj_123",
|
||||
event_types=["memory_add", "memory_update"]
|
||||
)
|
||||
|
||||
# Update
|
||||
client.update_webhook(webhook_id=123, name="Updated", url="https://new-url.com")
|
||||
|
||||
# Delete
|
||||
client.delete_webhook(webhook_id=123)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Project Management
|
||||
|
||||
Access via `client.project.*`:
|
||||
|
||||
```python
|
||||
# Get project config
|
||||
config = client.project.get(fields=["custom_categories", "custom_instructions"])
|
||||
|
||||
# Update project settings
|
||||
client.project.update(
|
||||
custom_instructions="Extract dietary preferences and health info",
|
||||
custom_categories=[{"health": "Medical and dietary info"}],
|
||||
multilingual=True,
|
||||
)
|
||||
|
||||
# Create/delete project
|
||||
client.project.create(name="My Project", description="...")
|
||||
client.project.delete()
|
||||
|
||||
# Member management
|
||||
members = client.project.get_members()
|
||||
client.project.add_member(email="user@example.com", role="READER") # READER or OWNER
|
||||
client.project.update_member(email="user@example.com", role="OWNER")
|
||||
client.project.remove_member(email="user@example.com")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Open Source / Self-Hosted
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install mem0ai
|
||||
```
|
||||
|
||||
### Memory Class
|
||||
|
||||
```python
|
||||
from mem0 import Memory
|
||||
|
||||
m = Memory() # Uses default config (OpenAI embedder + in-memory vector store)
|
||||
```
|
||||
|
||||
**Import:** `from mem0 import Memory` (NOT `MemoryClient` -- that is the Platform client)
|
||||
|
||||
### Configuration
|
||||
|
||||
```python
|
||||
config = {
|
||||
"llm": {
|
||||
"provider": "openai", # openai, groq, azure, ollama, lmstudio, google, anthropic, mistral
|
||||
"config": {
|
||||
"model": "gpt-5-mini",
|
||||
"api_key": "sk-xxx",
|
||||
}
|
||||
},
|
||||
"embedder": {
|
||||
"provider": "openai", # openai, ollama, azure, lmstudio, google, huggingface
|
||||
"config": {
|
||||
"model": "text-embedding-3-small",
|
||||
"api_key": "sk-xxx",
|
||||
}
|
||||
},
|
||||
"vector_store": {
|
||||
"provider": "qdrant", # faiss, qdrant, pgvector, redis, supabase, azure_ai_search, memory
|
||||
"config": {
|
||||
"collection_name": "my_memories",
|
||||
"host": "localhost",
|
||||
"port": 6333,
|
||||
}
|
||||
},
|
||||
"history_db_path": "history.db", # SQLite path for change history
|
||||
"custom_instructions": "...", # Custom LLM prompt for extraction
|
||||
}
|
||||
|
||||
m = Memory.from_config(config)
|
||||
```
|
||||
|
||||
### Context Manager
|
||||
|
||||
```python
|
||||
with Memory(config) as m:
|
||||
m.add("I prefer dark mode", user_id="alice")
|
||||
results = m.search("preferences", filters={"user_id": "alice"})
|
||||
# SQLite connections released automatically
|
||||
```
|
||||
|
||||
### Methods
|
||||
|
||||
All methods mirror the Platform client but run locally:
|
||||
|
||||
#### add(messages, *, user_id, agent_id, run_id, metadata, infer=True)
|
||||
|
||||
```python
|
||||
m.add("I'm a vegetarian", user_id="alice")
|
||||
m.add([
|
||||
{"role": "user", "content": "I like hiking"},
|
||||
{"role": "assistant", "content": "Great outdoor activity!"}
|
||||
], user_id="alice")
|
||||
```
|
||||
|
||||
At least one of `user_id`, `agent_id`, `run_id` required.
|
||||
|
||||
**Returns:** `{"results": [...], "relations": [...]}`
|
||||
|
||||
#### search(query, *, filters=None, top_k=20, threshold=0.1, rerank=False)
|
||||
|
||||
```python
|
||||
results = m.search("dietary preferences", filters={"user_id": "alice"}, top_k=5)
|
||||
```
|
||||
|
||||
Entity IDs (`user_id`, `agent_id`, `run_id`) must be passed inside the `filters` dict.
|
||||
|
||||
Supports filter operators: `eq`, `ne`, `in`, `nin`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`.
|
||||
|
||||
#### get(memory_id) / get_all(**kwargs) / update(memory_id, data, metadata=None) / delete(memory_id) / delete_all(**kwargs) / history(memory_id)
|
||||
|
||||
Same interface as Platform client.
|
||||
|
||||
#### reset()
|
||||
|
||||
Clear the entire vector store collection and history database. Recreates the vector store.
|
||||
|
||||
```python
|
||||
m.reset()
|
||||
```
|
||||
|
||||
#### close()
|
||||
|
||||
Release SQLite connections. Called automatically when using context manager.
|
||||
|
||||
### AsyncMemory
|
||||
|
||||
```python
|
||||
from mem0 import AsyncMemory
|
||||
|
||||
m = AsyncMemory(config)
|
||||
await m.add("text", user_id="alice")
|
||||
results = await m.search("query", filters={"user_id": "alice"})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Differences: Platform vs OSS
|
||||
|
||||
| Aspect | Platform (`MemoryClient`) | OSS (`Memory`) |
|
||||
|--------|--------------------------|----------------|
|
||||
| **Import** | `from mem0 import MemoryClient` | `from mem0 import Memory` |
|
||||
| **Auth** | API key required (`MEM0_API_KEY`) | No API key -- config-based |
|
||||
| **Execution** | API calls to `api.mem0.ai` | Local execution |
|
||||
| **Infrastructure** | Fully managed | Self-managed vector DB, embedder, LLM |
|
||||
| **Entity filtering** | `filters={"user_id": "..."}` | `filters={"user_id": "..."}` |
|
||||
| **Batch ops** | `batch_update`, `batch_delete` | Not available |
|
||||
| **Webhooks** | Full CRUD | Not available |
|
||||
| **Export** | `create_memory_export`, `get_memory_export` | Not available |
|
||||
| **Feedback** | `feedback()` | Not available |
|
||||
| **Project mgmt** | `client.project.*` | Not available |
|
||||
| **User listing** | `users()`, `delete_users()` | Not available |
|
||||
| **Custom prompts** | Via project settings | Direct config (`custom_instructions`) |
|
||||
| **History** | Platform-managed | SQLite (configurable) |
|
||||
| **Async** | `AsyncMemoryClient` | `AsyncMemory` |
|
||||
|
||||
---
|
||||
|
||||
## v2 Compatibility
|
||||
|
||||
If you're using SDK v2.x or the v2 API:
|
||||
|
||||
**API Changes:**
|
||||
- **Entity IDs in search/get_all:** Pass `user_id`, `agent_id` as top-level kwargs instead of inside `filters`
|
||||
```python
|
||||
# v2
|
||||
results = client.search("query", user_id="alice")
|
||||
# v3
|
||||
results = client.search("query", filters={"user_id": "alice"})
|
||||
```
|
||||
- **add() returns:** v2 returns ADD, UPDATE, DELETE events; v3 returns ADD only
|
||||
|
||||
**Default Changes:**
|
||||
| Param | v2 | v3 |
|
||||
|-------|----|----|
|
||||
| `top_k` | 100 | 20 |
|
||||
| `threshold` | None | 0.1 |
|
||||
| `rerank` | True | False |
|
||||
|
||||
**Removed Parameters:**
|
||||
- Constructor: `org_id`, `project_id`
|
||||
- add(): `async_mode`, `output_format`, `enable_graph`, `immutable`, `expiration_date`, `filter_memories`, `batch_size`, `force_add_only`, `includes`, `excludes`, `keyword_search`
|
||||
- search()/get_all(): `enable_graph`
|
||||
- Config: `enable_graph`, `graph_store`, `custom_fact_extraction_prompt` (renamed to `custom_instructions`)
|
||||
|
||||
See the [v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-v3) for full details.
|
||||
Reference in New Issue
Block a user