Tools Reference

Memory Tools

The hosted server returns only the tools allowed by the OAuth grant or MCP key. A local mcp-server-omi stdio process currently exposes the eight memory and conversation tools in the first two sections below; the additional tools are hosted-server tools.

get_memories

Retrieve a list of user memories with optional filtering.Parameters:

Name	Type	Required	Description
`categories`	array	No	Categories to filter by
`limit`	number	No	Maximum number of memories (default: 100)
`offset`	number	No	Offset for pagination (default: 0)
`sort`	string	No	`scoring_desc`, `created_desc`, `updated_desc`, or `manual_first`
`reviewed`	boolean	No	Filter by reviewed state
`manually_added`	boolean	No	Filter by manually-added state
`updated_after`	string	No	Only return memories updated after this ISO 8601 timestamp
`include_activity`	boolean	No	Include focus/screen/activity memories, which are excluded by default
`include_sensitive`	boolean	No	Include memories above standard data protection, default `true` for compatibility

Returns: { "memories": [...], "returned_count": 25, "has_more": true, "offset": 0, "limit": 25, "sort": "created_desc" }The response may also include scan diagnostics such as scanned_count and scan_truncated.Example:

"Search my memories" → get_memories with no filters
"What do you know about my hobbies?" → get_memories with categories: ["hobbies"]

Memory categories: interesting, core, hobbies, lifestyle, interests, habits, work, skills, learnings, other

search_memories

Semantic search across memories. Returns results ranked by relevance using vector similarity.Parameters:

Name	Type	Required	Description
`query`	string	Yes	Natural language search query
`limit`	number	No	Maximum number of results (default: 10)

Returns: { "memories": [{ ..., "relevance_score": 0.92 }, ...] }Each result includes a relevance_score (0.0 to 1.0) indicating how well it matches the query.Example:

"What do I know about machine learning?" → search_memories with query: "machine learning"
"Find memories about my morning routine" → search_memories with query: "morning routine"

create_memory

Create a new memory. Category is auto-detected if not provided.Parameters:

Name	Type	Required	Description
`content`	string	Yes	Content of the memory
`category`	string	No	Category (auto-detected if omitted)

Returns: { "success": true, "memory": { ... } }

edit_memory

Edit an existing memory’s content.Parameters:

Name	Type	Required	Description
`memory_id`	string	Yes	ID of the memory to edit
`content`	string	Yes	New content for the memory

Returns: { "success": true }

delete_memory

Delete a memory by ID.Parameters:

Name	Type	Required	Description
`memory_id`	string	Yes	ID of the memory to delete

Returns: { "success": true }

Conversation Tools

get_conversations

Retrieve a list of conversations with optional date and category filtering.Parameters:

Name	Type	Required	Description
`start_date`	string	No	Filter after this date (YYYY-MM-DD)
`end_date`	string	No	Filter before this date (YYYY-MM-DD)
`categories`	array	No	Categories to filter by
`limit`	number	No	Maximum number of conversations (default: 20)
`offset`	number	No	Offset for pagination (default: 0)

Returns: { "conversations": [...] } — metadata only. Use get_conversation_by_id for full transcripts.Example:

"What did I talk about last week?" → get_conversations with date range
"Show my work conversations" → get_conversations with categories: ["work"]

Conversation categories: personal, education, health, finance, technology, business, work, social, travel, entertainment, sports, family, and more.

search_conversations

Semantic search across conversations. Returns results ranked by relevance using vector similarity.Parameters:

Name	Type	Required	Description
`query`	string	Yes	Natural language search query
`start_date`	string	No	Filter after this date (YYYY-MM-DD)
`end_date`	string	No	Filter before this date (YYYY-MM-DD)
`limit`	number	No	Maximum number of results (default: 10)

Returns: { "conversations": [...] } — ranked by relevance to the query.Example:

"When did I discuss the product launch?" → search_conversations with query: "product launch"
"Find conversations about hiring from January" → search_conversations with query: "hiring", start_date: "2026-01-01", end_date: "2026-01-31"

get_conversation_by_id

Retrieve a single conversation by ID, including the full transcript with speaker segments.Parameters:

