Guides

AI Agent Context Guide

Use ClariLayer's recall-first loop, explicit replace semantics, warehouse or HubSpot reconcile adapters, and completion checkpoint receipt.

Your AI coding agent should not guess which table, join, or definition is right. With the ClariLayer MCP installed, it does not have to: it can recall the context you have saved, ground its answer in it, and surface a caveat when a definition has a known mismatch. This guide shows the working loop in practice.

If you have not connected yet, start with the Quickstart — 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 already has the four headline, everyday ClariLayer verbs and the context_checkpoint completion tool available.

The recall-first loop

The working loop is five moves:

recall the relevant context before answering (get_analysis_context).
work from the recalled definitions, carrying their status into the result.
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).
reconcile a compatible live definition against the supported source evidence when the work checks or changes it (reconcile).
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.

The first move is the one that changes everything. An agent that recalls before answering stops re-deriving your data model from scratch every session.

Make recall the default

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 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.

Reading what recall returns

Each recalled entry comes back with three things your agent should use:

content — the definition, schema note, saved query, or note.
provenance — where it came from (you, sql_import, dbt, agent, dictionary, semantic_model, or the accepted legacy value query_history), so the agent can tell a hand-saved fact from an imported or agent-normalized one. There is no public query-history bootstrap source or importer.
status — asserted or caveat.

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 for why.

When recall is scoped with use_case, treat that value as 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.

Remember corrections as you go

When you correct your agent — "no, revenue has to subtract refunds" — have it remember that, so the next session starts from the corrected understanding. A remembered entry is saved asserted with provenance you. Remembering is capture, not verification: it stores the claim, it does not check it. That is fine; the point is that your institutional memory stops evaporating at the end of each chat.

Good things to remember: the real join paths, the columns that are in cents, the tables that hold refunds or test data, and the precise inclusion and exclusion rules for the metrics people argue about.

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; 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

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.

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.

It compounds

Every recall, remember, reconcile, and checkpoint adds to a store and audit trail that are yours. Your agent grounds on more of your context each week, and that context travels across claude.ai, Claude Code, Cursor, and Codex. And that team layer exists today: the Governed Context Edge — org canon, Diff-to-team, adjudication — is in a hand-run private pilot. Request access on the For teams page.