neuroskill-search

name	neuroskill-search
description	NeuroSkill `search` and `compare` commands — ANN search for neurally similar EEG moments across all history, and A/B session comparison with metric deltas, trend directions, and UMAP enqueuing. Use when finding similar past brain states or comparing two recording sessions.

NeuroSkill search and compare Commands

---

LLM Tool Calls

When calling these commands via the LLM skill tool, use command + args:

{"command": "search", "args": {"start_utc": 1740412800, "end_utc": 1740415500, "k": 5}}
{"command": "compare", "args": {"a_start_utc": 1740380100, "a_end_utc": 1740382665, "b_start_utc": 1740412800, "b_end_utc": 1740415510}}

Cross-Modal Follow-Ups

After a search returns neighbor timestamps, you can bridge to other modalities:

• See what was on screen at a neural-search hit: {"command": "screenshots_around", "args": {"timestamp": <neighbor_timestamp_unix>}}
• Find labels near a neural-search hit: {"command": "search_labels", "args": {"query": "focus"}} filtered by time
• Full graph search from a text description to EEG to labels: {"command": "interactive_search", "args": {"query": "deep focus"}}

---

search — Neural Similarity Search

Find EEG moments from your entire history that are neurally similar to a query range. Uses approximate nearest-neighbor (ANN) search over the 5-second embedding HNSW index.

Auto-range: when no --start/--end flags are given, the CLI automatically uses your most recent session and prints a rerun: line you can copy-paste.

npx neuroskill search                                     # auto: last session, k=5
npx neuroskill search --k 10                             # 10 nearest neighbors
npx neuroskill search --start 1740412800 --end 1740415500
npx neuroskill search --start 1740412800 --end 1740415500 --k 20
npx neuroskill search --json | jq '.result.results | length'
npx neuroskill search --json | jq '.result.results[0].neighbors[0]'

HTTP (daemon API):

curl -s -X POST http://127.0.0.1:$PORT/v1/search/eeg \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUtc":1740412800,"endUtc":1740415500,"k":5}'

JSON Response

{
  "command": "search",
  "ok": true,
  "result": {
    "query_count": 541,
    "searched_days": ["20260224", "20260223"],
    "analysis": {
      "distance_stats": { "min": 0.0231, "mean": 0.1842, "max": 0.3901, "stddev": 0.0612 },
      "time_span_hours": 744.3,
      "neighbor_metrics": { "focus": 0.67, "relaxation": 0.43, "hr": 67.4 },
      "temporal_distribution": { "8": 142, "9": 198 },
      "top_days": [["20260222", 312], ["20260221", 289]]
    },
    "results": [
      {
        "timestamp_unix": 1740412800,
        "neighbors": [
          {
            "distance": 0.0231,
            "timestamp_unix": 1740320040,
            "date": "20260222",
            "device_name": "Muse-A1B2",
            "labels": [{ "text": "morning focus block" }],
            "metrics": { "focus": 0.73, "relaxation": 0.41, "hr": 66.2, "rel_alpha": 0.34 }
          }
        ]
      }
    ]
  }
}

Hidden Fields (visible only with --full or --json)

Hidden field	Contents
result.results[]	Full list of query epochs with complete neighbors[] arrays
result.analysis.temporal_distribution	Hour-of-day match counts as raw numbers
result.analysis.top_days	[["YYYYMMDD", count], …]

npx neuroskill search --json | jq '.result.results | length'
npx neuroskill search --json | jq '.result.results[0].neighbors'
npx neuroskill search --json | jq '[.result.results[].neighbors[]] | sort_by(.distance) | .[0]'
npx neuroskill search --json | jq '.result.analysis.temporal_distribution'

Note: Only epochs with computed EEG embeddings are searched. Use embedding-count to check coverage. Background re-embedding runs automatically when the device is idle (configurable in Settings → EEG Model).

---

compare — A/B Session Comparison

Side-by-side A/B comparison of two sessions. Returns averaged metrics for both ranges, delta values, and trend direction for every metric. Also enqueues a 3D UMAP projection.

Auto-range: uses your last two sessions as A (older) and B (newer).

npx neuroskill compare                                    # auto: last 2 sessions
npx neuroskill compare --a-start 1740380100 --a-end 1740382665 \
                    --b-start 1740412800 --b-end 1740415510
npx neuroskill compare --json
npx neuroskill compare --json | jq '{a_focus: .a.focus, b_focus: .b.focus}'
npx neuroskill compare --json | jq '.insights.deltas.focus'
npx neuroskill compare --json | jq '.insights.improved'
npx neuroskill compare --json | jq '.insights.declined'

HTTP (daemon API):

curl -s -X POST http://127.0.0.1:$PORT/v1/analysis/compare \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aStartUtc": 1740380100, "aEndUtc": 1740382665,
    "bStartUtc": 1740412800, "bEndUtc": 1740415510
  }' | jq '{a_focus: .a.focus, b_focus: .b.focus}'

JSON Response

{
  "ok": true,
  "a": { "focus": 0.62, "relaxation": 0.45, "hr": 72.1, "n_epochs": 513 /* ... */ },
  "b": { "focus": 0.71, "relaxation": 0.38, "hr": 68.4, "n_epochs": 541 /* ... */ },
  "sleep_a": { "total_epochs": 0 /* ... */ },
  "sleep_b": { "total_epochs": 0 /* ... */ },
  "insights": {
    "n_epochs_a": 513,
    "n_epochs_b": 541,
    "deltas": {
      "focus": { "a": 0.62, "b": 0.71, "abs": 0.09, "pct": 14.5, "direction": "up" },
      "relaxation": { "a": 0.45, "b": 0.38, "abs": -0.07, "pct": -15.6, "direction": "down" }
    },
    "improved": ["focus", "meditation", "engagement"],
    "declined": ["relaxation", "hr"]
  },
  "umap": {
    "queued": true,
    "job_id": 5,
    "estimated_secs": 14,
    "n_a": 513,
    "n_b": 541
  }
}

Hidden Fields

Hidden field	Contents
a / b	All ~50 averaged metrics for each session
sleep_a / sleep_b	Full sleep staging summary for each range
insights.deltas	Full delta table for every metric
umap	Enqueued job info — use with umap command

npx neuroskill compare --json | jq '.a'                         # all metrics for A
npx neuroskill compare --json | jq '.b'                         # all metrics for B
npx neuroskill compare --json | jq '.insights.deltas'           # every metric delta
npx neuroskill compare --json | jq '.insights.deltas | to_entries | sort_by(.value.pct) | reverse'
npx neuroskill compare --json | jq '.umap.job_id'               # use with umap --json