@memesh/cloud

MeMesh Cloud MCP Server — project-scoped AI memory and agent coordination across MCP-compatible clients.

Works with any MCP-compatible AI platform: Claude Code, Gemini CLI, Codex CLI, Cursor, Windsurf, Cline, and more.

Status: Alpha. MeMesh Cloud is in early access. Create an account at memesh.ai/en/signup before running setup.

Product Family

• @pcircle/memesh (npm) — the local, open-source MeMesh memory server. One SQLite file, no cloud account. Registers as memesh with bin memesh-mcp.
• @memesh/cloud (this package) — the hosted MeMesh Cloud server: project workspaces, shared project memory, and agent coordination at memesh.ai. Registers as memesh-cloud with bin memesh-cloud.

The two servers are complementary and can run side by side in the same MCP client without conflicts.

Product Boundary

MeMesh Cloud treats each workspace as an independent project boundary. MCP tools should write and retrieve memory in the selected project workspace context and preserve provenance metadata when the source comes from a project plan, runtime artifact, local MeMesh import, or shipped read-only connector source.

This MCP package can register external source metadata, queue/claim source sync work, run the shipped read-only Google Drive processor, accept local Obsidian and local MeMesh snapshots, import source content into project-scoped memory, record source provenance, and register project-scoped remote A2A dispatch targets. It does not perform bidirectional sync, write back to source systems, propagate source deletions, or silently share human provider credentials across teammates.

Quick Start

# One-time authentication
npx @memesh/cloud setup

# The MCP server starts automatically when configured in your AI client

To let an already-authenticated local CLI claim MeMesh work, run one worker in the same computer. The worker reuses the existing local execution lease and completion API; it does not upload the provider's credentials.

npx @memesh/cloud worker codex
npx @memesh/cloud worker claude
npx @memesh/cloud worker gemini

Use --once for a single queued execution. These presets require the matching codex, claude, or gemini command to already be installed and signed in on the computer. grok is currently reported as unsupported because no verified local CLI invocation is shipped.

GitHub issue sweeps (operator workflow)

MeMesh does not ship a GitHub issue connector. When an authenticated local provider has its own GitHub MCP or gh CLI, the provider can read open issues and turn them into MeMesh tasks. Keep one issue per task, include the issue number in the task result, and do not close an issue until implementation, review, and repository checks are approved. Issue access and issue closure remain in the provider's local session; an unavailable GitHub session is a blocked intake, not an empty "all clear" result.

Platform Installation

Claude Code

claude mcp add memesh-cloud -- npx -y @memesh/cloud

Or add to your user config (~/.claude.json) or project .mcp.json:

{
  "mcpServers": {
    "memesh-cloud": {
      "command": "npx",
      "args": ["-y", "@memesh/cloud"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "memesh-cloud": {
      "command": "npx",
      "args": ["-y", "@memesh/cloud"]
    }
  }
}

Or via CLI:

gemini mcp add memesh-cloud -- npx -y @memesh/cloud

OpenAI Codex CLI

codex mcp add memesh-cloud -- npx -y @memesh/cloud

Or edit ~/.codex/config.toml:

[mcp_servers.memesh-cloud]
command = "npx"
args = ["-y", "@memesh/cloud"]

Cursor

One-click install (click this link with Cursor open):

Install MeMesh in Cursor

Or manually add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "memesh-cloud": {
      "command": "npx",
      "args": ["-y", "@memesh/cloud"]
    }
  }
}

Windsurf

Add to Windsurf MCP settings (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "memesh-cloud": {
      "command": "npx",
      "args": ["-y", "@memesh/cloud"]
    }
  }
}

Cline (VS Code)

Add to Cline MCP settings:

{
  "mcpServers": {
    "memesh-cloud": {
      "command": "npx",
      "args": ["-y", "@memesh/cloud"]
    }
  }
}

Authentication

Device Flow (Recommended)

npx @memesh/cloud setup

This opens your browser for secure authorization via OAuth device flow. You need a MeMesh Cloud account first — sign up at memesh.ai/en/signup. Credentials are saved to ~/.memesh/cloud.json, which is owned by the Cloud MCP package.

Environment Variable

export MEMESH_API_KEY=mk_your_key_here

Credential Locations

The server reads credentials in this order:

1. MEMESH_API_KEY environment variable (highest priority)
2. ~/.memesh/cloud.json (canonical MeMesh Cloud credential file)

Custom API URL can be set via MEMESH_API_URL.

MEMESH_BASE_URL is retired and no longer read. If it is still set in your shell, the server names it in the message it prints when it finds no credentials, so a stale value cannot silently point you at the wrong host. Set MEMESH_API_URL instead.

