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

Duplicates and retries

A memory is identified by its text. Sending text the user already has returns that memory unchanged, with the same id, so a create is safe to retry without any extra header.

Request	Result
Text the user does not have yet	A new memory
Text the user already has	`200` with the existing memory; nothing new is stored
Same text with different `category`, `visibility`, or `tags`	`200` with the existing memory as stored; the new fields are not applied
Same text after the memory was deleted	A new memory with a new `id`

Matching ignores leading and trailing whitespace and is case-sensitive. To change a memory you already created, use Update Memory with its id.

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.Items follow the same duplicate rule: text the user already has returns the existing memory at that position, so retrying a batch never stores anything twice. created_count is the number of memories returned, including existing ones.

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. They cover 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”

Pagination and search coverage

List responses remain arrays. limit is clamped to 1–1000. Read X-Omi-Effective-Limit, X-Omi-Has-More, and X-Omi-Next-Offset for continuation. X-Omi-List-Truncated: true signals that the read budget ran out. An empty truncated page cannot guarantee progress; narrow the category filter or reduce the page size. Unknown list parameters are ignored and counted in X-Omi-Ignored-Query-Params, except query, which returns 400; use the search route. GET /v1/dev/user/memories/search?query=budget&limit=10 returns {memories, effective_limit, search_coverage, message} using the same eligible memory search as MCP. Limit is 1–20. It requires memories:read, the persisted app/key memory grant, and account readiness. Empty indexed results do not prove absence: inspect the memory list for unindexed content. Eligibility and privacy rules apply to both paths; archive is excluded by default. The existing /v1/dev/user/memories/vector/search remains available and reports effective_limit (at most 20) plus coverage and an empty-result message. The compatibility list has a 5000-item offset + limit window. Requests beyond it return 413. A full page ending exactly at that boundary reports truncated coverage without a next offset; it cannot certify that the account ends there.

Apps

Developer API

MCP

CLI

SDKs

Third-party wearables

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