Agent context - Lightdash

Agent context is shared background knowledge every AI agent in a project reads before answering. It lives in a single file, lightdash.project_context.yml, that sits next to lightdash.config.yml inside your dbt project directory. Notes you add here change future agent behavior without changing the semantic layer. The file is committed to your dbt repo and travels with the rest of your project metadata.

When to use it

Reach for agent context when the data model itself is fine but the agent is missing background knowledge — terminology, which table to prefer, or business rules that aren’t expressible as dbt metadata. If the fact would also help a new analyst joining the team, edit the semantic layer instead. Agents pick up new context on their next turn, so the loop between “notice a gap” and “agents behave better” is short.

How entries are added

There are two ways entries land in the file:

Through Issues writeback. When a project context fix runs, Lightdash proposes a single entry and opens a pull request against your dbt repo. The first time this happens the file is created (with a header explaining what it’s for). Subsequent fixes add or update entries in the same file.
By hand. You can edit lightdash.project_context.yml directly. Writeback uses the GitHub API to merge one entry at a time, preserving comments, quoting, and key order in the rest of the file, so manual edits and writeback coexist cleanly.

Either way, the same validation rules apply: invalid files surface schema-backed errors at ingest time. The full JSON Schema is published at lightdash-project-context-1.0.json — point your editor at it for autocomplete and validation.

File shape

lightdash.project_context.yml

version: 1
entries:
  - id: aov
    kind: definition
    content: "AOV means average order value — total revenue divided by number of orders in the period."
    terms: ["AOV", "average order value"]
    objects: []
  - id: active-customers-table
    kind: context
    content: "Use `fct_customer_activity` for active-customer questions; `dim_customers` is a slowly-changing dimension and double-counts churned customers."
    terms: ["active customers"]
    objects: ["fct_customer_activity", "dim_customers"]

The top-level document is { version, entries }. A bare array of entries is also accepted for backward compatibility, but new files are written in the canonical shape.

Top-level properties

Property	Type	Required	Description
`version`	number	yes	Schema version. Currently always `1`. Bumping this is the escape hatch for a future breaking change.
`entries`	array	yes	The list of context entries. May be empty.

Entry properties

Each item in entries is a single self-contained fact your agents should know.

Property	Type	Required	Description
`kind`	`"definition"` \| `"context"`	yes	How the entry is retrieved. Use `definition` for term-triggered facts (acronyms, vocabulary, “X means Y”). Use `context` for object-scoped guidance (routing rules, join rules, durable facts about a model).
`content`	string	yes	One self-contained sentence. This is what the agent reads. Keep it short and unambiguous.
`id`	string	no	Stable identifier used to update the entry later. Optional — Lightdash derives one from `terms[0]` (or `content`) at ingest if you omit it, suffixing on collision. Provide an explicit id if you want to hand-edit later without worrying about churn.
`terms`	string[]	no	Prompt-facing trigger words and phrases. Used to surface `definition` entries when a user’s question mentions one of them. Defaults to `[]`.
`objects`	string[]	no	Semantic objects (models, fields, joins) this entry concerns. Used to surface `context` entries when the agent is reasoning about one of these objects. Defaults to `[]`.

Unknown keys on an entry are preserved on round-trip, so a field a newer Lightdash version adds won’t be silently dropped if you edit the file by hand.

Issues — the board that proposes project context fixes and opens pull requests against this file.
Agent memory — the per-user counterpart: personal course corrections that never enter shared context.
Effective analytics with agents — knowledge documents and other ways to hand agents context upfront.

​When to use it

​How entries are added

​File shape

​Top-level properties

​Entry properties

​Related

When to use it

How entries are added

File shape

Top-level properties

Entry properties

Related