Metadata-Version: 2.4
Name: mind-nerve
Version: 0.3.1
Summary: Intent-classification preselector for agent runtimes — open the library, hide the cost. Apache-2.0 source and Phase-1 weights; wheel bundles a separately licensed native runtime component (see LICENSE.md). Full documentation lives in README.md on the project homepage.
Author-email: "STARGA, Inc." <info@star.ga>
License: Apache-2.0
Project-URL: Homepage, https://github.com/star-ga/mind-nerve
Project-URL: Issues, https://github.com/star-ga/mind-nerve/issues
Keywords: agent,agents,llm,mcp,preselector,intent-classification,routing,sentence-transformers,mind-language,ai-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.md
Requires-Dist: numpy>=1.24
Requires-Dist: sentence-transformers>=5.7.0
Requires-Dist: torch>=2.0
Requires-Dist: huggingface_hub>=1.26.1
Requires-Dist: cryptography>=50.0.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.28.1; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: ruff>=0.16.1; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pip-audit>=2.10.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/brand/mind-mark.svg" alt="" width="110">
</p>

<h1 align="center">mind-nerve</h1>

<p align="center">
  <strong>Intent-classification preselector for agent runtimes.</strong><br>
  <em>Every skill available. Few in context.</em>
</p>

<p align="center">
  <strong>Mind-Nerve</strong> 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.
</p>

<p align="center">
  <a href="https://pypi.org/project/mind-nerve/"><img alt="PyPI" src="https://img.shields.io/pypi/v/mind-nerve.svg?color=blue&style=flat-square"></a>
  <a href="https://pypi.org/project/mind-nerve/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/mind-nerve.svg?style=flat-square"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square"></a>
  <a href="https://github.com/star-ga/mind-nerve/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/star-ga/mind-nerve/ci.yml?branch=main&style=flat-square&label=CI"></a>
  <a href="https://github.com/star-ga/mind-nerve/releases"><img alt="Release" src="https://img.shields.io/github/v/release/star-ga/mind-nerve?style=flat-square&color=green&label=Release"></a>
  <img alt="Deterministic" src="https://img.shields.io/badge/deterministic-Q16.16-brightgreen?style=flat-square">
  <a href="https://huggingface.co/star-ga/mind-nerve"><img alt="Hugging Face" src="https://img.shields.io/badge/weights-HuggingFace-FFD21E?style=flat-square"></a>
</p>

---

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**.

```bash
pip install mind-nerve
```

```python
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

| | |
| :--- | :--- |
| **96.06% top-5 accuracy** | against 11,922 routing candidates (v1.1-oss catalog) |
| **2.6× faster deterministic routing than PyTorch** | 0.58 ms mean / 0.97 ms p95 on the routing/score step, byte-identical top-K on every run (U1 12-core bare metal, native Q16.16 backend) |
| **Byte-identical, cross-substrate determinism** | Q16.16 fixed-point + SHA-256 tie-break — same top-K every run, no IEEE-754 fallback — a structural guarantee numpy/PyTorch can't offer |
| **~99% token reduction** | on a 4,400-skill Claude Code catalog per turn (only the top-K load) |
| **One-line install** | `mind-nerve-install install --cli claude-code --with-preselect` |
| **Public integrations today** | Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, plus a stdio MCP server for any MCP-aware client — see [Integrations](#integrations) |

> **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](#license) and
> [`LICENSE.md`](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.

| Approach              | Correctness   | Latency           | Token cost |
| --------------------- | ------------- | ----------------- | ---------- |
| Load the whole library | strong        | fast              | O(N) skills, every turn |
| Vector-only retrieval  | weak on intent | fast              | low |
| LLM-as-router          | strong        | a full LLM call   | a full LLM call |
| **mind-nerve** | 96.06% top-5 | 0.58 ms mean routing/score step — 2.6× faster than PyTorch at that step, byte-identical every run | O(1) — fixed top-K, decoupled from catalog size |

## Quickstart

### 1. Install

```bash
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`](https://huggingface.co/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

```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).

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

