Context Management

Compass learns and improves based on your feedback. You can update its understanding of your business context at any time.

Update business context

You can correct Compass if something in its answer is wrong or out of date.

To update context:

Ask your question in Slack.
When Compass replies, tell it what's wrong.
Compass updates its context so future answers are correct.

Example:

User: "Who are our top sales reps by win rate?"

Compass: Answers with a list of people including David Lee and Sarah Brown.

User: "David Lee and Sarah Brown are not sales reps — please remove them."

Compass: Updates the context.

How context works

Compass builds understanding of your business through:

Your corrections - When you tell Compass something is wrong, it remembers
Database metadata - Column descriptions and table documentation from your warehouse
Usage patterns - Learning which queries work well for your team

This context is organization-specific and continuously improves as you use Compass.

Context files

Context files are how Compass stores reusable business knowledge.

Each file captures one clarification that Compass should remember for future questions. In practice, that means a single file should usually cover one concept, one definition, or one repeated misunderstanding.

Context files can be stored globally for your organization or scoped to a specific channel. The format is the same in both cases.

What a typical context repo looks like

A typical context repository might look like this:

acme-corp-context/
  context/
    uncategorized/
      20260121_closed-won-stage-meaning.yaml
      20260203_customer-vs-workspace.yaml
    metrics/
      20260108_active-user-definition.yaml
      20260214_monthly-recurring-revenue.yaml
      20260226_net-revenue-retention.yaml
      20260304_pipeline-coverage.yaml
    sales/
      20260115_sales-rep-definition.yaml
      20260218_enterprise-vs-mid-market.yaml

  channels/
    sales-leadership/
      system_prompt.md
      context/
        forecasting/
          20260211_commit-vs-best-case.yaml
          20260301_forecast-call-rules.yaml

  contextstore_project.yaml
  system_prompt.md

In general:

Put organization-wide context files under context/{group}/{name}.yaml
Put channel-specific context files under channels/{channel}/context/{group}/{name}.yaml
Use groups to organize related concepts such as metrics, sales, or finance

Expected context file format

Compass expects each context file to be a YAML file with these fields:

topic
incorrect_understanding
correct_understanding
search_keywords

Here is an example:

topic: Monthly recurring revenue
incorrect_understanding: MRR includes one-time services and implementation fees.
correct_understanding: MRR only includes recurring subscription revenue and excludes one-time services, implementation fees, and pass-through charges.
search_keywords: mrr, monthly recurring revenue, recurring revenue, subscription revenue

What each field means

topic is the concept Compass should learn
incorrect_understanding describes the mistake or misconception Compass should avoid
correct_understanding gives the definition or clarification Compass should use instead
search_keywords gives related terms that help Compass find the file when similar questions come up

Working with context files directly

Most teams will not need to create these files by hand.

You will usually work with context files directly when:

You are migrating existing curated context from outside Compass
You want to bulk edit or reorganize many files in the repo
You want to review or refine generated files directly

Already have context elsewhere?

If you already have context in docs, spreadsheets, Notion pages, internal wikis, prompt files, or semantic YAMLs, you do not need to rewrite everything by hand.

The easiest way to migrate that material is to convert it into small, focused Compass context files. Each output file should cover one concept, one metric definition, or one repeated misunderstanding, and it should include the path where the file should live in the repo.

As a reminder:

Put organization-wide files under context/{group}/{name}.yaml
Put channel-specific files under channels/{channel}/context/{group}/{name}.yaml
Use one YAML file per clarification instead of combining many concepts into one file

Try a prompt like this:

Convert the following business context into Compass context files.

For each distinct concept, output:
1. A recommended file path
2. One YAML object with exactly these fields:
   - topic
   - incorrect_understanding
   - correct_understanding
   - search_keywords

Requirements:
- Keep each YAML object focused on a single concept or clarification
- Make topic short and descriptive
- Write incorrect_understanding as the specific misconception Compass should avoid
- Write correct_understanding as the canonical definition or rule Compass should follow
- Write search_keywords as a comma-separated list of related business terms, aliases, and phrases
- Place organization-wide files under context/{group}/{name}.yaml
- Place channel-specific files under channels/{channel}/context/{group}/{name}.yaml
- Choose a clear group name such as metrics, sales, finance, or product
- Choose a concise filename that would work well in a repo
- If the source material does not describe a misconception, use "N/A" for incorrect_understanding
- Format each result like this:

PATH: context/{group}/{name}.yaml
  ```yaml
  topic: ...
  incorrect_understanding: ...
  correct_understanding: ...
  search_keywords: ...
  ```

Source material:
[paste your existing context here]

Data Exploration Admins