| 1 | # Migrating to Reasonix 1.0 (the Go rewrite) |
| 2 | |
| 3 | Reasonix 1.0 is a **ground-up rewrite in Go**. It is a new codebase, not an |
| 4 | incremental upgrade of the `0.x` TypeScript releases. This guide explains what |
| 5 | changed and how to move over. |
| 6 | |
| 7 | ## TL;DR |
| 8 | |
| 9 | | | Legacy (v1) | Reasonix 1.0+ (v2) | |
| 10 | |---|---|---| |
| 11 | | Language | TypeScript / Node | Go | |
| 12 | | Branch | [`v1`](https://github.com/esengine/DeepSeek-Reasonix/tree/v1) (maintenance only) | `main-v2` (default, active) | |
| 13 | | Versions | `0.x` (up to v0.54.x) | `1.0.0`+ | |
| 14 | | Install | `npm i -g reasonix@0.53.2` (pin a `0.x` version) | `npm i -g reasonix` — `latest` points at the current official `1.x` release; or a release archive / `go build` | |
| 15 | | Code intelligence | embedding semantic search + tree-sitter symbols | LSP-assisted code reading plus grep/read_file/glob; semantic index is not yet ported | |
| 16 | |
| 17 | "v1" and "v2" are **codebase generations**, not semver: the v1 line never reached |
| 18 | 1.0, so the Go rewrite takes the `1.x` major. |
| 19 | |
| 20 | ## Installing 1.0 |
| 21 | |
| 22 | `npm` stays the primary channel — the package wraps the prebuilt Go binary (the |
| 23 | same way esbuild/biome ship native binaries via npm). The binary itself is a |
| 24 | standalone Go executable; npm is only the installer, not a runtime dependency. |
| 25 | |
| 26 | **`npm i -g reasonix` installs the current official `1.x` release.** npm's `latest` tag |
| 27 | moved to the Go line with `1.17.5` — the earlier "`latest` stays pinned to |
| 28 | `0.x`" migration guard silently downgraded `npm update -g` users once 1.x went |
| 29 | official (#5822), so it was retired. Public release candidates are no longer |
| 30 | published. The legacy `next` and `canary` tags are compatibility aliases for |
| 31 | the same official version; `0.x` stays installable by pinning: |
| 32 | |
| 33 | ```sh |
| 34 | npm i -g reasonix # current official 1.x release |
| 35 | npm i -g reasonix@0.53.2 # pin the legacy TS build |
| 36 | ``` |
| 37 | |
| 38 | Prebuilt archives (`reasonix-<os>-<arch>.tar.gz` / `.zip`) and the desktop |
| 39 | installer are attached to each GitHub release. These are a **separate channel** |
| 40 | from npm: the installer drops a standalone desktop/binary build and does not |
| 41 | touch a CLI you installed with `npm i -g`, so the two coexist — an npm `0.53` in |
| 42 | your shell alongside a `1.x` desktop app is expected, not a conflict. Or build |
| 43 | from source: |
| 44 | |
| 45 | ```sh |
| 46 | git clone https://github.com/esengine/DeepSeek-Reasonix # default: main-v2 (Go) |
| 47 | cd DeepSeek-Reasonix && make build # -> bin/reasonix(.exe) |
| 48 | ``` |
| 49 | |
| 50 | ## Configuration |
| 51 | |
| 52 | | Legacy | Reasonix 1.0 | |
| 53 | |---|---| |
| 54 | | TS config files | `reasonix.toml` (project) / `config.toml` in Reasonix home (`~/.reasonix/` on macOS/Linux; `%AppData%\reasonix\` on Windows) from v1.8.1 — see `reasonix.example.toml` and [Configuration paths](./CONFIG_PATHS.md) | |
| 55 | | env / API keys | Provider config keeps `api_key_env`; saved key values live in Reasonix home `.env` (`DEEPSEEK_API_KEY`, `MIMO_API_KEY`, …) | |
| 56 | | project memory | `REASONIX.md` (+ auto-memory), Claude-Code-compatible | |
| 57 | | MCP servers | `[[plugins]]` in `reasonix.toml`, or a Claude-Code `.mcp.json` (read as-is) | |
| 58 | |
| 59 | On first launch, v1.8.1+ runs a one-time, **non-destructive** import: it reads |
| 60 | legacy config from `~/Library/Application Support/reasonix/config.toml`, |
| 61 | `~/.config/reasonix/config.toml`, `~/.reasonix/reasonix.toml`, or v0.x |
| 62 | `~/.reasonix/config.json` (API key, base URL, language, MCP servers), migrates |
| 63 | legacy credentials into `<Reasonix home>/.env` when a key is missing there, and |
| 64 | imports past sessions from legacy session directories. Old files are left |
| 65 | untouched, and Reasonix prints a boot notice when it imports data. Each session lands in the |
| 66 | workspace it belonged to (read from its v0.x sidecar meta, summary carried over |
| 67 | as the title), so the desktop sidebar lists it under the right project; sessions |
| 68 | whose workspace no longer exists land in the global session dir. Imported |
| 69 | sessions resume with `--resume` or the history panel. The config import only |
| 70 | runs when no v1.8.1+ config exists yet — if v1.8.1+ wrote its config before your |
| 71 | legacy data was in place nothing is overwritten, so copy any missing values |
| 72 | across by hand. |
| 73 | |
| 74 | If the automatic pass missed data because you opened a v1.8.1+ CLI/desktop build |
| 75 | before the old paths were available, run `/migrate` from an interactive session. |
| 76 | The command is available only in Go-based Reasonix builds that include it; if you |
| 77 | see `unknown command`, upgrade first. It prints progress while it checks legacy |
| 78 | config and credentials, scans legacy memory and session directories, imports |
| 79 | memory files and sessions that were not previously imported, and summarizes the |
| 80 | result. `/migrate` keeps the same safety rules as startup migration: it does not |
| 81 | overwrite an existing `config.toml` or memory file, it respects session import |
| 82 | markers, and it is not available in the legacy 0.x TypeScript line. If the old |
| 83 | v0.x sessions are in a custom Windows install/data directory, use |
| 84 | `/migrate --from "D:\OldReasonix"` to import sessions from that explicit source. |
| 85 | See |
| 86 | [Configuration paths](./CONFIG_PATHS.md) for the full path list and limitations. |
| 87 | |
| 88 | ## Context Engine v2 upgrade |
| 89 | |
| 90 | Instruction and memory upgrades are automatic and do not require a setup mode, |
| 91 | re-index command, or new configuration: |
| 92 | |
| 93 | | Existing data | Upgrade behavior | |
| 94 | | --- | --- | |
| 95 | | `REASONIX.md`, `AGENTS.md`, `CLAUDE.md` | Loaded as standing instructions with source, directory, precedence, imports, and diagnostics. Existing file names remain valid. | |
| 96 | | Nested instruction files | Resolve from workspace root to the active target path; within one directory, `.local.md` wins. Deeper directories still outrank broader ones. | |
| 97 | | Legacy fact without `id` / `revision` | Receives a deterministic scope-aware `legacy-*` ID and starts at revision 1. Migration is idempotent. | |
| 98 | | Legacy fact without `metadata.scope` | Scope is inferred from the project/global directory that already owns the file. | |
| 99 | | Existing `MEMORY.md` | Treated as a derived index and rebuilt from active fact files; hand-carried stale entries do not become facts. | |
| 100 | | Existing active facts | Remain active and gain revision history only when subsequently changed. | |
| 101 | | Existing archive entries | Remain excluded from recall and can be recovered explicitly from Context Center or `/memory recover`. | |
| 102 | | Old Memory v5 transcript | Remains readable; previews recover the original user prompt from `<memory-compiler-execution>`. | |
| 103 | | `[agent].memory_compiler` | Retired and removed by the existing one-time config migration. | |
| 104 | |
| 105 | The first current boot persists missing identity/timestamp metadata without |
| 106 | changing the fact body. Compatibility routing fields keep older Reasonix |
| 107 | clients from moving a fact into the wrong scope directory if versions share the |
| 108 | same state root. |
| 109 | |
| 110 | After upgrading, use these diagnostics instead of editing migration state: |
| 111 | |
| 112 | ```text |
| 113 | /memory |
| 114 | /memory instructions |
| 115 | /memory recall |
| 116 | /memory revisions <id-or-name> |
| 117 | /memory archived |
| 118 | ``` |
| 119 | |
| 120 | New relevant facts are recalled automatically. Only bounded, non-sensitive, |
| 121 | create-only project/reference facts may be saved without a confirmation; |
| 122 | global facts, preferences, feedback, updates, duplicates, sensitive content, |
| 123 | and every archive operation remain explicit user decisions. The desktop |
| 124 | Suggestions tab scans automatically but never saves a candidate until accepted. |
| 125 | |
| 126 | See [Context Engine v2](./SESSION_MEMORY_RETRIEVAL.md) for the full precedence, |
| 127 | freshness, recovery, cache, privacy, and remote-workspace contract. |
| 128 | |
| 129 | ## What's the same |
| 130 | |
| 131 | The agent core carries over: the loop, tools (read/write/edit/glob/grep/bash/…), |
| 132 | subagents (`task`, explore/research/review), skills, hooks, plan mode, MCP client, |
| 133 | and DeepSeek prefix-cache–oriented design. |
| 134 | |
| 135 | ## What's different |
| 136 | |
| 137 | - **Code intelligence**: the Go rewrite uses LSP-assisted code reading plus |
| 138 | `grep` / `read_file` / `glob` for local understanding. The legacy v1 semantic |
| 139 | search + tree-sitter symbol index is not bundled in v2 yet, and CodeGraph is no |
| 140 | longer shipped as an internal MCP server. |
| 141 | - **Plan mode** + `complete_step` (evidence-backed step sign-off). |
| 142 | - **MCP project identity and schema-cache URLs are credential-aware**: userinfo |
| 143 | and credential query values (token, api_key, password, ...) do not enter the |
| 144 | project launch identity digest or schema cache key, so credential rotation |
| 145 | keeps the same project runtime/cache identity. User-installed servers do not |
| 146 | compute a project identity digest. Legacy launch/tool authorization receipts |
| 147 | are no longer required by configured MCP servers. |
| 148 | - **MCP setup is now add-and-use.** Servers added by the user (Desktop, CLI, |
| 149 | user config, legacy user import, or a user-installed plugin package) are |
| 150 | trusted immediately and global installs persist to `config.toml`. Repository |
| 151 | `reasonix.toml` / `.mcp.json` servers stay project-scoped and are trusted |
| 152 | without a separate launch confirmation. Project entries override same-name |
| 153 | global entries; `reasonix.toml` overrides `.mcp.json` inside the project. |
| 154 | Treat opening an unfamiliar repository as opting into executable project |
| 155 | configuration: review `.reasonix/settings.json`, `reasonix.toml`, and |
| 156 | `.mcp.json` before starting Reasonix. If a repository causes unexpected MCP |
| 157 | or Hook behavior, close that workspace and correct or remove the project-local |
| 158 | entries before reopening it. |
| 159 | - **stdio MCP connections are persistent.** This fixes stateful servers that |
| 160 | lost browser/session state when writer calls received a fresh process. |
| 161 | - **Plan mode and permission policy are now independent**: Plan directs the |
| 162 | model to plan first. Ordinary built-in and Bash calls still use the active |
| 163 | Ask/Auto/YOLO rules and Sandbox, while installed MCP and proxy-resolved MCP |
| 164 | writer/destructive targets plus readers from unauthorized servers stay hard-blocked for the |
| 165 | whole planning phase. Explicit execution-phase tools such as `complete_step` also |
| 166 | remain unavailable until plan approval. `plan_mode_read_only_commands` is |
| 167 | still parsed and round-tripped for old configs, but it no longer controls |
| 168 | main Plan availability. Installed or project-configured servers contribute their |
| 169 | non-destructive `readOnlyHint` tools to planner/read-only registries |
| 170 | automatically. Use `read_only_task` / |
| 171 | `read_only_skill` when a child must be technically restricted to read-only; |
| 172 | ordinary `task` / `run_skill` calls remain writer-capable and permission-gated |
| 173 | in Plan. Installed MCP tools use the server's `readOnlyHint` for ordinary |
| 174 | dispatch. Tools without the hint remain writer-classified. The retired |
| 175 | `default_tools_approval_mode`, `tools.<raw>.approval_mode`, and |
| 176 | `approvals_reviewer` fields are ignored and removed on the next save; installing |
| 177 | or explicitly authorizing a server now makes all of its tools directly usable. |
| 178 | - **Read-only subagent research**: use `read_only_task` for generic isolated |
| 179 | research in plan mode, or `read_only_skill` when the work should follow an |
| 180 | existing skill. Both expose only read-only tools and safe foreground bash, do |
| 181 | not write resumable transcripts, and keep writer-capable `task` / `run_skill` |
| 182 | out of those explicitly read-only child registries. Ordinary writer-capable |
| 183 | delegation in Plan uses Permissions/Sandbox. |
| 184 | - **Web dashboard remains available; desktop is recommended**: run |
| 185 | `reasonix serve` when a local browser UI is useful. For the primary visual |
| 186 | experience, prefer the Wails desktop app; CLI/TUI remains the terminal-native |
| 187 | path. |
| 188 | - Some granular v1 tools are intentionally consolidated (e.g. file-management ops |
| 189 | go through `bash`); a few v1 tools are not yet ported (tracked on Discussions). |
| 190 | |
| 191 | ## File encoding |
| 192 | |
| 193 | Reasonix 1.0 supports reading and editing files in UTF-8, UTF-8 BOM, UTF-16 |
| 194 | LE/BE, and GB18030 (a superset of GBK). This matches v1's behavior. |
| 195 | |
| 196 | - `read_file` decodes any supported encoding to UTF-8 for the model. |
| 197 | - `edit_file` and `multi_edit` preserve the file's original encoding — if you |
| 198 | edit a GB18030 file, it stays GB18030 on disk. |
| 199 | - `write_file` always writes UTF-8 (the model's output encoding). |
| 200 | - `grep` decodes before matching, so regex patterns work on non-UTF-8 files. |
| 201 | |
| 202 | ## Reporting issues |
| 203 | |
| 204 | Issues and PRs are labelled by line: **`v1`** (legacy TypeScript) and **`v2`** |
| 205 | (Go). File new reports against the line you're using. The legacy `v1` line is in |
| 206 | maintenance mode — bug fixes only, no new features. |
| 207 | |
| 208 | Questions? Open a [Discussion](https://github.com/esengine/DeepSeek-Reasonix/discussions). |
| 209 |