Skip to main content

Endpoints

GET

Retrieve memories

POST

Create memory

PATCH

Update memory

DELETE

Delete memory

POST Batch

Create up to 25

Get Memories

GET /v1/dev/user/memories

Retrieve your memories with optional filtering

Query Parameters

ParameterTypeDefaultDescription
limitinteger25Maximum number of memories to return
offsetinteger0Number of memories to skip
categoriesstring-Comma-separated list (e.g., "interesting,system")
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.omi.me/v1/dev/user/memories?limit=50&categories=interesting"

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
  }
]
FieldTypeDescription
idstringUnique identifier
contentstringThe memory content
categorystringinteresting, system, or manual
visibilitystringpublic or private
tagsarrayList of tags
created_atdatetimeWhen created
updated_atdatetimeWhen last updated
manually_addedbooleanAdded via API or app
reviewedbooleanHas been reviewed
editedbooleanHas been edited

Create Memory

POST /v1/dev/user/memories

Create a new memory

Request Body

ParameterTypeRequiredDescription
contentstringYesThe memory content (1-500 characters)
categorystringNointeresting, system, or manual (auto-categorizes if not provided)
visibilitystringNopublic or private (default: private)
tagsarrayNoList of tags
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"]
  }'

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

ParameterTypeRequiredDescription
memoriesarrayYesList of memory objects (max 25)
Each memory object accepts the same fields as the single create endpoint.
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"}
    ]
  }'

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

ParameterTypeDescription
memory_idstringThe ID of the memory to update

Request Body

ParameterTypeRequiredDescription
contentstringNoNew content (1-500 characters)
visibilitystringNoNew visibility: public or private
At least one field must be provided.
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"
  }'

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

ParameterTypeDescription
memory_idstringThe ID of the memory to delete
curl -X DELETE "https://api.omi.me/v1/dev/user/memories/mem_xyz789" \
  -H "Authorization: Bearer $API_KEY"

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

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”