MindSync AI

One Python MCP server for multi-agent teams: shared memory, focus conflict detection, an in-process event bus, and CLI agent dispatch (Codex, Claude, Gemini, Cursor, Aider, Grok).

No cloud account required. Remote sync is opt-in. Zero hard-coded hosts or personal paths.

Rename (v1.1.0): PyPI package and GitHub repo are now mindsync-ai
(older installs used mindsync-mcp). Import path and CLI stay the same:
import mindsync · mindsync.

Install

pip install mindsync-ai

Requires Python 3.10+.

From source:

git clone https://github.com/adityarya24/mindsync-ai.git
cd mindsync-ai
python -m pip install -e ".[dev]"

MCP client config

{
  "mcpServers": {
    "mindsync": {
      "command": "mindsync"
    }
  }
}

Or:

{
  "mcpServers": {
    "mindsync": {
      "command": "python",
      "args": ["-m", "mindsync.server"]
    }
  }
}

(Windows: point at your venv’s python.exe if agents don’t share PATH.)

Tools (13)

Core memory / focus

Event bus

Agent dispatch

Dispatch also auto-emits job.started, job.completed, and job.failed on the bus.

CLI (dispatch)

mindsync-dispatch agents
mindsync-dispatch run codex "summarize README" --background
mindsync-dispatch status
mindsync-dispatch result <job-id>
mindsync-dispatch cancel <job-id>

Jobs live under ~/.claude/agent-dispatch/jobs/ (override with AGENT_DISPATCH_HOME).
Custom agents: ~/.claude/agent-dispatch/agents.json.

Built-in presets: codex, claude, gemini, cursor, aider, grok.

Quick start (local only)

No env vars required for core + bus + dispatch. State lives under ~/.mindsync.

1. Start: get_sync_context(agent_name)
2. Work: update_focus(agent_name, project, branch, focus, paths=[...])
3. Milestone: queue_durable_fact(agent_name, entity, attribute, text)
4. Delegate: delegate_task(agent="codex", prompt="...", background=True)
5. Reconnect: sync_offline_facts(agent_name) when remote is configured

Optional remote sync

Remote stays disabled until both are set:

export MINDSYNC_SSH_HOST=my-server          # SSH config Host or user@host
export MINDSYNC_REMOTE_ROOT=/opt/mindsync   # directory on that host

See .env.example and examples/remote/.

SSH must be key-based / BatchMode-friendly.

Two machines (VPS + laptop)

Run MindSync AI on each machine for local focus/state. Share durable facts via one always-on host:

1. VPS: deploy examples/remote/ scripts under e.g. /opt/mindsync.
2. Laptop: set MINDSYNC_SSH_HOST + MINDSYNC_REMOTE_ROOT to that VPS.
3. VPS itself: leave remote vars empty — it is the store.

Local data layout

Under MINDSYNC_HOME (default ~/.mindsync):

• local-state.json — active project + per-agent focus map
• local-audit.jsonl — append-only action log
• offline_queue.jsonl — durable facts waiting for remote
• events.jsonl — event bus log
• subscriptions.json — event subscriptions
• compiled-truth/*.md — pulled remote summaries
• .locks/ — exclusive lockfiles

Layout

mindsync-ai/                  # GitHub repo
├── mindsync/
│   ├── server.py             # FastMCP tools (core + bus + dispatch)
│   ├── storage.py            # JSON/JSONL + locks
│   ├── bridge.py             # optional SSH/SCP
│   ├── conflict.py           # focus overlap
│   ├── config.py             # env-based settings
│   ├── bus/                  # Event bus engine
│   └── dispatch/             # Agent dispatch (presets, runner, CLI)
├── examples/remote/
├── tests/
└── pyproject.toml            # PyPI: mindsync-ai

Develop / test

python -m pip install -e ".[dev]"
python -m pytest -q
python scripts/smoke_test.py

CI runs on every push/PR to master (Python 3.10 / 3.12 / 3.13 × Ubuntu + Windows).

Design principles

1. Offline-first — local tools always work; remote is opt-in.
2. Locked local state — exclusive locks around state/queue/events.
3. Safe remote writes — identifier allowlists + base64 text over SSH.
4. No false-positive conflicts — same project alone is not a conflict.
5. Generic by default — zero personal paths in code.
6. Safe dispatch — model tokens validated; Windows .cmd/.bat arg-mode prompts blocked.

Security notes

• Runs with the privileges of the executing user. Wire only into trusted local agents.
• Pulled remote truth is treated as untrusted (filename/UTF-8 validation, atomic swap).
• Local store defaults to Unix 0700 dirs / 0600 files where the OS allows.
• SSH errors are scrubbed before return to clients.

Full details: SECURITY.md.

License

MIT