personal-model AGENTS.md

AGENTS.md

Orientation for coding agents in persome-core. Code is authoritative; the documents explain its public contract and operational intent.

Runtime boundary

Persome Runtime is a local-first macOS daemon that observes one real person's screen context, forms durable state, builds an auditable personal model, and serves it to MCP clients. The public geometry is Point, Line, Face, Volume, and at most one Root. /model renders the current geometry locally.

This repository owns:

• AX capture and optional, local, subprocess-isolated OCR;
• timeline and deterministic session formation;
• incremental session reduction and personal modeling;
• Markdown/SQLite/evomem storage, provenance, correction, and forgetting;
• the versioned model snapshot, local viewer, REST, and MCP.

It does not own product dashboards, notification/task lifecycles, computer-use actuation, meeting audio, or evaluation datasets and runners.

• macOS 13+ for live capture; Python 3.12-3.13 via uv.
• Package: src/persome/; CLI: persome = "persome.cli:app".
• Default data root: ~/.persome.

Commands

uv sync --all-extras
bash install.sh

PERSOME_LLM_MOCK=1 uv run pytest -m "not macos and not integration"
uv run ruff check .
uv run ruff format --check .
uv run python scripts/secret_scan.py
uv run python scripts/pii_scan.py
uv run python scripts/language_scan.py

persome doctor
persome llm setup
persome llm status --check
persome start
persome status
persome stop
persome update
persome mcp
persome model build
persome model status
persome model export

Regenerate committed contracts after intentional changes:

uv run python scripts/regen_openapi.py
uv run python scripts/regen_db_schema.py
uv run pytest tests/test_openapi_drift.py tests/test_db_schema_drift.py -q

Commits require DCO sign-off: git commit -s.

Pipeline

There is one production path:

mac-ax-watcher or trusted ingest
  -> S0 debounce/dedup
  -> S1 focused element + visible text + URL
  -> capture buffer
  -> one-minute timeline blocks
  -> deterministic session cuts
  -> five-minute active reducer / event memory
  -> incremental Point/Line modeling
  -> session-end trailing-window finalizer
       -> classifier compatibility/incremental pass
       -> pattern detector
       -> evidence-gated memory_delta + deterministic apply
  -> debounced/daily/explicit structural model build
       -> cases -> Faces -> Volumes -> Root
  -> snapshot / MCP / localhost viewer