Email Guy

The biggest architectural split. preferences.json is raw training data: every swipe, metadata, correction notes. Lives at ~/.config/email-swipe/ via serve-ui.py.

training-pack.json is the agent-facing artifact — compact, curated, privacy-aware. Few-shot examples, watch rules, safe platform candidates, runtimeGuidance. The agent reads this at runtime, not a noisy swipe log. Contract is explicit in SKILL.md, analyze-preferences.py, and watch-preferences.py.

Lossy compression in the right direction: ~12 diverse examples plus stable rules and caveats — not 500 raw swipes stuffed into context every run.

Swipes compile into abstractions, not just stored history. One pass produces:

• training-pack.json — primary runtime artifact (examples + guidance)
• agent-watchlist.json — Needs Attention rules, urgent keywords, inconsistent-sender warnings
• platform-rules.json — label/star suggestions; preservesInbox: true, autoApply: false
• folder-suggestions.json — organizational proposals within folder budget
• analysis-summary.json — human-readable digest for the agent's next conversation turn

select_diverse_examples() picks representative decisions — not brittle prompt stuffing, a small domain model compiled from behavior.

Examples store the user's actual decision and optional correction note. No fabricated post-hoc reasoning — the system stays honest about what it knows.

Mixed decisions on the same sender/domain become inconsistentSenders. That's a better agent signal than pretending every pattern is clean.

runtimeGuidance ships with the pack: token budget advice, never auto-delete, never skip inbox without approval. Memory encodes preferences and safe agent behavior constraints.

Queue is active-learning-ish, not chronological. scoreEmailForQueue() ranks by uncertainty and urgency — prior swipes by domain, keyword hints (urgent, action required, etc.). Next best training example surfaces first; you teach faster.

Inline hints calibrate trust in real time:

• High confidence → “Similar to 3 you marked spam”
• Low confidence → “Help me learn this one”

Adapts without pretending it knows more than it does.

detectBatchOpportunity() never auto-batches. Batch spam is offered only when all three conditions hold:

• You manually marked one email from the domain as spam
• Remaining unswiped mail shares that sender domain
• The model would independently predict spam (confidence ≥ threshold)

Earned shortcut — magic through trust calibration, not reckless automation.

Session end closes the learning loop, not just UI polish:

• Pile breakdown (spam / keep / important counts)
• Grades scorable predictions against what you actually swiped
• Surfaces misses while context is fresh
• Captures correction notes → feeds the next compile

Review happens at the moment you still remember why you swiped — better training data, not a throwaway animation.

Artifact is shaped for operational cost, not just storage. Agent runtime:

1. Fetch inbox metadata only (from, subject, date, id)
2. Local rule match from platform-rules.json — no LLM
3. Watchlist pre-filter (keywords, senders, inconsistent-sender flags)
4. LLM only for remaining Needs Attention candidates

Two execution tiers: Platform (label suggestions, zero ongoing tokens) vs Agent (reasoning layer, scoped LLM). Agent reads training-pack.json + analysis-summary.json, not full swipe history.

Platform rules are suggest_only — labels and stars OK; skipping inbox is not. Needs Attention is agent-managed reasoning, not a hidden Gmail filter. Mail stays visible until you act.

Helpful automation without silent control loss. Inbox is sacred.

• UI layer — captures actions; IndexedDB in browser; serve-ui.py persists to ~/.config/email-swipe/preferences.json. UI never calls email APIs directly.
• Compiler layer — import-preferences.py + analyze-preferences.py derives all memory artifacts
• MCP layer — watch-preferences.py exposes get_training_pack, get_watch_rules; distilled artifact only

baseline-predictions.js — heuristic cold start from email #1; learned behavior takes over as swipes accumulate. Export falls back to download if local save unavailable; compiler runs from preferences if pack doesn't exist yet.

Minimal UI settings, richer chat context: job/goals live in agent conversation, not a bloated settings form — stable memory schema, flexible use cases.