The pain

You ask a simple question in a large project. The editor copies two or three thousand-line files and ships them to the model.

What you pay for:

1. Tokens you never needed — dollar cost on every turn
2. Seconds of fake loading while the window fills with helpers you will not touch
3. Lost in the middle — the model drowns in unrelated bodies and invents bugs

Today’s workarounds all leak in a different place:

NeuroMesh is the missing step: route first, then fold. The graph is for finding the path. The packet is what the model actually reads.

Don’t delete. Fold.

Nature does not delete DNA to fit a nucleus. It supercoils.

NeuroMesh treats the syntax tree like a genetic strand in RAM:

• Functions you need stay expressed (exons) — real body, real lines
• The rest collapse to a one-line reversible intron:

/* [neuromesh:fold:fold_unused_helper_1 | 12 lines folded | fn unused_helper()] */

The agent still sees the shape of the file — signatures, imports, neighbors — without paying for every private helper. When a folded body is required, neuromesh_expand_fold unsplices it from a registry in memory. Nothing was deleted. Nothing needs a second grep of the disk.

Structure stays. Tokens sleep. Wake a fold when you need it.

Inspired by living systems

The philosophy of the social pitch is right: a graph in RAM, a short path, the rest dormant. After seeds resolve, neighborhood Physarum grows tubes between them (under 20ms, skipped if the subgraph is huge). Fill still respects the token cap. record_feedback is how synapses change the next packet.

Play with the metaphors and the crates: docs/nature.md.

3D Neural Galaxy

neuromesh monitor is the live mesh: subsystems as a constellation, then the file graph, then the symbols inside a module.

_{Constellation — crates and subsystems}

_{3D galaxy — files and synapses; Play slime grows Physarum tubes}

_{Module zoom — files and AST symbols in one crate}

Default URL: http://127.0.0.1:8765. Port: neuromesh port.

How a turn actually goes

flowchart LR
  P[Prompt] --> I[Identifiers]
  I --> G[Graph in RAM]
  G --> S[Seed files]
  S --> T[Physarum tubes]
  T --> F[Fill + synapses]
  F --> X[Exon / intron splice]
  X --> E[Evidence packet]
  E --> W[expand_fold if needed]

1. Read the task as written. handle_tool_call survives; it is not lowercased into mush.
2. Resolve on the mesh. Edges exist when the target is unique. Ambiguous names stay sleepy — never a million fake links.
3. Ship seeds, grow the tube, fill the rest. The files that own those symbols always go in. With two or more seeds, Physarum traces the cheapest connecting tissue on a neighborhood subgraph. Callees and synaptic neighbors fill a real budget (balanced = 5k extra tokens).
4. Splice. Untargeted bodies become fold markers. Coverage tells you if a seed was missed — only then is Grep fair. Folds stay in the MCP session so the next tool can wake them.

Tell the agent (full install guide):

neuromesh_get_context(task_description)
  → neuromesh_expand_fold if a body is still folded
  → neuromesh_trace for callers
  → neuromesh_record_feedback after a good edit

Modes (the membrane)

Seeds are never truncated to fake a small packet.

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/pinoox/neuromesh/main/install.sh | bash

Windows

irm https://raw.githubusercontent.com/pinoox/neuromesh/main/install.ps1 | iex

# From source (needs rustup 1.80+; distro rustc 1.75 cannot parse this Cargo.lock)
git clone https://github.com/pinoox/neuromesh.git
cd neuromesh
cargo build --release --bin neuromesh

# Or Cargo
cargo install --git https://github.com/pinoox/neuromesh.git neuromesh-cli --bin neuromesh

neuromesh doctor
neuromesh connect    # write MCP configs for this repo (absolute binary, no PATH)

Update / uninstall

Same installer overwrites the binary. Re-run the curl / irm command above (or cargo install --force --git …). Then neuromesh -v and restart the IDE so MCP does not keep an old process.

Two copies are common: installer vs Cargo.

which neuromesh / where.exe neuromesh shows which one PATH hits first. Delete the extra file, or cargo uninstall neuromesh-cli if Cargo owns it. Drop the neuromesh block from .cursor/mcp.json (and friends) if you are leaving MCP.

Connect

