Content
# Mesh Core
**Local-first MCP server for multi-agent AI collaboration.**
Mesh Core is a free, open-source prototype that lets multiple AI agents (Claude Code, Cursor, ChatGPT via an MCP bridge, Gemini, etc.) collaborate on a shared project. It provides a task board, shared memory, agent-to-agent messaging, and an append-only timeline — all stored locally in a single SQLite file.
> ⚠️ **Security notice:** This prototype is designed for trusted, single-user local use. Do not expose the Mesh Core socket to a network or run it in a multi-user/shared environment without the hardened edition.
---
## Features
- **Shared project memory** — goals, decisions, conventions, architecture notes
- **Task board** — create, assign, and track tasks across agents with full audit history
- **Agent messaging** — direct messages and broadcasts between agents, timestamped at ingestion
- **Append-only timeline** — every action produces a timeline event; nothing is silently lost
- **Artifact storage** — content-addressed blob storage for files agents produce
- **Up to 10 concurrent agents** — no artificial cap in the open-source core
- **100% local** — nothing leaves the machine; no accounts, no cloud calls
---
## How It Works
Mesh Core runs as an **HTTP MCP server** on `127.0.0.1:3141`. Each AI client connects independently via the Streamable HTTP transport. All data is stored in `.mesh/mesh.db` (SQLite, WAL mode) inside your project directory.
Why HTTP and not stdio? The MCP `stdio` transport is 1:1 — one process per client. Supporting 10 concurrent agents requires HTTP transport, where each agent gets its own session but all share the same database.
---
## Quick Start
### Prerequisites
- Node.js ≥ 20
- npm ≥ 9
### Install & Build
```bash
git clone https://github.com/your-org/mesh-core
cd mesh-core
npm install
npm run build
```
### Start the Server
```bash
# Start in your project directory
npm run start
# Or point at a specific directory
node dist/bin/mesh-server.js start --dir /path/to/project
# Custom port (default: 3141)
node dist/bin/mesh-server.js start --port 8080
```
Mesh Core will create a `.mesh/` directory inside your project on first run.
### Connect an AI Client
Add this to your MCP client configuration (e.g. Claude Desktop's `claude_desktop_config.json`):
```json
{
"mcpServers": {
"mesh": {
"url": "http://127.0.0.1:3141/mcp"
}
}
}
```
For clients that don't support HTTP transport natively, you can use an MCP proxy. See [MCP documentation](https://modelcontextprotocol.io/) for details.
### Inspect What's Happening
```bash
# List connected agents
node dist/bin/mesh-inspect.js agents
# Show task board
node dist/bin/mesh-inspect.js tasks
# Task detail + history
node dist/bin/mesh-inspect.js tasks <task-id>
# Recent messages
node dist/bin/mesh-inspect.js messages
# Activity timeline
node dist/bin/mesh-inspect.js timeline
# Point at a different project directory
node dist/bin/mesh-inspect.js agents --dir /path/to/project
```
---
## On-Disk Layout
```
<project_root>/.mesh/
mesh.db # SQLite (WAL mode) — all structured data
mesh.db-wal
mesh.db-shm
config.json # Project settings (agent cap, port, bind address)
artifacts/
<sha256>.blob # Content-addressed binary storage
<sha256>.meta.json # Filename, mime type, size
logs/
mesh-core.log # Local only, never transmitted
```
---
## MCP Tool Reference
All tools follow the `mesh.<domain>.<action>` naming convention.
### Agents
| Tool | Description |
|---|---|
| `mesh.agents.register` | Register an agent (name, client_kind, strengths[]) |
| `mesh.agents.list` | List all agents and their status |
| `mesh.agents.heartbeat` | Update agent's last_seen_at timestamp |
### Memory
| Tool | Description |
|---|---|
| `mesh.memory.write` | Write a memory entry (goal/decision/convention/constraint/architecture) |
| `mesh.memory.list` | List entries, optionally filtered by category |
| `mesh.memory.search` | Full-text search across memory entries |
### Tasks
| Tool | Description |
|---|---|
| `mesh.tasks.create` | Create a task with title, description, priority, dependencies |
| `mesh.tasks.claim` | Assign a task to an agent |
| `mesh.tasks.update_status` | Update task status (todo→in_progress→review→done/blocked) |
| `mesh.tasks.list` | List tasks, optionally filtered by status or agent |
| `mesh.tasks.get` | Get a task with its full event history |
### Messaging
| Tool | Description |
|---|---|
| `mesh.messages.send` | Send a message to an agent (or broadcast to all) |
| `mesh.messages.inbox` | Read messages for an agent since a timestamp |
### Timeline
| Tool | Description |
|---|---|
| `mesh.timeline.list` | Read the append-only project timeline |
### Artifacts
| Tool | Description |
|---|---|
| `mesh.artifacts.put` | Upload a file (base64 encoded, max 50MB) |
| `mesh.artifacts.get` | Download a file by artifact_id |
| `mesh.artifacts.list` | List artifact metadata, optionally filtered by task |
---
## Configuration
On first start, `.mesh/config.json` is created with defaults:
```json
{
"max_agents": 10,
"port": 3141,
"bind": "127.0.0.1"
}
```
Edit this file to change settings. CLI flags override config file values.
---
## What's NOT in This Repo
The following features are intentionally reserved for the future premium/hardened edition:
- Cloud accounts, billing, org/team management
- Multi-machine sync for distributed teams
- Per-agent permission scopes and encrypted storage
- Signed/authenticated agent handshake
- Semantic/embedding memory search and knowledge graph
- Conflict detection between agents
- Desktop GUI
- Rust rewrite of the core
---
## Contributing
This project is MIT licensed and welcomes contributions. The codebase is TypeScript + SQLite — if you can read JavaScript, you can contribute.
1. Fork and clone the repo
2. `npm install && npm run build`
3. Make your changes in `src/`
4. Run the automated test suite with `npm run test` (or `npm run test:coverage`)
5. Test live server changes with `npm run dev` (tsx watch mode)
6. Open a PR
Please don't open PRs for premium features listed above — those are intentionally out of scope for this repo.
---
## License
MIT — see [LICENSE](./LICENSE)
