activity-frames 0.1.0__py3-none-any.whl

activity_frames-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: activity-frames
+Version: 0.1.0
+Summary: Episodic memory for AI agents: compile raw screen capture into structured, deterministic activity frames.
+Project-URL: Homepage, https://github.com/nossa-y/activity-frames
+Project-URL: Repository, https://github.com/nossa-y/activity-frames
+Project-URL: Issues, https://github.com/nossa-y/activity-frames/issues
+Author: Nossa Iyamu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-memory,ai-agents,context,episodic-memory,llm,mcp,screen-activity,screenpipe
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# activity-frames
+
+[![tests](https://github.com/nossa-y/activity-frames/actions/workflows/test.yml/badge.svg)](https://github.com/nossa-y/activity-frames/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/activity-frames)](https://pypi.org/project/activity-frames/)
+[![Python](https://img.shields.io/pypi/pyversions/activity-frames)](https://pypi.org/project/activity-frames/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-server-6E56CF)](https://modelcontextprotocol.io)
+
+**Episodic memory for AI agents.**
+
+Your agent can read your code, search the web, and call APIs - but it has no idea what you have been doing for the last 8 hours. It starts every conversation blind.
+
+activity-frames gives your agent eyes. It records your screen locally, compiles what it sees into structured **activity frames** (bounded episodes of what you actually did), and serves them to any agent over MCP. No cloud, no LLM in the pipeline, no guessing.
+
+```bash
+pip install activity-frames
+aframes record      # start capturing (local, audio off by default)
+aframes context     # your last 2 hours, agent-ready
+```
+
+## What your agent sees
+
+Capture stores instants: thousands of snapshot rows a day, each one saying "at 22:53:05, Chrome showed linkedin.com/in/...". Useless to reason over.
+
+activity-frames compiles those instants into episodes:
+
+```yaml
+- id: f-0007
+  app: Google Chrome
+  site: linkedin.com
+  start: "20:24:04"
+  end: "20:42:11"
+  duration_min: 18.0
+  pages:
+    - {kind: people_search, entity: "cto paris", count: 2}
+    - {kind: profile, entity: najmuzzaman}
+    - {kind: company, entity: nexdotai}
+  input: {keys: 214, clicks: 31}
+  evidence: {frame_ids: "99871..100147"}
+```
+
+And into a compact context block for any system prompt:
+
+```
+USER ACTIVITY (2026-07-04, local time; measured from screen capture, no interpretation):
+coverage: 09:12-18:47, 342 active min, 11 apps
+away: 12:30-13:15 (45m)
+- 09:12-09:58 Cursor (46.2m): main.py - api
+- 10:01-10:44 Google Chrome/github.com (41.3m): pull_request:acme/api#412; code:acme/api
+- 20:24-20:42 Google Chrome/linkedin.com (18.0m): people_search:cto paris x2; profile:najmuzzaman; company:nexdotai
+```
+
+Drop that into a prompt and your agent knows your day. A full day compiles in under a second and costs zero tokens.
+
+## Episodic memory, done honestly
+
+Agent memory today means conversation memory: what you told the model. Episodic memory is what you actually *did* - and the hard part is representing it without lying.
+
+activity-frames enforces a two-tier contract ([SPEC.md](SPEC.md)):
+
+- **Tier 1, measured (this package):** everything is derivable by deterministic code from capture data. Sessions, durations, typed page entities, input volume, coverage gaps. Same input, same output, every time. There are no intent labels - code cannot know that 2 profile views + a people search was "prospecting". That is your agent's job; it is an LLM.
+- **Tier 2, inferred (optional extension):** tools that add interpretation must namespace it, tag confidence (`high | medium | speculative`), and link evidence. Facts and guesses can never silently mix.
+
+Every frame carries evidence pointers back to raw capture rows. Every document declares its blind spots. What the system did not see, it says it did not see.
+
+## Use it from an agent (MCP)
+
+```bash
+# Claude Code
+claude mcp add activity-frames -- aframes mcp
+```
+
+Any MCP client works: command `aframes`, args `["mcp"]`. Four tools: `get_context`, `get_activity`, `get_day_summary`, `get_patterns` (repetitive-workflow detection: repeated clicks, URL loops, daily habits).
+
+## Use it from Python
+
+```python
+from activity_frames import ActivityLog
+
+log = ActivityLog()
+doc = log.day()                      # today, structured
+doc = log.recent(hours=2)            # last 2 hours
+print(log.context(hours=2))          # paste-ready context block
+```
+
+## Privacy model
+
+- **Local only.** Capture, storage, and compilation all happen on your machine. Nothing is uploaded anywhere, ever.
+- **Read-only compilation.** The compiler opens the capture database read-only.
+- **Content opt-in at the output.** Compiled documents carry input *counts* by default; typed-text content appears only if you explicitly pass `--include-text` (this also gates the repeated-text pattern detector). Be clear about the boundary: the capture database itself does store what the recorder sees, locally, so protect it like any sensitive file (FileVault, permissions).
+- **Audio off by default.** `aframes record --audio` to opt in.
+- **No LLM in the compile path.** Compilation is plain code, so no language model, local or remote, is involved in producing memory. The capture engine does run on-device OCR to read what is on screen; that stays on your machine.
+- **You choose what leaves**, when you paste a context block into an agent. Note that window titles and page entities originate from your screen and can contain third-party text; agents should treat them as data, not instructions.
+
+## Architecture
+
+```
+ capture engine          compiler (this package)         your agent
+ ------------------      ---------------------------     -----------------
+ screen snapshots   -->  sessionize (dwell, gaps,   -->  MCP tools /
+ accessibility tree      flicker merge)                  context blocks /
+ input events            entity typing (20+ sites)       JSON, YAML, md
+ (local SQLite)          enrichment, patterns
+```
+
+The default capture engine is [screenpipe](https://github.com/mediar-ai/screenpipe): `aframes record` provisions a pinned, MIT-licensed build (v0.3.324), verifies its published sha512 before first run, and manages it for you (see [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md)). Already running your own recorder? Point `$AFRAMES_DB` at any capture database with compatible `frames` / `ui_events` / `elements` tables and skip `aframes record` entirely.
+
+## CLI
+
+```bash
+aframes record                   # start capture (--stop / --status / --audio)
+aframes today                    # today's frames (YAML*)
+aframes day 2026-07-03 -f json   # any day, JSON
+aframes context --hours 3        # agent context block
+aframes apps                     # per-app time ledger
+aframes patterns --days 7        # repetitive workflow detection
+aframes mcp                      # MCP stdio server
+```
+
+*YAML output uses PyYAML (`pip install "activity-frames[yaml]"`); without it the CLI falls back to JSON.
+
+## Status
+
+v0.1. Developed and tested on macOS (Apple Silicon); Intel macOS and Linux x64 engine builds exist but are less exercised - reports welcome. Entity parsers cover LinkedIn, GitHub, Google (Search/Docs/Gmail/Maps/Meet/Calendar), YouTube, X, Instagram, Reddit, Luma, Partiful, Product Hunt, Vercel, Supabase, Stripe, Discord, Notion, Figma, Stack Overflow, Calendly, ChatGPT/Claude, localhost; unknown sites fall back to a generic page reference - always total, never lossy. Issues and parser PRs welcome.
+
+Built by [Nossa Iyamu](https://github.com/nossa-y), maker of [Nocta](https://usenocta.com). MIT.

activity_frames-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+activity_frames/__init__.py,sha256=Bbk3bXKB2eevMLpVQFnJcHPsfPmRd-CAIT49PLsaOVU,4206
+activity_frames/_time.py,sha256=3xv7tuAu1Tx5oHPKrl3rbmyEI1yIB0BYXoRDqjIgi5k,2782
+activity_frames/capture.py,sha256=SYdFKyZJ0E_Vljs8Jrfu1uhKU2Uzx0XH97PTXD8yu-w,8530
+activity_frames/cli.py,sha256=OVl_go2FwuqWQ46EIVPQIGfbxuL_J0-naZjIgqVbKcU,6015
+activity_frames/db.py,sha256=XYETa60ul6pP5dWspJsrUalqSAtnN-ksZQZSZD7CXLo,2772
+activity_frames/emit.py,sha256=85k3v_MiBoZEfhd3XzwYWlnz1VjEKFWnmusDA9v5kaU,4456
+activity_frames/enrich.py,sha256=Es0EG4l0bpyQpQjDkNHbagQdxM13XGJ8gEGiqvnQRVQ,12073
+activity_frames/entities.py,sha256=Q6YgYQmNRmC84XileGGd4RyUWPgY7bZrd353XhFl0IA,15264
+activity_frames/frames.py,sha256=wPsyn7t4AjyqAP5htL3Hgexitj2qhKgXBzmpXNlKb48,12204
+activity_frames/mcp_server.py,sha256=uMVX7cEtFM1qGVOJ3xwTwIEXek57Q0rI9p8Mk1mDHJY,9554
+activity_frames/patterns.py,sha256=Fu5P-Oy_jcAUJ-tpceE4ClFkkmRCw-CNFm9xt4_B2v0,8501
+activity_frames/sessionize.py,sha256=VeVvjA56dIVuX951D1hUxk-q6weFv7u2MJ08NAcfa50,11428
+activity_frames-0.1.0.dist-info/METADATA,sha256=6TefRRKfgkq3cfN8KuLwpL43TPnKJRcl4YAg52JUoms,8458
+activity_frames-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+activity_frames-0.1.0.dist-info/entry_points.txt,sha256=fEKkNTgoEHqxrztFm9ndhtjZl7a6mZf_yAg5GU-rHhg,53
+activity_frames-0.1.0.dist-info/licenses/LICENSE,sha256=jl2_onknQZ2IYcvTN_szF-T6A5ur8ZMM4tXawBVO20g,1068
+activity_frames-0.1.0.dist-info/RECORD,,

activity_frames-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

activity_frames-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aframes = activity_frames.cli:main

activity_frames-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nossa Iyamu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.