omi/docs/doc/developer/mcp/tools.mdx at main · ghzhost/omi

title	Tools Reference
icon	wrench
description	Complete reference for all Omi MCP tools

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.

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`

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 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 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 a memory by ID.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `memory_id` | string | Yes | ID of the memory to delete |

**Returns:** `{ "success": true }`

Conversation Tools

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.

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"
```

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.

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

FilesExpand file tree

tools.mdx

Latest commit

History