Product · Knowledge base

Knowledge base

The knowledge base is where your team writes down what is true about your data and cannot be read from the tables themselves: which report to trust, what a term means here, and which rules every answer must follow. The AI reads it before it answers, so everyone gets the same numbers.

Without it, the AI relearns your warehouse every time someone asks a question, and two people asking the same thing can get two different answers. With it, the definition of "active customer" is the same in Claude, in ChatGPT, in SignalPilot chat, and in every model the AI builds.

The Knowledge base page. Filters on the left, entries in the middle, the open entry on the right.

What to write down

Write down the things a new analyst would need to be told in their first week. The AI can already see table and column names. It cannot see:

• Which table is the right one. "Use fct_orders for revenue, not stg_orders."
• What a business term means. "An active customer has placed an order in the last 90 days."
• Rules every answer must follow. "Revenue is always reported net of refunds."
• Known traps. "fct_orders has one row per line item, so count distinct order ids."
• Fixes for errors the team has already hit. Include the error text people actually see.

Keep out anything the tables already say, anything that will be stale next month, and anything you would not want repeated on every single question.

A good entry is a fact with a reason. "fct_orders is one row per line item, so use count(distinct order_id)" helps more than "be careful with fct_orders". Short entries about one thing each work better than one long entry about six things.

Categories

Every entry has a category. It tells the AI what kind of thing it is reading.

Category	Plain meaning
Context	The short brief the AI reads on every task. Who you are, what the data is about, what matters most. Keep it short and stable.
Agent decisions	Why things are built the way they are: which tables join to which, what gets filtered out, and the reasoning behind it.
Rules	Business rules and house style. How a metric is defined, and how new models should be written here.
Troubleshooting	Known errors and their fixes, plus the quirks of a particular database.

The difference that matters most is Context versus everything else. Context goes to the AI on every task, whether or not it is relevant, so it should be a few paragraphs at most. The other three categories are looked up only when a question needs them, so you can have as many of those as you like.

Scopes

Every entry also has a scope. It says where the entry applies.

Scope	Applies to	Categories allowed
Org	Everyone and everything in your workspace	Context, Agent decisions, Rules
Project	One dbt project	Context, Agent decisions, Rules, Troubleshooting
Connection	One database connection	Context, Troubleshooting

Pick the narrowest scope that is true. A rule that only holds for one connection belongs on that connection, not on the org. That way it never confuses a question about a different database.

Add and edit entries

Open Knowledge base from the sidebar.

1. Choose New entry, or pick an entry from the list and press Edit (⌘E on Mac, Ctrl-E on Windows).
2. Give it a title, a scope, and a category. See the note on titles below.
3. Write the body. You can link to another entry by wrapping its title in double square brackets, like [[fct-orders-grain]]. The footer of an entry lists every other entry that links to it, which is the quickest way to find the cluster of notes around one model.
4. Save. The entry is live straight away. If you navigate away with unsaved edits, the page asks first.

The left rail filters by scope and category, with live counts. The middle column lists entries. Sort cycles through most viewed, most recent, alphabetical, and least viewed. The right pane shows the selected entry.

Two more things you can do from an open entry:

• History shows every earlier version with its author and lets you go back to one. The Free and Pro plans keep 5 versions, Team keeps 25, and Enterprise keeps 50.
• Archive hides the entry from the AI but keeps it readable under the archived filter. Nothing is lost.

note

Titles are slugs. A title must be lowercase letters, numbers, and hyphens, up to 120 characters: fct-orders-grain, not fct_orders grain or Fct Orders Grain. Anything else is rejected with the message "title must be lowercase alphanumeric with hyphens, no leading/trailing hyphens". Links written as [[wikilinks]] match on these slugs.

How the AI uses entries

Before it answers, the AI reads the Context entries for your org, the project, and the connection it is working with. Then it searches the rest of the knowledge base for entries that match the question and reads the ones that look relevant. Titles carry the most weight in that search, so name an entry after the thing someone would look for.

The AI can also suggest new entries. When it learns something during a task, it can propose an entry, which appears under Pending with a count badge. Nothing the AI proposes is used until a person approves it.

Review a pending entry the way you would review a change from a colleague. Something that was true in one session is not automatically a rule.

• Approve makes it live, and the AI starts using it straight away.
• Evaluate change runs your eval set with this entry added, so you can see whether it helps or hurts accuracy before you approve it.

Retrieval heatmap

The heatmap shows which entries the AI actually read, and how often. Use it both ways. An entry that is read a lot but never helps is adding noise to every question. An entry that is never read is either badly titled or answers a question nobody asks. Retrieval counts are kept for 90 days.

Limits

Knowledge storage is capped per workspace by plan: 50 MB on Free, 250 MB on Pro, 1 GB on Team, and 5 GB on Enterprise. Retrieval counts are pruned after 90 days. Entries and their history are never pruned.

For engineers

Tools. Agents read through get_knowledge, search_knowledge, and read_knowledge, and write back through propose_knowledge. Proposals land as pending until a human approves them. The scope_ref for a project scope is the project id and for a connection scope it is the connection name. Org scope has none.

Retrieval. search_knowledge runs three arms and fuses them with reciprocal rank fusion: Postgres full-text search, a lexical keyword match, and an in-process BM25 index over word and character 4-gram tokens. There are no embeddings and no external model calls. The arms degrade independently, so if one is unavailable the search still returns. Both the full-text and BM25 arms weight the title heavily, which is why titles matter more than prose and why short, single-concept entries rank better than long ones.

Versioning. Every save writes a new version with its author. History and revert work from those versions, and the number kept is set by plan (5 on Free and Pro, 25 on Team, 50 on Enterprise). Archive is a tombstone: the entry stays in the database and stays readable under the archived filter, but it is excluded from every retrieval arm. [[wikilinks]] and backlinks resolve against slugs, so renaming an entry breaks inbound links until they are updated.