Stop AI Agents From Guessing Your Database.

The Deterministic AI Database Context Compiler for Claude Code, Cursor, Windsurf, Codex, and Copilot.

⚡ The Problem: Why AI Coding Agents Fail at SQL

Modern AI coding agents (Claude Code, Cursor, GitHub Copilot, Codex) struggle with production databases:

• Raw pg_dump SQL dumps waste 10,000+ tokens of precious context window.
• Cluttered DDL dumps introduce noisy system metadata and lock definitions.
• LLMs hallucinate non-existent foreign keys (e.g. guessing orders.customer_id when the column is orders.user_id), creating broken multi-table JOINs.

Schemap solves this. Schemap is a high-speed CLI compiler that introspects your database, computes an AI Readiness Score, and outputs clean, token-optimized context maps (schemap_database_context.md, CLAUDE.md, AGENTS.md).

📊 Benchmarks: Empirical Framework, Context Efficiency & Compiler Speed

Tier 1 — Database Reasoning Outcome Benchmark (Empirical Protocol)

Hero Question: Does Schemap make AI coding agents faster, cheaper, and less error-prone when working with real databases?

To eliminate marketing hype and fabricated numbers, Schemap provides a rigorous, automated Dual-Gate Evaluation Framework (benchmarks/tier1_outcome_benchmark.py) designed to test real LLM reasoning outcomes against seeded databases:

• Controlled Protocol: Same Model · Same Database · Same Task across 3 conditions:
  1. Mode A: Blind (Zero Context) — Baseline query without schema.
  2. Mode B: Raw DDL (pg_dump) — Full CREATE TABLE definitions and constraints.
  3. Mode C: Schemap Compiled Context — Deterministic relationship graph, explicit join paths, and AI readiness rules.
• Dual-Gate Scientific Verification Standard:
  1. Gate 1 (Syntax & Execution): Query executes cleanly in SQLite without syntax or schema errors.
  2. Gate 2 (Semantic Dataset Result Match): Query output rows are compared directly against ground-truth datasets on seeded production schemas.
• 10 Real-World Engineering Tasks: Spanning 4 difficulty tiers (Easy, Medium, Hard, Very Hard) across Chinook, Northwind, and Pagila.
• Zero Fake Results Policy: Schemap never substitutes synthetic or simulated passes. When you run the benchmark with your own API key, it generates live empirical results.

# Run the live benchmark across 150 evaluations (10 tasks × 5 runs × 3 modes)
uv run python benchmarks/tier1_outcome_benchmark.py --runs 5

See current execution status and task details in TIER1_OUTCOME_REPORT.md.

⚡ Tier 2 — Context Efficiency across Database Scales

⚡ Tier 3 — Reliability & Scalability (Schemap Gets Out of the Way)

🔬 Reproduce All Benchmarks: Run uv run python benchmarks/tier1_outcome_benchmark.py --runs 5 or inspect full test methodologies in BENCHMARKS.md.

🚀 30-Second Quick Start

1. Run Instantly (No Installation Required)

Using uvx:

uvx schemap-tool doctor --db "sqlite:///app.db"

Or install globally via pipx (recommended) or uv / pip:

pipx install schemap-tool

Alternative installs:

• uv tool install schemap-tool
• pip install schemap-tool

To update or cleanly remove Schemap anytime:

schemap update
schemap uninstall --purge

2. Run Database Health Diagnostic (schemap doctor)

Audit your database schema for AI compatibility, missing foreign keys, and ambiguous naming:

schemap doctor

==================================================
 Schemap AI Database Health Check
==================================================
  Connection:             Connected (39 tables)
  Relationships Analyzed: 26
