fix: update skills and docs (#4868)

This commit is contained in:
Kartik
2026-04-18 11:42:37 +05:30
committed by GitHub
parent c1c5bd62f6
commit 93da5ef8f7
23 changed files with 461 additions and 662 deletions
+18 -14
View File
@@ -46,18 +46,16 @@ Both read from `MEM0_API_KEY` env var if no key provided.
```python
# Python: kwargs
client.add(messages, user_id="alice", metadata={"source": "chat"})
client.search("query", user_id="alice", top_k=5, rerank=True)
client.search("query", filters={"user_id": "alice"}, top_k=5, rerank=True)
```
```typescript
// TypeScript: options object
await client.add(messages, { user_id: 'alice', metadata: { source: 'chat' } });
await client.search('query', { user_id: 'alice', top_k: 5, rerank: true });
// 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 });
```
**Important:** Both use `snake_case` for API parameter names (`user_id`, `agent_id`, `top_k`, etc.). Only method names differ.
Exception: OSS TypeScript uses `camelCase` for config params (`userId`, `agentId`, `runId`).
**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
@@ -97,10 +95,8 @@ These methods exist in Python but not TypeScript:
| Python config key | TypeScript config key |
|-------------------|----------------------|
| `vector_store` | `vectorStore` |
| `graph_store` | `graphStore` |
| `history_db_path` | `historyDbPath` |
| `custom_instructions` | `customInstructions` |
| `enable_graph` | `enableGraph` |
## OSS Scope Parameter Naming
@@ -110,16 +106,24 @@ These methods exist in Python but not TypeScript:
| `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 SDKs use `snake_case`** for filter keys:
When searching/filtering, both Python and TypeScript use `snake_case` for filter keys. TypeScript only uses `camelCase` for top-level method parameters:
```python
# Python
filters = {"AND": [{"user_id": "alice"}, {"categories": {"contains": "health"}}]}
# Python - snake_case in filters
results = client.search("query", filters={"user_id": "alice"})
```
```typescript
// TypeScript -- same snake_case in filter objects!
const filters = { AND: [{ user_id: 'alice' }, { categories: { contains: 'health' } }] };
// TypeScript - snake_case in filters, camelCase for top-level params
const results = await client.search('query', { filters: { user_id: 'alice' }, topK: 20 });
```
+75 -69
View File
@@ -41,23 +41,18 @@ 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, { user_id: 'alice' });
await client.add(messages, { userId: 'alice' });
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `messages` | `Message[]` | Array of `{role, content}` objects |
| `options.user_id` | string | User identifier |
| `options.agent_id` | string | Agent identifier |
| `options.app_id` | string | Application identifier |
| `options.run_id` | string | Session identifier |
| `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.enable_graph` | boolean | Activate knowledge graph |
| `options.infer` | boolean | If false, store raw text (default: true) |
| `options.immutable` | boolean | Prevent future modification |
| `options.expiration_date` | string | Auto-expiry (`YYYY-MM-DD`) |
| `options.includes` | string | Preference filter for inclusion |
| `options.excludes` | string | Preference filter for exclusion |
**Returns:** `Promise<any>` -- list of events
@@ -66,7 +61,7 @@ await client.add(messages, { user_id: 'alice' });
Search memories by semantic similarity.
```typescript
const results = await client.search('dietary preferences', { user_id: 'alice' });
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);
}
@@ -75,17 +70,12 @@ for (const mem of results.results) {
| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Natural language search query |
| `options.user_id` | string | Filter by user |
| `options.agent_id` | string | Filter by agent |
| `options.filters` | object | V2 filter object (`AND`/`OR`/`NOT`) |
| `options.top_k` | number | Number of results (default: 10) |
| `options.rerank` | boolean | Enable semantic reranking |
| `options.threshold` | number | Minimum similarity (default: 0.3) |
| `options.keyword_search` | boolean | Enable keyword search |
| `options.enable_graph` | boolean | Include graph relations |
| `options.filter_memories` | boolean | Precision filtering |
| `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, ...}], relations: [...]}`
**Returns:** `Promise<SearchResult>` -- `{results: [{id, memory, score, ...}]}`
#### get(memoryId)
@@ -98,7 +88,7 @@ const memory = await client.get('ea925981-...');
Retrieve all memories. Requires at least one entity identifier in filters.
```typescript
const memories = await client.getAll({ user_id: 'alice' });
const memories = await client.getAll({ filters: { user_id: 'alice' } });
// With filters
const filtered = await client.getAll({
filters: { AND: [{ user_id: 'alice' }, { categories: { contains: 'health' } }] },
@@ -107,11 +97,9 @@ const filtered = await client.getAll({
| Parameter | Type | Description |
|-----------|------|-------------|
| `options.user_id` | string | Filter by user |
| `options.filters` | object | V2 filter object |
| `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.page_size` | number | Results per page |
| `options.enable_graph` | boolean | Include graph relations |
| `options.pageSize` | number | Results per page |
#### update(memoryId, data)
@@ -136,14 +124,14 @@ await client.delete('ea925981-...');
#### deleteAll(options?)
```typescript
await client.deleteAll({ user_id: 'alice' });
await client.deleteAll({ userId: 'alice' });
```
#### history(memoryId)
```typescript
const history = await client.history('ea925981-...');
// Returns: [{previous_value, new_value, action, timestamps}]
// Returns: [{previousValue, newValue, action, timestamps}]
```
---
@@ -179,8 +167,8 @@ const users = await client.users();
#### deleteUser(data) / deleteUsers(data)
```typescript
await client.deleteUser({ user_id: 'alice' }); // Single entity
await client.deleteUsers({ agent_id: 'bot-1' }); // Flexible
await client.deleteUser({ userId: 'alice' }); // Single entity
await client.deleteUsers({ agentId: 'bot-1' }); // Flexible
```
---
@@ -189,13 +177,12 @@ await client.deleteUsers({ agent_id: 'bot-1' }); // Flexible
```typescript
// Get project config
const config = await client.getProject({ fields: ['custom_categories'] });
const config = await client.getProject({ fields: ['customCategories'] });
// Update project settings
await client.updateProject({
custom_instructions: 'Extract dietary preferences and health info',
custom_categories: [{ health: 'Medical and dietary info' }],
enable_graph: true,
customInstructions: 'Extract dietary preferences and health info',
customCategories: [{ health: 'Medical and dietary info' }],
});
```
@@ -205,25 +192,25 @@ await client.updateProject({
```typescript
// List
const webhooks = await client.getWebhooks({ project_id: 'proj_123' });
const webhooks = await client.getWebhooks({ projectId: 'proj_123' });
// Create
const webhook = await client.createWebhook({
url: 'https://your-app.com/webhook',
name: 'Memory Logger',
project_id: 'proj_123',
event_types: ['memory_add', 'memory_update'],
projectId: 'proj_123',
eventTypes: ['memory_add', 'memory_update'],
});
// Update
await client.updateWebhook({
webhook_id: 'wh_123',
webhookId: 'wh_123',
name: 'Updated Logger',
url: 'https://new-url.com',
});
// Delete
await client.deleteWebhook({ webhook_id: 'wh_123' });
await client.deleteWebhook({ webhookId: 'wh_123' });
```
---
@@ -232,9 +219,9 @@ await client.deleteWebhook({ webhook_id: 'wh_123' });
```typescript
await client.feedback({
memory_id: 'mem-123',
memoryId: 'mem-123',
feedback: 'POSITIVE',
feedback_reason: 'Accurately captured preference',
feedbackReason: 'Accurately captured preference',
});
```
@@ -248,7 +235,7 @@ const exportReq = await client.createMemoryExport({
filters: { user_id: 'alice' },
});
const result = await client.getMemoryExport({ memory_export_id: exportReq.id });
const result = await client.getMemoryExport({ memoryExportId: exportReq.id });
```
---
@@ -259,14 +246,12 @@ Key interfaces from `mem0.types.ts`:
```typescript
interface Message { role: string; content: string; }
interface Memory { id: string; memory: string; user_id: string; categories: string[]; score?: number; /* ... */ }
interface MemoryOptions { user_id?: string; agent_id?: string; app_id?: string; run_id?: string; metadata?: object; /* ... */ }
interface SearchOptions { user_id?: string; filters?: object; top_k?: number; rerank?: boolean; threshold?: number; /* ... */ }
interface MemoryHistory { id: string; memory_id: string; previous_value: string; new_value: string; action: string; /* ... */ }
interface FeedbackPayload { memory_id: string; feedback: string; feedback_reason?: string; }
interface WebhookCreatePayload { url: string; name: string; project_id: string; event_types: string[]; }
enum OutputFormat { v1_0 = 'v1.0', v1_1 = 'v1.1' }
enum API_VERSION { v1 = 'v1', v2 = 'v2' }
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[]; }
```
---
@@ -296,7 +281,7 @@ const config = {
llm: {
provider: 'openai', // openai, groq, anthropic, google, ollama, lmstudio, mistral, azure
config: {
model: 'gpt-4o-mini',
model: 'gpt-5-mini',
apiKey: 'sk-xxx',
},
},
@@ -315,17 +300,8 @@ const config = {
port: 6333,
},
},
graphStore: { // Optional
provider: 'neo4j',
config: {
url: 'neo4j://localhost:7687',
username: 'neo4j',
password: 'password',
},
},
historyDbPath: 'history.db',
customPrompt: '...',
enableGraph: false,
customInstructions: '...',
disableHistory: false,
};
@@ -363,17 +339,14 @@ await m.add([
#### search(query, config)
```typescript
const results = await m.search('dietary preferences', { userId: 'alice', limit: 5 });
const results = await m.search('dietary preferences', { filters: { user_id: 'alice' }, topK: 5 });
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Search query |
| `config.userId` | string | Filter by user |
| `config.agentId` | string | Filter by agent |
| `config.runId` | string | Filter by run |
| `config.limit` | number | Max results (default: 100) |
| `config.filters` | object | Advanced filters |
| `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)
@@ -401,12 +374,45 @@ await m.reset();
| **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** | `snake_case` in options (`user_id`) | `camelCase` in config (`userId`) |
| **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 |
| **Graph store** | Platform-managed | Self-managed (Neo4j) |
| **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.
+53 -47
View File
@@ -36,7 +36,7 @@ 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", user_id="alice")
results = await client.search("query", filters={"user_id": "alice"})
```
Same methods as `MemoryClient`, all `async`/`await`. Supports async context manager.
@@ -65,25 +65,19 @@ client.add(messages, user_id="alice")
| `app_id` | str | None | Application identifier |
| `run_id` | str | None | Session/run identifier |
| `metadata` | dict | None | Custom key-value pairs |
| `enable_graph` | bool | None | Activate knowledge graph extraction |
| `infer` | bool | True | If False, store raw text without LLM inference |
| `immutable` | bool | None | If True, prevents future modification |
| `expiration_date` | str | None | Auto-expiry date (`YYYY-MM-DD`) |
| `includes` | str | None | Preference filter for inclusion |
| `excludes` | str | None | Preference filter for exclusion |
| `async_mode` | bool | True | If False, wait for processing to complete |
| `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|UPDATE|DELETE", "data": {"memory": "..."}}]`
**Returns:** `dict` -- list of events: `[{"id": "...", "event": "ADD", "data": {"memory": "..."}}]`
#### search(query, **kwargs)
Search memories by semantic similarity.
```python
results = client.search("dietary preferences", user_id="alice")
results = client.search("dietary preferences", filters={"user_id": "alice"})
for mem in results.get("results", []):
print(mem["memory"], mem["score"])
```
@@ -91,20 +85,14 @@ for mem in results.get("results", []):
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | str | required | Natural language search query |
| `user_id` | str | None | Filter by user |
| `agent_id` | str | None | Filter by agent |
| `app_id` | str | None | Filter by app |
| `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 |
| `filters` | dict | None | V2 filter object (`AND`/`OR`/`NOT`) |
| `rerank` | bool | None | Enable deep semantic reranking (+150-200ms) |
| `threshold` | float | 0.3 | Minimum similarity score |
| `keyword_search` | bool | None | Enable keyword-based search (+10ms) |
| `enable_graph` | bool | None | Include graph relations in results |
| `filter_memories` | bool | None | Precision filtering, removes low-relevance (+200-300ms) |
| `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, ...}], "relations": [...]}`
**Returns:** `dict` -- `{"results": [{id, memory, user_id, categories, score, created_at, ...}]}`
#### get(memory_id)
@@ -121,27 +109,23 @@ memory = client.get(memory_id="ea925981-...")
Retrieve all memories with optional filtering. Requires at least one entity identifier.
```python
memories = client.get_all(user_id="alice")
# With filters
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 |
|-----------|------|---------|-------------|
| `user_id` | str | None | Filter by user |
| `agent_id` | str | None | Filter by agent |
| `app_id` | str | None | Filter by app |
| `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 |
| `filters` | dict | None | V2 filter object |
| `enable_graph` | bool | None | Include graph relations |
**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. Cannot update immutable memories.
Update a memory's content, metadata, or timestamp. At least one parameter required.
```python
client.update("ea925981-...", text="Updated: vegan since 2024")
@@ -320,11 +304,10 @@ config = client.project.get(fields=["custom_categories", "custom_instructions"])
client.project.update(
custom_instructions="Extract dietary preferences and health info",
custom_categories=[{"health": "Medical and dietary info"}],
enable_graph=True,
multilingual=True,
)
# Create/delete project (requires org_id)
# Create/delete project
client.project.create(name="My Project", description="...")
client.project.delete()
@@ -362,7 +345,7 @@ config = {
"llm": {
"provider": "openai", # openai, groq, azure, ollama, lmstudio, google, anthropic, mistral
"config": {
"model": "gpt-4o-mini",
"model": "gpt-5-mini",
"api_key": "sk-xxx",
}
},
@@ -381,18 +364,8 @@ config = {
"port": 6333,
}
},
"graph_store": { # Optional
"provider": "neo4j",
"config": {
"url": "neo4j://localhost:7687",
"username": "neo4j",
"password": "password",
}
},
"history_db_path": "history.db", # SQLite path for change history
"custom_instructions": "...", # Custom LLM prompt for extraction
"custom_update_memory_prompt": "...", # Custom LLM prompt for updates
"enable_graph": False, # Enable graph memory
"custom_instructions": "...", # Custom LLM prompt for extraction
}
m = Memory.from_config(config)
@@ -403,7 +376,7 @@ m = Memory.from_config(config)
```python
with Memory(config) as m:
m.add("I prefer dark mode", user_id="alice")
results = m.search("preferences", user_id="alice")
results = m.search("preferences", filters={"user_id": "alice"})
# SQLite connections released automatically
```
@@ -425,12 +398,14 @@ At least one of `user_id`, `agent_id`, `run_id` required.
**Returns:** `{"results": [...], "relations": [...]}`
#### search(query, *, user_id, agent_id, run_id, limit=100, filters=None, threshold=None, rerank=True)
#### search(query, *, filters=None, top_k=20, threshold=0.1, rerank=False)
```python
results = m.search("dietary preferences", user_id="alice", limit=5)
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)
@@ -456,7 +431,7 @@ from mem0 import AsyncMemory
m = AsyncMemory(config)
await m.add("text", user_id="alice")
results = await m.search("query", user_id="alice")
results = await m.search("query", filters={"user_id": "alice"})
```
---
@@ -469,13 +444,44 @@ results = await m.search("query", user_id="alice")
| **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 |
| **Graph store** | Platform-managed | Self-managed (Neo4j) |
| **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.