neuroskill-bci – skill Khác cho agent AI

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

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

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 <UT

… (nội dung đầy đủ có trong gói tải về)