{"id":47912906,"url":"https://github.com/hkuds/catchme","last_synced_at":"2026-04-05T06:00:49.607Z","repository":{"id":347946682,"uuid":"1195795222","full_name":"HKUDS/CatchMe","owner":"HKUDS","description":"\"CatchMe: Make Your AI Agents Truly Personal\"","archived":false,"fork":false,"pushed_at":"2026-04-01T03:34:09.000Z","size":18699,"stargazers_count":279,"open_issues_count":1,"forks_count":28,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-04T05:34:17.907Z","etag":null,"topics":["ai-agent","clawdbot-plugin","llm","recall-ai","retrieval-systems","screen-recorder"],"latest_commit_sha":null,"homepage":"https://hkuds.github.io/CatchMe/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HKUDS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T04:21:59.000Z","updated_at":"2026-04-03T20:04:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"a74bde1a-049d-4698-ab54-4aa2528d3639","html_url":"https://github.com/HKUDS/CatchMe","commit_stats":null,"previous_names":["hkuds/catchme"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/HKUDS/CatchMe","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FCatchMe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FCatchMe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FCatchMe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FCatchMe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HKUDS","download_url":"https://codeload.github.com/HKUDS/CatchMe/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUDS%2FCatchMe/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31426193,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","clawdbot-plugin","llm","recall-ai","retrieval-systems","screen-recorder"],"created_at":"2026-04-04T05:24:45.962Z","updated_at":"2026-04-05T06:00:49.577Z","avatar_url":"https://github.com/HKUDS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"right\"\u003e\n  \u003ca href=\"assets/readme/README_zh.md\"\u003e中文\u003c/a\u003e · \u003ca href=\"assets/readme/README_ja.md\"\u003e日本語\u003c/a\u003e · \u003ca href=\"assets/readme/README_es.md\"\u003eEspañol\u003c/a\u003e · \u003cb\u003eEnglish\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/catchme-logo.png\" width=\"360\" alt=\"CatchMe Logo\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCatchMe: Make Your AI Agents Truly Personal\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eCapture Your Entire Digital Footprint: Lightweight \u0026 Vectorless \u0026 Powerful.\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue?style=flat\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-%E2%89%A53.11-3776AB?style=flat\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey?style=flat\" alt=\"Platform\"\u003e\n  \u003ca href=\"https://hkuds.github.io/CatchMe\"\u003e\u003cimg src=\"https://img.shields.io/badge/Blog-online-orange?style=flat\" alt=\"Blog\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Report-coming%20soon-lightgrey?style=flat\" alt=\"Report\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"./COMMUNICATION.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/Feishu-Group-E9DBFC?style=flat-square\u0026logo=feishu\u0026logoColor=white\" alt=\"Feishu\"\u003e\u003c/a\u003e\n  \u003ca href=\"./COMMUNICATION.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/WeChat-Group-C5EAB4?style=flat-square\u0026logo=wechat\u0026logoColor=white\" alt=\"WeChat\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/2vDYc2w5\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join-7289DA?style=flat-square\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-key-features\"\u003eFeatures\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#%EF%B8%8F-how-it-works\"\u003eHow It Works\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#-llm-configuration\"\u003eLLM Config\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#-get-started\"\u003eGet Started\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#-cost--efficiency\"\u003eCost\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#-community\"\u003eCommunity\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003ci\u003e「 \u003cb\u003eJust do your thing. CatchMe captures everything else — stored locally to ensure privacy and security. \u003c/b\u003e 」\u003c/i\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/terminal_demo.svg\" alt=\"CatchMe Terminal Demo\"/\u003e\n\u003c/p\u003e\n\n**🦞 Makes Your Agents Truly Personal**. CatchMe ships as an agent-compatible skill for CLI agents (OpenClaw, NanoBot, Claude, Cursor, etc.). Run CatchMe independently. Your agents query memories via CLI commands only.\n##\n\n\n## 🎯 Enrich Your Personal Digital Context\n\n\u003ctable width=\"100%\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cimg src=\"assets/usecase_coding.png\" height=\"150\" alt=\"Coding\"/\u003e\u003cbr\u003e\n      \u003ch3\u003e💻 Personal Coding Assistant\u003c/h3\u003e\n      \u003cb\u003e\u003ci\u003e\"What was I coding in Claude Code today?\"\u003c/i\u003e\u003c/b\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cdiv align=\"left\"\u003e\n        • Code session replay\u003cbr\u003e\n        • Recall your edited files\u003cbr\u003e\n        • Trace what you typed\n      \u003c/div\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cimg src=\"assets/usecase_research.png\" height=\"150\" alt=\"Research\"/\u003e\u003cbr\u003e\n      \u003ch3\u003e🔍 Personal Deep Research\u003c/h3\u003e\n      \u003cb\u003e\u003ci\u003e\"What was I reading about AI yesterday?\"\u003c/i\u003e\u003c/b\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cdiv align=\"left\"\u003e\n        • Web/PDF viewed\u003cbr\u003e\n        • Search queries typed\u003cbr\u003e\n        • Reading info tracked\n      \u003c/div\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cimg src=\"assets/usecase_files.png\" height=\"150\" alt=\"Files\"/\u003e\u003cbr\u003e\n      \u003ch3\u003e📁 Personal Files Manager\u003c/h3\u003e\n      \u003cb\u003e\u003ci\u003e\"Which files did I change today?\"\u003c/i\u003e\u003c/b\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cdiv align=\"left\"\u003e\n        • File changes tracked\u003cbr\u003e\n        • Docs accessed\u003cbr\u003e\n        • Edits reviewed\n      \u003c/div\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\n      \u003cimg src=\"assets/usecase_digital_life.png\" height=\"150\" alt=\"Digital Life\"/\u003e\u003cbr\u003e\n      \u003ch3\u003e🧩 Digital Life Overview\u003c/h3\u003e\n      \u003cb\u003e\u003ci\u003e\"How did I spend my afternoon?\"\u003c/i\u003e\u003c/b\u003e\u003cbr\u003e\u003cbr\u003e\n      \u003cdiv align=\"left\"\u003e\n        • App usage tracked\u003cbr\u003e\n        • Workflows replayed\u003cbr\u003e\n        • Activities recalled\n      \u003c/div\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## ✨ Key Features\n\n### 📹 Always-On Event Capture\n- **Event-Driven Recording**: No timer or delays - catch mouse actions with crosshair annotation instantly.\n- **Comprehensive Context**: Five recorders track windows, keyboard, clipboard, notifications, and files around mouse actions.\n\n### 🌲 Intelligent Memory Hierarchy\n- **Auto-Organization**: Raw streams structure into five tiers: Day → Session → App → Location → Action.\n- **Smart Summaries**: LLM summaries at each level, transforming logs into searchable knowledge trees.\n\n### 🔍 Tree-Based Retrieval\n- **No Vector Complexity**: Skip embeddings and VDBs — our system uses tree-based reasoning for navigation.\n- **Top-Down Search**: LLM reads summaries, selects relevant branches, and drills down to evidence.\n\n### 🤖 Zero-Config Agent Integration\n- **One-File Setup**: Drop a single skill file into any AI agent for instant integration.\n- **Immediate Access**: CLI-based screen history queries with zero configuration required.\n\n### 🪶 Ultralight \u0026 Privacy-First\n- **Minimal Footprint**: ~0.2GB runtime RAM with efficient SQLite + FTS5 storage.\n- **Local \u0026 Offline**: All data stays on your machine with full offline mode via Ollama/vLLM/LM Studio.\n\n### 🖥️ Rich Web Interface\n- **Visual Exploration**: Interactive timelines, memory tree navigation, and real-time system monitoring.\n- **Natural Conversation**: Chat with your complete digital footprint using natural language.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/web.png\" width=\"100%\" alt=\"CatchMe Web Dashboard\"/\u003e\n\u003c/p\u003e\n\n\n## 💡 CatchMe Architecture\n\nCatchMe transforms raw digital activity into structured, searchable memory through three concurrent stages:\n\n### 🔄 Record → Organize → Reason: Turn digital chaos into queryable memory\n\n**Capture**. Six background recorders silently track your activity. They monitor window focus, keystrokes, mouse movement, screenshots, clipboard, and notifications.\n\n**Index**. Raw events auto-organize into a Hierarchical Activity Tree: Day → Session → App → Location → Action. Each node gets LLM-generated summaries. Fast, meaningful recall without vector embeddings.\n\n**Retrieve**. You ask a question. The LLM traverses your memory tree top-down. It selects relevant nodes and inspects raw data like screenshots or keystrokes. Then synthesizes a precise answer.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/catchme-pipe.png\" width=\"680\" alt=\"CatchMe Pipeline: Capturing → Indexing → Retrieving\"/\u003e\n\u003c/p\u003e\n\n### 🌲 Hierarchical Activity Tree\nThe Activity Tree is CatchMe's memory core. It provides structured, multi-level views of your digital life. Browse high-level summaries or dive into granular details.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/fig1_activity_tree.png\" width=\"800\" alt=\"Hierarchical Activity Tree Structure\"/\u003e\n\u003c/p\u003e\n\n### 🔍 Intelligent Tree Retrieval\nCatchMe skips traditional vector search. Instead, the LLM directly navigates your Activity Tree. This enables complex, cross-day reasoning. Precise evidence gathering from raw activity history.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/fig2_retrieval.png\" width=\"800\" alt=\"Tree-based Retrieval Process\"/\u003e\n\u003c/p\u003e\n\n**📖 Learn More**: Detailed design insights and technical deep-dive available in our [blog](https://hkuds.github.io/CatchMe/).\n\n## 🧠 LLM Configuration\n\n### **❗️ Data Privacy Notice**\n• **100% Local Storage**: All raw data (screenshots, keystrokes, activity trees) stays in ~/data/ and never leaves your machine. \n\n• **Offline-First Options**: Local LLMs (Ollama, vLLM, LM Studio) enable fully offline operation without any cloud dependency.\n\n• **⚠️Cloud Provider Caution**: If used, cloud APIs will be used to summarize your daily activities. **Untrusted endpoints may expose private data** — review data policies of your provider carefully.\n\n### **📋 Requirements**\n• **Multimodal support**: Your model should be able to handle text + images.\n\n• **Context window**: Make sure the context window of your model exceed `max_tokens` limits in `config.json`.\n\n• **Cost control**: For *forced cost control*, set limits via `llm.max_calls` or increase `filter.mouse_cluster_gap` to reduce summarization frequency.\n\nCatchMe requires an LLM for background summarization and intelligent retrieval. Use **catchme init** (in \u003ca href=\"#-get-started\"\u003eGet Started\u003c/a\u003e)for **guided setup** or follow the **manual configuration** steps below.\n\nFor cloud API services:\n\n```json\n{\n    \"llm\": {\n        \"provider\": \"openrouter\",\n        \"api_key\": \"sk-or-...\",\n        \"api_url\": null,\n        \"model\": \"google/gemini-3-flash-preview\"\n    }\n}\n```\n\nFor local/offline operation:\n\n```json\n{\n    \"llm\": {\n        \"provider\": \"ollama\",\n        \"api_key\": null,\n        \"api_url\": null,\n        \"model\": \"gemma3:4b\"\n    }\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSupported LLM Providers\u003c/b\u003e\u003c/summary\u003e\n\n| Provider                  | Config name              | Default API URL                                         | Get Key                                                              |\n| ------------------------- | ------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------- |\n| **OpenRouter** (gateway)  | `openrouter`             | `https://openrouter.ai/api/v1`                          | [openrouter.ai/keys](https://openrouter.ai/keys)                     |\n| **AiHubMix** (gateway)    | `aihubmix`               | `https://aihubmix.com/v1`                               | [aihubmix.com](https://aihubmix.com)                                 |\n| **SiliconFlow** (gateway) | `siliconflow`            | `https://api.siliconflow.cn/v1`                         | [cloud.siliconflow.cn](https://cloud.siliconflow.cn)                 |\n| **OpenAI**                | `openai`                 | `https://api.openai.com/v1`                             | [platform.openai.com](https://platform.openai.com/api-keys)          |\n| **Anthropic**             | `anthropic`              | `https://api.anthropic.com/v1`                          | [console.anthropic.com](https://console.anthropic.com)               |\n| **DeepSeek**              | `deepseek`               | `https://api.deepseek.com/v1`                           | [platform.deepseek.com](https://platform.deepseek.com/api_keys)      |\n| **Gemini**                | `gemini`                 | `https://generativelanguage.googleapis.com/v1beta`      | [aistudio.google.com](https://aistudio.google.com/apikey)            |\n| **Groq**                  | `groq`                   | `https://api.groq.com/openai/v1`                        | [console.groq.com](https://console.groq.com/keys)                    |\n| **Mistral**               | `mistral`                | `https://api.mistral.ai/v1`                             | [console.mistral.ai](https://console.mistral.ai)                     |\n| **Moonshot / Kimi**       | `moonshot`               | `https://api.moonshot.ai/v1`                            | [platform.moonshot.cn](https://platform.moonshot.cn)                 |\n| **MiniMax**               | `minimax`                | `https://api.minimax.io/v1`                             | [platform.minimaxi.com](https://platform.minimaxi.com)               |\n| **Zhipu AI (GLM)**        | `zhipu`                  | `https://open.bigmodel.cn/api/paas/v4`                  | [open.bigmodel.cn](https://open.bigmodel.cn)                         |\n| **DashScope (Qwen)**      | `dashscope`              | `https://dashscope.aliyuncs.com/compatible-mode/v1`     | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |\n| **VolcEngine**            | `volcengine`             | `https://ark.cn-beijing.volces.com/api/v3`              | [console.volcengine.com](https://console.volcengine.com)             |\n| **VolcEngine Coding**     | `volcengine_coding_plan` | `https://ark.cn-beijing.volces.com/api/coding/v3`       | [console.volcengine.com](https://console.volcengine.com)             |\n| **BytePlus**              | `byteplus`               | `https://ark.ap-southeast.bytepluses.com/api/v3`        | [console.byteplus.com](https://console.byteplus.com)                 |\n| **BytePlus Coding**       | `byteplus_coding_plan`   | `https://ark.ap-southeast.bytepluses.com/api/coding/v3` | [console.byteplus.com](https://console.byteplus.com)                 |\n| **Ollama** (local)        | `ollama`                 | `http://localhost:11434/v1`                             | —                                                                    |\n| **vLLM** (local)          | `vllm`                   | `http://localhost:8000/v1`                              | —                                                                    |\n| **LM Studio** (local)     | `lmstudio`               | `http://localhost:1234/v1`                              | —                                                                    |\n\n\u003e Any OpenAI-compatible endpoint works — just set `api_url` and `api_key` directly.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAll Configuration Parameters\u003c/b\u003e\u003c/summary\u003e\n\n| Section       | Parameter                  | Default     | Description                                         |\n| ------------- | -------------------------- | ----------- | --------------------------------------------------- |\n| **web**       | `host`                     | `127.0.0.1` | Dashboard bind address                              |\n|               | `port`                     | `8765`      | Dashboard port                                      |\n| **llm**       | `provider`                 | —           | LLM provider name (see table above)                 |\n|               | `api_key`                  | —           | API key for the provider                            |\n|               | `api_url`                  | *(auto)*    | Custom endpoint; auto-set per provider if omitted   |\n|               | `model`                    | —           | Model name (provider-specific)                      |\n|               | `max_calls`                | `0`         | Max LLM calls per cycle (`0` = unlimited; set to limit costs) |\n|               | `max_images_per_cluster`   | `5`         | Max screenshots sent per event cluster              |\n| **filter**    | `window_min_dwell`         | `3.0`       | Min window dwell time (sec) before recording        |\n|               | `keyboard_cluster_gap`     | `3.0`       | Keyboard event clustering gap (sec)                 |\n|               | `mouse_cluster_gap`        | `3.0`       | Time gap (sec) to merge mouse events; **larger values reduce LLM summaries** |\n| **summarize** | `language`                 | `en`        | Summary output language (`en`, `zh`, etc.)          |\n|               | `max_tokens_l0`–`l3`       | `1200`      | Max tokens per tree level (L0=Action … L3=Session)  |\n|               | `temperature`              | `0.4`       | LLM temperature for summarization                   |\n|               | `max_workers`              | `2`         | Concurrent summarization workers                    |\n|               | `debounce_sec`             | `3.0`       | Debounce before triggering summary                  |\n|               | `save_interval_sec`        | `5.0`       | Tree auto-save interval                             |\n| **retrieve**  | `max_prompt_chars`         | `42000`     | Max chars in retrieval prompt                       |\n|               | `max_iterations`           | `15`        | Max tree traversal iterations                       |\n|               | `max_file_chars`           | `8000`      | Max chars from extracted files                      |\n|               | `max_select_nodes`         | `7`         | Max nodes selected per iteration                    |\n|               | `max_tokens_step`          | `4096`      | Max tokens per retrieval step                       |\n|               | `max_tokens_answer`        | `8192`      | Max tokens for final answer                         |\n|               | `temperature_select`       | `0.3`       | Temperature for node selection                      |\n|               | `temperature_answer`       | `0.5`       | Temperature for answer generation                   |\n|               | `temperature_time_resolve` | `0.1`       | Temperature for time resolution                     |\n|               | `max_tokens_time_resolve`  | `1000`      | Max tokens for time resolution                      |\n\n\u003c/details\u003e\n\n## 🚀 Get Started\n\n### 📦 Install\n\n```bash\ngit clone https://github.com/HKUDS/catchme.git \u0026\u0026 cd catchme\n\nconda create -n catchme python=3.11 -y \u0026\u0026 conda activate catchme\n\npip install -e .\n```\n\n\u003e **macOS** — grant *Accessibility*, *Input Monitoring*, *Screen Recording* in System Settings → Privacy \u0026 Security\n\u003e **Windows** — run as Administrator for global input monitoring\n\n### ⚡ Init\n\n```bash\ncatchme init                  # interactive setup: provider, API key, llm model\n```\n\n### 🔥 Run\n\n```bash\ncatchme awake                 # start recording\ncatchme web                   # visualize and chat\n\n# or through cli\ncatchme ask -- \"What am I doing today?\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull CLI Reference\u003c/b\u003e\u003c/summary\u003e\n\n| Command                     | Description                                            |\n| --------------------------- | ------------------------------------------------------ |\n| `catchme awake`             | Start the recording daemon                             |\n| `catchme web [-p PORT]`     | Launch web dashboard (default `http://127.0.0.1:8765`) |\n| `catchme ask -- \"question\"` | Query your activity in natural language                |\n| `catchme cost`              | Show LLM token usage (last 10 min / today / all time)  |\n| `catchme disk`              | Show storage breakdown \u0026 event count                   |\n| `catchme ram`               | Show memory usage of running processes                 |\n| `catchme init`              | Interactive setup: LLM provider, API key \u0026 model       |\n\n\u003c/details\u003e\n\n\n## 🦞 CatchMe Makes Your Agents Truly Personal\nCatchMe ships as an agent-compatible skill for CLI agents (OpenClaw, NanoBot, Claude, Cursor, etc.).\n\n**🪶 Agent Integration:**\nRun CatchMe independently. Your agents query memories via CLI commands only.\n\n```bash\n# 1. Start CatchMe yourself\ncatchme awake\n\n# 2. Give the light skill to your agent\ncp CATCHME-light.md ~/.cursor/skills/catchme/SKILL.md\n```\n\n**Option B — Full Skill** (agent manages the full CatchMe lifecycle autonomously):\n\n```bash\ncp CATCHME-full.md ~/.cursor/skills/catchme/SKILL.md\n```\n\n### 🔧 Integrate into your current workflow\n\n```python\nfrom catchme import CatchMe\nfrom catchme.pipelines.retrieve import retrieve\n\n# 1. One-line search — fast keyword lookup over all recorded activity\nwith CatchMe() as mem:\n    for e in mem.search(\"meeting notes\"):\n        print(e.timestamp, e.data)\n\n# 2. LLM-powered retrieval — natural language Q\u0026A over your screen history\nfor step in retrieve(\"What was I working on this morning?\"):\n    if step[\"type\"] == \"answer\":\n        print(step[\"content\"])\n```\n\n## 📊 Cost \u0026 Efficiency\n\n*Benchmarked with **2 hours of intensive, continuous computer use** on MacBook Air M4.*\n\n\n| Metric                                          | Value                                                                           |\n| ----------------------------------------------- | ------------------------------------------------------------------------------- |\n| **Runtime RAM**                                 | ~0.2 GB                                                                    |\n| **Disk Usage**                                  | ~ 200 MB                                                                        |\n| **Token Throughput**                                 | input ~ 6 M , output ~ 0.7 M                                                    |                   |\n| **LLM cost** — `qwen-3.5-plus`                  | ~ $0.42 via [Aliyun DashScope](https://home.console.aliyun.com/home/dashboard/) |\n| **LLM cost** — `gemini-3-flash-preview`         | ~ $5.00 via [OpenRouter](https://openrouter.ai/models)       \n| **Full Retrieval Speed** (depends on question) | 5 - 20s per query using `gemini-3-flash-preview`                                |\n\n\n## 🚀 Roadmap\nCatchMe evolves with community input. Upcoming features include:\n\n**Multi-Device Recording**. Capture and unify GUI activities across all your machines via LAN synchronization.\n\n**Dynamic Clustering**. Adaptive clustering algorithms that better reflect your actual work patterns and flows, reducing unnecessary costs.\n\n**Enhanced Data Utilization**. Unlock deeper insights from screenshots and metadata beyond current processing pipelines.\n\n\u003e 🌟 **Star this repo** to follow our future updates — your interest keeps us motivated!\n\nWe welcome contributions of any kind - whether it's a comment, a bug report, a feature idea, or a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n\n## 🤝 Community\n\n### Acknowledgments !\n\nCatchMe is inspired by these excellent open-source projects:\n\n| Project                                                         | Inspiration                                           |\n| --------------------------------------------------------------- | ----------------------------------------------------- |\n| [ActivityWatch](https://github.com/ActivityWatch/activitywatch) | Pioneering open-source activity tracking              |\n| [Screenpipe](https://github.com/mediar-ai/screenpipe)           | Screen recording infrastructure for AI agents         |\n| [Windrecorder](https://github.com/Antonoko/Windrecorder)        | Personal screen recording \u0026 search on Windows         |\n| [OpenRecall](https://github.com/openrecall/openrecall)          | Open-source alternative to Windows Recall             |\n| [Selfspy](https://github.com/selfspy/selfspy)                   | Classic daemon-style activity logging                 |\n| [PageIndex](https://github.com/HKUDS/PageIndex)                 | Tree-structured document retrieval without embeddings |\n| [MineContext](https://github.com/volcengine/MineContext)        | Proactive context-aware AI partner \u0026 screen capture   |\n\n\n### 🏛️ Ecosystem\n\nCatchMe is part of the **[HKUDS](https://github.com/HKUDS)** agent ecosystem — building the infrastructure layer for personal AI agents:\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"25%\"\u003e\n      \u003ca href=\"https://github.com/HKUDS/nanobot\"\u003e\u003cb\u003eNanoBot\u003c/b\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003csub\u003eUltra-Lightweight Personal AI Assistant\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\"\u003e\n      \u003ca href=\"https://github.com/HKUDS/CLI-Anything\"\u003e\u003cb\u003eCLI-Anything\u003c/b\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003csub\u003eMaking All Software Agent-Native\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\"\u003e\n      \u003ca href=\"https://github.com/HKUDS/ClawWork\"\u003e\u003cb\u003eClawWork\u003c/b\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003csub\u003eAI Assistant → AI Coworker Evolution\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"25%\"\u003e\n      \u003ca href=\"https://github.com/HKUDS/ClawTeam\"\u003e\u003cb\u003eClawTeam\u003c/b\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003csub\u003eAgent Awarm Intelligence for Full Team Automation\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n  Thanks for visiting ✨ \u003cb\u003eCatchMe\u003c/b\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://visitor-badge.laobi.icu/badge?page_id=HKUDS.catchme\" alt=\"visitors\"/\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkuds%2Fcatchme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhkuds%2Fcatchme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkuds%2Fcatchme/lists"}