Database Migrations

Database Migrations

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

Migration Files

Located in packages/core/src/db/migrations/NNN_description.sql. All 47 migrations:

#	File	Database	Description
001	001_core.sql	cortex.db	sessions, turns, jobs
002	002_memory.sql	memory.db	5-tier memory + FTS5
003	003_lens.sql	lens.db	lens_events audit
004	004_vault.sql	vault.db	vault_entries + access_log
005	005_plugins.sql	plugins.db	plugin registry
006	006_session.sql	per-session	session_messages table
007	007_jobs_v2.sql	cortex.db	job scheduler columns
008	008_memory_embeddings.sql	memory.db	embedding + decay columns
009	009_policy.sql	cortex.db	policy_rules + default seeds
010	010_services.sql	cortex.db	micro-service definitions
011	011_workspace.sql	cortex.db	workspace_config + file_edit_log
012	012_plugins_enhanced.sql	plugins.db	enhanced plugin columns
013	013_sessions_parent.sql	cortex.db	parent_session_id for sub-agents
014	014_skills_origin.sql	memory.db	skills origin tracking
015	015_nodes.sql	cortex.db	distributed node registry
016	016_node_policies.sql	cortex.db	per-node policy rules
017	017_skills_metadata.sql	memory.db	skills metadata extension
018	018_quartermaster.sql	cortex.db	tool orchestration learning
019	019_model_quartermaster.sql	cortex.db	Model Quartermaster (MQM)
020	020_episodic_updated_at.sql	memory.db	updated_at + graph_relation_types seed
021	021_workspace_type_config.sql	cortex.db	workspace type configuration
022	022_policy_enabled.sql	cortex.db	policy enabled flag
023	023_skills_enhancements.sql	memory.db	skills lifecycle, trust, health, deps, embedding
024	024_codegraph.sql	memory.db	code graph tables (nodes, edges, communities)
025	025_data_sensitivity.sql	cortex.db	data sensitivity classification
026	026_memory_sensitivity.sql	memory.db	memory sensitivity classification
027	027_lens_sensitivity.sql	lens.db	lens event sensitivity classification
028	028_channel_sessions.sql	cortex.db	channel session tracking
029	029_channel_messages.sql	cortex.db	channel message storage
030	030_channels_config.sql	cortex.db	channels configuration
031	031_job_runs.sql	cortex.db	job runs tracking
032	032_memori_checkpoints.sql	cortex.db	memori conversation checkpoints
033	033_plugins_verification_report.sql	plugins.db	plugin supply chain verification reports
034	034_sandbox_snapshots.sql	cortex.db	sandbox snapshots, workspace snapshots, dev env manifests, bug repro runs
035	035_compliance.sql	lens.db	compliance metadata and audit records
036	036_jobs_source.sql	cortex.db	jobs source tracking (ui, cli, seed, tool)
037	037_graph_metadata.sql	memory.db	graph metadata extensions
038	038_episodic_last_accessed.sql	memory.db	episodic memory last accessed tracking
039	039_shared_context.sql	memory.db	shared context between agents
040	040_linked_sessions.sql	memory.db	linked session relationships
041	041_cleanup_orphaned.sql	cortex.db	orphaned data cleanup
042	042_policy_review.sql	cortex.db	policy CHECK constraint widening + deny rules
043	043_swarm.sql	cortex.db	swarm directives, resource snapshots, node metrics
044	044_users_teams.sql	cortex.db	identity: users, teams, agents, membership, federation
045	045_vault_scoping.sql	vault.db	vault entry owner scoping columns
046	046_memory_scoping.sql	memory.db	memory table user/team scoping columns
047	047_core_scoping.sql	cortex.db	resource table user/team scoping columns

Database Files

Database	Purpose
cortex.db	Sessions, jobs, policies, services, nodes, agents, workspace config
memory.db	5-tier memory: episodic, semantic, reflection, graph, skills
lens.db	Audit log — full activity timeline, security events, metrics
vault.db	AES-256-GCM encrypted credential vault
plugins.db	Plugin registry with versions, permissions, and trust levels
Per-session .db	Individual session message storage

Running Migrations

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

Creating a New Migration

1. Create packages/core/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. applyMigration() is resilient to concurrent execution, catching "already exists" errors from multi-process startup and recording them as applied via INSERT OR IGNORE.

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
• Memori Checkpoints — Migration 032 details
• Sandbox — Migration 034 details