@timmeck/trading-brain 1.0.0

package/src/cli/commands/query.ts

@@ -0,0 +1,28 @@
+import { Command } from 'commander';
+import { withIpc } from '../ipc-helper.js';
+import { c, icons, header } from '../colors.js';
+
+export function queryCommand(): Command {
+  return new Command('query')
+    .description('Search trades and signals')
+    .argument('<search>', 'Search query (fingerprint, pair, bot type)')
+    .option('-l, --limit <n>', 'Max results', '20')
+    .action(async (search, opts) => {
+      console.log(header('Trade Search', icons.search));
+
+      await withIpc(async (client) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const results: any = await client.request('trade.query', { search, limit: Number(opts.limit) });
+        if (!results?.length) {
+          console.log(`  ${c.dim('No trades found.')}`);
+          return;
+        }
+        console.log(`  ${c.info(`Found ${results.length} trades:`)}\n`);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const t of results) {
+          const badge = t.win ? c.green('WIN') : c.red('LOSS');
+          console.log(`  #${t.id} [${badge}] ${c.cyan(t.pair)} ${c.dim(t.fingerprint)} ${t.profit_pct.toFixed(2)}%`);
+        }
+      });
+    });
+}

package/src/cli/commands/rules.ts

@@ -0,0 +1,27 @@
+import { Command } from 'commander';
+import { withIpc } from '../ipc-helper.js';
+import { c, icons, header } from '../colors.js';
+
+export function rulesCommand(): Command {
+  return new Command('rules')
+    .description('Show learned trading rules')
+    .action(async () => {
+      console.log(header('Learned Rules', icons.rule));
+
+      await withIpc(async (client) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const rules: any = await client.request('rule.list', {});
+        if (!rules?.length) {
+          console.log(`  ${c.dim('No rules learned yet. Brain needs more trades.')}`);
+          return;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        for (const r of rules) {
+          const conf = Math.round(r.confidence * 100);
+          const wr = Math.round(r.win_rate * 100);
+          const confColor = conf > 70 ? c.green : conf > 50 ? c.orange : c.red;
+          console.log(`  ${confColor(`${conf}%`)} conf ${c.dim('|')} ${c.cyan(`${wr}%`)} WR ${c.dim('|')} n=${r.sample_count} ${c.dim('|')} ${c.value(r.pattern)}`);
+        }
+      });
+    });
+}

package/src/cli/commands/start.ts

