How to build a context layer for CRM AI

A CRM context layer is a set of notes your AI can read that explains what your CRM fields actually mean.

That is the simple version. The more precise version: it is a versioned set of field-level definitions that sits between your CRM and any AI reading from it. It turns raw properties like account_health = Green or risk_score = 82 into the business meaning behind those values.

You need this because CRMs are full of fields that look obvious until you try to make a machine reason from them.

The model can see the field name. It cannot see the Slack thread where everyone agreed to stop using that field. It cannot see that a score of 82 is bad in one model and good in another. It cannot see that "Strategic" changes the rules for support escalation, renewal risk, and executive coverage.

So it guesses.

This guide explains the pattern. The setup details live in the platform guides:

The problem: your CRM has data, not meaning

Here is a normal-looking account record:

raw-account.json

{
  "id": "0017a00001Example",
  "name": "Northstar Supply",
  "industry": "Manufacturing",
  "account_health": "Green",
  "renewal_risk_score": 82,
  "support_escalations_90d": 4,
  "last_executive_touch_days": 121,
  "contract_end_date": "2026-10-15",
  "customer_tier": "Strategic"
}

If you work around CRM data long enough, you can already feel the problem.

account_health says Green. Is that real, or is it a field someone stopped maintaining last year?

renewal_risk_score says 82. Is 82 good or bad?

support_escalations_90d says 4. Is that alarming for this customer, or normal?

The model does not know. It sees names and values. Your business runs on the rules around those values.

That gap is where bad CRM AI answers come from.

Before and after: one account, two answers

The fastest way to understand the problem is to ask one question:

Is Northstar Supply genuinely at risk?

Without context, the answer might look like this:

ungrounded-answer.md

Northstar Supply does not appear to be at high renewal risk. The account health
field is Green, which indicates the customer is in good standing. There are some
support escalations, but the overall account status suggests the team does not need
to prioritize intervention yet.

That sounds reasonable. It is also wrong.

The model trusted account_health because the field name sounded official. But in this example, that field is stale. The real risk signal is renewal_risk_score, and the model had no way to know how to read it.

Now give the model context for the important fields:

context/account_health.yaml

property: account_health
object: account
label: Account health
meaning: >
  Old manually maintained health field. Do not use this for renewal-risk
  decisions. It may be stale.
authoritative: false
replacedBy: renewal_risk_score
updated: 2026-08-01

context/renewal_risk_score.yaml

property: renewal_risk_score
object: account
label: Renewal risk score
meaning: >
  0–100 estimate of renewal risk. Higher means more risk.
interpretation:
  - "0–39: low risk"
  - "40–74: watch"
  - "75–100: high risk"
authoritative: true
updated: 2026-08-01

context/last_executive_touch_days.yaml

property: last_executive_touch_days
object: account
label: Days since executive touch
meaning: >
  Days since a director-level or above contact had a logged meeting, call, or
  email with the account. For Strategic customers near renewal, values above 90
  increase risk.
authoritative: true
updated: 2026-08-01

Ask the same question again:

grounded-answer.md

Northstar Supply should be treated as at risk.
 
Do not rely on account_health = Green. The context says that field is old,
manually maintained, and not authoritative for renewal-risk decisions.
 
The stronger signal is renewal_risk_score = 82. The context says scores from
75–100 are high risk. This account is also Strategic, has four support escalations
in the last 90 days, and has gone 121 days without an executive touch.
 
Recommended next step: review this account with CS leadership and schedule an
executive touch before the renewal motion starts.

Same record. Same question. Better answer.

Not because the model got magically smarter. It just stopped guessing which fields to trust.

Why the built-in CRM AI still leaves a gap

HubSpot and Salesforce both ship useful AI grounding features. You should use them where they fit.

HubSpot has Breeze context and knowledge vaults. Those can give HubSpot AI tools business-level context, files, CRM content, and segments. That helps. It still does not give every workflow you build a clean, versioned explanation of which custom properties are authoritative and how to interpret their values. HubSpot documents those features here: Breeze context and knowledge vaults.

Salesforce has Agentforce grounding, Data Libraries, and Prompt Builder resources. Those can ground prompts with CRM data, Apex, flows, related lists, and other sources. Also useful. But the same gap remains: Salesforce can pass the field to the model; it does not automatically know your company's operating rule for that field. Salesforce documents those pieces here: grounding Agentforce in data and grounding prompt templates.

The short version: platforms can retrieve the data. You still own the meaning.

The data model

Keep this boring. One file per field that matters.

context/fields/renewal_risk_score.yaml

property: renewal_risk_score
object: account
label: Renewal risk score
meaning: >
  0–100 estimate of renewal risk. Higher means more risk.
interpretation:
  - "0–39: low risk"
  - "40–74: watch"
  - "75–100: high risk"
authoritative: true
owner: customer-success-ops
updated: 2026-08-01

You do not need a giant ontology. You need the few fields that change the answer.

Three parts matter most:

meaning: what the field means in plain English;
interpretation: how to read the values;
authoritative: whether the model should trust it.

That last one matters more than people think. A model will happily trust a dead field if the name sounds important.

Why this should be data, not a longer prompt

You can paste this into a system prompt. For five fields, fine.

Then you add accounts, contacts, opportunities, tickets, custom objects, scoring fields, lifecycle fields, routing fields, and fields that only matter in one region. Now your prompt is a junk drawer.

Store the context as data instead.

That lets you:

review changes;
version the definitions;
load only the fields needed for the current task;
test whether the model is using the right fields;
reuse the same definitions across HubSpot, Salesforce, n8n, or anything else.

The prompt is how you deliver the context. It should not be where the context lives.

How to know it works

Run the same record twice.

First, give the model only raw CRM data. Then give it the same data plus the relevant context entries.

You are looking for a change in reasoning, not just a nicer answer.

A working context layer should make the model:

ignore fields marked non-authoritative;
explain which fields it trusted;
apply your thresholds correctly;
stop treating field labels as business rules.

If the answer only sounds more polished, you did not fix the problem. If the answer changes because the model now knows which signal matters, you are on the right path.

What this is called elsewhere

The terms get messy.

Term	Plain-English version
Context layer	The broad category. It gives AI the extra business context it needs at runtime.
Field context layer	The CRM version. It explains fields, properties, objects, and values.
Semantic layer	Related, but usually about metrics. A context layer also tells an agent when and how to use something.
Context graph	A graph-shaped way to model context. Useful sometimes. Not required here.
AI context gap	The failure mode: the AI can access data but not the rules that make the data useful.

A knowledge graph maps entities and relationships: accounts connected to contacts, opportunities, products, tickets, and so on. A context layer is different. It tells the model how to interpret the data it already has in front of it: which fields to trust, which ones are stale, and what the values mean in practice. You can build a context layer on top of a knowledge graph, but you do not need one to solve the field-meaning problem.

Pick your platform

Start with the implementation closest to your stack.

HubSpot

Use this if your problem starts with custom properties, associations, property types, or Breeze-era AI features.

HubSpot context layer
Best fit: HubSpot properties and associations
Main concern: stored values often need more explanation than the UI label gives

Salesforce

Use this if you want field definitions stored near Salesforce and retrieved with Apex or an MCP server.

Salesforce context layer
Best fit: custom metadata, Apex retrieval, Agentforce-adjacent workflows
Main concern: custom fields and record types carry business rules the model cannot infer

n8n

Use this if you want the context layer outside any one CRM so the same definitions can work across tools.

n8n context layer
Best fit: portable workflows across HubSpot, Salesforce, and other systems
Main concern: keeping the context store independent from one CRM vendor

The pattern is the same in all three. The plumbing changes.