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