07_Relevance_Scoring.md
Manual – Relevance Scoring and Persistence of Memory
1) Purpose: Why some memories persist
Reggie doesn’t “remember everything.” He maintains context buckets where events decay or rise in importance based on their relevance score.
The scoring system determines which events stay top-of-mind and which fade quietly.
Relevance combines recency, frequency, impact, and risk to emulate how human attention works.
2) The human analogy
Think of it as cognitive triage. Humans forget unimportant details but remember repeated or serious issues.
Reggie’s mind works the same way—using numbers instead of neurons.
- Frequent events → strengthened connections.
- Severe outcomes → higher urgency.
- Recent events → fresh in memory.
- Resolved unrepeating or retired items → drift into the past.
3) Core factors
| Factor | Meaning | Range | Notes |
|---|---|---|---|
| Severity (S) | How serious the impact is | 1–5 | From Reason Log risks.severity |
| Frequency (F) | How often it has occurred | 1+ | Incremented on repeats |
| Repeatable (R) | Can it happen again? | 0/1 | Flipped when participant/asset retires |
| Decay (D) | How long ago it occurred | 0–1 | Reduces daily (like forgetting) |
| Family Boost (B) | How linked repeats lift each other | 1–2 | Encourages clusters to persist |
Formula (core):
current = (S × F) × D × R × B
4) Extended signals
Reggie can also consider richer signals to capture nuance:
| Extra Metric | Purpose |
|---|---|
| Financial impact | Prioritize high-dollar anomalies |
| Safety/compliance risk | Keep potential harm visible |
| Urgency / SLA risk | Elevate near-deadline problems |
| Sentiment | React to negative customer tone |
| Exposure | Weight by number of people affected |
| Confidence | Down-weight uncertain data |
| Reversibility | Boost if costly to undo |
| Spread | Multi-domain issues rise faster |
| Trend & Velocity | Detect growing patterns |
These are combined through configurable weights that can be tuned in Admin Settings.
5) Daily rhythm – the “sleep cycle”
Each day, Reggie performs a decay pass on his memories:
decay = decay × 0.98
current = base × decay × repeatable × family_boost
This mimics forgetting. Frequent or severe issues maintain their score through repeats or high base severity.
6) Why Reason-Tags matter
Every event or bucket entry must carry its Reason-Tag.
That’s how Reggie ties cause and effect:
- “Bob’s billing dropped” → Finance bucket entry.
- Reason-Tag → “Bob cancelled Saturday program.”
- Cause and consequence stay connected forever.
Without Reason-Tags, Reggie would know what happened but not why.
7) Example narrative
“I’m still keeping an eye on the Wednesday bus because it’s had three late departures this month and one safety complaint.”
Under the hood:
Severity=4, Frequency=3, Decay=0.9, Repeatable=1, FamilyBoost=1.2 → current=12.96
If the issue doesn’t repeat, decay will lower it by 2% daily until it leaves the top 20 list.
8) Transparency & safety
- Scores are explainable: each component can be shown in plain English.
- Users can see why something ranks highly.
- Privacy: Reason Logs and bucket events redact sensitive fields; Reggie’s narration only exposes what the user’s role allows.
9) Tuning weights (Admin)
Admins can adjust the influence of each factor via a slider interface linked to agent_score_weights:
| Key | Default | Description |
|---|---|---|
| w_fin | 0.2 | Financial impact |
| w_safety | 0.3 | Safety/compliance |
| w_urg | 0.3 | Urgency |
| w_sent | 0.1 | Sentiment negativity |
| w_exp | 0.2 | Exposure breadth |
| w_conf | 0.3 | Confidence dampening |
| w_rev | 0.2 | Reversibility boost |
Adjusting these values reshapes Reggie’s focus dynamically.
10) Relationship to dashboards
The Top Issues dashboard is driven by the scoring engine:
agent_top_issues materialized view sorts by current descending.
When you ask “What are our biggest problems this week?”, Reggie’s answer comes from this ranked list.
11) Maintenance and auditing
- Decay job: runs nightly.
- Repeat boost: triggered on new linked events.
- Weights table: editable via Admin UI.
- Logs: all changes to weights and decay factors are auditable in
agent.reasonlog.
End of chapter