MindSync MCP
MindSync MCP orchestrates AI coding agents with shared memory, task routing, and job management.
Sync local/remote session state and compiled truth (
get_sync_context,pull_truth,sync_offline_facts)Manage agent focus and warn on overlaps (
update_focus)Queue and consolidate durable facts (
queue_durable_fact,memory_consolidation)Delegate tasks with capability routing, worktree isolation, and quota handoff (
delegate_task,route_task,get_orchestration_policy)Manage jobs: status, wait, result, review, cancel (
job)Publish/poll/subscribe to events (
events)Manage memory sessions: start, checkpoint, end (
session)Bootstrap and semantically recall project memory (
memory_bootstrap,memory_recall)List agents, models, or roles (
list)Check health, paths, queue depth, and remote reachability (
health)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MindSync MCP Update my focus to myapp/main focusing on auth module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MindSync AI
Local-first MCP orchestration, persistent shared memory, and automatic task routing for coding agents.
š adityarya24.github.io/mindsync-ai
MindSync Community is no longer maintained. v1.9 is the final release and this repository is archived (read-only). Existing installs keep working, but there will be no further fixes or releases. Its successor is Hivelane by Yuvaan Labs: routing, git worktrees per agent, handoff when a seat runs low, and shared memory. 7-day trial, no card.
š” What is MindSync?
MindSync connects disparate AI coding agents (Codex, Claude Code, Gemini CLI, Antigravity, Grok, Cursor, OpenCode, Aider) into a single, coordinated local ecosystem without requiring a cloud SaaS account or third-party servers.
The human-facing CLI session you are talking to remains in charge as the orchestrator. MindSync routes subtasks by domain capability, enforces file locks to prevent multi-agent collisions, tracks rate limits for seamless quota handoff across providers, and preserves long-term factual memory across sessions.
āāāāāāāāāāāāāāāāāāāāāāāāāā
ā You (Human Prompt) ā
āāāāāāāāāāāāā¬āāāāāāāāāāāāā
ā
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Human-Facing CLI Session (Orchestrator) ā
ā (e.g., Codex / Claude / Gemini / Grok / ...) ā
āāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāā
ā (MCP Protocol)
ā¼
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā MINDSYNC CORE ā
ā āāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
ā ā Capability Router ā Conflict Prevention Shield ā ā
ā āāāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā⤠ā
ā ā Quota & Handoff Tier ā Vector Memory (`sqlite-vec`) ā ā
ā āāāāāāāāāāāāāāāāāāāāāāāāā“āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā (Isolated Worktrees)
āāāāāāāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāāāāāāā
ā¼ ā¼ ā¼
āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā
ā Codex Worker ā ā Claude Worker ā ā Gemini / Grok ā
ā (Implementation)ā ā (Deep Reasoning) ā ā (Audit & Search) ā
āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāāKey Guarantee: Dispatched workers receive bounded tasks inside isolated Git worktrees and cannot recursively re-delegate through MindSync.
Related MCP server: Agent Nudge
ā” Quick Start
1. Installation
pip install mindsync-ai(Requires Python 3.10+)
2. Automated Auto-Discovery & Setup
# Auto-detects installed MCP hosts and PATH coding CLIs
mindsync setup --mode auto
# Verify system health, lock engines, and adapter status
mindsync doctor
# Inspect available agent roster and capabilities
mindsync agentsRestart your CLI sessions after setup to load the registered MCP servers.
# Additional setup options
mindsync setup --dry-run # Preview changes without modifying host configs
mindsync setup --cli grok # Target a specific host only
mindsync setup --no-discover # Register hosts without PATH CLI scanning
mindsync setup --no-hooks # Skip Codex standalone hooksš¤ Supported Clients & Roster
A CLI may act as an MCP Host (orchestrator), a Worker (dispatched execution), or both:
CLI / Engine | MCP Host | Dispatched Worker | Domain Strength / Role |
OpenAI Codex | Native | Yes | Fast implementation, refactoring, standalone memory hooks |
Anthropic Claude Code | Native | Yes | Architecture, comprehensive reviews, massive context |
Google Gemini CLI | Native | Yes | Research, multimodal analysis, tool integrations |
Antigravity ( | Via Gemini | Yes | Preferred execution worker in Gemini family |
Grok CLI (xAI) | Native | Yes | Codebase exploration, security audit, rapid synthesis |
Cursor Agent | JSON ( | Yes | In-IDE pair programming, file editing |
OpenCode | JSON ( | Yes | Context-first systems counseling & multi-model routing |
Aider | ā | Yes | Surgical git diffs & local file edits |
ā¹ļø Family Isolation: Gemini CLI and
agyshare thegemini-antigravityfamily. When either is the human-facing orchestrator, both are excluded from automatic worker selection to protect orchestrator bandwidth.
šÆ Orchestration & Capability Dispatch
Policy configuration is located at ~/.mindsync/orchestration.json (Modes: auto, suggest, off).
Run Dispatched Jobs
# Route task automatically to best suited agent by capability
mindsync-dispatch run auto "implement and test the auth fix" --capability coding
# Check status of running or completed jobs
mindsync-dispatch statusAutomatic Provider Quota Handoff
MindSync prevents blocked workflows when an LLM provider's quota exhausts mid-task. When enabled with an isolated worktree, MindSync transfers the working state, task prompt, and latest checkpoint to a ranked successor agent:
# Run with worktree isolation and automatic quota handoff
mindsync-dispatch run auto "refactor database schema" --write --worktree --on-limit handoff
# Inspect provider and account cooldowns
mindsync-dispatch limits
# Clear cooldowns manually after operator verification
mindsync-dispatch limits clearPre-emptive Usage Evaluation
MindSync includes pluggable usage readers. Bundled readers use local CLI/IDE session stores (not browser cookies). A missing or failed read stays unavailable ā dispatch does not invent a percent.
Adapter | Reader | Local source |
|
|
|
|
|
|
|
| Grok CLI session + billing credits |
|
| Official Antigravity CLI vault + quota summary |
|
| Cursor IDE session DB ( |
|
| OpenCode Go plan key only, not BYOK upstreams |
Antigravity token refresh. A still-valid access token is enough to read quota. If the token has expired, refresh needs the official installed-app OAuth client. Set both of these in the environment of the process that runs dispatch/MCP ā they are not stored in the repo:
MINDSYNC_ANTIGRAVITY_CLIENT_IDMINDSYNC_ANTIGRAVITY_CLIENT_SECRET
Without them, an expired Antigravity token makes the reader return unavailable (neutral, not a fake 0%). mindsync doctor reports the adapter as preemptive only when usage.enabled is on.
{
"usage": {
"enabled": false,
"defaultThresholdPercent": 90,
"orchestratorReservePercent": 80,
"pollingIntervalSeconds": 60,
"readers": {
"cursor": false
}
}
}defaultThresholdPercent: Dispatched worker handoff threshold.orchestratorReservePercent: Threshold for warning the operator before starting large runs.readers.cursor: Must betruebefore MindSync opens Cursor's IDEstate.vscdb. The other bundled readers do not need a per-reader flag.If a provider reaches threshold during a worktree job, MindSync checkpoints observable file changes before transferring them to the successor agent. If no usable checkpoint is available, the handoff stays blocked.
Automated Pull Request Workflow
Configure MindSync to automatically publish branches and open PRs upon successful task completion:
# Enable PR creation upon successful completion for current repository
mindsync config onComplete pr --project .(MindSync never auto-merges PRs and strictly declines to publish if checks fail or if secrets/sensitive tokens are detected in diffs).
š§ Persistent Memory & Shared Facts
MindSync embeds a lightweight, local vector and relational database powered by sqlite-vec for cross-session knowledge retention:
# View memory database statistics
mindsync memory stats
# List recorded facts for a specific repository
mindsync memory list --project my-repo
# Semantic search across historical decisions and architecture facts
mindsync memory recall --project my-repo --query "database migration decision"MCP Tool Bundles
Orchestrator Hosts (16 Tools): Exposes full orchestration (
delegate_task,route_task,get_sync_context,update_focus,memory_checkpoint,memory_recall,queue_durable_fact, etc.).Dispatched Workers (12 Tools): Runs with
MINDSYNC_WORKER=1, omitting recursive delegation tools while retaining shared context, focus locks, and fact retrieval.
š Safety & Security Architecture
Human-in-the-Loop Authority: The human-facing orchestrator CLI always retains final approval and verification.
Explicit Binary Execution:
mindsync setuponly configures known recipes. Unknown binaries are suggested, never executed blindly.Crash-Safe Locking: State updates use atomic writes and file locks. On Windows, lock contention timeouts are configurable via environment variables.
Secret-Safe Serialization: Job status, telemetry, and handoff payloads strictly strip access tokens, auth headers, and raw credential structures before logging.
āļø Advanced Configuration & Environment Variables
Variable | Description | Default |
| Root configuration directory |
|
| Storage for dispatch jobs and rosters |
|
| Declares calling CLI engine identity | Auto-detected |
| Max wait time for file locks (seconds) |
|
| Backoff base for Windows lock contention |
|
| Remote VPS host for optional sync | ā |
| Remote VPS sync directory | ā |
| Google installed-app client id for Antigravity token refresh | ā |
| Matching client secret. Required only when the vault access token is expired; omit both rather than guessing | ā |
š ļø Development & Testing
# 1. Clone repository
git clone https://github.com/adityarya24/mindsync-ai.git
cd mindsync-ai
# 2. Set up virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# 3. Install in editable mode with development dependencies
python -m pip install -e ".[dev]"
# 4. Run linter & test suite
python -m ruff check .
python -m pytest -qš License
Distributed under the MIT License. Open-source and free for personal and commercial use.
Available Tools
16 toolsdelegate_taskA
Delegate a task to a headless CLI agent or role.
The default agent='auto' selects an installed worker by capability. Pass required_capabilities when the orchestrator already knows what the task needs, and exclude_agents to keep the human-facing orchestrator out of the worker pool. Direct agent selection and static roles remain available as explicit overrides. If worktree is True, the agent runs in an isolated git worktree branching from cwd. checks are shell commands run after the agent finishes (for example a test command); read their outcome with job_review before spending anything on the job's output. memory_mode controls dispatch memory: auto (the default) infers an opaque Git checkout identity when no project is supplied, explicit requires memory_project, and off disables memory. An explicit project overrides inference. Raw prompts are never stored in memory. on_limit='handoff' is opt-in and requires worktree=True; only a configured, provider-specific quota signature can rotate to another available agent.
Inputs: cwd, role, agent, model, +12 more. Returns: result
eventsC
Event bus: publish, poll, or subscribe.
Inputs: action (required), agent_name (required), limit, payload, +4 more. Returns: object
get_orchestration_policyB
Read automatic delegation policy. Call when deciding whether to delegate or offer it.
Inputs: agent_name. Returns: object
get_sync_contextA
Load local session state + compiled truth. Optionally pull remote truth first.
Offline-first: always returns local data even if remote is unreachable or disabled.
Inputs: agent_name (required), project_name, refresh_remote. Returns: object
healthB
Report local paths, queue depth, and remote reachability.
Inputs: agent_name. Returns: object
jobC
Job lifecycle: status, wait, result, review, or cancel.
Inputs: action (required), job_id, agent_name, timeout_seconds, +1 more. Returns: result
listC
Orchestrator catalog: agents, models, or roles.
Inputs: kind (required), agent, agent_name. Returns: result
memory_bootstrapB
Retrieve bounded project context, prioritizing open and recent sessions.
Inputs: agent_name (required), project_key (required), budget_chars. Returns: object
memory_consolidationC
Fact consolidation: preview, apply, undo, or list.
Inputs: action (required), agent_name (required), limit, status, +6 more. Returns: object
memory_recallC
Recall related project facts with a loopback-only embedding model.
Inputs: query (required), agent_name (required), project_key (required), limit, +2 more. Returns: object
pull_truthC
Pull compiled-truth markdown from the remote host into the local cache.
Inputs: agent_name (required). Returns: object
queue_durable_factC
Write a durable fact remotely if online; otherwise queue locally for later flush.
Inputs: text (required), entity (required), attribute (required), agent_name (required), +1 more. Returns: object
route_taskB
Preview automatic worker selection without launching a job.
Inputs: prompt (required), agent_name, exclude_agents, required_capabilities. Returns: object
sessionC
Local memory session: start, checkpoint, or end.
Inputs: action (required), agent_name (required), goal, tests, +10 more. Returns: object
sync_offline_factsC
Flush the offline queue to remote, optionally consolidate + pull compiled truth.
Inputs: agent_name (required), consolidate. Returns: object
update_focusC
Update this agent's focus and warn on overlaps with other non-stale agents.
Inputs: focus (required), branch (required), project (required), agent_name (required), +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 16 tools
Several tool pairs blur together: get_sync_context and pull_truth both pull remote truth, memory_bootstrap and memory_recall both retrieve memory, and route_task plus get_orchestration_policy both serve delegation decisions. The descriptions help clarify intent, but an agent could easily select the wrong tool when aiming for a sync or memory operation.
Naming follows three conventions: verb_noun for most sync/delegation tools (queue_durable_fact, sync_offline_facts, delegate_task), bare nouns for infrastructure tools (health, job, events, session, list), and a memory_ prefix group (memory_bootstrap, memory_recall, memory_consolidation). Each pattern is readable on its own, but the mix makes the overall surface feel inconsistent.
At 16 tools, this sits at the start of the heavy band (16-25) and spans four distinct domains: sync/facts, memory, delegation/orchestration, and events. The breadth is defensible for a unified agent-sync server, but several tools could have been consolidated, pushing it slightly past a well-scoped 3-15 tool set.
Core lifecycles are well covered: offline fact queueing and flushing, memory sessions with consolidation undo, delegation preview/execute with job lifecycle, and event pub/sub. Minor gaps exist, such as a read-only orchestration policy with no setter, no way to delete a durable fact, and no offline-queue inspection beyond depth in health, but agents can work around these.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
An MCP memory server. One memory your agents share ā across models, devices and apps.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA shared memory and coordination server for multiple AI coding agents, built on the Model Context Protocol (MCP).6MIT
- AlicenseNot gradedqualityCmaintenanceA local-first MCP server for AI coding agents that shares structured execution state, routes context deltas, and provides preflight nudges to prevent conflicts and stale decisions.MIT
- FlicenseNot gradedqualityDmaintenanceA local-first MCP server that manages developer memory for coding agents, enabling shared project context, permissions, and audit trails across different agents.1-
- AlicenseAqualityBmaintenanceA local-first MCP server that provides a shared Markdown-based memory for AI coding agents, enabling cross-agent context persistence via tools like memory_search and memory_capture.161MIT