Documentation Index
Fetch the complete documentation index at: https://ritual-6a4ce4d6.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Context Understanding uses local watcher activity to group computer work into compact project/task workstreams, alongside habit logs, wearable data, phone usage, and location context.
The current path is structured and lightweight. Ritual focuses on activity signals and daily summaries instead of broad screen recording, OCR frame history, or “search everything I saw” memory.
Overview
Ritual’s context model is built around structured signals.
| Layer | Role |
|---|
| Watcher activity | Tracks local app and website usage over time |
| Workstreams | Groups computer time into project/task labels |
| Daily rollups | Summarizes app, domain, project, and task activity by day |
| Habit and health context | Adds manual logs, wearable data, phone usage, and location context |
What Ritual Uses
The watcher collects compact activity signals from your Mac.
| Signal | How it is used |
|---|
| Active app | Builds app usage totals and active computer-time segments |
| Website/domain | Builds website usage totals without needing full browsing history as the default |
| Window/title signals | Helps identify the current task or project when available |
| Safe artifact hints | Uses file, project, or workspace hints when apps expose them safely |
| Time ranges | Preserves start/end boundaries for app and work sessions |
| App/domain counts | Powers app and website rankings in Metrics |
| Project/task labels | Groups related computer activity into workstreams |
| Compact daily rollups | Keeps the long-term record small and useful |
What Ritual Avoids
The current context path is intentionally narrower than the older recorder/search design.
| Avoided as the primary path | Why |
|---|
| Full screen recording | Too heavy and unnecessary for most time/context questions |
| OCR frame history | Creates too much noisy text and sensitive raw context |
| Raw screen text as memory | Not needed for daily rollups and workstream grouping |
| Broad “search everything I saw” memory | Harder to control, explain, and keep lightweight |
Watcher
Ritual Watcher tracks app and website activity locally, then groups computer time into project/task workstreams and daily rollups.
What it captures
| Signal | Stored data |
|---|
| Active app | Bundle id, app name, process, and focused time |
| Window title | A task/project hint when available and allowed |
| Browser domain | Domain-level website activity |
| Session boundaries | App switches, idle periods, lock/unlock, sleep/wake |
| Daily rollups | App, website, computer-time, and workstream summaries |
Workstreams
Workstreams are compact labels for what your computer time was about. They are built from app usage, domains, titles, and safe project/file hints when available.
Examples:
| Raw activity | Workstream result |
|---|
| Cursor + project folder + terminal activity | Coding on a project |
| Chrome + docs/wiki domains + document titles | Research or writing |
| Figma + design file title | Design work |
| Calendar + meeting app activity | Meetings and planning |
Daily Rollups
Ritual turns raw activity segments into compact daily facts.
| Rollup | Used for |
|---|
| Computer Time | Total active computer usage |
| App rankings | Which apps took the most time |
| Website rankings | Which domains took the most time |
| Project/task workstreams | What the work was about |
| Date-range summaries | Daily, weekly, monthly, and all-time views |
Context Sources
Computer activity is only one part of Ritual’s context model.
| Source | What it contributes |
|---|
| Manual habit logs | What you explicitly logged |
| Wearables and health signals | Sleep, workouts, heart rate, steps, recovery, and related metrics |
| iPhone Time | Foreground iPhone app usage when Apple Biome data is available |
| Location context | Optional location enrichment for habits and activity |
| Watcher workstreams | Computer-time context grouped into tasks and projects |
What This Enables
The current model is designed for practical questions.
| Question | Primary backing signal |
|---|
| ”Where did my computer time go today?” | Watcher rollups and workstreams |
| ”What apps did I use most this week?” | App usage rollups |
| ”What websites took the most time?” | Domain usage rollups |
| ”What did I work on yesterday?” | Project/task workstreams |
| ”How did sleep relate to work or phone usage?” | Habit facts plus watcher and iPhone rollups |
| ”Summarize my day” | Habit logs, health data, activity rollups, and context sources |
Privacy And Control
The context system is meant to stay understandable and controllable.
| Control | Effect |
|---|
| Local-first watcher data | Raw computer activity starts on the Mac |
| App exclusions | Stop tracking for selected apps |
| Domain-focused browser usage | Website activity can be summarized without full-page capture |
| Compact rollups | Long-term storage favors daily facts over raw screen content |
| Workstream labels | Context is summarized as projects/tasks instead of broad raw memory |
Health Signals
Ritual surfaces diagnostics so context quality is visible.
| Signal | Meaning |
|---|
| Watcher running | The local activity collector is active |
| Recent activity | App/website segments are being captured recently |
| Rollup freshness | Daily facts have been rebuilt from recent activity |
| Sync status | Local activity has reached the backend when needed |
| Degraded mode | The app can still show partial summaries if one source is unavailable |
