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 or native Lightdash YAML project — in the Project directory path you set on the connection, which isn’t always your repository root. Notes you add here change future agent behavior without changing the semantic layer. The file is committed to your project repository and travels with the rest of your project metadata.

When agents load it

Two things have to be true, beyond the file existing in your repository:

Review AI agent turns is on. Lightdash only reads lightdash.project_context.yml into a project when the organization setting Review AI agent turns (Settings → Ask AI → General) is enabled. Turn it on, then click Refresh dbt (Refresh models for native projects), or run lightdash refresh, so Lightdash compiles the project and picks up the file. lightdash deploy uploads models compiled on your machine and doesn’t read the file.
The project connects to a Git repository. Agents only load project context on projects connected to a repository (GitHub, GitLab, Bitbucket or Azure DevOps). A project with no repository connection — including a preview created with lightdash preview, lightdash start-preview, or lightdash deploy with no repository connection — has no project context at all, regardless of the setting above: nothing is ingested and agents load nothing.

Lightdash reads the file from the branch set on the project connection, so commit and push an edit before you refresh. A preview built from a connected branch reads lightdash.project_context.yml from that branch at compile time, the same as any other project file. A CLI-created preview with no repository connection doesn’t — there’s no branch to read it from.

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 semantic definitions. 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. Agent context replaces agent memories, which are deprecated. Agents no longer learn new memories or read existing ones. Settings → Ask AI → Memories still lists memories saved earlier so you can review them; add anything worth keeping here instead.

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 project repository. 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: an invalid file fails the refresh, and the error marks the part of the file that broke the schema. The two most common causes are a { entries } document with no version and plain strings in the objects of a version: 2 file, both covered in File shape. The full JSON Schema is published at lightdash-project-context-2.0.json — point your editor at it for autocomplete and validation.

File shape

lightdash.project_context.yml

version: 2
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:
      - type: explore
        name: fct_customer_activity
      - type: field
        explore: dim_customers
        fieldId: dim_customers_customer_id

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. If you use the document shape, version: 2 is required: leaving it out fails validation at the document root.

Top-level properties

Property	Type	Required	Description
`version`	number	yes	Schema version. Currently `2`. Files with `version: 1`, and bare arrays, still load, but any `objects` list that isn’t made of typed references is dropped.
`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`	object[]	no	Semantic objects this entry concerns, as typed references: `{ type: explore, name }` for an explore, or `{ type: field, explore, fieldId }` for a field. Plain strings are rejected in `version: 2` files. 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.
Effective analytics with agents — knowledge documents and other ways to hand agents context upfront.

​When agents load it

​When to use it

​How entries are added

​File shape

​Top-level properties

​Entry properties

​Related