nossa-y/activity-frames

activity‑frames – 将您的屏幕使用时间转化为 AI 智能体的结构化记忆

功能介绍 – activity‑frames 在本地记录您在计算机上进行的所有操作（窗口标题、URL、点击、按键等），然后将这些原始快照编译成活动帧 (activity frames)：每个任务的确定性、有时限的记录。这些帧可以渲染为简洁、节省 token 的上下文块，您可以将其粘贴到提示词中，或者导出为 JSON/YAML 以供智能体重放精确的操作序列。

重要意义 – 当前的计算机使用型智能体每次都需要从头重新推导每个任务，这会消耗大量的 LLM token，且可能不够稳定。通过将重复性工作转化为可重用的脚本，activity‑frames 让智能体能够以（接近）零 token 成本和完美的保真度执行已知工作流，同时仍能为它们提供您全天其余时间的概要总结以供上下文参考。

核心功能

• 仅限本地捕获 – 内置的屏幕录制器 (nocta‑recorder) 将快照存储在 SQLite DB 中；不会上传任何内容。
• 确定性编译 – 纯代码（不使用 LLM）在 < 1 秒内将数百万行数据转化为几百个 token。
• 智能体就绪的上下文块 – 即插即用的 YAML/markdown 摘要，符合 LLM token 限制。
• 可执行工作流 – aframes steps --find "…" 提取按点击顺序排列的脚本，智能体无需重新推理即可重放。
• MCP 集成 – 六个 Model‑Context‑Protocol 工具 (get_context, get_activity, get_steps, get_day_summary, get_patterns, get_communications) 向任何兼容 MCP 的智能体开放帧数据。
• Python API – ActivityLog() 提供 day(), recent(), 和 context() 辅助函数。
• 隐私控制 – 默认关闭音频，除非传递 --include‑text 参数，否则省略文本内容，且所有数据都保留在您的机器上。
• 网站解析器 – 内置对 25 个以上热门网站的实体提取功能（LinkedIn, GitHub, Google services, YouTube, Slack, Notion, 等）。

安装方法

pip install activity-frames          # core library & CLI
pip install "activity-frames[yaml]" # optional YAML output support

第一次调用 aframes record 时会下载并验证适用于 macOS (Apple Silicon 或 Intel) 的相应 nocta‑recorder 二进制文件。Linux 用户可以将 $AFRAMES_DB 指向任何兼容的捕获数据库。

典型 CLI 工作流

# 1. 记录您的屏幕 (默认关闭音频)
aframes record

# 2. 当您需要为智能体提供过去 2 小时的上下文时
aframes context --hours 2   # prints a ready‑to‑paste block

# 3. 提取可重用的工作流 (例如，发送 LinkedIn 消息)
aframes steps --find "message john doe"

# 4. 通过 MCP 从智能体运行确定性执行器
aframes mcp   # serves the six MCP tools over stdio

Python 使用示例

from activity_frames import ActivityLog
log = ActivityLog()
print(log.context(hours=3))          # one‑liner for a prompt
print(log.recent(hours=1).json())    # raw frames as JSON

论文与社区 – 该方法在 Activity Frames: Deterministic Screen‑Activity Compilation for Agent Memory and Replay (arXiv 2608.05784) 中进行了描述。该仓库包含测量代码、重放执行器以及详尽的文档 (AGENTS.md, SPEC.md, docs/*)。它采用 MIT 许可证，并处于积极维护中 (v0.2, macOS-first, 通过自定义录制器支持 Linux)。