project-lyra/docs/SCOUTING_DESK.md

The Scouting Desk — proactive poker recall + villain identity resolution

Design spec. Not built yet. Companion to the "she remembers" north star in the poker-copilot memory. Written 2026-07-03, before the trial-by-fire session.

Purpose

Turn the copilot from a logbook into a copilot that remembers across sessions, unprompted — the way a broadcast stats desk slides a note to the color commentator: "he mentioned the guy's hot streak → here are his last 10 games."

Target moments:

• "you had this exact leak last week too, remember?"
• "neck-tattoo guy just 3-bet you — last time he did that at the Meadows he had it."
• "Sleepy John was here two weeks ago; you stacked off AK into his set."

The failure mode to avoid at all costs: confident-but-wrong. A stats desk that guesses gets the commentator burned on air. Silence is the default; the desk speaks only when there's real signal.

What already exists (don't rebuild it)

mind.build_messages() already runs a recall pass on every message: memory.recall(user_msg) over past exchanges + memory.recall_summaries(user_msg) over session gists, injected as system notes before she replies. The "slide-a-note-in-before-she-speaks" machinery is already the architecture. This spec adds a poker desk to that pass — it does not build a new RAG system.

Episodic links also already exist: link_hand_players writes a player_observations row per named villain in a recorded hand, carrying hand_id AND session_id; player_reads carry session_id. So villain → observation → hand → session/date is reconstructable today.

Two retrieval channels (don't conflate them)

1. Entity desk — deterministic. A known name in the message → exact/fuzzy SQL match on poker_players → pull dossier + your history vs him. ~1ms, no hallucination. This is the "hears the name, pulls last 10 games" case.
2. Pattern desk — semantic. No entity to key on ("I keep punting these river bluffs") → embed the message, retrieve similar scar notes / hands / recap passages by meaning. This is where embeddings earn their keep. Also the backbone of nameless-villain matching (below).

Both feed one injected STATS DESK system note, relevance-gated.

The hard part: nameless villains

Most live villains have no name. Brian identifies them by physical descriptor ("guy with the lips/neck tattoo"), by seat ("seat 4", "two to my left"), or — uselessly — generically ("mid-aged white dude with glasses").

Current gap

poker_players.name is NOT NULL and identity is an exact name match (upsert_player → WHERE name = ?). The description column exists but is dead weight: not a key, not embedded, never matched. Nameless villains can't exist today. This is the core schema fix.

Identity model — descriptor as a fuzzy primary key

Store a villain as:

• name — now optional.
• descriptors — accumulated distinctive physical tags heard over time ("neck tattoo", "lips ink", "heavyset", "bald+beard").
• descriptor_embedding — embedding of the accumulated distinctive tags, for semantic match against drifting phrasings.
• venue — a strong disambiguator (the neck-tattoo reg at the Meadows ≠ the one at Wheeling, unless Brian travels).
• distinctiveness — a weight; distinctive features (tattoos, scars, a name) score high, generic ones (age/race/glasses) near zero.

Resolver — matching an incoming reference

1. Name present → exact/fuzzy SQL match (entity desk). Done.
2. Descriptor present → embed it, compare to descriptor_embedding of known villains scoped to the current venue, weighted by distinctiveness.
3. Confidence bands:
   • High (distinctive + strong match) → surface the file; if live, a light confirm ("the neck-tattoo LAG from 3 weeks ago?").
   • Medium/ambiguous (several candidates, or a middling score) → do NOT interrupt. File a needs_clarification task to the review queue and stay quiet, OR ask only if it's decision-relevant right now.
   • Generic-only (no distinctive signal) → refuse to guess. Stay silent or ask for one distinctive detail ("anything that stands out — ink, chips, how he plays?"). Wrong-guy citation is worse than nothing.
   • No match → new villain; open a descriptor-keyed dossier.

Seat = within-session alias only

The live session keeps a seat → villain map so reads accumulate whether Brian says "seat 4" or "the tattoo guy." Seats evaporate when the session ends — they mean nothing next week.

Confirmation loop (live, in chat)

Auto-merging on a fuzzy match is dangerous, so she proposes and Brian confirms in natural language:

Brian: "neck tattoo guy just 3-bet me again" Lyra: "The neck-tattoo LAG from the Meadows three weeks ago — the one who stacked you with the flush? Or new guy?" Brian: "yeah him" → reinforce identity · "nah different" → split, and learn what distinguishes them.

Handles name-arrives-later for free: catch his name off Bravo → "merge neck-tattoo guy into 'Danny'" → history follows.

The review interface (async, out-of-band)

Silence at the table ≠ forget it → it routes to a queue Brian clears at his pace.

/players — villain file browser

List: name-or-lead-descriptor, venue, category (feeder/risky/reg), hands observed, VPIP/PFR (when sample is real), last seen, distinctive tags. Detail view: reads, showdowns, notable hands (link to /hand/{id}), sessions seen, stats. Edit / rename / retag / delete / manual-merge.

Resolution queue — two lanes

• Possible merges — two profiles likely one person (high descriptor similarity + same venue, below auto-merge). Side-by-side → Same guy (merge) / Different (split).
• Needs clarification — a descriptor that matched several candidates, or a nameless villain the resolver couldn't place → pick match / New guy.

Two rules that keep the queue from rotting

1. A rejected merge stays rejected — record the pair as known-distinct so it never re-surfaces; start tracking the distinguishing tell.
2. Merge-candidate scan runs in the dream cycle, not the hot path — nightly, compare descriptor embeddings within each venue, file new maybes. Zero live latency.

Injection format & gating

A single system note, clearly marked as structured fact so she cites it (not confabulates), e.g.:

STATS DESK — Neck-tattoo guy (Meadows, LAG/reg): seen 3×, last 2wk ago.
  vs you: hand #38 (AK, stacked off into his set). Reads: overfolds turn,
  3-bets light from the CO. Sample: 22 hands — VPIP 41 / PFR 28.

Gate hard: inject only on a confident entity hit or a strong semantic score. Default to nothing. Never inject a generic-only guess.

Honest limits

Never perfect. Some players are genuinely indistinguishable — fine. The system's only job: right when there's signal, quiet when there isn't.

New data model (sketch)

• poker_players: name → nullable; add descriptors TEXT, descriptor_embedding BLOB, distinctiveness REAL.
• player_distinct_pairs(a_id, b_id, note, created_at) — rejected merges.
• identity_queue(id, kind, player_ids, descriptor, context, session_id, confidence, status, resolution, created_at) — kind ∈ {merge_candidate, needs_clarification}.
• Live-session seat → player_id alias map (in-session only).

Sequencing (after the trial-by-fire session — recall feeds on real data)

1. Nameless identity + resolver — schema, descriptor embedding, venue-scoped semantic match, distinctiveness gate. (Unblocks everything.)
2. Scouting-desk injection — wire entity + pattern recall into build_messages as the gated STATS DESK note.
3. Confirmation loop — the live propose/confirm/merge/split UX in the persona.
4. /players browser + resolution queue UI — the async review interface.
5. Dream-cycle merge scan — nightly candidate generation.
6. Pattern desk — semantic recall over scars/notes/recaps for "this leak again."