CatchMe开源AI代理记忆系统：无向量检索与本地化存储实践-AI智能范式网

CatchMe开源AI代理记忆系统：无向量检索与本地化存储实践

下厨房

1. CatchMe项目概述

CatchMe是由HKUDS团队开发的开源AI代理记忆系统，旨在通过记录用户数字活动轨迹，构建结构化的个人记忆树，使AI代理能够真正理解用户的工作习惯和个人上下文。这个项目最核心的创新点在于完全摒弃了传统的向量检索方式，转而采用基于活动树的层级检索机制。

提示：与传统屏幕录制工具不同，CatchMe的设计哲学是"记录一切，按需检索"，所有数据都存储在本地SQLite数据库中，确保隐私安全。

2. 核心架构解析

2.1 三层处理流水线

CatchMe的架构围绕三个核心阶段构建：

记录层：六个后台记录器持续捕获：
- 窗口焦点变化（每秒采样）
- 键盘输入（带语义聚类）
- 鼠标移动轨迹（带十字标注）
- 屏幕截图（智能触发）
- 剪贴板内容
- 系统通知

组织层：原始数据自动构建为五级活动树：

plaintext复制Day → Session → App → Location → Action

推理层：LLM通过以下路径检索信息：
- 读取顶层摘要
- 选择相关分支
- 钻取到原始证据（如截图、按键记录）

2.2 关键技术突破

2.2.1 无向量检索系统

传统方案通常需要：

生成嵌入向量
构建向量数据库
执行相似度搜索

而CatchMe采用：

python复制def tree_retrieval(query):
    nodes = select_relevant_branches(tree.root, query)
    evidence = []
    for node in nodes:
        if needs_deeper_lookup(node):
            evidence += extract_raw_data(node)
    return synthesize_answer(evidence)

这种方法的优势在于：

支持跨日复杂推理
精确到具体操作步骤的追溯
避免嵌入过程中的信息损失

2.2.2 轻量化存储设计

实测数据（MacBook Air M4 2小时持续使用）：

内存占用：~200MB
磁盘空间：~200MB
事件记录：约15,000条

存储优化策略：

SQLite+FTS5组合索引
截图JPEG压缩（85%质量）
键盘事件差分存储

3. 实战部署指南

3.1 环境配置

硬件要求：

macOS：需要授予辅助功能权限
Windows：需要管理员权限运行
Linux：需要X11截图权限

Python环境：

bash复制conda create -n catchme python=3.11 -y
conda activate catchme
pip install git+https://github.com/HKUDS/CatchMe.git

3.2 LLM配置选项

本地部署方案（推荐）：

json复制{
  "llm": {
    "provider": "ollama",
    "model": "gemma3:4b",
    "api_url": "http://localhost:11434"
  }
}

云端API方案（需注意隐私风险）：

json复制{
  "llm": {
    "provider": "openrouter",
    "api_key": "sk-or-...",
    "model": "google/gemini-3-flash-preview"
  }
}

3.3 典型工作流

启动后台服务：
```
bash复制catchme awake
```

进行自然语言查询：

bash复制catchme ask -- "昨天下午修改的Python文件有哪些？"

查看资源使用：

bash复制catchme disk  # 存储分析
catchme cost  # token消耗

4. 深度应用场景

4.1 编程辅助实践

问题重现：

bash复制catchme ask -- "展示我最近在VSCode中调试的代码片段"

输出示例：

code复制2024-03-15 14:32:22 [VSCode] 
调试文件：/projects/llm-agent/train.py
修改内容：
- 第45行：调整learning_rate从1e-4到3e-5
- 第78行：添加early_stopping逻辑
关联截图：screenshots/20240315_143222.jpg

4.2 研究助手模式

学术追踪：

bash复制catchme ask -- "找出我上周阅读的所有AI论文PDF"

检索逻辑：

识别所有PDF阅读器活动
提取文件打开事件
关联剪贴板中的引用内容
按修改时间排序输出

5. 性能优化技巧

5.1 成本控制策略

关键配置参数：

json复制{
  "filter": {
    "mouse_cluster_gap": 5.0,  // 增大可减少事件量
    "window_min_dwell": 2.0    // 忽略短暂窗口切换
  },
  "llm": {
    "max_calls": 50,           // 每日最大调用
    "max_images_per_cluster": 3 
  }
}

