nossa-y/activity-frames

activity‑frames – 당신의 화면 사용 시간을 AI 에이전트를 위한 구조화된 메모리로 전환하기

무엇을 하는가 – activity‑frames는 컴퓨터에서 수행하는 모든 작업(창 제목, URL, 클릭, 키스트로크 등)을 로컬에 기록한 다음, 이러한 원시 스냅샷을 activity frames: 각 작업의 결정론적이고 시간 제한적인 기록으로 컴파일합니다. 이 프레임은 프롬프트에 붙여넣을 수 있는 간결하고 토큰 효율적인 컨텍스트 블록으로 렌더링되거나, 에이전트가 정확한 작업 순서를 재현할 수 있도록 JSON/YAML로 내보낼 수 있습니다.

왜 중요한가 – 현재의 컴퓨터 사용 에이전트는 매번 작업을 처음부터 다시 유도해내야 하므로 많은 LLM 토큰을 소모하며 불안정할 수 있습니다. 반복되는 작업을 재사용 가능한 스크립트로 전환함으로써, activity‑frames는 에이전트가 (거의) 제로에 가까운 토큰 비용으로 완벽한 충실도로 알려진 워크플로우를 실행할 수 있게 하면서도, 컨텍스트를 위해 하루의 나머지 부분에 대한 고수준 요약을 제공합니다.

주요 기능

• 로컬 전용 캡처 – 번들로 제공되는 화면 녹화기(nocta‑recorder)가 스냅샷을 SQLite DB에 저장하며, 아무것도 업로드되지 않습니다.
• 결정론적 컴파일 – 순수 코드(LLM 미사용)가 수백만 개의 행을 1초 미만에 수백 개의 토큰으로 변환합니다.
• 에이전트용 컨텍스트 블록 – LLM 토큰 제한 내에 들어가는 바로 붙여넣기 가능한 YAML/markdown 요약본입니다.
• 실행 가능한 워크플로우 – aframes steps --find "…"는 에이전트가 재사고 없이 재현할 수 있는 순서대로 된 클릭 단위 스크립트를 추출합니다.
• MCP 통합 – 6개의 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를 호환 가능한 캡처 DB로 지정할 수 있습니다.

일반적인 CLI 워크플로우

# 1. 화면을 녹화합니다 (기본적으로 오디오는 꺼져 있습니다)
aframes record

# 2. 에이전트에게 지난 2시간 동안의 컨텍스트를 제공해야 할 때
aframes context --hours 2   # 바로 붙여넣기 가능한 블록을 출력합니다

# 3. 재사용 가능한 워크플로우를 추출합니다 (예: LinkedIn 메시지 보내기)
aframes steps --find "message john doe"

# 4. MCP를 통해 에이전트로부터 결정론적 실행기를 실행합니다
aframes mcp   # stdio를 통해 6개의 MCP 도구를 제공합니다

Python 사용 예시

from activity_frames import ActivityLog
log = ActivityLog()
print(log.context(hours=3))          # 프롬프트용 한 줄 코드
print(log.recent(hours=1).json())    # JSON 형식의 원시 프레임

논문 및 커뮤니티 – 이 접근 방식은 Activity Frames: Deterministic Screen‑Activity Compilation for Agent Memory and Replay (arXiv 2608.05784)에 설명되어 있습니다. 레포지토리는 측정 코드, 재현 실행기, 그리고 광범위한 문서(AGENTS.md, SPEC.md, docs/*)를 포함합니다. MIT 라이선스로 제공되며 활발하게 유지 관리되고 있습니다 (v0.2, macOS 우선, custom recorder를 통한 Linux 지원).