Available Tools

Memory & Analytics

| Tool | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | sync_memory_to_cloud | Upload memories in batch (max 100); requires UUID project_id for project workspace memory | | search_cloud_memory | Semantic search across project workspace memory (pgvector); requires UUID project_id so retrieval stays inside one selected project workspace boundary | | write_memory | Write a single memory; requires UUID project_id to preserve project workspace provenance | | get_analytics | Retrieve usage analytics and quota information | | audit_log | Query audit logs for security and compliance |

Agent Management

| Tool | Description | | ------------------- | ---------------------------------------- | | list_cloud_agents | List registered AI agents across devices | | register_agent | Register an agent to join the network |

Inbox & Messaging

| Tool | Description | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | send_message | Send cross-agent messages with priority, threading, attachments, routing hints, and optional UUID project_id inbox context | | list_messages | Read inbox messages with type/priority filters | | mark_message_read | Mark a message as read |

Project Workspace Orchestration

Project workspace orchestration MCP tools now present one product model: every workspace is a project workspace, and every response identifies whether runtime truth is already linked through Project -> OrchestratorPlan -> AgentRun -> ApprovalRequest / RunEvent or still limited to project workspace memory.

Generic memory tools follow the same boundary. For project work, sync_memory_to_cloud, search_cloud_memory, and write_memory require UUID project_id; each forwards SDK projectId, then returns a project_workspace envelope with memory_scope: "project_memory". Cross-project or account-memory retrieval requires a separate explicit product/API path.

| Tool | Description | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create_plan | Define a phased plan inside an existing canonical project_id; new MCP plans must link to Cloud Project runtime truth | | assemble_team | Assign agents to project_id-linked roles and initialize project-scoped role memory | | register_remote_dispatch_target | Register and bind a remote A2A dispatch target to one project workspace through the canonical agents registration path | | dispatch_task | Dispatch a manifest task through the canonical project_id runtime path with role memory and compressed context | | complete_task | Return project_id-scoped retirement guidance for the old inbox completion bridge; does not complete work or save memories | | review_task | Review a project_id-linked runtime task through ApprovalRequest semantics; workspace-memory-only review is rejected | | get_project_status | Project workspace status overview by project_id: progress, pending actions, runtime audit view, assigned roles, memory, and source health | | close_project | Close a project_id-linked workspace with project-scoped retrospective memory and runtime audit summary | | manage_schedule | Create/list/pause/resume scheduled agent tasks inside one UUID project_id project workspace boundary | | register_project_source | Register a read-only external knowledge source in a project workspace | | update_project_source_connector_auth | Link or clear a human-owned connector authorization for a project source; records readiness only | | request_project_source_sync | Queue or return the existing in-flight read-only sync request for a non-paused source whose connector authorization is ready, without crawling the external source | | list_claimable_project_source_syncs | List queued or lease-expired source sync requests the caller may claim across manageable project workspaces and ready sources | | claim_project_source_sync | Claim a queued source sync request before connector work begins; records worker ownership only | | heartbeat_project_source_sync | Extend a claimed source sync worker lease while connector work is in progress | | process_google_drive_project_source_sync | Run the server-side Google Drive read-only processor for a claimed source sync and close the same syncRunId as completed or failed through runtime.status; returns documents_scanned and documents_imported from processor or sync-run truth | | process_obsidian_project_source_sync | Import a local Obsidian vault markdown snapshot for a claimed source sync and close the same syncRunId as completed or failed through runtime.status; returns documents_scanned and documents_imported from processor or sync-run truth | | process_local_memesh_project_source_sync | Import a local MeMesh memory snapshot for a claimed source sync and close the same syncRunId as completed or failed through runtime.status; returns documents_scanned and documents_imported from processor or sync-run truth | | import_project_source_documents | Import caller-provided source document content into project workspace memory and save provenance; pass sync_run_id from a queued request to close that same run and claim_token when claimed | | record_project_source_sync | Record imported document provenance, imported memory ids, sync cursor, and sync health for a project source; pass sync_run_id from a queued request to close that same run and claim_token when claimed |

Project Workspace Response Contract

Project workspace orchestration responses expose project_workspace as the only workspace-boundary envelope, so callers can distinguish the project workspace boundary from runtime execution state without guessing from tool-specific fields.

