> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to Reason

> Move your agents, memory, skills, routines, secrets and MCP servers from another agent platform into Reason with the migrate-to-reason skill.

Already run agents on another platform? The migrate-to-reason skill moves your setup into Reason. The agent you are leaving runs the skill. It exports everything it can reach into a portable bundle, then imports the bundle through Reason's public API.

The skill works from Claude Code, Codex, Cursor, Grok Bot, OpenClaw, Devin and similar agents. It can back the bundle up to a private GitHub repository you own, so you can restore it later.

Install the skill into the agent you are leaving:

```sh theme={null}
npx skills add reason-machines/skills --skill migrate-to-reason
```

Want to read it first? See [the migrate-to-reason folder](https://github.com/reason-machines/skills/tree/main/migrate-to-reason).

## What moves where

| From the old platform | In Reason | Notes |
| - | - | - |
| An agent or bot: name, persona, instructions | A Reason | Each agent becomes its own Reason. |
| Routines, schedules, cron jobs, triggers | Loops on that Reason | Event triggers become Loop triggers. |
| Memory files, notes, learned facts | Reason memory | Each Reason reads its memory at the start of every Session. |
| Skills, rules, custom commands | Reason skills | The person's own skills move. Built-in skills of the old platform stay behind. |
| Secrets, API keys, environment variables | Workspace secrets | Values move only when the skill can read them. Otherwise the names are listed for you. |
| MCP servers | Reason MCP servers | Servers with a URL, command or headers move as they are. |
| OAuth apps: Slack, GitHub, Linear, Gmail, Notion | Reason connections | Each one needs a sign-in once, from the report's reconnect link. |
| Work in progress, open threads | A handoff message to each Reason | Sent only when you import with the handoff option. |

Conversation transcripts cannot be imported as history. The skill puts their gist into the handoff message, and into memory where it lasts.

## Before you start

You need:

* The migrate-to-reason skill installed in the agent you are leaving.
* A Reason API key for the workspace you are moving into.

Create the key in **Settings > API** for the workspace, and give it a short expiry. Select these scopes:

| Scope | Why |
| - | - |
| `run` | Start agent work for each Reason |
| `repos:read` | Read the repositories each Reason uses |
| `memory:read`, `memory:write` | Read and write memory |
| `skills:read`, `skills:write` | Read and write skills |
| `secrets:read`, `secrets:write` | Read and write workspace secrets |
| `mcp:read`, `mcp:write` | Read and write MCP servers |
| `automations:read`, `automations:write` | Read and write Loops |
| `sessions:read` | Read Sessions |

The skill never prints the key or puts it in the bundle. Keep it in your environment or your password manager.

## How to start

1. Install the skill with the command above. It lets you pick the agent to install into.
2. Ask that agent to migrate you to Reason, for example: "Migrate my agents to Reason."
3. When the agent asks for it, give it the API key.
4. The agent inventories your setup, writes the bundle, checks it with a dry run, and imports it. It tells you before importing anything private.

Your old agent keeps running until you switch it off. If it still runs its own routines, the skill imports the matching Loops turned off, so the same job does not run twice.

## What you get at the end

The agent ends with a report:

* **What moved:** counts for each kind of item, and a link to each Reason.
* **What needs one action from you:** usually a reconnect for each OAuth app (Slack, GitHub, Google and others), and any secret the agent could not read.
* **What could not move, and why.**

Check the report's links to each Reason before you switch off the old platform.

## Next steps

* [Connect an agent](https://ara-90a60a07.mintlify.site/docs/mcp.md) if you want to keep using your current agent with Reason.
* [Authentication and scopes](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md) for how API keys and their scopes work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.