mind-nerve

Intent-classification preselector for agent runtimes.
Open the library, hide the cost.

Mind-Nerve implements a drop-the-decoder + sliding-window encoder design compiled to native Q16.16 fixed-point — the same deterministic architecture as MIND, designed for byte-identical routing output across substrates. The native backend reproduces a pinned bit-identity reference on x86_64, and the underlying MIND Q16.16 substrate is verified byte-identical across x86_64 (AVX2) and ARM64 (NEON) on real hardware; GPU validation is Phase 2 work.

mind-nerve sits between a user prompt and the host runtime. It reads the prompt, decides which subset of the available skills, tools, and MCP servers is relevant, and hands the host a short list — so the downstream LLM never sees the full library in its system prompt.

Library size decouples from token cost. Hosting 4,400 skills costs the same prompt budget as hosting 44, because only the top-K are ever loaded per turn.

pip install mind-nerve

from mind_nerve import route
result = route("deploy the staging build", top_k=5)
for r in result.routes:
    print(f"{r.score:.3f}  {r.name}")

0.912  deploy-pipeline
0.847  staging-environment
0.812  ci-cd
0.778  release-checklist
0.741  rollback-strategy

Highlights

Dual-license note. The repo source, the Python wheel surface, and the Phase-1 weights are Apache-2.0. The wheel additionally bundles libmindnerve.so, a compiled native runtime component under a separate STARGA license. The Phase-1 PyTorch inference path runs entirely under Apache-2.0 and does not require that binary. See License and LICENSE.md for the full split.

The problem

Agent runtimes today load every available skill / tool / MCP server into the LLM's system prompt on every turn. At small scale this is fine. At hundreds of skills, the prompt-cache and per-call token cost become the binding constraint on library growth.

Quickstart

1. Install

pip install mind-nerve

Runs on Linux, macOS and Windows from the same universal (py3-none-any) wheel. The native Q16.16 encoder is a Linux-only speed-up that ships inside the wheel as optional data; on macOS/Windows (or any box without the native library) the router transparently falls back to the pure-Python backend — same results, slightly slower per query, with a one-line notice on first use. The one-shot mind-nerve route CLI needs no daemon and is fully OS-agnostic.

On the 0.3.0 beta line. The current stable is 0.2.0. The active beta series (0.3.0b*) ships the rebuilt native runtime, the offline quantizer, and the Phase 2 encoder rewire. To install the latest beta:

pip install --pre mind-nerve

Pre-release tags are PEP 440 bN suffixes; --pre is required because pip skips pre-releases by default.

The first route() call auto-downloads the Phase-1 weights (~150 MB) from star-ga/mind-nerve into ~/.local/share/mind-nerve/runtime/. To pre-seed or use a custom location, set MIND_NERVE_RUNTIME_DIR.

2. Call it from Python

from mind_nerve import route

result = route("debug a slow Postgres query", top_k=5)
for r in result.routes:
    print(r.score, r.name, r.kind)

3. Run as a daemon (recommended for hot paths)

For CLI hooks, the MCP server, or anything that hits route() many times per minute, run the daemon and connect over a UNIX socket. It loads the runtime once. After warmup the round trip is ~23 ms on GPU and ~90 ms on 4-core CPU. The model load (~250 ms) only happens once at daemon start, so subsequent prompts never pay for it.

mind-nerve-routed &       # listens on $XDG_RUNTIME_DIR/mind-nerve.sock

import json, os, socket

def route(prompt: str, top_k: int = 5) -> dict:
    sock_path = f"{os.environ.get('XDG_RUNTIME_DIR', f'/run/user/{os.getuid()}')}/mind-nerve.sock"
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:
        s.connect(sock_path)
        s.sendall(json.dumps({"prompt": prompt, "top_k": top_k}).encode() + b"\n")
        return json.loads(s.makefile("r").readline())

4. Wire it into Claude Code (one command)

mind-nerve-install install --cli claude-code --with-preselect

That writes two hooks into ~/.claude/settings.json:

• SessionStart — spawns mind-nerve-routed if it's not already running (~7 s warmup; sub-30 ms responses afterwards).
• UserPromptSubmit — asks the daemon for the top-K matching skills and atomically rewrites ~/.claude/skills/ as a directory of symlinks into your real catalog.

The installer auto-detects your layout:

• Default Claude Code install (most users): your existing ~/.claude/skills/ directory is renamed once to ~/.claude/skills.full/. After that the daemon projects a top-K subset back into ~/.claude/skills/ per turn.
• Shared catalog (multiple agent CLIs pointed at one directory, e.g. ~/.agents/skills/): the shared catalog stays put; mind-nerve projects from there into ~/.claude/skills/ per turn.

Already use mind-mem for durable memory? Add the companion MCP:

mind-nerve-install install --cli claude-code --with-preselect --with-mind-mem

mind-nerve handles intent routing; mind-mem provides search-backed memory. Together they bracket the prompt path.