5.2 存储管理方案

自动清理策略：

python复制# 保留最近7天完整数据
catchme.db.execute("""
DELETE FROM raw_events WHERE timestamp < datetime('now', '-7 days');
""")

# 压缩旧截图为缩略图
optimize_images(older_than=timedelta(days=3))

6. 开发者扩展接口

6.1 自定义记录器

示例：添加Slack消息捕获

python复制from catchme.recorders.base import BaseRecorder

class SlackRecorder(BaseRecorder):
    def run(self):
        while True:
            msg = monitor_slack_activity()
            self.emit_event({
                'type': 'slack',
                'content': msg,
                'timestamp': time.time()
            })

6.2 插件开发规范

标准插件结构：

code复制catchme/plugins/
├── slack_integration/
│   ├── __init__.py
│   ├── recorder.py
│   └── config.json

注册流程：

python复制from catchme import register_plugin

register_plugin(
    name="slack",
    recorder=SlackRecorder,
    config_schema={"token": str}
)

7. 安全与隐私架构

7.1 数据保护机制

加密存储方案：

python复制from cryptography.fernet import Fernet

class SecureStorage:
    def __init__(self):
        self.key = load_key_from_keyring()
        self.cipher = Fernet(self.key)

    def save(self, data):
        encrypted = self.cipher.encrypt(json.dumps(data).encode())
        write_to_db(encrypted)

7.2 权限控制矩阵

操作类型	所需权限
屏幕录制	root/管理员
键盘记录	输入监控权限
文件访问	标准用户权限
网络通信	显式用户确认

8. 故障排查手册

8.1 常见问题处理

问题1：截图功能失效

解决方案：
1. macOS：检查系统设置 > 隐私与安全 > 屏幕录制
2. Windows：以管理员身份重新安装
3. Linux：确保gnome-screenshot已安装

问题2：LLM响应超时

bash复制# 测试连接性
curl -X POST http://localhost:11434/api/generate -d '{
  "model": "gemma3:4b",
  "prompt": "test"
}'

8.2 诊断工具集

内置检测命令：

bash复制catchme doctor  # 全面系统检查
catchme debug --recorder=keyboard  # 特定记录器调试

日志分析技巧：

bash复制tail -f ~/.catchme/logs/main.log | grep -i "error"

9. 性能基准测试

9.1 检索延迟分析

查询复杂度	本地LLM (ms)	云端LLM (ms)
简单事实查询	1200	800
跨会话推理	3500	2500
多模态检索	4200	3100

9.2 资源占用对比

工作负载	CPU占用 (%)	内存 (MB)
空闲状态	0.5	85
标准记录	3.2	120
密集截图时段	15.8	210

10. 生态整合方案

10.1 与Cursor IDE集成

安装技能文件：

bash复制cp CATCHME-full.md ~/.cursor/skills/catchme/SKILL.md

触发查询示例：

cursor复制/catchme 显示我今天修改的React组件

10.2 命令行代理对接

python复制from catchme import CatchMe

def agent_loop():
    with CatchMe() as cm:
        while True:
            query = get_user_input()
            for event in cm.search(query):
                display_result(event)

11. 高级配置技巧

11.1 多显示器支持

配置示例：

json复制{
  "recorders": {
    "screenshot": {
      "displays": [0, 1],  // 主副显示器
      "rotation": 90       // 竖屏调整
    }
  }
}

11.2 自定义事件过滤

python复制from catchme.filters import EventFilter

class MyFilter(EventFilter):
    def process(self, event):
        if event.app == "Telegram":
            return None  # 忽略Telegram活动
        return event

12. 未来演进方向

多设备同步：通过LAN同步不同设备的记忆树
动态聚类算法：自适应调整事件分组策略
增强OCR能力：深度提取截图文本信息
语音指令集成：支持自然语音查询

实际部署中发现，将mouse_cluster_gap参数设置为3-5秒区间，能在记录精细度和存储效率间取得最佳平衡。对于编程场景，建议额外启用文件diff记录功能，可以精确追踪代码变更历史。