MeshMind

A local intelligence mesh for disconnected and local-first AI systems.

MeshMind is a resilient edge AI coordination layer for running specialized AI nodes across laptops, desktops, phones, and other edge devices without depending on the internet.

---

MeshMind connects local AI systems into a collaborative mesh. Each device runs its own model, capabilities, and context. A coordinator node discovers peers, routes sub-queries, executes work in parallel where possible, and aggregates the results into a unified answer.

This is not distributed inference for a single giant model. MeshMind is built around distributed collaboration: multiple specialized nodes working together over local networks and offline-capable environments.

MeshMind v0.1.1

What this is: A local-first mesh for Ollama-backed specialist nodes on a trusted LAN, with a coordinator that routes work and aggregates answers. There is no MeshMind cloud; configuration and traffic stay on machines you control.

Install (released package): Python 3.11+ and Ollama. Stable installs:

pip install -U meshmind

Install (from source, contributors): from the repo root:

pip install -e ".[dev]"   # or: pip install -e .

Golden path:

1. meshmind init my-project — creates data/knowledge.json and meshmind.yaml (or meshmind init --wizard; use --preset code for demo plugins).
2. cd my-project
3. meshmind doctor -c meshmind.yaml — environment, Ollama, config, ports, and plugin directories.
4. meshmind config validate -c meshmind.yaml
5. meshmind up -c meshmind.yaml — interactive REPL (› prompt), or open Dashboard / Chat at http://localhost:<ui_port>, or run meshmind query "…".

Second machine on your LAN: docs/second-machine.md (minimal steps; full detail: docs/lan-two-device.md).