{
  "project_workspace": {
    "mode": "project_workspace",
    "isolation_boundary": "project_workspace",
    "linked_project_id": "project UUID or null",
    "canonical_truth": "project_runtime | workspace_memory",
    "runtime_status": "runtime_linked | workspace_memory_only",
    "notice": "human-readable workspace state",
    "canonical_guidance": "human-readable next action",
    "coordination_overview": {
      "roadmap": "optional linked-project roadmap progress from the SDK coordination overview",
      "agents": "optional assigned-role and role-gap counts",
      "runtime": "optional active run, pending approval, and artifact counts",
      "memory": "optional project and source memory counts",
      "sources": "optional registered source, imported document, and source health counts"
    }
  }
}

get_project_status requires the canonical Cloud project_id and reads status from client.projects.getOperationsReport(project_id), with project_workspace.coordination_overview attached from client.projects.getCoordinationOverview() when available. MCP callers should not rebuild roadmap, agent role gap, approval, artifact, memory, or source-health totals from workspace-memory manifests. Assigned project agent role binding visibility is exposed through assigned_agent_roles.roster, where each role includes the provider connection label/status and the explicit model binding returned by the project operations report.

Shared runtime Envelope

Task-related responses expose runtime posture through runtime plus runtime_links.

{
  "runtime": {
    "path": "runtime_plan | runtime_approval_request | workspace_memory | compatibility_retired",
    "project_task_id": "ptask_123 or null",
    "plan_id": "plan_123 or null",
    "task_index": 0,
    "run_id": "run_123 or null",
    "approval_request_id": "approval_123 or null",
    "state": "tool-specific runtime state or null"
  },
  "runtime_links": {
    "project_task_id": "ptask_123 or null",
    "plan_id": "plan_123 or null",
    "task_index": 0,
    "run_id": "run_123 or null",
    "approval_request_id": "approval_123 or null"
  }
}

Interpretation rules:

• runtime.path = "runtime_plan": task has been dispatched onto the orchestrator/runtime spine
• runtime.path = "runtime_approval_request": current review action is resolving canonical approval state
• runtime.path = "workspace_memory": task is still operating in project workspace memory before runtime linkage
• runtime.path = "compatibility_retired": the old completion bridge is intentionally non-executable and only returns runtime migration guidance
• runtime_links: canonical linkage IDs intended for callers and tests

Migration Assets

If you are migrating an external integration, see the hosted documentation at memesh.ai/docs for the runtime contract guide and example fixtures.

Cross-Agent Messaging

MeMesh enables AI agents on different platforms to communicate:

1. register_agent      →  Register your agent (idempotent)
2. send_message        →  Send a task/question to another agent type
3. list_messages       →  Check inbox for responses
4. mark_message_read   →  Mark a message as read

Messages can target a specific agent ID or broadcast to all agents of a type (e.g., all chatgpt agents). Supported message types: task, context, result, question, notification.

send_message supports priority (normal/high/urgent), parent_id (reply threading), attachments (up to 10 files), and routing_hints for smart agent selection.

Project Workspace Orchestration

Coordinate teams of AI agents across platforms:

1. create_plan       →  Define project_id-linked goal, phases, tasks with dependencies
2. assemble_team     →  Assign project_id-linked agent roles and role memories
3. dispatch_task     →  Dispatch project_id-linked task through runtime truth
4. complete_task     →  Retired guidance only; use runtime approval and artifact-memory paths
5. review_task       →  Review project_id-linked runtime ApprovalRequest
6. get_project_status →  Project workspace status by project_id with progress and next actions
7. close_project     →  Project-scoped retrospective and runtime audit by project_id

Key features:

• Role-based memory: Knowledge accumulates per role across tasks
• Mistake-to-experience: Errors are converted to lessons that prevent recurrence
• Quality loops: Max 3 revision rounds with enriched feedback
• Dependency management: Tasks auto-unblock when dependencies are approved
• Project-scoped learning: Retrospectives stay inside the selected project_id unless an explicit sharing path is used
• Project workspace contract: Responses include project_workspace, runtime, and runtime_links so workspace scope and runtime truth stay explicit

Using With MCP-Compatible Clients

Use @memesh/cloud as the MeMesh Cloud bridge for Claude Code, Cursor, and other MCP-compatible clients. The package exposes the hosted project workspace contract directly:

• project-scoped memory tools require an explicit project_id
• project source tools preserve provenance and read-only import boundaries
• runtime tools return project_workspace, runtime, and runtime_links

Do not treat a local knowledge graph tool as the project boundary. MeMesh Cloud keeps the selected hosted project workspace as the coordination boundary.

Requirements

• Node.js >= 18
• MeMesh Cloud account — sign up at memesh.ai/en/signup (Alpha)

Support

• Documentation: memesh.ai/docs
• Support: [email protected]

License

MIT