Endpoints
POST Batch Create up to 25
Get Memories
GET /v1/dev/user/memories Retrieve your memories with optional filtering
Parameter Type Default Description limitinteger 25 Maximum number of memories to return offsetinteger 0 Number 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"
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 ();
[
{
"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
}
]
Field Type Description idstring Unique identifier contentstring The memory content categorystring interesting, system, or manualvisibilitystring public or privatetagsarray List of tags created_atdatetime When created updated_atdatetime When last updated manually_addedboolean Added via API or app reviewedboolean Has been reviewed editedboolean Has been edited
Create Memory
POST /v1/dev/user/memories Create a new memory
Parameter Type Required Description contentstring Yes The memory content (1-500 characters) categorystring No interesting, system, or manual (auto-categorizes if not provided)visibilitystring No public or private (default: private)tagsarray No List 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"]
}'
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 ();
{
"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)
Parameter Type Required Description memoriesarray Yes List 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"}
]
}'
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` );
{
"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
Parameter Type Description memory_idstring The ID of the memory to update
Parameter Type Required Description contentstring No New content (1-500 characters) visibilitystring No New 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"
}'
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 ();
{
"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
Parameter Type Description memory_idstring The ID of the memory to delete
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" );
}
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" )
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”