Building a Data Stack Live with AI AgentsLivestream August 18

START FREE
BACK TO VIDEOS
StreamAI, ML and LLMsMotherDuck Features

Introducing Guides: Warehouse-Native Context for AI Agents

2026/08/13

TL;DR: Guides are versioned markdown docs stored in your MotherDuck warehouse that give AI agents business context automatically. The agent reads the guide before writing SQL, and context matters more than model size for accuracy.

Why agents need context in the warehouse

Point an AI agent at a database and it'll guess what your business terms mean. Garrett and Bev walk through how MotherDuck handles this: Guides are versioned markdown documents that live inside your warehouse as database objects, queryable in SQL. Think of them as a README for a new hire, except the agent actually reads them. Every natural language query that comes through the MotherDuck MCP server checks the guide before writing SQL, so you don't have to remember to point your agent at a YAML file or a skill.

Context beats model size

On the DABStep benchmark — hundreds of hard multi-step analytics questions — providing context about the data pushed correctness to nearly 100%, using a cheap Gemini Flash-class model rather than a frontier one. A smaller model with good context outperforms a bigger model without it. Bev also reports roughly 90th-percentile consistency when swapping between different agents that share the same guide.

How guides are organized

Topics work like folders. Organization-level guides hold shared definitions (MRR, churn, etc.), user-level guides hold personal preferences and experiments, and topics can nest. Reserved topics for flights/ and dives/ keep pipeline context separate from query context. Agents can write back into guides too — Bev has hers log every inference and assumption to a personal guide section so a human can review them and promote the good ones to the org level.

Manage guides as code

Guides are plain markdown, so git and CI work out of the box. Open a PR and a user-scoped copy of the guide deploys for testing; merge, and a GitHub Action pushes the org-level guide with the md_update_guide SQL function. The MCP workflows docs cover how agents connect. The demo walks through the full loop: a revenue question answered wrong without a guide, a guide defining cost-of-goods-sold rules, and the same question answered correctly after.

FAQS

Guides are markdown documents stored in your MotherDuck data warehouse as database objects. They hold business context — metric definitions, table quirks, query patterns, internal terminology — and they're versioned and queryable with SQL. When an agent queries MotherDuck through the MCP server, it checks the relevant guide before writing SQL, so the context lives with the data rather than in external files.

A semantic layer like dbt's defines strict, deterministic metrics, and it's the right tool for that job. Guides capture what YAML can't: business term definitions, data anomalies, ambiguities, and quirks like a mid-year payment processor change. The two work together — you can include your dbt metric definitions in a guide and add the messy context around them in plain markdown.

A guide looks similar to a skill — both are markdown that agents parse well — but guides live in the data warehouse next to the data. They're versioned, shareable across an organization, and loaded automatically by the MotherDuck MCP server on every query, so nobody has to remember to reference a file. They also stay portable if you switch agents. Any MCP-enabled client gets the same context.

No. The MCP server is the easiest path, but guides are managed through SQL functions like md_create_guide and md_update_guide, so any client that can connect to MotherDuck — including the DuckDB CLI — can create, update, and read them. The MCP server adds automatic guide consultation on every natural language query.

Yes. Guides are plain markdown, so you can keep the canonical copy in a GitHub repo and wire up a pipeline: a PR deploys a user-scoped test copy, and merging pushes the change to the organization-level guide via md_update_guide. MotherDuck's Blueprints repo on GitHub has a working example with the GitHub Actions configuration.

Related Videos

View all