mind-nerve

Intent-classification preselector for agent runtimes.
Every skill available. Few in context.

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. The open-source release ships CPU backends only; a GPU tier (CUDA/WebGPU) is reserved for a potential private/enterprise offering, mirroring the MIND compiler's licensing split.

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. Point it at every SKILL file published on GitHub — ~1.6M of them — and the standing prompt cost stays fixed, because only the top-K are ever loaded per turn.

The catalog does not sit in the context window; the router does, and it is a fixed cost. There is no ceiling in the design: the number of routable artifacts is bounded by disk, not by context. Measured today: 96.06% top-5 accuracy across 11,922 candidates.

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 — the default backend — ships inside the wheel as a Linux ELF .so; 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. No Windows PE build exists today, and mindc cannot yet cross-compile one, so Windows always runs the pure-Python path — native Windows support is roadmap, not shipped. The one-shot mind-nerve route CLI needs no daemon and is fully OS-agnostic.

Current stable is 0.3.1. It ships the native Q16.16 encoder as the default backend (mindc 0.10.2), a security + dependency-floor bump, and doc/version-sync fixes — no --pre flag needed.

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.

The runtime-dir pin is load-bearing. If you maintain a curated route table, export MIND_NERVE_RUNTIME_DIR to point at it (for a daemon, pin it in the systemd unit / shared env). When the variable is unset, resolution falls through to the default location and serves the generic catalog — the routes will look plausible but be far less relevant. As of the fix that added this note, an unset pin prints a one-time WARNING — MIND_NERVE_RUNTIME_DIR is not set on stderr so the fallback is never silent. If route_table.npy and route_table.jsonl ever fall out of sync (a load-time "Route table embeddings/meta length mismatch"), run mind-nerve prune to realign them.

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 — the model load (~250 ms) only happens at daemon start, so subsequent prompts never pay for it. The scoring step itself is sub-millisecond (0.58 ms mean, 12-core CPU, 2.6× faster than PyTorch at the same step); the encode step ahead of it is a shared, microarch- and weight-dependent cost still being optimized toward the ≤30 ms p95 end-to-end target (see the native backend status further below).

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 once; the daemon then serves every subsequent request without paying that cost again — the routing/score step itself is sub-millisecond).
• 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

The full 20-client matrix (grok, kimi, qwen, windsurf, continue, cline, roo, zed, aider, copilot, cody, qodo, …) plus the verify verb — per-client checks of config, hooks, env pins, MCP entry, and daemon socket — lives in the TypeScript installer under integrations/installer/ (npm install && npm run build, then node dist/src/index.js install <client> / verify --cli all; bin name mind-nerve-installer, npm publication pending).

Console scripts

Acquiring skills

The catalog is not fixed. mind-nerve acquire searches the public ecosystem across nine sources — Anthropic's skills repo, the official MCP servers repo, the MCP registry API, Glama, Smithery, community skill/agent/template libraries (obra/superpowers, wshobson/agents, davila7/claude-code-templates), plus generic GitHub repository search as a fallback. Skills, agents and MCP servers, all three. There is no curated whitelist you are confined to: if it is published, it is reachable.

Anything found is vetted 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. Acquired content is always reindexed as untrusted, even though the local hub is a first-party trust root — a skill you did not write does not inherit your trust.

Acquisition is the only network path in the system, and it is explicit and operator-invoked. Routing itself never opens a socket: local encoder, local table, read off local disk. 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. The underlying MIND Q16.16 substrate's cross-architecture (x86_64 / ARM64 CPU) identity is verified on real hardware; mind-nerve's own ranking pipeline reproduces the pinned x86_64 reference today, and ARM64 reproduction of that same pipeline is the task #57 gate — not yet hardware-validated (see docs/benchmarks.md §1). The authoritative design is spec/architecture.md.

That single design has two backends: a native MIND Q16.16 encoder, the default since 0.3.0b9, and a PyTorch fallback (MIND_NERVE_BACKEND=pytorch). Both implement the identical deterministic top-K contract; only the inference path differs.

PyTorch backend — fallback

• 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).
• License: Apache-2.0 end-to-end. The wheel runs entirely on its own Apache-2.0 surface (the bundled native Q16.16 encoder cdylib included); it never loads the separately-licensed libmindnerve.so runtime.

Native Q16.16 backend — default since 0.3.0b9

The same drop-the-decoder + sliding-window encoder design, compiled to a native MIND Q16.16 fixed-point cdylib that ships inside the wheel and is the default backend. The routing/score step is a measured, shipped win: 0.58 ms mean / 0.97 ms p95 across all 12 hardware threads (i7-5930K, U1 bare metal) — 2.6× faster than PyTorch at the same step (PyTorch: 1.52 ms mean / 3.77 ms p95), with byte-identical top-K on every run. That is the Phase 2 core wedge, and it is done. What's still ahead: optimizing the encode step (the embedding forward pass ahead of scoring — a shared, microarch- and weight-dependent cost) toward the ≤30 ms p95 end-to-end target — the fix is wiring encode through the same MT GEMM kernel that already wins on the score path, tracked for the next release, not claimed here. The underlying MIND Q16.16 substrate is verified byte-identical on x86_64 (AVX2) and ARM64 (NEON) real hardware; mind-nerve's own encoder/route pipeline reproduces the pinned x86_64 reference today, and ARM64 reproduction of that pipeline is the task #57 gate — not yet hardware-validated. The open-source release ships CPU backends only; a GPU tier (CUDA/WebGPU) is reserved for a potential private/enterprise Pro offering (scope decision 2026-08-15).

