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

Database Schema	Tables	Raw SQL Dump (pg_dump)	Schemap Context	CLAUDE.md Rules	Token Reduction
Chinook	11	995 tokens	536 tokens	953 tokens	46.1%
Northwind	13	1,045 tokens	590 tokens	999 tokens	43.5%
Pagila (Postgres)	15	1,222 tokens	673 tokens	1,054 tokens	44.9%
SaaS E-Commerce	30	2,446 tokens	516 tokens	834 tokens	78.9%
Enterprise Scale	100	8,577 tokens	921 tokens	1,496 tokens	89.3%

---

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

Database Scale	Mean Latency	Median (p50)	Peak RAM	Workflow Impact
10 Tables	0.52 ms	0.52 ms	17.7 KB	Imperceptible ($< 1\text{ms}$)
50 Tables	2.11 ms	2.08 ms	47.6 KB	Imperceptible ($2\text{ms}$)
100 Tables	3.61 ms	3.60 ms	76.4 KB	Instant ($3.6\text{ms}$)
1,000 Tables	43.15 ms	43.09 ms	777.7 KB	Ultra-fast ($43\text{ms}$, $<1\text{MB}$ RAM)

🔬 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]

Loading

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

Command	Purpose	JSON Output Flag
schemap doctor	Run onboarding health check & schema diagnostic	schemap doctor --json
schemap context	Compile schemap_database_context.md context map	schemap context --format=json
schemap agents	Generate CLAUDE.md, AGENTS.md, and agent rules	N/A
schemap benchmark	Measure raw SQL vs. Schemap token savings & speed	schemap benchmark --json
schemap score	Calculate AI Readiness Score (0–100) & improvement roadmap	schemap score --json
schemap explain	Explain table architecture, columns, and relationships	schemap explain <table_name>
schemap join	Find foreign key join paths and generate SQL snippets	schemap join <table> <table>
schemap diff	Track structural schema changes (+, ~, -)	N/A
schemap export	Export schema as JSON or code for Agent Frameworks	schemap export --format=json
schemap hook	Install/manage Git pre-commit hooks for auto-compilation	schemap hook install
schemap watch	Watch directory for changes and auto-regenerate context	N/A

---

🗄️ Supported Databases

• PostgreSQL (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.

Edition	Price	Intended Audience & Capabilities
Free Community	$0	Solo developers, local evaluation, up to 100 tables, full CLI suite.
Pro Individual	$1.99/mo or $29 once	Freelancers & solo devs: unlimited tables, LLM enrichment (--enrich), 3 devices.
Team Plan	$19/seat/mo ($15 annual)	Engineering teams: CI/CD Quality Gates (schemap gate), PR bot, PII sanitization, seat pooling.
Enterprise	Custom	Large orgs: air-gapped on-prem verification, SAML/SSO, SOC 2 pack, SLA.

License Management

# Activate a license key
schemap activate <LICENSE_KEY>

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

# Deactivate device / logout
schemap logout

---

Built with ❤️ for the AI developer community.

Website • Documentation • Issues & Support