App Sessions: The Core Unit of Meridian Activity Data

Learn what a session is, how Meridian detects session boundaries, and what every field in the app_sessions table means — with direct query examples.

A session is the fundamental unit of data in Meridian. Every time you switch from one app to another, Meridian closes the previous session and opens a new one. Each session captures everything that was visible on your screen during that focused block of time — the app you were in, the windows you had open, OCR text sampled from the display, clipboard activity, and more.

What makes a session

A session starts the moment an app comes into focus and ends the moment you switch away from it. Meridian detects these boundaries by watching for app-switch events in the screenpipe frame stream. If you stay in VS Code for 45 minutes without switching away, that becomes a single session lasting 45 minutes. If you switch to Slack and back, those are three separate sessions.

Active vs completed sessions

Meridian maintains exactly one active session at a time — the app currently in focus. The active session is stored in the active_session table and updated with each ETL tick. It has no ended_at value yet.

When you switch apps, Meridian closes the active session, writes it as a completed row to app_sessions, and opens a new active session for the app you switched to. Only completed sessions are classified by category and linked to tickets.

The session data model

The app_sessions table in ~/.meridian/meridian.db holds one row per completed session. Every field is documented below.

Field	Type	Description
app_name	TEXT	The name of the application that owned this session (e.g. code.visualstudio.com, Slack).
started_at	TEXT	ISO 8601 UTC timestamp when the session opened.
ended_at	TEXT	ISO 8601 UTC timestamp when the session closed.
duration_s	INTEGER	Wall-clock length of the session in seconds.
frame_count	INTEGER	Number of screenpipe frames captured during this session.
category	TEXT	AI-assigned activity category (e.g. coding, meeting, research).
confidence	REAL	Category confidence score from 0.0 to 1.0. Higher means the AI is more certain.
window_titles	JSON	Array of {window_name, count} objects — deduplicated window titles seen during the session, ordered by frequency.
ocr_samples	JSON	Array of up to 20 deduplicated OCR text samples extracted from screen frames.
elements_samples	JSON	Array of up to 20 deduplicated accessibility tree samples captured during the session.
audio_snippets	JSON	Array of transcribed audio captured during the session. Stored in the DB but excluded from MCP responses.
signals	JSON	Array of deduplicated clipboard copies and app-switch events detected during the session.
min_frame_id	INTEGER	The lowest screenpipe frame ID included in this session — links back to screenpipe’s raw data.
max_frame_id	INTEGER	The highest screenpipe frame ID included in this session.

audio_snippets are stored in meridian.db but intentionally excluded from all MCP tool responses. This keeps LLM context clean and reduces noise when AI tools query your session data. Audio content is still searchable via the search-sessions MCP tool.

Where sessions live

Meridian writes all completed sessions to its own SQLite database at ~/.meridian/meridian.db. This file is separate from screenpipe’s database and is owned entirely by Meridian. The min_frame_id and max_frame_id fields on each session let you trace back to the original screenpipe frames if you need them.

The database grows at roughly 10 MB per 9,000 frames of recorded activity. You can open it with any SQLite client.

Querying sessions directly

Use sqlite3 to query your sessions without going through the dashboard or MCP tools:

-- Today's sessions by app, ordered by total time
SELECT
  app_name,
  ROUND(SUM(duration_s) / 60.0, 1) AS minutes,
  COUNT(*) AS session_count
FROM app_sessions
WHERE started_at >= date('now')
  AND started_at < date('now', '+1 day')
GROUP BY app_name
ORDER BY minutes DESC
LIMIT 10;

# Run it from your terminal
sqlite3 ~/.meridian/meridian.db \
  "SELECT app_name, ROUND(SUM(duration_s)/60.0,1) AS min, COUNT(*) AS n
   FROM app_sessions
   WHERE started_at >= date('now')
   GROUP BY app_name ORDER BY min DESC LIMIT 10;"

The Meridian dashboard at http://localhost:3000 and the MCP server both read from this same database. Any SQL query you run against ~/.meridian/meridian.db reflects exactly what the dashboard shows.