Recommended companion: mind-mem is our open-source (Apache-2.0) governed memory engine for agent CLIs — hybrid BM25+vector recall, a tamper-evident evidence chain, and an MCP server that plugs into the same installer. If you take one other tool from this ecosystem, take that one.

Integrations

The CLI matrix is opt-in:

mind-nerve-install list      # see all supported targets
mind-nerve-install detect    # see what's installed on this machine
mind-nerve-install install --cli all

Console scripts

Acquiring skills

mind-nerve acquire finds external skills/agents/MCP servers in curated sources (Anthropic's skills repo, the official MCP servers repo, the MCP registry API, GitHub search), vets them with a deterministic fail-closed static scanner (shell-pipe installers, reverse shells, exfiltration collectors, prompt injection, archive escapes, obfuscation, credential access, persistence hooks), and installs the clean ones into the hub:

mind-nerve acquire search "pdf"
mind-nerve acquire install <url> [--accept-warnings]
mind-nerve acquire list
mind-nerve acquire remove <name>

Fetches land in a size/file-count-capped quarantine dir first; a FAIL verdict never reaches the hub. Installs write a per-file SHA-256 manifest, reindex the route table through the license gate, and restart the routing daemon so every hooked CLI sees the new skill immediately. Full threat model and source-registry format: docs/acquisition.md.

Configuration

How it works

The frozen design is drop-the-decoder + sliding-window encoder + direct scoring head. The decoder is dropped entirely; the encoder uses sliding-window self-attention (window 256 tokens, stride 192) and writes a pooled query vector that is dot-producted against the precomputed catalog embedding table to produce the top-K routes. Top-K extraction is deterministic: both backends break ties by ascending SHA-256(route_id), matching the spec contract — the Python scoring path (python/mind_nerve/inference.py) and the native Q16.16 top-K (src/top_k.mind) share the same score-descending, SHA-256(route_id)-ascending ordering. Cross-architecture (x86 / ARM / CUDA) identity of the ranking is the Phase 2 gate and is not yet hardware-validated. The authoritative design is spec/architecture.md.

That single design has two backends. Phase 1 is the one users install today. Phase 2 is being brought up incrementally and is not yet end-to-end.

Phase 1 backend — shipped today

• Implementation: PyTorch + sentence-transformers (BAAI/bge-small-en-v1.5 fine-tuned on the v1.1-oss catalog), loaded once into the mind-nerve-routed UNIX-socket daemon.
• Routing path: encoder forward → L2-normalised pooled query vector → dense dot product against the precomputed route_table.npy → deterministic top-K with SHA-256 tie-break and top_k ∈ [1, 64] bounds.
• Weights: auto-downloaded on first use from star-ga/mind-nerve at the pinned revision recorded in the wheel (override via MIND_NERVE_HF_REVISION).
• Latency: warm-daemon p95 ~23 ms on GPU, ~90 ms on a 4-core CPU. The ≤30 ms-on-CPU target is the Phase 2 target, not the Phase 1 result.
• License: Apache-2.0 end-to-end. Phase 1 does not load libmindnerve.so; it runs entirely on the Python wheel surface.

Phase 2 backend — in progress (A1.5 PARTIAL)

The same drop-the-decoder + sliding-window encoder design, compiled to a native MIND Q16.16 fixed-point cdylib that the wheel loads through a C-ABI shim. Goals: remove the PyTorch dependency, close the ≤30 ms-on-CPU budget, and prove cross-architecture bit-identity across CUDA and WebGPU (x86_64 and ARM64 CPU byte-identity already verified on real hardware).

Status, as of commit b9b6401 (A1.5 PARTIAL):

• ✅ A1.1–A1.4 — Q16.16 corpus, encoder kernels, C-ABI export surface, and the SHA-256 bit-identity harness scaffold all landed.
• ✅ A1.5 — pure-MIND encoder cdylib builds. The native score path (matmul against the 11,922-row route table) measures p50 14.4 ms / p95 15.1 ms on a 4-core CPU at commit b9b6401 — already inside the Phase 2 budget for that stage of the pipeline.
• 🚧 Blocked on mindc Phase 6.2 quantizer + SIMD lowering for the full encoder forward; until that lands, the wheel still routes through the Phase 1 PyTorch backend by default.
• 🚧 Cross-architecture bit-identity hardware validation across CUDA and WebGPU is the gating step before Phase 2 becomes the default backend. x86_64 (AVX2) and ARM64 (NEON) CPU byte-identity is verified on real hardware via the MIND Q16.16 cross-substrate proof.

Design constraints

• Latency p95 ≤ 30 ms on 4-core CPU — non-negotiable end target. Phase 1 hits 23 ms via the GPU+daemon path and ~90 ms with a warm daemon on 4-core CPU; the full ≤30 ms-on-CPU budget closes with the Phase 2 native MIND Q16.16 inference loop (toolchain-side mindc prerequisites landed by v0.4.2 / RFC 0005 Phase C — mindc is on the v0.10.x line today; mind-nerve-side native encoder is the remaining work).
• Cross-architecture bit-identity — same request on x86, ARM, CUDA, and WebGPU returns the same top-K. Q16.16 fixed-point throughout, no IEEE-754 fallback in the inference path. (Phase 2 gate; mindc-side cdylib emit landed in v0.3.0; mind-nerve-side hardware validation still pending.)
• No training-data leakage at inference — the classifier reveals only route names, never the training corpora content.
• Tamper detection — every inference can emit an attestation envelope tying the request hash, model hash, and result hash into the evidence chain (opt-in; see python/mind_nerve/attestation.py).

Roadmap

Phase 1 (now) — Public alpha. PyTorch inference, HF-hosted weights, MCP

• hooks integrations, six target CLIs, 96.06% top-5 accuracy on a 11,922-route catalog.

Phase 2 (next) — Native MIND Q16.16 inference loop replaces PyTorch. Cross-architecture bit-identity gate. p95 budget tightens. The HF artifact will be star-ga/mind-nerve-phase2 (parallel to the current star-ga/mind-nerve) — same corpus + tokenizer + model hash contract, different inference path. Toolchain prerequisites all shipped: mindc 0.2.6 (C-ABI export), mindc 0.3.0 (cdylib emit + Phase 0/1/1.5 std-surface intrinsics + RFC 0005 P0e/P0f struct + FieldAccess ABI), and mindc 0.4.4 (RFC 0005 Phase 2 + B + C + D₁ + D₂a — pure-MIND std.vec/string/map/io bundled into the binary, with a $MIND_STDLIB_PATH env-var fork-without-recompile escape hatch, and Named-struct parameter names preserved in arity/type error messages). Remaining work is the mind-nerve-side native encoder kernel that links against the toolchain. The CI gate for the mind/ kernel tree is pinned to mindc 0.10.2 (built with std-surface,cross-module-imports,mlir-build — mlir-build produces the real native objects the gate's symbol leg checks): 0.10.2 name-checks function bodies (mind#23) and resolves the tree's cross-module imports in project mode via mind/Mind.toml. Run the same gate locally with bash tests/mindc_gate.sh — it is fail-closed and never trusts a bare exit code.

Phase 3 — Catalog v2: license-aware ingest at scale, evidence-chain proofs, per-tenant route tables.

Full roadmap: ROADMAP.md.

Repository layout

mind-nerve/
  python/mind_nerve/        Python wheel (Phase 1 inference + CLI)
    cli.py                  `mind-nerve` entrypoint
    daemon.py               `mind-nerve-routed` UNIX-socket server
    ensure.py               `mind-nerve-routed-ensure` idempotent starter
    preselect_hook.py       `mind-nerve-preselect` UserPromptSubmit hook
    installer.py            `mind-nerve-install` cross-CLI installer
    mcp_server.py           `mind-nerve-mcp` MCP stdio server
    inference.py            PyTorch route() implementation
    discovery.py            route catalog discovery + atomic writes
  src/                      pure-MIND implementation (Phase 2 target)
  spec/                     authoritative design documents
  tests/python/             unit tests for the wheel
  .github/workflows/        CI: ruff lint + build + smoke + pytest matrix

License

mind-nerve ships under a dual license:

• Apache-2.0 — the repository source (python/, src/, spec/, cli/, integrations/, tests/), the Python wheel surface, and the Phase-1 trained weights at star-ga/mind-nerve are Apache-2.0. Phase-1 PyTorch inference runs entirely under Apache-2.0 and does not load any STARGA-licensed binary.
• STARGA Commercial — the wheel additionally bundles libmindnerve.so, a compiled native runtime component whose source is not part of this repository. That binary carries a separate STARGA license. Redistribution outside the published wheel is not granted by the Apache-2.0 file.

Full split is documented in LICENSE.md. For commercial enquiries, contact license@star.ga.

Governance and support

• Contributing: CONTRIBUTING.md — build, test, and PR flow.
• Security disclosures: SECURITY.md — please do not file public issues for vulnerabilities; report to info@star.ga.
• Privacy: docs/privacy.md — local-only routing, opt-in logging, no telemetry by default.
• Model card: docs/model_card.md — Phase-1 base model, training data, intended use, and known limitations.
• Dataset and governance: docs/dataset.md and docs/data_governance.md — corpus schema, provenance, retention, and license posture.

Citation

If mind-nerve helps your work, a citation is appreciated:

@software{mind_nerve_2026,
  author  = {STARGA, Inc.},
  title   = {mind-nerve: Intent-classification preselector for agent runtimes},
  year    = {2026},
  url     = {https://github.com/star-ga/mind-nerve},
  version = {0.3.0-beta.1}
}

Links

• PyPI: https://pypi.org/project/mind-nerve/
• Phase-1 weights: https://huggingface.co/star-ga/mind-nerve
• mind-mem (companion memory engine, Apache-2.0): https://github.com/star-ga/mind-mem
• MIND language: https://mindlang.dev
• Changelog: CHANGELOG.md
• Roadmap: ROADMAP.md
• Issues: https://github.com/star-ga/mind-nerve/issues