Memories - Docs

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 — 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.

​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

​Pagination and search coverage

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

Pagination and search coverage