```python
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)

```bash
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`](https://pypi.org/project/mind-mem/) for durable
memory? Add the companion MCP:

```bash
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`](https://github.com/star-ga/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

| Host                        | Mechanism                                          | Status |
| --------------------------- | -------------------------------------------------- | ------ |
| Claude Code                 | MCP + optional `UserPromptSubmit`/`SessionStart` hooks | shipping |
| Claude Desktop              | MCP (`claude_desktop_config.json`)                 | shipping |
| Cursor                      | MCP (`~/.cursor/mcp.json`)                         | shipping |
| Codex                       | MCP (`~/.codex/config.toml`)                       | shipping |
| Gemini CLI                  | extension manifest (`~/.gemini/extensions/`)       | shipping |
| Any MCP-aware client        | stdio MCP server                                   | shipping |
| Aider, Windsurf             | shim integrations                                  | roadmap |

The CLI matrix is opt-in:

```bash
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

| Script | What it does |
| --- | --- |
| `mind-nerve` | one-shot CLI router: `mind-nerve route "git status" --top-k 5` |
| `mind-nerve-mcp` | stdio MCP server exposing the `mind_nerve_route` tool |
| `mind-nerve-routed` | long-lived UNIX-socket route server (the hot path) |
| `mind-nerve-routed-ensure` | idempotent daemon starter, designed for SessionStart hooks |
| `mind-nerve-preselect` | UserPromptSubmit hook that atomically projects the skills dir |
| `mind-nerve-install` | wires the above into each CLI's config |

## 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:

```bash
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](docs/acquisition.md).

## Configuration

| Env var                       | Default                                     | What it controls |
| ----------------------------- | ------------------------------------------- | ---------------- |
| `MIND_NERVE_RUNTIME_DIR`      | `~/.local/share/mind-nerve/runtime/`        | model + catalog cache |
| `MIND_NERVE_DEVICE`           | auto (CUDA → MPS → CPU) — PyTorch fallback only | force the PyTorch-fallback device (e.g. `cpu` when sharing a GPU with another model — auto-fallback to CPU also happens on CUDA OOM). The default native Q16.16 backend is CPU-only. |
| `MIND_NERVE_SOCKET`           | `$XDG_RUNTIME_DIR/mind-nerve.sock`          | daemon UNIX socket |
| `MIND_NERVE_SOURCE_DIR`       | auto-detected (`~/.claude/skills.full` or `~/.agents/skills`) | preselect source catalog |
| `MIND_NERVE_PROJECTED_DIR`    | `~/.claude/skills`                          | preselect projection target |
| `MIND_NERVE_TOP_K`            | `20`                                        | how many skills to project per turn |
| `MIND_NERVE_OVERFETCH`        | `300`                                       | how many to ask the daemon for before dedup |
| `MIND_NERVE_SOCKET_TIMEOUT`   | `2.0`                                       | daemon socket timeout (s) |
| `MIND_NERVE_LOG`              | `~/.mind-nerve/hook.log`                    | jsonl log for the preselect hook |
| `MIND_NERVE_CORE_ALWAYS_ON`   | `diagnose:code-review:git-workflow:…`       | colon-separated names always added to the projection |
| `MIND_NERVE_HF_REVISION`      | pinned commit SHA in the package             | override the Hugging Face model revision to download; set to a specific commit SHA or tag for reproducible artifact pinning |
| `MIND_NERVE_ENV_FILE`         | `~/.mind-nerve/env`                         | shared env file: `KEY=VALUE` lines (`#` comments) read by the hook, the MCP server, and the daemon spawner; an explicitly exported var or CLI-config pin ALWAYS wins — the file only fills vars that are unset |

## 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`](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`](https://huggingface.co/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`](https://huggingface.co/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](https://github.com/star-ga/mind/releases/tag/v0.3.0)
(cdylib emit + Phase 0/1/1.5 std-surface intrinsics + RFC 0005 P0e/P0f
struct + FieldAccess ABI), and
[`mindc` 0.4.4](https://github.com/star-ga/mind/releases/tag/v0.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](https://github.com/star-ga/mind/releases/tag/v0.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`](./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`](https://huggingface.co/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`](LICENSE.md). For commercial
enquiries, contact [`license@star.ga`](mailto:license@star.ga).

## Governance and support

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

## Citation

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

```bibtex
@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`](./CHANGELOG.md)
- **Roadmap**: [`ROADMAP.md`](./ROADMAP.md)
- **Issues**: <https://github.com/star-ga/mind-nerve/issues>

<!-- mind-profile: default -->
