Skip to main content
The Pro Workflow database provides persistent storage for learnings, session analytics, and full-text search capabilities. Built on SQLite with FTS5 (Full-Text Search) for fast BM25-ranked queries.

​
Architecture

import { initializeDatabase, createStore } from 'pro-workflow';

const db = initializeDatabase(); // Creates ~/.pro-workflow/data.db
const store = createStore();     // Returns high-level API

​
Database Location

Default path: ~/.pro-workflow/data.db
The database directory is created automatically on first use. No manual setup required.

​
Core Features

Learnings Storage

Persistent memory for corrections, patterns, and rules. Searchable via full-text search with BM25 ranking.

Session Tracking

Track edit counts, correction counts, and prompts per session. Analyze productivity patterns.

FTS5 Search

Fast prefix matching, phrase search, and BM25 relevance scoring. Sub-millisecond queries.

Project Scoping

Filter learnings by project. Share global learnings across projects or keep them isolated.

​
Schema

​
Tables

TablePurpose
learningsCore learning storage with category, rule, mistake, correction
learnings_ftsFTS5 virtual table for full-text search
sessionsSession metadata with timing and activity counts

​
Indexes

  • idx_learnings_category — Fast category filtering
  • idx_learnings_project — Fast project scoping
  • idx_learnings_created_at — Chronological queries
  • idx_sessions_project — Session-by-project lookups
  • idx_sessions_started_at — Recent sessions

​
Database Configuration

​
dbPath
string
default:"~/.pro-workflow/data.db"
Custom database location. Must be an absolute path.
import { createStore } from 'pro-workflow';

const store = createStore('/custom/path/to/data.db');

​
SQLite Pragmas

The database is initialized with optimized settings: 
PRAGMA journal_mode = WAL;  -- Write-Ahead Logging for concurrency
PRAGMA foreign_keys = ON;   -- Enforce referential integrity
WAL mode allows multiple readers and one writer simultaneously. Perfect for background hooks and parallel agents.

​
Triggers

Automatic FTS synchronization via triggers: 
-- After insert: add to FTS index
CREATE TRIGGER learnings_ai AFTER INSERT ON learnings BEGIN
  INSERT INTO learnings_fts(rowid, category, rule, mistake, correction)
  VALUES (new.id, new.category, new.rule, new.mistake, new.correction);
END;

-- After update: re-index
CREATE TRIGGER learnings_au AFTER UPDATE ON learnings BEGIN
  INSERT INTO learnings_fts(learnings_fts, rowid, category, rule, mistake, correction)
  VALUES ('delete', old.id, old.category, old.rule, old.mistake, old.correction);
  INSERT INTO learnings_fts(rowid, category, rule, mistake, correction)
  VALUES (new.id, new.category, new.rule, new.mistake, new.correction);
END;

-- After delete: remove from FTS
CREATE TRIGGER learnings_ad AFTER DELETE ON learnings BEGIN
  INSERT INTO learnings_fts(learnings_fts, rowid, category, rule, mistake, correction)
  VALUES ('delete', old.id, old.category, old.rule, old.mistake, old.correction);
END;

​
API Functions

​
Initialization

​
initializeDatabase
(dbPath?: string) => Database
Initialize the database with schema and indexes. Idempotent — safe to call multiple times.
​
getDefaultDbPath
() => string
Returns ~/.pro-workflow/data.db. Use for custom configurations.
​
ensureDbDir
() => void
Create ~/.pro-workflow/ if it doesn’t exist. Called automatically by initializeDatabase.

​
Store API

​
createStore
(dbPath?: string) => Store
Create a high-level store instance with methods for learnings and sessions.

​
Example Usage

import { createStore } from 'pro-workflow';

const store = createStore();

// Add a learning
const learning = store.addLearning({
  project: 'my-app',
  category: 'Testing',
  rule: 'Run tests after editing server code',
  mistake: 'Pushed broken API endpoint',
  correction: 'Added npm test to pre-push hook'
});

console.log(`Saved as learning #${learning.id}`);

// Close when done
store.close();

​
Next Steps

Learnings API

CRUD operations for learnings storage

Sessions API

Track and query session analytics

Search API

Full-text search with BM25 ranking

Plugin Config

Install the database as a Claude Code plugin

Build docs developers (and LLMs) love

Get started for freeTalk to us