# How to Execute Migration Paths from Older Reasonix Versions (0.x) to 1.x Go Releases

> Learn how to migrate from Reasonix 0.x to 1.x. Install the new Go binary and run the migrate command to import legacy TypeScript configurations into the TOML format.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: migration-guide
- Published: 2026-08-07

---

**Migrating from Reasonix 0.x to 1.x requires installing the new Go binary and running the built-in `/migrate` command to non-destructively import legacy TypeScript configurations into the new TOML-based format.**

The esengine/DeepSeek-Reasonix repository underwent a fundamental architectural shift when version 1.0 introduced a ground-up rewrite in Go. This guide details the complete migration paths from older Reasonix versions to current releases, ensuring your API keys, project memory files, and MCP server definitions transfer seamlessly to the new stand-alone binary runtime.

## Understanding the Architectural Shift (0.x vs 1.x)

Reasonix 1.x represents a complete break from the previous TypeScript codebase. You cannot perform an in-place upgrade; migration must be executed explicitly between these distinct runtime environments.

### Legacy TypeScript Branch (v1)

The 0.x line resides on the `v1` branch and runs on Node.js. Install it via `npm i -g reasonix@0.xx` to pin a specific legacy version. This branch receives maintenance-only updates and uses configuration files located in user directories such as `~/Library/Application Support/reasonix/` or `~/.config/reasonix/`.

### Current Go Branch (main-v2)

Reasonix 1.x lives on the `main-v2` branch and compiles to a stand-alone Go binary. It introduces a new configuration hierarchy centered on [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) for project-level settings and `~/.reasonix/config.toml` for global preferences. Environment variables now store credentials in `<Reasonix-home>/.env` rather than scattered user configuration files.

## Step 1: Install the Go Binary

You must install the 1.x binary before initiating configuration migration. The project provides two primary installation methods.

### Installation via npm Wrapper

The simplest method uses npm to fetch the pre-built Go binary:

```bash

# Installs the latest 1.x release (Go binary wrapped for npm)

npm i -g reasonix

```

To maintain access to the legacy TypeScript CLI during transition, pin the last 0.x version:

```bash
npm i -g reasonix@0.53.2

```

### Building from Source

Clone the repository and compile manually for custom builds or development:

```bash
git clone https://github.com/esengine/DeepSeek-Reasonix   # Defaults to main-v2

cd DeepSeek-Reasonix
make build                                                # Outputs bin/reasonix(.exe)

```

## Step 2: Automatic Configuration Migration

When the Go binary launches, it automatically detects legacy configurations without destroying existing files.

### Legacy Config Discovery Paths

The binary scans these locations for 0.x artifacts:

- `~/Library/Application Support/reasonix/config.toml`
- `~/.config/reasonix/config.toml`
- `~/.reasonix/reasonix.toml`
- `~/.reasonix/config.json` (legacy 0.x format)

### Non-Destructive Import Process

If the binary detects legacy files and no newer configuration exists, it imports:

- **API keys and credentials** → `<Reasonix-home>/.env` (e.g., `DEEPSEEK_API_KEY`)
- **Project memory files** ([`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md)) → upgraded [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) format
- **MCP server definitions** → `[[plugins]]` sections in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml)

This process runs only once and never overwrites existing data. For the complete path specification, see [`docs/CONFIG_PATHS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CONFIG_PATHS.md) in the repository.

## Step 3: Manual Migration with the /migrate Command

If automatic detection missed files or you need to import from a custom location, invoke the explicit migration utility.

### Default Legacy Import

Run the following to import from standard legacy locations:

```bash
reasonix /migrate

```

The command prints a summary of imported assets and respects existing configurations by refusing to overwrite current [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml) or memory files.

### Custom Source Directory

Specify an explicit source path for non-standard installations:

```bash
reasonix /migrate --from "D:\OldReasonix"   # Windows example

reasonix /migrate --from "/old/path"        # Unix example

```

## Step 4: Context Engine and Memory Upgrade

The Context Engine v2 automatically loads all existing facts and memory files without requiring manual re-indexing. Your previous [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) content remains accessible, and the core agent loop preserves existing workflows for tools like `read`, `write`, `edit`, `glob`, and `grep`.

Verify the migration using the new diagnostics commands:

```bash
/memory               # List imported memory files

/memory instructions  # View system instructions

/memory recall        # Test fact retrieval

```

## Post-Migration Verification Checklist

1. **Confirm version**: Run `reasonix version` and verify it reports a `1.x` release.
2. **Validate imports**: Execute `reasonix /migrate` to ensure no legacy config files remain unimported.
3. **Test project loading**: Launch the desktop UI via `reasonix serve` and verify MCP servers defined in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) are trusted.
4. **Functional test**: Execute a task like `reasonix explore "list files"` to confirm LSP-assisted code reading operates correctly.

For edge cases and detailed troubleshooting, consult [`docs/MIGRATING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/MIGRATING.md) in the `main-v2` branch.

## Summary

- **Reasonix 1.x is a Go rewrite** on the `main-v2` branch, not an incremental update to the TypeScript 0.x (`v1`) line.
- **Install via npm** (`npm i -g reasonix`) or build from source using `make build`.
- **Automatic migration** scans legacy paths and non-destructively imports credentials to `.env`, memory to [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md), and MCP servers to [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml).
- **Manual fallback** uses `reasonix /migrate --from <path>` for custom source directories.
- **Context Engine v2** retains all previous memory and facts without re-indexing.

## Frequently Asked Questions

### Is Reasonix 1.x backward compatible with 0.x configuration files?

No, Reasonix 1.x uses a fundamentally different configuration structure. However, the `/migrate` command automatically converts legacy [`config.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.json) and [`config.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/config.toml) files into the new format, storing API keys in `.env` and project settings in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) without modifying the original files.

### Can I run Reasonix 0.x and 1.x side by side?

Yes. Install the legacy version using `npm i -g reasonix@0.53.2` (or your specific 0.x version) and the current version using `npm i -g reasonix`. The binaries operate independently, though you should verify that environment variables do not conflict if running simultaneous instances.

### What happens to my existing project memory during migration?

All facts and memory files automatically load into Context Engine v2. The migration process upgrades [`REASONIX.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) and [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md) files to the new format while preserving content. No manual re-indexing or data export is required, and archived memory remains accessible via `/memory archived`.

### Where are migrated credentials stored in Reasonix 1.x?

The migration utility extracts API keys and sensitive data from legacy config files and writes them to `<Reasonix-home>/.env` (typically `~/.reasonix/.env`). This centralizes credentials outside of version-controlled configuration files, improving security while maintaining accessibility for the Go binary.