# Hotspot Memory Layer

## Purpose

This layer stores durable context that future Codex, Claude, Hermes, or agent
team workers should remember before changing the hotspot scanner.

## Canonical Memory

Primary memory file:

- `docs/hotspot_memory.md`

This file records:

- current objective
- working assumptions
- feature hypotheses
- harness decisions
- open questions
- next safe step

## Current Memory State

- The scanner is experimental but already wired into the web through
  `/api/stock/hotspots`.
- Web reads `docs/full_market_hotspots.json`; it should not scan the full market
  during a user request.
- The current visible web artifact may be a small smoke set until the full
  120-trading-day institutional cache is backfilled.
- `data/institutional_flow_cache.py` is the durable cache layer for future
  foreign/trust/dealer/institutional 120-day data.
- Unvalidated hotspot scores are observation lists, not BUY/SELL production
  changes.

## Update Rule

When a worker changes the scanner, append a short note to
`docs/hotspot_memory.md` only if the change affects:

- scoring assumptions
- validation gates
- daily runbook
- production/HF/Hermes integration status
- known data gaps or failures

Do not paste long logs. Link to JSON/HTML artifacts instead.