Transport: stdio JSON-RPC (neuromesh mcp <workspace>). That is what Cursor, Claude, Codex, OpenCode, MiMo CLI, Antigravity, Kilo Code, Trae, Cline, and similar clients launch. Stdio has no TCP port — --port on mcp does nothing. Background index uses the same file-cap rules as neuromesh index (--max-files, NEUROMESH_MAX_FILES, project-slot config.json; default auto, ceiling 50,000). See cli.md.
Warning: Never run neuromesh mcp without a workspace path (or NEUROMESH_WORKSPACE). Without it the server may bind to your home directory and index unrelated projects. Prefer neuromesh connect, which pins an absolute binary path and workspace in MCP config.
Remote / multi-agent: neuromesh monitor (optionally --port 9000 / neuromesh port 9000), then SSE and HTTP as in api.md.
neuromesh connect # write project MCP configs + globals for installed apps
neuromesh connect --print # snippets only
neuromesh connect --project # this repo only
neuromesh connect --global # also create user-level filesThe command points each client at this binary (absolute path) and the current workspace (args: ["mcp", "<workspace>"] plus NEUROMESH_WORKSPACE). PATH is not required. It merges a neuromesh server into existing files and does not delete other MCP servers.
When neuromesh is on PATH and the IDE runs MCP from your project root (or you set NEUROMESH_WORKSPACE), paste this into MCP settings — no neuromesh connect required.
Cursor — .cursor/mcp.json, or Settings → MCP → Edit config:
{
"mcpServers": {
"neuromesh": {
"command": "neuromesh",
"args": ["mcp"]
}
}
}Same mcpServers shape works for Claude Desktop (claude_desktop_config.json), Trae (.trae/mcp.json), MiniMax (.minimax/mcp.json), and other clients that use that key. OpenCode uses an mcp object with type: "local" and a command array — run neuromesh connect --print and map the binary + args. MiMo CLI uses .mimo-code.json / ~/.mimo-code/config.json with an mcpServers list. VS Code / Copilot uses .vscode/mcp.json with a top-level servers object instead — run neuromesh connect --print for that shape.
neuromesh connect is still preferred when PATH is unreliable: it writes an absolute command and pins the workspace via args: ["mcp", "<path>"] plus NEUROMESH_WORKSPACE.
| Client | Project file | User file (if the app is installed) |
|---|---|---|
| Cursor | .cursor/mcp.json |
~/.cursor/mcp.json |
| VS Code / Copilot | .vscode/mcp.json (servers) |
— |
| Codex | .codex/config.toml |
~/.codex/config.toml |
| OpenCode | opencode.json / .opencode/opencode.jsonc |
~/.config/opencode/opencode.jsonc |
| MiMo CLI | .mimo-code.json |
~/.mimo-code/config.json |
| Antigravity | .agents/mcp_config.json |
~/.gemini/config/mcp_config.json |
| Gemini CLI | — | ~/.gemini/settings.json |
| Kilo Code | .kilo/kilo.jsonc (mcp + command array) |
kilo.jsonc in the user config dir |
| Trae | .trae/mcp.json |
Trae/User/mcp.json |
| MiniMax Code | .minimax/mcp.json |
same mcpServers snippet as Cursor |
| Claude Desktop / Code | .mcp.json |
claude_desktop_config.json |
| Windsurf / Cline / Roo | — | their existing MCP settings files |
Stdout is JSON-RPC only (NDJSON). Handshake logs go to stderr so Antigravity and other strict hosts stay happy.
neuromesh_get_context(task_description)
→ if coverage is partial or no_seed_resolved: neuromesh_search_symbols
→ if you need diagnostics: neuromesh_explain_packet(packet_id)
→ if a folded body is required: neuromesh_expand_fold(fold_id)
→ after a successful edit: neuromesh_record_feedback
Start with get_context. The default packet is minimal: packet_id, coverage string, selected/packet tokens, skeletonized files, fold descriptors without bodies. missing and next appear only when coverage is partial or no_seed_resolved (zero identifiers resolved — do not treat a utility fallback file as the answer). After a good edit, always call neuromesh_record_feedback — that is the synaptic learning step; without it the next packet does not change.
neuromesh connect only registers the MCP server. It does not tell the IDE agent to call those tools. Without project instructions, many agents still Read / Grep whole files and skip NeuroMesh.
Full tutorial (every client): agent-guide.md — Cursor, VS Code/Copilot, Claude, Codex, OpenCode, MiMo CLI, Antigravity, Kilo, Trae, MiniMax, Gemini CLI, Windsurf, Cline/Roo, Zed, plus a one-shot prompt and smoke test.
Quick Cursor install:
mkdir -p .cursor/rules
cp /path/to/neuromesh/docs/agent-rule.mdc .cursor/rules/neuromesh.mdcCursor-ready template: agent-rule.mdc. Same body without YAML frontmatter lives in the guide for AGENTS.md / CLAUDE.md / Copilot instructions.
| Tool | Input | Returns |
|---|---|---|
neuromesh_get_context |
task_description, prompt, or task; optional mode; optional response_detail |
Compact evidence packet (minimal by default) |
neuromesh_explain_packet |
packet_id; optional include |
On-demand diagnostics (no fold bodies) |
neuromesh_expand_fold |
fold_id, node_id, or query; optional reason |
Original folded body |
neuromesh_get_file_skeleton |
file_path, optional active_symbols |
One skeletonized file + fold descriptors (no bodies) |
neuromesh_search_symbols |
query, optional limit |
Ranked hits |
neuromesh_get_dependencies |
name or path | Typed neighbors |
neuromesh_trace |
query, direction (in / out / both), depth |
Call/import chains. Inbound includes throw new, throw $e after catch (Type $e), and ternary new Type. Trace the exception that is actually thrown. |
neuromesh_analyze_impact |
query, depth |
Blast radius |
neuromesh_get_architecture |
— | Languages, packages, entry points |
neuromesh_get_project_memory |
— | Seeded facts |
neuromesh_record_feedback |
task_success, touched_nodes |
STDP on that path; persists base_relevance to graph.bin |
neuromesh_get_node_weights |
query / symbol / path |
Read access_count, base_relevance, learning_bonus (verify learning) |
neuromesh_expand_gap |
path, optional token_cap |
Cheap skeleton for packet_gaps paths |
neuromesh_get_stats |
— | Node/edge counts |
Aliases exist for older clients (activate_context, expand_context, search_context, explain_packet, get_context_details). Prefer the neuromesh_* names.
neuromesh_get_context is the product. Default (response_detail=minimal) shape:
packet_id— session key forneuromesh_explain_packet(LRU, ~10 minutes, 32 packets)coverage—claim(no_recorded_gap,bounded,partial,no_seed_resolved), pluscovered,skipped,sidecar_files,unsure,packet_gaps, and optionalsemantic_coveragefor style tasks.no_recorded_gaponly when every attempted seed resolved,packet_gapsis empty, no sidecar connector files, and the packet was not budget-truncated.boundedmeans seeds resolved but optional connector/sidecar fill or budget cut was applied — do not Grep unless you need more context.tokens.selected/tokens.packet— raw selected vs skeletonized packetfiles[]—path, shortwhy, optionalsidecar: true(connector fill, not a task anchor), skeletoncode,folds[]as descriptors (fold_id,symbol,signature, lines,saved_tokens) with nooriginal_bodymissing/next— only when coverage is incomplete; one search action, not a repeated seed list
mode: balanced (default, +5,000 fill), max_savings (0), max_quality (+16,000). Critical tasks (auth / payment / secret) upgrade to max quality. mode does not add metadata; response_detail does (minimal ≤ 256 metadata tokens, standard ≤ 750, diagnostic on demand).
neuromesh_explain_packet returns seeds, selection, budget, physarum, and membrane for a packet_id. selection.candidates lists ranked files with selected, emitted, drop_stage, score_breakdown, and learning_bonus — use this when debugging why feedback did or did not change the emitted packet. Pass include: ["graph"] for graph stats; otherwise use neuromesh_get_stats. The HTTP monitor (/api/simulate) still requests diagnostic so the VS Code inspector keeps the nested evidence_packet.
Markers look like:
/* [neuromesh:fold:fold_unused_helper_1 | 12 lines folded | fn unused_helper()] */
Pass that fold_id to neuromesh_expand_fold as fold_id, node_id, or query. The full marker line also works. Folds persist for the MCP session (same process, same project). Folds from the current activation stay resolvable; older activations are LRU-trimmed (cap 2000) so long sessions do not grow without bound. A new project id wipes the registry. Ids include a short path tag so two files that both fold write do not collide. Fold bodies are never in get_context or get_file_skeleton; only expand_fold restores them.
neuromesh_record_feedback updates base_relevance, edge pheromones, and episodic memory. Durable weights persist in graph.bin (episode checkpoints in the snapshot); neuromesh.json holds episodic records for recall. The response includes episode_saved_this_call, learning_episodes_in_store, and persisted_to: "graph.bin" (episodes_recorded is a per-call 0/1 compat field).
E
31B9
ffects apply on the next get_context in the same MCP process: search ranking, selector fill, unified scoring, and the emission pipeline (which files actually ship after fill/packet caps). Negative feedback lowers base_relevance and can suppress penalized files from the optional set. Use neuromesh_get_node_weights before and after feedback to verify deltas. When a file shows selected: true but is missing from files[], call neuromesh_explain_packet and check emitted / drop_stage on selection.candidates.
Learning does not change a packet mid-request; restart the MCP server to load persisted graph state from a prior session. Positive reinforcement (learning_bonus ≥ learning_promotion_min_bonus, default 14) can add focus-matched files to the next packet; it does not inject heavily reinforced files into unrelated queries. Negative reinforcement drops penalized hop-expanded files. Benchmark locally with neuromesh eval --learning.