The pure-MIND front end also ships a native MCP server (src/mcp.mind, compiled into the same binary): its JSON-RPC message framing (initialize, error shapes, notification suppression) is byte-identical to the Python mind-nerve-mcp server on the frozen golden transcript (tests/harness/mcp_golden.sh). tools/call on the native server is fail-closed by default with an explicit unavailable payload: the binary-bundle producer plumbing is landed and loader-round-trip tested, but the only bundle producible today uses placeholder zero embeddings (no 256-dim trained checkpoint exists; the 384-dim BGE route table is incompatible with the native loader), which would rank by SHA-256 tie-break rather than relevance — so auto-seed is intentionally off until a real checkpoint lands (see the honest limits at the top of src/mcp.mind). The Python mind-nerve-mcp server remains the one that actually routes today. A Windows target is declared in Mind.toml ([targets.windows]), but no Windows PE build exists anywhere in this repo or its history, and mindc 0.10.2 cannot cross-compile to PE yet (it fails loud rather than emitting a broken binary — "cross-target native codegen landing incrementally"). Windows installs run the pure-Python fallback, same as the encoder path above; native Windows support is roadmap, gated on that mindc capability.

Status, as of v0.3.1 (mindc 0.10.2):

• ✅ 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 and ships in the wheel as the default backend. The native score path (matmul against the 11,922-row route table, the pure-MIND MT __mind_blas_gemv_q16_mt) measures p50 ≈0.58 ms / p95 ≈0.97 ms across all 12 hardware threads (i7-5930K) — 2.6× faster than PyTorch at the same step. This is the Phase 2 core wedge and it is done.
• ✅ Full .mind tree ported to mindc 0.10.2 (2026-08-15) — the 17-module kernel tree AND all 13 front-end files (sha256, q16_16, tokenizer, evidence, encoder_kernels, model, loader, inference, …) compile and execute, gated by the fail-closed tests/mindc_gate.sh (262 exact-count tests + a native-ELF end-to-end harness byte-verified against CPython hashlib).
• ✅ x86_64 bit-identity: the native score path reproduces the pinned x86_64 Q16.16 reference byte-for-byte (AVX2 == scalar oracle == the pinned hash, docs/benchmarks.md §1). The underlying MIND Q16.16 substrate is separately verified byte-identical on x86_64 (AVX2) and ARM64 (NEON) real hardware; ARM64 reproduction of mind-nerve's own encoder/route pipeline against that same pinned hash is the task #57 gate and is not yet hardware-validated. The open-source release is CPU-only; no OSS GPU tier to validate.
• ⏳ Still ahead, honestly labeled as not-yet-shipped: tail-latency optimization of the encode step toward the ≤30 ms p95 end-to-end target; a native-MIND training pipeline (today's fine-tuning uses an external framework); multilingual coverage; Windows-PE distribution.

Design constraints

• Deterministic, byte-identical routing — the score step (0.58 ms mean / 0.97 ms p95, U1 12-core bare metal) is 2.6× faster than PyTorch at the same step and returns the identical top-K on every run, Q16.16 fixed-point throughout with no IEEE-754 fallback in the inference path.
• Latency p95 ≤ 30 ms on CPU — the end-to-end target/direction for Phase 2, not a published hard number today: encode is a shared, microarch- and weight-dependent cost, still being optimized (see the status list above).
• Cross-architecture bit-identity — same request on x86_64 and ARM64 CPU returns the same top-K. The underlying MIND Q16.16 substrate is verified on real x86_64 + ARM64 hardware; mind-nerve's own pipeline is verified on x86_64 today, with ARM64 reproduction gated on task #57 (not yet hardware-validated). There is no GPU backend in the open-source release (scope decision 2026-08-15; a commercial Pro tier is roadmap).
• 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 (shipping) — Native Q16.16 encoder by default (PyTorch fallback), HF-hosted weights, MCP + hooks integrations, 20 installer targets, 96.06% top-5 accuracy on a 11,922-route catalog.

Phase 2 (core shipped, tail-latency in progress) — The native MIND Q16.16 inference loop is already the default backend, replacing PyTorch for routing: the score step measures 0.58 ms mean / 0.97 ms p95, 2.6× faster than PyTorch at that step, byte-identical every run. What remains: optimizing the encode step toward the ≤30 ms p95 end-to-end target, ARM64 hardware validation of mind-nerve's own pipeline (task #57), a native-MIND training pipeline (today's fine-tuning uses an external framework), and multilingual coverage. 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). The mind-nerve-side encoder kernel has since shipped in the wheel (default backend), and the whole .mind tree — kernel surface plus the 13 front-end files — compiles and executes on the current 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 (backend selection + 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            route() implementation — native Q16.16 (default) + PyTorch (fallback)
    discovery.py            route catalog discovery + atomic writes
  src/                      pure-MIND implementation (native front-end, shipped)
  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.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