# HBM — Hierarchical Briefing Model (v0.1) **Status:** Deferred to Phase 7 (2026-04-28) **Author:** Daedalus (UX/Design Architecture) **Date:** 2026-04-27 **Blocker:** Resolved — Wadsworth review complete, scope deferred **Next Review:** Phase 7 planning — LLM token efficiency (local vs cloud) --- ## Phase 7 Placement Justification **Deferred from Phase 6 (2026-04-28):** - Phase 6 already has 5 major pillars (Document Intelligence, IMAP Ingress, Drop Zone, Finance Intelligence, Brain Query) - HBM requires mature Event Graph (still building in Phase 6) - Cognitive layer (Briefing Agent) adds significant complexity - LLM cost optimization needed before daily generation commitment **Recommended Phase 7 Entry:** After Event Graph proven stable and multi-user sync validated --- ## Pre-Phase 7 Requirements Before implementing HBM, complete: | Requirement | Owner | Validation | |-------------|-------|------------| | Event Graph maturity | Socrates | 30 days stable operation | | Multi-user state sync | Socrates | Aundrea + Matt concurrent use | | LLM token efficiency review | Wadsworth | Local vs cloud cost analysis | | Caching strategy | Socrates | Cache hit rate >80% | --- ## Wadsworth Review Summary (2026-04-28) ### Approved Architecture - **Scheduler:** Extend heartbeat (no new cron) - **State Management:** States in Event Graph with `state_last_updated` - **Fallback:** Simplified extraction on failure, not previous day - **Conflict Detection:** Keep real-time, surface in DayBrief - **Multi-user:** Nightly regeneration picks up state changes ### Modifications Required - **Phase entry:** Start with Week Brief only (aggregation), defer Day/Hour Agent - **Notification timing:** Evening-only (21:30) first, add morning if validated - **Timezone:** Configurable per household (not hardcoded UTC) - **Caching:** Cache DayBrief until Event Graph changes ### Cost Analysis (Pending Phase 7) - Daily Briefing Agent: ~$0.02-0.05 (GLM-5.1 cloud) - Monthly estimate: $0.60-1.50 - **Review required:** Local model costs (Gaming PC) vs cloud --- ## Overview The Hierarchical Briefing Model (HBM) defines the data structures and generation pipeline for the Family Assistant's four-level brief hierarchy: Month, Week, Day, Hour. Built on cognitive psychology research (prospective memory, implementation intentions, cognitive offloading). **Core Principle:** Ingestion stays clean. Cognition is a separate, nightly layer. --- ## Architecture Decision: Clean Separation ``` ┌─────────────────────────────────────────────────────────────────┐ │ DATA LAYER │ │ Event Graph — clean ingestion from all sources (real-time) │ │ Entities: events, people, locations, materials, states │ └─────────────────────────────────────────────────────────────────┘ │ ▼ (22:00 UTC nightly trigger) ┌─────────────────────────────────────────────────────────────────┐ │ COGNITION LAYER │ │ Briefing Agent — generates cognitive artifacts from Event Graph│ │ Month/Week: pattern aggregation (no Agent needed) │ │ Day/Hour: When/Then chains, forgetting budget, scripts │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ PRESENTATION LAYER │ │ HTMX templates: month_grid.html, week_deck.html, │ │ day_chain.html, hour_detail.html │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Data Structures ### 1. Event Graph (Ingestion Output) ```yaml Event: id: uuid source: calendar|email|sms|voice|manual title: string # raw extracted title start_time: ISO8601 end_time: ISO8601 | null participants: - person_id: uuid role: primary|secondary|optional confirmed: bool location: name: string address: string | null lat: float | null lon: float | null materials: [string] # things to bring prep_tasks: [Task] # things to do before states: # dynamic, updated in real-time permission_slip: pending|signed|n/a lunch_required: bool car_seat_needed: bool penalty_score: 1-10 # forgetting cost (auto-calculated) anchor_weight: 1-10 # structural importance to day Task: id: uuid description: string trigger_event_id: uuid | null # if chained trigger_type: absolute_time | event_start | event_end | state_change due_time: ISO8601 | null completed: bool delegated_to: person_id | null ``` ### 2. Month Brief (Pattern Layer) **Generation:** Pure aggregation on Event Graph. No Agent. ```yaml MonthBrief: month: YYYY-MM days: - date: YYYY-MM-DD commitment_count: int anchor_present: bool pattern_density: light|medium|heavy|redline has_conflict: bool family_states_touched: [FamilyState] # which transition windows hit ``` **Visual:** 28-dot heatmap. No text. ### 3. Week Brief (Pattern + Anchor Layer) **Generation:** Pure aggregation on Event Graph. No Agent. ```yaml WeekBrief: week_start: YYYY-MM-DD days: - date: YYYY-MM-DD anchor_event: EventSummary | null # the structural anchor commitment_count: int pattern_density: light|medium|heavy|redline conflict_count: int high_penalty_tasks: [TaskSummary] # top 3 by penalty_score EventSummary: id: uuid title: string time_range: "08:15 – 14:30" location: string participants: [string] # first names only ``` **Visual:** 7 horizontal cards. Anchor event prominent. Red dots for conflicts. ### 4. Day Brief (Cognition Layer — Agent Generated) **Generation:** Briefing Agent runs at 22:00 UTC. Reads Event Graph for next 36h. Outputs DayBrief. ```yaml DayBrief: date: YYYY-MM-DD generated_at: ISO8601 family_state: FamilyState # which window this day sits in anchor_event: EventSummary | null # the structural anchor forgetting_budget: active_commitments: int # events + uncompleted prep_tasks budget_threshold: int = 8 # configurable per household status: green|yellow|redline warning: string | null # shown if redline when_then_chains: [WhenThenChain] # the implementation intentions high_penalty_alerts: [Alert] # surfaced first, top of brief ambient_gist: string # 10-word summary for evening glance FamilyState: name: launch_phase|deep_work|the_pivot|wind_down window_start: HH:MM window_end: HH:MM cognitive_priority: high_penalty|ambient_gist|high_coordination|encoding WhenThenChain: id: uuid sequence: int # order in chain trigger: type: state_change | time | event_start | event_end description: string # "When coffee is done..." state_check: string | null # "check if permission_slip == signed" action: description: string # "...then check lunchbox is in backpack" material_check: [string] | null # ["lunchbox", "backpack"] location_hint: string | null fallback: description: string | null # if trigger fires but state wrong escalation: person_id | null # who to notify Alert: id: uuid severity: high|medium|low title: string action_script: WhenThenChain # full script to resolve location_hint: string | null material_check: [string] | null ``` **Visual:** When/Then chain as vertical timeline. Forgetting budget gauge at top. High-penalty alerts in red banner. ### 5. Hour Brief (Detail Layer — On Tap) **Generation:** Briefing Agent pre-generates, but fetched on-demand from DayBrief.hour_details. ```yaml HourDetail: event_id: uuid generated_at: ISO8601 full_action_script: target: string # what we're doing action_steps: [string] # step-by-step materials: [string] # what to bring fallback_plan: string | null # if primary fails expected_duration: int # minutes parking_hint: string | null checkin_procedure: string | null # "sign in at front desk" contact_on_site: string | null dependencies: must_complete_before: [Task] # from Event.prep_tasks blocked_by: [uuid] | null # other events this depends on coordination_notes: who_picks_up: person_id | null who_drops_off: person_id | null carpool_optimization: [person_id] | null ``` **Visual:** Collapsible detail panel. Materials checklist. Map embed. Contact card. --- ## Briefing Agent Specification ### Trigger - **Schedule:** 22:00 UTC daily - **Data window:** Next 36 hours (tonight + tomorrow + tomorrow evening) - **Input:** Event Graph (all sources, latest state) - **Output:** DayBrief + HourDetails (written to briefing store) ### Generation Logic ``` 1. Identify FamilyState for target date (from time-of-day + day-of-week patterns) 2. Find anchor_event (highest anchor_weight, or first high-penalty event) 3. Calculate forgetting_budget (active_commitments vs threshold) 4. Build when_then_chains: - Start from anchor_event, work backward - For each prep_task, create chain linking to previous state - Add material_check hints where spatial memory helps - Add fallback for each high-penalty item 5. Generate high_penalty_alerts (anything with penalty_score >= 7) 6. Draft ambient_gist (10 words, evening-glance optimized) 7. Pre-generate HourDetails for all anchor_event + high_penalty events ``` ### LLM Prompt Structure (Draft) ``` You are the Briefing Agent. Generate a DayBrief for {date} based on the Event Graph below. CONTEXT: - FamilyState for this date: {family_state} - Anchor event: {anchor_event} - Active commitments: {count} - Budget threshold: 8 - Current states: {event_states} EVENT GRAPH (next 36h): {events_json} OUTPUT: Generate a DayBrief with: 1. forgetting_budget calculation 2. when_then_chains (minimum 3, maximum 6 chains) 3. high_penalty_alerts (include action_script for each) 4. ambient_gist (exactly 10 words) Format: YAML matching HBM spec. ``` --- ## Integration Points (Wadsworth Review Required) ### 1. Scheduler Integration - **New cron job:** `briefing-generator` at 22:00 UTC - **Dependencies:** Event Graph must be up-to-date (requires calendar sync completion) - **Retry logic:** If generation fails, fall back to previous day's DayBrief with warning banner ### 2. Notification Routing - **Evening Glance:** Telegram message at 21:30 UTC with ambient_gist + link to DayBrief - **Morning Brief:** Telegram message at 06:00 UTC (or configurable) with DayBrief summary - **Conflict Nag:** Real-time as conflicts emerge, not batched ### 3. Cross-Agent Dependencies - **Socrates:** Implements ingestion pipeline, Event Graph, Briefing Agent - **Wadsworth:** Implements scheduler, notification routing, retry logic - **Daedalus:** Implements presentation templates (HTMX), visual design ### 4. API Endpoints Required ``` GET /family/brief/month/{YYYY-MM} GET /family/brief/week/{YYYY-MM-DD} # week start date GET /family/brief/day/{YYYY-MM-DD} GET /family/brief/hour/{event_id} POST /family/brief/regenerate/{YYYY-MM-DD} # manual trigger (admin only) ``` --- ## Open Questions for Wadsworth Review 1. **Conflict Detection:** Should this run continuously or as part of Briefing Agent? (Real-time vs nightly tradeoff) 2. **State Management:** Where do event states live? (Event Graph vs separate state store) 3. **Retry/Fallback:** If Briefing Agent fails at 22:00, what's the 06:00 fallback? (Previous day brief vs error state vs simplified version) 4. **Multi-User Coordination:** If Aundrea marks a task complete at 21:45, does Matt's 22:00 brief regenerate? 5. **Resource Budget:** Briefing Agent runs LLM call daily. Acceptable cost? Cache strategy? --- ## Files to Create | File | Owner | Purpose | |------|-------|---------| | `shared/api-specs/hbm-data-model.yaml` | Socrates | Canonical spec | | `family/briefing.py` | Socrates | Briefing Agent logic | | `family/briefing_routes.py` | Socrates | API endpoints | | `family/templates/month_grid.html` | Daedalus | Month view | | `family/templates/week_deck.html` | Daedalus | Week view | | `family/templates/day_chain.html` | Daedalus | Day view | | `family/templates/hour_detail.html` | Daedalus | Hour detail panel | | `cron/briefing_generator.sh` | Wadsworth | Scheduler entry | --- ## References - Peper, Alakbarova, & Ball (2022). Benefits From Prospective Memory Offloading Depend on Memory Load and Reminder Type. *Journal of Experimental Psychology: Learning, Memory, and Cognition.* - Gollwitzer (1999). Implementation intentions: Strong effects of simple plans. *American Psychologist.* - Risko & Gilbert (2016). Cognitive Offloading. *Trends in Cognitive Sciences.* --- ## Blocker Statement **Status:** Resolved — Wadsworth review complete (2026-04-28) **Phase:** Deferred to Phase 7 (per Director approval) **Next Action:** LLM token efficiency review before Phase 7 entry **Blocker History:** - 2026-04-27: Spec drafted, Wadsworth review required - 2026-04-28: Review complete, scope deferred to Phase 7 **Key Review Decisions:** - ✅ Scheduler: Extend heartbeat (no new cron) - ✅ State management: Event Graph with `state_last_updated` - ✅ Fallback: Simplified extraction on failure - ⚠️ Notification: Evening-only first (21:30), morning if validated - ⚠️ Phase placement: Phase 7 (not Phase 6) **Pre-Implementation Requirements:** 1. Event Graph 30-day stability 2. Multi-user state sync validated 3. LLM token efficiency review (local vs cloud) 4. Phase 6 UAT complete --- ## References - Peper, Alakbarova, & Ball (2022). Benefits From Prospective Memory Offloading Depend on Memory Load and Reminder Type. *Journal of Experimental Psychology: Learning, Memory, and Cognition.* - Gollwitzer (1999). Implementation intentions: Strong effects of simple plans. *American Psychologist.* - Risko & Gilbert (2016). Cognitive Offloading. *Trends in Cognitive Sciences.*