nossa-y/activity-frames

activity‑frames – 將您的螢幕使用時間轉化為 AI agent 的結構化記憶

功能說明 – activity‑frames 會在本地端記錄您在電腦上所做的一切（視窗標題、URL、點擊、按鍵等），然後將這些原始快照編譯成 activity frames：每個任務的確定性、有時間限制的記錄。這些 frames 可以被渲染成簡潔、節省 token 的上下文區塊，供您貼入 prompt，或者匯出為 JSON/YAML 以供 agent 執行精確的動作序列。

重要性 – 目前使用電腦的 agent 會在每次執行任務時從頭重新推導，這會消耗大量的 LLM token 並可能導致不穩定。透過將重複的工作轉化為可重複使用的腳本，activity‑frames 讓 agent 能以（接近）零 token 成本且具備完美保真度的執行已知的工作流程，同時仍能為其提供當天其餘時間的高層次摘要以作為上下文。

核心功能

• 僅限本地端擷取 – 內建的螢幕錄製工具 (nocta‑recorder) 將快照儲存在 SQLite DB 中；不會上傳任何內容。
• 確定性編譯 – 使用純程式碼（不使用 LLM）在 < 1 秒內將數百萬行數據轉化為幾百個 token。
• Agent 準備就緒的上下文區塊 – 可直接貼上的 YAML/markdown 摘要，符合 LLM token 限制。
• 可執行工作流程 – aframes steps --find "…" 會提取出一個有序的點擊步驟腳本，讓 agent 能在無需重新推理的情況下重新執行。
• MCP 整合 – 六個 Model‑Context‑Protocol 工具 (get_context, get_activity, get_steps, get_day_summary, get_patterns, get_communications) 將 frames 暴露給任何相容 MCP 的 agent。
• Python API – ActivityLog() 提供 day(), recent(), 和 context() 輔助函式。
• 隱私控制 – 預設關閉音訊，除非傳遞 --include‑text 參數，否則會省略文字內容，且所有數據都保留在您的機器上。
• 網站解析器 – 內建針對 25 個以上熱門網站（LinkedIn, GitHub, Google 服務, 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 指向任何相容的擷取 DB。

典型的 CLI 工作流程

# 1. 記錄您的螢幕 (預設關閉音訊)
aframes record

# 2. 當您需要提供 agent 上次 2 小時的上下文時
aframes context --hours 2   # prints a ready‑to‑paste block

# 3. 提取可重複使用的工作流程 (例如：傳送 LinkedIn 訊息)
aframes steps --find "message john doe"

# 4. 透過 MCP 從 agent 執行確定性執行器
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 支援透過自定義錄製工具)。