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 助手提供对您的数字历史的真实感知，而无需向量数据库或云存储的负担。