@@ -0,0 +1,93 @@
+import { Command } from 'commander';
+import { spawn, type ChildProcess } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDataDir } from '../../utils/paths.js';
+import { c, icons } from '../colors.js';
+
+const MAX_RESTARTS = 5;
+const RESTART_WINDOW_MS = 5 * 60 * 1000;
+const BASE_BACKOFF_MS = 1000;
+
+function spawnDaemon(entryPoint: string, args: string[]): ChildProcess {
+  const child = spawn(process.execPath, [entryPoint, ...args], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  return child;
+}
+
+function startWatchdog(entryPoint: string, args: string[], pidPath: string): void {
+  const restartTimes: number[] = [];
+
+  function launch(): void {
+    const child = spawnDaemon(entryPoint, args);
+    console.log(`${icons.trade}  ${c.info('Trading Brain daemon starting')} ${c.dim(`(PID: ${child.pid})`)}`);
+
+    child.on('exit', (code) => {
+      if (code === 0 || code === null) return;
+
+      const now = Date.now();
+      restartTimes.push(now);
+      const recentRestarts = restartTimes.filter((t) => now - t < RESTART_WINDOW_MS);
+      restartTimes.length = 0;
+      restartTimes.push(...recentRestarts);
+
+      if (recentRestarts.length > MAX_RESTARTS) {
+        console.error(`${icons.error}  ${c.error(`Trading Brain crashed ${MAX_RESTARTS} times in 5 minutes — giving up.`)}`);
+        try { fs.unlinkSync(pidPath); } catch { /* ignore */ }
+        return;
+      }
+
+      const backoff = BASE_BACKOFF_MS * Math.pow(2, recentRestarts.length - 1);
+      console.log(`${icons.warn}  ${c.warn(`Trading Brain exited (code ${code}) — restarting in ${backoff / 1000}s...`)}`);
+      setTimeout(launch, backoff);
+    });
+  }
+
+  launch();
+
+  setTimeout(() => {
+    if (fs.existsSync(pidPath)) {
+      console.log(`${icons.ok}  ${c.success('Trading Brain daemon started successfully.')} ${c.dim('(watchdog active)')}`);
+    } else {
+      console.log(`${icons.clock}  ${c.warn('Trading Brain may still be starting.')} Check: ${c.cyan('trading status')}`);
+    }
+  }, 1000);
+}
+
+export function startCommand(): Command {
+  return new Command('start')
+    .description('Start the Trading Brain daemon')
+    .option('-f, --foreground', 'Run in foreground (no detach)')
+    .option('-c, --config <path>', 'Config file path')
+    .action((opts) => {
+      const pidPath = path.join(getDataDir(), 'trading-brain.pid');
+
+      if (fs.existsSync(pidPath)) {
+        const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+        try {
+          process.kill(pid, 0);
+          console.log(`${icons.trade}  Trading Brain daemon is ${c.green('already running')} ${c.dim(`(PID: ${pid})`)}`);
+          return;
+        } catch {
+          fs.unlinkSync(pidPath);
+        }
+      }
+
+      if (opts.foreground) {
+        import('../../trading-core.js').then(({ TradingCore }) => {
+          const core = new TradingCore();
+          core.start(opts.config);
+        });
+        return;
+      }
+
+      const args = ['daemon'];
+      if (opts.config) args.push('-c', opts.config);
+      const entryPoint = path.resolve(import.meta.dirname, '../../index.js');
+
+      startWatchdog(entryPoint, args, pidPath);
+    });
+}

package/src/cli/commands/status.ts

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDataDir } from '../../utils/paths.js';
+import { withIpc } from '../ipc-helper.js';
+import { c, icons, header, keyValue, divider } from '../colors.js';
+
+export function statusCommand(): Command {
+  return new Command('status')
+    .description('Show Trading Brain daemon status')
+    .action(async () => {
+      const pidPath = path.join(getDataDir(), 'trading-brain.pid');
+
+      if (!fs.existsSync(pidPath)) {
+        console.log(`${icons.trade}  Trading Brain Daemon: ${c.red.bold('NOT RUNNING')}`);
+        return;
+      }
+
+      const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+      let running = false;
+      try { process.kill(pid, 0); running = true; } catch { /* not running */ }
+
+      if (!running) {
+        console.log(`${icons.trade}  Trading Brain Daemon: ${c.red.bold('NOT RUNNING')} ${c.dim('(stale PID file)')}`);
+        return;
+      }
+
+      console.log(header('Trading Brain Status v1.0.0', icons.trade));
+      console.log(`  ${c.green(`${icons.dot} RUNNING`)} ${c.dim(`(PID ${pid})`)}`);
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      await withIpc(async (client) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const summary: any = await client.request('analytics.summary', {});
+
+        const dbPath = path.join(getDataDir(), 'trading-brain.db');
+        let dbSize = '?';
+        try {
+          const stat = fs.statSync(dbPath);
+          dbSize = `${(stat.size / 1024 / 1024).toFixed(1)} MB`;
+        } catch { /* ignore */ }
+
+        console.log(keyValue('Database', `${dbPath} (${dbSize})`));
+        console.log();
+
+        console.log(`  ${icons.trade}  ${c.green.bold('Trade Brain')}`);
+        console.log(`     ${c.label('Trades:')}     ${c.value(summary.trades?.total ?? 0)} total, ${c.cyan(`${summary.trades?.recentWinRate ?? 0}%`)} recent win-rate`);
+        console.log(`     ${c.label('Rules:')}      ${c.green(summary.rules?.total ?? 0)} learned`);
+        console.log();
+
+        console.log(`  ${icons.synapse}  ${c.cyan.bold('Synapse Network')}`);
+        console.log(`     ${c.label('Synapses:')}   ${c.value(summary.network?.synapses ?? 0)}`);
+        console.log(`     ${c.label('Avg weight:')} ${c.value(summary.network?.avgWeight ?? 0)}`);
+        console.log(`     ${c.label('Graph:')}      ${c.value(summary.network?.graphNodes ?? 0)} nodes, ${c.value(summary.network?.graphEdges ?? 0)} edges`);
+        console.log();
+
+        console.log(`  ${icons.insight}  ${c.orange.bold('Research')}`);
+        console.log(`     ${c.label('Insights:')}   ${c.value(summary.insights?.total ?? 0)}`);
+        console.log(`     ${c.label('Chains:')}     ${c.value(summary.chains?.total ?? 0)}`);
+
+        console.log(`\n${divider()}`);
+      });
+    });
+}

