# ClariLayer

> ClariLayer is the context layer you never have to curate — it grows out of the work you are already doing, and every definition is reconciled against your source, not just asserted. Connect it to claude.ai, Claude Code, Cursor, or Codex over MCP. It bootstraps five artifact kinds — SQL, dbt, CLAUDE.md, dictionary/codebook, and semantic model — and reconciles one saved definition at a time through warehouse actual_sample or row-free HubSpot crm_evidence, so your agent stops re-explaining your data every session.

## Key Pages
- [Home](https://clarilayer.com)
- [Features](https://clarilayer.com/features)
- [Use Cases](https://clarilayer.com/use-cases)
- [Pricing](https://clarilayer.com/pricing)
- [About](https://clarilayer.com/about)
- [Blog](https://clarilayer.com/blog)
- [Methodology](https://clarilayer.com/methodology)
- [For teams](https://clarilayer.com/for-teams)

## Comparisons & Security
- [Security](https://clarilayer.com/security)
- [Comparisons](https://clarilayer.com/comparisons)
- [ClariLayer vs CLAUDE.md](https://clarilayer.com/comparisons/claude-md)
- [ClariLayer vs Semantic Layers](https://clarilayer.com/comparisons/semantic-layer)

## Product Facts
- ClariLayer is the context layer you never have to curate — it grows out of the work you are already doing, and every definition is reconciled against your source, not just asserted. It is delivered over MCP so an individual analyst or RevOps operator can give their AI durable, checkable context.
- In our internal paired eval — three batteries, 38 pre-registered data questions, same agent with and without the layer — the agent scored 36/38 with ClariLayer connected vs 26/38 without. The cheaper the model, the bigger the lift (the control went confidently wrong under session load).
- It is single-player: one analyst or RevOps operator, their own data, their own agent — no team account or procurement required. The production service supports claude.ai through OAuth; Claude Code, Cursor, and Codex connect over MCP with a context key.
- Connect the clarilayer MCP server at POST /api/mcp/mcp. The four headline verbs are recall (get_analysis_context), remember, bootstrap, and reconcile; context_checkpoint separately records a bounded completion receipt.
- bootstrap bulk-ingests context from artifacts you already have — five source kinds: validated SQL (deterministically structured into tables/joins/grain), a data dictionary / codebook (the agent maps it into structured per-variable schema-notes), a semantic-layer artifact such as a Databricks Metric View or dbt semantic models (the agent normalizes it into structured models, one canonical metric definition each), dbt models, and CLAUDE.md / freeform notes.
- propose and propose_batch suggest context for your review instead of saving it directly: proposals land in your Context Inbox to accept or reject (nothing is recalled until you accept). propose_batch is the bulk path and the vehicle for conversation harvest — ask your agent to distill the durable facts from a working session into your Inbox; explicit-request only, you approve each, and the transcript is never sent to ClariLayer (only the distilled candidate facts cross the boundary).
- Each explicit reconcile checks one compatible saved definition through one shipped adapter. Warehouse definitions accept agent-supplied actual_sample evidence: columns, an optional row count, and optional preview rows. HubSpot CRM definitions accept bounded crm_evidence: property metadata and aggregate value distributions, with CRM rows recursively forbidden.
- HubSpot reconcile is generally available to authenticated organizations behind the global emergency kill switch. Salesforce CRM contracts can be stored and recalled, but Salesforce reconcile is disabled.
- In the personal MCP reconciliation path, ClariLayer never holds source credentials, executes SQL, or calls HubSpot; the agent is the connector. Optional preview rows are permitted only in warehouse actual_sample evidence, while CRM evidence is row-free. Separately configured team connectors belong to the gated Governed Context Edge surface and are not part of this personal path.
- context_checkpoint durably and idempotently persists the agent's managed-protocol context_updated or no_update_required declaration. It validates ownership and eligibility of referenced ClariLayer objects; it does not independently prove an entry changed or external work happened. Proposal-only work and update_failed cannot complete the loop, and the receipt never certifies code, deployment, query output, provider state, or semantic correctness.
- Statuses are asserted and caveat. The stronger verified status is not live and remains gated off.
- The context you build compounds across sessions and is portable across claude.ai, Claude Code, Cursor, and Codex. The Governed Context Edge — shared team canon, Diff-to-team, and conflict adjudication — is built and in a hand-run private pilot; teams request access at clarilayer.com/for-teams.

## Docs
- [ClariLayer Docs](https://clarilayer.com/docs)
- [MCP Quickstart](https://clarilayer.com/docs/getting-started)
- [bootstrap verb](https://clarilayer.com/docs/quickstart/bootstrap)
- [Use ClariLayer with Databricks (semantic_model import)](https://clarilayer.com/docs/quickstart/databricks)
- [harvest & propose workflow (propose_batch)](https://clarilayer.com/docs/quickstart/harvest)
- [recall verb (recall_context and get_analysis_context)](https://clarilayer.com/docs/quickstart/recall)
- [remember verb](https://clarilayer.com/docs/quickstart/remember)
- [reconcile verb](https://clarilayer.com/docs/quickstart/reconcile)
- [Verified vs Asserted](https://clarilayer.com/docs/concepts/verified-vs-asserted)
- [The Context Layer](https://clarilayer.com/docs/concepts/context-layer)
- [The Reasoning Trail](https://clarilayer.com/docs/concepts/reasoning-trail)
- [AI Agent Context Guide](https://clarilayer.com/docs/guides/ai-agent-context)
- [dbt-check CLI Guide](https://clarilayer.com/docs/guides/dbt-check)
- [SaaS Metrics Definition Library](https://clarilayer.com/docs/reference/saas-metrics)
- [Annual Recurring Revenue Definition](https://clarilayer.com/docs/reference/saas-metrics/arr)
- [Monthly Recurring Revenue Definition](https://clarilayer.com/docs/reference/saas-metrics/mrr)
- [Net Revenue Retention Definition](https://clarilayer.com/docs/reference/saas-metrics/nrr)
- [Churn Definition](https://clarilayer.com/docs/reference/saas-metrics/churn)
- [Pipeline Coverage Definition](https://clarilayer.com/docs/reference/saas-metrics/pipeline-coverage)
- [Gross Revenue Retention Definition](https://clarilayer.com/docs/reference/saas-metrics/gross-revenue-retention)
- [Expansion MRR Definition](https://clarilayer.com/docs/reference/saas-metrics/expansion-mrr)
- [Contraction MRR Definition](https://clarilayer.com/docs/reference/saas-metrics/contraction-mrr)
- [Customer Churn Rate Definition](https://clarilayer.com/docs/reference/saas-metrics/customer-churn-rate)
- [Logo Retention Definition](https://clarilayer.com/docs/reference/saas-metrics/logo-retention)
- [Average Revenue per Account Definition](https://clarilayer.com/docs/reference/saas-metrics/arpa)
- [Annual Contract Value Definition](https://clarilayer.com/docs/reference/saas-metrics/acv)
- [ARR Growth Rate Definition](https://clarilayer.com/docs/reference/saas-metrics/arr-growth-rate)
- [Sales Cycle Length Definition](https://clarilayer.com/docs/reference/saas-metrics/sales-cycle-length)
- [Win Rate Definition](https://clarilayer.com/docs/reference/saas-metrics/win-rate)
- [Forecast Accuracy Definition](https://clarilayer.com/docs/reference/saas-metrics/forecast-accuracy)
- [API v1 Overview](https://clarilayer.com/docs/api/v1)
- [API v1 Authentication](https://clarilayer.com/docs/api/v1/authentication)
- [GET /api/v1/metrics and GET /api/v1/metrics/{id}](https://clarilayer.com/docs/api/v1/metrics)
- [GET /api/v1/metrics/{id}/contract](https://clarilayer.com/docs/api/v1/metrics-contract)

## Blog
- [Semantic Recall: Helping Your AI Find What It Saved](https://clarilayer.com/blog/semantic-recall-find-saved-context)
- [We checked every public dbt project we could find for docs-vs-warehouse drift](https://clarilayer.com/blog/dbt-docs-warehouse-drift-survey)
- [How a Context Layer Differs From Notes and AI Memory](https://clarilayer.com/blog/context-layer-vs-notes-and-ai-memory)
- [Anthropic and OpenAI both said context is the bottleneck for data agents. Here's what they didn't say.](https://clarilayer.com/blog/what-anthropic-and-openai-didnt-say-about-context-for-data-agents)
- [Your AI Agent Used a Retired Metric Definition. Did It Tell You?](https://clarilayer.com/blog/post-trust-benchmark-v2-1)
- [The ClariLayer Trust Benchmark v1: A 2,136-Call Study of AI Accuracy](https://clarilayer.com/blog/post-trust-benchmark-v1)
- [The Context Gap: Why Warehouses and Semantic Layers Aren't Enough](https://clarilayer.com/blog/context-gap-warehouses-semantic-layers)
- [What ClariLayer Does (And What It Does Not)](https://clarilayer.com/blog/what-clarilayer-does)
- [Why AI Agents Need a Context Layer](https://clarilayer.com/blog/why-ai-agents-need-context)
- [Why Your Metrics Need a Context Layer](https://clarilayer.com/blog/why-metrics-need-context)

## Full Documentation

# Docs

Connect Claude Code, Cursor, Codex, or claude.ai. Save one confirmed decision from your work, then ask your AI to recall it in a later project or session.

## Start here

[Choose your client and start setup](/docs/getting-started#1-connect-your-client). Start free. No credit card. [Pricing](/pricing).

The [Quickstart](/docs/getting-started) keeps connection, one saved decision or rule, and agent recall together. Connecting MCP is separate from optional history import or ongoing capture: you choose the source, space, provider, and what to accept.

- [The Context Layer](/docs/concepts/context-layer) explains how saved context travels between tasks.
- [Verified vs Asserted](/docs/concepts/verified-vs-asserted) explains the live `asserted` and `caveat` statuses; `verified` is not live.

## The four verbs

ClariLayer documents four verbs. `recall` and `remember` are the everyday continuity loop. `bootstrap` and `reconcile` cover structured Analytics context and its supported evidence paths.

- [recall](/docs/quickstart/recall) pulls relevant saved decisions, definitions, notes, and caveats for the current task. General work uses `recall_context`; supported Analytics or CRM work also uses `get_analysis_context` when relevant.
- [remember](/docs/quickstart/remember) saves a confirmed decision, constraint, definition, or correction for later sessions. It is an explicit agent-triggered write.
- [bootstrap](/docs/quickstart/bootstrap) seeds Analytics context from SQL, dbt models, `CLAUDE.md` notes, a data dictionary or codebook, and semantic-layer models.
- [reconcile](/docs/quickstart/reconcile) checks a compatible Analytics SQL definition against warehouse `actual_sample` evidence or a HubSpot CRM contract against row-free `crm_evidence`; a mismatch is flagged as a caveat.

Saved context keeps its source and applicability visible. Correct, replace, supersede, or forget an entry when the work changes. General work memory is not independently reconciled; the `asserted` and `caveat` model applies to the supported Analytics evidence paths described above.

## Going deeper

- [AI Agent Context Guide](/docs/guides/ai-agent-context) walks through the recall-first working loop in practice.
- The completion loop uses `context_checkpoint` to persist the agent's bounded managed-protocol declaration and validate its referenced ClariLayer objects. It does not independently prove that an entry changed, external code deployed, or a source result is correct.
- [SaaS Metrics Definition Library](/docs/reference/saas-metrics) is a reference for the metric definitions teams argue about most: ARR, MRR, NRR, churn, and pipeline coverage.

## For teams

The Governed Context Edge supports shared team canon, governed write and explicit adoption. It is available as a hand-run private pilot:

- [For teams](/for-teams) covers where ClariLayer goes as teams adopt it: personal context layers joined by a governed Context Edge — propose your definition up, adopt the team's canon down, with agency.
- [API v1 overview](/docs/api/v1) documents the read-only Contract API an external workflow or BI tool can use to read a governed metric's canonical context.

# Quickstart

<span id="1-for-cli-agents-mint-a-context-key" />
<span id="2-install-the-mcp-server" />

## 1. Connect your client

Choose your client, copy the setup prompt, and paste it into that AI. The prompt can configure supported local clients or guide you through hosted settings. It does not contain a context key, authorize context uploads, or edit project instructions. You may need to complete browser sign-in or restart the client before its tools appear. Use the manual configuration under the selected client only when the assisted path cannot finish.

ClariLayer is **the context layer you never have to curate**. Start with one decision or rule you want your AI to remember. Start free. No credit card. [See pricing](/pricing).

<span id="3-confirm-the-connection" />

After connecting, ask your agent to call `clarilayer__health`. A successful response confirms the authenticated workspace, not that a particular rule was used. If authentication fails, check your key or complete the claude.ai approval flow. [Connection recovery](#connection-recovery) has the details.

<details id="selected-history">
<summary>Optional: bring over selected history after connecting</summary>

Connecting ClariLayer does not read local history, install a collector, or accept past context. If your setup is supported, you separately choose a local history source, an authorized space, and an extraction provider. Review the extracted batch before accepting it. Ongoing capture is another explicit choice and can be paused or revoked.

Source support and extraction-provider support are different. Current qualified extraction uses the version-specific Claude CLI profile; OpenAI and Cursor extraction providers are unavailable, and native Cursor history qualification remains limited. Your selected source content is processed by the provider you choose. ClariLayer stores extracted context rather than a raw transcript archive.

</details>

<span id="4-bootstrap-your-first-context" />

## 2. Save one artifact or rule

Pick one decision, preference, rule, lesson, or short Analytics artifact you already use. Ask your agent:

> Help me save this selected decision or rule as durable ClariLayer context. Keep its source and applicability. Ask about anything ambiguous before saving, and reuse an existing equivalent instead of creating a duplicate.

No file or source access? Describe one rule yourself, such as how your team handles refunds. Your agent reads a selected file locally and sends the chosen content to ClariLayer. The browser cannot inspect your files. ClariLayer holds no warehouse or CRM credentials, runs no SQL, and does not call your CRM provider in this personal MCP flow.

If you already have saved context, reuse an existing personal rule; when guided setup is available, you can choose it in Connect your AI. A pending proposal still needs Inbox review; it is not saved context for this exercise. The [bootstrap reference](/docs/quickstart/bootstrap) covers all five source kinds: `sql`, `dbt`, `claude_md`, `dictionary`, and `semantic_model`.

## 3. Ask your AI to recall it

Ask: “Use ClariLayer recall before answering: what should I know about [the decision or rule]?” Your agent uses `recall_context` for general work, or `get_analysis_context` for Analytics. Inspect the returned source and applicability. Analytics entries also carry `asserted` or `caveat`; general work memory is not independently verified. When you need the complete body or stored SQL, use `get_context_entry` with the `entry_id` returned by general recall, or with the type/name address returned by Analytics recall. [Read the recall reference](/docs/quickstart/recall).

When the guided setup is available, its browser preview lets you try the question against a scoped read of saved context. Preview does not run your agent or record agent use. After the agent's real recall, use **Check agent reuse** in Connect. Missing or partial activity is unknown; it does not prove the rule was never used. You can report whether the result was useful, or skip.

<details>
<summary>Optional: find context by meaning</summary>

You can search saved context by name without semantic indexing. When self-service consent is available, guided setup with an eligible selected starter reveals an optional organization-wide choice for an owner/admin. The older setup flow offers this choice before the connection instructions when the guide is off. Existing granted, withheld or revoked decisions are not re-prompted; an error dismissal writes nothing.

Enabling permits eligible existing and future entry names/main text and recall query text to be sent to Google through the Vercel AI Gateway; ClariLayer stores entry vectors. Indexing is asynchronous, and search availability depends on the service controls. **Not now** records withheld. Check progress or change consent in Account settings. Revocation removes stored embedding rows, but in-flight requests may finish and data already sent cannot be recalled. Read the [semantic indexing privacy notice](/privacy#semantic-indexing).

</details>

<details id="what-you-need-details">
<summary id="what-you-need">Credentials and other deployments</summary>

ClariLayer's MCP server is a remote, stateless Streamable HTTP endpoint at `POST /api/mcp/mcp`. Claude Code, Cursor, Codex, and other compatible clients can use the remote endpoint; claude.ai uses its hosted Connector flow. A client that supports only stdio needs a compatible HTTP bridge and is not directly supported by the generic route.

Use an MCP-capable client and a ClariLayer workspace. Local clients use a personal `cl_…` context key. `context:read` permits recall; saving or importing requires `context:write`. The full key is shown once: store it securely and keep it out of prompts, tickets and recordings. Revoke a lost key and create a replacement.

Prefer OAuth when the selected client offers a compatible flow. ClariLayer has not verified OAuth end to end in every client. When OAuth is unavailable, enter the context key directly in the client's secure bearer-token, API-key, or Authorization-header field; never paste it into AI chat. The production claude.ai connector uses OAuth approval, with no context key field. A self-hosted or other deployment must enable and configure OAuth before offering that path. Use the deployment's canonical app endpoint; do not replace it with a marketing URL.

</details>

<details id="connection-recovery-details">
<summary id="connection-recovery">Connection recovery and managed instructions</summary>

For a local-client authentication failure, check that the full key was installed and has not been revoked. For claude.ai, reconnect and finish the approval flow. Return to the [client selector](#1-connect-your-client) to open setup with your selected client; sign-in and signup preserve that choice.

Open **Optional: install or update project instructions** under your local client's snippet when you are ready to make recall part of your working routine.

The managed prompt names exactly one target for the client you selected. Copying it does not change your repository: your local agent inspects that one file, asks for approval before an edit, and preserves bytes outside the recognized ClariLayer range. An already-current or conflict decision, or an approved write, reports exactly `installed`, `already current`, or `conflict/manual review`; if you decline approval, the agent stops without claiming an installation state. A malformed managed range, a legacy stanza whose sentinel remains but whose full bytes differ, or incompatible Cursor frontmatter fails closed to manual review. For Claude Code and Codex, otherwise-unrecognized existing text is preserved while the managed range appends on first install.

If an early `CLAUDE.md` or `AGENTS.md` kept the exact old ClariLayer heading but shortened or edited the section underneath it, open **Older shortened ClariLayer section?** and explicitly copy the separate guided recovery prompt. The standard installer remains fail closed. The recovery option appears only for Claude Code and Codex, shows a full one-file replacement diff before asking for approval, and stops on ambiguous headings, fenced examples, marker fragments, or concurrent file changes. Cursor recovery stays manual because its frontmatter and target semantics differ. Neither copying option lets the browser or remote server read or write your repository.

</details>

<details id="5-finish-relevant-data-work-with-a-receipt-details">
<summary id="5-finish-relevant-data-work-with-a-receipt">Completion receipts for ongoing work</summary>

The managed instructions establish a completion loop: **recall → confirmed live remember/reconcile → `context_checkpoint`**. Your agent recalls before relevant data work, writes a confirmed durable change to live context with `remember`, and reconciles it when appropriate. If the suggestion still needs human review, it uses `propose` and stops for acceptance; proposal-only work cannot continue to a completion receipt. After an accepted proposal is live, or after another confirmed live outcome, the completion loop can continue.

A pending proposal is not live recall context, and an `update_failed` checkpoint does not allow completion. When the task made no durable context change, the agent can use `no_update_required` only after explicitly checking the relevant facets.

The receipt has a deliberately narrow meaning: it persists the agent's managed-protocol declaration (`context_updated` or `no_update_required`) and validates ownership and eligibility of any referenced ClariLayer objects. It does **not** independently prove that an entry changed during this task, that code deployed, that Databricks validation passed, that a query result is correct, or that the saved rule is semantically equivalent to an external system.

</details>

## The four verbs

ClariLayer documents four verbs. General work starts with `recall_context` and explicit `remember` writes. `bootstrap`, `get_analysis_context`, and `reconcile` are the structured Analytics path.

- [recall](/docs/quickstart/recall) — use `recall_context` for selected general work, preserving source and applicability. Use `get_analysis_context` as the additional specialist Analytics or CRM recall path.
- [remember](/docs/quickstart/remember) — save a confirmed decision, fact, preference, rule, lesson, or Analytics definition so your agent can use it in later sessions.
- [bootstrap](/docs/quickstart/bootstrap) — import selected SQL, dbt, `CLAUDE.md` notes, a data dictionary or codebook, and semantic-layer models into Analytics context.
- [reconcile](/docs/quickstart/reconcile) — check a saved SQL definition against warehouse `actual_sample` evidence or a HubSpot CRM contract against row-free `crm_evidence`; a mismatch is flagged as a caveat. Salesforce contracts remain store/recall-only.

### Beyond the four verbs

Beyond the basic recall-and-remember loop, the agent can also:

- **Record a completion receipt** — after the relevant recall and confirmed write/reconcile path, call `context_checkpoint` so the task has a durable `context_updated` or `no_update_required` receipt.
- **[Harvest a whole session](/docs/quickstart/harvest)** — on your explicit request, distill the durable facts from a working conversation and stage them in your **Context Inbox** for review (via `propose` / `propose_batch`). Nothing is auto-saved; you approve each, and the transcript is never sent to ClariLayer — only the distilled candidate facts.
- **Manage what's saved** — reversibly retire context with `archive` / `restore` (and `archive_reasoning` / `restore_reasoning` for the caveats and assumptions attached to an entry), or remove it for good with `forget`.

## What "checked" means

General work memory keeps its source and applicability visible, but it is not independently reconciled against an external source. When specialist Analytics `reconcile` runs against a supported warehouse or HubSpot evidence path, a declared-vs-observed mismatch is flagged as a **caveat**; otherwise the entry stays **asserted**. Those are the only public Analytics outcomes. The **verified** status remains gated and is not live. Read [Verified vs Asserted](/docs/concepts/verified-vs-asserted) for exactly what each status means and why.

## Where to go next

- [The Context Layer](/docs/concepts/context-layer) explains selected memory, recall, source, applicability, correction, and specialist Analytics reconciliation.
- [AI Agent Context Guide](/docs/guides/ai-agent-context) shows the recall-first working loop in practice.
- [SaaS Metrics Definition Library](/docs/reference/saas-metrics) is a reference for the metric definitions teams argue about most.
- The [For teams](/for-teams) strand covers what happens as your personal context merges into shared, governed team context.

# bootstrap

Start with one artifact whose meaning you can check: a short SQL query, one dbt model, a note, a dictionary entry, or a semantic-model definition. Ask your agent to inspect only that selected source and clarify ambiguous facts before saving. If you have no file to share, [remember one rule](/docs/quickstart/remember) instead. The [Quickstart](/docs/getting-started#2-save-one-artifact-or-rule) walks through that first task.

When you want to import more, `bootstrap` supports bounded batches of the five source kinds below. You choose the content the agent sends.

**`bootstrap` feeds on your files, never your data.** Your agent reads each artifact locally — your SQL, your dbt models, your `CLAUDE.md`, a data dictionary, a semantic-layer artifact — and passes what it reads to the `bootstrap` tool (raw text for some kinds, structured `rows` or `models` for others). ClariLayer never connects to or reads your warehouse, holds no credentials, and runs no server-side SQL, so you stay in control of exactly what is shared.

## What it ingests

`bootstrap` accepts five source kinds today. Three are **structured** (`sql`, `dictionary`, and `semantic_model`); the other two are stored mostly as raw notes:

- **`sql`** — a SELECT query. This is the only source kind structured by **server-side parsing of raw text**: ClariLayer validates the SQL and deterministically extracts a structured shape (tables, joins, group-bys, time grain) so the resulting entry is genuinely queryable context, not just stored text. (`dictionary` and `semantic_model` are also structured, but via a different mechanism — see below.)
- **`dbt`** — a dbt model file. The content is imported and stored as a schema note (raw content plus light metadata). It is not parsed into structure the way SQL is.
- **`claude_md`** — a `CLAUDE.md` or freeform notes. Imported and stored as a note so your agent can recall it later.
- **`dictionary`** — a column / variable dictionary (a codebook, data dictionary, CSV header + labels, `df.dtypes`, a Looker view, or a SAS/SPSS/Stata export). This is **another structured source kind**, but it is structured differently from `sql`: there is no server-side dictionary parser. Instead your agent maps whatever artifact it has into a structured `rows` payload, and ClariLayer fans those agent-supplied rows out to one schema note per variable. This is the cold-start path when your context lives in a codebook rather than a SQL repo. See [the dictionary section below](#dictionary-a-codebook-or-data-dictionary).
- **`semantic_model`** — a semantic-layer artifact (a Databricks Metric View, dbt semantic models, a Snowflake semantic view, and so on). Like `dictionary`, there is no server-side vendor parser: your agent normalizes the artifact into structured `models` and ClariLayer fans those out to one metric **`definition`** per model, each carrying a structured metric contract. This is the path when your definitions already live in a semantic layer. See [Use ClariLayer with Databricks](/docs/quickstart/databricks) for a worked example.

### `dictionary` — a codebook or data dictionary

If your data context lives in a codebook or data dictionary (common for survey, research, or spreadsheet-first work that has no SQL repo behind it), point your agent at it. Unlike the other kinds, you do **not** paste raw file text: your agent maps the artifact into structured `rows` — each row is one column / variable — and ClariLayer expands it into one schema note per row. There is no per-format parser; the agent does the mapping, so any codebook shape works (a CSV header plus labels, `df.dtypes`, a dbt `schema.yml`'s column docs, a SAS/SPSS/Stata dictionary export).

Each row carries a required `variable` and optional `label`, `type`, `value_labels` (a coded-value → label map), and `notes`. An optional `dataset` on the source names the table. A small worked example — a customer-survey codebook:

```json
{
  "kind": "dictionary",
  "name": "Customer survey 2026",
  "dataset": "survey_2026",
  "rows": [
    {
      "variable": "respondent_id",
      "label": "Stable per-respondent identifier (hashed owner email)",
      "type": "string"
    },
    {
      "variable": "nps_bucket",
      "label": "Net Promoter Score bucket from the q3 survey",
      "type": "categorical",
      "value_labels": { "0": "Detractor (0-6)", "1": "Passive (7-8)", "2": "Promoter (9-10)" }
    },
    {
      "variable": "csat_score",
      "label": "Customer satisfaction rating, 1-5 Likert",
      "type": "integer",
      "notes": "null when the respondent skipped the item"
    }
  ]
}
```

Each row becomes **one recall-addressable schema note** named `{dataset}.{variable}` — so the example above lands `survey_2026.respondent_id`, `survey_2026.nps_bucket`, and `survey_2026.csat_score`. When `dataset` is omitted, the source `name` is used as the prefix instead. After this, asking your agent "what does `survey_2026.nps_bucket` mean?" recalls the variable with its label and decoded value labels. The same per-call bounds apply (each row is size-checked, and a very large dictionary is split across multiple calls).

## How to run it

Ask your agent to bootstrap from a directory or a set of files. A natural prompt:

> Bootstrap my ClariLayer context from `./analytics/sql` and my dbt models in `./models`.

Or, when your context lives in a codebook instead of a SQL repo:

> Bootstrap my ClariLayer context from the data dictionary in `./docs/survey_2026_codebook.csv`.

Your agent reads those files and calls `bootstrap` with their content (mapping a codebook into the `dictionary` source's `rows`). The tool is bounded so a single call cannot flood your store: each source is capped (around 50 KB per source), and the whole call is capped (around 200 KB and 200 sources). Oversized sources are reported back, never silently truncated.

## What you get back

`bootstrap` returns a summary of what happened: how many entries were created, updated, and skipped, a breakdown by source type, and any sources it dropped (for example, an oversized file or an unparseable SQL statement). Ingestion is deduped, so re-running `bootstrap` over the same artifacts updates existing entries rather than creating duplicates.

After a bootstrap, the entries it created are stored with status `asserted` and provenance that records where they came from: SQL uses `sql_import`, dbt uses `dbt`, dictionary rows use `dictionary`, semantic models use `semantic_model`, and `CLAUDE.md` / freeform notes use `you`. The separate `agent` provenance identifies facts an AI agent extracted through an agent-originated write path; it is not the provenance assigned to `claude_md` bootstrap entries. `asserted` is the honest baseline — the entry has not been contradicted, but it is not stamped as proven. To check a supported definition, run [reconcile](/docs/quickstart/reconcile) against it.

## Bootstrap, then recall

Once your store has content, your agent can [recall](/docs/quickstart/recall) it in-flow. The typical first loop is:

1. `bootstrap` the relevant SQL, dbt, `CLAUDE.md` notes, dictionary rows, or semantic models so the store is not empty.
2. Ask a question; your agent recalls the relevant definitions and answers from them.
3. When your agent learns something new or you correct it, [remember](/docs/quickstart/remember) it so the next session benefits.
4. When a number looks off, [reconcile](/docs/quickstart/reconcile) a stored SQL definition with warehouse `actual_sample` or a HubSpot CRM contract with row-free `crm_evidence`.

## Privacy posture

ClariLayer receives only what your agent chooses to send — the artifact text (your SQL, dbt models, `CLAUDE.md`), or the structured input your agent maps for the schema-first kinds (a `dictionary` source's `rows`, a `semantic_model` source's `models`); it never connects to your warehouse, holds source credentials, executes SQL server-side, or calls a CRM provider. The `sql` structuring is a static parse of query text, not a live data read. `reconcile` is a separate flow: warehouse `actual_sample` can include optional preview rows with real values, while HubSpot `crm_evidence` is row-free by contract.

## See also

- [Quickstart](/docs/getting-started) — connect a CLI agent with a context key or production claude.ai over OAuth.
- [recall](/docs/quickstart/recall) — pull bootstrapped context back in-flow.
- [Verified vs Asserted](/docs/concepts/verified-vs-asserted) — what the `asserted` status on a bootstrapped entry means.

# recall

`recall` is how your agent pulls relevant saved context mid-task without you leaving your flow. General work uses the `recall_context` MCP tool. When your agent is about to draft, decide, or answer a question, it can recall selected decisions, facts, preferences, rules, and lessons from the authorized space, with source and applicability intact. Supported Analytics or CRM work has an additional specialist path through `get_analysis_context`.

This is the structural fix for the old "destination app" problem. You do not open a tool to look a number up; the context rides along inside claude.ai, Claude Code, Cursor, or Codex, and your agent reaches for it when it needs it.

## What it returns

`recall_context` takes a query and optional `project` and `purpose` relevance hints. It searches the selected authorized space; those hints do not change access or silently exclude other projects. Each result carries:

- an **entry ID and bounded summary**;
- its **source**, including provenance and available capture metadata;
- its **applicability**, including general or bounded scope, project references, and conditions.

Recall is read-only and in-flow. It never mutates your store; it only surfaces what is already there. Because it reads, it needs only `context:read` — a read-only context key can recall.

For Analytics, `get_analysis_context` returns definitions, schema notes, saved queries, and notes with provenance and `asserted` or `caveat` status. There is no public query-history bootstrap source or importer.

## Fetch the full entry

Recall returns bounded body previews and does not inline stored SQL. For general recall, call `get_context_entry` with the returned `entry_id` when `summary_truncated` is true or you need complete content. For Analytics recall, use the type/name address when `has_sql` or `has_crm_contract` indicates more detail. The browser's scoped preview is separate: it does not run MCP recall or record agent use.

## Who decides when to recall

Recall is a tool your agent decides to call — ClariLayer exposes it; it does not force a call. In practice you get the most value by making recall the first step of your agent's loop. For Claude Code, Cursor, or Codex, the [Quickstart](/docs/getting-started#2-install-the-mcp-server) generates one managed-install prompt from the local client you explicitly select. Your local agent inspects only that client's canonical instruction target, asks before editing, and installs a managed range that carries the recall-first and completion-checkpoint workflow into future sessions. The browser and remote server do not inspect or edit your files. The claude.ai path connects to the production custom Connector over OAuth and does not install a local project instruction file.

That is the difference between "can recall in-flow" (always true — the tool is there) and "always recalls first" (true only when your client config or prompt makes it so).

<span id="how-ranking-works" className="block h-0 scroll-mt-24" aria-hidden="true" />

## How general recall is scoped

General recall searches the entire selected authorized space. Optional `project` and `purpose` values help relevance; they are not access controls or candidate filters. A customer- or project-bounded entry stays bounded when recalled elsewhere, and the response identifies how its applicability relates to the supplied project hint.

Ranking and delivery are bounded. A delivery record shows that context was served to the client, not that the agent used it or that the content is true.

## Honest use-case scoping

This section applies to specialist Analytics `get_analysis_context`. `use_case` is a precision hint. Analytics recall prefers entries in that use case together with unscoped context. When there is no authoritative in-scope result, it can rescue a strong cross-scope match and label it `use_case_mismatch` instead of silently hiding it or pretending it is in scope. Inspect the additive honesty fields when present: `use_case_warning`, `off_scope_entries`, `routing_confidence`, and `available_use_cases`.

Set `strict_use_case: true` when the task must never use cross-scope fallback. In that mode, recall does not rescue off-scope entries.

## A typical loop

1. Your agent calls `recall_context` for relevant general work, and the specialist Analytics recall when applicable.
2. It answers from recalled context, preserving source and applicability. Analytics answers also carry known status mismatches.
3. If the task confirms a durable change, it [remembers](/docs/quickstart/remember) it. If the suggestion still needs review, it uses `propose` and stops for human acceptance instead of treating proposal-only work as live context.
4. If a compatible recalled definition is checked or has drifted, it [reconciles](/docs/quickstart/reconcile) it through the supported warehouse `actual_sample` or HubSpot `crm_evidence` adapter.
5. Before reporting completion, it calls `context_checkpoint` with `context_updated` and active live entry references, or `no_update_required` after explicitly checking that no durable context update was needed. Proposal-only work cannot reach this completing step.

The checkpoint receipt persists the agent's bounded managed-protocol declaration and validates its referenced ClariLayer objects. It does not independently prove that an entry changed, external code deployed, a warehouse validation passed, a query is correct, or saved context is semantically equivalent to another system. `update_failed` and proposal-only work are non-completing outcomes.

Confirmed corrections and new notes remain available to later sessions when you or your agent explicitly save them.

## Status, honestly

For specialist Analytics reconciliation, a recalled entry's status is either `asserted` or `caveat`. `asserted` means saved but not contradicted; `caveat` means `reconcile` found a declared-vs-actual mismatch worth treating with care. General memory is not independently reconciled. The stronger `verified` status remains gated and is not part of the live public result contract — see [Verified vs Asserted](/docs/concepts/verified-vs-asserted) for what that means and why.

## See also

- [Quickstart](/docs/getting-started) — install the MCP and confirm the connection.
- [remember](/docs/quickstart/remember) — save context so future recalls are richer.
- [AI Agent Context Guide](/docs/guides/ai-agent-context) — the recall-first working loop in detail.

# remember

`remember` is the retention mechanic. It saves one confirmed piece of context — a project decision, definition, note, constraint, join path, or caveat — so your AI can use it in later sessions.

Save durable context after you confirm it. Agent-triggered writes are explicit tool calls; ClariLayer does not force every conversation detail into memory. You can correct, replace, supersede, or forget context as the work changes.

## What it saves

`remember` saves one context entry. You give it a type and a name, the content to store, and optionally a SELECT query, structured metric contract, or CRM contract. A materially different entry with the same natural key is not overwritten silently; ClariLayer returns a structured collision and writes nothing until the caller makes the replacement decision explicit.

Typical things worth remembering:

- a **decision** — "Show the product demo first and keep technical detail in the docs";
- a **project constraint** — "This launch page is for individual AI workers, not the team pilot";
- a **definition** — "Active Customer means an account with at least one billable subscription in the trailing 30 days, excluding internal test workspaces";
- a **schema note** — "`fct_orders.amount` is in cents, not dollars";
- a **join path** — "join `users` to `orgs` on `users.org_id`, never on email";
- a **gotcha** — "refunds live in `fct_refunds`, so revenue queries must subtract them or they double-count."

## How to run it

You rarely call `remember` directly; you let your agent do it as part of the conversation. A natural prompt:

> Remember that our revenue numbers must subtract refunds from `fct_refunds`, or they double-count.

Your agent calls `remember` with that content, and it is saved to your store. A definition can also carry the SQL or strict CRM contract that backs it, which sets up a supported warehouse or HubSpot [reconcile](/docs/quickstart/reconcile) later.

## Updating without silent overwrite

The default is non-destructive:

- Repeating an identical `(type, name)` and payload is an idempotent no-op.
- Sending materially different content for the same natural key returns a collision; the existing entry stays unchanged.
- To overwrite that exact entry in place, reissue the exact key and payload with `replace: true`.

Natural-key collision detection normalizes case and whitespace, but `replace: true` targets the exact stored key. A case- or whitespace-variant request can therefore report a collision without becoming an alternate way to overwrite the original.

An in-place replacement returns the entry to `asserted`. If an existing structured `metric` or `crm` contract is omitted from the replacement payload, it is preserved; send `metric: null` or `crm: null` only when you intend to clear it.

## Replacement versus supersede lineage

`replace: true` overwrites one entry in place; it does not create a historical lineage edge. When the old statement should remain visible as history, save the revised statement as a distinct entry, then call `supersede` to point the old entry to the new one. That marks the old entry superseded while keeping the replacement as the live context.

## Status and provenance

A remembered or replaced entry is saved with status `asserted` and provenance `you`. `asserted` is the honest baseline: the entry has not been contradicted, but it is not stamped as proven. Provenance `you` records that you are the source, as opposed to something imported by [bootstrap](/docs/quickstart/bootstrap).

Remembering is not verifying. A saved definition has the same trust property as the words you typed. That is the gap [reconcile](/docs/quickstart/reconcile) narrows for its two supported adapters: warehouse `actual_sample` for SQL definitions and row-free HubSpot `crm_evidence` for CRM contracts. A mismatch becomes a caveat; a clean or inconclusive check remains asserted.

## remember vs reconcile

- `remember` **captures** a claim. It is fast and always available, and it is the right tool for institutional memory and corrections.
- `reconcile` **checks** a captured claim against supported source evidence. It is how an `asserted` definition earns a caveat when its declaration and the observed evidence disagree.

Use `remember` for confirmed context worth carrying forward. Use `reconcile` when you want to know whether a supported SQL or HubSpot definition still holds against the evidence your agent collected.

After a confirmed live write, the managed completion loop calls `context_checkpoint` with the active entry as evidence. The durable, idempotent receipt persists the agent's `context_updated` declaration and validates ownership and eligibility of the referenced ClariLayer object. It does not independently prove the entry changed or that an external deployment or source result is correct.

<span id="it-compounds" className="block h-0 scroll-mt-24" aria-hidden="true" />

## It carries forward

Remembered entries persist and can be surfaced by [recall](/docs/quickstart/recall) in a later session. The context can travel across claude.ai, Claude Code, Cursor, and Codex, subject to each client's connection and recall behavior.

## See also

- [recall](/docs/quickstart/recall) — pull remembered context back in-flow.
- [reconcile](/docs/quickstart/reconcile) — check a remembered SQL definition or HubSpot CRM contract against supported evidence.
- [Verified vs Asserted](/docs/concepts/verified-vs-asserted) — why a remembered entry is `asserted`, not `verified`.

# reconcile

`reconcile` checks a saved definition against source evidence collected by your agent. It is the step that distinguishes a context layer from a notes file: when declared context and observed evidence disagree, the entry becomes a `caveat`; otherwise it remains `asserted`.

In the personal MCP reconciliation path, ClariLayer never receives your warehouse or CRM credentials, runs your SQL, or calls a CRM provider. The agent uses its own authorized connection and sends one of the two supported evidence shapes in capability v43: warehouse `actual_sample` or bounded, row-free HubSpot `crm_evidence`. HubSpot reconciliation is generally available to authenticated organizations behind the mandatory server-side global emergency switch. Salesforce remains store/recall-only.

## The two evidence paths

The stored definition selects exactly one path:

- **Warehouse/SQL definition:** the agent runs stored SQL and passes `actual_sample` with result columns, an optional bounded row preview, and an optional row count.
- **CRM definition:** the agent passes mutually exclusive `crm_evidence` containing only declared property metadata and value distributions. HubSpot is the only reconcilable CRM provider in the current v43 contract. Salesforce contracts can be remembered and recalled, but after CRM access passes reconcile returns `crm_provider_not_enabled`.

For both paths, a successful check replaces the entry's current evidence detail and updates `last_checked`. It does not append another live evidence blob. Public reconcile output does not include `verified_at` and no `verified` status/result ships.

## Store a CRM definition

Use `remember` with `type: "definition"` and a strict `crm` contract. CRM contracts cannot be combined with `metric` or `sql`. This minimal HubSpot example declares one internal property value:

```json
{
  "type": "definition",
  "name": "Lifecycle stage contract",
  "content": "The lifecycle value used by this workflow.",
  "crm": {
    "schema_version": 1,
    "provider": "hubspot",
    "object_api_name": "contacts",
    "properties": [
      {
        "name": "lifecyclestage",
        "expected_values": [{ "value": "customer" }]
      }
    ]
  }
}
```

`expected_values` and `canonical_value.value` are positive record-usage assertions: the declared internal value is expected to occur in the property's record distribution. A normalized internal identifier may appear in exactly one of `expected_values`, `canonical_value.value`, or `canonical_value.deprecated_aliases`; in particular, do not repeat the canonical value in `expected_values`. Deprecated aliases are conflict candidates, not values expected to remain in use. The canonical presence assertion is independent and requires positive canonical record usage. Positive deprecated-alias usage is a conflict signal; for a complete distribution, the alias-conflict check is inconsistent when the canonical value and an alias both have positive counts. `expected_label` is a separate option-metadata assertion and does not establish record usage. Use provider internal object/property/value identifiers, not display labels, as filter operands.

Configured-but-unused is intentionally different from configured-but-present. An option can exist in HubSpot metadata while having zero record usage. For an expected or canonical value, absence or an exact zero count in a `complete` record distribution is inconsistent with reason `absent_from_complete_distribution`; that means absent from populated records in the complete distribution, not missing from HubSpot configuration. Missing or truncated distributions remain asserted-only, as does a zero `lower_bound` count. Every emitted `crm_enum_value_present` detail therefore carries `evidence_basis: "record_distribution"`. Reconcile does not issue a separate provider-configuration check.

## Complete HubSpot agent recipe

Do not hard-code connector tool names. Provider connectors change their surface; capability-probe the connected provider and choose a bounded read path it actually advertises.

1. Recall the relevant context. When a result says `has_crm_contract: true`, call `get_context_entry` and use the complete stored `body.crm` contract. Do not reconstruct the contract from a truncated recall summary.
2. Inspect the connected provider's capabilities. Request metadata for **only** the contract's declared `object_api_name` and declared property names. Report a property as `unavailable` or omit it when the connector cannot inspect it; never turn a failed read into `absent`.
3. Prefer a bounded aggregation/count capability for each required property distribution. Collect only internal values, optional labels, counts, precision, completeness, and the cap when applicable.
4. If no aggregation capability exists, use the provider's official search/list API through the connected provider, page it, and aggregate locally. Set an explicit record/page cap before starting. Do not persist the executable request or connector-specific tool name into ClariLayer.
5. Mark a distribution or option list `complete` only after every page is exhausted. If a provider, connector, pagination, or local safety cap stops collection, mark it `truncated` and include the actual positive `cap`. A value missing from truncated evidence is inconclusive, never evidence of absence.
6. Use `status: "unavailable"` (or omit the observation) for a failed or inaccessible property lookup. Use `status: "absent"` only when authoritative metadata positively reports the declared property absent.
7. Normalize the envelope before calling `reconcile`: include only the declared provider, object, property metadata, and distributions. Never send CRM records/rows, `sample_rows`, credentials/tokens, undeclared properties, executable provider queries, connector names as persisted dependencies, or raw provider payloads. The recursive row ban rejects `sample_rows` anywhere, including under unexpected nesting.
8. Set count precision honestly. `exact` means the count is complete for that value under the collection method. `lower_bound` means at least that many were observed, but more may exist. A positive lower bound proves presence; a zero lower bound never proves absence.

A complete row-free evidence envelope for the example above is:

```json
{
  "entry_id": "<saved-entry-id>",
  "crm_evidence": {
    "schema_version": 1,
    "provider": "hubspot",
    "object_api_name": "contacts",
    "properties": [
      { "name": "lifecyclestage", "status": "present" }
    ],
    "distributions": [
      {
        "property": "lifecyclestage",
        "completeness": "complete",
        "values": [
          {
            "value": "customer",
            "count": { "value": 7, "precision": "exact" }
          }
        ]
      }
    ]
  }
}
```

Only send evidence after the full contract is fetched and the provider read is complete enough to label honestly. Normalized CRM evidence is capped at 128 KiB; the final stored verification detail is capped at 1 MiB.

## CRM availability and failure boundaries

HubSpot reconcile is generally available for authenticated organizations. A mandatory server-side global emergency switch remains authoritative and fail-closed; when it is off, CRM reconcile returns `crm_reconcile_disabled`. The production operation and rollback procedure belongs in the repository runbook, not in the agent's evidence payload.

After CRM access passes, a Salesforce definition returns `crm_provider_not_enabled`, because Salesforce contracts are store/recall-only. A HubSpot definition without an evidence envelope returns `crm_evidence_required`. Strictly malformed or row-bearing `crm_evidence` is rejected at the MCP schema boundary as JSON-RPC `-32602` InvalidParams. Schema-accepted evidence that is semantically mismatched or exceeds the byte bounds returns `crm_evidence_mismatch`. None of these errors downgrades the definition or manufactures a successful check.

## Warehouse workflow

For a stored SQL definition, the agent runs the SQL using its own warehouse access and calls `reconcile` with `actual_sample`. ClariLayer extracts declared signals from the stored SQL and compares them with the supplied result shape. Optional preview rows may contain sensitive values and are persisted with the warehouse verdict evidence, so omit or redact them when columns and row count are sufficient.

A natural prompt is:

> Reconcile our Active Customer definition: fetch its complete stored context, run its SQL with my warehouse connection, and compare the result shape in ClariLayer.

The warehouse path remains distinct from CRM: never send `actual_sample` for a CRM definition, and never send `crm_evidence` for a warehouse definition.

## Honest outcomes

`reconcile` has two trust outcomes:

- **`caveat`** — at least one applicable declared check conflicts with the supplied evidence.
- **`asserted`** — no applicable check conflicted. This may include checks that were inconclusive because evidence was missing, unavailable, or truncated.

A clean run does not create a stronger status. Inconclusive evidence stays asserted-only at the check level, and a missing value becomes inconsistent only when a complete distribution establishes that absence. Read [Verified vs Asserted](/docs/concepts/verified-vs-asserted) for the trust model.

After a relevant successful reconcile, the managed completion loop calls `context_checkpoint` with the active entry as evidence. The durable, idempotent receipt persists the agent's `context_updated` declaration and validates ownership and eligibility of the referenced ClariLayer object. It does not independently prove that the entry changed, that the warehouse query or CRM source is semantically correct, or that any external code deployed.

## When to reconcile

- When two reports or workflows use different internal values.
- After a warehouse schema or CRM property/options change.
- Before relying on a definition for a consequential analysis or automation.
- When a deprecated CRM alias may still be active beside its canonical value.

## See also

- [remember](/docs/quickstart/remember) — capture the definition that reconcile checks.
- [recall](/docs/quickstart/recall) — recalled entries carry `asserted` or `caveat`.
- [AI Agent Context Guide](/docs/guides/ai-agent-context) — use reconcile inside the recall-first loop.
- [Verified vs Asserted](/docs/concepts/verified-vs-asserted) — the trust-status model.

# Verified vs Asserted

This page explains the trust statuses used by ClariLayer's specialist Analytics reconciliation. General work memory keeps source and applicability visible, but it is not independently reconciled against an external source. For compatible warehouse SQL and HubSpot CRM contracts, the live public statuses are `asserted` and `caveat`; the stronger `verified` status remains gated.

## The three statuses

The status model defines three labels. Two are live today; the stronger one is gated and not part of the public result contract.

### asserted (live)

`asserted` is the neutral baseline — the honest "we are taking your word for it." It is not a claim that an entry is right, and it is not a claim that an entry is wrong. It simply means the entry has not been contradicted.

An entry is `asserted` in any of three cases:

1. it was never reconciled, so nothing has been checked;
2. it was reconciled, but the stored definition and supplied evidence yielded no applicable conclusive checks; or
3. it was reconciled, every applicable check passed, but the strong `verified` mark is gated off in v1 — so a would-be `verified` match is recorded as `asserted`.

Because of case 3, `asserted` does not mean "never checked." A clean reconcile pass still reads `asserted` today. The important thing `asserted` tells you is: not flagged, not stamped.

### caveat (live)

`caveat` is the status `reconcile` assigns when a definition's declared signals and supplied source evidence mismatch. Today that evidence is either warehouse `actual_sample` for stored SQL or row-free HubSpot `crm_evidence` for a CRM contract. It is a flagged "treat this with care."

A caveat is the valuable signal, not an error. It means ClariLayer caught a definition whose stored shape no longer matches the data it claims to produce — exactly the drift that makes two reports disagree. When your agent recalls an entry with a caveat, it should carry that caveat into its answer.

### verified (gated, not live)

`verified` is the strong trust mark for an entry whose declared signals conclusively matched supported source evidence. It is **not shipped today.** The mark is gated off in v1, and a would-be `verified` outcome is deliberately downgraded to `asserted`.

You will not see a `verified` status on a ClariLayer entry today, and ClariLayer's marketing does not show a live "Verified" badge. The stronger status is gated and not part of the current public contract; public reconcile results remain `asserted` or `caveat`.

## Why verified is gated off

It would be easy to stamp entries `verified` and look more impressive. ClariLayer deliberately does not, and the reason is the core of the product's honesty.

For SQL definitions, the thing that would back a `verified` mark is extracting the declared signals from an entry's query — reasoning about what it says it should produce. Today that extraction is a deliberately conservative heuristic over SQL text. A heuristic cannot be made sound against the long tail of SQL dialect edge cases, and a single **false** `verified` is the one failure mode a trust product cannot ship: it would tell you a wrong definition is correct, which is worse than saying nothing. HubSpot evidence has similarly bounded completeness and count semantics; it can establish a conflict or leave a check inconclusive without creating a stronger trust stamp.

So ClariLayer makes the safe trade. Over-flagging is harmless — a caveat just tells you to look. A false all-clear is not. ClariLayer therefore caps every public reconcile result at `caveat` or `asserted`; this documentation makes no delivery-condition or timeline promise for a stronger status.

## What this means for your agent

When your agent recalls context, it should read the status and act on it:

- **`asserted`** — usable context that has not been contradicted. It may be unreconciled, inconclusive, or cleanly reconciled; do not present it as proven.
- **`caveat`** — a known mismatch. Carry the caveat into the answer so the reader knows what to distrust.
- **`verified`** — gated and not part of the live public result contract. Do not expect or infer it from a clean reconcile response.

The honest framing for users is: ClariLayer **reconciles** supported SQL context against warehouse evidence and HubSpot CRM context against row-free CRM evidence, then flags **caveats** — it is evidence-backed and caveat-aware, not blindly asserted. No stronger status is part of the current public result contract.

## See also

- [reconcile](/docs/quickstart/reconcile) — the verb that assigns `caveat` or leaves an entry `asserted`.
- [remember](/docs/quickstart/remember) — why a saved entry starts `asserted`.
- [The Context Layer](/docs/concepts/context-layer) — how reconciled, caveat-aware context beats a hand-typed `CLAUDE.md`.

# The Context Layer

ClariLayer is a personal context layer for the AI tools you already use, delivered over MCP. It keeps selected decisions, definitions, notes, and caveats available across projects and sessions. That might be a launch decision, a project constraint, or an Analytics definition you would otherwise have to explain again in a new chat.

You choose what becomes durable context. Saved entries keep their source and scope, so your agent can recall the relevant context in a later task and you can correct or forget it when it no longer applies. Recall helps continuity; it does not guarantee that every saved statement is correct or that every client will call the tool.

<span id="why-a-hand-typed-claudemd-is-not-enough" className="block h-0 scroll-mt-24" aria-hidden="true" />

## A layer for durable working context

Project instruction files are useful, but they are one file in one client and usually need manual upkeep. ClariLayer gives compatible AI clients a shared place to recall context while you work. A saved entry can carry its source, provenance, applicability, and current trust status instead of becoming an unexplained line in a long prompt.

The basic loop has three parts:

- **Choose** selected work worth carrying forward, either as you work or through a reviewed history import from a supported source.
- **Recall** relevant entries inside your AI client, with source and scope visible.
- **Correct or forget** context when a decision changes or should no longer apply.

<span id="bootstrap-dont-blank-slate" className="block h-0 scroll-mt-24" aria-hidden="true" />

## Start from selected work

After connection, you can save one confirmed rule or decision directly. Where history support is available, you choose a supported local history source, space, and extraction provider, then review the proposed batch before accepting it. Continuous capture is a separate choice for the sources you select. ClariLayer does not archive raw transcripts; selected source content is processed by the extraction provider you choose.

For Analytics work, existing SQL, dbt models, `CLAUDE.md` notes, a data dictionary or codebook, and semantic-layer models can seed context. Those are the five Analytics bootstrap source kinds. See [bootstrap](/docs/quickstart/bootstrap) for their exact contracts and limits.

<span id="reconciled-not-blindly-asserted" className="block h-0 scroll-mt-24" aria-hidden="true" />

## Analytics reconciliation

General work context is saved with its source and applicability; it is not independently reconciled against an external source. Specialist Analytics context has two live reconcile adapters. For a compatible stored SQL definition, your agent runs the query with its own warehouse access and sends `actual_sample` result-shape evidence. For a HubSpot CRM contract, it collects bounded property metadata and distributions and sends row-free `crm_evidence`. ClariLayer compares what the definition declared with that supported evidence, and a mismatch surfaces as a **caveat**.

In the personal MCP reconcile path, ClariLayer does not receive your source credentials or execute SQL server-side, and it never calls HubSpot — your agent is the connector. The separately gated team connector surface uses only explicitly configured connectors under its own controls. Warehouse `actual_sample` may include an optional bounded preview with real values, so omit or redact it when result columns and row count are enough. HubSpot `crm_evidence` is row-free by contract: it contains declared property metadata and aggregate value distributions, never CRM records. Reconcile records a **caveat** on mismatch or leaves the entry **asserted**. The stronger **verified** status remains gated and is not part of the live public result contract. The honest claim is "reconciled and caveat-aware," and [Verified vs Asserted](/docs/concepts/verified-vs-asserted) explains exactly why.

## In-flow, via MCP

ClariLayer lives inside the agent you already use. Claude Code, Cursor, and Codex connect to the production MCP server with a local context key; claude.ai connects to the same service as a custom Connector over OAuth. For general work, `recall_context` pulls relevant context from the selected authorized space while preserving source and applicability. For supported Analytics or CRM work, `get_analysis_context` provides the specialist recall path. Recall is a tool your agent decides to call. For local clients, the managed project rule tells the agent to recall ClariLayer context before relevant work.

<span id="it-compounds" className="block h-0 scroll-mt-24" aria-hidden="true" />

## Build continuity deliberately

Confirmed corrections and new notes persist when you or your agent explicitly save them. Later tasks can recall that context across claude.ai, Claude Code, Cursor, and Codex. Scope and provenance help your agent decide where an entry applies; you remain in control of correction and forgetting.

## For teams

The personal context you build can become the foundation for the team story. The Governed Context Edge adds org canon, Diff-to-team, and adjudication in a hand-run private pilot; request access on the [For teams](/for-teams) page.

## See also

- [Quickstart](/docs/getting-started) — install the MCP and connect your agent.
- [AI Agent Context Guide](/docs/guides/ai-agent-context) — the recall-first working loop.
- [Verified vs Asserted](/docs/concepts/verified-vs-asserted) — what "checked" honestly means.

# The Reasoning Trail

Every data tool you already own stores the current definition of a metric. Warehouses store the SQL. Semantic layers store the joins. dbt stores the lineage. None of them store the assumption the definition rests on, the caveat that is still open, or the correction you made last quarter that must never be re-litigated.

That reasoning is not metadata. It is the memory of *why* your context is what it is — and an AI agent that answers questions about your data without it is structurally guessing.

## Reasoning rides on the entry

In ClariLayer, reasoning is not a separate comments surface. It travels with the context entry itself. Every entry — a definition, a schema note, a reusable query — carries its **provenance** (where it came from: you, a SQL import, a data dictionary, dbt, a semantic model, or a fact your agent proposed) and its **status** (`asserted` or `caveat`).

On top of that, an entry can carry **reasoning attachments**: the assumptions it depends on and the caveats it has earned. An assumption records something the definition takes for granted — "billing exports land by 6am UTC," "test workspaces are already excluded upstream." A caveat records a known reason for care — most importantly, the caveat `reconcile` attaches when an entry's declared shape and the actual result your agent got back disagree.

When your agent recalls an entry, the attachments come along. The answer it gives you is grounded not just in *what* the definition says but in what it assumes and where it is known to be fragile.

## The attachment lifecycle

Reasoning ages, so attachments have a real lifecycle instead of accumulating forever:

- **Archive** retires an assumption or caveat that no longer applies — it leaves the entry's active reasoning but is kept as durable history, so the record of *having once been a concern* is never lost.
- **Restore** reactivates an archived attachment when the concern turns out to still be live.
- **Forget** permanently deletes an attachment — the deliberate, no-undo path for reasoning that was simply wrong.

Superseding an entry works the same way: iteration creates a new version rather than rewriting the old one, so the evidence trail stays inspectable.

## Edges: variants and conflicts

Some of the most valuable reasoning is about how two pieces of context relate. ClariLayer records that as **edges** between entries:

- A **`variant_of`** edge says two definitions are deliberate variants of the same concept — "active user (7-day)" and "active user (28-day)" are both real, and the edge keeps them related instead of letting them masquerade as duplicates or contradictions.
- A **`conflicts_with`** edge says two entries genuinely disagree. The disagreement stays visible: when your agent recalls one side, the conflict is labeled rather than silently resolved by whichever entry ranked higher.

This is the single-player version of a truth every team learns eventually: the problem was never disagreement, it was *invisible* disagreement. An edge makes the disagreement a first-class fact your agent can reason about.

## Corrections are captured

The most common reasoning event is the simplest one: you correct your agent. "No — net revenue must net refunds." ClariLayer is built to capture that correction as durable context, so the next session starts from the corrected understanding instead of rediscovering it. A captured correction lands with provenance `you` and status `asserted`, and it can carry the reasoning — what was wrong, what is right, and why — rather than just the final string.

## How your agent uses the trail

An answer grounded in the Reasoning Trail looks different from an answer grounded in bare SQL:

> Active Customer means an account with at least one billable subscription in the trailing 30 days, excluding internal test workspaces (saved by you). This definition assumes the billing export is current, and it carries a caveat from the last reconcile — the actual result was missing a column the definition declares, so confirm the window before ARR-facing work. A 7-day variant exists and is linked as a deliberate variant.

That is a categorically different answer than the same agent reading the SQL alone: it names the assumption, carries the caveat, and knows the variant exists.

## What belongs in the trail

A useful Reasoning Trail is selective. The highest-value entries are the decisions that explain why a definition differs from the intuitive one, the assumptions a consumer would otherwise discover the hard way, and the caveats that are still open.

- Attach an assumption when a definition depends on something outside the SQL — a pipeline schedule, an upstream filter, a fiscal-calendar quirk.
- Keep a real caveat active until it is resolved; archive it when it is, so the history survives.
- Link deliberate variants with `variant_of` instead of deleting one, and record genuine disagreements with `conflicts_with` instead of picking a winner silently.
- Capture corrections the moment you make them — they are the reasoning your future sessions inherit.

## For teams

The same trail scales up. The Governed Context Edge — in a hand-run private pilot today — carries this reasoning across the team boundary: a definition proposed up to the shared canon arrives with its provenance, status, assumptions, and caveats attached, and conflicts between teammates' definitions are adjudicated in the open rather than overwritten. See [For teams](/for-teams).

## See also

- [reconcile](/docs/quickstart/reconcile) — the verb that attaches a caveat on a declared-vs-actual mismatch.
- [remember](/docs/quickstart/remember) — saving definitions, assumptions, caveats, and decisions.
- [Verified vs Asserted](/docs/concepts/verified-vs-asserted) — what each status honestly means.
- [The Context Layer](/docs/concepts/context-layer) — the mental model the trail rides on.

# AI Agent Context Guide

Your AI should not lose a confirmed project decision when one session ends. With the ClariLayer MCP installed, it can recall the context you chose to save, use it in a later task, and keep its source and applicability visible. For supported Analytics definitions, it can also surface a caveat when reconciliation found a mismatch. This guide shows the working loop in practice.

If you have not connected yet, start with the [Quickstart](/docs/getting-started) — connect Claude Code, Cursor, or Codex with a context key and add that local client's managed instructions, or add the production ClariLayer custom Connector to claude.ai over OAuth. This guide assumes your agent has general `recall_context`, `remember`, and `context_checkpoint` tools available. Analytics tools appear when their supported route is relevant.

## Start with one useful rule

If your store is empty, follow the [one-artifact step](/docs/getting-started#2-save-one-artifact-or-rule). Otherwise choose a saved rule and ask your agent a question using its name. Have the agent recall before answering. A browser preview is a scoped read; it does not establish agent use or correctness.

## The recall-first loop

The working loop is five moves:

1. **recall** relevant general context with `recall_context`; for supported Analytics or CRM work, also use `get_analysis_context` when relevant ([recall](/docs/quickstart/recall)).
2. **work** from the recalled context, preserving its source and applicability. Carry Analytics trust status into specialist results.
3. **remember** a confirmed durable change. If the result is only a suggestion, **propose** it and stop for human acceptance instead of treating it as live context ([remember](/docs/quickstart/remember)).
4. **reconcile** a compatible live definition against the supported source evidence when the work checks or changes it ([reconcile](/docs/quickstart/reconcile)).
5. **checkpoint** only a confirmed live outcome, or a genuine `no_update_required` decision, with `context_checkpoint` before reporting the task complete. Proposal-only work cannot complete this loop.

When your agent recalls before answering, it can use your selected working context instead of starting from an empty session.

For a first task, saving one rule and recalling it is enough to inspect what the agent received. Reconcile is a follow-on for supported definitions, not a prerequisite for basic reuse or Engineering context.

## Make recall the default

<details id="make-recall-the-default-details">
<summary>Installation and approval details</summary>

Recall is a tool your agent decides to call — ClariLayer exposes it, but it does not force a call. For Claude Code, Codex, or Cursor, use the [Quickstart's client selector](/docs/getting-started#2-install-the-mcp-server) to copy one managed-install prompt. The selection targets exactly one local project instruction file; it never probes your browser or filesystem to guess. The claude.ai OAuth path connects as a custom Connector and does not install a project instruction file.

Copying the prompt is not a file write. Your local agent calls `get_project_stanza`, inspects only the selected target, and asks before editing. A recognized managed range can be updated without touching surrounding content. An exact legacy stanza can be migrated once; legacy text whose sentinel remains but whose full bytes differ, malformed markers, or incompatible Cursor frontmatter returns `conflict/manual review` with no change. For Claude Code and Codex, otherwise-unrecognized existing text is preserved while the managed range appends on first install. A current block returns `already current`; an approved create or update returns `installed`; declined approval stops without claiming an installation state.

The managed block tells future sessions to recall first, write confirmed durable changes, reconcile when appropriate, and call `context_checkpoint` before completion. This remains a behavioral protocol, not a technical guarantee that every arbitrary client will comply.

</details>

## Reading what recall returns

General `recall_context` entries include the complete address needed for later retrieval:

- **summary and entry ID** — a bounded preview plus the address for the full entry.
- **source** — provenance and available capture-source metadata.
- **applicability** — whether the context is general or bounded, with project references and conditions where present.

Analytics `get_analysis_context` entries carry content previews, provenance, `asserted` or `caveat` status, and a type/name address. There is no public query-history bootstrap source or importer.

Both recall paths return bounded previews. Call `get_context_entry` with the `entry_id` returned by general recall, or with the type/name address returned by Analytics recall, when you need the complete body, CRM contract, or stored SQL.

Use status to shape the answer. An `asserted` entry has not been contradicted, but it may be unreconciled, inconclusive, or cleanly reconciled, so ground on it without presenting it as proven. A `caveat` entry has a known mismatch, so carry the caveat into the answer. The stronger `verified` status remains gated and is not part of the live public result contract — see [Verified vs Asserted](/docs/concepts/verified-vs-asserted) for why.

For general recall, `project` and `purpose` are relevance hints, never access controls or hard filters. Preserve a bounded entry's applicability even when it is recalled elsewhere. For Analytics recall, `use_case` is a precision hint rather than a silent hard filter. Scoped and unscoped entries are preferred; if the scoped set is empty or weak, a strong cross-scope match can be returned with `use_case_mismatch` and the relevant warning fields. Use `strict_use_case: true` only when cross-scope rescue would be unsafe.

<span id="remember-corrections-as-you-go" className="block h-0 scroll-mt-24" aria-hidden="true" />

## Remember confirmed changes as you go

When you confirm a durable decision — "lead the launch page with the product demo" — have your agent remember it so the next session can start from the same direction. A remembered entry is saved `asserted` with provenance `you`. Remembering stores the statement; it does not prove it correct.

Good things to remember include adopted product decisions, project constraints, preferred approaches, recurring caveats, and the precise Analytics inclusion and exclusion rules people rely on.

## Reconcile when a number looks off

The acute moment is "why don't these two numbers match?" When it happens, have your agent reconcile the relevant definition. Capability v43 has two explicit live adapters: compatible stored SQL definitions plus warehouse `actual_sample`, and HubSpot CRM contracts plus bounded, row-free `crm_evidence`. HubSpot reconciliation is generally available to authenticated organizations behind the mandatory server-side global emergency switch. This explicit adapter boundary is not a claim that every source the agent can reach is already supported.

In the personal MCP reconcile path, ClariLayer does not receive your source credentials or run SQL server-side, and it never calls HubSpot. Your agent collects the supported evidence with its own authorized connection; the separately gated team connector surface uses only explicitly configured connectors under its own controls. For HubSpot, follow the single canonical [complete capability-probed, row-free recipe](/docs/quickstart/reconcile#complete-hubspot-agent-recipe); it defines pagination, caps, completeness, unavailable observations, and exact/lower-bound count semantics. Reconcile is how an `asserted` definition earns a caveat when it has drifted from the evidence.

## Checkpoint the context decision before completion

<details id="checkpoint-the-context-decision-before-completion-details">
<summary>Completion protocol and receipt limits</summary>

After the recall and any confirmed live write/reconcile, your agent calls `context_checkpoint`. A `context_updated` declaration must reference at least one active live context entry. A proposal can be included only as supplemental evidence; proposal-only work stops for human acceptance, remains pending review, and cannot claim completion. If the task made no durable context change, the agent can declare `no_update_required` only after checking the relevant facets and deciding the context was already current or the task changed nothing durable.

If the tool returns `update_failed`, the managed instructions tell the agent to retry or report the failure instead of calling the task complete. A successful receipt persists the agent's bounded managed-protocol declaration and validates the referenced ClariLayer objects. It does not independently prove that an entry changed, external deployment happened, a Databricks validation passed, a query is correct, or saved context is semantically equivalent to another system.

</details>

## A grounded answer looks like this

An answer grounded in ClariLayer carries the definition, its provenance, and its status:

> Active Customer means an account with at least one billable subscription in the trailing 30 days, excluding internal test workspaces (saved by you). Heads up: this definition currently has a caveat — when I reconciled it last, the actual result did not match the declared shape, so confirm the window before using this for ARR-facing work.

That answer uses your saved definition, names where it came from, and is honest about its trust state. It does not pretend the raw SQL alone contains the business truth.

<span id="it-compounds" className="block h-0 scroll-mt-24" aria-hidden="true" />

## Continue across sessions

When you confirm a durable correction and ask your agent to save it, later tasks can recall that context across claude.ai, Claude Code, Cursor, and Codex. Recall reads saved context; it does not add a new rule. The Governed Context Edge adds org canon, Diff-to-team, and adjudication in a hand-run private pilot. Request access on the [For teams](/for-teams) page.

## See also

- [Quickstart](/docs/getting-started) — connect a CLI agent with a context key or production claude.ai over OAuth.
- [recall](/docs/quickstart/recall), [remember](/docs/quickstart/remember), [reconcile](/docs/quickstart/reconcile) — the verb pages.
- [The Context Layer](/docs/concepts/context-layer) — the mental model.

## SaaS Metric Definitions

### Annual Recurring Revenue
Also known as: ARR, annual recurring revenue, annualized recurring revenue, recurring revenue run rate.

Annual Recurring Revenue is the recurring subscription revenue expected from active customer commitments over a twelve-month period, after the team decides which contract states, billing events, discounts, and recurring product lines count.

Formula (ARR): sum(active recurring subscription value normalized to an annual period)
- Exclude one-time services, implementation fees, usage overages, and taxes unless a governed definition explicitly includes them.
- Normalize monthly, quarterly, and multi-year recurring commitments to an annual amount before aggregation.

Common variants:
- Booked ARR: Counts recurring contract value once an order or subscription is signed, even if billing or service start happens later.
- Live ARR: Counts only recurring value from subscriptions that are active and serviceable during the reporting period.
- Committed ARR: Counts signed recurring commitments that are not yet active separately from currently live subscriptions.

Decisions a governed definition must settle:
- Which subscription states count as active recurring revenue?
- How are discounts, credits, ramp deals, and future-dated starts normalized?
- Which product lines are recurring enough to belong in ARR?

Validation questions:
- Can the ARR total be reconciled from account-level rows back to signed commitments and active billing records?
- Do booked, live, and committed ARR views use separate labels rather than sharing one ambiguous ARR field?
- Are future-dated starts, canceled subscriptions, credits, and non-recurring fees visible in exception checks?

Drift traps:
- A CRM opportunity amount is reused as ARR after close even though the billing subscription later starts with a different net recurring value.
- Ramped contracts are annualized from the first month instead of the governed committed schedule, changing expansion and renewal views.
- One-time implementation or usage fees get bundled into recurring revenue because product and charge-type filters are not versioned.

AI-agent risk: An AI agent answering ARR questions can mix booked, live, and committed definitions if the context layer does not expose the approved state boundary, product filters, and normalization rule next to the metric.
Typical owners: Finance, Revenue Operations, Data & Analytics.
ClariLayer Drift Risk: high.

### Monthly Recurring Revenue
Also known as: MRR, monthly recurring revenue, monthly subscription run rate, recurring monthly revenue.

Monthly Recurring Revenue is the recurring subscription revenue expected for a normalized month from active customer commitments, after the team decides how to handle billing cadence, usage, discounts, credits, pauses, and partial-month activity.

Formula (MRR): sum(active recurring subscription value normalized to one month)
- Normalize annual, quarterly, and monthly recurring commitments to a monthly amount before aggregation.
- Keep MRR separate from cash collected, invoices issued, and recognized revenue unless a governed variant says otherwise.

Common variants:
- Ending MRR: Measures recurring monthly value at the end of a reporting period.
- Average MRR: Averages recurring monthly value across the period rather than taking one point-in-time snapshot.
- Net New MRR: Tracks the period change from new, expansion, contraction, and churn movements.

Decisions a governed definition must settle:
- Is the metric a point-in-time ending value, an average value, or a movement measure?
- How are pauses, credits, discounts, and partial-month subscriptions represented?
- Does usage-based recurring revenue belong in core MRR or a separate governed variant?

Validation questions:
- Can ending MRR reconcile to the active subscription ledger for the same close date?
- Do new, expansion, contraction, and churn movements add back to the total period change?
- Are credits, pauses, and partial-month records classified consistently instead of being dropped silently?

Drift traps:
- Invoice totals are treated as MRR, creating swings from annual prepayments, credits, and tax lines.
- A daily snapshot and a month-end snapshot share the same MRR label, so trend charts do not reconcile.
- Paused accounts remain active in CRM while billing records show no collectible recurring value.

AI-agent risk: An AI agent can confuse MRR with invoiced revenue or ARR divided by twelve unless the context layer supplies the approved monthly normalization and movement model.
Typical owners: Finance, Revenue Operations, Data & Analytics.
ClariLayer Drift Risk: high.

### Net Revenue Retention
Also known as: NRR, net revenue retention, net dollar retention, NDR, net retention.

Net Revenue Retention measures how much recurring revenue a starting cohort keeps after expansion, contraction, and churn over a defined period, before adding revenue from new customers outside that starting cohort.

Formula (NRR): (starting cohort recurring revenue + expansion - contraction - churn) / starting cohort recurring revenue
- Use the same cohort, currency, product filter, and recurring revenue basis for the numerator and denominator.
- Exclude new-customer recurring revenue that was not present in the starting cohort.

Common variants:
- Account-cohort NRR: Builds the cohort from accounts active at the start of the period and follows those accounts through expansion, contraction, and churn.
- Subscription-cohort NRR: Builds the cohort from subscriptions active at the start of the period and follows subscription-level changes.
- Logo-excluded NRR: Keeps reactivated or acquired logos out of the cohort unless they existed at the start of the period.

Decisions a governed definition must settle:
- What creates the starting cohort: accounts, subscriptions, products, or contracts?
- How are reactivations, account merges, acquisitions, and product migrations treated?
- Which recurring revenue basis powers NRR: ARR, MRR, booked value, or live value?

Validation questions:
- Can each NRR movement be traced back to a starting-cohort account or subscription?
- Do expansion, contraction, and churn movements reconcile to the same recurring revenue basis?
- Are reactivations, account merges, product migrations, and acquired accounts classified before the ratio is calculated?

Drift traps:
- New customers are accidentally included in the numerator because the ending-period query does not restrict to the starting cohort.
- Expansion uses booked ARR while contraction and churn use live MRR, producing a ratio that mixes definitions.
- Account hierarchy changes make a retained parent account look like churn at a child account level.

AI-agent risk: An AI agent summarizing retention can produce a confident but wrong answer if it cannot see the cohort grain, revenue basis, and movement classification that created the NRR figure.
Typical owners: Finance, Customer Success, Revenue Operations, Data & Analytics.
ClariLayer Drift Risk: high.

### Churn
Also known as: customer churn, logo churn, revenue churn, gross churn, gross revenue churn.

Churn measures the loss of customers, subscriptions, or recurring revenue from a defined starting population over a defined period, with the exact answer depending on whether the governed variant is logo churn, revenue churn, or another approved loss view.

Formula (Churn): lost logos or lost recurring revenue from the starting population / starting population
- Logo churn and revenue churn answer different questions and should keep separate labels.
- State whether downgrades, pauses, non-payment, reactivations, and product migrations count as churn, contraction, or neither.

Common variants:
- Logo Churn: Counts customers from the starting population that are no longer active by the end of the period.
- Gross Revenue Churn: Counts recurring revenue lost from churn and contraction before expansion offsets.
- Net Revenue Churn: Offsets lost recurring revenue with expansion or recovery inside the same governed population.

Decisions a governed definition must settle:
- Is the governed metric counting logos, subscriptions, seats, or recurring revenue?
- When does churn occur: cancellation request, contract end, service stop, billing stop, or data inactivity?
- How are pauses, downgrades, reactivations, non-payment, and product migrations classified?

Validation questions:
- Can each churned logo or revenue amount be tied back to a member of the starting population?
- Do cancellation, billing, and customer-success states agree on the churn date or expose a governed precedence rule?
- Are downgrades, pauses, non-payment, and reactivations reported as explicit exceptions instead of being hidden in churn?

Drift traps:
- A customer marked canceled in CRM still has an active billing subscription, so logo churn and revenue churn diverge without explanation.
- Downgrades are counted as full churn in one dashboard and contraction in another because the movement taxonomy is not governed.
- Reactivated accounts are removed from churn retroactively, changing historical retention without a visible version change.

AI-agent risk: An AI agent can answer churn questions with the wrong grain if it does not know whether the user needs logo churn, revenue churn, contraction, or a retention-cohort movement view.
Typical owners: Customer Success, Finance, Revenue Operations, Data & Analytics.
ClariLayer Drift Risk: high.

### Pipeline Coverage
Also known as: sales pipeline coverage, pipeline coverage ratio, quota coverage, target coverage.

Pipeline Coverage compares qualified open pipeline to a bookings, revenue, or quota target for a defined future period, after the team decides which opportunities, stages, probabilities, forecast categories, and close dates are eligible.

Formula (Pipeline Coverage): eligible open pipeline for the target period / target bookings, revenue, or quota for the same period
- State whether pipeline is unweighted, probability-weighted, commit-only, or limited to specific forecast categories.
- Use the same territory, segment, currency, and close-period boundary for pipeline and target.

Common variants:
- Unweighted Pipeline Coverage: Uses the full amount of eligible open opportunities without multiplying by probability.
- Weighted Pipeline Coverage: Weights opportunity amount by probability, stage, or forecast category before comparing to target.
- Commit Pipeline Coverage: Limits coverage to opportunities in commit or similarly strict forecast categories.

Decisions a governed definition must settle:
- Which opportunity stages, forecast categories, and close dates count as eligible pipeline?
- Is opportunity value unweighted, probability-weighted, stage-weighted, or commit-only?
- What target is the denominator: bookings, ARR, revenue, quota, or another sales goal?

Validation questions:
- Can every opportunity in coverage be explained by stage, forecast category, owner, amount, currency, and close-period eligibility?
- Does the denominator come from the same segment, territory, currency, and period as the open-pipeline numerator?
- Are stale opportunities, pushed close dates, duplicate opportunities, and renewal or expansion deals classified consistently?

Drift traps:
- The numerator uses all open opportunity amount while the denominator is new ARR quota, mixing renewals, expansion, services, and new business.
- Close dates are pushed into the target quarter without stage-quality checks, making coverage look healthier than sales execution supports.
- One dashboard uses unweighted pipeline while another uses probability-weighted pipeline under the same coverage label.

AI-agent risk: An AI agent can recommend sales action from a misleading coverage number if it cannot see the eligible stage boundary, target denominator, weighting rule, and stale-pipeline policy.
Typical owners: Sales, Revenue Operations, Finance, Data & Analytics.
ClariLayer Drift Risk: high.

### Gross Revenue Retention
Also known as: GRR, gross revenue retention, gross dollar retention, GDR, gross retention.

Gross Revenue Retention measures how much recurring revenue a starting customer cohort keeps after churn and contraction, before any expansion offsets are added back into the result.

Formula (GRR): (starting cohort recurring revenue - contraction - churn) / starting cohort recurring revenue
- Use one recurring revenue basis for starting revenue, contraction, and churn.
- Exclude expansion from the numerator so the metric shows downside retention pressure.

Common variants:
- Account-cohort GRR: Follows accounts active at the start of the period and measures retained recurring revenue after losses.
- Subscription-cohort GRR: Follows subscriptions active at the start of the period instead of rolling movement to the account level.
- Product-filtered GRR: Limits the starting cohort and loss movements to approved recurring products or packages.

Decisions a governed definition must settle:
- Which starting cohort grain and recurring revenue basis define GRR?
- Which movements count as contraction versus full churn?
- How are reactivations, account merges, and partial-period losses handled?

Validation questions:
- Can every contraction and churn amount be traced to a starting-cohort customer or subscription?
- Does GRR exclude expansion even when the same account expands in the measurement period?
- Are downgrades, product migrations, and reactivations classified before the ratio is calculated?

Drift traps:
- Expansion is netted into the numerator, causing GRR to behave like NRR under a different label.
- Contraction uses subscription events while churn uses CRM account status, creating movement totals that do not reconcile.
- Product migrations are recorded as contraction in one system and retained revenue in another without a governed bridge.

AI-agent risk: An AI agent can misread GRR as net retention if the context layer does not expose that expansion is excluded and the loss movements come only from the starting cohort.
Typical owners: Finance, Customer Success, Revenue Operations.
ClariLayer Drift Risk: high.

### Expansion MRR
Also known as: expansion MRR, expansion monthly recurring revenue, upsell MRR, upgrade MRR, cross-sell MRR.

Expansion MRR measures recurring monthly revenue added from existing customers through upgrades, seat growth, package changes, or cross-sell activity during a defined period.

Formula (Expansion MRR): sum(positive recurring monthly revenue movements from existing customers in the period)
- Classify expansion from the same movement spine used for MRR, NRR, and retention reporting.
- Exclude new-customer MRR unless the governed definition explicitly treats reactivation or acquisition as expansion.

Common variants:
- Upgrade Expansion MRR: Counts monthly recurring revenue added when an existing customer moves to a higher package or plan.
- Seat Expansion MRR: Counts monthly recurring revenue added from additional seats, users, or capacity on an existing subscription.
- Cross-sell Expansion MRR: Counts monthly recurring revenue added from new recurring products sold to existing customers.

Decisions a governed definition must settle:
- What qualifies a customer as existing for expansion purposes?
- Which movement events distinguish expansion from correction, migration, or new business?
- How are mid-period upgrades, ramp schedules, and currency changes normalized?

Validation questions:
- Do expansion movements reconcile to the net change in MRR for existing customers?
- Are upgrades, seat growth, cross-sell, migrations, and billing corrections classified as separate movement types?
- Can each expansion amount be tied to an account, subscription, product, effective date, and prior monthly value?

Drift traps:
- Reactivated customers are counted as expansion even though they were outside the retained cohort at period start.
- Package migrations create both contraction and expansion movements that are not netted or labeled consistently.
- Sales opportunity amount is used as expansion MRR before billing activation confirms the recurring monthly value.

AI-agent risk: An AI agent can overstate account growth if expansion MRR is not tied to the approved existing-customer boundary, movement taxonomy, and monthly normalization rule.
Typical owners: Revenue Operations, Finance, Sales, Data & Analytics.
ClariLayer Drift Risk: high.

---
[Truncated: llms-full.txt reached its size budget. See https://clarilayer.com/llms.txt for the link index and https://clarilayer.com/docs for the full documentation.]