Neuroskill Bci

NeuroSkill BCI Integration

Connect Hermes to a running NeuroSkill 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

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).

Global Flags

1. Checking Current State

Get Live Metrics

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):

{
  "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

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

npx neuroskill sessions --json
npx neuroskill sessions --trends      # show per-session metric trends

3. Historical Search

Neural Similarity Search

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

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

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

npx neuroskill compare --json                   # auto: last 2 sessions
npx neuroskill compare --a-start <UTC> --a-end <UTC> --b-start <UTC> --b-end <UTC> --json

Returns metric deltas with absolute change, percentage change, and direction for ~50 metrics. Also includes insights.improved[] and insights.declined[] arrays, sleep staging for both sessions, and a UMAP job ID.

Interpret comparisons with context — mention trends, not just deltas:

"Yesterday you had two strong focus blocks (10am and 2pm). Today you've had one starting around 11am that's still going. Your overall engagement is higher today but there have been more stress spikes — your stress index jumped 15% and FAA dipped negative more often."

# Sort metrics by improvement percentage
npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'

5. Sleep Data

npx neuroskill sleep --json                     # last 24 hours
npx neuroskill sleep 0 --json                   # most recent sleep session
npx neuroskill sleep --start <UTC> --end <UTC> --json

Returns epoch-by-epoch sleep staging (5-second windows) with analysis:

• Stage codes: 0=Wake, 1=N1, 2=N2, 3=N3 (deep), 4=REM
• Analysis: efficiency_pct, onset_latency_min, rem_latency_min, bout counts
• Healthy targets: N3 15–25%, REM 20–25%, efficiency >85%, onset <20 min

npx neuroskill sleep --json | jq '.summary | {n3: .n3_epochs, rem: .rem_epochs}'
npx neuroskill sleep --json | jq '.analysis.efficiency_pct'

Use this when the user mentions sleep, tiredness, or recovery.

6. Labeling Moments

npx neuroskill label "breakthrough"
npx neuroskill label "studying algorithms"
npx neuroskill label "post-meditation"
npx neuroskill label --json "focus block start"   # returns label_id

Auto-label moments when:

• User reports a breakthrough or insight
• User starts a new task type (e.g., "switching to code review")
• User completes a significant protocol
• User asks you to mark the current moment
• A notable state transition occurs (entering/leaving flow)

Labels are stored in a database and indexed for later retrieval via search-labels and interactive commands.