{"id":49958665,"url":"https://github.com/star-ga/mind-nerve","last_synced_at":"2026-05-20T03:01:48.970Z","repository":{"id":358247098,"uuid":"1237900146","full_name":"star-ga/mind-nerve","owner":"star-ga","description":"Intent-classification preselector for agent runtimes — decouples library size from token cost","archived":false,"fork":false,"pushed_at":"2026-05-16T13:23:33.000Z","size":3586,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T13:43:00.249Z","etag":null,"topics":["agent-tools","ai-agents","intent-classification","llm","mcp","mind-language","preselector","python","routing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mind-nerve/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/star-ga.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T16:04:20.000Z","updated_at":"2026-05-16T13:23:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/star-ga/mind-nerve","commit_stats":null,"previous_names":["star-ga/mind-nerve"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/star-ga/mind-nerve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-nerve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-nerve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-nerve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-nerve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/star-ga","download_url":"https://codeload.github.com/star-ga/mind-nerve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/star-ga%2Fmind-nerve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33160168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"ssl_error","status_checked_at":"2026-05-17T22:39:10.741Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","ai-agents","intent-classification","llm","mcp","mind-language","preselector","python","routing"],"created_at":"2026-05-18T01:08:18.461Z","updated_at":"2026-05-19T02:01:38.680Z","avatar_url":"https://github.com/star-ga.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003emind-nerve\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eIntent-classification preselector for agent runtimes.\u003c/strong\u003e\u003cbr\u003e\n  \u003cem\u003eOpen the library, hide the cost.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/mind-nerve/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/mind-nerve.svg?color=blue\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/mind-nerve/\"\u003e\u003cimg alt=\"Python versions\" src=\"https://img.shields.io/pypi/pyversions/mind-nerve.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/pypi/l/mind-nerve.svg?color=4c1\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/star-ga/mind-nerve/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/star-ga/mind-nerve/actions/workflows/ci.yml/badge.svg?branch=main\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/mind-nerve/\"\u003e\u003cimg alt=\"Downloads\" src=\"https://img.shields.io/pypi/dm/mind-nerve.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://huggingface.co/star-ga/mind-nerve-phase1\"\u003e\u003cimg alt=\"Hugging Face\" src=\"https://img.shields.io/badge/weights-Hugging%20Face-FFD21E\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/star-ga/mind-nerve/stargazers\"\u003e\u003cimg alt=\"Stars\" src=\"https://img.shields.io/github/stars/star-ga/mind-nerve?style=social\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nmind-nerve sits between a user prompt and the host runtime. It reads the\nprompt, decides which subset of the available skills, tools, and MCP servers\nis relevant, and hands the host a short list — so the downstream LLM never\nsees the full library in its system prompt.\n\nLibrary size decouples from token cost. Hosting **4,400 skills** costs the\nsame prompt budget as hosting **44**, because only the top-K are ever loaded\nper turn.\n\n```bash\npip install mind-nerve\n```\n\n```python\nfrom mind_nerve import route\nresult = route(\"deploy the staging build\", top_k=5)\nfor r in result.routes:\n    print(f\"{r.score:.3f}  {r.name}\")\n```\n\n```\n0.912  deploy-pipeline\n0.847  staging-environment\n0.812  ci-cd\n0.778  release-checklist\n0.741  rollback-strategy\n```\n\n---\n\n## Highlights\n\n| | |\n| :--- | :--- |\n| **96.06% top-5 accuracy** | against 11,922 routing candidates (v1.1-oss catalog) |\n| **23 ms p95 latency** | UNIX-socket daemon, warm, on GPU — Phase 1 PyTorch (warm daemon on 4-core CPU is ~90 ms; native MIND target is ≤30 ms on 4-core CPU) |\n| **~95% token reduction** | on a 440-skill Claude Code catalog per turn |\n| **One-line install** | `mind-nerve-install install --cli claude-code --with-preselect` |\n| **Six target CLIs today** | Claude Code, Claude Desktop, Cursor, Codex, Claude Code hooks, MCP — 13 more on the roadmap |\n\n## The problem\n\nAgent runtimes today load every available skill / tool / MCP server into the\nLLM's system prompt on every turn. At small scale this is fine. At hundreds\nof skills, the prompt-cache and per-call token cost become the binding\nconstraint on library growth.\n\n| Approach              | Correctness   | Latency           | Token cost |\n| --------------------- | ------------- | ----------------- | ---------- |\n| Load the whole library | strong        | fast              | O(N) skills, every turn |\n| Vector-only retrieval  | weak on intent | fast              | low |\n| LLM-as-router          | strong        | a full LLM call   | a full LLM call |\n| **mind-nerve**         | 96.06% top-5  | 23 ms p95 (warm daemon) | a few hundred tokens |\n\n## Quickstart\n\n### 1. Install\n\n```bash\npip install mind-nerve\n```\n\nThe first `route()` call auto-downloads the Phase-1 weights (~150 MB) from\n[`star-ga/mind-nerve-phase1`](https://huggingface.co/star-ga/mind-nerve-phase1)\ninto `~/.local/share/mind-nerve/runtime/`. To pre-seed or use a custom\nlocation, set `MIND_NERVE_RUNTIME_DIR`.\n\n### 2. Call it from Python\n\n```python\nfrom mind_nerve import route\n\nresult = route(\"debug a slow Postgres query\", top_k=5)\nfor r in result.routes:\n    print(r.score, r.name, r.kind)\n```\n\n### 3. Run as a daemon (recommended for hot paths)\n\nFor CLI hooks, the MCP server, or anything that hits `route()` many times\nper minute, run the daemon and connect over a UNIX socket. It loads the\nruntime once. After warmup the round trip is ~23 ms on GPU and ~90 ms on\n4-core CPU. The model load (~250 ms) only happens once at daemon start,\nso subsequent prompts never pay for it.\n\n```bash\nmind-nerve-routed \u0026       # listens on $XDG_RUNTIME_DIR/mind-nerve.sock\n```\n\n```python\nimport json, os, socket\n\ndef route(prompt: str, top_k: int = 5) -\u003e dict:\n    sock_path = f\"{os.environ.get('XDG_RUNTIME_DIR', f'/run/user/{os.getuid()}')}/mind-nerve.sock\"\n    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as s:\n        s.connect(sock_path)\n        s.sendall(json.dumps({\"prompt\": prompt, \"top_k\": top_k}).encode() + b\"\\n\")\n        return json.loads(s.makefile(\"r\").readline())\n```\n\n### 4. Wire it into Claude Code (one command)\n\n```bash\nmind-nerve-install install --cli claude-code --with-preselect\n```\n\nThat writes two hooks into `~/.claude/settings.json`:\n\n- **`SessionStart`** — spawns `mind-nerve-routed` if it's not already running\n  (~7 s warmup; sub-30 ms responses afterwards).\n- **`UserPromptSubmit`** — asks the daemon for the top-K matching skills and\n  atomically rewrites `~/.claude/skills/` as a directory of symlinks into\n  your real catalog.\n\nThe installer auto-detects your layout:\n\n- **Default Claude Code install** (most users): your existing\n  `~/.claude/skills/` directory is renamed once to `~/.claude/skills.full/`.\n  After that the daemon projects a top-K subset back into\n  `~/.claude/skills/` per turn.\n- **Shared catalog** (multiple agent CLIs pointed at one directory, e.g.\n  `~/.agents/skills/`): the shared catalog stays put; mind-nerve projects\n  from there into `~/.claude/skills/` per turn.\n\nAlready use [`mind-mem`](https://pypi.org/project/mind-mem/) for durable\nmemory? Add the companion MCP:\n\n```bash\nmind-nerve-install install --cli claude-code --with-preselect --with-mind-mem\n```\n\nmind-nerve handles intent routing; mind-mem provides search-backed memory.\nTogether they bracket the prompt path.\n\n## Integrations\n\n| Host                        | Mechanism                       | Status |\n| --------------------------- | ------------------------------- | ------ |\n| Claude Code                 | MCP + optional hooks            | shipping |\n| Claude Desktop              | MCP                             | shipping |\n| Cursor                      | MCP (`~/.cursor/mcp.json`)      | shipping |\n| Codex                       | MCP (`~/.codex/config.toml`)    | shipping |\n| Any MCP-aware client        | stdio MCP server                | shipping |\n| Aider, Gemini CLI, Windsurf | shim integrations               | v0.1.1 roadmap |\n\nThe CLI matrix is opt-in:\n\n```bash\nmind-nerve-install list      # see all supported targets\nmind-nerve-install detect    # see what's installed on this machine\nmind-nerve-install install --cli all\n```\n\n## Console scripts\n\n| Script | What it does |\n| --- | --- |\n| `mind-nerve` | one-shot CLI router: `mind-nerve route \"git status\" --top-k 5` |\n| `mind-nerve-mcp` | stdio MCP server exposing the `mind_nerve_route` tool |\n| `mind-nerve-routed` | long-lived UNIX-socket route server (the hot path) |\n| `mind-nerve-routed-ensure` | idempotent daemon starter, designed for SessionStart hooks |\n| `mind-nerve-preselect` | UserPromptSubmit hook that atomically projects the skills dir |\n| `mind-nerve-install` | wires the above into each CLI's config |\n\n## Configuration\n\n| Env var                       | Default                                     | What it controls |\n| ----------------------------- | ------------------------------------------- | ---------------- |\n| `MIND_NERVE_RUNTIME_DIR`      | `~/.local/share/mind-nerve/runtime/`        | model + catalog cache |\n| `MIND_NERVE_DEVICE`           | auto (CUDA → MPS → CPU)                     | force device (e.g. `cpu` when sharing a GPU with another model — auto-fallback to CPU also happens on CUDA OOM) |\n| `MIND_NERVE_SOCKET`           | `$XDG_RUNTIME_DIR/mind-nerve.sock`          | daemon UNIX socket |\n| `MIND_NERVE_SOURCE_DIR`       | auto-detected (`~/.claude/skills.full` or `~/.agents/skills`) | preselect source catalog |\n| `MIND_NERVE_PROJECTED_DIR`    | `~/.claude/skills`                          | preselect projection target |\n| `MIND_NERVE_TOP_K`            | `20`                                        | how many skills to project per turn |\n| `MIND_NERVE_OVERFETCH`        | `300`                                       | how many to ask the daemon for before dedup |\n| `MIND_NERVE_SOCKET_TIMEOUT`   | `2.0`                                       | daemon socket timeout (s) |\n| `MIND_NERVE_LOG`              | `~/.mind-nerve/hook.log`                    | jsonl log for the preselect hook |\n| `MIND_NERVE_CORE_ALWAYS_ON`   | `diagnose:code-review:git-workflow:…`       | colon-separated names always added to the projection |\n\n## How it works\n\nAsymmetric encoder/decoder with a classifier head. The encoder reads the\nrequest (no feed-forward blocks — attention + gated residuals only — for\ncompact representation). The decoder cross-attends to the encoder output\nand to a fixed embedding of every available route. The classifier head\nemits per-route relevance scores. Top-K extraction is deterministic;\nties break by route-ID hash so the same input on x86 / ARM / CUDA returns\nthe same ranking. Full spec in [`spec/architecture.md`](spec/architecture.md).\n\n## Design constraints\n\n- **Latency p95 ≤ 30 ms** on 4-core CPU — non-negotiable end target. Phase 1\n  hits 23 ms via the GPU+daemon path and ~90 ms with a warm daemon on\n  4-core CPU; the full ≤30 ms-on-CPU budget closes with the Phase 2 native\n  MIND Q16.16 inference loop (toolchain-side mindc shipped through v0.4.2 /\n  RFC 0005 Phase C; mind-nerve-side native encoder is the remaining work).\n- **Cross-architecture bit-identity** — same request on x86, ARM, CUDA, and\n  WebGPU returns the same top-K. Q16.16 fixed-point throughout, no IEEE-754\n  fallback in the inference path. (Phase 2 gate; mindc-side cdylib emit\n  landed in v0.3.0; mind-nerve-side hardware validation still pending.)\n- **No training-data leakage at inference** — the classifier reveals only\n  route names, never the training corpora content.\n- **Tamper detection** — every inference emits an attestation envelope tying\n  the request hash, model hash, and result hash into the evidence chain.\n\n## Roadmap\n\n**Phase 1 (now)** — Public alpha. PyTorch inference, HF-hosted weights, MCP\n+ hooks integrations, six target CLIs, 96.06% top-5 accuracy on a 11,922-route\ncatalog.\n\n**Phase 2 (next)** — Native MIND Q16.16 inference loop replaces PyTorch.\nCross-architecture bit-identity gate. p95 budget tightens. The HF artifact\nwill be `star-ga/mind-nerve-phase2` (parallel to the current\n[`star-ga/mind-nerve-phase1`](https://huggingface.co/star-ga/mind-nerve-phase1)) —\nsame corpus + tokenizer + model hash contract, different inference path.\nToolchain prerequisites all shipped: `mindc` 0.2.6 (C-ABI export),\n[`mindc` 0.3.0](https://github.com/star-ga/mind/releases/tag/v0.3.0)\n(cdylib emit + Phase 0/1/1.5 std-surface intrinsics + RFC 0005 P0e/P0f\nstruct + FieldAccess ABI), and\n[`mindc` 0.4.4](https://github.com/star-ga/mind/releases/tag/v0.4.4)\n(RFC 0005 Phase 2 + B + C + D₁ + D₂a — pure-MIND std.vec/string/map/io\nbundled into the binary, with a `$MIND_STDLIB_PATH` env-var\nfork-without-recompile escape hatch, and Named-struct parameter names\npreserved in arity/type error messages).  Remaining work is the\nmind-nerve-side native encoder kernel that links against the toolchain.\n\n**Phase 3** — Catalog v2: license-aware ingest at scale, evidence-chain\nproofs, per-tenant route tables.\n\nFull roadmap: [`ROADMAP.md`](./ROADMAP.md).\n\n## Repository layout\n\n```\nmind-nerve/\n  python/mind_nerve/        Python wheel (Phase 1 inference + CLI)\n    cli.py                  `mind-nerve` entrypoint\n    daemon.py               `mind-nerve-routed` UNIX-socket server\n    ensure.py               `mind-nerve-routed-ensure` idempotent starter\n    preselect_hook.py       `mind-nerve-preselect` UserPromptSubmit hook\n    installer.py            `mind-nerve-install` cross-CLI installer\n    mcp_server.py           `mind-nerve-mcp` MCP stdio server\n    inference.py            PyTorch route() implementation\n    discovery.py            route catalog discovery + atomic writes\n  src/                      pure-MIND implementation (Phase 2 target)\n  spec/                     authoritative design documents\n  tests/python/             unit tests for the wheel\n  .github/workflows/        CI: ruff lint + build + smoke + pytest matrix\n```\n\n## License\n\nmind-nerve ships under **Apache-2.0** — repository, Python wheel, and the\nPhase-1 trained weights on Hugging Face all carry the same license. The wheel\nadditionally bundles `libmindnerve.so`, a compiled runtime component whose\nsource is not part of this repository and is not distributed under Apache\n2.0. The Phase-1 PyTorch path does not depend on it.\n\nFor commercial enquiries, contact\n[`license@star.ga`](mailto:license@star.ga). See\n[`LICENSE.md`](LICENSE.md) for the full text.\n\n## Citation\n\nIf mind-nerve helps your work, a citation is appreciated:\n\n```bibtex\n@software{mind_nerve_2026,\n  author  = {STARGA, Inc.},\n  title   = {mind-nerve: Intent-classification preselector for agent runtimes},\n  year    = {2026},\n  url     = {https://github.com/star-ga/mind-nerve},\n  version = {0.3.0-beta.1}\n}\n```\n\n## Links\n\n- **PyPI**: \u003chttps://pypi.org/project/mind-nerve/\u003e\n- **Phase-1 weights**: \u003chttps://huggingface.co/star-ga/mind-nerve-phase1\u003e\n- **MIND language**: \u003chttps://mindlang.dev\u003e\n- **Changelog**: [`CHANGELOG.md`](./CHANGELOG.md)\n- **Roadmap**: [`ROADMAP.md`](./ROADMAP.md)\n- **Issues**: \u003chttps://github.com/star-ga/mind-nerve/issues\u003e\n\n\u003c!-- mind-profile: default --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstar-ga%2Fmind-nerve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstar-ga%2Fmind-nerve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstar-ga%2Fmind-nerve/lists"}