Memories

Endpoints

GET

Retrieve memories

POST

Create memory

PATCH

Update memory

DELETE

Delete memory

POST Batch

Create up to 25

Access and availability

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.

Get Memories

GET /v1/dev/user/memories

Retrieve your memories with optional filtering

Query Parameters

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"`)

cURL
Python
JavaScript

curl -H "Authorization: Bearer $API_KEY" \
  "https://api.omi.me/v1/dev/user/memories?limit=50&categories=interesting"

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()

const response = await fetch(
  "https://api.omi.me/v1/dev/user/memories?limit=50&categories=interesting",
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const memories = await response.json();

Response Example

[
  {
    "id": "mem_789ghi",
    "content": "User is building an AI fitness app with personal trainer",
    "category": "interesting",
    "visibility": "private",
    "tags": [],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "manually_added": false,
    "scoring": "01_999_1705315800",
    "reviewed": false,
    "user_review": null,
    "edited": false
  }
]

Response Fields

Field	Type	Description
`id`	string	Unique identifier
`content`	string	The memory content
`category`	string	`interesting`, `system`, or `manual`
`visibility`	string	`public` or `private`
`tags`	array	List of tags
`created_at`	datetime	When created
`updated_at`	datetime	When last updated
`manually_added`	boolean	Added via API or app
`reviewed`	boolean	Has been reviewed
`edited`	boolean	Has been edited

Create Memory

POST /v1/dev/user/memories

Create a new memory

Request Body

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

cURL
Python
JavaScript

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"]
  }'

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()

const response = await fetch(
  "https://api.omi.me/v1/dev/user/memories",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      content: "User prefers dark mode in all applications",
      category: "system",
      tags: ["preferences", "ui"]
    })
  }
);
const memory = await response.json();

Response Example

{
  "id": "mem_xyz789",
  "content": "User prefers dark mode in all applications",
  "category": "system",
  "visibility": "private",
  "tags": ["preferences", "ui"],
  "created_at": "2025-12-06T10:35:00Z",
  "updated_at": "2025-12-06T10:35:00Z",
  "manually_added": true,
  "scoring": "01_999_1733482500"
}

Create Memories (Batch)

POST /v1/dev/user/memories/batch

Create multiple memories in a single request (max 25)

Request Body

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.

cURL
Python
JavaScript

curl -X POST "https://api.omi.me/v1/dev/user/memories/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {"content": "User prefers async communication over meetings", "category": "system"},
      {"content": "User speaks fluent Japanese and French", "category": "interesting"}
    ]
  }'

import requests

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")

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: [
        { content: "User prefers async communication over meetings", category: "system" },
        { content: "User speaks fluent Japanese and French", category: "interesting" }
      ]
    })
  }
);
const result = await response.json();
console.log(`Created ${result.created_count} memories`);

Response Example

{
  "memories": [
    { "id": "mem_001", "content": "User prefers async communication over meetings", "category": "system", ... },
    { "id": "mem_002", "content": "User speaks fluent Japanese and French", "category": "interesting", ... }
  ],
  "created_count": 2
}

Update Memory

PATCH /v1/dev/user/memories/{memory_id}

Update a memory’s content or visibility

Path Parameters

Parameter	Type	Description
`memory_id`	string	The ID of the memory to update

Request Body

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.

cURL
Python
JavaScript

curl -X PATCH "https://api.omi.me/v1/dev/user/memories/mem_xyz789" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User strongly prefers dark mode in all applications",
    "visibility": "private"
  }'

import requests

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()

const response = await fetch(
  "https://api.omi.me/v1/dev/user/memories/mem_xyz789",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      content: "User strongly prefers dark mode in all applications",
      visibility: "private"
    })
  }
);
const memory = await response.json();

Response Example

{
  "id": "mem_xyz789",
  "content": "User strongly prefers dark mode in all applications",
  "category": "system",
  "visibility": "private",
  "tags": ["preferences", "ui"],
  "created_at": "2025-12-06T10:35:00Z",
  "updated_at": "2025-12-25T14:00:00Z",
  "manually_added": true,
  "edited": true
}

Delete Memory

DELETE /v1/dev/user/memories/{memory_id}

Delete a memory permanently

Path Parameters

Parameter	Type	Description
`memory_id`	string	The ID of the memory to delete

cURL
Python
JavaScript

curl -X DELETE "https://api.omi.me/v1/dev/user/memories/mem_xyz789" \
  -H "Authorization: Bearer $API_KEY"

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")

const response = await fetch(
  "https://api.omi.me/v1/dev/user/memories/mem_xyz789",
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${API_KEY}` }
  }
);
const result = await response.json();
if (result.success) {
  console.log("Memory deleted successfully");
}

Response Example

{
  "success": true
}

This action is permanent. Deleted memories cannot be recovered.

What Are Memories?

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.

Use Case: Store User Preferences

Import known facts and preferences about the user:

Python
JavaScript

import requests

API_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")

const API_KEY = process.env.OMI_API_KEY;

// 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`);

Memory Categories Explained

system

Useful context for the AI: preferences, work details, relationships, logistical info. Example: “User prefers dark mode”

interesting

Shareable, notable facts — things the user would excitedly tell someone at dinner. Example: “User climbed Mount Kilimanjaro”

Overview

Conversations

Folders

Action Items

Authentication

API Keys

Action Items

Conversations

Folders

Goals

Memories

developer

Memories

Endpoints

GET

POST

PATCH

DELETE

POST Batch

Access and availability

Get Memories

GET /v1/dev/user/memories

Create Memory

POST /v1/dev/user/memories

Create Memories (Batch)

POST /v1/dev/user/memories/batch

Update Memory

PATCH /v1/dev/user/memories/{memory_id}

Delete Memory

DELETE /v1/dev/user/memories/{memory_id}

What Are Memories?

Use Case: Store User Preferences

Memory Categories Explained

system

interesting

​Endpoints

GET

POST

PATCH

DELETE

POST Batch

​Access and availability

​Get Memories

GET /v1/dev/user/memories

​Create Memory

POST /v1/dev/user/memories

​Create Memories (Batch)

POST /v1/dev/user/memories/batch

​Update Memory

PATCH /v1/dev/user/memories/{memory_id}

​Delete Memory

DELETE /v1/dev/user/memories/{memory_id}

​What Are Memories?

​Use Case: Store User Preferences

​Memory Categories Explained

system

interesting

Endpoints

Access and availability

Get Memories

Create Memory

Create Memories (Batch)

Update Memory

Delete Memory

What Are Memories?

Use Case: Store User Preferences

Memory Categories Explained