RaiSE 3.1.0 Release Notes¶

What changed and what you must do.

Each section follows the format: Change / Why / Required action.

Upgrading from any earlier version? The upgrade guide routes you by install method and walks the path step by step — including the rai self-update defect that affects every release candidate up to rc5. Coming from a per-project venv or pip, it hands off to the venv-to-binary migration guide.

1. Install method change¶

Change: The global binary is now the recommended and supported install method. All per-project venv, pip, pipx, and legacy install.sh methods are legacy.

Why: Per-project venvs create 5 GB of duplicated Python environments per checkout, produce residues that confuse the graph scanner and database migration, and require activation before every command. The global binary is a single install: no Python required, no venv, no activation.

Required action: Follow the Migration Guide to uninstall the legacy method and install the global binary. Run rai clean --dry-run in each project checkout afterward.

2. New: `rai clean`¶

Change: A new rai clean command detects and removes legacy installation residues. rai doctor gained a legacy check category (rai doctor -c legacy). On session open, a one-time advisory is shown if legacy residues are detected; it is snoozed once the user runs rai clean --dry-run.

Why: Users upgrading from per-project installs accumulate orphan venvs, local databases, stale config entries, and dependency references. Without a tool to find and clean them, migration takes hours of manual inspection (one field report measured twenty hours across two days).

Required action: Run rai clean --dry-run once per project checkout to review residues. Then rai clean to process owned residues, and rai clean --fix-config to repair configuration files. Use rai clean --force only if you also want to process advisory residues (files you own, like pyproject.toml).

3. Graph is checkout-scoped (schema v68)¶

Change: The knowledge graph index is now scoped to each checkout. The prior shared partition (last-writer-wins across checkouts of the same repo) is discarded. The graph must be rebuilt per checkout.

Why: Multi-checkout projects previously shared a single graph partition. Whichever checkout ran rai graph build last overwrote the others' data. The checkout-scoped layout attributes nodes correctly and eliminates silent data loss.

Required action:

Run rai clean --dry-run first -- this flags the stale repo cartridge as an advisory residue (repo-cartridge-self-ingest). rai clean cannot remove it automatically; you must move the stale cartridge aside manually:
```
mv .raise/cartridges/repo/instances /tmp/repo-instances-aside
```
Then rebuild per checkout:
```
cd ~/projects/my-app
rai graph build
```
Repeat for every checkout and worktree.

If the graph build fails with RepoCartridgeCollapseError, move the stale cartridge aside first:

mv .raise/cartridges/repo/instances /tmp/repo-instances-bak
rai graph build

4. Memory is tiered¶

Change: Memory is now organized into two tiers. Tier-1 (MEMORY.md index) keeps mission-scoped, recent, and critical notes. Tier-2 stores demoted notes (aged project notes beyond 30 days, non-critical feedback, and reference notes) for retrieval via the hint oracle and graph queries.

Why: As projects accumulate memory notes, the context window fills with stale or low-relevance entries. Tiering keeps the working context focused while preserving historical knowledge for on-demand retrieval.

Required action: Tier-2 retrieval requires running rai memory ingest --apply manually. This is not automatic today. Without this step, demoted notes leave Tier-1 but are not queryable via Tier-2 -- demotion is effectively one-way until you run the ingest. Run:

rai memory ingest --apply

This creates the memory cartridge at ~/.rai/cartridges/memory/ and indexes demoted notes for graph-based retrieval.

5. Skills export to other harnesses¶

Change: Skills are now exported as portable markdown files that work across AI coding tools (Claude Code, Cursor, Aider, Codex, etc.).

Why: Skills were previously coupled to Claude Code's custom command mechanism. The portable format allows the same governance workflows to run in any tool that supports custom instructions.

Required action: Re-sync skills in each project:

rai init --detect     # or rai upgrade

6. DB migration 45 to 79¶

Change: The database schema migrates from version 45 to 79. The migration is forward-only and happens automatically the first time any rai command opens the database. This includes read-only commands like rai db status and rai db check -- reading the schema version is what triggers the migration.

Why: The new schema supports checkout-scoped graphs, tiered memory, signal tracking, and other 3.1 features.

Required action: Back up your database before running any rai command with the new binary. The migration is irreversible.

cp ~/.rai/raise.db ~/.rai/raise.db.backup-pre-3.1

The migration itself is fast (measured at 1.7 seconds on a production database with 45 tables) and exact -- rehearsals matched the live run row-for-row in field testing.

Note: rai db import-legacy (formerly rai db migrate) imports legacy JSONL/YAML personal data into SQLite (a one-time data import, not the schema migration). The schema migration happens in create_all() on any database open.

