What Orion knows about your business
The context sources Orion injects into every answer — memory, the knowledge graph, metric contracts, session history, live query context, and dataset date-awareness.
When to use it: Whenever you want Orion to answer the way your team thinks about the business — and whenever you want to teach it a definition, correction, or preference that should stick.
Where to find it: It runs automatically inside every Orion chat. You shape it from the chat itself (corrections) and from Forge (knowledge graph and metric contracts).
Who can use it: Tracer, Weaver, and Luminary roles.
Orion is not answering from general knowledge. Before it responds, it builds a system prompt that pulls together what it has learned about your workspace, the governed definitions in your semantic layer, the conversation you are in, and — if you opened it from a chart — the exact result on your screen. This page explains each source so you can predict why Orion answers the way it does, and so you can teach it deliberately.
Overview
Every time you ask Orion a question, it composes a fresh system prompt out of several context blocks. Most of these blocks are read from your workspace on demand and cached briefly so repeated questions stay fast. The blocks are:
- Learned memory — durable facts Orion has stored about your business across sessions.
- Structured workspace memory — a curated record of metric definitions, data gotchas, past corrections, and preferences.
- Business knowledge graph — relationships between the entities in your model, surfaced for the specific question you asked.
- Metric contracts — the authoritative, governed definitions of your metrics.
- Session history — the recent turns of the current conversation, trimmed so it stays focused.
- Live query context — the actual result you are looking at, injected when you open Orion from a Discover result.
- Project context — a description of the project you are working in.
On top of these, Orion always carries date-awareness rules so it anchors relative time periods to your dataset instead of the real calendar. Each block is built defensively: if any single source fails to load, Orion drops that block and still answers rather than erroring.
When to use it
You do not turn context-awareness on or off — it is always active. The reason to understand it is to control it:
- When Orion uses the wrong definition for a metric, you want to correct it so the fix sticks.
- When you have a recurring rule (for example, "always exclude test orders"), you want Orion to remember it.
- When Orion's answer ignores something on your screen, you want to know whether it had the live query context.
- When a number looks like it is for the wrong time period, you want to understand the date-anchoring behavior before assuming it is a bug.
Concepts
| Term | What it means |
|---|---|
| Learned memory | Free-form facts stored in the orion_memory table — typed entries like business_context, metric_definition, correction, preference, and schema_insight. Orion loads up to 50 of these per session, ordered by confidence then recency. |
| Workspace memory | A single structured record per workspace holding key metric definitions, data gotchas, past corrections, and user preferences (default grain, currency, default date range). |
| Knowledge graph | The map of entities and relationships in your semantic model. Orion queries it for context relevant to the question you just asked. |
| Metric contract | The authoritative definition of a metric — what it counts, how it is computed, and how it should be labeled. Contracts are injected as "authoritative definitions" so Orion does not redefine your metrics on the fly. |
| Session | The current conversation thread. Its recent turns are replayed to Orion so follow-up questions have continuity. |
| Live query context | A snapshot of the Discover result you opened Orion from — domain, report, selected metrics and attributes, grain, row count, columns, and the first few rows of data. |
| Date-awareness | The rule set that anchors relative time windows ("last 7 days", "this month") to the dataset's most recent date instead of today's calendar date, and labels periods honestly. |
Getting started
There is no setup to enable context-awareness — it is part of every Orion session. To make the most of it:
- To teach Orion a definition, correction, or preference, just say it in the chat. Orion stores important learnings with its
store_memorytool so they persist into future sessions. - To give it governed definitions, define metric contracts and build out your knowledge graph in Forge. See Metric contracts and the Knowledge graph.
- To give it live result context, open Orion from a Discover result rather than from a blank chat — the result you are viewing is passed in automatically.
Step-by-step
Open Orion in context
Open Orion from inside a Discover result so the current query context travels with your question. When you do, Orion receives the domain, report, selected metrics and attributes, grain, row count, columns, and a sample of the first five rows — and it answers about that specific data using the real numbers.
Ask your question
Ask in plain language. Orion assembles its context blocks — learned memory, workspace memory, the knowledge graph for your question, metric contracts, and the recent conversation — into its system prompt before it reasons or runs any tools.
Correct it when it is wrong
If Orion uses the wrong definition or makes a mistake, tell it the correct answer in the chat. After learning something important — a correction, a definition, or a preference — Orion calls store_memory so the fact is available in future sessions, not just this one.
Teach it a definition or preference
State definitions and preferences explicitly: "Revenue means net of refunds" or "Always show me weekly grain." Orion stores these as typed memory (for example metric_definition or preference) so later answers honor them automatically.
Govern definitions in Forge
For definitions that must be authoritative across the whole workspace, encode them as metric contracts and model relationships in the knowledge graph in Forge. These are injected as governed context, so Orion treats them as the source of truth rather than something it can reinterpret.
Examples
Suppose your team always excludes test orders and treats revenue as net of refunds. You can teach Orion both facts in one short exchange. When you tell it, Orion records them as memory so every future session starts already knowing them:
{
"memory_type": "metric_definition",
"key": "revenue_definition",
"value": "Revenue is net of refunds; exclude orders where is_test = true.",
"source": "user_explicit"
}The memory_type is one of business_context, metric_definition, correction, preference, or schema_insight, and source is one of user_explicit, inferred, or correction. On the next session, that fact is loaded back in and shown to Orion under "What you know about this business," so it applies the rule without being reminded.
Now picture a date-sensitive question on a dataset that ends in the past. You ask, "How did revenue do last week?" Because Orion anchors relative windows to the dataset's most recent date, it will not silently query an empty future window. Instead it answers with the real period and labels it honestly:
For the week of Dec 16–22, 2024 (most recent available — this dataset ends
before today, 2026-06-27), revenue was $412,800.
Orion will not call lagged data "last week" unless that exact calendar week, relative to today, is what the figure actually covers.
Best practices
- Teach corrections once. When Orion gets a metric wrong, correct it in the chat. Stored corrections are surfaced back to Orion in later sessions under "Past corrections — you got these wrong before," so the same mistake should not recur.
- Promote stable definitions to contracts. Chat-taught memory is great for evolving knowledge, but definitions that must be authoritative belong in metric contracts where they are injected as the source of truth.
- Build out the knowledge graph. The more relationships your model captures, the more relevant the context Orion pulls for a given question. See the knowledge graph.
- Open Orion from a result when your question is about something you can see. The live query context lets Orion answer with the actual numbers on screen instead of re-running a query.
- Keep preferences explicit. Stating a default grain, currency, or date range lets Orion store it as a preference and apply it consistently.
Tips
You can confirm Orion absorbed a lesson by asking it to restate the definition or preference in a later message. Because learned memory persists across sessions, the right answer should come back even in a brand-new chat. If it does not, restate it clearly so Orion stores it again — explicit, user-stated facts are recorded with the highest confidence and load first.
Common mistakes
store_memory on — typically clear corrections, definitions, and preferences. If you need something to stick, state it as a definite rule ("Always…", "X means…") rather than mentioning it in passing.Expecting full conversation recall. Session history is trimmed to roughly the last 8 turns, and large tool results inside that history are truncated. Details from much earlier in a long thread may no longer be in context — restate anything important.
Treating anchored periods as a bug. If a number is labeled with an explicit past date ("week of Dec 16–22") instead of "last week," that is date-awareness working as intended on a dataset that ends in the past — not a wrong answer.
Opening Orion from a blank chat for an on-screen question. Without the live query context, Orion has no snapshot of the result you are looking at and may re-derive it instead of answering about your exact rows.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Orion ignores a definition you stated earlier in the same thread | The fact was beyond the ~8-turn session-history window, or it was not stored as durable memory | Restate it clearly as a rule; Orion will store it with store_memory so it persists next session |
| Orion repeats a mistake you already corrected | The correction was not captured as a correction memory entry | Correct it explicitly ("That's wrong — the right value is X"); corrections are surfaced back under "Past corrections" in future sessions |
| Orion does not use the chart you have open | You opened Orion without a live result, so no query context block was injected | Open Orion from the Discover result; it then receives the domain, metrics, grain, columns, and a 5-row sample |
| Orion uses a different metric definition than your team's standard | The definition lives only in chat memory, not in a governed contract | Encode it as a metric contract so it is injected as an authoritative definition |
| A number is labeled with a past date instead of "last week" | The dataset ends before today, so Orion anchored the relative window to the dataset's latest date | This is expected — Orion labels periods honestly and will say when data is behind the real calendar |
| Older context seems missing in a long conversation | Session history is trimmed to ~8 turns and large tool results are truncated | Restate the key facts; for anything durable, ask Orion to remember it so it survives across sessions |