WrenAI: A Governed Text-to-SQL Engine That Treats Context as Code

The Problem: Agents That Guess at SQL Without Business Context

A raw LLM agent can write SQL, but it does not know that 'revenue' means net of returns in your company, or that a particular join is the approved one. Schemas do not carry that meaning. WrenAI addresses this by adding a governed semantic layer, called MDL, plus an AI context layer that includes unstructured knowledge from docs, wikis, and chat threads. The intended user is a developer or data team building agents with tools like Claude Code or Cursor who wants those agents to produce not just plausible SQL but trustworthy dashboards. The README is explicit about who should skip it: anyone who only needs a one-off chart from a single CSV, or anyone happy with ungoverned guesses.

How It Works: MDL Planning, Dry-Plan Validation, and Structured Errors

The architecture rests on a few named mechanisms. Schema-aware retrieval pulls the relevant tables and columns for a question. MDL planning then uses the semantic model to map business terms to physical schema. A dry-plan validation step checks the generated SQL plan before execution, and structured errors with hints are returned when something fails. The README also mentions value profiling and an eval runner. The key design choice is that the semantic layer is not a prompt hack; it is versionable files. Definitions live in MDL, company-level instructions go in instructions.md, and a memory stores what worked. This is a concrete data flow: the agent queries the context layer, gets a validated plan, executes against the warehouse, and the trace of what happened stays in the agent's reasoning.

Getting It Running: CLI First, Agent Drives the Rest

Installation is via pip. The core package includes DuckDB, so you can start locally without a separate database. The README shows: pip install wrenai for the core, and pip install "wrenai[postgres,memory]" to add per-datasource and memory extras. The workflow is agent-driven: you install the CLI, install a one-file discovery stub for your AI client, and then let the agent handle the rest. Workflow guides are served on demand from inside the CLI, which means the instructions always match the installed version. That is a practical touch, because it avoids the common problem of stale documentation. If you are in mainland China and pip is slow, the README has a tip, though the text is truncated before the actual tip appears.

The Open-Core Boundary: What Is Free vs. What Costs Money

The repository license is marked NOASSERTION in the metadata, but the README shows an Apache-2.0 badge and states that the core, SDK, and skills are open-sourced under Apache-2.0. However, the README also says that row- and column-level security and access control are only in the Cloud or self-hosted tier. That is a significant limitation for any team with strict data governance requirements. The open-source version gives you dry-plan validation, row limits, and structured errors, but not fine-grained security. The README mentions an open-core page on the homepage, which presumably details the exact split. Before adopting, you need to check that page to see which features are gated. The distinction is not cosmetic: if your compliance regime requires column-level masking, the OSS version will not satisfy it.

Deployment and the Wasm Dashboard Path

One distinctive feature is the ability to deploy dashboards from an answer. The README describes turning any answer into a shareable, browser-side dashboard powered by wren-core-wasm, then shipping it to your own Vercel or Cloudflare Pages account with one command. This is a different model from a traditional BI tool where dashboards live inside the vendor's UI. Here the dashboard is generated and deployed to infrastructure you control. The actual command is not shown in the material, so the exact syntax is unverified. But the architecture is clear: the dashboard runs in the browser via WebAssembly, which means the heavy lifting happens client-side. That has implications for performance with very large result sets, though the README does not discuss limits.

A Real Alternative: A Bare Semantic Layer or a Raw LLM Agent

The README's own comparison table gives the alternatives. A raw LLM agent writes SQL but is often wrong and knows nothing about business definitions. A traditional BI tool can generate dashboards but requires manual work and does not work through your own agents. A bare semantic layer, like a pure MDL store, gives you definitions but not non-schema knowledge or agent-driven deployment. WrenAI sits in the middle: it adds an AI context layer on top of the semantic layer, and it adds deployment. The difference is not just feature count. A bare semantic layer is a passive store; WrenAI is an active engine that validates plans and returns structured errors. If you already have a semantic layer, you might only need the context layer piece, but WrenAI is not modular in that way. It is an integrated stack.

Maintenance and Upgrade Cost: What the Repo Layout Tells You

The repository has recently merged the Wren Engine into this repo under core/, and the previous engine repo is archived. That is a sign of consolidation, but it also means the project structure has changed. The legacy v1 chat-first product is preserved on a branch called legacy/v1 and is now called Wren GenBI Classic. This split creates a maintenance question: which version are you on, and which branch will receive fixes? The README states that workflow guides inside the CLI always match the installed version, which helps with documentation drift. The release cadence is active, with v0.14.0 pushed in September 2026 and v0.13.4 a week earlier. The project is not archived and the default branch is main. For an open-source project, the cost of upgrading depends on how much you customize the semantic layer. Since definitions live in Git, you can diff changes across versions, which is an advantage over a UI-driven tool.

The Verdict: Governed Context Is the Product, Not the SQL

WrenAI is not just another text-to-SQL wrapper. The core value proposition is that business context becomes a versionable, evidence-linked asset. The mechanisms, MDL planning, dry-plan validation, structured errors, and memory, are all in service of that. The limitations are real: no row-level security in the OSS version, a recent repo merge that may cause confusion, and a dependency on the agent ecosystem to drive the workflow. If you are a data engineer who wants to keep control of definitions and let agents do the heavy lifting, this is a serious candidate. If you need enterprise security features out of the box, you must budget for the Cloud or self-hosted tier. The project is worth a proof of concept with your own warehouse, but only after you confirm your data source is in the 22+ list and you can live with the open-core boundary.

Editorial conclusion

Adopt WrenAI if you run AI agents against a warehouse and need business definitions, approved joins, and memory to live outside prompts, in versionable files. Skip it if you only need a quick chart from a CSV or you are comfortable letting an agent guess at SQL without guardrails. Before committing, verify that your required data source is in the 22+ list and that the row-level security gap is acceptable, since access control is only in the Cloud or self-hosted tier. Then test the CLI's dry-plan validation with your own schema to see if the structured errors match your team's workflow.

Official sources

1. Canner/WrenAI on GitHub
2. Issues
3. Project website
4. README
5. Releases