Getting Started

Pretensor introspects PostgreSQL, Snowflake, BigQuery, and MySQL, builds a Kuzu knowledge graph of tables, columns, foreign keys, inferred joins, and related metadata, and exposes that graph to AI tools through an MCP server. Agents query schema context and search without issuing raw SQL against your graph store.

Pretensor is in beta — 0.1.0 is the first stable (non-alpha) release. CLI flags, MCP tools, and graph schema can still change between minor versions — pin exact versions until 1.0.0.

Requirements

Python 3.11 or 3.12 (3.13 is not yet tested).
A reachable database for pretensor index. Postgres is the fastest local path.
An MCP-aware client (Claude Desktop, Cursor, Cline, Continue, Zed, Goose, …).

Install

pip install 'pretensor[postgres]'
# or, inside a uv-managed environment:
uv pip install 'pretensor[postgres]'

The base package ships no database driver — pick the extra for your engine (a bare pip install pretensor can serve an existing graph but cannot index). Extras combine with comma separation, e.g. pip install 'pretensor[snowflake,clustering]':

Extra	Adds	Use when
`pretensor[postgres]`	`psycopg2-binary`	indexing PostgreSQL
`pretensor[snowflake]`	`snowflake-sqlalchemy`	indexing a Snowflake warehouse
`pretensor[bigquery]`	`google-cloud-bigquery`	indexing BigQuery
`pretensor[mysql]`	`PyMySQL`	indexing MySQL
`pretensor[all-connectors]`	all four database drivers	you touch more than one engine
`pretensor[clustering]`	`leidenalg`	you want Leiden community detection (without it, Pretensor logs a warning and falls back to igraph Louvain)
`pretensor[embeddings]`	`onnxruntime`, `transformers`, `huggingface-hub`, `numpy`	you want the `semantic_search` tool, hybrid BM25+cosine reranking in `query`, and similar-table lookup in `context`

Full breakdown of what each extra does and when it pays off lives in Connecting your database → Optional extras.

Want to try it without installing? uvx --from pretensor pretensor --help runs the CLI in a temporary environment.

Recommended: `pretensor init`

pretensor init is the fastest path from a fresh install to a working MCP connection: one command connects your database, indexes it, optionally links a code repository for analyze, and registers pretensor with your MCP client.

pretensor init

It infers what it can from your environment (a DSN from DATABASE_URL, POSTGRES_URL, or assembled from PGHOST/PGUSER/PGDATABASE (plus optional PGPORT, PGPASSWORD); a candidate repository if the current directory is a git repo), shows a one-screen summary of what it found, and asks a single Yes/No/Customize question. Say yes and it indexes the database, links the repository, and asks per detected MCP client (Claude Code, Claude Desktop, Cursor) whether to register pretensor with it, backing up that client’s config before writing. Pass --yes to accept every default non-interactively, or flags like --dsn, --repo, and --client to skip individual prompts. See the pretensor init reference for the full flag set.

Don’t have a real database handy? pretensor init --sample (equivalently, pretensor quickstart below) sets up the bundled sample database instead.

One-command quickstart

If you have Docker and just want to see Pretensor working end-to-end without a real database, run:

pretensor quickstart

This boots a throwaway Postgres on localhost:55432 pre-loaded with the Pagila sample schema, indexes it into ./.pretensor/, and prints the mcpServers JSON snippet for Claude or Cursor. pretensor quickstart --down tears it down. Pass --no-docker to skip the compose step if you already have a Postgres instance available.

Or: index your own database

If you’d rather script it or skip the wizard, point Pretensor at a connection string directly. It introspects the schema, writes a Kuzu graph file at .pretensor/graphs/<name>.kuzu (override the state directory with --state-dir), and runs the deterministic intelligence pipeline (classification, clustering, join-path precomputation):

pretensor index postgresql://USER:PASSWORD@HOST:5432/DBNAME

See Database Support for Snowflake, BigQuery, and MySQL DSN formats, and for the build-from-parts flow pretensor init walks you through interactively.

Connect your agent

pretensor init handles this for you: it detects Claude Code (the claude CLI on your PATH), Claude Desktop, and Cursor, and, with your per-client confirmation (or an explicit --client), registers pretensor with each one, backing up the client’s config file first. Claude Code is registered by running claude mcp add; Claude Desktop and Cursor get their config file’s mcpServers block edited directly.

For a client init doesn’t auto-register (Cline, Continue, Zed, and others), print the MCP server config yourself and merge it in by hand:

pretensor serve --config-only

The output is a mcpServers JSON block. Merge the pretensor entry into your client’s MCP settings — the IDE starts the server automatically. If you prefer a long-running process, run pretensor serve --state-dir .pretensor directly.

Try a tool call

Ask the agent: “Use pretensor to find tables related to customers.” Under the hood the agent reaches for the query tool (BM25 search over schema metadata) and gets back a list of matching tables and columns. From there it can call context for column-level detail, traverse to find a join path between two tables, or cypher to run read-only Kuzu Cypher against the graph. See the CLI reference for the full surface.