neuroloop-py

NeuroLoop™ – EXG-aware AI agent (Python edition)

A Python port of neuroloop using litellm for multi-provider LLM access and prompt_toolkit for the interactive terminal UI.

What it does

neuroloop-py is an EXG-aware conversational AI agent that:

• Reads your brainwaves before every turn via neuroskill status
• Injects your live mental state into the system prompt so the AI responds with full awareness of how you actually feel — cognitively, emotionally, somatically
• Auto-labels notable moments (awe, grief, deep focus, moral clarity, etc.) as permanent EXG annotations
• Runs guided protocols (breathing, meditation, grounding, somatic scans, etc.) step by step with OS notifications and EXG timestamps
• Searches the web, reads URLs, and maintains persistent memory across sessions
• Loads skill reference docs on-demand based on what you're asking about
• Pre-warms the compare cache so session comparisons are instant when you ask

Architecture

neuroloop/
├── main.py          Entry point — model selection, CLI args, asyncio.run()
├── agent.py         NeuroloopAgent — main loop, before_agent_start hook, tool dispatch
├── memory.py        ~/.neuroskill/memory.md — read/write persistent memory
├── prompts.py       STATUS_PROMPT + build_system_prompt() + read_skill_index()
├── neuroskill/
│   ├── run.py       run_neuroskill() — subprocess executor (npx neuroskill ...)
│   ├── signals.py   detect_signals() — 40+ regex-based domain signal detectors
│   ├── context.py   select_contextual_data() — parallel queries + skill injection
│   └── client.py    SkillConnection — WebSocket live event listener
└── tools/
    ├── web_fetch.py  web_fetch tool — URL → plain text
    ├── web_search.py web_search tool — DuckDuckGo Lite (no API key)
    └── protocol.py   run_protocol tool — timed step execution + EXG labelling

NEUROLOOP.md         Capability index — always injected into the system prompt
METRICS.md           Full EXG metrics reference — injected on metric questions
skills/              One SKILL.md per neuroskill domain — injected on-demand
  neuroskill-data-reference/
  neuroskill-labels/
  neuroskill-protocols/
  neuroskill-recipes/
  neuroskill-search/
  neuroskill-sessions/
  neuroskill-sleep/
  neuroskill-status/
  neuroskill-streaming/
  neuroskill-transport/

vs. the TypeScript original

Installation

cd /agent/ns/neuroloop-py
pip install -e .
# or: uv sync

Requires Python ≥ 3.12.

Usage

# Interactive mode (auto-detects model)
neuroloop-py

# With a specific model
neuroloop-py --model claude-3-5-sonnet-20241022
neuroloop-py --model ollama/qwen3:5b

# With an initial message
neuroloop-py "How is my focus today?"

# Via python -m
python -m neuroloop --model gpt-4o "Summarise my last session"

Model selection (priority order)

1. --model MODEL CLI flag
2. NEUROLOOP_MODEL environment variable
3. Auto-detect running Ollama → prefers qwen3:5b, falls back to first available model
4. Cloud API keys: ANTHROPIC_API_KEY → claude, OPENAI_API_KEY → gpt-4o, GEMINI_API_KEY → gemini
5. Hard default: ollama/qwen3:5b

Note: Ollama models don't support function calling — tools are disabled automatically. Cloud models (Anthropic, OpenAI, Gemini) get full tool access.

Keyboard shortcuts

Commands

Tools available to the AI

Tools are only available to cloud models (Anthropic, OpenAI, Gemini). Ollama models receive the same context but respond in plain text without tool calls.

Skills & signal-driven injection

Every user prompt is scanned by detect_signals() (40+ regex patterns across 40+ domains). Matching signals trigger two things in parallel:

1. Neuroskill queries — neuroskill session, neuroskill sleep, search-labels …, etc. — run concurrently and appended to the system context
2. Skill file injection — the relevant skills/*/SKILL.md or METRICS.md is read and prepended to the context block

NEUROLOOP.md (capability overview) is always injected between the static guidance and the live EXG context.

Requirements

• Python ≥ 3.12
• neuroskill npm package reachable via npx neuroskill
• At least one of:
  • A running Ollama instance (no API key needed, no tools)
  • ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY (full tool support)