Native MCP stdio — what Cursor, Claude, Codex, Antigravity, VS Code, Kilo Code, Trae, MiniMax, Windsurf, Cline, and Zed launch.

neuromesh connect           # merge NeuroMesh into project + installed-app configs
neuromesh connect --print   # copy-paste snippets only

That writes an absolute command (this binary) plus args: ["mcp", "<workspace>"] and NEUROMESH_WORKSPACE, so the agent does not need neuromesh on PATH.

Manual (PATH required): if neuromesh is on PATH, paste into Cursor MCP settings (.cursor/mcp.json). Always pass the workspace path as the second argument — args: ["mcp"] alone may index your home directory:

{
  "mcpServers": {
    "neuromesh": {
      "command": "neuromesh",
      "args": ["mcp", "/absolute/path/to/your/project"]
    }
  }
}

Details and other clients: docs/mcp.md#manual.

It finds the git / Cargo / package.json root. It refuses $HOME and drive roots (that is how you accidentally index 11k junk files).

Optional but recommended: teach the agent to call NeuroMesh — full per-IDE tutorial in docs/agent-guide.md. Cursor shortcut: copy docs/agent-rule.mdc → .cursor/rules/neuromesh.mdc.

3D galaxy UI of the live graph: screenshots above · neuromesh monitor → http://127.0.0.1:8765 by default.

Monitor port

Default is 8765. Persist it for this repo, override one run, or use an env var:

neuromesh port                 # print effective port
neuromesh port 9000            # save to the managed project slot (see `neuromesh store`)
neuromesh monitor --port 9000  # this process only (`-p` works too)

Priority: --port / -p → NEUROMESH_PORT → project slot config.json → ~/.neuromesh/config.json → 8765.

neuromesh mcp has no TCP port. Cursor / Claude talk JSON-RPC over stdin/stdout (args: ["mcp"]). Do not put --port on that command.

HTTP / SSE MCP (GET /sse, POST /mcp) rides on the monitor process. Change that port the same way, then open http://127.0.0.1:<port>/sse.

VS Code / Cursor: Settings → neuromesh.port must match the running monitor. After neuromesh port 9000, restart neuromesh monitor and set the editor to 9000.

Index file cap

Default is auto: every production source, then tests, up to 50,000 files. The old silent 6,000-file stop is gone for large src/ trees.

neuromesh index --max-files auto     # persist auto (default)
neuromesh index --max-files 20000    # persist a hard limit

Priority: --max-files → NEUROMESH_MAX_FILES (auto / 0 = auto) → project slot config.json → auto. See cli.md.

Tools

Each file in the packet has path, a short why, skeleton code, and fold descriptors without bodies. Details: docs/mcp.md.

Rust, TypeScript, Python, Go, Java, Kotlin, PHP, C#, Dart, Swift, and Ruby go through tree-sitter queries. JavaScript uses the TypeScript grammar. .svelte, .astro, .twig, .cshtml, .razor, .css, .scss, .less, and .svg are indexed. Framework overlays tag Android/Spring/Django/FastAPI/Next/Nuxt/Laravel/Pinoox/Symfony/WordPress/React/Vue/SvelteKit/Astro/Electron/Tauri/Vite/Prime/Rails/Flutter/Express/Nest/Angular/Gin/Echo/Axum/ASP.NET/SwiftUI/Remix/Ktor routes without a compiler. Vue has a scoped extractor. C/C++ use the generic regex parser. Ambiguous names are not “resolved” by hope.

What we actually measured

Not a universal “99.6%” — that number was never a warranty. Savings are per task, after folding. Re-run: neuromesh eval.

On this repo (release, 2026-08-28, 554,554 workspace tokens):

Selected is the raw token count of the packet files before fold. Packet is after fold. Grep is 0 when every gold file is already in the packet. max_savings can miss gold files (0 extra tokens); that is visible in the same command, not hidden.

Recall ≥ 0.8 and precision ≥ 0.4 stay locked on this repo and the fixture projects (including mini-shop SCSS/dead-code/checkout). Packet activation < 200 ms in the debug gold test.

Index snapshot from that eval run: 323 files · 2,458 nodes · 5,594 edges · ~490 ms index (release).

Docs

MIT · LICENSE