# star-ga/mind-nerve architecture

> Architecture diagram of the GitHub repository star-ga/mind-nerve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/star-ga/mind-nerve
- Repository: https://github.com/star-ga/mind-nerve

## Overview

mind-nerve is an intent-based preselector between a prompt and an agent runtime: it encodes the query, ranks catalog entries, and returns a fixed top-K list. Its runtime can be called directly, through a socket daemon, or via MCP and agent hooks; the installer wires supported clients into that path. A separate catalog/model lifecycle prepares routing data and weights. The README documents these capabilities; unsampled modules are shown only where their role is supported, and uncertain internal wiring is omitted.

Main entry points: [`python/mind_nerve/daemon_client.py`](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/daemon_client.py) (Daemon client), [`python/mind_nerve/inference.py`](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/inference.py) (Encode and rank), [`python/mind_nerve/daemon.py`](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/daemon.py) (Socket daemon), [`python/mind_nerve/preselect_hook.py`](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/preselect_hook.py) (Preselect hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Routing runtime"]
  node_api["Python API<br/>[__init__.py]"]
  node_cli["Route CLI<br/>[cli.py]"]
  node_inference["Encode and rank<br/>[inference.py]"]
  node_native["Native encoder<br/>[_native.py]"]
  node_native_rt["Q16 runtime<br/>[nerve_rt_shims.c]"]
  node_daemon["Socket daemon<br/>[daemon.py]"]
  node_daemon_client["Daemon client<br/>[daemon_client.py]"]
end

subgraph group_assets["Catalog and model"]
  node_runtime_assets[("Runtime weights and tables<br/>[inference.py]")]
  node_corpus["Corpus preparation<br/>[build_corpus.py]"]
  node_index["Catalog index<br/>[build_index.py]"]
  node_format["Catalog encoding<br/>[cat_v2.py]"]
  node_training["Phase-one training<br/>[train_phase1.py]"]
  node_quantize["Encoder quantization"]
end

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_preselect["Preselect hook<br/>[preselect_hook.py]"]
  node_projector["Claude projector<br/>[projector.ts]"]
  node_subprocess["Runtime subprocess<br/>[subprocess.ts]"]
end

subgraph group_operations["Client setup"]
  node_installer["Client installer<br/>[index.ts]"]
  node_install_flow["Install wiring<br/>[install.ts]"]
end

node_user(("Prompt user"))
node_hf["Hugging Face"]
node_agent(("Agent runtime"))

node_user -->|"submits prompt"| node_api
node_api -->|"routes directly"| node_inference
node_user -->|"submits prompt"| node_cli
node_cli -->|"routes directly"| node_inference
node_inference -->|"loads weights and catalog"| node_runtime_assets
node_inference -->|"encodes query"| node_native
node_native -->|"calls native runtime"| node_native_rt
node_hf -.->|"provides weights"| node_runtime_assets
node_daemon -->|"loads and routes"| node_inference
node_user -->|"submits prompt"| node_daemon_client
node_daemon_client -->|"sends socket request"| node_daemon
node_daemon -->|"returns ranked routes"| node_daemon_client
node_mcp -.->|"routes via daemon"| node_daemon_client
node_preselect -.->|"routes via daemon"| node_daemon_client
node_agent -->|"starts prompt hook"| node_projector
node_projector -->|"invokes runtime"| node_subprocess
node_subprocess -.->|"requests routes"| node_daemon_client
node_preselect -->|"returns selected routes"| node_agent
node_corpus -->|"prepares source data"| node_index
node_index -->|"encodes catalog"| node_format
node_training -->|"produces encoder weights"| node_quantize
node_quantize -->|"emits Q16 weights"| node_runtime_assets
node_installer -->|"dispatches install"| node_install_flow

click node_api "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/__init__.py"
click node_cli "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/cli.py"
click node_inference "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/inference.py"
click node_native "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/_native.py"
click node_native_rt "https://github.com/star-ga/mind-nerve/blob/main/mind/runtime/nerve_rt_shims.c"
click node_daemon "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/daemon.py"
click node_daemon_client "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/daemon_client.py"
click node_runtime_assets "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/inference.py"
click node_corpus "https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/build_corpus.py"
click node_index "https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/build_index.py"
click node_format "https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/format/cat_v2.py"
click node_training "https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/train_phase1.py"
click node_quantize "https://github.com/star-ga/mind-nerve/blob/main/tools/quantize_encoder_to_q16.py"
click node_mcp "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/mcp_server.py"
click node_preselect "https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/preselect_hook.py"
click node_projector "https://github.com/star-ga/mind-nerve/blob/main/integrations/claude-code/projector.ts"
click node_subprocess "https://github.com/star-ga/mind-nerve/blob/main/integrations/claude-code/subprocess.ts"
click node_installer "https://github.com/star-ga/mind-nerve/blob/main/integrations/installer/src/index.ts"
click node_install_flow "https://github.com/star-ga/mind-nerve/blob/main/integrations/installer/src/install.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_cli,node_inference,node_native,node_native_rt,node_daemon,node_daemon_client,node_user toneBlue
class node_runtime_assets,node_corpus,node_index,node_format,node_training,node_quantize toneAmber
class node_mcp,node_preselect,node_projector,node_subprocess toneMint
class node_installer,node_install_flow toneRose
class node_hf,node_agent toneIndigo
```

## Components

### Routing runtime

- [Python API](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/__init__.py): `python/mind_nerve/__init__.py`
- [Route CLI](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/cli.py): `python/mind_nerve/cli.py`
- [Encode and rank](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/inference.py): `python/mind_nerve/inference.py`
- [Native encoder](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/_native.py): `python/mind_nerve/_native.py`
- [Q16 runtime](https://github.com/star-ga/mind-nerve/blob/main/mind/runtime/nerve_rt_shims.c): `mind/runtime/nerve_rt_shims.c`
- [Socket daemon](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/daemon.py): `python/mind_nerve/daemon.py`
- [Daemon client](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/daemon_client.py): `python/mind_nerve/daemon_client.py`

### Catalog and model

- [Runtime weights and tables](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/inference.py): `python/mind_nerve/inference.py`
- [Corpus preparation](https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/build_corpus.py): `catalog-builder/build_corpus.py`
- [Catalog index](https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/build_index.py): `catalog-builder/build_index.py`
- [Catalog encoding](https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/format/cat_v2.py): `catalog-builder/format/cat_v2.py`
- [Phase-one training](https://github.com/star-ga/mind-nerve/blob/main/catalog-builder/train_phase1.py): `catalog-builder/train_phase1.py`
- [Encoder quantization](https://github.com/star-ga/mind-nerve/blob/main/tools/quantize_encoder_to_q16.py): `tools/quantize_encoder_to_q16.py`

### Agent interfaces

- [MCP server](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/mcp_server.py): `python/mind_nerve/mcp_server.py`
- [Preselect hook](https://github.com/star-ga/mind-nerve/blob/main/python/mind_nerve/preselect_hook.py): `python/mind_nerve/preselect_hook.py`
- [Claude projector](https://github.com/star-ga/mind-nerve/blob/main/integrations/claude-code/projector.ts): `integrations/claude-code/projector.ts`
- [Runtime subprocess](https://github.com/star-ga/mind-nerve/blob/main/integrations/claude-code/subprocess.ts): `integrations/claude-code/subprocess.ts`

### Client setup

- [Client installer](https://github.com/star-ga/mind-nerve/blob/main/integrations/installer/src/index.ts): `integrations/installer/src/index.ts`
- [Install wiring](https://github.com/star-ga/mind-nerve/blob/main/integrations/installer/src/install.ts): `integrations/installer/src/install.ts`

### Other components

- **Prompt user**
- **Hugging Face**
- **Agent runtime**

## Connections

- Prompt user → Python API: submits prompt
- Python API → Encode and rank: routes directly
- Prompt user → Route CLI: submits prompt
- Route CLI → Encode and rank: routes directly
- Encode and rank → Runtime weights and tables: loads weights and catalog
- Encode and rank → Native encoder: encodes query
- Native encoder → Q16 runtime: calls native runtime
- Hugging Face → Runtime weights and tables: provides weights
- Socket daemon → Encode and rank: loads and routes
- Prompt user → Daemon client: submits prompt
- Daemon client → Socket daemon: sends socket request
- Socket daemon → Daemon client: returns ranked routes
- MCP server → Daemon client: routes via daemon
- Preselect hook → Daemon client: routes via daemon
- Agent runtime → Claude projector: starts prompt hook
- Claude projector → Runtime subprocess: invokes runtime
- Runtime subprocess → Daemon client: requests routes
- Preselect hook → Agent runtime: returns selected routes
- Corpus preparation → Catalog index: prepares source data
- Catalog index → Catalog encoding: encodes catalog
- Phase-one training → Encoder quantization: produces encoder weights
- Encoder quantization → Runtime weights and tables: emits Q16 weights
- Client installer → Install wiring: dispatches install