Name	Type	Required	Description
`conversation_id`	string	Yes	The ID of the conversation

Returns: Full conversation object with transcript segments, timestamps, structured summary, and metadata.

Profile, Imported Data, and Activity Tools

Tool	Parameters	Description
`get_user_profile`	None	Return Omi’s cached high-level user summary, if generated
`get_x_posts`	`kind?` (`tweet` or `bookmark`), `limit?` (default 50)	List imported X posts and bookmarks, newest first
`search_x_posts`	`query`, `limit?` (default 10)	Semantic search over imported X posts and bookmarks
`get_goals`	`include_inactive?` (default false)	List goals, active by default
`get_chat_messages`	`limit?` (default 50), `offset?`	List recent Omi chat messages, newest first
`get_people`	None	List recognized people with speaker samples
`get_screen_activity`	`start_date?`, `end_date?`, `app?`, `summary?`, `limit?`	List synced screen activity or return a per-app summary
`get_daily_summaries`	`start_date?`, `end_date?`, `limit?` (default 30), `offset?`	List Omi’s daily summaries, newest first

Dates use YYYY-MM-DD. get_screen_activity defaults to 200 raw rows; limit is ignored when summary is true. Screen summaries count synced observations, not elapsed app usage. OCR gating, frame deduplication, privacy exclusions, and sync compaction mean a row cannot be converted to a fixed number of seconds or treated as proof of the user’s intent. The same summary contract serves hosted MCP, REST MCP, and GET /v1/screen-activity/summary:

total_screenshots and per-app count count only the summarized rows.
coverage.source is synced_screen_activity; coverage.row_limit is 5000.
coverage.truncated is true only when a lookahead row proves more matching rows exist. Only the earliest 5000 rows contribute to the summary. Narrow the date range to inspect later observations.
coverage.first_observed_at and last_observed_at bound the summarized rows, in UTC (YYYY-MM-DD HH:MM:SS.mmm), and are null for an empty result. They do not establish continuous activity or the device’s latest capture time.
coverage.capture_completeness is unknown, even when truncated is false: the cloud query cannot attest to device capture status, excluded activity, retention, or pending sync. An empty result does not prove inactivity.

Window titles are samples, not a ranking by dwell time. Summaries remain derived views of screen evidence; they do not create or promote semantic memories.

Action Item Tools

Tool	Required parameters	Optional parameters	Description
`get_action_items`	None	`completed`, `due_start_date`, `due_end_date`, `limit` (default 100), `offset`	List tasks and to-dos
`search_action_items`	`query`	`limit` (default 10)	Semantic search over tasks
`create_action_item`	`description`	`due_at`, `completed` (default false)	Create a task; identical retries do not duplicate it
`complete_action_item`	`action_item_id`	`completed` (default true)	Complete or reopen a task
`update_action_item`	`action_item_id`	`description`, `due_at`	Update only the supplied fields
`delete_action_item`	`action_item_id`	None	Delete a task

Due dates accept YYYY-MM-DD or an ISO 8601 date-time where noted by the client schema.

Error Handling

All tools return JSON-RPC 2.0 errors when something goes wrong:

Code	Meaning
`-32602`	Invalid parameters (bad date format, unknown category)
`-32001`	Resource not found (memory or conversation doesn’t exist)
`-32002`	Locked content (paid plan required)
`-32003`	The OAuth grant is missing the tool’s required scope
`-32009`	Authorization or serving policy denied the operation
`-32601`	Unknown tool name

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Memory not found"
  }
}

Locked Content

Memories and conversations behind the paid plan are handled gracefully:

Memories: Content is truncated to 70 characters with ...
Conversations: Action items and events are hidden from the structured data
Direct access: Returns error -32002 with a clear message

Getting Started

Reference

Resources

Tools Reference

Memory Tools

Conversation Tools

Profile, Imported Data, and Activity Tools

Action Item Tools

Error Handling

Locked Content

​Memory Tools

​Conversation Tools

​Profile, Imported Data, and Activity Tools

​Action Item Tools

​Error Handling

​Locked Content

Memory Tools

Conversation Tools

Profile, Imported Data, and Activity Tools

Action Item Tools

Error Handling

Locked Content