--------------------------------------------------
  AI Readiness Score:
  [################----] 82/100

  Top Diagnostic Insights:
  - [High] 4 tables lack explicit foreign key constraints (-10 pts)
  - [Med]  12 column names contain ambiguous abbreviations (-8 pts)
--------------------------------------------------
 Recommendation: Run `schemap context` to compile AI-ready database context.
==================================================

3. Compile AI Database Context (schemap context)

Compile a clean, token-compressed markdown context file (schemap_database_context.md):

schemap context

4. Generate Agent Rule Files (schemap agents)

Generate native instruction files for Claude Code (CLAUDE.md), Cursor (.cursorrules), and AI agents (AGENTS.md):

schemap agents

5. Benchmark Token Savings (schemap benchmark)

Measure real-time token compression and compilation speed on your own schema:

schemap benchmark

🛠️ Architecture & Workflow

flowchart LR
    A[(PostgreSQL / MySQL / SQLite / Turso / Oracle)] -->|schemap extract| B(Schemap Engine)
    B -->|Score & Graph| C{Deterministic Compiler}
    C -->|CLAUDE.md| D[Claude Code]
    C -->|AGENTS.md / .cursorrules| E[Cursor & Windsurf]
    C -->|schemap_database_context.md| F[Copilot / Codex / Prompts]

1. Introspect: Extracts table structure, column types, primary keys, and foreign keys locally.
2. Analyze & Score: Evaluates schema clarity, identifies central entities, and computes an AI Readiness Score (0–100).
3. Compile: Generates structured, token-efficient markdown context and native rule files for your coding assistants.

✨ Key Features

• 🔒 100% Local-First & Air-Gapped: Your database credentials, data rows, and schema metadata never leave your machine.
• ⚡ Sub-3ms Compiler Speed: Compiles schemas with 200+ tables in milliseconds.
• 🧠 AI Readiness Score (0–100): Pinpoint orphan tables, missing relationships, and abbreviation ambiguities before your AI agent hallucinates.
• 🤖 Multi-Agent Workspace Sync: Instantly creates CLAUDE.md, AGENTS.md, and .cursorrules with one command.
• 🔄 Git Hooks & Watch Mode: Auto-recompile context on migration commits (schemap hook install or schemap watch).
• 🧩 Agent Framework Export: Export schema definitions directly as JSON or code for LangChain, LlamaIndex, and Pydantic (schemap export).

💻 Complete CLI Reference

🗄️ Supported Databases & Platforms

• PostgreSQL & Supabase & Neon (postgresql://user:password@localhost:5432/my_db)
• MySQL (mysql://user:password@localhost:3306/my_db)
• SQLite (sqlite:///path/to/db.sqlite3)
• Turso / Remote libSQL (libsql://[your-db].turso.io?authToken=[token])
• Oracle (oracle://user:password@localhost:1521/my_db)

⚙️ Configuration (schemap.yaml)

Initialize a lightweight configuration file in your project root:

schemap init

Example schemap.yaml:

database:
  connection_url: "sqlite:///app.db"

output:
  file_path: "./schemap_database_context.md"

domain:
  mappings:
    cust: "Customer"
    tx: "Transaction"
    inv: "Invoice"
    acct: "Account"

For full boilerplate options (table exclusions, descriptions, custom profiles):

schemap init --full

🤖 CI/CD Integration & GitHub Actions

Keep your AI context maps up to date automatically on every migration commit:

name: Schemap CI/CD AI Database Intelligence & Gate

on:
  pull_request:
    paths:
      - 'migrations/**'
      - 'alembic/versions/**'
      - 'prisma/schema.prisma'
      - 'schema.sql'
  push:
    branches: [main]
    paths:
      - 'migrations/**'
      - 'alembic/versions/**'
      - 'prisma/schema.prisma'

jobs:
  schemap-gate-and-sync:
    name: AI Quality Gate & Agent Rules Sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
        with:
          version: "latest"
      - name: 1. Evaluate AI Quality Gate (Blocks PRs on Low AI Readiness)
        env:
          SCHEMAP_LICENSE_KEY: ${{ secrets.SCHEMAP_LICENSE_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: uvx schemap-tool gate --min-score 80 --fail-on-breaking
      - name: 2. Compile Sanitized AI Context & Agent Rules
        env:
          SCHEMAP_LICENSE_KEY: ${{ secrets.SCHEMAP_LICENSE_KEY }}
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: |
          uvx schemap-tool context --sanitize
          uvx schemap-tool agents --targets claude,cursor,codex --sanitize
      - name: 3. Commit and Push Synchronized Agent Rules
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: |
          git config --global user.name 'github-actions[bot]'
          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
          git add schemap_database_context.md CLAUDE.md AGENTS.md .cursor/rules/*.mdc
          git diff --quiet && git diff --staged --quiet || (git commit -m "chore(ai): auto-update deterministic database context [skip ci]" && git push)

🔑 Dual-Engine Editions & Licensing

Schemap provides a Dual-Engine Licensing Model: an ultra-accessible developer edition for solo engineers and an enterprise intelligence layer for engineering teams.

License Management

# Activate a license key
schemap activate <LICENSE_KEY>

# Verify active license status & device seats
schemap status --verify

# Deactivate device / logout
schemap logout