| title | Memories |
|---|---|
| icon | brain |
| description | Create and retrieve memories via the Developer API |
Memory endpoints require a Developer API key with the corresponding scope: memories:read for reads and
memories:write for writes. Creating a key is self-service in Developer → API Keys, and creation
records the matching key grant when the key includes a memory scope.
Default memory reads also have a separate, server-owned account readiness gate. A valid, correctly scoped
key can therefore receive 403 while that account is not yet provisioned for Developer Memory API access.
Do not recreate the key in that case; retry after the account is enabled or contact Omi support if it remains
unavailable.
{
"detail": {
"enabled": false,
"code": "developer_memory_access_not_ready",
"message": "Developer Memory API access is not enabled for this account.",
"reason": "missing_rollout_state"
}
}code is the stable programmatic signal. reason provides a diagnostic for the current server-side gate and
must not be treated as a key or scope error.
Retrieve your memories with optional filtering | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `limit` | integer | 25 | Maximum number of memories to return | | `offset` | integer | 0 | Number of memories to skip | | `categories` | string | - | Comma-separated list (e.g., `"interesting,system"`) | ```bash curl -H "Authorization: Bearer $API_KEY" \ "https://api.omi.me/v1/dev/user/memories?limit=50&categories=interesting" ``` ```python import requests
response = requests.get(
"https://api.omi.me/v1/dev/user/memories",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"limit": 50, "categories": "interesting"}
)
memories = response.json()
```
Create a new memory | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | **Yes** | The memory content (1-500 characters) | | `category` | string | No | `interesting`, `system`, or `manual` (auto-categorizes if not provided) | | `visibility` | string | No | `public` or `private` (default: `private`) | | `tags` | array | No | List of tags | ```bash curl -X POST "https://api.omi.me/v1/dev/user/memories" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "User prefers dark mode in all applications", "category": "system", "tags": ["preferences", "ui"] }' ``` ```python import requests
response = requests.post(
"https://api.omi.me/v1/dev/user/memories",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"content": "User prefers dark mode in all applications",
"category": "system",
"tags": ["preferences", "ui"]
}
)
memory = response.json()
```
Create multiple memories in a single request (max 25) | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `memories` | array | **Yes** | List of memory objects (max 25) |
Each memory object accepts the same fields as the single create endpoint.
response = requests.post(
"https://api.omi.me/v1/dev/user/memories/batch",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"memories": [
{"content": "User prefers async communication over meetings", "category": "system"},
{"content": "User speaks fluent Japanese and French", "category": "interesting"}
]
}
)
result = response.json()
print(f"Created {result['created_count']} memories")
```
Update a memory's content or visibility | Parameter | Type | Description | |-----------|------|-------------| | `memory_id` | string | The ID of the memory to update | | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `content` | string | No | New content (1-500 characters) | | `visibility` | string | No | New visibility: `public` or `private` |
At least one field must be provided.
response = requests.patch(
"https://api.omi.me/v1/dev/user/memories/mem_xyz789",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"content": "User strongly prefers dark mode in all applications",
"visibility": "private"
}
)
memory = response.json()
```
Delete a memory permanently | Parameter | Type | Description | |-----------|------|-------------| | `memory_id` | string | The ID of the memory to delete | ```bash curl -X DELETE "https://api.omi.me/v1/dev/user/memories/mem_xyz789" \ -H "Authorization: Bearer $API_KEY" ``` ```python import requests
response = requests.delete(
"https://api.omi.me/v1/dev/user/memories/mem_xyz789",
headers={"Authorization": f"Bearer {API_KEY}"}
)
result = response.json()
if result["success"]:
print("Memory deleted successfully")
```
**Memories are timeless facts about the user** — preferences, relationships, personal details, and notable insights. They are NOT for notes, tasks, or time-sensitive information.
- Good memories: "User is vegetarian", "User's sister Sarah lives in Portland", "User prefers async communication"
- Bad memories: "Meeting on March 15th", "Call dentist tomorrow" (these are action items or conversations)
For notes, meeting summaries, or imported text content, use the Conversations API instead — it automatically extracts memories and action items.
Import known facts and preferences about the user:
```python import requestsAPI_KEY = "omi_dev_your_api_key"
# Facts about the user from another system
user_facts = [
{"content": "User is vegetarian", "category": "system"},
{"content": "User's dog is named Luna", "category": "interesting"},
{"content": "User works at Acme Corp as lead engineer", "category": "system"},
{"content": "User ran a marathon in under 4 hours", "category": "interesting"}
]
# Create batch
response = requests.post(
"https://api.omi.me/v1/dev/user/memories/batch",
headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
json={"memories": user_facts}
)
print(f"Added {response.json()['created_count']} facts about the user")
```
// Facts about the user from another system
const userFacts = [
{ content: "User is vegetarian", category: "system" },
{ content: "User's dog is named Luna", category: "interesting" },
{ content: "User works at Acme Corp as lead engineer", category: "system" },
{ content: "User ran a marathon in under 4 hours", category: "interesting" }
];
// Create batch
const response = await fetch(
"https://api.omi.me/v1/dev/user/memories/batch",
{
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ memories: userFacts })
}
);
const result = await response.json();
console.log(`Added ${result.created_count} facts about the user`);
```
Useful context for the AI: preferences, work details, relationships, logistical info. Example: "User prefers dark mode" Shareable, notable facts — things the user would excitedly tell someone at dinner. Example: "User climbed Mount Kilimanjaro"