nossa-y/activity-frames

activity‑frames – スクリーンタイムをAIエージェントのための構造化されたメモリに変換する

What it does – activity‑frames は、コンピュータ上で行うすべての操作（ウィンドウのタイトル、URL、クリック、キーストロークなど）をローカルに記録し、それらの生のスナップショットを、各タスクの決定論的な時間限定記録である activity frames にコンパイルします。これらのフレームは、プロンプトに貼り付け可能な簡潔でトークン効率の良いコンテキストブロックとしてレンダリングされるか、エージェントが正確なアクションのシーケンスを再生するために JSON/YAML としてエクスポートできます。

Why it matters – 現在のコンピュータ使用エージェントは、毎回タスクをゼロから再導出するため、大量の LLM トークンを消費し、動作が不安定になることがあります。繰り返しの作業を再利用可能なスクリプトに変換することで、activity‑frames は、エージェントが既知のワークフローを（ほぼ）ゼロのトークンコストで、完璧な忠実度で実行できるようにし、同時に、コンテキストとして一日の残りの活動のハイレベルな要約を提供します。

Key features

• Local‑only capture – バンドルされたスクリーンレコーダー (nocta‑recorder) がスナップショットを SQLite DB に保存します。何もアップロードされません。
• Deterministic compilation – 純粋なコード（LLM は使用しません）が、数百万行のデータを 1 秒未満で数百トークンに変換します。
• Agent‑ready context blocks – LLM のトークン制限内に収まる、そのまま貼り付け可能な YAML/markdown の要約です。
• Executable workflows – aframes steps --find "…" は、エージェントが再考なしに再生できる、順序立てられたクリックごとのスクリプトを抽出します。
• MCP integration – 6 つの Model‑Context‑Protocol ツール (get_context, get_activity, get_steps, get_patterns, get_communications) が、フレームをあらゆる MCP 互換エージェントに公開します。
• Python API – ActivityLog() は、day(), recent(), context() ヘルパーを提供します。
• Privacy controls – デフォルトでオーディオはオフ、--include‑text が指定されない限りテキスト内容は除外され、すべてのデータはマシン上に保持されます。
• Site parsers – 25 以上もの人気サイト（LinkedIn, GitHub, Google サービス, YouTube, Slack, Notion など）向けの組み込みのエンティティ抽出機能があります。

Installation

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 に指定できます。

Typical CLI workflow

# 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 usage example

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

Paper & community – このアプローチは 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 support via custom recorder)。