Database
RaiSE stores all personal state in a single SQLite database at ~/.rai/raise.db. This is the consolidated database — one file that holds sessions, patterns, missions, worktrees, signals, and learning records across all your projects.
What It Stores¶
The database contains 50+ tables organized by domain:
| Domain | Key tables | Purpose |
|---|---|---|
| Sessions | sessions, session_journals, session_bindings |
Session lifecycle, journal entries, variable bindings |
| Graph | graph_nodes, graph_edges, graph_annotations |
Knowledge graph persistence and DDD annotations |
| Patterns | patterns, pattern_reinforcements |
Extracted learnings with reinforcement tracking |
| Backlog | backlog_items, backlog_cache |
Local backlog mirror and cache |
| Worktrees | worktrees, worktree_stories |
Registered worktrees with merge targets and story bindings |
| Artifacts | artifacts, artifact_versions |
Governance artifacts with versioning |
| Telemetry | signals, token_usage, cost_records |
Work events, token tracking, cost analysis |
| Infrastructure | schema_version, migrations, learning_records |
Schema management and calibration data |
The database is personal — it is not committed to git. It lives in your home directory and persists across projects, worktrees, and sessions.
Migration from Per-Project DBs¶
Prior to v3.1.0 (Epic E8204), RaiSE maintained a separate .raise/raise.db in each project directory. This caused state fragmentation: patterns captured in one worktree were invisible in another, and mission state could diverge between checkouts.
E8204 consolidated all personal state into ~/.rai/raise.db. Per-project databases are no longer created. The rai db consolidate command migrates existing per-project data into the global store.
If you have old per-project databases, run:
Key Commands¶
| Command | What it does |
|---|---|
rai db status |
Show database stats: tables, row counts, size, schema version |
rai db check |
Check database integrity, foreign keys, and schema invariants |
rai db consolidate |
Merge orphaned per-project DBs into the global store |
rai db export |
Export all tables to JSONL files for backup |
rai db import |
Import JSONL backup into the local database |
rai db import-legacy |
Import legacy JSONL/YAML personal data into SQLite (one-time) |
The Golden Rule: Never Touch .db Files Directly¶
Do not open, edit, copy, or move .raise/*.db or ~/.rai/raise.db with anything other than the rai CLI.
SQLite files can be silently corrupted by concurrent writers. Copying a live database can produce an inconsistent snapshot. Editing records directly bypasses validation and can leave foreign keys broken.
The CLI is the only safe interface. If you need to inspect data for debugging, use rai db export to get a JSONL snapshot, or rai db status for counts.
Backup and Recovery¶
The database is not version-controlled. Back it up as part of your machine backup strategy. For point-in-time recovery:
If the database becomes corrupted:
The import command restores from a JSONL backup created by rai db export. Some learning data may be lost if the backup is not recent.
Next Steps¶
- CLI Reference: db — all flags and options
- Memory — how patterns and sessions relate to database records
- Worktrees — worktree registrations stored in the DB