package/src/cli/commands/stop.ts

@@ -0,0 +1,33 @@
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDataDir } from '../../utils/paths.js';
+import { c, icons } from '../colors.js';
+
+export function stopCommand(): Command {
+  return new Command('stop')
+    .description('Stop the Trading Brain daemon')
+    .action(() => {
+      const pidPath = path.join(getDataDir(), 'trading-brain.pid');
+
+      if (!fs.existsSync(pidPath)) {
+        console.log(`${icons.trade}  ${c.dim('Trading Brain daemon is not running (no PID file found).')}`);
+        return;
+      }
+
+      const pid = parseInt(fs.readFileSync(pidPath, 'utf8').trim(), 10);
+
+      try {
+        process.kill(pid, 'SIGTERM');
+        console.log(`${icons.trade}  ${c.success('Trading Brain daemon stopped')} ${c.dim(`(PID: ${pid})`)}`);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ESRCH') {
+          console.log(`${icons.trade}  ${c.dim('Trading Brain was not running (stale PID file removed).')}`);
+        } else {
+          console.error(`${icons.error}  ${c.error(`Failed to stop daemon: ${err}`)}`);
+        }
+      }
+
+      try { fs.unlinkSync(pidPath); } catch { /* ignore */ }
+    });
+}

package/src/cli/ipc-helper.ts

@@ -0,0 +1,22 @@
+import { IpcClient } from '../ipc/client.js';
+import { getPipeName } from '../utils/paths.js';
+import { c, icons } from './colors.js';
+
+export async function withIpc<T>(fn: (client: IpcClient) => Promise<T>): Promise<T> {
+  const client = new IpcClient(getPipeName(), 5000);
+  try {
+    await client.connect();
+    return await fn(client);
+  } catch (err) {
+    if (err instanceof Error && err.message.includes('ENOENT')) {
+      console.error(`${icons.error}  ${c.error('Trading Brain daemon is not running.')} Start it with: ${c.cyan('trading start')}`);
+    } else if (err instanceof Error && err.message.includes('ECONNREFUSED')) {
+      console.error(`${icons.error}  ${c.error('Trading Brain daemon is not responding.')} Try: ${c.cyan('trading stop && trading start')}`);
+    } else {
+      console.error(`${icons.error}  ${c.error(err instanceof Error ? err.message : String(err))}`);
+    }
+    process.exit(1);
+  } finally {
+    client.disconnect();
+  }
+}

