MindSync MCP

Local-first Model Context Protocol server for multi-agent memory sync and focus conflict detection.

Use it when several coding agents (Claude Code, Codex, Cursor, Gemini CLI, Grok, custom agents, …) share one developer machine and need:

1. A shared session/focus registry (who is editing what)

2. Conflict warnings when focuses overlap

3. Optional durable fact sync to your remote host over SSH (offline queue when remote is down)

No cloud account. No hard-coded hosts or home directories.

Features

Design principles:

1. Offline-first — local tools always work; remote is opt-in and best-effort.

2. Locked local state — exclusive lockfiles around state/queue writes.

3. Safe remote writes — identifier allowlists + base64 text transport over SSH.

4. No false-positive conflicts — same project alone is not a conflict; token/path overlap is.

5. Generic by default — zero personal paths in code; configure via env.

Related MCP server: junto-memory

Install

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

Quick start (local only)

No env vars required. State lives under ~/.mindsync.

MCP client config

After pip install -e .:

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

Or run the module path explicitly:

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

(Windows: use your venv’s python.exe if agents don’t see the same PATH.)

Optional remote sync

Remote features stay 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 for the full list and examples/remote/ for sample server-side scripts (mindsync_fact.py, mindsync_consolidate.py).

SSH must be key-based / BatchMode-friendly (no interactive password prompts).

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

• compiled-truth/*.md — pulled remote summaries

• .locks/ — exclusive lockfiles

Agent usage pattern

1. Start: get_sync_context(agent_name) (set refresh_remote=true when remote is configured).

2. Work: update_focus(agent_name, project, branch, focus, paths=[...]).

3. Milestone: queue_durable_fact(agent_name, entity, attribute, text).

4. Reconnect: sync_offline_facts(agent_name).

Layout

mindsync-mcp/
├── mindsync/
│   ├── server.py      # FastMCP tools
│   ├── storage.py     # JSON/JSONL + locks
│   ├── bridge.py      # optional SSH/SCP
│   ├── conflict.py    # focus overlap
│   └── config.py      # env-based settings
├── examples/remote/   # sample remote hooks
├── tests/
├── .env.example
└── pyproject.toml

Develop / test

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

GitHub Actions runs the same suite on every push/PR to master (Python 3.10 + 3.12, Ubuntu + Windows).

Security notes

• Treat tool arguments as untrusted: entity/attribute/agent must match a strict allowlist.

• Fact text is base64-transported to the remote host (no raw shell interpolation of free text).

• This server runs with your user privileges and can SSH only when you configure a host — wire it into trusted local agent clients only.

• Do not commit real .env files or server secrets.

License

MIT