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

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 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:

# 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:

npm i -g reasonix@0.53.2

Building from Source

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

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, AGENTS.md) → upgraded REASONIX.md format
• MCP server definitions → [[plugins]] sections in reasonix.toml

This process runs only once and never overwrites existing data. For the complete path specification, see 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:

reasonix /migrate

The command prints a summary of imported assets and respects existing configurations by refusing to overwrite current config.toml or memory files.

Custom Source Directory

Specify an explicit source path for non-standard installations:

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 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:

/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 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 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, and MCP servers to 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 and config.toml files into the new format, storing API keys in .env and project settings in 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}