7. Known issues¶

The following items are known and documented in the Troubleshooting Guide:

PATH shadowing: After installing the global binary, legacy entry points (.venv/bin/rai, pipx shims) may still win in PATH resolution. See troubleshooting entry #1.
.mcp.json tracked in git: Projects that committed .mcp.json to version control block automatic reprovisioning. rai clean --fix-config handles this, but the diff must be reviewed and committed manually. See troubleshooting entry #2.
RepoCartridgeCollapseError on first graph build: The stale repo cartridge from pre-3.1 re-ingests its own nodes. rai clean flags this as an advisory; the workaround is to move instances/ aside before rebuilding. See troubleshooting entry #4.
Tier-2 memory retrieval requires manual ingest: rai memory ingest --apply must be run manually. Automated ingest during tiering is planned but not yet wired up.
Base pattern uniqueness is global: pattern_id is a global primary key. The first project to install base patterns owns them; other projects see zero base patterns. This is a known design constraint, not a regression.

Bugfixes included in 3.1.0 (not in rc3)¶

RAISE-16215: Renamed venvs (.venv.old, .venv-backup) are now excluded from the code scanner via _is_venv_like. In rc3, only exact names were excluded, causing renamed venvs to produce massive garbage graphs.

8. Command changes that break scripts¶

Change: four command surfaces changed in ways that break automation which worked on 3.0 or on a release candidate.

Change	What to do
`rai init` is plan-only — it prints what it would write and exits	Add `--apply` wherever it runs unattended. `--dry-run` remains as a deprecated no-op alias. `rai upgrade` is unaffected: it still writes by default.
`rai scm` lost five proxy commands (`repos`, `branches`, `disconnect`, `create-pr`, `get-pr`)	`create-pr` → `rai scm create-mr`; `get-pr` → your provider's CLI; the other three have no replacement. The group now exposes `resolve-conflicts`, `create-mr` and `merge-mr`.
`rai db migrate` renamed to `rai db import-legacy`	Rename the call. The old name still works but is deprecated.
`rai clean` scans all registered projects by default	Add `--path .` for the previous current-directory-only behaviour. When stdin is not a tty, `rai clean` already defaults to dry-run.

Why: rai init was hardened for adoption on existing, non-greenfield repositories, where an unattended write is destructive — a single explicit write-gate replaced a mix of implicit writes and --dry-run. The five rai scm commands proxied through a server-side adapter that was removed; the local ScmAdapter protocol replaces it and works against GitHub and GitLab without a server round-trip. The old db migrate name wrongly suggested it ran the schema migration.

Required action: audit shell scripts, CI jobs, provisioning tooling and Makefiles for these four commands. If you discovered SCM adapters through the rai.adapters.scm entry-point group, note that the group is removed, not emptied — load the ScmAdapter protocol from raise_cli.scm via from_manifest() instead.

Upgrading? The upgrade guide covers the mechanics; this section covers what to change in your own automation.

9. Other behavior changes¶

Bare rai launches the Textual TUI cockpit. Running rai with no subcommand starts the redesigned Textual cockpit instead of the previous Rich one. No action is required unless you depend on the old interface:

rai --legacy                  # per invocation
export RAI_COCKPIT_LEGACY=1   # persistent

rai --version reports git-state drift. On editable or git checkouts it now also warns when the declared version is ahead of, or unrelated to, its release tag. Frozen binary installs are unaffected.

Server operators: additive Alembic migrations. Teams running raise-server pick up several additive migrations. They run automatically on server restart (alembic upgrade head on dev, the migrate job on production). Take a snapshot first if your pipeline_runs table is large. CLI-only users are not affected.

10. New in 3.1.0¶

You do not have to adopt any of these:

rai self-upgrade — the package and project layers in one command, in the order that matters. See the upgrade guide.
rai clean — finds and removes legacy install residues; rai doctor -c legacy is the matching diagnostic (see section 2).
rai ddd — tactical domain modelling: discover, refine, validate and report.
rai graph gained fields, contexts, classify, assign-bcs and prune. Note that rai graph prune is a different thing from the --prune flag on rai graph build: it deletes graph rows for worktrees whose checkout no longer exists on disk.
rai telemetry ingest-tool-cost and rai telemetry backfill-story-costs.
Two new adapters. local joins the rai.adapters.pm group alongside filesystem and jira; platform joins rai.docs.targets alongside filesystem, confluence and gdrive. The existing filesystem adapters in both groups are unchanged — the only entry-point group removed in this release is rai.adapters.scm (see section 8).
Redesigned admin UI and cockpit TUI, HTML artifact publishing through rai docs publish, and container agent orchestration.