package/src/config.ts

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import type { TradingBrainConfig } from './types/config.types.js';
+import { getDataDir, getPipeName } from './utils/paths.js';
+
+const defaults: TradingBrainConfig = {
+  dataDir: getDataDir(),
+  dbPath: path.join(getDataDir(), 'trading-brain.db'),
+  ipc: {
+    pipeName: getPipeName(),
+    timeout: 5000,
+  },
+  api: {
+    port: 7779,
+    enabled: true,
+  },
+  mcpHttp: {
+    port: 7780,
+    enabled: true,
+  },
+  calibration: {
+    learningRate: 0.15,
+    weakenPenalty: 0.7,
+    decayHalfLifeDays: 14,
+    patternExtractionInterval: 50,
+    patternMinSamples: 10,
+    patternWilsonThreshold: 0.5,
+    wilsonZ: 1.96,
+    spreadingActivationDecay: 0.6,
+    spreadingActivationThreshold: 0.05,
+    minActivationsForWeight: 3,
+    minOutcomesForWeights: 5,
+  },
+  learning: {
+    intervalMs: 900_000, // 15 minutes
+    fingerprintSimilarityThreshold: 0.7,
+    chainMinLength: 3,
+    maxChains: 100,
+  },
+  research: {
+    intervalMs: 3_600_000, // 1 hour
+    initialDelayMs: 300_000, // 5 minutes
+    trendWindowDays: 7,
+    minTrades: 20,
+    maxInsights: 50,
+  },
+  log: {
+    level: 'info',
+    file: path.join(getDataDir(), 'trading-brain.log'),
+    maxSize: 10 * 1024 * 1024,
+    maxFiles: 3,
+  },
+};
+
+function applyEnvOverrides(config: TradingBrainConfig): void {
+  if (process.env['TRADING_BRAIN_DATA_DIR']) {
+    config.dataDir = process.env['TRADING_BRAIN_DATA_DIR'];
+    config.dbPath = path.join(config.dataDir, 'trading-brain.db');
+    config.log.file = path.join(config.dataDir, 'trading-brain.log');
+  }
+  if (process.env['TRADING_BRAIN_DB_PATH']) config.dbPath = process.env['TRADING_BRAIN_DB_PATH'];
+  if (process.env['TRADING_BRAIN_LOG_LEVEL']) config.log.level = process.env['TRADING_BRAIN_LOG_LEVEL'];
+  if (process.env['TRADING_BRAIN_PIPE_NAME']) config.ipc.pipeName = process.env['TRADING_BRAIN_PIPE_NAME'];
+  if (process.env['TRADING_BRAIN_API_PORT']) config.api.port = Number(process.env['TRADING_BRAIN_API_PORT']);
+  if (process.env['TRADING_BRAIN_API_ENABLED']) config.api.enabled = process.env['TRADING_BRAIN_API_ENABLED'] !== 'false';
+  if (process.env['TRADING_BRAIN_API_KEY']) config.api.apiKey = process.env['TRADING_BRAIN_API_KEY'];
+  if (process.env['TRADING_BRAIN_MCP_HTTP_PORT']) config.mcpHttp.port = Number(process.env['TRADING_BRAIN_MCP_HTTP_PORT']);
+  if (process.env['TRADING_BRAIN_MCP_HTTP_ENABLED']) config.mcpHttp.enabled = process.env['TRADING_BRAIN_MCP_HTTP_ENABLED'] !== 'false';
+}
+
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const key of Object.keys(source)) {
+    const val = source[key];
+    if (val && typeof val === 'object' && !Array.isArray(val) && target[key] && typeof target[key] === 'object') {
+      deepMerge(target[key] as Record<string, unknown>, val as Record<string, unknown>);
+    } else if (val !== undefined) {
+      target[key] = val;
+    }
+  }
+}
+
+export function loadConfig(configPath?: string): TradingBrainConfig {
+  const config = structuredClone(defaults);
+
+  if (configPath) {
+    const filePath = path.resolve(configPath);
+    if (fs.existsSync(filePath)) {
+      const raw = fs.readFileSync(filePath, 'utf-8');
+      const fileConfig = JSON.parse(raw) as Partial<TradingBrainConfig>;
+      deepMerge(config as unknown as Record<string, unknown>, fileConfig as unknown as Record<string, unknown>);
+    }
+  } else {
+    const defaultConfigPath = path.join(getDataDir(), 'config.json');
+    if (fs.existsSync(defaultConfigPath)) {
+      const raw = fs.readFileSync(defaultConfigPath, 'utf-8');
+      const fileConfig = JSON.parse(raw) as Partial<TradingBrainConfig>;
+      deepMerge(config as unknown as Record<string, unknown>, fileConfig as unknown as Record<string, unknown>);
+    }
+  }
+
+  applyEnvOverrides(config);
+  return config;
+}

package/src/db/connection.ts

