HKUDS/CatchMe

CatchMe – AI 代理的個人記憶引擎

功能說明

• 在您的電腦背景執行，記錄您所做的一切：滑鼠點擊、按鍵輸入、視窗焦點變化、剪貼簿內容、螢幕截圖、通知和檔案修改。
• 原始事件會自動組織成層級活動樹（日 → 工作階段 → 應用程式 → 位置 → 動作）。
• 每個層級加入小型 LLM 驅動的摘要，將樹轉換為可搜尋的知識庫。
• 當您提出問題（透過 CLI、網頁儀表板或 AI 代理技能），LLM 會從上到下遍歷樹，選取最相關的分支，檢查底層原始資料，並回傳簡潔的答案。
• 所有資料都保留在本機（SQLite + FTS5），並可使用您喜歡的任何 LLM 處理——從雲端 API（OpenAI、Anthropic、Gemini 等）到由 Ollama、vLLM 或 LM Studio 提供的離線模型。

重要性

• 為 AI 助手（Claude、Cursor、OpenClaw、NanoBot 等）提供您數位生活的個人記憶，無需向量資料庫或外部服務。
• 保持隱私完整：除非您刻意使用雲端 LLM 進行摘要，否則不會上傳任何內容。
• 可在 macOS、Windows 和 Linux（僅 X11）上運作，執行時佔用資源極小（約 0.2 GB RAM）。

---

主要功能（依 README 描述）

功能	您獲得什麼
持續事件擷取	六個低階記錄器即時擷取滑鼠、鍵盤、視窗焦點、剪貼簿、通知和檔案變更（無需計時器）。
智慧記憶層級	事件自動組織成五層樹；每個節點獲得 LLM 生成的摘要，以進行快速、語意瀏覽。
樹狀檢索（無向量）	不是嵌入向量，而是 LLM 直接導覽活動樹，選擇分支並深入原始證據。
零設定代理整合	將單一技能檔案放入任何 CLI 型 AI 代理；代理可透過簡單 CLI 指令查詢記憶。
超輕量與隱私優先	所有內容儲存在本機 SQLite + FTS5；可完全離線執行，搭配本機 LLM。
豐富網頁介面	互動式儀表板，包含時間軸、樹狀導覽和聊天視窗，可與您自己的數位足跡對話。
成本控制設定	可設定 LLM 呼叫次數、每個叢集的影像數量，以及摘要頻率限制，以降低 token 使用量。

---

運作方式（高階管線）

1. 擷取 – 六個背景守護程式監聽作業系統事件（滑鼠、鍵盤、視窗焦點、螢幕截圖、剪貼簿、通知）。
2. 索引 – 事件串流到層級活動樹。
3. 摘要 – 可設定的 LLM 為每個節點（日、工作階段、應用程式、位置、動作）建立簡短摘要。
4. 檢索 – 當您提出問題，LLM 讀取頂層摘要，選取最有希望的分支，並遞迴向下直到找到具體證據（例如螢幕截圖或按鍵記錄）來回答。

---

開始使用（README 的快速入門步驟）

# 1. 複製並建立 Python 3.11 環境
git clone https://github.com/HKUDS/catchme.git && cd catchme
conda create -n catchme python=3.11 -y && conda activate catchme

# 2. 安裝套件（可編輯模式）
pip install -e .

# 3. 平台特定權限
#   macOS – 授予輔助使用、輸入監控、螢幕錄製
#   Windows – 以系統管理員身分執行終端機
#   Linux – 安裝 xdotool 和 xprop，然後執行 `pip install -e "[linux]"`

# 4. 初始化 LLM 設定（互動式）
catchme init   # 選擇提供者、API 金鑰、模型等

# 5. 開始記錄
catchme awake   # 守護程式在背景執行

# 6. 查詢或探索
catchme ask -- "What was I coding yesterday?"
catchme web    # 在 http://127.0.0.1:8765 開啟本機儀表板

---

LLM 設定（您需要設定的內容）

• 提供者 – 任何眾多支援的服務（OpenAI、Anthropic、Gemini、Ollama 等）。
• 模型 – 您要用於摘要和檢索的模型名稱。
• 上下文視窗 – 必須足夠大以容納 max_tokens_* 設定（最終答案預設最多 8192 個 token）。
• 隱私注意事項 – 如果您使用雲端提供者，原始活動資料將被傳送以進行摘要；否則使用本機模型保持完全離線。
• 成本限制 – llm.max_calls、filter.mouse_cluster_gap 和其他旋鈕可讓您限制 token 使用量。

---

代理整合

CatchMe 可透過一個小型技能檔案暴露給任何 CLI 型 AI 代理：

• 輕量技能 – 您自己執行 catchme awake；代理只需呼叫 catchme ask …。
• 完整技能 – 代理可以啟動/停止 CatchMe，並使用 MCP stdio 伺服器進行更豐富的互動。

代理支援的工具：

• search_activity(query, date?)
• list_days()
• get_session(session_id)
• get_tree(date)

---

社群與資源

• 部落格 / 設計深入探討 – https://hkuds.github.io/CatchMe/
• Discord – https://discord.gg/2vDYc2w5
• 飛書 / 微信群組 – 連結在 COMMUNICATION.md
• 授權 – Apache 2.0

---

結論

CatchMe 是一個輕量、隱私優先的「個人記憶儲存庫」，將您的日常電腦活動轉換為結構化、可 LLM 查詢的知識庫。它讓您能為任何 AI 助手提供對您的數位歷史的真實感知，而無需向量資料庫或雲端儲存的負擔。