Database Migrations

Database Migrations

CortexPrism uses idempotent SQLite migrations via @libsql/client. Migrations are numbered sequentially and guarded by checksums.

Migration Files

Located in src/db/migrations/NNN_description.sql. All 33 migrations:

#	File	Database	Description
001	core.sql	cortex.db	sessions, turns, jobs
002	memory.sql	memory.db	5-tier memory + FTS5
003	lens.sql	lens.db	lens_events audit
004	vault.sql	vault.db	vault_entries + access_log
005	plugins.sql	plugins.db	plugin registry
006	session.sql	cortex.db	session_messages table
007	jobs_v2.sql	cortex.db	job scheduler columns
008	memory_embeddings.sql	memory.db	embedding + decay columns
009	policy.sql	cortex.db	policy_rules + default seeds
010	services.sql	cortex.db	micro-service definitions
011	workspace.sql	cortex.db	workspace_config + file_edit_log
012	plugins_enhanced.sql	plugins.db	enhanced plugin columns
013	sessions_parent.sql	cortex.db	parent_session_id for sub-agents
014	skills_origin.sql	cortex.db	skills table with origin tracking
015	nodes.sql	cortex.db	distributed node registry
016	node_policies.sql	cortex.db	per-node policy rules
017	skills_metadata.sql	cortex.db	skills metadata extension
018	quartermaster.sql	cortex.db	tool orchestration learning
019	model_quartermaster.sql	cortex.db	Model Quartermaster (MQM)
020	episodic_updated_at.sql	memory.db	updated_at + graph_relation_types seed
021	workspace_type_config.sql	cortex.db	workspace type configuration
022	a2a_discovery.sql	cortex.db	A2A agent discovery and routing tables
023	mcp_gateway_tools.sql	cortex.db	MCP gateway tool registry and routing
024	memori_checkpoints.sql	memory.db	Memori conversation checkpoints
025	eval_runs.sql	cortex.db	evaluation runner results tables
026	channel_adapters.sql	cortex.db	enhanced channel adapter storage
027	projects.sql	cortex.db	project management and isolation
028	triggers_v2.sql	cortex.db	webhook + filesystem trigger events
029	workflow_dag.sql	cortex.db	workflow DAG execution tables
030	desktop.sql	cortex.db	desktop app state and integration
031	update_tracking.sql	cortex.db	self-update tracking and integrity
032	tui_state.sql	cortex.db	TUI state persistence
033	plugin_verification.sql	plugins.db	plugin supply chain verification

Running Migrations

cortex migrate          # Apply all pending migrations
deno run --allow-all src/db/migrate.ts  # Direct execution

Creating a New Migration

1. Create src/db/migrations/NNN_description.sql using the next sequential number
2. Add an entry to the targets array in src/db/migrate.ts
3. Never edit a migration that has already been applied — create a new one instead

Migrations should be idempotent — use CREATE TABLE IF NOT EXISTS, ALTER TABLE ... ADD COLUMN IF NOT EXISTS, and other guarded statements.

Checksum Protection

Each migration has a checksum computed on first application. The system detects if a previously-applied migration has been modified and refuses to run it.

See Also

• Architecture — Database overview
• Contributing — How to add a migration