Interoperability: OpenAI-compatible GET /v1/models and POST /v1/chat/completions on the coordinator ui_port; optional MESHMIND_API_TOKEN for /v1/* only (not Dashboard//api/*). Parity details: docs/openai-parity.md. MCP: pip install "meshmind[mcp]" then meshmind mcp-serve (docs/mcp.md). LAN and token scope: docs/security-and-lan.md. Coordinator capability JSON: GET /api/capabilities or GET /.well-known/meshmind.json.

Plugins (plugin: in YAML): docs/plugins.md.

Release notes: docs/RELEASE_v0.1.md, CHANGELOG.md.

First-time user guide: docs/USER_GUIDE.md.

Not in v0.1.x yet: QR or PWA onboarding, meshmind join / go-style scanning, or full OpenAI API parity (embeddings, images, …).

Features

• Automatic peer discovery: Nodes discover each other over mDNS with manual-peer fallback when deterministic networking matters.
• Capability-based routing: Queries are routed to the nodes best suited to answer them.
• Parallel fan-out: Multi-capability queries can be sent to multiple nodes concurrently.
• Coordinator aggregation: Responses are combined into a single final answer.
• Built-in dashboard: Monitor mesh topology, routing activity, query traces, and node availability.
• Dashboard cards: Hover a node to inspect capabilities, knowledge domains, tools, and system prompt previews without exposing raw knowledge file lists or plugin ids.
• CLI-first workflow: Bootstrap, validate, run, and query the mesh from the terminal.
• Python SDK: Create and control meshes programmatically.
• Local-model runtime: Uses Ollama-backed local models instead of remote APIs.
• Knowledge-aware nodes: Load local knowledge files into specific nodes.
• Manual discovery fallback: Useful for restrictive firewalls, unusual LANs, or offline field setups.
• Plugins: Drop-in packages under ~/.meshmind/plugins/ (or MESHMIND_PLUGIN_DIR) merged into specialist nodes via plugin: <id> in meshmind.yaml. See docs/plugins.md for layout and merge rules.
• Init presets / wizard: meshmind init <dir> --preset code for a multi-specialist template; meshmind init --wizard for an interactive flow.
• OpenAI-compatible API: GET /v1/models and POST /v1/chat/completions on the coordinator UI port — same process as Dashboard/Chat. See docs/USER_GUIDE.md.
• MCP (optional): pip install "meshmind[mcp]" and meshmind mcp-serve for editor/agent tools. See docs/mcp.md.

Dashboard

MeshMind includes a built-in dashboard for inspecting your mesh in real time.

• mesh topology
• node state
• query routing
• event log
• query history
• unavailable-node warnings

Enable the dashboard on a coordinator with:

coordinator:
  type: 'coordinator'
  port: 8403
  ui: true
  ui_port: 8080

Then open:

http://localhost:8080

Paths on the same coordinator UI (one HTTP server on ui_port):

• /dashboard — topology canvas, connected nodes, and live event log
• /chat — full-page mesh query composer (POST /api/query and streaming POST /api/query/stream)
• /pwa — Field PWA for phones on the same LAN (QR join from the dashboard; see docs/USER_GUIDE.md)
• /v1/models, /v1/chat/completions — OpenAI-compatible API for external clients (subset of the OpenAI schema; see docs/USER_GUIDE.md)

The dashboard sidebar also shows plugin cards for installed prompt packs, with prompt previews and tool summaries, and a Join from phone QR for the Field PWA. When a plugin lives inside this repository, its source folder is linked directly from the card.

If /chat returns {"detail":"Not Found"}, the running process is an older MeshMind build: stop the mesh (type stop in the meshmind up REPL, or Ctrl+C if you used --no-interactive), then from the repo root run pip install -e . and start again with meshmind up so the coordinator loads the current meshmind.ui.app routes.

Benchmarks

The CLI includes meshmind benchmark (synthetic or real AI) for repeatable routing and latency scenarios in development. Multi-device SLOs and published performance numbers are still evolving.

What is already true today:

• MeshMind can route work across multiple nodes.
• Parallel fan-out is implemented for multi-capability queries.
• Real-world speedup depends on query shape, model size, discovery overhead, and aggregation cost.

Ongoing measurement priorities:

• discovery time across 2 and 3 devices
• routing correctness
• single-node vs multi-node latency
• disconnect and rejoin behavior
• failure handling under node loss

Quick Start

Devices running MeshMind can discover each other automatically over local networks. The default generated project also exposes a local dashboard on the configured ui_port.

You can install a released build (pip install meshmind) or run from a clone for development.

Run from PyPI

Prerequisites:

• Python 3.11+

• Ollama installed and running

• A local model, for example:

  ollama pull gemma3:1b

pip install meshmind
meshmind doctor
meshmind init my-project
cd my-project
meshmind up -c meshmind.yaml

Run from Source

Prerequisites: same as above. Clone the repo and bootstrap the environment:

git clone https://github.com/Nexarion-Distributed-AI/MeshMind.git
cd MeshMind

# Windows PowerShell
./scripts/bootstrap.ps1

# Linux/macOS
# ./scripts/bootstrap.sh

Activate the virtual environment if needed:

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

Run the environment diagnostics:

meshmind doctor

Create a project, validate it, and start the mesh:

meshmind init my-project
cd my-project
meshmind doctor -c meshmind.yaml
meshmind config validate -c meshmind.yaml
meshmind up -c meshmind.yaml

Presets: meshmind init <dir> --preset default (same as omitting --preset) uses the generic assistant + coordinator template. meshmind init <dir> --preset code generates a reviewer + security + coordinator mesh and, by default, copies bundled demo plugins demo_review and demo_security into your plugin directory. Use --skip-bundled-plugins to only write YAML. In a normal terminal, bare meshmind init (no name, default options) starts the same interactive wizard as meshmind init --wizard; the wizard shows a Rich preview and asks for confirmation before creating files.

Wizard: meshmind init --wizard interactively chooses a preset and project name (optional NAME as the first argument).

Plugins CLI: meshmind plugin list, meshmind plugin list --available / meshmind plugin catalog, meshmind plugin install <path-or-bundled-id>, meshmind plugin add-node <bundled-id> -c meshmind.yaml, meshmind plugin sync -c meshmind.yaml, meshmind plugin validate <path-or-id>, meshmind plugin remove <id>. Details: docs/plugins.md.

Two-terminal workflow (Claude Code–style): the terminal where you run meshmind up starts an interactive REPL with a › prompt. Mesh INFO logs are written to .meshmind/logs/mesh-<mesh-name>.log next to your YAML (not mixed into that REPL). Open a second terminal and tail them:

meshmind logs -f -c meshmind.yaml

REPL behavior: use /help for a Rich command table. /status shows mesh and node tables (plus UI URLs). /urls, /query …, /clear (clears screen and in-session transcript), /export <path> (save transcript as Markdown), /compact (placeholder — mesh has no token budget), /version, and /stop work with or without the leading slash. The prompt shows MeshMind › with a bottom hint and mesh name on the right. Enter submits; Ctrl+J inserts a newline. Ctrl+C: empty line = exit; non-empty = clear line; during a query = cancel. Each turn prints a You panel (question preview), then Assistant: if the mesh streams chunks, a Rich Live panel updates with rendered Markdown (bold, bullets, emphasis—not raw ** syntax), then dim routing/duration; if there are no stream chunks (result only on done), the answer is shown in a single Markdown panel instead. Tab completes commands and node names; auto-suggest uses history. History file: .meshmind/repl_history beside your meshmind.yaml.

Query from either terminal: in the REPL type a line (it is sent as a query) or /query …; or from another shell:

meshmind query "Summarize the latest AI trends in 5 bullets" -c meshmind.yaml -t 300

CLI output format: meshmind query defaults to --format auto — markdown when stdout is a TTY (styled panel + markdown body), plain text when not (e.g. pipes/CI). Use --format json for a stable JSON object (result, nodes_used, duration, unavailable_nodes, trace).

For a single terminal with the old log stream on stdout (e.g. CI), use meshmind up -c meshmind.yaml --log-to-stdout. To skip the REPL and wait until Ctrl+C only: --no-interactive.

Python SDK

MeshMind also provides a Python SDK for programmatic mesh creation:

from meshmind.sdk.mesh import Mesh
from meshmind.sdk.node_def import NodeDef

mesh = Mesh("my-mesh", default_model="gemma3:1b")

mesh.add_node(NodeDef(
    name="researcher",
    model="gemma3:1b",
    capabilities=["research", "analysis", "summarization"],
    system_prompt="You are a research assistant.",
    port=8401,
))

mesh.add_node(NodeDef(
    name="writer",
    model="gemma3:1b",
    capabilities=["writing", "editing"],
    system_prompt="You are a technical writer.",
    port=8402,
))

mesh.add_coordinator(port=8403)

await mesh.start()
result = await mesh.query("Research recent AI papers and write a summary")
print(result.text)
await mesh.stop()

Example Configuration

meshmind.yaml defines the mesh, default model settings, and the participating nodes:

mesh:
  name: 'my-team'
  discovery: 'mdns'

defaults:
  model: 'gemma3:1b'

nodes:
  analyst:
    type: 'specialist'
    port: 8401
    system_prompt: |
      You are a data analyst. Analyze data and provide insights.
    capabilities:
      - 'data_analysis'
      - 'statistics'
    knowledge_domains:
      - 'data'
      - 'statistics'
    knowledge:
      - ./data/knowledge.json

  writer:
    type: 'specialist'
    port: 8402
    system_prompt: |
      You are a technical writer. Write clear documentation.
    capabilities:
      - 'writing'
      - 'documentation'

  coordinator:
    type: 'coordinator'
    port: 8403
    ui: true
    ui_port: 8080

Additional committed examples:

• my-project/meshmind.yaml
• smoke-local/meshmind.yaml

CLI Reference

meshmind init <name>
meshmind up [-c meshmind.yaml] [--no-interactive] [--log-to-stdout] [--log-file PATH]
meshmind logs [-c meshmind.yaml] [-f] [-n 200]
meshmind down
meshmind stats
meshmind nodes
meshmind query "text"
meshmind doctor
meshmind config validate
meshmind config show

Architecture

meshmind/
|- core/          protocol, discovery, registry, router, orchestrator, node
|- network/       async TCP transport
|- ai/            Ollama integration and function calling
|- sdk/           Python SDK
|- cli/           Click-based command line interface
|- config/        YAML schema and parser
|- knowledge/     local knowledge loading
|- plugins/       plugin loading
|- ui/            FastAPI dashboard

Current Status

MeshMind is currently an early open source release focused on:

• local multi-agent orchestration across laptops and desktops
• Ollama-backed local models
• mDNS discovery with manual-peer fallback
• CLI and SDK workflows
• dashboard-based mesh visibility

Current focus areas:

• discovery hardening
• routing observability
• repeatable benchmarking
• offline/manual-peer workflows
• mobile-node interoperability

Current Limitations

• Large models may exceed available RAM and create unstable first-run behavior.
• First-query latency can be significantly slower than warm runs.
• mDNS behavior varies across networks, firewalls, and operating systems.
• Multi-device routing is implemented, but guaranteed speedup has not yet been comprehensively benchmarked.
• Mobile-node support is still experimental and not yet a stable documented flow.

Guides

• 2-device LAN guide
• Known limitations
• Vision

Testing

Run the automated test suite from the repository root:

python -m pytest tests -q

The current test suite covers:

• protocol serialization
• routing behavior
• registry state
• configuration parsing and validation
• CLI helper logic
• SDK lifecycle behavior

Use Cases

• private local developer assistants
• research workflows across multiple machines
• on-prem AI coordination for sensitive environments
• offline or degraded-network operations
• edge and field-device intelligence coordination

Contributing

See:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md

For local development:

python -m pip install -e .
python -m pytest tests -q

License

MeshMind is licensed under the Apache License 2.0.