~/.meridian/meridian.db as a read-only snapshot on each tool call, so the data is always at most one poll interval (default 60 seconds) stale. No data ever leaves your machine.
audio_snippets are stored in the database but intentionally excluded from all MCP tool responses to reduce noise in LLM context. Audio transcriptions from screenpipe can be noisy and prone to hallucinations. They remain searchable via search-sessions, which performs a LIKE match against the column.Session Browsing
get-sessions
List completed app sessions for a given date, with pagination. Each result includes the app name, time range, duration, frame count, and the top window titles seen during the session. Example questions- “What apps did I use today?”
- “How long was I in VS Code this morning?”
- “What was I working on yesterday?”
Local date in
YYYY-MM-DD format. Defaults to today.Filter by exact app name, e.g.
code.visualstudio.com. Case-sensitive.Page number (1-based). Use in combination with
page_size for large days.Results per page. Maximum 50.
get-timeline
Returns the full day timeline — app sessions ordered chronologically, interleaved with user-idle and system-sleep gaps. Use this when you want a narrative walk-through of the day rather than a flat list of apps. Example questions- “Walk me through my day.”
- “What was I doing at 3 pm?”
- “How many breaks did I take today?”
Local date in
YYYY-MM-DD format. Defaults to today.get-stats
Returns daily productivity statistics: total focus time, idle time, away (system-sleep) time, session count, and the top 8 apps by duration. Example questions- “How productive was I today?”
- “What app did I spend the most time in this week?”
Local date in
YYYY-MM-DD format. Defaults to today.get-active-session
Returns the currently open app session — the application in focus right now according to the most recent daemon poll. Returnsnull if the daemon has not run recently or the computer is idle.
Example questions
- “What am I doing right now?”
- “What app is currently active?”
get-apps
Returns all-time app usage statistics: total time, session count, average session length, and the date the app was last seen. Useful for understanding long-term habits rather than a single day. Example questions- “Which apps do I use most overall?”
- “When did I last use Slack?”
Maximum number of apps to return. Maximum 50.
get-recent-sessions
Returns sessions from the last N hours using a sliding time window, with any linked Jira task shown alongside each session. Unlikeget-sessions (which is calendar-date based), this tool is anchored to the current moment.
Example questions
- “What did I do in the last 2 hours?”
- “What was I working on since lunch?”
- “Give me a quick summary of recent activity.”
Look-back window in hours. Maximum 48.
Filter by exact app name. Case-sensitive.
Maximum sessions to return. Maximum 50.
get-session-detail
Returns the full detail for a single session by ID: all window titles with occurrence counts, accessibility element samples, signals (clipboard copies and app-switch events), and the full OCR screen content. Use this afterget-sessions or search-sessions when you need the complete content of a specific session.
Example questions
- “Show me everything that was on screen during session #42.”
- “What exact files did I have open in that VS Code session?”
Session ID from a previous
get-sessions or search-sessions result.Search
search-sessions
Performs a case-insensitive partial-text search across window titles, OCR screen text, and audio transcriptions. Use this when you know what you were looking at but not which ticket or app it maps to. Example questions- “When did I work on the Stripe integration?”
- “Find sessions where I was in a meeting.”
- “Which sessions mention authentication?”
Text to search for. Matched case-insensitively across window titles, OCR text, and audio transcriptions.
Limit the search to a specific date (
YYYY-MM-DD). Omit to search all history.Filter results by exact app name. Case-sensitive.
Maximum results to return. Maximum 50.
Task-Linked Tools
These tools require the AI tagger pipeline to have run and linked sessions to ticket keys. They use semantic and rule-based classification, not just text search, so they are more accurate thansearch-sessions when you know the ticket key.
get-task-sessions
Returns all sessions linked to a specific Jira task key by the tagger pipeline. Optionally filter by an exact time window or a sliding hour look-back. Setinclude_content=true to also return OCR and audio text for each session.
Example questions
- “What did I do on KAN-108 today?”
- “Show all work on KAN-108 in the last 4 hours.”
- “How long have I spent on this ticket?”
- “What was I actually doing on this task?”
Jira task key, e.g.
KAN-108.Exact window start as ISO 8601 UTC, e.g.
2026-05-13T09:00:00Z. Takes priority over since_hours and date.Exact window end as ISO 8601 UTC, e.g.
2026-05-13T13:00:00Z. Used together with from_time.Return sessions from the last N hours (maximum 48). Overrides
date when set.Limit to a specific date (
YYYY-MM-DD). Defaults to today if no other time parameter is set.When
true, each session in the response includes its OCR and audio text (up to 1,500 characters per session).get-task-breakdown
Shows total time spent grouped by linked Jira task for a given date or time window. Each row includes the task title, status, URL, session count, and percentage of total focus time. Ideal for standups and Jira progress updates. Example questions- “How much time per ticket today?”
- “Give me a work breakdown for today.”
- “How was my time split across Jira tickets this week?”
Exact window start as ISO 8601 UTC. Takes priority over
since_hours and date.Exact window end as ISO 8601 UTC. Used together with
from_time.Date (
YYYY-MM-DD). Defaults to today. Ignored if from_time or since_hours is set.Look-back window in hours (maximum 168 = 1 week). Overrides
date when set.get-active-task
Returns the Jira ticket you are most likely working on right now. The tool checks the tagger’s inferred context first, then falls back to the most recently linked completed session for the same app. It also reports elapsed time, task status, and confidence score. Example questions- “What Jira ticket am I working on right now?”
- “What is my current task?”
- “What should I log time against?”
Health
health-check
Verifies that the Meridian daemon is running and the database is accessible. Returns the last ETL run status, cursor position (the last screenpipe frame ID processed), and total session count. Example questions- “Is Meridian running?”
- “When did the daemon last process new frames?”
Tool Selection Quick Reference
| Question | Recommended Tool |
|---|---|
| ”What did I do today?” | get-timeline |
| ”How productive was I?” | get-stats |
| ”Which apps did I use?” | get-sessions |
| ”What am I doing right now?” | get-active-session |
| ”What Jira ticket am I on?” | get-active-task |
| ”What did I do in the last 2 hours?” | get-recent-sessions |
| ”Time per ticket today?” | get-task-breakdown |
| ”All sessions for KAN-108” | get-task-sessions |
| ”When did I work on X?” | search-sessions |
| ”Full content of session #N” | get-session-detail |
| ”All-time app usage” | get-apps |
| ”Is the daemon healthy?” | health-check |