@@ -0,0 +1,22 @@
+import Database from 'better-sqlite3';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLogger } from '../utils/logger.js';
+
+export function createConnection(dbPath: string): Database.Database {
+  const logger = getLogger();
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  logger.info(`Opening database at ${dbPath}`);
+  const db = new Database(dbPath);
+
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('cache_size = 10000');
+  db.pragma('foreign_keys = ON');
+
+  return db;
+}

package/src/db/migrations/001_core.ts

@@ -0,0 +1,43 @@
+import type Database from 'better-sqlite3';
+
+export function up(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS trades (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      fingerprint TEXT NOT NULL,
+      pair TEXT NOT NULL,
+      bot_type TEXT NOT NULL,
+      regime TEXT,
+      profit_pct REAL NOT NULL,
+      win INTEGER NOT NULL DEFAULT 0,
+      signals_json TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_trades_fingerprint ON trades(fingerprint);
+    CREATE INDEX IF NOT EXISTS idx_trades_pair ON trades(pair);
+    CREATE INDEX IF NOT EXISTS idx_trades_bot_type ON trades(bot_type);
+    CREATE INDEX IF NOT EXISTS idx_trades_created_at ON trades(created_at);
+    CREATE INDEX IF NOT EXISTS idx_trades_win ON trades(win);
+
+    CREATE TABLE IF NOT EXISTS signal_combos (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      fingerprint TEXT NOT NULL,
+      signals_json TEXT NOT NULL,
+      regime TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_combos_fingerprint ON signal_combos(fingerprint);
+
+    CREATE TABLE IF NOT EXISTS pairs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL UNIQUE,
+      total_trades INTEGER NOT NULL DEFAULT 0,
+      total_wins INTEGER NOT NULL DEFAULT 0,
+      total_profit REAL NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}

package/src/db/migrations/002_synapses.ts

@@ -0,0 +1,44 @@
+import type Database from 'better-sqlite3';
+
+export function up(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS synapses (
+      id TEXT PRIMARY KEY,
+      fingerprint TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.5,
+      wins INTEGER NOT NULL DEFAULT 0,
+      losses INTEGER NOT NULL DEFAULT 0,
+      activations INTEGER NOT NULL DEFAULT 0,
+      total_profit REAL NOT NULL DEFAULT 0,
+      last_activated TEXT NOT NULL DEFAULT (datetime('now')),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_synapses_fingerprint ON synapses(fingerprint);
+    CREATE INDEX IF NOT EXISTS idx_synapses_weight ON synapses(weight);
+
+    CREATE TABLE IF NOT EXISTS graph_nodes (
+      id TEXT PRIMARY KEY,
+      type TEXT NOT NULL,
+      label TEXT NOT NULL,
+      activation REAL NOT NULL DEFAULT 0,
+      total_activations INTEGER NOT NULL DEFAULT 0
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_graph_nodes_type ON graph_nodes(type);
+
+    CREATE TABLE IF NOT EXISTS graph_edges (
+      id TEXT PRIMARY KEY,
+      source TEXT NOT NULL,
+      target TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 0.5,
+      activations INTEGER NOT NULL DEFAULT 0,
+      last_activated TEXT NOT NULL DEFAULT (datetime('now')),
+      FOREIGN KEY (source) REFERENCES graph_nodes(id),
+      FOREIGN KEY (target) REFERENCES graph_nodes(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_graph_edges_source ON graph_edges(source);
+    CREATE INDEX IF NOT EXISTS idx_graph_edges_target ON graph_edges(target);
+  `);
+}

package/src/db/migrations/003_learning.ts

@@ -0,0 +1,49 @@
+import type Database from 'better-sqlite3';
+
+export function up(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS rules (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      pattern TEXT NOT NULL,
+      confidence REAL NOT NULL,
+      sample_count INTEGER NOT NULL,
+      win_rate REAL NOT NULL,
+      avg_profit REAL NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_rules_pattern ON rules(pattern);
+    CREATE INDEX IF NOT EXISTS idx_rules_confidence ON rules(confidence);
+
+    CREATE TABLE IF NOT EXISTS chains (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      pair TEXT NOT NULL,
+      type TEXT NOT NULL,
+      length INTEGER NOT NULL,
+      fingerprints_json TEXT NOT NULL,
+      total_profit REAL NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_chains_pair ON chains(pair);
+    CREATE INDEX IF NOT EXISTS idx_chains_type ON chains(type);
+
+    CREATE TABLE IF NOT EXISTS calibration (
+      id TEXT PRIMARY KEY DEFAULT 'main',
+      learning_rate REAL NOT NULL,
+      weaken_penalty REAL NOT NULL,
+      decay_half_life_days INTEGER NOT NULL,
+      pattern_extraction_interval INTEGER NOT NULL,
+      pattern_min_samples INTEGER NOT NULL,
+      pattern_wilson_threshold REAL NOT NULL,
+      wilson_z REAL NOT NULL,
+      spreading_activation_decay REAL NOT NULL,
+      spreading_activation_threshold REAL NOT NULL,
+      min_activations_for_weight INTEGER NOT NULL,
+      min_outcomes_for_weights INTEGER NOT NULL,
+      last_calibration TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}

package/src/db/migrations/004_research.ts

@@ -0,0 +1,30 @@
+import type Database from 'better-sqlite3';
+
+export function up(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS insights (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      severity TEXT NOT NULL DEFAULT 'medium',
+      title TEXT NOT NULL,
+      description TEXT NOT NULL,
+      data_json TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_insights_type ON insights(type);
+    CREATE INDEX IF NOT EXISTS idx_insights_severity ON insights(severity);
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS insights_fts USING fts5(
+      title, description, content=insights, content_rowid=id
+    );
+
+    CREATE TRIGGER IF NOT EXISTS insights_ai AFTER INSERT ON insights BEGIN
+      INSERT INTO insights_fts(rowid, title, description) VALUES (new.id, new.title, new.description);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS insights_ad AFTER DELETE ON insights BEGIN
+      INSERT INTO insights_fts(insights_fts, rowid, title, description) VALUES ('delete', old.id, old.title, old.description);
+    END;
+  `);
+}

package/src/db/migrations/index.ts

@@ -0,0 +1,60 @@
+import type Database from 'better-sqlite3';
+import { getLogger } from '../../utils/logger.js';
+import { up as coreSchema } from './001_core.js';
+import { up as synapsesSchema } from './002_synapses.js';
+import { up as learningSchema } from './003_learning.js';
+import { up as researchSchema } from './004_research.js';
+
+interface Migration {
+  version: number;
+  name: string;
+  up: (db: Database.Database) => void;
+}
+
+const migrations: Migration[] = [
+  { version: 1, name: '001_core', up: coreSchema },
+  { version: 2, name: '002_synapses', up: synapsesSchema },
+  { version: 3, name: '003_learning', up: learningSchema },
+  { version: 4, name: '004_research', up: researchSchema },
+];
+
+function ensureMigrationsTable(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS migrations (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+
+function getCurrentVersion(db: Database.Database): number {
+  const row = db.prepare('SELECT MAX(version) as version FROM migrations').get() as { version: number | null } | undefined;
+  return row?.version ?? 0;
+}
+
+export function runMigrations(db: Database.Database): void {
+  const logger = getLogger();
+  ensureMigrationsTable(db);
+
+  const currentVersion = getCurrentVersion(db);
+  const pending = migrations.filter(m => m.version > currentVersion);
+
+  if (pending.length === 0) {
+    logger.info('Database is up to date');
+    return;
+  }
+
+  logger.info(`Running ${pending.length} migration(s) from version ${currentVersion}`);
+
+  const runAll = db.transaction(() => {
+    for (const migration of pending) {
+      logger.info(`Applying migration ${migration.name}`);
+      migration.up(db);
+      db.prepare('INSERT INTO migrations (version, name) VALUES (?, ?)').run(migration.version, migration.name);
+    }
+  });
+
+  runAll();
+  logger.info(`Migrations complete. Now at version ${pending[pending.length - 1]!.version}`);
+}