neuroskill-bci

Connect to a running NeuroSkill instance and incorporate the user's real-time cognitive and emotional state (focus, relaxation, mood, cognitive load, drowsiness, heart rate, HRV, sleep staging, and 40+ derived EXG scores) into responses. Requires a BCI wearable (Muse 2/S or OpenBCI) and the NeuroSkill desktop app running locally.

# NeuroSkill BCI Integration

Connect Hermes to a running [NeuroSkill](https://neuroskill.com/) instance to read
real-time brain and body metrics from a BCI wearable. Use this to give
cognitively-aware responses, suggest interventions, and track mental performance
over time.

> **⚠️ Research Use Only** — NeuroSkill is an open-source research tool. It is
> NOT a medical device and has NOT been cleared by the FDA, CE, or any regulatory
> body. Never use these metrics for clinical diagnosis or treatment.

See `references/metrics.md` for the full metric reference, `references/protocols.md`
for intervention protocols, and `references/api.md` for the WebSocket/HTTP API.

---

## Prerequisites

- **Node.js 20+** installed (`node --version`)
- **NeuroSkill desktop app** running with a connected BCI device
- **BCI hardware**: Muse 2, Muse S, or OpenBCI (4-channel EEG + PPG + IMU via BLE)
- `npx neuroskill status` returns data without errors

### Verify Setup
```bash
node --version                    # Must be 20+
npx neuroskill status             # Full system snapshot
npx neuroskill status --json      # Machine-parseable JSON
```

If `npx neuroskill status` returns an error, tell the user:
- Make sure the NeuroSkill desktop app is open
- Ensure the BCI device is powered on and connected via Bluetooth
- Check signal quality — green indicators in NeuroSkill (≥0.7 per electrode)
- If `command not found`, install Node.js 20+

---

## CLI Reference: `npx neuroskill <command>`

All commands support `--json` (raw JSON, pipe-safe) and `--full` (human summary + JSON).

| Command | Description |
|---------|-------------|
| `status` | Full system snapshot: device, scores, bands, ratios, sleep, history |
| `session [N]` | Single session breakdown with first/second half trends (0=most recent) |
| `sessions` | List all recorded sessions across all days |
| `search` | ANN similarity search for neurally similar historical moments |
| `compare` | A/B session comparison with metric deltas and trend analysis |
| `sleep [N]` | Sleep stage classification (Wake/N1/N2/N3/REM) with analysis |
| `label "text"` | Create a timestamped annotation at the current moment |
| `search-labels "query"` | Semantic vector search over past labels |
| `interactive "query"` | Cross-modal 4-layer graph search (text → EXG → labels) |
| `listen` | Real-time event streaming (default 5s, set `--seconds N`) |
| `umap` | 3D UMAP projection of session embeddings |
| `calibrate` | Open calibration window and start a profile |
| `timer` | Launch focus timer (Pomodoro/Deep Work/Short Focus presets) |
| `notify "title" "body"` | Send an OS notification via the NeuroSkill app |
| `raw '{json}'` | Raw JSON passthrough to the server |

### Global Flags
| Flag | Description |
|------|-------------|
| `--json` | Raw JSON output (no ANSI, pipe-safe) |
| `--full` | Human summary + colorized JSON |
| `--port <N>` | Override server port (default: auto-discover, usually 8375) |
| `--ws` | Force WebSocket transport |
| `--http` | Force HTTP transport |
| `--k <N>` | Nearest neighbors count (search, search-labels) |
| `--seconds <N>` | Duration for listen (default: 5) |
| `--trends` | Show per-session metric trends (sessions) |
| `--dot` | Graphviz DOT output (interactive) |

---

## 1. Checking Current State

### Get Live Metrics
```bash
npx neuroskill status --json
```

**Always use `--json`** for reliable parsing. The default output is colorized
human-readable text.

### Key Fields in the Response

The `scores` object contains all live metrics (0–1 scale unless noted):

```jsonc
{
  "scores": {
    "focus": 0.70,           // β / (α + θ) — sustained attention
    "relaxation": 0.40,      // α / (β + θ) — calm wakefulness
    "engagement": 0.60,      // active mental investment
    "meditation": 0.52,      // alpha + stillness + HRV coherence
    "mood": 0.55,            // composite from FAA, TAR, BAR
    "cognitive_load": 0.33,  // frontal θ / temporal α · f(FAA, TBR)
    "drowsiness": 0.10,      // TAR + TBR + falling spectral centroid
    "hr": 68.2,              // heart rate in bpm (from PPG)
    "snr": 14.3,             // signal-to-noise ratio in dB
    "stillness": 0.88,       // 0–1; 1 = perfectly still
    "faa": 0.042,            // Frontal Alpha Asymmetry (+ = approach)
    "tar": 0.56,             // Theta/Alpha Ratio
    "bar": 0.53,             // Beta/Alpha Ratio
    "tbr": 1.06,             // Theta/Beta Ratio (ADHD proxy)
    "apf": 10.1,             // Alpha Peak Frequency in Hz
    "coherence": 0.614,      // inter-hemispheric coherence
    "bands": {
      "rel_delta": 0.28, "rel_theta": 0.18,
      "rel_alpha": 0.32, "rel_beta": 0.17, "rel_gamma": 0.05
    }
  }
}
```

Also includes: `device` (state, battery, firmware), `signal_quality` (per-electrode 0–1),
`session` (duration, epochs), `embeddings`, `labels`, `sleep` summary, and `history`.

### Interpreting the Output

Parse the JSON and translate metrics into natural language. Never report raw
numbers alone — always give them meaning:

**DO:**
> "Your focus is solid right now at 0.70 — that's flow state territory. Heart
> rate is steady at 68 bpm and your FAA is positive, which suggests good
> approach motivation. Great time to tackle something complex."

**DON'T:**
> "Focus: 0.70, Relaxation: 0.40, HR: 68"

Key interpretation thresholds (see `references/metrics.md` for the full guide):
- **Focus > 0.70** → flow state territory, protect it
- **Focus < 0.40** → suggest a break or protocol
- **Drowsiness > 0.60** → fatigue warning, micro-sleep risk
- **Relaxation < 0.30** → stress intervention needed
- **Cognitive Load > 0.70 sustained** → mind dump or break
- **TBR > 1.5** → theta-dominant, reduced executive control
- **FAA < 0** → withdrawal/negative affect — consider FAA rebalancing
- **SNR < 3 dB** → unreliable signal, suggest electrode repositioning

---

## 2. Session Analysis

### Single Session Breakdown
```bash
npx neuroskill session --json         # most recent session
npx neuroskill session 1 --json       # previous session
npx neuroskill session 0 --json | jq '{focus: .metrics.focus, trend: .trends.focus}'
```

Returns full metrics with **first-half vs second-half trends** (`"up"`, `"down"`, `"flat"`).
Use this to describe how a session evolved:

> "Your focus started at 0.64 and climbed to 0.76 by the end — a clear upward trend.
> Cognitive load dropped from 0.38 to 0.28, suggesting the task became more automatic
> as you settled in."

### List All Sessions
```bash
npx neuroskill sessions --json
npx neuroskill sessions --trends      # show per-session metric trends
```

---

## 3. Historical Search

### Neural Similarity Search
```bash
npx neuroskill search --json                    # auto: last session, k=5
npx neuroskill search --k 10 --json             # 10 nearest neighbors
npx neuroskill search --start <UTC> --end <UTC> --json
```

Finds moments in history that are neurally similar using HNSW approximate
nearest-neighbor search over 128-D ZUNA embeddings. Returns distance statistics,
temporal distribution (hour of day), and top matching days.

Use this when the user asks:
- "When was I last in a state like this?"
- "Find my best focus sessions"
- "When do I usually crash in the afternoon?"

### Semantic Label Search
```bash
npx neuroskill search-labels "deep focus" --k 10 --json
npx neuroskill search-labels "stress" --json | jq '[.results[].EXG_metrics.tbr]'
```

Searches label text using vector embeddings (Xenova/bge-small-en-v1.5). Returns
matching labels with their associated EXG metrics at the time of labeling.

### Cross-Modal Graph Search
```bash
npx neuroskill interactive "deep focus" --json
npx neuroskill interactive "deep focus" --dot | dot -Tsvg > graph.svg
```

4-layer graph: query → text labels → EXG points → nearby labels. Use `--k-text`,
`--k-EXG`, `--reach <minutes>` to tune.

---

## 4. Session Comparison
```bash
npx neuroskill compare --json                   # auto: last 2 sessions
npx neuroskill compare --a